Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(core): add DateTimeInput timeOptionInterval for a preset-time dropdown (#4837)

AK8a9c0402e824
diff --git a/.changeset/datetimeinput-time-option-dropdown.md b/.changeset/datetimeinput-time-option-dropdown.md
new file mode 100644
index 0000000000..b4f078c7bd
--- /dev/null
+++ b/.changeset/datetimeinput-time-option-dropdown.md
@@ -0,0 +1,9 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] DateTimeInput: new `timeOptionInterval` prop adds a dropdown of preset times to the time field, at a cadence of `5 | 10 | 15 | 30 | 60` minutes (`60` gives the 12 AM - 11 PM list). The field becomes an APG combobox over a `listbox`: click or Alt+ArrowDown opens it, ArrowUp/ArrowDown move the active option, Enter picks, Escape closes, and typing moves the highlight to the closest option without filtering the list. `min`/`max` trim the options on the boundary date. Style the popup through the `date-time-input-time-listbox` and `date-time-input-time-option` theme targets.
+
+Opt-in and additive: with `timeOptionInterval` omitted the time field keeps exactly its current behavior and gains no combobox semantics, so existing `getByRole('combobox')` queries still resolve to the date input. With the list closed the arrow keys keep stepping by `timeIncrement`.
+
+@AKnassa
diff --git a/apps/storybook/stories/DateTimeInput.stories.tsx b/apps/storybook/stories/DateTimeInput.stories.tsx
index 291d743afc..ec597cf253 100644
--- a/apps/storybook/stories/DateTimeInput.stories.tsx
+++ b/apps/storybook/stories/DateTimeInput.stories.tsx
@@ -186,6 +186,50 @@ export const WithTimeIncrement: Story = {
},
};
+/**
+ * `timeOptionInterval` turns the time field into a combobox over a list of
+ * preset times at that cadence. Click the time field or press Alt+ArrowDown to
+ * open it; ArrowUp/ArrowDown move through the list, Enter picks, Escape closes.
+ *
+ * The list is a shortcut, not a restriction — a time between two options can
+ * still be typed, and with the list closed the arrow keys keep stepping by
+ * `timeIncrement` exactly as they do without this prop.
+ */
+export const WithTimeOptions: Story = {
+ render: args => {
+ const [value, setValue] = useState<ISODateTimeString | undefined>(
+ '2026-03-15T09:00' as ISODateTimeString,
+ );
+ return <DateTimeInput {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Meeting time',
+ timeOptionInterval: 30,
+ description: 'Pick from half-hour slots, or type any time',
+ },
+};
+
+/**
+ * An hourly list — the 12 AM to 11 PM shape most scheduling flows want.
+ * `min` and `max` trim the list on the boundary date, so only bookable hours
+ * are offered.
+ */
+export const WithHourlyTimeOptions: Story = {
+ render: args => {
+ const [value, setValue] = useState<ISODateTimeString | undefined>(
+ '2026-03-15T13:00' as ISODateTimeString,
+ );
+ return <DateTimeInput {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Office hours',
+ timeOptionInterval: 60,
+ min: '2026-03-15T09:00' as ISODateTimeString,
+ max: '2026-03-15T17:00' as ISODateTimeString,
+ description: 'Hourly slots, trimmed to 9 AM - 5 PM',
+ },
+};
+
export const Optional: Story = {
render: args => {
const [value, setValue] = useState<ISODateTimeString | undefined>(
diff --git a/packages/core/locales/en.json b/packages/core/locales/en.json
index e0c8bb5f47..503a3e0120 100644
--- a/packages/core/locales/en.json
+++ b/packages/core/locales/en.json
@@ -751,6 +751,10 @@
"defaultMessage": "{label} time",
"description": "Screen-reader-only accessible name for the time-of-day slot in a DateTimeInput. Example: `Start date time`; reorder freely (e.g. \"time of {label}\")."
},
+ "@astryx.dateTimeInput.timeOptionsLabel": {
+ "defaultMessage": "{label} options",
+ "description": "Screen-reader-only accessible name for the list of preset times that drops down from a DateTimeInput's time slot. `{label}` is the accessible name of the time field itself, already ending in the word for time — example: `Meeting time options`. Plural: the list holds every selectable time."
+ },
"@astryx.dateRangeInput.placeholder": {
"defaultMessage": "Select date range",
"description": "Grey placeholder inside an empty DateRangeInput field. Represents picking a start–end date pair. Imperative verb."
diff --git a/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs b/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs
index ca14148de2..250a232976 100644
--- a/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs
+++ b/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs
@@ -123,6 +123,12 @@ export const docs = {
'Minutes to add or subtract when using arrow keys in the time input.',
default: '1',
},
+ {
+ name: 'timeOptionInterval',
+ type: '5 | 10 | 15 | 30 | 60',
+ description:
+ 'Minute cadence for a dropdown of preset times on the time portion. Set it to turn the time field into a combobox listing every valid time at that cadence (60 gives a 12 AM to 11 PM list). Omitted, the time field stays a plain text input and gains no combobox semantics. Typed entry keeps working either way, so a time between two options is still reachable. Independent of timeIncrement, which governs arrow-key stepping.',
+ },
{
name: 'hasClear',
type: 'boolean',
@@ -206,6 +212,8 @@ export const docs = {
},
{className: 'astryx-date-time-input-toggle-icon', states: ['state']},
{className: 'astryx-date-time-input-clock-icon'},
+ {className: 'astryx-date-time-input-time-listbox'},
+ {className: 'astryx-date-time-input-time-option'},
],
},
usage: {
@@ -283,6 +291,12 @@ export const docs = {
description:
'A text input for entering the time, displayed beside the date input.',
},
+ {
+ name: 'Time options popover',
+ required: false,
+ description:
+ 'A list of preset times at the timeOptionInterval cadence, shown when that prop is set and the time input is clicked or opened with Alt+ArrowDown.',
+ },
{
name: 'Clear button',
required: false,
@@ -512,6 +526,8 @@ export const docsZh = {
},
{className: 'astryx-date-time-input-toggle-icon', states: ['state']},
{className: 'astryx-date-time-input-clock-icon'},
+ {className: 'astryx-date-time-input-time-listbox'},
+ {className: 'astryx-date-time-input-time-option'},
],
},
};
@@ -585,6 +601,8 @@ export const docsDense = {
hasSeconds: 'include seconds in time portion',
hourFormat: "display format. '12h' shows AM/PM; '24h' uses 24-hour",
timeIncrement: 'minutes to add/subtract on arrow keys in time input',
+ timeOptionInterval:
+ 'minute cadence for a preset-time dropdown on the time input; omitted = plain text input, no combobox. typed entry still works',
hasClear: 'Shows clear button when datetime is set',
placeholder: 'date-portion placeholder when empty',
timePlaceholder: 'time-portion placeholder when empty',
diff --git a/packages/core/src/DateTimeInput/DateTimeInput.test.tsx b/packages/core/src/DateTimeInput/DateTimeInput.test.tsx
index 1af565f1a7..3357d8bafd 100644
--- a/packages/core/src/DateTimeInput/DateTimeInput.test.tsx
+++ b/packages/core/src/DateTimeInput/DateTimeInput.test.tsx
@@ -942,6 +942,1094 @@ describe('DateTimeInput', () => {
});
});
+ // ===========================================================================
+ // Time-option dropdown (#2727)
+ // ===========================================================================
+
+ describe('timeOptionInterval', () => {
+ // The dropdown renders through the same popover as the calendar, so its
+ // content lands in the top layer: jsdom keeps the nodes in the DOM but
+ // role queries skip them. Read the options off the container directly,
+ // exactly as the weekStartsOn tests read columnheaders.
+ const optionsIn = (container: HTMLElement): HTMLElement[] =>
+ Array.from(container.querySelectorAll('[role="option"]'));
+
+ const labelsIn = (container: HTMLElement): (string | null)[] =>
+ optionsIn(container).map(o => o.textContent);
+
+ // ---- opt-in gate --------------------------------------------------------
+
+ it('adds no listbox and no second combobox without timeOptionInterval', () => {
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:30' as ISODateTimeString}
+ onChange={() => {}}
+ />,
+ );
+
+ // The date input stays the only combobox on the field. 30+ existing
+ // assertions use the singular getByRole('combobox'); a second one would
+ // break every one of them, and every downstream consumer's too.
+ expect(screen.getAllByRole('combobox')).toHaveLength(1);
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ expect(timeInput).not.toHaveAttribute('role', 'combobox');
+ fireEvent.click(timeInput);
+ expect(optionsIn(container)).toHaveLength(0);
+ });
+
+ // ---- option generation --------------------------------------------------
+
+ it('renders one option per interval step across the day', () => {
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:30' as ISODateTimeString}
+ timeOptionInterval={30}
+ onChange={() => {}}
+ />,
+ );
+
+ fireEvent.click(screen.getByLabelText('Meeting time'));
+ // A full day at 30-minute cadence.
+ expect(optionsIn(container)).toHaveLength(48);
+ });
+
+ it('renders 24 options at an hourly interval', () => {
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:30' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />,
+ );
+
+ fireEvent.click(screen.getByLabelText('Meeting time'));
+ const labels = labelsIn(container);
+ expect(labels).toHaveLength(24);
+ // The 12 AM - 11 PM list the issue asks for.
+ expect(labels[0]).toBe('12:00 AM');
+ expect(labels[23]).toBe('11:00 PM');
+ });
+
+ it('labels options in 24-hour format when hourFormat is 24h', () => {
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:30' as ISODateTimeString}
+ timeOptionInterval={60}
+ hourFormat="24h"
+ onChange={() => {}}
+ />,
+ );
+
+ fireEvent.click(screen.getByLabelText('Meeting time'));
+ const labels = labelsIn(container);
+ expect(labels[0]).toBe('00:00');
+ expect(labels[13]).toBe('13:00');
+ });
+
+ it('includes seconds in option labels when hasSeconds is set', () => {
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:30:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ hasSeconds
+ onChange={() => {}}
+ />,
+ );
+
+ fireEvent.click(screen.getByLabelText('Meeting time'));
+ expect(labelsIn(container)[0]).toBe('12:00:00 AM');
+ });
+
+ // ---- committing ---------------------------------------------------------
+
+ it('commits the clicked option and keeps the selected date', () => {
+ const onChange = vi.fn();
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:30' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={onChange}
+ />,
+ );
+
+ fireEvent.click(screen.getByLabelText('Meeting time'));
+ // 09:00 is the tenth hourly option.
+ fireEvent.click(optionsIn(container)[9]);
+
+ expect(onChange).toHaveBeenCalledTimes(1);
+ expect(onChange.mock.calls[0][0]).toBe('2026-03-15T09:00');
+ });
+
+ it('marks the committed option as selected, not merely highlighted', () => {
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />,
+ );
+
+ fireEvent.click(screen.getByLabelText('Meeting time'));
+ const selected = optionsIn(container).filter(
+ o => o.getAttribute('aria-selected') === 'true',
+ );
+ expect(selected).toHaveLength(1);
+ expect(selected[0].textContent).toBe('2:00 PM');
+ });
+
+ // ---- keyboard: the arrow-key collision ----------------------------------
+
+ it('keeps ArrowUp stepping by timeIncrement while the list is closed', () => {
+ const onChange = vi.fn();
+ render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:30' as ISODateTimeString}
+ timeIncrement={15}
+ timeOptionInterval={30}
+ onChange={onChange}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ // Closed list: arrows still step the value, as they always have.
+ fireEvent.keyDown(timeInput, {key: 'ArrowUp'});
+
+ expect(onChange).toHaveBeenCalledTimes(1);
+ expect(onChange.mock.calls[0][0]).toContain('14:45');
+ expect(timeInput).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('opens the list on Alt+ArrowDown without changing the value', () => {
+ const onChange = vi.fn();
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:30' as ISODateTimeString}
+ timeOptionInterval={30}
+ onChange={onChange}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown', altKey: true});
+
+ expect(timeInput).toHaveAttribute('aria-expanded', 'true');
+ expect(onChange).not.toHaveBeenCalled();
+ expect(optionsIn(container)).toHaveLength(48);
+ });
+
+ it('moves the active option with ArrowDown while open, without committing', () => {
+ const onChange = vi.fn();
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={onChange}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown', altKey: true});
+ // Opening starts the highlight on the committed value (14:00).
+ expect(timeInput).toHaveAttribute(
+ 'aria-activedescendant',
+ optionsIn(container)[14].id,
+ );
+
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown'});
+ expect(timeInput).toHaveAttribute(
+ 'aria-activedescendant',
+ optionsIn(container)[15].id,
+ );
+ // Navigating is not selecting.
+ expect(onChange).not.toHaveBeenCalled();
+ });
+
+ it('commits the active option on Enter and closes the list', () => {
+ const onChange = vi.fn();
+ render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={onChange}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown', altKey: true});
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown'});
+ fireEvent.keyDown(timeInput, {key: 'Enter'});
+
+ expect(onChange).toHaveBeenCalledTimes(1);
+ expect(onChange.mock.calls[0][0]).toBe('2026-03-15T15:00');
+ expect(timeInput).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('jumps to the first and last option with Home and End', () => {
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown', altKey: true});
+
+ fireEvent.keyDown(timeInput, {key: 'Home'});
+ expect(timeInput).toHaveAttribute(
+ 'aria-activedescendant',
+ optionsIn(container)[0].id,
+ );
+
+ fireEvent.keyDown(timeInput, {key: 'End'});
+ expect(timeInput).toHaveAttribute(
+ 'aria-activedescendant',
+ optionsIn(container)[23].id,
+ );
+ });
+
+ it('closes on Escape without committing', () => {
+ const onChange = vi.fn();
+ render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={onChange}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown', altKey: true});
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown'});
+ fireEvent.keyDown(timeInput, {key: 'Escape'});
+
+ expect(timeInput).toHaveAttribute('aria-expanded', 'false');
+ expect(onChange).not.toHaveBeenCalled();
+ });
+
+ // ---- typed entry keeps working -----------------------------------------
+
+ it('moves the highlight to the closest option as the user types, without dropping options', () => {
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.click(timeInput);
+ fireEvent.change(timeInput, {target: {value: '9:00 PM'}});
+
+ // Free-form entry is the contract here: the list narrows nothing, it
+ // follows the typed value so Enter still lands on something sensible.
+ expect(optionsIn(container)).toHaveLength(24);
+ expect(timeInput).toHaveAttribute(
+ 'aria-activedescendant',
+ optionsIn(container)[21].id,
+ );
+ });
+
+ // ---- constraints --------------------------------------------------------
+
+ it('drops options outside min/max on the boundary date', () => {
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ min={'2026-03-15T09:00' as ISODateTimeString}
+ max={'2026-03-15T17:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />,
+ );
+
+ fireEvent.click(screen.getByLabelText('Meeting time'));
+ const labels = labelsIn(container);
+ // 09:00 through 17:00 inclusive.
+ expect(labels).toHaveLength(9);
+ expect(labels[0]).toBe('9:00 AM');
+ expect(labels[8]).toBe('5:00 PM');
+ });
+
+ it('offers the whole day when the selected date is inside the min/max range', () => {
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-16T14:00' as ISODateTimeString}
+ min={'2026-03-15T09:00' as ISODateTimeString}
+ max={'2026-03-17T17:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />,
+ );
+
+ fireEvent.click(screen.getByLabelText('Meeting time'));
+ // The time bound only bites on the boundary date itself.
+ expect(optionsIn(container)).toHaveLength(24);
+ });
+
+ // ---- a11y wiring + disabled --------------------------------------------
+
+ it('wires the time input as a combobox onto the listbox', () => {
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ expect(timeInput).toHaveAttribute('role', 'combobox');
+ expect(timeInput).toHaveAttribute('aria-expanded', 'false');
+ expect(timeInput).toHaveAttribute('aria-autocomplete', 'list');
+
+ fireEvent.click(timeInput);
+ const listbox = container.querySelector('[role="listbox"]');
+ expect(listbox).not.toBeNull();
+ expect(timeInput).toHaveAttribute('aria-controls', listbox?.id);
+ // Named, so the list is not an anonymous group to a screen reader.
+ expect(listbox).toHaveAttribute('aria-label');
+ });
+
+ it('does not open the list when disabled', () => {
+ render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ isDisabled
+ onChange={() => {}}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.click(timeInput);
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown', altKey: true});
+
+ // The layer mounts its content whether or not it is open — visibility is
+ // the popover attribute's job, which jsdom does not apply. So assert the
+ // open state itself, not the presence of option nodes.
+ expect(timeInput).toHaveAttribute('aria-expanded', 'false');
+ expect(timeInput).not.toHaveAttribute('aria-controls');
+ });
+
+ it('does not open the list for a focusable-disabled field', () => {
+ // With disabledMessage the input drops the native `disabled` attribute so
+ // the reason stays discoverable, which means clicks and keys really do
+ // reach it. This is the case the guards have to catch — a natively
+ // disabled input never delivers the events in the first place.
+ render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ isDisabled
+ disabledMessage="Pick a project first"
+ onChange={() => {}}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ expect(timeInput).not.toBeDisabled();
+
+ fireEvent.click(timeInput);
+ expect(timeInput).toHaveAttribute('aria-expanded', 'false');
+
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown', altKey: true});
+ expect(timeInput).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ // -- edge cases ----------------------------------------------------------
+
+ it('does not fire a change when the already-selected option is clicked', () => {
+ // The marker compares a seconds-normalised time while the commit path
+ // compared the raw one, so with a stray-seconds value the option that
+ // renders as selected still emitted a change when clicked.
+ const onChange = vi.fn();
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={onChange}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.click(timeInput);
+ const selected = optionsIn(container).find(
+ o => o.getAttribute('aria-selected') === 'true',
+ );
+ expect(selected).toBeDefined();
+
+ fireEvent.click(selected as HTMLElement);
+
+ expect(onChange).not.toHaveBeenCalled();
+ expect(timeInput).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('does not open an empty list when min/max leave no valid option', () => {
+ // A window narrower than the cadence survives no option at all. Opening
+ // then shows a blank popover with nothing to pick.
+ render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T09:15' as ISODateTimeString}
+ min={'2026-03-15T09:10' as ISODateTimeString}
+ max={'2026-03-15T09:20' as ISODateTimeString}
+ timeOptionInterval={30}
+ onChange={() => {}}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.click(timeInput);
+ expect(timeInput).toHaveAttribute('aria-expanded', 'false');
+
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown', altKey: true});
+ expect(timeInput).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('commits the active option on Enter once the user arrows away from what they typed', () => {
+ // Typed text beats the highlight only while the highlight is still the
+ // one typing derived. After an arrow key the highlight is the user's own
+ // choice, and Enter must honour what the field says is active.
+ const onChange = vi.fn();
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T09:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={onChange}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.click(timeInput);
+ fireEvent.change(timeInput, {target: {value: '9:15 AM'}});
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown'});
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown'});
+
+ expect(timeInput).toHaveAttribute(
+ 'aria-activedescendant',
+ optionsIn(container)[11].id,
+ );
+
+ fireEvent.keyDown(timeInput, {key: 'Enter'});
+ expect(onChange.mock.calls[onChange.mock.calls.length - 1][0]).toBe(
+ '2026-03-15T11:00',
+ );
+ });
+
+ it('closes a list that empties underneath it', () => {
+ // The open-time guard cannot help here: the window narrows after the
+ // list is already up. Left open, the keyboard switch is gated off and
+ // the arrows fall back to stepping a value the user cannot see.
+ const onChange = vi.fn();
+ const {container, rerender} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-16T14:00' as ISODateTimeString}
+ min={'2026-03-15T09:10' as ISODateTimeString}
+ max={'2026-03-15T09:20' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={onChange}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.click(timeInput);
+ expect(timeInput).toHaveAttribute('aria-expanded', 'true');
+
+ rerender(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T09:15' as ISODateTimeString}
+ min={'2026-03-15T09:10' as ISODateTimeString}
+ max={'2026-03-15T09:20' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={onChange}
+ />,
+ );
+
+ expect(optionsIn(container)).toHaveLength(0);
+ expect(timeInput).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('closes the list when focus leaves the field entirely', () => {
+ // Light dismiss covers outside clicks and Escape, never a programmatic
+ // focus move. Without this the listbox is orphaned in the top layer.
+ render(
+ <>
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />
+ <button type="button">after</button>
+ </>,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown', altKey: true});
+ expect(timeInput).toHaveAttribute('aria-expanded', 'true');
+
+ fireEvent.blur(timeInput, {relatedTarget: getButton('after')});
+ expect(timeInput).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('closes an open list when the field goes busy', () => {
+ const {rerender} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T09:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.click(timeInput);
+ expect(timeInput).toHaveAttribute('aria-expanded', 'true');
+
+ rerender(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T09:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ isLoading
+ onChange={() => {}}
+ />,
+ );
+
+ // An open dropdown over a control that no longer takes input.
+ expect(timeInput).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('scales option padding with the field size', () => {
+ const small = render(
+ <DateTimeInput
+ label="Small"
+ value={'2026-03-15T09:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ size="sm"
+ onChange={() => {}}
+ />,
+ );
+ fireEvent.click(screen.getByLabelText('Small time'));
+ const smallClass = optionsIn(small.container)[0].className;
+ small.unmount();
+
+ const large = render(
+ <DateTimeInput
+ label="Large"
+ value={'2026-03-15T09:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ size="lg"
+ onChange={() => {}}
+ />,
+ );
+ fireEvent.click(screen.getByLabelText('Large time'));
+ const largeClass = optionsIn(large.container)[0].className;
+
+ // Rows that ignore size leave an sm field with md-sized options.
+ expect(smallClass).not.toBe(largeClass);
+ });
+
+ it('commits the typed time on Enter, not the option below it', () => {
+ // Typing is free-form, so Enter must not quietly round 1:07 PM down to
+ // the 1:00 PM option the highlight is resting on.
+ const onChange = vi.fn();
+ render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T09:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={onChange}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.click(timeInput);
+ fireEvent.change(timeInput, {target: {value: '1:07 PM'}});
+ fireEvent.keyDown(timeInput, {key: 'Enter'});
+
+ const last = onChange.mock.calls[onChange.mock.calls.length - 1][0];
+ expect(last).toBe('2026-03-15T13:07');
+ expect(timeInput).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('names the list after timeLabel when one is given', () => {
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ timeLabel="Start time"
+ value={'2026-03-15T09:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />,
+ );
+
+ fireEvent.click(screen.getByLabelText('Start time'));
+ // The list belongs to the field the consumer renamed, so it must not
+ // announce itself under the old one.
+ expect(container.querySelector('[role="listbox"]')).toHaveAttribute(
+ 'aria-label',
+ 'Start time options',
+ );
+ });
+
+ it('opens from the keyboard after a pointer press that never became a click', () => {
+ // The show is deferred past an in-flight click so light-dismiss cannot
+ // eat it. A press that ends without a click must not wedge that flag.
+ render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T09:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.pointerDown(timeInput);
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown', altKey: true});
+
+ expect(timeInput).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('activates the first option when the field has a date but no time', () => {
+ // The state you land in after picking a date and no time yet. With no
+ // active option, ArrowUp and Enter both did nothing at all.
+ const onChange = vi.fn();
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={onChange}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.click(timeInput);
+
+ expect(timeInput).toHaveAttribute(
+ 'aria-activedescendant',
+ optionsIn(container)[0].id,
+ );
+
+ // ArrowUp on the first option is a no-op, not a dead end.
+ fireEvent.keyDown(timeInput, {key: 'ArrowUp'});
+ expect(timeInput).toHaveAttribute(
+ 'aria-activedescendant',
+ optionsIn(container)[0].id,
+ );
+
+ fireEvent.keyDown(timeInput, {key: 'Enter'});
+ expect(onChange).toHaveBeenCalledTimes(1);
+ expect(onChange.mock.calls[0][0]).toBe('2026-03-15T00:00');
+ });
+
+ it('keeps the active option valid when the list shrinks while open', () => {
+ const {container, rerender} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ timeOptionInterval={5}
+ onChange={() => {}}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown', altKey: true});
+ fireEvent.keyDown(timeInput, {key: 'End'});
+ expect(optionsIn(container)).toHaveLength(288);
+
+ // The cadence widens under the open list, so the old index is far past
+ // the end. A stale index leaves the user with no visible highlight and
+ // arrow keys that appear dead until they walk it back into range.
+ rerender(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />,
+ );
+
+ const options = optionsIn(container);
+ expect(options).toHaveLength(24);
+ expect(timeInput).toHaveAttribute(
+ 'aria-activedescendant',
+ options[23].id,
+ );
+ });
+
+ it('handles a min/max window that leaves exactly one option', () => {
+ const onChange = vi.fn();
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T09:20' as ISODateTimeString}
+ min={'2026-03-15T09:00' as ISODateTimeString}
+ max={'2026-03-15T09:30' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={onChange}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.click(timeInput);
+
+ const options = optionsIn(container);
+ expect(options).toHaveLength(1);
+ expect(options[0].textContent).toBe('9:00 AM');
+
+ // Every clamp expression collapses at length 1.
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown'});
+ fireEvent.keyDown(timeInput, {key: 'ArrowUp'});
+ fireEvent.keyDown(timeInput, {key: 'End'});
+ expect(timeInput).toHaveAttribute('aria-activedescendant', options[0].id);
+
+ fireEvent.keyDown(timeInput, {key: 'Enter'});
+ expect(onChange).toHaveBeenCalledTimes(1);
+ expect(onChange.mock.calls[0][0]).toBe('2026-03-15T09:00');
+ });
+
+ it('labels midnight and noon correctly in 12-hour format', () => {
+ // 00:00 and 12:00 are where 12-hour formatting classically goes wrong.
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />,
+ );
+
+ fireEvent.click(screen.getByLabelText('Meeting time'));
+ const labels = labelsIn(container);
+ expect(labels[0]).toBe('12:00 AM');
+ expect(labels[12]).toBe('12:00 PM');
+ expect(labels[11]).toBe('11:00 AM');
+ expect(labels[13]).toBe('1:00 PM');
+ });
+
+ it('highlights the nearest earlier option for a value off the cadence', () => {
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:07' as ISODateTimeString}
+ timeOptionInterval={30}
+ onChange={() => {}}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.click(timeInput);
+
+ // 14:07 sits between 14:00 (index 28) and 14:30.
+ expect(timeInput).toHaveAttribute(
+ 'aria-activedescendant',
+ optionsIn(container)[28].id,
+ );
+ // ...and nothing claims to be the selected value.
+ expect(
+ optionsIn(container).filter(
+ o => o.getAttribute('aria-selected') === 'true',
+ ),
+ ).toHaveLength(0);
+ });
+
+ it('highlights the first option for a value below the whole range', () => {
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T06:00' as ISODateTimeString}
+ min={'2026-03-15T09:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.click(timeInput);
+
+ expect(timeInput).toHaveAttribute(
+ 'aria-activedescendant',
+ optionsIn(container)[0].id,
+ );
+ expect(labelsIn(container)[0]).toBe('9:00 AM');
+ });
+
+ it('clamps the active option at both ends of the list', () => {
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T00:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown', altKey: true});
+
+ // Already on the first option: ArrowUp must not wrap to the last.
+ fireEvent.keyDown(timeInput, {key: 'ArrowUp'});
+ expect(timeInput).toHaveAttribute(
+ 'aria-activedescendant',
+ optionsIn(container)[0].id,
+ );
+
+ fireEvent.keyDown(timeInput, {key: 'End'});
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown'});
+ expect(timeInput).toHaveAttribute(
+ 'aria-activedescendant',
+ optionsIn(container)[23].id,
+ );
+ });
+
+ it('leaves Escape alone while the list is closed', () => {
+ // Swallowing Escape here would stop an enclosing Dialog from closing.
+ render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ // fireEvent returns false when the event was cancelled.
+ expect(fireEvent.keyDown(timeInput, {key: 'Escape'})).toBe(true);
+ });
+
+ it('closes the list on Tab without blocking focus from leaving', () => {
+ render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown', altKey: true});
+ expect(timeInput).toHaveAttribute('aria-expanded', 'true');
+
+ // Not cancelled, so the browser still moves focus to the next control.
+ expect(fireEvent.keyDown(timeInput, {key: 'Tab'})).toBe(true);
+ expect(timeInput).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('picking a time with no date selected changes nothing', () => {
+ // Documents the component's existing contract: every time-commit path
+ // requires a date, so the list cannot invent one.
+ const onChange = vi.fn();
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ timeOptionInterval={60}
+ onChange={onChange}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.click(timeInput);
+ expect(timeInput).toHaveAttribute('aria-expanded', 'true');
+
+ fireEvent.click(optionsIn(container)[9]);
+
+ // The click IS handled — the list closes — it just cannot produce a
+ // datetime without a date, so no change is emitted and the field stays
+ // empty rather than showing a time that was never committed.
+ expect(timeInput).toHaveAttribute('aria-expanded', 'false');
+ expect(onChange).not.toHaveBeenCalled();
+ expect(timeInput).toHaveValue('');
+ });
+
+ it('does not open the list while a change is in flight', () => {
+ render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ isLoading
+ onChange={() => {}}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ fireEvent.click(timeInput);
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown', altKey: true});
+
+ expect(timeInput).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('commits seconds in the value when hasSeconds is set', () => {
+ const onChange = vi.fn();
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ hasSeconds
+ onChange={onChange}
+ />,
+ );
+
+ fireEvent.click(screen.getByLabelText('Meeting time'));
+ fireEvent.click(optionsIn(container)[9]);
+
+ expect(onChange).toHaveBeenCalledTimes(1);
+ expect(onChange.mock.calls[0][0]).toBe('2026-03-15T09:00:00');
+ });
+
+ it('keeps two fields on one page independent', () => {
+ const {container} = render(
+ <>
+ <DateTimeInput
+ label="Starts"
+ value={'2026-03-15T09:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />
+ <DateTimeInput
+ label="Ends"
+ value={'2026-03-15T17:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />
+ </>,
+ );
+
+ const starts = screen.getByLabelText('Starts time');
+ const ends = screen.getByLabelText('Ends time');
+
+ fireEvent.click(starts);
+ expect(starts).toHaveAttribute('aria-expanded', 'true');
+ expect(ends).toHaveAttribute('aria-expanded', 'false');
+
+ const listboxes = container.querySelectorAll('[role="listbox"]');
+ expect(listboxes).toHaveLength(1);
+ // Option ids must not collide between instances.
+ const ids = optionsIn(container).map(o => o.id);
+ expect(new Set(ids).size).toBe(ids.length);
+ expect(starts.getAttribute('aria-controls')).toBe(listboxes[0].id);
+ });
+
+ it('mounts no option nodes until the list is opened', () => {
+ // The layer renders its children whether open or closed, so an
+ // unconditional list would park a day's worth of divs in the DOM of
+ // every opted-in field. At a 5-minute cadence that is 288 nodes.
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ timeOptionInterval={5}
+ onChange={() => {}}
+ />,
+ );
+
+ expect(optionsIn(container)).toHaveLength(0);
+ expect(container.querySelector('[role="listbox"]')).toBeNull();
+
+ fireEvent.click(screen.getByLabelText('Meeting time'));
+ expect(optionsIn(container)).toHaveLength(288);
+ });
+
+ it('marks the selected option when the value carries unwanted seconds', () => {
+ // splitDateTime slices the string after the T, so an external value of
+ // 14:00:00 with hasSeconds off leaves valueParts.time as "14:00:00"
+ // while every option is "14:00". A raw equality check silently marks
+ // nothing selected.
+ const {container} = render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />,
+ );
+
+ fireEvent.click(screen.getByLabelText('Meeting time'));
+ const selected = optionsIn(container).filter(
+ o => o.getAttribute('aria-selected') === 'true',
+ );
+ expect(selected).toHaveLength(1);
+ expect(selected[0].textContent).toBe('2:00 PM');
+ });
+
+ it('keeps focus in the time field when opening evicts the calendar', () => {
+ // Both layers are popover="auto", so showing the time list closes the
+ // calendar. The calendar's onHide returns focus to the date input —
+ // which would rip focus out of the field the user is working in.
+ render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />,
+ );
+
+ const dateInput = screen.getAllByRole('combobox')[0];
+ const timeInput = screen.getByLabelText('Meeting time');
+
+ fireEvent.keyDown(dateInput, {key: 'ArrowDown'});
+ expect(dateInput).toHaveAttribute('aria-expanded', 'true');
+
+ timeInput.focus();
+ fireEvent.keyDown(timeInput, {key: 'ArrowDown', altKey: true});
+
+ expect(timeInput).toHaveAttribute('aria-expanded', 'true');
+ expect(timeInput).toHaveFocus();
+ });
+
+ it('starts closed and opens only when asked', () => {
+ render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:00' as ISODateTimeString}
+ timeOptionInterval={60}
+ onChange={() => {}}
+ />,
+ );
+
+ const timeInput = screen.getByLabelText('Meeting time');
+ expect(timeInput).toHaveAttribute('aria-expanded', 'false');
+ expect(timeInput).not.toHaveAttribute('aria-activedescendant');
+
+ fireEvent.click(timeInput);
+ expect(timeInput).toHaveAttribute('aria-expanded', 'true');
+ });
+ });
+
describe('weekStartsOn', () => {
// The calendar popover renders in the top layer; jsdom keeps the content in
// the DOM but role queries skip it, so read the columnheaders directly.
diff --git a/packages/core/src/DateTimeInput/DateTimeInput.tsx b/packages/core/src/DateTimeInput/DateTimeInput.tsx
index 9464cbe375..ed5aa0b0f8 100644
--- a/packages/core/src/DateTimeInput/DateTimeInput.tsx
+++ b/packages/core/src/DateTimeInput/DateTimeInput.tsx
@@ -21,10 +21,12 @@ import {
useId,
useState,
useCallback,
+ useEffect,
useRef,
useMemo,
useOptimistic,
useTransition,
+ type FocusEvent,
type KeyboardEvent,
} from 'react';
import * as stylex from '@stylexjs/stylex';
@@ -35,6 +37,7 @@ import {
spacingVars,
typographyVars,
typeScaleVars,
+ fontWeightVars,
borderVars,
} from '../theme/tokens.stylex';
import {
@@ -64,6 +67,7 @@ import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {
type ISOTimeString,
parseDateInput,
+ parseISOTime,
parseTimeInput,
formatDisplayTime12h,
formatDisplayTime24h,
@@ -102,6 +106,12 @@ export type DateTimeInputSize = 'sm' | 'md' | 'lg';
/** Supported minute increments for arrow-key stepping of the time field. */
export type DateTimeInputTimeIncrement = 1 | 5 | 10 | 15 | 30;
+/**
+ * Supported minute cadences for the preset-time dropdown. Every value divides
+ * an hour evenly, so each option lands on a round clock time.
+ */
+export type DateTimeInputTimeOptionInterval = 5 | 10 | 15 | 30 | 60;
+
export type {
InputStatus as DateTimeInputStatus,
InputStatusType as DateTimeInputStatusType,
@@ -170,6 +180,57 @@ const styles = stylex.create({
flex: 1,
flexBasis: 0,
},
+ // Preset-time list. Paddings and states mirror BaseTypeahead's dropdown and
+ // Selector's options so every list in the system reads the same.
+ timeListbox: {
+ boxSizing: 'border-box',
+ maxHeight: 300,
+ overflowY: 'auto',
+ padding: spacingVars['--spacing-1'],
+ minWidth: 'anchor-size(width)',
+ },
+ timeOption: {
+ boxSizing: 'border-box',
+ display: 'flex',
+ alignItems: 'center',
+ width: '100%',
+ paddingBlock: spacingVars['--spacing-1-5'],
+ paddingInline: spacingVars['--spacing-2'],
+ borderRadius: radiusVars['--radius-element'],
+ cursor: {
+ default: 'pointer',
+ ':is(:disabled,[aria-disabled="true"])': 'default',
+ },
+ textAlign: 'start',
+ fontFamily: typographyVars['--font-family-body'],
+ fontSize: typeScaleVars['--text-body-size'],
+ lineHeight: typeScaleVars['--text-body-leading'],
+ color: colorVars['--color-text-primary'],
+ backgroundColor: 'transparent',
+ },
+ timeOptionHighlighted: {
+ backgroundColor: colorVars['--color-overlay-hover'],
+ },
+ timeOptionSelected: {
+ fontWeight: fontWeightVars['--font-weight-medium'],
+ },
+});
+
+/**
+ * Size-specific padding for the preset-time options, so an `sm` field gets a
+ * compact list. Matches DropdownMenuItem / Selector / BaseTypeahead.
+ */
+const timeOptionSizeStyles = stylex.create({
+ sm: {
+ paddingBlock: spacingVars['--spacing-1'],
+ paddingInline: spacingVars['--spacing-2'],
+ },
+ md: {
+ paddingBlock: spacingVars['--spacing-1-5'],
+ },
+ lg: {
+ paddingBlock: spacingVars['--spacing-2'],
+ },
});
const sizeStyles = stylex.create({
@@ -307,6 +368,22 @@ export interface DateTimeInputProps extends Omit<
*/
timeIncrement?: DateTimeInputTimeIncrement;
+ /**
+ * Minute cadence for a dropdown of preset times on the time field. Set it to
+ * turn the time field into a combobox listing every valid time at that
+ * cadence (`60` gives the 12 AM - 11 PM list, `15` a quarter-hour list).
+ *
+ * Omitted, the time field stays a plain text input: typed entry and
+ * arrow-key stepping only, with no combobox semantics added to the
+ * accessibility tree. Typed entry keeps working when the dropdown is on —
+ * the list is a shortcut, not a restriction, so a time between two options
+ * can still be typed.
+ *
+ * Independent of `timeIncrement`, which governs arrow-key stepping. Setting
+ * both to the same value is the usual choice for scheduling flows.
+ */
+ timeOptionInterval?: DateTimeInputTimeOptionInterval;
+
/**
* Whether to show a clear button when a value is set.
* @default false
@@ -396,6 +473,8 @@ function combineDateTime(
return `${date}T${time}` as ISODateTimeString;
}
+const MINUTES_PER_DAY = 24 * 60;
+
function getDefaultTime(hasSeconds: boolean): ISOTimeString {
const now = new Date();
return formatISOTime(
@@ -436,6 +515,7 @@ export function DateTimeInput({
hasSeconds = false,
hourFormat = '12h',
timeIncrement = 1,
+ timeOptionInterval,
hasClear = false,
placeholder: placeholderFromProps,
timePlaceholder: timePlaceholderFromProps,
@@ -613,6 +693,46 @@ export function DateTimeInput({
return timePlaceholder;
}, [isTimeFocused, timeDisplayValue, hourFormat, timePlaceholder, t]);
+ // The time field's own accessible name. The option list is named from this
+ // rather than from `label`, so a consumer-supplied timeLabel renames both
+ // together instead of leaving the list announcing the old name.
+ const resolvedTimeLabel =
+ timeLabel ?? t('@astryx.dateTimeInput.timeSuffix', {label});
+
+ // --- Preset time options (#2727) ---
+ // Opt-in: without timeOptionInterval the time field keeps exactly the
+ // semantics it shipped with — a plain text input, no combobox role, no
+ // second listbox in the accessibility tree.
+ const hasTimeOptions = timeOptionInterval !== undefined;
+
+ const timeOptions = useMemo(() => {
+ if (timeOptionInterval === undefined) {
+ return [];
+ }
+ const options: {time: ISOTimeString; label: string}[] = [];
+ for (
+ let minutes = 0;
+ minutes < MINUTES_PER_DAY;
+ minutes += timeOptionInterval
+ ) {
+ const time = formatISOTime(
+ {
+ hour: Math.floor(minutes / 60),
+ minute: minutes % 60,
+ second: 0,
+ },
+ hasSeconds,
+ );
+ // The same bound the typed path enforces, so the list can never offer a
+ // time that typing the identical string would reject.
+ if (!isTimeInRange(time, timeMin, timeMax)) {
+ continue;
+ }
+ options.push({time, label: formatDisplayTime(time, hasSeconds)});
+ }
+ return options;
+ }, [timeOptionInterval, hasSeconds, timeMin, timeMax, formatDisplayTime]);
+
// --- Unified change handler ---
const fireChange = useCallback(
(newValue: ISODateTimeString | undefined) => {
@@ -789,6 +909,222 @@ export function DateTimeInput({
[popover, commitDatePendingInput, isEffectivelyDisabled],
);
+ // --- Time-option popover (#2727) ---
+ const timeListboxId = useId();
+ const [highlightedTimeIndex, setHighlightedTimeIndex] = useState(-1);
+
+ // With popover="auto", showing the popover between pointerdown and
+ // pointerup/click lets the browser's light-dismiss treat that same click as
+ // "outside" and close it again. Defer the show past the click, as
+ // BaseTypeahead does for the same reason.
+ const timePointerActiveRef = useRef(false);
+
+ // Whether the highlight is still the one typing derived, or the user has
+ // since moved it themselves. Enter honours typed text only in the former
+ // case — otherwise the field would commit something other than the option
+ // it is showing as active.
+ const timeHighlightFollowsTypingRef = useRef(true);
+
+ const markTimePointerActive = useCallback(() => {
+ timePointerActiveRef.current = true;
+ document.addEventListener(
+ 'click',
+ () => {
+ timePointerActiveRef.current = false;
+ },
+ {once: true},
+ );
+ }, []);
+
+ const timePopover = usePopover({
+ hasLightDismiss: true,
+ hasCloseButton: false,
+ hasAutoFocus: false,
+ // The popup's own role="listbox" carries the semantics; the input keeps
+ // DOM focus, so announcing a dialog here would misrepresent it.
+ role: 'none',
+ onHide: () => setHighlightedTimeIndex(-1),
+ });
+
+ // Anchor the list to the time wrapper, not the date input the field's own
+ // trigger ref points at.
+ useEffect(() => {
+ if (!hasTimeOptions) {
+ return;
+ }
+ const el = timeContainerRef.current;
+ if (el) {
+ timePopover.triggerRef(el);
+ }
+ return () => {
+ timePopover.triggerRef(null);
+ };
+ }, [timePopover, hasTimeOptions]);
+
+ const timeOptionId = useCallback(
+ (index: number) => `${timeListboxId}-option-${index}`,
+ [timeListboxId],
+ );
+
+ // A field can go disabled or busy while its list is open — a changeAction
+ // starting elsewhere in the form is enough. Leave it up and the dropdown
+ // hangs over a control that no longer accepts input.
+ // The same applies to a list that empties after it opened, which a narrowing
+ // min/max window does. An open-but-empty list gates the keyboard switch off,
+ // so the arrows quietly fall back to stepping the value instead.
+ useEffect(() => {
+ if (
+ timePopover.isOpen &&
+ (isEffectivelyDisabled || timeOptions.length === 0)
+ ) {
+ timePopover.hide();
+ }
+ }, [isEffectivelyDisabled, timeOptions.length, timePopover]);
+
+ // The option list can shrink under an open popover — min/max tighten when
+ // the date moves onto a boundary day, or the cadence prop changes. A stale
+ // index past the new end shows no highlight at all and makes the arrow keys
+ // look dead until the user walks it back into range.
+ // Clamped as it is read rather than synced through an effect: no extra
+ // render, and the index can never point past the end even for the paint
+ // where the list shrank.
+ const activeTimeIndex =
+ highlightedTimeIndex > timeOptions.length - 1
+ ? timeOptions.length - 1
+ : highlightedTimeIndex;
+
+ // Keep the active option visible. The listbox is a fixed-height scroll
+ // container, so without this a list opens at midnight with the highlight far
+ // below the fold, and keyboard navigation walks off-screen. Mirrors
+ // BaseTypeahead's scrollIntoView({block: 'nearest'}).
+ useEffect(() => {
+ if (
+ !timePopover.isOpen ||
+ activeTimeIndex < 0 ||
+ activeTimeIndex >= timeOptions.length
+ ) {
+ return;
+ }
+ document
+ .getElementById(timeOptionId(activeTimeIndex))
+ ?.scrollIntoView?.({block: 'nearest'});
+ }, [timePopover.isOpen, activeTimeIndex, timeOptionId, timeOptions.length]);
+
+ /**
+ * The selected time in the same shape the options carry. splitDateTime slices
+ * whatever follows the `T`, so a caller passing `14:00:00` with hasSeconds
+ * off leaves `"14:00:00"` against options of `"14:00"` — comparing raw would
+ * mark nothing selected, silently.
+ */
+ const selectedOptionTime = useMemo(() => {
+ if (!valueParts.time) {
+ return undefined;
+ }
+ const parsed = parseISOTime(valueParts.time);
+ return parsed ? formatISOTime(parsed, hasSeconds) : undefined;
+ }, [valueParts.time, hasSeconds]);
+
+ /**
+ * Index of the option at or immediately before `time`, so opening on a value
+ * that is not itself an option (13:07 in a 15-minute list) still lands the
+ * highlight somewhere sensible instead of nowhere.
+ */
+ const closestOptionIndex = useCallback(
+ (time: ISOTimeString | undefined) => {
+ if (timeOptions.length === 0) {
+ return -1;
+ }
+ // No time yet — the state a field lands in once a date is picked. The
+ // list still opens on the first option, per the APG listbox pattern;
+ // leaving it inactive made ArrowUp and Enter do nothing at all.
+ if (!time) {
+ return 0;
+ }
+ let candidate = -1;
+ for (let i = 0; i < timeOptions.length; i++) {
+ if (timeOptions[i].time <= time) {
+ candidate = i;
+ } else {
+ break;
+ }
+ }
+ // A value below every option (min pushes the list past it) still gets the
+ // first option rather than an empty highlight.
+ return candidate === -1 ? 0 : candidate;
+ },
+ [timeOptions],
+ );
+
+ const showTimeOptions = useCallback(() => {
+ if (
+ !hasTimeOptions ||
+ isEffectivelyDisabled ||
+ timePopover.isOpen ||
+ // A min/max window narrower than the cadence survives no option at all.
+ // Opening on that would show an empty panel with nothing to pick.
+ timeOptions.length === 0
+ ) {
+ return;
+ }
+ setHighlightedTimeIndex(closestOptionIndex(selectedOptionTime));
+ // useInputContainer routes wrapper clicks through input.click() once the
+ // input advertises a popup, and a programmatic click does not focus. The
+ // input must hold DOM focus or aria-activedescendant announces nothing.
+ timeInputRef.current?.focus();
+ if (timePointerActiveRef.current) {
+ document.addEventListener(
+ 'click',
+ () =>
+ requestAnimationFrame(() => timePopover.show({skipAutoFocus: true})),
+ {once: true},
+ );
+ } else {
+ timePopover.show({skipAutoFocus: true});
+ }
+ }, [
+ hasTimeOptions,
+ isEffectivelyDisabled,
+ timePopover,
+ timeOptions.length,
+ closestOptionIndex,
+ selectedOptionTime,
+ ]);
+
+ /**
+ * The single commit path for a time chosen from the list. Deliberately the
+ * same shape as the typed path: same range check, same date requirement, so
+ * picking 9:00 AM and typing "9:00 AM" are indistinguishable downstream.
+ */
+ const commitTimeOption = useCallback(
+ (time: ISOTimeString) => {
+ if (isEffectivelyDisabled || !isTimeInRange(time, timeMin, timeMax)) {
+ return;
+ }
+ setTimePendingInput(null);
+ // Compared against the normalised time, the same one the selected marker
+ // uses. Comparing the raw value instead made clicking the option that
+ // renders as selected emit a change, whenever the value carried seconds
+ // the field does not display.
+ if (time !== selectedOptionTime && valueParts.date) {
+ const combined = combineDateTime(valueParts.date, time);
+ if (combined) {
+ fireChange(combined);
+ }
+ }
+ timePopover.hide();
+ timeInputRef.current?.focus();
+ },
+ [
+ isEffectivelyDisabled,
+ timeMin,
+ timeMax,
+ selectedOptionTime,
+ valueParts.date,
+ fireChange,
+ timePopover,
+ ],
+ );
+
// --- Time handlers ---
const handleTimeInputChange = useCallback(
(e: React.ChangeEvent<HTMLInputElement>) => {
@@ -801,6 +1137,15 @@ export function DateTimeInput({
setTimePendingInput(text);
const parsed = parseTimeInput(text, hasSeconds);
+
+ // Typing narrows nothing — free-form entry is the contract, and a time
+ // between two options must stay reachable. The list instead follows the
+ // typed value so Enter lands somewhere the user expects.
+ if (timePopover.isOpen && parsed) {
+ timeHighlightFollowsTypingRef.current = true;
+ setHighlightedTimeIndex(closestOptionIndex(parsed));
+ }
+
if (
parsed &&
isTimeInRange(parsed, timeMin, timeMax) &&
@@ -822,6 +1167,8 @@ export function DateTimeInput({
valueParts.date,
fireChange,
isEffectivelyDisabled,
+ timePopover.isOpen,
+ closestOptionIndex,
],
);
@@ -835,29 +1182,59 @@ export function DateTimeInput({
setIsTimeFocused(true);
}, [isEffectivelyDisabled]);
- const handleTimeBlur = useCallback(() => {
- setIsTimeFocused(false);
- if (timePendingInput === null) {
- return;
- }
+ const handleTimeBlur = useCallback(
+ (e: FocusEvent<HTMLInputElement>) => {
+ setIsTimeFocused(false);
+
+ // Native light dismiss only fires on outside clicks and Escape, so a focus
+ // move that is neither — Tab handled elsewhere, or a programmatic focus —
+ // would strand the listbox open in the top layer. Focus landing inside the
+ // field or the popup itself is not a leave. Mirrors BaseTypeahead.
+ if (timePopover.isOpen) {
+ const next = e.relatedTarget as Node | null;
+ const popoverEl = next ? document.getElementById(timePopover.id) : null;
+ if (
+ !next ||
+ !(
+ timeContainerRef.current?.contains(next) ||
+ popoverEl?.contains(next)
+ )
+ ) {
+ timePopover.hide();
+ }
+ }
- if (!timePendingInput.trim()) {
- // Empty time: revert display to previous value (don't emit partial datetime)
- setTimePendingInput(null);
- return;
- }
+ if (timePendingInput === null) {
+ return;
+ }
- const parsed = parseTimeInput(timePendingInput, hasSeconds);
- if (parsed && isTimeInRange(parsed, timeMin, timeMax)) {
- if (parsed !== valueParts.time && valueParts.date) {
- const combined = combineDateTime(valueParts.date, parsed);
- if (combined) {
- fireChange(combined);
+ if (!timePendingInput.trim()) {
+ // Empty time: revert display to previous value (don't emit partial datetime)
+ setTimePendingInput(null);
+ return;
+ }
+
+ const parsed = parseTimeInput(timePendingInput, hasSeconds);
+ if (parsed && isTimeInRange(parsed, timeMin, timeMax)) {
+ if (parsed !== valueParts.time && valueParts.date) {
+ const combined = combineDateTime(valueParts.date, parsed);
+ if (combined) {
+ fireChange(combined);
+ }
}
}
- }
- setTimePendingInput(null);
- }, [timePendingInput, hasSeconds, timeMin, timeMax, valueParts, fireChange]);
+ setTimePendingInput(null);
+ },
+ [
+ timePendingInput,
+ hasSeconds,
+ timeMin,
+ timeMax,
+ valueParts,
+ fireChange,
+ timePopover,
+ ],
+ );
const handleTimeKeyDown = useCallback(
(e: KeyboardEvent<HTMLInputElement>) => {
@@ -868,6 +1245,84 @@ export function DateTimeInput({
if (isImeKeyEvent(e.nativeEvent)) {
return;
}
+
+ // The dropdown claims the arrow keys only while it is open. Closed, they
+ // keep stepping the value by timeIncrement exactly as they always have —
+ // that behaviour is documented and tested, so the list borrows Alt+Arrow
+ // Down (the APG "open without moving" binding) to open instead.
+ if (hasTimeOptions && !isEffectivelyDisabled) {
+ if (e.key === 'Escape' && timePopover.isOpen) {
+ e.preventDefault();
+ timePopover.hide();
+ return;
+ }
+
+ if (e.key === 'ArrowDown' && e.altKey) {
+ e.preventDefault();
+ // A keyboard open is never mid-click, so clear the deferral flag. A
+ // press that ended without a click would otherwise leave it set and
+ // hold every later open hostage to the next click anywhere.
+ timePointerActiveRef.current = false;
+ showTimeOptions();
+ return;
+ }
+
+ if (timePopover.isOpen && timeOptions.length > 0) {
+ switch (e.key) {
+ case 'ArrowDown':
+ e.preventDefault();
+ timeHighlightFollowsTypingRef.current = false;
+ setHighlightedTimeIndex(
+ activeTimeIndex < timeOptions.length - 1
+ ? activeTimeIndex + 1
+ : activeTimeIndex,
+ );
+ return;
+ case 'ArrowUp':
+ e.preventDefault();
+ timeHighlightFollowsTypingRef.current = false;
+ setHighlightedTimeIndex(
+ activeTimeIndex > 0 ? activeTimeIndex - 1 : activeTimeIndex,
+ );
+ return;
+ case 'Home':
+ e.preventDefault();
+ timeHighlightFollowsTypingRef.current = false;
+ setHighlightedTimeIndex(0);
+ return;
+ case 'End':
+ e.preventDefault();
+ timeHighlightFollowsTypingRef.current = false;
+ setHighlightedTimeIndex(timeOptions.length - 1);
+ return;
+ case 'Enter': {
+ e.preventDefault();
+ // Typed text wins over the highlight. The highlight only tracks
+ // the option at or before what was typed, so committing it here
+ // would round 1:07 PM down to 1:00 PM and discard the entry.
+ const typed =
+ timeHighlightFollowsTypingRef.current &&
+ timePendingInput !== null
+ ? parseTimeInput(timePendingInput, hasSeconds)
+ : null;
+ const option = timeOptions[activeTimeIndex];
+ if (typed) {
+ commitTimeOption(typed);
+ } else if (option) {
+ commitTimeOption(option.time);
+ }
+ return;
+ }
+ case 'Tab':
+ // Let focus leave; blur commits any typed text as usual.
+ timePopover.hide();
+ return;
+ default:
+ break;
+ }
+ }
+ }
+
if (e.key === 'ArrowUp' || e.key === 'ArrowDown') {
e.preventDefault();
@@ -907,6 +1362,14 @@ export function DateTimeInput({
fireChange,
announce,
formatDisplayTime,
+ hasTimeOptions,
+ isEffectivelyDisabled,
+ timePopover,
+ timeOptions,
+ activeTimeIndex,
+ timePendingInput,
+ showTimeOptions,
+ commitTimeOption,
],
);
@@ -1067,6 +1530,10 @@ export function DateTimeInput({
ref={timeContainerRef}
onClick={handleTimeWrapperClick}
onMouseUp={handleTimeWrapperMouseUp}
+ // On the wrapper, not just the input: clicking the clock icon or the
+ // padding is routed to the input as a synthetic click, which would
+ // otherwise open the list mid-gesture and let light dismiss eat it.
+ onPointerDown={hasTimeOptions ? markTimePointerActive : undefined}
{...mergeProps(
themeProps('date-time-input-time-segment', {
size,
@@ -1105,16 +1572,32 @@ export function DateTimeInput({
onFocus={handleTimeFocus}
onBlur={handleTimeBlur}
onKeyDown={handleTimeKeyDown}
+ onClick={hasTimeOptions ? showTimeOptions : undefined}
+ onPointerDown={hasTimeOptions ? markTimePointerActive : undefined}
placeholder={resolvedTimePlaceholder}
+ // Combobox semantics appear only with the dropdown opted in, so a
+ // field without it keeps a single combobox on the date half.
+ role={hasTimeOptions ? 'combobox' : undefined}
+ aria-expanded={hasTimeOptions ? timePopover.isOpen : undefined}
+ aria-controls={
+ hasTimeOptions && timePopover.isOpen ? timeListboxId : undefined
+ }
+ aria-autocomplete={hasTimeOptions ? 'list' : undefined}
+ aria-activedescendant={
+ hasTimeOptions &&
+ timePopover.isOpen &&
+ activeTimeIndex >= 0 &&
+ activeTimeIndex < timeOptions.length
+ ? timeOptionId(activeTimeIndex)
+ : undefined
+ }
// With a disabledMessage the input keeps focusability via
// aria-disabled so the reason is focus-discoverable; typing is
// blocked with readOnly and the mutation guards.
disabled={isEffectivelyDisabled && !showsDisabledMessage}
aria-disabled={showsDisabledMessage ? 'true' : undefined}
readOnly={showsDisabledMessage || undefined}
- aria-label={
- timeLabel ?? t('@astryx.dateTimeInput.timeSuffix', {label})
- }
+ aria-label={resolvedTimeLabel}
aria-describedby={ariaDescribedBy}
aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={
@@ -1152,6 +1635,55 @@ export function DateTimeInput({
{placement: 'below', alignment: 'start'},
)}
+ {hasTimeOptions &&
+ timePopover.render(
+ // The layer renders its children open or closed, so mount the list
+ // only while it is open — a 5-minute cadence is 288 nodes that would
+ // otherwise sit in the DOM of every opted-in field for its lifetime.
+ !timePopover.isOpen ? null : (
+ <div
+ id={timeListboxId}
+ role="listbox"
+ aria-label={t('@astryx.dateTimeInput.timeOptionsLabel', {
+ label: resolvedTimeLabel,
+ })}
+ {...mergeProps(
+ themeProps('date-time-input-time-listbox'),
+ stylex.props(styles.timeListbox),
+ )}>
+ {timeOptions.map((option, index) => {
+ const isSelected = option.time === selectedOptionTime;
+ return (
+ <div
+ key={option.time}
+ id={timeOptionId(index)}
+ role="option"
+ aria-selected={isSelected}
+ tabIndex={-1}
+ // Pointer-down commit: the input must not lose focus to the
+ // option, or blur would fire its own commit first.
+ onPointerDown={e => e.preventDefault()}
+ onClick={() => commitTimeOption(option.time)}
+ onMouseEnter={() => setHighlightedTimeIndex(index)}
+ {...mergeProps(
+ themeProps('date-time-input-time-option'),
+ stylex.props(
+ styles.timeOption,
+ timeOptionSizeStyles[size],
+ index === activeTimeIndex &&
+ styles.timeOptionHighlighted,
+ isSelected && styles.timeOptionSelected,
+ ),
+ )}>
+ {option.label}
+ </div>
+ );
+ })}
+ </div>
+ ),
+ {placement: 'below', alignment: 'start'},
+ )}
+
{showsDisabledMessage &&
disabledMessageTooltip.renderTooltip(disabledMessage)}
</Field>
diff --git a/packages/core/src/DateTimeInput/index.ts b/packages/core/src/DateTimeInput/index.ts
index 8ae8292da4..2f14f0f83c 100644
--- a/packages/core/src/DateTimeInput/index.ts
+++ b/packages/core/src/DateTimeInput/index.ts
@@ -15,6 +15,7 @@ export type {
DateTimeInputSize,
DateTimeInputHourFormat,
DateTimeInputTimeIncrement,
+ DateTimeInputTimeOptionInterval,
DateTimeInputStatus,
DateTimeInputStatusType,
ISODateTimeString,