datetime2 component migration

To prepare for the Popover changes coming in Blueprint v5.0, we're providing "v2" variants of @blueprintjs/datetime and @blueprintjs/timezone components which use Popover2 instead of Popover. Migrate to these now in order to ensure a smooth migration path.

These components are available in the new @blueprintjs/datetime2 package:

DateInput2

Replacement for DateInput, with notable changes:

• Component uses Popover2 instead of Popover, so there are some DOM changes and the type of popoverProps has changed to Popover2Props. See Popover2 migration for more info.
• The controlled value and uncontrolled defaultValue API have changed to use an ISO string instead of a JS Date value. ISO strings are also returned in the onChange callback. This allows the component to be more explicit about timezones.
• Component optionally embeds a TimezoneSelect inside the input, which allows the user to change the timezone of the selected datetime. This can be enabled with the new prop showTimezoneSelect={true}.
• Key event handlers have been updated to use non-deprecated KeyboardEvent APIs. This may affect testing code which relies on setting event.which key codes to simulate keyboard behavior. Tests should be updated to use the event.key property instead.

API changes

Before:

const [date, setDate] = React.useState(new Date());

return (
  <DateInput value={date} onChange={setDate} />
);

After:

const [date, setDate] = React.useState(new Date().toISOString());
// alternatively, you can specify the string explicitly, like "2022-07-14T15:01:08.859Z" or "2022-07-14T11:01:08.859-4:00"

return (
  <DateInput value={date} onChange={setDate} />
);

Rendered DOM changes

- <span class="bp4-popover-wrapper">
-   <span aria-haspopup="true" class="bp4-popover-target">
-     <div class="bp4-input-group">
-       <input type="text" autocomplete="off" placeholder="JS Date" class="bp4-input" value="7/14/2022">
-     </div>
-   </span>
- </span>
+ <span aria-haspopup="true" class="bp4-date-input bp4-popover2-target">
+   <div class="bp4-input-group">
+     <input type="text" autocomplete="off" placeholder="MM/dd/yyyy" class="bp4-input" value="07/14/2022">
+     <!-- optional timezone select here -->
+   </div>
+ </span>

TimezoneSelect

Replacement for TimezonePicker, with notable changes:

• Component name has changed to better match semantic naming patterns of other Blueprint components:
  • It is a specialized select component, not a picker component.
  • Note that we use the term "picker" to refer to DatePicker / DateRangePicker, which do not rely on popovers.
• New name means that class names have changed:
  • .bp4-timezone-picker → .bp4-timezone-select
  • .bp4-timezone-picker-popover → .bp4-timezone-select-popover
  • ℹ️ remember to always use the $bp-ns variable in Sass and the Classes constants in TS/JS when referencing Blueprint class names
• Component uses Select2 instead of Select, so there are some DOM changes — see Select2 migration for more info.
• New prop fill matches behavior of <Select fill>.
• The type of popoverProps has changed to Popover2Props, which means a few properties have changed. See Popover2 migration for more info.
  • popover positioning may be specified with "placement" or "position"
  • boundary has been replaced with rootBoundary, which better matches popper.js' definition of what a "boundary" is
  • modifiers type has changed
  • targetClassName and targetTagName properties have been removed

Rendered DOM changes

- <span class="bp4-popover-wrapper bp4-timezone-picker">
-   <span aria-haspopup="true" class="bp4-popover-target">
-     <div class="">
-       <button type="button" class="bp4-button">
-         ...
-       </button>
-     </div>
-   </span>
- </span>
+ <div
+   aria-controls="listbox-1"
+   aria-expanded="false"
+   aria-haspopup="listbox"
+   class="bp4-timezone-select bp4-popover2-target"
+   role="combobox"
+ >
+   <button type="button" class="bp4-button">
+     ...
+   </button>
+ </div>