An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file DateTimeInput.tsx
* @input Uses React, Field, Calendar, NativeDateSegment, NativeTimeSegment, TouchDateTimeField, usePopover, useAnnounce, time parsing utilities, StyleX intrinsic flex layout
* @output Exports DateTimeInput component, DateTimeInputProps, and native picker type; cleared values keep the pointer Calendar controlled-empty
* @position Core implementation; consumed by index.ts, tested by DateTimeInput.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/DateTimeInput/NativeDateSegment.tsx (native date surface)
* - /packages/core/src/DateTimeInput/NativeTimeSegment.tsx (native time surface)
* - /packages/core/src/DateTimeInput/NativePickerSegments.test.tsx (native surface tests)
* - /packages/core/src/DateTimeInput/DateTimeInput.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/DateTimeInput/DateTimeInput.test.tsx (desktop tests for new/changed behavior)
* - /packages/core/src/DateTimeInput/DateTimeInputTouch.test.tsx (touch-surface tests)
* - /packages/core/src/DateTimeInput/index.ts (exports if types change)
* - /apps/storybook/stories/DateTimeInput.stories.tsx (storybook stories)
* - /packages/cli/assets/templates/blocks/components/DateTimeInput/ (showcase blocks)
*/
import {
useId,
useState,
useCallback,
useEffect,
useRef,
useMemo,
useOptimistic,
useTransition,
type FocusEvent,
type KeyboardEvent,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
import {
colorVars,
sizeVars,
radiusVars,
spacingVars,
typographyVars,
typeScaleVars,
fontWeightVars,
} from '../theme/tokens.stylex';
import {
Field,
InputClearButton,
type InputStatus,
inputWrapperStyles,
inputStatusBorderStyles,
inputStatusHoverShadowStyles,
inputStatusFocusWithinStyles,
} from '../Field';
import {Icon} from '../Icon';
import {VisuallyHidden} from '../VisuallyHidden';
import {Spinner} from '../Spinner';
import {
Calendar,
type ISODateString,
type CalendarHandle,
type DayOfWeek,
type DayOfWeekName,
} from '../Calendar';
import {useCalendarConstraints} from '../Calendar/hooks';
import {usePopover} from '../Popover';
import {
isFocusInsideOwnedLayer,
isPressInsideOwnedLayer,
noteOutsideDismissal,
useOutsidePress,
} from '../Layer/outsidePress';
import {useTooltip} from '../Tooltip';
import {useInputContainer} from '../hooks/useInputContainer';
import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {
type ISOTimeString,
parseISOTime,
formatISOTime,
isTimeInRange,
adjustTime,
isImeKeyEvent,
mergeProps,
isFocusDetached,
} from '../utils';
import {chainEventHandlers} from '../utils/chainEventHandlers';
import {joinAriaIDs} from '../utils/inputAria';
import type {CalendarSystem} from '../utils/calendarSystem';
import {isRenderable} from '../utils/isRenderable';
import {useTypedDateField} from '../DateInput/useTypedDate';
import {
useFieldInputStyling,
type FieldInputBaseProps,
} from '../Field/fieldParts';
import type {SizeValue} from '../utils/types';
import {useAnnounce} from '../hooks/useAnnounce';
import {useMediaQuery} from '../hooks/useMediaQuery';
import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {useSize} from '../SizeContext/SizeContext';
import {themeProps} from '../utils/themeProps';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
import {useLocale} from '../i18n';
import {
formatLocaleTime,
parseLocaleTime,
resolveHourFormat,
} from '../utils/timeFormat';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {useHighlightedOptionScroll} from '../hooks/useHighlightedOptionScroll';
import {NativeDateSegment} from './NativeDateSegment';
import {NativeTimeSegment} from './NativeTimeSegment';
import {TouchDateTimeField} from './TouchDateTimeField';
import {
resolvePickerPresentation,
type PickerPresentation,
} from '../utils/inputPresentation';
import {useCalendarPresentation} from '../DateInput/useCalendarPresentation';
import {useDevWarning} from '../hooks/useDevWarning';
import {
registerEnglishFallback,
useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/DateTimeInput/DateTimeInput.generated';
registerEnglishFallback(english);
export type ISODateTimeString = string & {
readonly __brand: 'ISODateTimeString';
};
/** @deprecated Use {@link DateTimeInputPresentation} via the `presentation` prop. */
export type DateTimeInputNativePicker = 'touch' | 'always' | 'never';
/** Which surfaces collect the date and time (`spec:AST-043` FR1; no `text-input` — TimeInput-only). */
export type DateTimeInputPresentation = PickerPresentation;
export type DateTimeInputHourFormat = '12h' | '24h';
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,
} from '../Field';
// Two 196px segments plus the 8px gap fit at exactly 400px. Below that,
// flex wrapping moves each growing segment onto its own full-width row.
const HORIZONTAL_SEGMENT_BASIS = 196;
const styles = stylex.create({
row: {
display: 'flex',
flexWrap: 'wrap',
gap: spacingVars['--spacing-2'],
},
nativeRow: {
// Match DateInput's closed-field floor. Without one, WebKit reports almost
// no intrinsic width for appearance:none temporal inputs with overlays.
minInlineSize: 180,
},
iconButton: {
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
padding: 0,
margin: 0,
borderWidth: 0,
borderStyle: 'none',
backgroundColor: 'transparent',
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
borderRadius: radiusVars['--radius-element'],
},
iconButtonDisabled: {
cursor: 'default',
},
icon: {
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
flexShrink: 0,
},
input: {
display: 'block',
flex: 1,
minWidth: 0,
borderWidth: 0,
borderStyle: 'none',
padding: 0,
fontFamily: typographyVars['--font-family-body'],
// The 16px floor is iOS-only: iOS Safari zooms the page when a focused
// control sits under 16px, and only iOS WebKit implements
// -webkit-touch-callout to key the coarse-pointer floor to it.
fontSize: {
default: typeScaleVars['--text-body-size'],
'@media (pointer: coarse)': {
'@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
},
},
lineHeight: typeScaleVars['--text-body-leading'],
color: colorVars['--color-text-primary'],
backgroundColor: 'transparent',
outline: 'none',
'::placeholder': {
color: colorVars['--color-text-secondary'],
},
},
inputDisabled: {
cursor: 'default',
},
inputInvalid: {
color: colorVars['--color-text-secondary'],
},
dateWrapper: {
flex: 1,
flexBasis: HORIZONTAL_SEGMENT_BASIS,
minWidth: 0,
},
timeWrapper: {
flex: 1,
flexBasis: HORIZONTAL_SEGMENT_BASIS,
minWidth: 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 TOUCH_POINTER_QUERY = '(pointer: coarse)';
const sizeStyles = stylex.create({
sm: {
height: sizeVars['--size-element-sm'],
},
md: {
height: sizeVars['--size-element-md'],
},
lg: {
height: sizeVars['--size-element-lg'],
},
});
export interface DateTimeInputProps extends Omit<
FieldInputBaseProps<HTMLInputElement>,
'onChange' | 'defaultValue'
> {
/** Ref forwarded to the date input element */
ref?: React.Ref<HTMLInputElement>;
/**
* Label text for the input (required for accessibility).
*/
label: string;
/**
* Whether to visually hide the label (still accessible to screen readers).
* @default false
*/
isLabelHidden?: boolean;
/**
* Description text displayed between the label and input.
*/
description?: string;
/**
* Whether the field is optional. Mutually exclusive with isRequired.
* @default false
*/
isOptional?: boolean;
/**
* Whether the field is required. Mutually exclusive with isOptional.
* @default false
*/
isRequired?: boolean;
/**
* Whether the input is disabled.
* @default false
*/
isDisabled?: boolean;
/**
* Explains why the input is disabled. When set together with
* `isDisabled`, the input shows a tooltip with this text on hover and
* keyboard focus, and the date and time fields are described by it, so the
* reason is discoverable by keyboard and assistive technology. Typing and
* calendar activation stay blocked.
*
* Use this instead of wrapping a disabled input in `Tooltip`, so the
* reason is tied to the field.
*
* @example
* ```
* <DateTimeInput
* label="Meeting time"
* value={dateTime}
* onChange={setDateTime}
* isDisabled
* disabledMessage="You need the Editor role to change this"
* />
* ```
*/
disabledMessage?: string;
/**
* The selected datetime in ISO 8601 format ("YYYY-MM-DDTHH:MM" or "YYYY-MM-DDTHH:MM:SS").
*/
value?: ISODateTimeString | undefined;
/**
* Callback fired when the datetime changes.
* Called with undefined when input is cleared.
*/
onChange: (value: ISODateTimeString | undefined) => void;
/**
* Async action on change. Fires after onChange.
*/
changeAction?: (value: ISODateTimeString | undefined) => void | Promise<void>;
/**
* Whether the input is in a loading state.
* @default false
*/
isLoading?: boolean;
/**
* Minimum selectable datetime in ISO format.
* Constrains both date and time selection.
*/
min?: ISODateTimeString;
/**
* Maximum selectable datetime in ISO format.
* Constrains both date and time selection.
*/
max?: ISODateTimeString;
/**
* Custom date constraint functions.
* Date is disabled in the calendar if ANY function returns false.
*/
dateConstraints?: ReadonlyArray<(date: Date) => boolean>;
/**
* Whether to include seconds in the time portion.
* @default false
*/
hasSeconds?: boolean;
/**
* Hour display format: '12h' with the locale's day period, or '24h'.
* When unset, follows the `InternationalizationProvider` locale's hour
* cycle (`en-US` 12-hour, `en-GB` 24-hour); a per-user preference rides on
* the locale tag (`en-US-u-hc-h23`).
* @default the locale's hour cycle
*/
hourFormat?: DateTimeInputHourFormat;
/**
* Minute step for the time field. Astryx's typed field uses it for arrow-key
* stepping. The default value permits the native time picker; a non-default
* value retains the Astryx time field because iOS does not apply native
* `step` as picker cadence. Ignored by the Astryx touch sheet.
* @default 1
*/
timeIncrement?: DateTimeInputTimeIncrement;
/**
* Minute cadence for a dropdown of preset times on the desktop 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 desktop 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.
*
* Setting this prop retains Astryx's typed/combobox time field even when
* `nativePicker` otherwise selects native controls, because the OS picker has
* no equivalent preset list. The Astryx touch sheet uses wheels instead.
* Independent of `timeIncrement`, which governs arrow-key stepping.
*/
timeOptionInterval?: DateTimeInputTimeOptionInterval;
/**
* Whether to show a clear button when a value is set.
* @default false
*/
hasClear?: boolean;
/**
* Placeholder text shown in the date portion when no date is selected. A
* caller placeholder replaces the calendar format hint.
* @default "Select a date"
*/
placeholder?: string;
/**
* The calendar the date field reads and writes typed dates in, such as
* `'persian'`, `'hebrew'`, or `'buddhist'`. `value`, `onChange`, `min`, and
* `max` stay Gregorian ISO datetimes in every calendar. People type a date
* the way the locale writes it in this calendar, and the committed date
* text uses it. Years are years of this calendar, so set `min` and `max` to
* catch a year typed in the wrong calendar. Calendars other than `gregory`,
* `iso8601`, `buddhist`, `roc`, and `japanese` need `Temporal`, native or a
* polyfill the application loads; without it the field uses the Gregorian
* calendar.
*
* @default the InternationalizationProvider's calendar, else `'gregory'`
*/
calendar?: CalendarSystem;
/**
* Placeholder text shown in the time portion when no time is selected.
* On touch, this appears in the closed time segment before a time is chosen.
* @default "Select a time"
*/
timePlaceholder?: string;
/**
* Accessible label for the time portion of the field. Defaults to
* `"{label} time"` so it is tied to the field's own label and localizable,
* rather than a hardcoded English "Time".
*/
timeLabel?: string;
/**
* The size of the inputs.
* @default 'md'
*/
size?: DateTimeInputSize;
/**
* Status indicator for the input.
*/
status?: InputStatus;
/**
* Width of the field. Numbers are treated as pixels, strings are used as-is
* (e.g. `'100%'`). Sizes the whole field (label, control, and status) so they
* stay aligned, unlike setting width via `containerXstyle` or `controlXstyle`.
*/
width?: SizeValue;
/**
* Tooltip text to display in an info icon at the end of the label.
*/
labelTooltip?: string;
/**
* Number of months to display in the desktop calendar popover. Ignored on the
* mobile touch sheet, whose Date panel always shows one swipe-paged month at a
* time.
* @default 1
*/
numberOfMonths?: 1 | 2;
/**
* First day of week in the calendar. Accepts a number
* (0 = Sunday … 6 = Saturday) or a three-letter day name ('sun'–'sat',
* case-insensitive).
* @default 0
*/
weekStartsOn?: DayOfWeek | DayOfWeekName;
/**
* When date and time picking are handed to the browser/OS instead of Astryx's
* calendar and time surfaces.
*
* - `'touch'` (default): native date and time inputs on a coarse primary
* pointer; Astryx's typed fields and popovers otherwise
* - `'always'`: native date and time inputs wherever the browser supports them
* - `'never'`: Astryx's own surfaces everywhere — typed fields on a fine
* pointer and the coordinated Date/Time bottom sheet on a coarse pointer
*
* Native pickers cannot express `numberOfMonths`, `weekStartsOn`,
* `dateConstraints`, or `timeOptionInterval`. Calendar-only options are
* ignored in native mode and constraints are enforced on commit. The native
* time control is used for the default minute-precision contract; requesting
* `hasSeconds`, a non-default `timeIncrement`, or `timeOptionInterval` keeps
* Astryx's time field because iOS cannot represent those behaviors faithfully.
* `min` / `max` are forwarded to each native control as hints and enforced in
* JavaScript. `hourFormat` formats the closed value; the OS picker follows the
* user's locale.
*
* In a calendar other than `gregory` or `iso8601`, `'touch'` and `'always'`
* use Astryx's popovers on a fine pointer and the bottom sheet on a coarse
* pointer.
*
* @default 'touch'
* @deprecated Use `presentation` (`spec:AST-043` FR3):
* `'touch'` → `'adaptive-native'`, `'always'` → `'native'`,
* `'never'` → `'adaptive-bottom-sheet'`. Still works exactly as released;
* `presentation` wins when both are set.
*/
nativePicker?: DateTimeInputNativePicker;
/**
* Which surfaces collect the date and time (`spec:AST-043` FR1). Every
* value opens pickers; the typed-fields-only `'text-input'` belongs to
* `TimeInput`.
*
* - `'popover'`: Astryx's typed fields + popovers on every pointer
* - `'bottom-sheet'`: Astryx's bottom-sheet date/time wheels on every pointer
* - `'native'`: browser/OS date and time pickers on every pointer, with no
* Astryx fallback (FR2), except in a calendar other than `gregory` or
* `iso8601`, where it is `'adaptive-bottom-sheet'` and warns in
* development
* - `'adaptive-bottom-sheet'`: popovers on a fine pointer, bottom sheet on
* a coarse pointer
* - `'adaptive-native'` (default): popovers on a fine pointer, browser/OS
* pickers on a coarse pointer, keeping the released per-segment Astryx
* fallbacks (seconds, non-default `timeIncrement`, `timeOptionInterval`)
* where a native control cannot express the value (FR2), and the bottom
* sheet in a calendar other than `gregory` or `iso8601`
*
* @default 'adaptive-native'
*/
presentation?: DateTimeInputPresentation;
}
function splitDateTime(dt: ISODateTimeString | undefined): {
date: ISODateString | undefined;
time: ISOTimeString | undefined;
} {
if (!dt) {
return {date: undefined, time: undefined};
}
const tIndex = dt.indexOf('T');
if (tIndex === -1) {
return {date: dt as unknown as ISODateString, time: undefined};
}
return {
date: dt.slice(0, tIndex) as ISODateString,
time: dt.slice(tIndex + 1) as ISOTimeString,
};
}
function combineDateTime(
date: ISODateString | undefined,
time: ISOTimeString | undefined,
): ISODateTimeString | undefined {
if (!date || !time) {
return undefined;
}
return `${date}T${time}` as ISODateTimeString;
}
const MINUTES_PER_DAY = 24 * 60;
function getDefaultTime(hasSeconds: boolean): ISOTimeString {
const now = new Date();
return formatISOTime(
{hour: now.getHours(), minute: now.getMinutes(), second: now.getSeconds()},
hasSeconds,
);
}
/**
* A combined date and time picker with side-by-side date input and
* time input under a single label. The date input opens a calendar
* popover; the time input supports typed entry and arrow-key adjustment.
*
* @example
* ```
* <DateTimeInput
* label="Meeting time"
* value={dateTime}
* onChange={setDateTime}
* />
* ```
*/
function PointerDateTimeField({
label,
isLabelHidden = false,
description,
isOptional = false,
isRequired = false,
isDisabled = false,
disabledMessage,
value,
onChange,
changeAction,
isLoading = false,
min,
max,
dateConstraints,
hasSeconds = false,
hourFormat = '12h',
timeIncrement = 1,
timeOptionInterval,
hasClear = false,
placeholder: placeholderFromProps,
calendar,
timePlaceholder: timePlaceholderFromProps,
timeLabel,
size: sizeProp,
status,
labelTooltip,
numberOfMonths = 1,
weekStartsOn,
width,
containerXstyle,
containerClassName,
containerStyle,
controlXstyle,
controlClassName,
controlStyle,
ref,
nativeMode = 'off',
...restProps
}: DateTimeInputProps & {
nativeMode?: 'off' | 'adaptive' | 'forced' | 'legacy';
}) {
const {rest, container} = useFieldInputStyling('DateTimeInput', restProps, {
containerXstyle,
containerClassName,
containerStyle,
});
const {
id: idProp,
'aria-describedby': ariaDescribedByProp,
'aria-labelledby': ariaLabelledByProp,
onBlur: onBlurProp,
onClick: onClickProp,
onFocus: onFocusProp,
onKeyDown: onKeyDownProp,
...controlProps
} = rest;
const t = useComponentTranslator();
const locale = useLocale();
const usesNativePicker = nativeMode !== 'off';
// `forced` (`presentation="native"`, FR2): no Astryx fallback. `adaptive`
// (`adaptive-native` coarse) and `legacy` (deprecated `always`):
// iOS's native time picker has no seconds wheel, treats step as validation
// rather than picker cadence, and cannot express our preset-time list, so
// those keep the Astryx time field — exactly as released.
const usesNativeTimePicker =
nativeMode === 'forced' ||
((nativeMode === 'adaptive' || nativeMode === 'legacy') &&
!hasSeconds &&
timeIncrement === 1 &&
timeOptionInterval === undefined);
const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
// Speaks arrow-key stepping results through the persistent live regions:
// stepping programmatically rewrites a plain textbox's value, which screen
// readers do not announce on their own (WCAG 4.1.2).
const announce = useAnnounce();
const placeholder =
placeholderFromProps ?? t('@astryx.dateTimeInput.placeholder');
const timePlaceholder =
timePlaceholderFromProps ?? t('@astryx.dateTimeInput.timePlaceholder');
const size = useSize(sizeProp, 'md');
const generatedID = useId();
const dateInputId = idProp ?? generatedID;
const fieldLabelID = useId();
// A caller aria-labelledby names the date input together with the field's
// own label.
const controlLabelledBy =
ariaLabelledByProp != null
? joinAriaIDs(fieldLabelID, ariaLabelledByProp)
: undefined;
const timeInputId = useId();
const descriptionID = useId();
const statusMessageID = useId();
const calendarDescriptionID = useId();
const dateInputRef = useRef<HTMLInputElement | null>(null);
const mergedDateInputRef = useMergedRefs(ref, dateInputRef);
const timeInputRef = useRef<HTMLInputElement | null>(null);
const timeContainerRef = useRef<HTMLDivElement | null>(null);
const calendarRef = useRef<CalendarHandle | null>(null);
const [, startTransition] = useTransition();
const [optimisticValue, setOptimisticValue] = useOptimistic(value);
const isPendingChange = optimisticValue !== value;
const isBusy = isLoading || isPendingChange;
// The busy Spinner is decorative; this control announces its busy start
// (spec:AST-086 FR8).
useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), dateInputRef);
// A native wheel emits several edits while it remains open. Disabling the
// control after the first optimistic edit detaches the iOS picker, so pending
// changeAction work stays interactive just like TouchDateTimeField. Explicit
// loading still disables every surface.
const isEffectivelyDisabled =
isDisabled || isLoading || (!usesNativePicker && isPendingChange);
// Disabled-reason tooltip. Disabled controls swallow pointer events, so the
// tooltip listeners attach to the outer row container (which already exists)
// and both the date and time inputs stay perceivable via aria-disabled
// instead of the disabled attribute. Typing is blocked with readOnly and the
// value mutation guards; calendar activation is blocked by the
// isEffectivelyDisabled guards. Only the persistent isDisabled state (not the
// transient busy state) surfaces a reason.
const showsDisabledMessage = isDisabled && !!disabledMessage;
const disabledMessageTooltip = useTooltip({
placement: 'above',
// The container div is not naturally focusable; focusin bubbles up from
// the inputs, so always attach focus listeners.
focusTrigger: 'always',
isEnabled: showsDisabledMessage,
});
// Split min/max and current value
const minParts = useMemo(() => splitDateTime(min), [min]);
const maxParts = useMemo(() => splitDateTime(max), [max]);
const valueParts = useMemo(
() => splitDateTime(optimisticValue),
[optimisticValue],
);
// Date constraints from min/max
const calendarMin = minParts.date;
const calendarMax = maxParts.date;
const {isDateDisabled} = useCalendarConstraints({
min: calendarMin,
max: calendarMax,
dateConstraints,
});
// Time constraints change depending on selected date
const timeMin = useMemo(() => {
if (!minParts.date || !minParts.time || !valueParts.date) {
return undefined;
}
return valueParts.date === minParts.date ? minParts.time : undefined;
}, [minParts.date, minParts.time, valueParts.date]);
const timeMax = useMemo(() => {
if (!maxParts.date || !maxParts.time || !valueParts.date) {
return undefined;
}
return valueParts.date === maxParts.date ? maxParts.time : undefined;
}, [maxParts.date, maxParts.time, valueParts.date]);
// --- Time input state ---
const [timePendingInput, setTimePendingInput] = useState<string | null>(null);
const [isTimeFocused, setIsTimeFocused] = useState(false);
// Native date and time are separate OS pickers. Hold a time chosen before the
// date exists, then combine it when the date picker commits.
const [nativeTimeDraft, setNativeTimeDraft] = useState<
ISOTimeString | undefined
>(undefined);
const previousNativeValueRef = useRef(optimisticValue);
if (optimisticValue !== previousNativeValueRef.current) {
previousNativeValueRef.current = optimisticValue;
if (nativeTimeDraft !== undefined) {
setNativeTimeDraft(undefined);
}
}
const nativeTimeValue = nativeTimeDraft ?? valueParts.time;
const formatDisplayTime = useCallback(
(time: ISOTimeString, includeSeconds: boolean) =>
formatLocaleTime(time, locale, hourFormat, includeSeconds),
[locale, hourFormat],
);
const timeDisplayValue = useMemo(() => {
if (timePendingInput !== null) {
return timePendingInput;
}
return valueParts.time
? formatDisplayTime(valueParts.time, hasSeconds)
: '';
}, [timePendingInput, valueParts.time, formatDisplayTime, hasSeconds]);
const isTimeInputValid = useMemo(() => {
if (timePendingInput === null || !timePendingInput.trim()) {
return true;
}
const parsed = parseLocaleTime(timePendingInput, locale, hasSeconds);
if (!parsed) {
return false;
}
return isTimeInRange(parsed, timeMin, timeMax);
}, [timePendingInput, locale, hasSeconds, timeMin, timeMax]);
const resolvedTimePlaceholder = useMemo(() => {
if (isTimeFocused && !timeDisplayValue) {
return hourFormat === '12h'
? t('@astryx.dateTimeInput.timeHint12h')
: t('@astryx.dateTimeInput.timeHint24h');
}
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 =
!usesNativeTimePicker && timeOptionInterval !== undefined;
const timeOptions = useMemo(() => {
if (!hasTimeOptions || 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;
}, [
hasTimeOptions,
timeOptionInterval,
hasSeconds,
timeMin,
timeMax,
formatDisplayTime,
]);
// --- Unified change handler ---
const fireChange = useCallback(
(newValue: ISODateTimeString | undefined) => {
if (isEffectivelyDisabled) {
return;
}
onChange(newValue);
if (changeAction) {
startTransition(async () => {
setOptimisticValue(newValue);
await changeAction(newValue);
});
}
},
[
isEffectivelyDisabled,
onChange,
changeAction,
startTransition,
setOptimisticValue,
],
);
// --- Popover ---
const popover = usePopover({
dialogLabel: t('@astryx.dateTimeInput.dialogLabel'),
closeButtonLabel: t('@astryx.dateInput.closeCalendar'),
// Return focus to the date input when the calendar closes — but only when
// the dismiss left focus detached (Escape, or a click on non-focusable
// empty space), which the focus trap can't restore on its own. A native
// popover="auto" light-dismiss fires synchronously with the pointer event
// that moved focus, so if the user clicked another control — the time
// input, the clear button, another field, anywhere — focus has already
// landed there; reclaiming it would fight their click.
onHide: () => {
if (isFocusDetached()) {
dateInputRef.current?.focus();
}
},
});
const handleCalendarToggle = useCallback(() => {
if (!isEffectivelyDisabled) {
if (popover.isOpen) {
popover.hide();
} else {
popover.show();
}
}
}, [isEffectivelyDisabled, popover]);
const handleDateInputClick = useCallback(() => {
if (!isEffectivelyDisabled && !popover.isOpen) {
popover.show({skipAutoFocus: true});
}
}, [isEffectivelyDisabled, popover]);
// --- Date handlers ---
const handleDateChange = useCallback(
(newDate: ISODateString, source: 'calendar' | 'input') => {
const currentTime =
valueParts.time ?? nativeTimeDraft ?? getDefaultTime(hasSeconds);
let effectiveTime = currentTime;
if (minParts.date && newDate === minParts.date && minParts.time) {
if (!isTimeInRange(effectiveTime, minParts.time, undefined)) {
effectiveTime = minParts.time;
}
}
if (maxParts.date && newDate === maxParts.date && maxParts.time) {
if (!isTimeInRange(effectiveTime, undefined, maxParts.time)) {
effectiveTime = maxParts.time;
}
}
const combined = combineDateTime(newDate, effectiveTime);
if (combined) {
fireChange(combined);
}
if (source === 'calendar') {
popover.hide();
}
},
[
valueParts.time,
nativeTimeDraft,
hasSeconds,
minParts,
maxParts,
fireChange,
popover,
],
);
const handleTypedDateChange = useCallback(
(date: ISODateString) => handleDateChange(date, 'input'),
[handleDateChange],
);
const clearTypedDate = useCallback(() => {
if (value !== undefined) {
fireChange(undefined);
}
}, [value, fireChange]);
const navigateToTypedDate = useCallback((date: ISODateString) => {
calendarRef.current?.navigateTo(date);
}, []);
const {
typedDate,
displayValue: dateDisplayValue,
formatHint: dateFormatHint,
isPending: isDatePending,
isInvalid: isDateInvalid,
fieldStatus,
alertMessage: dateAlertMessage,
handleChange: handleTypedDateInput,
commit: commitDatePendingInput,
handleFocus: handleDateFocus,
handleBlur: handleDateBlur,
reset: resetTypedDate,
} = useTypedDateField({
source: 'DateTimeInput',
calendar,
format: 'date_long',
min: calendarMin,
max: calendarMax,
isDateDisabled,
value: splitDateTime(value).date,
shownValue: valueParts.date,
onChange: handleTypedDateChange,
onClear: clearTypedDate,
onTypedDate: navigateToTypedDate,
isDisabled: isEffectivelyDisabled,
status,
isStatusAnnounced: true,
hasPlaceholder: placeholderFromProps != null,
});
// The detached message box carries its own glyph, so the helper shows no
// on-field icon.
const {statusIcon, describedBy: statusTooltipDescribedBy} =
useInputStatusIcon({
status: fieldStatus,
statusVariant: 'detached',
});
const ariaDescribedBy =
[
description ? descriptionID : null,
!usesNativePicker && typedDate.calendarDescription != null
? calendarDescriptionID
: null,
fieldStatus?.message ? statusMessageID : null,
statusTooltipDescribedBy,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
ariaDescribedByProp,
]
.filter(Boolean)
.join(' ') || undefined;
const handleNativeDateChange = useCallback(
(newDate: ISODateString | undefined) => {
if (newDate === undefined) {
fireChange(undefined);
return;
}
handleDateChange(newDate, 'input');
},
[fireChange, handleDateChange],
);
const handleNativeTimeChange = useCallback(
(newTime: ISOTimeString | undefined) => {
if (newTime === undefined) {
setNativeTimeDraft(undefined);
if (optimisticValue !== undefined) {
fireChange(undefined);
}
return;
}
if (valueParts.date) {
const combined = combineDateTime(valueParts.date, newTime);
if (combined) {
fireChange(combined);
}
return;
}
// A datetime cannot be emitted until its date exists, but the OS time
// picker is independently reachable. Preserve this draft for the date
// commit instead of making the user's first choice disappear.
setNativeTimeDraft(newTime);
},
[fireChange, optimisticValue, valueParts.date],
);
const handleDateInputChange = useCallback(
(e: React.ChangeEvent<HTMLInputElement>) => {
handleTypedDateInput(e.target.value);
},
[handleTypedDateInput],
);
const handleDateKeyDown = useCallback(
(e: React.KeyboardEvent) => {
// Guard the composing keydown (fires before compositionend): an IME uses
// Enter to commit the candidate and Escape to cancel it, so without this
// a CJK user committing a syllable with Enter would commit the pending
// date instead. See utils/ime.ts.
if (isImeKeyEvent(e.nativeEvent)) {
return;
}
if (e.key === 'Escape' && popover.isOpen) {
e.preventDefault();
popover.hide();
} else if (
(e.key === 'ArrowDown' || (e.altKey && e.key === 'ArrowDown')) &&
!popover.isOpen
) {
// APG combobox: ArrowDown (and Alt+ArrowDown) opens the calendar
// popover from the keyboard, keeping focus in the input (forms-13).
e.preventDefault();
if (!isEffectivelyDisabled) {
popover.show({skipAutoFocus: true});
}
} else if (
e.key === 'Enter' &&
(isDatePending || isEffectivelyDisabled)
) {
// Typed text holds Enter back, or a form would submit the value from
// before the commit. A disabled or busy field must not submit its
// form either. Otherwise Enter keeps its default, as in any text field.
e.preventDefault();
commitDatePendingInput();
}
},
[popover, commitDatePendingInput, isEffectivelyDisabled, isDatePending],
);
// --- Time-option popover (#2727) ---
const timeListboxId = useId();
const [highlightedTimeIndex, setHighlightedTimeIndex] = useState(-1);
// Defer a show that happens during a press past that press's click, so the
// list's outside-press watch starts after the press ends and never judges
// it, as BaseTypeahead does.
const timePointerActiveRef = useRef(false);
// These one-shot `document` listeners belong to this field. Unmount removes
// them. Otherwise the next click runs work for a field that is gone.
const timeClickWatchersRef = useRef<Set<EventListener> | null>(null);
const addTimeClickWatcher = useCallback((handler: () => void) => {
const watchers = timeClickWatchersRef.current ?? new Set<EventListener>();
timeClickWatchersRef.current = watchers;
const watcher: EventListener = () => {
// The `once` option removes the listener from the document. Delete it from
// the set too, or the set keeps every past press.
watchers.delete(watcher);
handler();
};
watchers.add(watcher);
document.addEventListener('click', watcher, {once: true});
}, []);
const clearTimeClickWatchers = useCallback(() => {
for (const watcher of timeClickWatchersRef.current ?? []) {
document.removeEventListener('click', watcher);
}
timeClickWatchersRef.current?.clear();
}, []);
// The Effect owns this field's `document` click watchers: its setup acquires
// nothing, its cleanup releases whatever a press left pending.
useEffect(() => clearTimeClickWatchers, [clearTimeClickWatchers]);
// 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;
addTimeClickWatcher(() => {
timePointerActiveRef.current = false;
});
}, [addTimeClickWatcher]);
// The time list is a manual popover: the browser's light dismiss counts a
// press in the time input as outside (a text input cannot be an invoker), so
// a press in the field would close the list it just opened. A press on the
// time field or in the list is inside; a press anywhere else closes it
// (architecture:layer-runtime, component:BaseTypeahead FR12's rule).
const timeOutsidePress = useOutsidePress();
const timePopover = usePopover({
hasLightDismiss: false,
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',
onShow: () => {
const field = timeContainerRef.current;
if (field == null) {
return;
}
timeOutsidePress.start(
field,
path => isPressInsideOwnedLayer(path, field, timePopover.id),
// Called after usePopover has returned, so `timePopover` is assigned.
() => timePopover.hide(),
);
},
onHide: () => {
timeOutsidePress.stop();
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; hover highlights never scroll (#6077).
// Both sides live in useHighlightedOptionScroll.
const highlightTimeOnHover = useHighlightedOptionScroll({
isOpen: timePopover.isOpen,
highlightedIndex: activeTimeIndex,
setHighlightedIndex: setHighlightedTimeIndex,
getOptionId: timeOptionId,
itemCount: 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) {
addTimeClickWatcher(() =>
requestAnimationFrame(() => timePopover.show({skipAutoFocus: true})),
);
} else {
timePopover.show({skipAutoFocus: true});
}
}, [
addTimeClickWatcher,
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>) => {
// The input is never natively disabled (AST-085 FR1), so
// guard value mutation explicitly (readOnly also blocks typing).
if (isEffectivelyDisabled) {
return;
}
const text = e.target.value;
setTimePendingInput(text);
const parsed = parseLocaleTime(text, locale, 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) &&
parsed !== valueParts.time
) {
if (valueParts.date) {
const combined = combineDateTime(valueParts.date, parsed);
if (combined) {
fireChange(combined);
}
}
}
},
[
locale,
hasSeconds,
timeMin,
timeMax,
valueParts.time,
valueParts.date,
fireChange,
isEffectivelyDisabled,
timePopover.isOpen,
closestOptionIndex,
],
);
const handleTimeFocus = useCallback(() => {
// A disabled/busy input stays focusable (via aria-disabled) so its reason
// is discoverable, but it must not present editing affordances — keep the
// static placeholder rather than swapping in the format hint.
if (isEffectivelyDisabled) {
return;
}
setIsTimeFocused(true);
}, [isEffectivelyDisabled]);
const handleTimeBlur = useCallback(
(e: FocusEvent<HTMLInputElement>) => {
setIsTimeFocused(false);
// The outside-press watch only answers pointer presses and Escape stays
// on the layer stack, so a focus move that is neither — Tab handled
// elsewhere, or a programmatic focus — would strand the listbox open. Focus landing inside the
// field or the popup itself is not a leave. Mirrors BaseTypeahead.
if (
timePopover.isOpen &&
!isFocusInsideOwnedLayer(
e.relatedTarget,
timeContainerRef.current,
timePopover.id,
)
) {
noteOutsideDismissal(e.currentTarget.ownerDocument);
timePopover.hide();
}
if (timePendingInput === null) {
return;
}
if (!timePendingInput.trim()) {
// Empty time: revert display to previous value (don't emit partial datetime)
setTimePendingInput(null);
return;
}
const parsed = parseLocaleTime(timePendingInput, locale, 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,
locale,
hasSeconds,
timeMin,
timeMax,
valueParts,
fireChange,
timePopover,
],
);
const handleTimeKeyDown = useCallback(
(e: KeyboardEvent<HTMLInputElement>) => {
// ArrowUp/ArrowDown step the time and preventDefault; an IME candidate
// window uses those same arrows to navigate candidates, so guard the
// composing keydown (fires before compositionend) to avoid stealing them
// mid-composition. See utils/ime.ts.
// A disabled or busy field steps nothing, so it announces nothing (FR2).
if (isImeKeyEvent(e.nativeEvent) || isEffectivelyDisabled) {
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
? parseLocaleTime(timePendingInput, locale, 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();
let currentTime = valueParts.time;
if (!currentTime) {
const now = new Date();
currentTime = formatISOTime(
{
hour: now.getHours(),
minute: now.getMinutes(),
second: now.getSeconds(),
},
hasSeconds,
);
}
const delta = e.key === 'ArrowUp' ? timeIncrement : -timeIncrement;
const newTime = adjustTime(currentTime, delta, hasSeconds);
if (isTimeInRange(newTime, timeMin, timeMax) && valueParts.date) {
const combined = combineDateTime(valueParts.date, newTime);
if (combined) {
fireChange(combined);
// Screen readers do not announce the programmatic value rewrite,
// so speak the new time explicitly (WCAG 4.1.2).
announce(formatDisplayTime(newTime, hasSeconds));
}
}
}
},
[
valueParts,
locale,
hasSeconds,
timeIncrement,
timeMin,
timeMax,
fireChange,
announce,
formatDisplayTime,
hasTimeOptions,
isEffectivelyDisabled,
timePopover,
timeOptions,
activeTimeIndex,
timePendingInput,
showTimeOptions,
commitTimeOption,
],
);
// --- Clear ---
const handleClear = useCallback(
(e?: React.MouseEvent<HTMLButtonElement>) => {
setNativeTimeDraft(undefined);
fireChange(undefined);
if (!usesNativePicker) {
if (!e || e.detail === 0) {
dateInputRef.current?.focus();
} else {
// Defer focus restoration past the button's unmount task so iOS Safari
// and touch browsers don't jump the page scroll to 0 on tap.
requestAnimationFrame(() => {
dateInputRef.current?.focus({preventScroll: true});
});
}
}
},
[fireChange, usesNativePicker],
);
// Focus time input when clicking wrapper padding/icon
const {onClick: handleTimeWrapperClick, onMouseUp: handleTimeWrapperMouseUp} =
useInputContainer({
containerRef: timeContainerRef,
inputRef: timeInputRef,
disabled: isEffectivelyDisabled,
});
return (
<Field
{...container}
label={label}
isLabelHidden={isLabelHidden}
description={description}
inputID={dateInputId}
labelID={ariaLabelledByProp != null ? fieldLabelID : undefined}
descriptionID={description ? descriptionID : undefined}
isOptional={isOptional}
isRequired={isRequired}
isDisabled={isDisabled}
status={
fieldStatus
? {
type: fieldStatus.type,
message: fieldStatus.message,
messageID: fieldStatus.message ? statusMessageID : undefined,
}
: undefined
}
labelTooltip={labelTooltip}
statusVariant="detached"
width={width}>
<div
ref={disabledMessageTooltip.ref}
{...mergeProps(
themeProps('date-time-input', {
size,
status: fieldStatus?.type ?? null,
disabled: isDisabled ? 'disabled' : null,
}),
stylex.props(
styles.row,
usesNativePicker && styles.nativeRow,
controlXstyle,
),
controlClassName,
controlStyle,
)}>
{/* Date input */}
<div
ref={usesNativePicker ? undefined : popover.triggerRef}
{...mergeProps(
themeProps('date-time-input-date-segment', {
size,
status: fieldStatus?.type ?? null,
}),
stylex.props(
inputWrapperStyles.base,
inputWrapperStyles.textField,
sizeStyles[size],
styles.dateWrapper,
isEffectivelyDisabled && inputWrapperStyles.disabled,
isEffectivelyDisabled && inputDisabledFocusStyles.withinRing,
fieldStatus && inputStatusBorderStyles[fieldStatus.type],
fieldStatus &&
!isEffectivelyDisabled &&
inputStatusHoverShadowStyles[fieldStatus.type],
fieldStatus && inputStatusFocusWithinStyles[fieldStatus.type],
),
)}>
{usesNativePicker ? (
<NativeDateSegment
id={dateInputId}
inputRef={mergedDateInputRef}
value={valueParts.date}
onChange={handleNativeDateChange}
placeholder={placeholder}
min={calendarMin}
max={calendarMax}
isDateDisabled={isDateDisabled}
isEffectivelyDisabled={isEffectivelyDisabled}
isFocusableDisabled
isEffectivelyRequired={isEffectivelyRequired}
isBusy={isBusy}
statusType={status?.type}
ariaDescribedBy={ariaDescribedBy}
controlProps={{
...controlProps,
'aria-labelledby': controlLabelledBy,
onBlur: onBlurProp,
onFocus: onFocusProp,
onClick: isEffectivelyDisabled ? undefined : onClickProp,
onKeyDown: onKeyDownProp,
}}
/>
) : (
<>
<button
type="button"
onClick={handleCalendarToggle}
aria-disabled={isEffectivelyDisabled || undefined}
// A tab stop while disabled too, so it carries the reason (FR5).
aria-describedby={
showsDisabledMessage
? disabledMessageTooltip.describedBy
: undefined
}
aria-label={
popover.isOpen
? t('@astryx.dateInput.toggleCalendarClose')
: t('@astryx.dateInput.openCalendar')
}
{...stylex.props(
focusOutlineStyles.focusVisible,
styles.iconButton,
isEffectivelyDisabled && styles.iconButtonDisabled,
)}>
<Icon
icon="calendar"
size="sm"
color="secondary"
// Stable theme target on the calendar toggle glyph, so a theme
// can restyle just this icon (color, size, hover) — and each
// open/closed state — via `defineTheme`, mirroring
// `date-input-toggle-icon`. Same-element rules in
// @layer astryx-theme win over the icon's own base color/size,
// which a segment-level target could not reach.
{...themeProps('date-time-input-toggle-icon', {
state: popover.isOpen ? 'expanded' : 'collapsed',
})}
/>
</button>
<input
{...controlProps}
ref={mergedDateInputRef}
id={dateInputId}
type="text"
role="combobox"
value={dateDisplayValue}
onChange={handleDateInputChange}
onBlur={chainEventHandlers(handleDateBlur, onBlurProp)}
onFocus={chainEventHandlers(handleDateFocus, onFocusProp)}
onClick={
isEffectivelyDisabled
? undefined
: chainEventHandlers(handleDateInputClick, onClickProp)
}
onKeyDown={chainEventHandlers(handleDateKeyDown, onKeyDownProp)}
aria-labelledby={controlLabelledBy}
placeholder={dateFormatHint ?? placeholder}
aria-disabled={isEffectivelyDisabled ? 'true' : undefined}
readOnly={isEffectivelyDisabled || undefined}
aria-describedby={ariaDescribedBy}
aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={
fieldStatus?.type === 'error' || isDateInvalid
? 'true'
: undefined
}
aria-busy={isBusy || undefined}
aria-expanded={popover.isOpen}
aria-haspopup="dialog"
aria-controls={popover.isOpen ? popover.id : undefined}
aria-autocomplete="none"
autoComplete="off"
{...stylex.props(
styles.input,
isEffectivelyDisabled && styles.inputDisabled,
isDateInvalid && styles.inputInvalid,
)}
/>
{/*
Announces a typed date rejection that the field status does not
announce. The field status announces the rest.
*/}
<VisuallyHidden as="div" role="alert" aria-live="assertive">
{dateAlertMessage}
</VisuallyHidden>
{isRenderable(typedDate.calendarDescription) && (
<VisuallyHidden id={calendarDescriptionID}>
{typedDate.calendarDescription}
</VisuallyHidden>
)}
</>
)}
{hasClear && value !== undefined && !isEffectivelyDisabled && (
<InputClearButton
label={t('@astryx.dateInput.clear', {label})}
onClick={handleClear}
/>
)}
{isBusy && <Spinner size="sm" aria-hidden="true" />}
{statusIcon}
</div>
{/* Time input */}
<div
ref={timeContainerRef}
onClick={usesNativeTimePicker ? undefined : handleTimeWrapperClick}
onMouseUp={
usesNativeTimePicker ? undefined : 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.
onPointerDown={hasTimeOptions ? markTimePointerActive : undefined}
{...mergeProps(
themeProps('date-time-input-time-segment', {
size,
status: status?.type ?? null,
}),
stylex.props(
inputWrapperStyles.base,
inputWrapperStyles.textField,
sizeStyles[size],
styles.timeWrapper,
isEffectivelyDisabled && inputWrapperStyles.disabled,
isEffectivelyDisabled && inputDisabledFocusStyles.withinRing,
status && inputStatusBorderStyles[status.type],
status &&
!isEffectivelyDisabled &&
inputStatusHoverShadowStyles[status.type],
status && inputStatusFocusWithinStyles[status.type],
),
)}>
{usesNativeTimePicker ? (
<NativeTimeSegment
id={timeInputId}
inputRef={timeInputRef}
value={nativeTimeValue}
onChange={handleNativeTimeChange}
placeholder={timePlaceholder}
inputLabel={resolvedTimeLabel}
openPickerLabel={t('@astryx.dateTimeInput.openTimePicker', {
label: resolvedTimeLabel,
})}
iconThemeProps={themeProps('date-time-input-clock-icon')}
min={timeMin}
max={timeMax}
hourFormat={hourFormat}
isEffectivelyDisabled={isEffectivelyDisabled}
isFocusableDisabled
isEffectivelyRequired={isEffectivelyRequired}
isBusy={isBusy}
statusType={status?.type}
ariaDescribedBy={ariaDescribedBy}
/>
) : (
<>
<div {...stylex.props(styles.icon)}>
<Icon
icon="clock"
size="sm"
color="secondary"
// Stable theme target on the leading clock glyph, so a theme can
// restyle just this icon (color, size) via `defineTheme`. The
// time segment has no toggle button — the clock is a static
// leading affordance — so this carries no interactive state.
{...themeProps('date-time-input-clock-icon')}
/>
</div>
<input
ref={timeInputRef}
id={timeInputId}
type="text"
value={timeDisplayValue}
onChange={handleTimeInputChange}
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
}
aria-disabled={isEffectivelyDisabled ? 'true' : undefined}
readOnly={isEffectivelyDisabled || undefined}
aria-label={resolvedTimeLabel}
aria-describedby={ariaDescribedBy}
aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={
status?.type === 'error' || !isTimeInputValid
? 'true'
: undefined
}
aria-busy={isBusy || undefined}
{...stylex.props(
styles.input,
isEffectivelyDisabled && styles.inputDisabled,
!isTimeInputValid && styles.inputInvalid,
)}
/>
{/*
Live region announcing invalid typed time input to assistive
technology (WCAG 3.3.1).
*/}
<VisuallyHidden as="div" role="alert" aria-live="assertive">
{!isTimeInputValid ? t('@astryx.timeInput.invalidTime') : ''}
</VisuallyHidden>
</>
)}
</div>
</div>
{!usesNativePicker &&
popover.render(
// Mounted only while open, like the time list below; the calendar
// opens on the current value.
!popover.isOpen ? null : (
<Calendar
handleRef={calendarRef}
calendar={typedDate.calendar}
mode="single"
value={valueParts.date ?? null}
onChange={(d: ISODateString) => {
handleDateChange(d, 'calendar');
resetTypedDate();
}}
min={calendarMin}
max={calendarMax}
dateConstraints={dateConstraints}
numberOfMonths={numberOfMonths}
weekStartsOn={weekStartsOn}
/>
),
{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={() => highlightTimeOnHover(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>
);
}
PointerDateTimeField.displayName = 'PointerDateTimeField';
/**
* A combined date and time picker whose `presentation` prop chooses both
* surfaces (`spec:AST-043`). Native modes use OS-owned date and time controls
* in Astryx field chrome; the deprecated `nativePicker` maps to the same
* surfaces (FR3).
*
* Base props (`ref`, `id`, `data-*`, `aria-*`, DOM event handlers) go to the date input.
* A DOM handler runs after the component's own handler for the same event
* and still receives events the component handled, even ones it called
* `preventDefault` on, so it cannot cancel built-in behavior.
*/
export function DateTimeInput(props: DateTimeInputProps) {
const isTouch = useMediaQuery(TOUCH_POINTER_QUERY);
useDevWarning(
'DateTimeInput',
'`nativePicker` is deprecated; use `presentation` instead (`touch` → `adaptive-native`, `always` → `native`, `never` → `adaptive-bottom-sheet`). `presentation` wins when both are set.',
props.nativePicker !== undefined,
);
const {calendar, presentation: effective} = useCalendarPresentation(
'DateTimeInput',
props.calendar,
props.presentation,
props.nativePicker,
);
const locale = useLocale();
const {
presentation: _presentation,
nativePicker: _nativePicker,
...surfaceProps
} = props;
// Every surface gets the resolved hour format, so typed text, the native
// field's resting text, preset times, and the sheet wheels agree.
const rest = {
...surfaceProps,
calendar,
hourFormat: resolveHourFormat(locale, props.hourFormat),
};
if (effective === 'native') {
return (
<PointerDateTimeField
{...rest}
nativeMode={
props.presentation === undefined && props.nativePicker === 'always'
? 'legacy'
: 'forced'
}
/>
);
}
switch (resolvePickerPresentation(effective, isTouch)) {
case 'native':
// Only `adaptive-native` on a coarse pointer resolves here (FR2).
return <PointerDateTimeField {...rest} nativeMode="adaptive" />;
case 'sheet':
// Month indexes depend on the calendar. A new calendar remounts the sheet.
return <TouchDateTimeField key={calendar} {...rest} />;
case 'desktop':
return <PointerDateTimeField {...rest} />;
}
}
DateTimeInput.displayName = 'DateTimeInput';