{
// Tap outside the wheel card (on the covered calendar area)
// collapses the wheels without selecting a date, matching the
// native behavior.
- if (e.target === e.currentTarget) setTimeOpen(false);
+ if (e.target === e.currentTarget) closeTime();
}}
>
@@ -622,9 +680,10 @@ export const DateTimeInputBase = forwardRef<
setTimeOpen(o => !o)}
+ onClick={() => (timeOpen ? closeTime() : setTimeOpen(true))}
aria-expanded={timeOpen}
disabled={disabled}
>
diff --git a/bulma-ui/src/form/TimeInput.stories.tsx b/bulma-ui/src/form/TimeInput.stories.tsx
index 2a2bdec43..38d69ca1a 100644
--- a/bulma-ui/src/form/TimeInput.stories.tsx
+++ b/bulma-ui/src/form/TimeInput.stories.tsx
@@ -345,7 +345,7 @@ export const ManualEntry24h: Story = {
docs: {
description: {
story:
- '24-hour segmented entry with `openOnFocus={false}` — the hours segment accepts `00`–`23` directly, and the wheel popover only opens from the launcher icon or `↓`.',
+ '24-hour segmented entry with `openOnFocus={false}` — the hours segment accepts `00`–`23` directly, and the wheel popover only opens from the launcher icon or `Alt+↓`.',
},
},
},
@@ -362,7 +362,7 @@ export const ManualEntryIncrementSteps: Story = {
docs: {
description: {
story:
- 'Increments steer the wheels, not the keyboard — typed minutes stay free-grained, so `09:32` goes in even with a step of 5. With `openOnFocus={false}` the stepped wheels only appear from the launcher icon or `↓`.',
+ 'Increments steer the wheels, not the keyboard — typed minutes stay free-grained, so `09:32` goes in even with a step of 5. With `openOnFocus={false}` the stepped wheels only appear from the launcher icon or `Alt+↓`.',
},
},
},
@@ -409,7 +409,7 @@ export const ManualEntryFormats: Story = {
docs: {
description: {
story:
- 'The same token formats, typing-first — `openOnFocus={false}` on each field keeps the wheels behind the launcher icon or `↓` while you type through the segments.',
+ 'The same token formats, typing-first — `openOnFocus={false}` on each field keeps the wheels behind the launcher icon or `Alt+↓` while you type through the segments.',
},
},
},
@@ -425,7 +425,7 @@ export const ManualEntryLauncherIcon: Story = {
docs: {
description: {
story:
- 'With `openOnFocus={false}` the custom `triggerIconName` launcher (or `↓`) is the only way to open the spinner — clicking into the field just starts typing.',
+ 'With `openOnFocus={false}` the custom `triggerIconName` launcher (or `Alt+↓`) is the only way to open the spinner — clicking into the field just starts typing.',
},
},
},
@@ -459,7 +459,7 @@ export const ManualEntrySizes: Story = {
docs: {
description: {
story:
- 'Every size with `openOnFocus={false}` — segmented typing works the same at each scale, and the spinner waits for the launcher icon or `↓`.',
+ 'Every size with `openOnFocus={false}` — segmented typing works the same at each scale, and the spinner waits for the launcher icon or `Alt+↓`.',
},
},
},
@@ -479,7 +479,7 @@ export const ManualEntryColors: Story = {
docs: {
description: {
story:
- 'Every color with `openOnFocus={false}` — type into each field directly; the wheels only open from the launcher icon or `↓`.',
+ 'Every color with `openOnFocus={false}` — type into each field directly; the wheels only open from the launcher icon or `Alt+↓`.',
},
},
},
@@ -497,7 +497,7 @@ export const ManualEntryAudioTick: Story = {
docs: {
description: {
story:
- 'The same audio-thunk feedback with `openOnFocus={false}` — typing into the field is silent; the tick fires when you open the wheels via the launcher icon (or `↓`) and scroll them.',
+ 'The same audio-thunk feedback with `openOnFocus={false}` — typing into the field is silent; the tick fires when you open the wheels via the launcher icon (or `Alt+↓`) and scroll them.',
},
},
},
@@ -515,7 +515,7 @@ export const ManualEntryHaptics: Story = {
docs: {
description: {
story:
- 'Auto-routed haptics with `openOnFocus={false}` — the per-platform feedback fires when the wheels opened via the launcher icon (or `↓`) are scrolled, while typed entry stays feedback-free.',
+ 'Auto-routed haptics with `openOnFocus={false}` — the per-platform feedback fires when the wheels opened via the launcher icon (or `Alt+↓`) are scrolled, while typed entry stays feedback-free.',
},
},
},
diff --git a/bulma-ui/src/form/TimeInputBase.tsx b/bulma-ui/src/form/TimeInputBase.tsx
index ba04c97e1..1fb0caaf7 100644
--- a/bulma-ui/src/form/TimeInputBase.tsx
+++ b/bulma-ui/src/form/TimeInputBase.tsx
@@ -130,7 +130,7 @@ export interface TimeInputBaseProps
* Open the popover when the input is focused. Focus that a closing popover
* hands back to the input leaves it closed. Dismissing it commits nothing:
* an empty field stays empty, and leaving afterwards commits only what was
- * typed since.
+ * typed since. With it off, the launcher or Alt+ArrowDown opens it.
*/
openOnFocus?: boolean;
/** Close the popover after a time is selected (off by default). */
@@ -362,10 +362,17 @@ export const TimeInputBase = forwardRef(
[isControlled, onChange]
);
+ // An empty field starts from today, at the whole minute or second the
+ // wheels show.
const handleSpinnerChange = useCallback(
(parts: { hours: number; minutes: number; seconds?: number }) => {
- const base = value ?? new Date();
- const next = setTimeOfDay(base, parts);
+ const next = value
+ ? setTimeOfDay(value, parts)
+ : setTimeOfDay(new Date(), {
+ ...parts,
+ seconds: parts.seconds ?? 0,
+ milliseconds: 0,
+ });
if (!isWithin(next, lowerBound, max)) return;
commitValue(next);
},
diff --git a/bulma-ui/src/form/__tests__/Calendar.test.tsx b/bulma-ui/src/form/__tests__/Calendar.test.tsx
index e68207508..67876edd3 100644
--- a/bulma-ui/src/form/__tests__/Calendar.test.tsx
+++ b/bulma-ui/src/form/__tests__/Calendar.test.tsx
@@ -2036,3 +2036,44 @@ describe('Calendar focus inside a shadow root', () => {
expect(root.activeElement).toHaveTextContent('2025');
});
});
+
+describe('Calendar and the popover toggle keys', () => {
+ // Alt+ArrowDown and Alt+ArrowUp open and close a picker's popover, so the
+ // calendar leaves them to it in every view rather than moving focus.
+ beforeAll(() => {
+ HTMLElement.prototype.scrollIntoView = jest.fn();
+ });
+ const toggleKeys = (el: Element) =>
+ ['ArrowUp', 'ArrowDown'].map(key =>
+ fireEvent.keyDown(el, { key, altKey: true })
+ );
+
+ it.each([
+ ['the day grid', 'day', '[data-focused="true"]'],
+ ['the month grid', 'month', '[data-focused="true"]'],
+ ['the year list', 'year', '[data-focused-year="true"]'],
+ ] as const)('in %s', (_view, granularity, selector) => {
+ const onFocusedDateChange = jest.fn();
+ const { container } = render(
+ {
onChange={handler}
/>
);
- fireEvent.keyDown(wheels[0], { key: 'PageUp' });
+ fireEvent.keyDown(wheels[0], { key: 'PageDown' });
expect(lastDate(handler).getHours()).toBe(5);
});
@@ -704,7 +725,7 @@ describe('TimeWheels keyboard and value mapping', () => {
onChange={handler}
/>
);
- fireEvent.keyDown(wheels[0], { key: 'ArrowUp' }); // display 12 → 11 (PM)
+ fireEvent.keyDown(wheels[0], { key: 'ArrowDown' }); // display 12 → 11 (PM)
expect(lastDate(handler).getHours()).toBe(23);
});
@@ -718,12 +739,12 @@ describe('TimeWheels keyboard and value mapping', () => {
onChange={handler}
/>
);
- fireEvent.keyDown(wheels[0], { key: 'ArrowDown' }); // display 12 → 1 (AM)
+ fireEvent.keyDown(wheels[0], { key: 'ArrowUp' }); // display 12 → 1 (AM)
expect(lastDate(handler).getHours()).toBe(1);
expect(lastDate(handler).getMinutes()).toBe(30);
});
- it('ArrowDown on the seconds wheel advances the seconds', () => {
+ it('ArrowUp on the seconds wheel advances the seconds', () => {
const handler = jest.fn();
const { wheels } = openPicker(
{
onChange={handler}
/>
);
- fireEvent.keyDown(wheels[2], { key: 'ArrowDown' });
+ fireEvent.keyDown(wheels[2], { key: 'ArrowUp' });
expect(lastDate(handler).getSeconds()).toBe(31);
});
@@ -747,12 +768,12 @@ describe('TimeWheels keyboard and value mapping', () => {
/>
);
const ampm = getAllByRole('spinbutton')[2];
- fireEvent.keyDown(ampm, { key: 'ArrowDown' });
+ fireEvent.keyDown(ampm, { key: 'ArrowUp' });
expect(fn).toHaveBeenCalledTimes(1);
expect(fn.mock.calls[0][0]).toMatchObject({ hours: 21, minutes: 0 });
// The value prop is uncontrolled here (still 9 AM = index 0), so moving
// back fires onChange(0) — equal to the current ampmIndex → no commit.
- fireEvent.keyDown(ampm, { key: 'ArrowUp' });
+ fireEvent.keyDown(ampm, { key: 'ArrowDown' });
expect(fn).toHaveBeenCalledTimes(1);
});
@@ -833,7 +854,7 @@ describe('TimeWheels keyboard and value mapping', () => {
expect(getByRole('dialog')).toBeInTheDocument();
});
- it('hour and minute changes preserve the seconds part; ArrowUp steps seconds back', () => {
+ it('hour and minute changes preserve the seconds part; ArrowDown steps seconds back', () => {
const handler = jest.fn();
const { wheels } = openPicker(
{
onChange={handler}
/>
);
- fireEvent.keyDown(wheels[0], { key: 'ArrowDown' });
+ fireEvent.keyDown(wheels[0], { key: 'ArrowUp' });
expect(lastDate(handler).getHours()).toBe(11);
expect(lastDate(handler).getSeconds()).toBe(30);
- fireEvent.keyDown(wheels[1], { key: 'ArrowDown' });
+ fireEvent.keyDown(wheels[1], { key: 'ArrowUp' });
expect(lastDate(handler).getMinutes()).toBe(31);
expect(lastDate(handler).getSeconds()).toBe(30);
- fireEvent.keyDown(wheels[2], { key: 'ArrowUp' });
+ fireEvent.keyDown(wheels[2], { key: 'ArrowDown' });
expect(lastDate(handler).getSeconds()).toBe(29);
});
+ it('asks unselectableTimes about whole seconds, without the milliseconds of the clock', () => {
+ jest.useFakeTimers({
+ doNotFake: [
+ 'performance',
+ 'requestAnimationFrame',
+ 'cancelAnimationFrame',
+ ],
+ });
+ jest.setSystemTime(new Date(2026, 9, 7, 14, 23, 10, 507));
+ try {
+ const predicate = jest.fn((d: Date) => d.getMilliseconds() !== 0);
+ const fn = jest.fn();
+ const { getAllByRole } = render(
+ = ({
const handleKeyDown = useCallback(
(e: React.KeyboardEvent) => {
+ if (isPopoverToggleKey(e)) return;
// A key takes the range preview back from the pointer.
setHoverDate(null);
switch (e.key) {
@@ -615,6 +617,7 @@ export const Calendar: React.FC = ({
const handleMonthKeyDown = useCallback(
(e: React.KeyboardEvent) => {
+ if (isPopoverToggleKey(e)) return;
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault();
if (!isMonthUnselectable(focusedDate)) {
@@ -789,6 +792,7 @@ export const Calendar: React.FC = ({
const handleYearListKeyDown = useCallback(
(e: React.KeyboardEvent) => {
+ if (isPopoverToggleKey(e)) return;
if (isYearGranularity) {
const step = yearStep(e.key, focusedYear, yearList);
if (!step) return;
diff --git a/bulma-ui/src/form/_pickerInternals/PickerPopover.tsx b/bulma-ui/src/form/_pickerInternals/PickerPopover.tsx
index 8d33d3a59..d073bd7b7 100644
--- a/bulma-ui/src/form/_pickerInternals/PickerPopover.tsx
+++ b/bulma-ui/src/form/_pickerInternals/PickerPopover.tsx
@@ -18,6 +18,7 @@ export interface PickerPopoverProps {
className?: string;
trapFocus?: boolean;
closeOnClickOutside?: boolean;
+ /** Close on Escape and on Alt+ArrowUp. Default `true`. */
closeOnEscape?: boolean;
ariaLabel?: string;
ariaLabelledBy?: string;
@@ -102,12 +103,18 @@ export const PickerPopover: React.FC = ({
return () => document.removeEventListener('pointerdown', handler);
}, [isOpen, closeOnClickOutside, anchorRef, onClose]);
+ // Escape closes it, and so does Alt+ArrowUp, the combobox's key for it,
+ // which the calendar and the time wheels inside leave to it.
useEffect(() => {
if (!isOpen || !closeOnEscape || !isBrowser) return undefined;
const handler = (e: KeyboardEvent) => {
if (e.key === 'Escape') {
e.stopPropagation();
onClose();
+ } else if (e.altKey && e.key === 'ArrowUp') {
+ e.preventDefault();
+ e.stopPropagation();
+ onClose();
}
};
document.addEventListener('keydown', handler);
diff --git a/bulma-ui/src/form/_pickerInternals/TimeWheels.tsx b/bulma-ui/src/form/_pickerInternals/TimeWheels.tsx
index 7d73c2d3e..37a021eeb 100644
--- a/bulma-ui/src/form/_pickerInternals/TimeWheels.tsx
+++ b/bulma-ui/src/form/_pickerInternals/TimeWheels.tsx
@@ -21,7 +21,12 @@ import {
usePrefixedClassNames,
} from '../../helpers/classNames';
import { useConfig } from '../../helpers/Config';
-import { HourFormat, PickerLabels, mergeLabels } from './pickerTypes';
+import {
+ HourFormat,
+ PickerLabels,
+ isPopoverToggleKey,
+ mergeLabels,
+} from './pickerTypes';
import { setTimeOfDay } from './dateUtils';
import { tickHaptic as fireTickHaptic } from './haptics';
import { playAudioTick, unlockAudioTick } from './audioTick';
@@ -394,24 +399,28 @@ const WheelInner = (
[disabled, cancelRaf, commitPosition]
);
+ // The keys are a spinbutton's: up raises the value and down lowers it. The
+ // values run down the wheel, so up brings the one below the band into it,
+ // the way a drag or a scroll that moves the items up does.
const onKeyDown = useCallback(
(e: React.KeyboardEvent) => {
+ if (isPopoverToggleKey(e)) return;
switch (e.key) {
case 'ArrowUp':
e.preventDefault();
- moveBy(-1);
+ moveBy(1);
break;
case 'ArrowDown':
e.preventDefault();
- moveBy(1);
+ moveBy(-1);
break;
case 'PageUp':
e.preventDefault();
- moveBy(-5);
+ moveBy(5);
break;
case 'PageDown':
e.preventDefault();
- moveBy(5);
+ moveBy(-5);
break;
case 'Home':
e.preventDefault();
@@ -799,6 +808,7 @@ export const TimeWheels: React.FC = ({
hours: h,
minutes: m,
seconds: s,
+ milliseconds: 0,
});
return !unselectableTimes(probe);
},
diff --git a/bulma-ui/src/form/_pickerInternals/dateUtils.ts b/bulma-ui/src/form/_pickerInternals/dateUtils.ts
index 44c023452..615ffbf71 100644
--- a/bulma-ui/src/form/_pickerInternals/dateUtils.ts
+++ b/bulma-ui/src/form/_pickerInternals/dateUtils.ts
@@ -240,14 +240,26 @@ export function addSeconds(d: Date, n: number): Date {
return r;
}
+/**
+ * A copy of `d` with the given parts of its time of day set and the rest
+ * left as they are. A time started from the clock rather than from a value
+ * should pass the seconds its picker does not show, and the milliseconds,
+ * as `0`, or it keeps the ones the clock had.
+ */
export function setTimeOfDay(
d: Date,
- parts: { hours?: number; minutes?: number; seconds?: number }
+ parts: {
+ hours?: number;
+ minutes?: number;
+ seconds?: number;
+ milliseconds?: number;
+ }
): Date {
const r = new Date(d);
if (parts.hours !== undefined) r.setHours(parts.hours);
if (parts.minutes !== undefined) r.setMinutes(parts.minutes);
if (parts.seconds !== undefined) r.setSeconds(parts.seconds);
+ if (parts.milliseconds !== undefined) r.setMilliseconds(parts.milliseconds);
return r;
}
diff --git a/bulma-ui/src/form/_pickerInternals/pickerTypes.ts b/bulma-ui/src/form/_pickerInternals/pickerTypes.ts
index e06a2e56b..3aec3294a 100644
--- a/bulma-ui/src/form/_pickerInternals/pickerTypes.ts
+++ b/bulma-ui/src/form/_pickerInternals/pickerTypes.ts
@@ -5,6 +5,16 @@ export type HourFormat = '12' | '24';
export type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * Whether a key is Alt+ArrowDown or Alt+ArrowUp, which open and close a
+ * picker's popover. The calendar and the time wheels leave both to it rather
+ * than reading them as plain arrows.
+ */
+export const isPopoverToggleKey = (e: {
+ altKey: boolean;
+ key: string;
+}): boolean => e.altKey && (e.key === 'ArrowDown' || e.key === 'ArrowUp');
+
/** The unit a date picker selects: a day, a month or a year. */
export type DateGranularity = 'day' | 'month' | 'year';
diff --git a/bulma-ui/src/form/_pickerInternals/useSegmentedEntry.ts b/bulma-ui/src/form/_pickerInternals/useSegmentedEntry.ts
index 39eba5d19..e424783d3 100644
--- a/bulma-ui/src/form/_pickerInternals/useSegmentedEntry.ts
+++ b/bulma-ui/src/form/_pickerInternals/useSegmentedEntry.ts
@@ -79,15 +79,15 @@ export interface UseSegmentedEntryParams {
readOnly?: boolean;
/** Allow segmented typing. When false, segment mode never engages. */
editable?: boolean;
- /** Whether a popover exists; gates open-on-focus / click / ArrowDown. */
+ /** Whether a popover exists; gates open-on-focus / click / Alt+ArrowDown. */
popover?: boolean;
openOnFocus?: boolean;
closeOnSelect?: boolean;
isOpen: boolean;
/**
* The host's open-state setter. The hook asks it to open on focus, click
- * or ArrowDown, but not on the focus the popover's focus trap hands back
- * to the input as it closes, which is not the user arriving.
+ * or Alt+ArrowDown, but not on the focus the popover's focus trap hands
+ * back to the input as it closes, which is not the user arriving.
*/
setOpen: (next: boolean) => void;
inputRef: React.RefObject;
@@ -386,7 +386,7 @@ export function useSegmentedEntry(
// Clicking the field opens the popover only when `openOnFocus` is on —
// a click is just a focus. With `openOnFocus={false}` (manual-entry
// mode) the click positions the caret for typing and the popover is
- // opened explicitly via the right launcher button (or ArrowDown).
+ // opened explicitly via the right launcher button (or Alt+ArrowDown).
if (openOnFocus && popover && !disabled && !readOnly) setOpen(true);
if (segmentEditable && segmentMap && inputRef.current) {
const caret = inputRef.current.selectionStart ?? 0;
@@ -427,14 +427,28 @@ export function useSegmentedEntry(
const isPm = base.getHours() >= 12;
switch (e.key) {
case 'ArrowUp':
- e.preventDefault();
- typedDigitsRef.current = '';
- applyDateFromSegment(incrementSegmentValue(seg, base, 1, isPm));
- return;
case 'ArrowDown':
e.preventDefault();
+ // The plain arrows step the segment, so the popover opens on
+ // Alt+ArrowDown and closes on Alt+ArrowUp, as a combobox's does,
+ // and neither steps it.
+ if (e.altKey) {
+ if (e.key === 'ArrowUp') {
+ if (isOpen) setOpen(false);
+ } else if (!isOpen && popover) {
+ setOpen(true);
+ }
+ return;
+ }
typedDigitsRef.current = '';
- applyDateFromSegment(incrementSegmentValue(seg, base, -1, isPm));
+ applyDateFromSegment(
+ incrementSegmentValue(
+ seg,
+ base,
+ e.key === 'ArrowUp' ? 1 : -1,
+ isPm
+ )
+ );
return;
case 'ArrowRight':
e.preventDefault();
@@ -514,11 +528,25 @@ export function useSegmentedEntry(
}
}
// ----- free-form / popover key handling -----
- if (e.key === 'ArrowDown' && !isOpen && popover) {
+ // With no segment to step, ArrowDown opens the popover with or without
+ // Alt, unless the field is read-only or disabled, as focus and the
+ // launcher don't open it then either. Alt+ArrowUp closes it.
+ if (
+ e.key === 'ArrowDown' &&
+ !isOpen &&
+ popover &&
+ !disabled &&
+ !readOnly
+ ) {
e.preventDefault();
setOpen(true);
return;
}
+ if (e.key === 'ArrowUp' && e.altKey && isOpen) {
+ e.preventDefault();
+ setOpen(false);
+ return;
+ }
if (e.key === 'Escape' && isOpen) {
e.preventDefault();
setOpen(false);
@@ -552,6 +580,8 @@ export function useSegmentedEntry(
setOpen,
closeOnSelect,
popover,
+ disabled,
+ readOnly,
isUntouched,
tryParse,
text,
diff --git a/docs/docs/api/form/datetime/dateinput.md b/docs/docs/api/form/datetime/dateinput.md
index 4c811ec41..ec3ec43ae 100644
--- a/docs/docs/api/form/datetime/dateinput.md
+++ b/docs/docs/api/form/datetime/dateinput.md
@@ -42,7 +42,7 @@ function example() {
}
```
-**Typing-first** — the same example with `openOnFocus={false}`: focusing or clicking the field lets you type; open the popover with the launcher icon (or press `↓`).
+**Typing-first** — the same example with `openOnFocus={false}`: focusing or clicking the field lets you type; open the popover with the launcher icon (or press `Alt+↓`).
```tsx live
function example() {
@@ -76,7 +76,7 @@ function example() {
}
```
-**Typing-first** — identical, but with `openOnFocus={false}` so focusing just lets you type; the calendar waits behind the launcher icon (or `↓`).
+**Typing-first** — identical, but with `openOnFocus={false}` so focusing just lets you type; the calendar waits behind the launcher icon (or `Alt+↓`).
```tsx live
function example() {
@@ -190,7 +190,7 @@ function example() {
On iOS Safari the calendar lets the user pick any date; `min`/`max` only fire at form-submission validation ([WebKit bug #225639](https://bugs.webkit.org/show_bug.cgi?id=225639), still open). Pass `mobileNative={false}` for iOS-side enforcement. Android Chrome's native picker does honor them.
:::
-**Typing-first** — the same bounds with `openOnFocus={false}`: every keystroke and `↑` / `↓` arrow is clamped to the range (out-of-range candidates are silently rejected), and the launcher icon (or `↓`) opens the calendar.
+**Typing-first** — the same bounds with `openOnFocus={false}`: every keystroke and `↑` / `↓` arrow is clamped to the range (out-of-range candidates are silently rejected), and the launcher icon (or `Alt+↓`) opens the calendar.
```tsx live
function example() {
@@ -227,7 +227,7 @@ Disable specific dates with `shouldDisableDate` (predicate) or `unselectableDate
HTML has no equivalent to `shouldDisableDate` or `unselectableDates`, so the OS-native pickers can't block any dates. This example forces `mobileNative={false}` so the rule works on touch devices too; in your app, keep the default `mobileNative="auto"` and also validate in `onChange`.
:::
-**Typing-first** — with `openOnFocus={false}` the predicate also vetoes manual entry: typing or arrowing to a weekend is rejected, and the calendar stays tucked behind the launcher icon (or `↓`).
+**Typing-first** — with `openOnFocus={false}` the predicate also vetoes manual entry: typing or arrowing to a weekend is rejected, and the calendar stays tucked behind the launcher icon (or `Alt+↓`).
```tsx live
function example() {
@@ -262,7 +262,7 @@ Use an alternative token format. Supported tokens: `YYYY YY MM M DD D HH H hh h
The OS-native pickers use the device's locale format and don't render `placeholder` text. This example forces `mobileNative={false}` so the format/placeholder show on touch devices too.
:::
-**Typing-first** — the same format with `openOnFocus={false}`: type day-first (typing `/` jumps to the next segment) and reach for the launcher icon (or `↓`) when you want the calendar.
+**Typing-first** — the same format with `openOnFocus={false}`: type day-first (typing `/` jumps to the next segment) and reach for the launcher icon (or `Alt+↓`) when you want the calendar.
```tsx live
function example() {
@@ -376,7 +376,7 @@ A clickable launcher sits on the **right** and toggles the popover — handy for
```
-**Typing-first** — the same group with `openOnFocus={false}`, where the launcher icon earns its keep; note that the `triggerIcon={false}` instance has no launcher, so its popover is keyboard-only (`↓`).
+**Typing-first** — the same group with `openOnFocus={false}`, where the launcher icon earns its keep; note that the `triggerIcon={false}` instance has no launcher, so its popover is keyboard-only (`Alt+↓`).
```tsx live
@@ -387,7 +387,7 @@ A clickable launcher sits on the **right** and toggles the popover — handy for
openOnFocus={false}
/>
@@ -593,7 +593,7 @@ Set `firstDayOfWeek` to align the grid to Monday-first locales.
The OS-native calendars use the device locale for the week start, so `firstDayOfWeek` (and `dayNames`/`monthNames`/`nearbyMonthDays`) are ignored there. This example forces `mobileNative={false}` so the Monday-first grid shows on touch devices too.
:::
-**Typing-first** — the same example with `openOnFocus={false}`: type freely, then open the Monday-first grid with the launcher icon (or `↓`).
+**Typing-first** — the same example with `openOnFocus={false}`: type freely, then open the Monday-first grid with the launcher icon (or `Alt+↓`).
```tsx live
```
-**Typing-first** — every size with `openOnFocus={false}` so focusing just lets you type; the launcher icon (or `↓`) opens the popover.
+**Typing-first** — every size with `openOnFocus={false}` so focusing just lets you type; the launcher icon (or `Alt+↓`) opens the popover.
```tsx live
@@ -686,7 +686,7 @@ If any of these matter, pass `mobileNative={false}` to force the custom calendar
```
-**Typing-first** — the same palette with `openOnFocus={false}`: click in to type, and use the launcher icon (or `↓`) for the calendar.
+**Typing-first** — the same palette with `openOnFocus={false}`: click in to type, and use the launcher icon (or `Alt+↓`) for the calendar.
```tsx live
@@ -747,7 +747,7 @@ function example() {
void` | — | Fired when the value changes. |
+| `onChange` | `(d: Date \| null) => void` | — | Fired when the value changes. A day picked in the calendar, by click or by key, arrives at local midnight. |
| `onOpen` | `() => void` | — | Fired when the popover opens. |
| `onClose` | `() => void` | — | Fired when the popover closes. |
| `min` | `Date` | — | Earliest selectable date. A `min` before year 1 is raised to 1 January of year 1, where the range starts without one too: HTML's date and month inputs hold no earlier year, so the calendar and typing stop there. |
@@ -1009,7 +1012,7 @@ Use `inline` instead of the popover when you have vertical room to spare — boo
| `mobileNative` | `boolean` \| `'auto'` | `'auto'` | Use ``s on coarse-pointer, small-viewport devices (`'auto'`), always (`true`) or never (`false`). The end input's `min` follows the start, and a change goes through the same rules as typing. |
| `editable` | `boolean` | `true` | Allow segmented keyboard typing in both inputs. `false` makes the field picker-only. |
| `popover` | `boolean` | `true` | Whether the calendar popover exists. `false` makes the field input-only. |
-| `openOnFocus` | `boolean` | `true` | Open the popover when focus arrives in the field. Moving focus between the two inputs, or back from the launcher, leaves it closed, and so does the focus a closing popover hands back. A click on either input opens it. |
+| `openOnFocus` | `boolean` | `true` | Open the popover when focus arrives in the field. Moving focus between the two inputs, or back from the launcher, leaves it closed, and so does the focus a closing popover hands back. A click on either input opens it. With it off, the launcher or Alt+ArrowDown opens it. |
| `closeOnSelect` | `boolean` | `true` | Close the popover once the range is picked. The first pick, which only marks the start, never closes it. |
| `position` | `'bottom-left'` \| `'bottom-right'` \| `'top-left'` \| `'top-right'` \| `'auto'` | `'bottom-left'` | Popover anchor position relative to the field. |
| `appendToBody` | `boolean` | `false` | Render the popover into `document.body` via portal. |
diff --git a/docs/docs/api/form/datetime/datetimeinput.md b/docs/docs/api/form/datetime/datetimeinput.md
index 9a1cfde4f..e9b004bc4 100644
--- a/docs/docs/api/form/datetime/datetimeinput.md
+++ b/docs/docs/api/form/datetime/datetimeinput.md
@@ -40,7 +40,7 @@ The popover opens to the calendar with an iOS-style footer — the selected time
```
-**Typing-first** — the same group with `openOnFocus={false}` on every instance, so clicking a field just lets you type and the launcher icon opens the popover; note the `triggerIcon={false}` instance has no launcher, leaving its popover keyboard-only via `↓`.
+**Typing-first** — the same group with `openOnFocus={false}` on every instance, so clicking a field just lets you type and the launcher icon opens the popover; note the `triggerIcon={false}` instance has no launcher, leaving its popover keyboard-only via `Alt+↓`.
```tsx live
@@ -276,7 +276,7 @@ A clickable launcher sits on the **right** and toggles the popover — handy for
openOnFocus={false}
/>
@@ -533,7 +533,7 @@ The OS-native pickers always use the device's system locale, so these examples s
```
-**Typing-first** — every size with `openOnFocus={false}`: clicking any field lets you type straight away, with the launcher icon (or `↓`) opening the popover.
+**Typing-first** — every size with `openOnFocus={false}`: clicking any field lets you type straight away, with the launcher icon (or `Alt+↓`) opening the popover.
```tsx live
@@ -573,7 +573,7 @@ The OS-native pickers always use the device's system locale, so these examples s
```
-**Typing-first** — the same colors with `openOnFocus={false}` on every instance: type directly in any field and open the popover with the launcher icon (or `↓`).
+**Typing-first** — the same colors with `openOnFocus={false}` on every instance: type directly in any field and open the popover with the launcher icon (or `Alt+↓`).
```tsx live
@@ -664,7 +664,7 @@ The single input spans the whole date-time: year → month → day → hours →
These examples use `openOnFocus={false}` so the popover doesn't cover the input.
:::tip Opening the picker vs. typing
-With `openOnFocus={false}` (used here), **clicking the field just lets you type** — the popover does not appear on focus or click. Open the picker by clicking the **launcher icon on the right** (or pressing `↓`). With the default `openOnFocus={true}`, focusing or clicking the field opens the popover immediately (you can still type while it's open).
+With `openOnFocus={false}` (used here), **clicking the field just lets you type** — the popover does not appear on focus or click. Open the picker by clicking the **launcher icon on the right** (or pressing `Alt+↓`). With the default `openOnFocus={true}`, focusing or clicking the field opens the popover immediately (you can still type while it's open).
:::
#### Basic
@@ -757,6 +757,7 @@ A single field spans year → month → day → hours → minutes (→ seconds
| Key | Action |
| --------------------------------- | ------------------------------------------------------------------------------ |
| `↑` / `↓` | Increment / decrement the active segment (wraps in place) |
+| `Alt+↓` / `Alt+↑` | Open / close the popover, leaving the segment as it is |
| `←` / `→` | Move to previous / next segment |
| `0`–`9` | Overwrite the active segment; auto-advances when no further digit is valid |
| `a` / `A` / `p` / `P` | Toggle AM/PM on the meridiem segment (12-hour formats) |
@@ -765,12 +766,13 @@ A single field spans year → month → day → hours → minutes (→ seconds
| `Tab` | Clear segment selection so focus moves out naturally |
| `Escape` | Close the popover |
+In free-form entry there is no segment to step, so a plain `↓` opens the popover as well.
+
### On the popover
| Key | Action |
| --------------------- | ----------------------------------------------- |
-| `↓` | Open popover (when closed) |
-| `Escape` | Close popover |
+| `Escape` / `Alt+↑` | Close popover |
| `←` / `→` | Move focused date by ±1 day |
| `↑` / `↓` | Move focused date by ±7 days |
| `PageUp` / `PageDown` | Move focused date by ±1 month |
@@ -781,7 +783,7 @@ A single field spans year → month → day → hours → minutes (→ seconds
Clicking the month and year in the calendar's header opens the year list to jump to another year. There `←` / `→` move focus by a year, `↑` / `↓` by a row, `Home` / `End` go to the list's ends, and `Enter` / `Space` jump to the focused year. The calendar stays on its month until a year is picked, and `Escape` goes back to it without jumping (a second `Escape` closes the popover).
-Activate the footer **time** button (`Enter` / `Space`) to float the wheels over the calendar. On a time wheel: `↑` / `↓` change the value, `←` / `→` move between the hours / minutes / (seconds) columns, and `Enter` commits and closes. While the wheels are open, `Escape` collapses them (a second `Escape` closes the popover), and clicking anywhere outside the wheel card dismisses them.
+Activate the footer **time** button (`Enter` / `Space`) to float the wheels over the calendar, with focus on the hours wheel. On a time wheel: `↑` / `↓` raise / lower the value, `PageUp` / `PageDown` by 5, `Home` / `End` jump to the lowest / highest, `←` / `→` move between the hours / minutes / (seconds) columns, and `Enter` commits and closes. While the wheels are open, `Escape` collapses them (a second `Escape` closes the popover), and clicking anywhere outside the wheel card dismisses them. The calendar under the wheels is out of reach while they are open, so `Tab` walks the wheels and the footer. Closing them puts focus back on the time button, unless you had moved it on to Reset or ✓, where it stays.
---
@@ -827,7 +829,7 @@ function DateTimeInputFormDemo() {
- Roving `tabindex` keeps a single day focusable at a time, and focus moves with it, inline as in the popover. When the focused date is disabled, that cell is the nearest enabled day of the month.
- Each time wheel uses `role="spinbutton"` with `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, and `aria-valuetext`.
- The footer's confirm button exposes an accessible label (`Done`); the Reset button reverts your edits to the value the popover opened with.
-- Tab order naturally walks from calendar → time wheels → footer (Reset / ✓).
+- Tab order walks from the calendar to the footer (Reset / ✓), and from the time wheels to the footer while they are open.
---
@@ -878,7 +880,7 @@ The DateTimeInput prop set is the union of [DateInput](./dateinput.md) and [Time
| `controlClassName` | `string` | — | Additional CSS classes for the Control wrapper. |
| `value` | `Date` \| `null` | — | Controlled selected date-time. |
| `defaultValue` | `Date` \| `null` | — | Initial value for uncontrolled usage. |
-| `onChange` | `(d: Date \| null) => void` | — | Fired when either the date or time portion changes. |
+| `onChange` | `(d: Date \| null) => void` | — | Fired when either the date or time portion changes. Picking a day keeps the value's whole time of day, down to seconds and milliseconds the field doesn't show, and `min` and `max` judge the picked day at that time. An empty field's day is picked at midnight. |
| `onOpen` | `() => void` | — | Fired when the popover opens. |
| `onClose` | `() => void` | — | Fired when the popover closes. |
| `min` | `Date` | — | Lower bound for the combined date-time. A `min` before year 1 is raised to midnight on 1 January of year 1, where the range starts without one too: HTML's datetime-local input holds no earlier year, so the calendar, the time wheels and typing stop there. |
@@ -893,7 +895,7 @@ The DateTimeInput prop set is the union of [DateInput](./dateinput.md) and [Time
| `mobileNative` | `boolean` \| `'auto'` | `'auto'` | Use `
```
-**Typing-first** — the same set with `openOnFocus={false}` on each instance: the field is type-first, which makes the right launcher icon (or `↓`) the way into the popover.
+**Typing-first** — the same set with `openOnFocus={false}` on each instance: the field is type-first, which makes the right launcher icon (or `Alt+↓`) the way into the popover.
```tsx live
@@ -734,7 +734,7 @@ A clickable launcher sits on the **right** and toggles the popover — handy for
openOnFocus={false}
/>
```
-**Typing-first** — the same sizes with `openOnFocus={false}` on every instance: focusing lets you type, and the launcher icon (or `↓`) opens the popover.
+**Typing-first** — the same sizes with `openOnFocus={false}` on every instance: focusing lets you type, and the launcher icon (or `Alt+↓`) opens the popover.
```tsx live
@@ -805,7 +805,7 @@ The launcher gives way to a loading spinner at the same right edge, whether the
```
-**Typing-first** — the same colors with `openOnFocus={false}` everywhere: click in to type, and use the launcher icon (or `↓`) to open the popover.
+**Typing-first** — the same colors with `openOnFocus={false}` everywhere: click in to type, and use the launcher icon (or `Alt+↓`) to open the popover.
```tsx live
@@ -912,6 +912,7 @@ Focus the input — the **hours** segment is automatically highlighted. Segment
| Key | Action |
| --------------------- | ------------------------------------------------------------------------------ |
| `↑` / `↓` | Increment / decrement the active segment (wraps at boundaries) |
+| `Alt+↓` / `Alt+↑` | Open / close the popover, leaving the segment as it is |
| `←` / `→` | Move to previous / next segment (hour ↔ minute ↔ second ↔ AM/PM) |
| `0`–`9` | Overwrite the active segment; auto-advances when no further digit is valid |
| `a` / `A` / `p` / `P` | Toggle AM/PM on the meridiem segment |
@@ -920,14 +921,21 @@ Focus the input — the **hours** segment is automatically highlighted. Segment
| `Escape` | Close popover |
| `Enter` | Close popover when `closeOnSelect={true}` (value is already committed live) |
+In free-form entry there is no segment to step, so a plain `↓` opens the popover as well.
+
### On a wheel column (when the popover is open)
-| Key | Action |
-| --------------------- | ------------------------------------ |
-| `↑` / `↓` | Increment / decrement focused column |
-| `PageUp` / `PageDown` | Increment / decrement by 5× |
-| `Tab` | Move focus to next column |
-| `Enter` | Commit live value, close popover |
+| Key | Action |
+| --------------------- | ---------------------------------------- |
+| `↑` / `↓` | Increment / decrement focused column |
+| `PageUp` / `PageDown` | Increment / decrement by 5× |
+| `Home` / `End` | Jump to the column's lowest / highest |
+| `←` / `→` | Move focus to the previous / next column |
+| `Tab` | Move focus to next column |
+| `Enter` | Commit live value, close popover |
+| `Escape` / `Alt+↑` | Close popover |
+
+The values run down each wheel, so `↑` brings the value below the band into it, the way dragging the wheel up or scrolling down over it does.
---
@@ -1036,7 +1044,7 @@ Combine `incrementMinutes={5}` (or `15`/`30`) with `min` and `max` to build a ti
| `mobileNative` | `boolean` \| `'auto'` | `'auto'` | Use `