An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file DateInput.tsx
* @input Uses React, useId, useCallback, useRef, useTypedDateField, Field, Icon, Calendar, usePopover, InputGroupContext
* @output Exports DateInput component, DateInputProps
* @position Core implementation; consumed by index.ts, tested by DateInput.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/DateInput/DateInput.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/DateInput/DateInput.test.tsx (tests for new/changed behavior)
* - /packages/core/src/DateInput/index.ts (exports if types change)
* - /apps/storybook/stories/DateInput.stories.tsx (storybook stories)
* - /packages/cli/assets/templates/blocks/components/DateInput/ (showcase blocks)
*/
import {
use,
useId,
useCallback,
useRef,
useOptimistic,
useTransition,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
import {
colorVars,
sizeVars,
radiusVars,
typographyVars,
typeScaleVars,
} from '../theme/tokens.stylex';
import {
Field,
InputClearButton,
type InputStatus,
inputWrapperStyles,
inputStatusBorderStyles,
inputStatusHoverShadowStyles,
inputStatusFocusWithinStyles,
} from '../Field';
import {Icon} from '../Icon';
import {VisuallyHidden} from '../VisuallyHidden';
import {useInputGroup} from '../InputGroup/InputGroupContext';
import {InputGroupInternalContext} from '../InputGroup/InputGroupInternalContext';
import {groupStyles, inputGroupItemProps} from '../InputGroup/groupStyles';
import {useSize} from '../SizeContext/SizeContext';
import {Spinner} from '../Spinner';
import {
Calendar,
type ISODateString,
type CalendarHandle,
type DayOfWeek,
type DayOfWeekName,
} from '../Calendar';
import {useCalendarConstraints} from '../Calendar/hooks';
import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
import {useMediaQuery} from '../hooks/useMediaQuery';
import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {usePopover} from '../Popover';
import {
isFocusInsideOwnedLayer,
isPressInsideOwnedLayer,
noteOutsideDismissal,
useOutsidePress,
} from '../Layer/outsidePress';
import {NativeDateField} from './NativeDateField';
import {TouchDateField} from './TouchDateField';
import {useTooltip} from '../Tooltip';
import {getInputARIA, isImeKeyEvent} from '../utils';
import {chainEventHandlers} from '../utils/chainEventHandlers';
import type {CalendarSystem} from '../utils/calendarSystem';
import {isRenderable} from '../utils/isRenderable';
import {useTypedDateField} from './useTypedDate';
import type {TimestampFormat} from '../Timestamp';
import {
resolvePickerPresentation,
type PickerPresentation,
} from '../utils/inputPresentation';
import {useCalendarPresentation} from './useCalendarPresentation';
import {useDevWarning} from '../hooks/useDevWarning';
const styles = stylex.create({
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',
},
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'],
},
});
const sizeStyles = stylex.create({
sm: {
height: sizeVars['--size-element-sm'],
minWidth: 180,
},
md: {
height: sizeVars['--size-element-md'],
minWidth: 180,
},
lg: {
height: sizeVars['--size-element-lg'],
minWidth: 180,
},
});
export type DateInputSize = keyof typeof sizeStyles;
/**
* Named display formats for a committed date value. These are the date-only
* members of Timestamp's `format` vocabulary — reused verbatim (via
* `Extract`) so the same literal renders the same date shape in both
* `Timestamp` and `DateInput`:
* - `'date'`: locale short-month date, e.g. "Mar 21, 2026"
* - `'date_long'`: locale long-month date, e.g. "March 21, 2026" (the default)
* - `'date_weekday'`: short weekday + date, e.g. "Wed, Mar 21, 2026"
* - `'system_date'`: ISO 8601 calendar date, e.g. "2026-03-21"
*
* Because `DateInputFormat` is `Extract`ed from `TimestampFormat`, the two
* types stay in compile-time lockstep: renaming or removing one of these
* members from `TimestampFormat` breaks this type at build time.
*/
/**
* When DateInput hands date picking to the browser/OS instead of its own
* surfaces.
*
* - `'touch'`: native on touch devices (coarse pointer), Astryx's calendar
* popover on mouse-driven ones
* - `'always'`: native wherever the browser supports `<input type="date">`
* - `'never'`: Astryx's own pickers everywhere
*/
/** @deprecated Use {@link DateInputPresentation} via the `presentation` prop. */
export type DateInputNativePicker = 'touch' | 'always' | 'never';
/** Which surface collects the date (`spec:AST-043` FR1; no `text-input` — TimeInput-only). */
export type DateInputPresentation = PickerPresentation;
export type DateInputFormat = Extract<
TimestampFormat,
'date' | 'date_long' | 'date_weekday' | 'system_date'
>;
// Re-export shared types for convenience
export type {
InputStatus as DateInputStatus,
InputStatusType as DateInputStatusType,
} from '../Field';
import {mergeProps, isFocusDetached} from '../utils';
import {joinAriaIDs} from '../utils/inputAria';
import {
useFieldInputStyling,
type FieldInputBaseProps,
} from '../Field/fieldParts';
import type {SizeValue} from '../utils/types';
import {themeProps} from '../utils/themeProps';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
import {useMergedRefs} from '../hooks/useMergedRefs';
import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
import {
registerEnglishFallback,
useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/DateInput/DateInput.generated';
registerEnglishFallback(english);
export interface DateInputProps extends Omit<
FieldInputBaseProps<HTMLInputElement>,
'onChange' | 'defaultValue'
> {
/** Ref forwarded to the date input (the field's semantic control) */
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 field shows a tooltip with this text on hover and
* keyboard focus, and the field's focusable controls 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
* ```
* <DateInput
* label="Event date"
* value={date}
* onChange={setDate}
* isDisabled
* disabledMessage="You need the Editor role to change this"
* />
* ```
*/
disabledMessage?: string;
/**
* The selected date in ISO format (YYYY-MM-DD).
*/
value?: ISODateString | undefined;
/**
* Callback fired when the date changes.
* Called with undefined when input is cleared.
*/
onChange?: (value: ISODateString | undefined) => void;
/**
* Async action on change. Fires after onChange.
*/
changeAction?: (value: ISODateString | undefined) => void | Promise<void>;
/**
* Whether the input is in a loading state. The field stays focusable and
* exposes `aria-busy` with a Spinner; typing, picking, and clearing are
* blocked until loading ends.
* @default false
*/
isLoading?: boolean;
/**
* Minimum selectable date in ISO format.
*/
min?: ISODateString;
/**
* Maximum selectable date in ISO format.
*/
max?: ISODateString;
/**
* Custom date constraint functions. Date is disabled if ANY function returns false.
*/
dateConstraints?: ReadonlyArray<(date: Date) => boolean>;
/**
* Placeholder text shown when no date is selected. A caller placeholder
* replaces the calendar format hint.
* @default "Select a date"
*/
placeholder?: string;
/**
* The size of the input. The field height follows the theme's element-size
* token for the chosen size (`--size-element-sm`, `--size-element-md`, or
* `--size-element-lg`).
* @default 'md'
*/
size?: DateInputSize;
/**
* Status indicator for the input.
* When set, displays a colored border and status icon.
* If message is provided, displays below the input.
*/
status?: InputStatus;
/**
* How the status message is placed relative to the input.
* - 'attached': message overlaps directly below the input (bordered treatment)
* - 'detached': message floats below as a separate element with spacing
* - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
* @default 'attached'
*/
statusVariant?: FieldStatusPlacement;
/**
* 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;
/**
* Whether to show a clear button when a date is set.
* When clicked, resets the value to undefined and returns focus to the input.
* @default false
*/
hasClear?: boolean;
/**
* Number of months to display in the calendar popover.
* @default 1
*/
numberOfMonths?: 1 | 2;
/**
* First day of week in the calendar popover. Accepts a number
* (0 = Sunday … 6 = Saturday) or a three-letter day name ('sun'–'sat',
* case-insensitive).
* @default 0
*/
weekStartsOn?: DayOfWeek | DayOfWeekName;
/**
* How the committed date value is displayed in the text field. Accepts a
* named format reused from `Timestamp`'s `format` vocabulary (so the same
* literal renders the same date shape in both components) or a function that
* maps the ISO value to a custom display string.
*
* - `'date_long'` (default): long-month date, e.g. "March 21, 2026"
* - `'date'`: short-month date, e.g. "Mar 21, 2026"
* - `'date_weekday'`: short weekday + date, e.g. "Wed, Mar 21, 2026"
* - `'system_date'`: ISO 8601 calendar date, e.g. "2026-03-21"
* - `(value: ISODateString) => string`: fully custom display string
*
* Formatting applies only to the committed value — never to text the user is
* actively typing. Named formats write the date in the field's `calendar`;
* `'system_date'` stays the Gregorian ISO date. A custom function's output
* that the field cannot read back can't be re-committed after an edit;
* external `value` changes always recompute the display from the ISO value.
*
* @default 'date_long'
* @example
* ```
* <DateInput label="Ship date" value={date} onChange={setDate} format="date" />
* <DateInput
* label="Ship date"
* value={date}
* onChange={setDate}
* format={iso => new Date(iso + 'T00:00').toDateString()}
* />
* ```
*/
format?: DateInputFormat | ((value: ISODateString) => string);
/**
* The calendar the field shows dates in, such as `'persian'`, `'hebrew'`, or
* `'buddhist'`: the text field, its calendar popover, and the bottom sheet's
* months and wheels. `value`, `onChange`, `min`, and `max` stay Gregorian
* ISO dates in every calendar. People type a date the way the locale writes
* it in this calendar, and the committed text uses it.
* Years are years of this calendar, so a Buddhist field reads `2026` as
* Buddhist year 2026; 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.
* The native date control is Gregorian, so with a calendar other than
* `gregory` or `iso8601` every presentation that would show it uses the
* popover on a fine pointer and the bottom sheet on a coarse pointer.
*
* @default the InternationalizationProvider's calendar, else `'gregory'`
* @example
* ```
* <DateInput label="Start date" calendar="persian" value={date} onChange={setDate} />
* ```
*/
calendar?: CalendarSystem;
/**
* When date picking is handed to the browser/OS instead of Astryx's own
* surfaces: the field becomes an `<input type="date">` and the platform
* draws the picker — the iOS wheel, the Android calendar dialog — with the
* OS's own hit areas, momentum scrolling, locale and accessibility
* settings.
*
* - `'touch'` (default): native on touch devices (coarse pointer), the text
* field and calendar popover on mouse-driven ones
* - `'always'`: native wherever the browser supports `<input type="date">`
* - `'never'`: Astryx's own pickers everywhere — the touch picker on a
* finger, the calendar popover on a mouse
*
* `format` and `placeholder` still apply in native mode: DateInput paints
* the closed field's text itself, over the control. `numberOfMonths` and
* `weekStartsOn` do not — they describe a calendar grid the native picker
* does not have — so a field that needs either should pass `'never'`.
*
* `min` and `max` are forwarded, but note that a native picker may not
* *show* them: on iOS they are constraint-validation flags rather than
* clamps, so an out-of-range date can be selected and is refused on commit
* (announced to assistive technology) rather than being greyed out in the
* picker. `dateConstraints` is enforced the same way, on commit, and is
* reason enough to prefer `'never'` on a field that uses it.
*
* In a calendar other than `gregory` or `iso8601`, `'touch'` and `'always'`
* use the calendar popover on a mouse and the touch picker on a finger.
*
* @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?: DateInputNativePicker;
/**
* Which surface collects the date (`spec:AST-043` FR1). Every value opens
* a picker; the typed-field-only `'text-input'` belongs to `TimeInput`.
*
* - `'popover'`: Astryx's typed field + calendar popover on every pointer
* - `'bottom-sheet'`: Astryx's bottom-sheet calendar on every pointer
* - `'native'`: the browser/OS picker 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'`: popover on a fine pointer, bottom sheet on
* a coarse pointer
* - `'adaptive-native'` (default): popover on a fine pointer, browser/OS
* picker on a coarse pointer, keeping the released Astryx fallbacks
* 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?: DateInputPresentation;
}
/**
* The pointer that decides which surface a `DateInput` renders.
*
* `pointer: coarse` is the *primary* pointing device, which is what makes it
* the whole test. A touchscreen laptop reports `fine` (its trackpad) with
* `any-pointer: coarse` alongside, so it keeps the typable field — right,
* because its keyboard is there. A tablet reports `coarse` and gets the
* picker, at any width. There is deliberately no width bound: it would only
* re-exclude the tablets, since a narrowed desktop window is still a mouse.
*
* Deliberately NOT exported. It was, briefly, on the theory that an app might
* want to ask the same question and lay out to match — but nothing asked, and
* six other core components (CheckboxInput, ChatComposerInput, ...) just
* write `@media (pointer: coarse)` inline rather than sharing a constant. An
* export is additive later and awkward to withdraw, so it waits for a real
* caller.
*/
const TOUCH_POINTER_QUERY = '(pointer: coarse)';
/**
* Whether `target` is a label whose control is `input`. Checked by nodeType
* and tag name, so a label in a same-origin iframe counts.
*/
function isLabelFor(target: EventTarget, input: HTMLInputElement | null) {
const node = target as Partial<HTMLLabelElement>;
return (
input != null &&
node.nodeType === 1 &&
node.localName === 'label' &&
node.control === input
);
}
/**
* The pointer-driven field: a text input you can type into, with a calendar
* in a popover beside it. `DateInput` renders this whenever the primary
* pointer is not a finger — see {@link TOUCH_POINTER_QUERY}.
*/
function PointerDateField({
label,
isLabelHidden = false,
description,
isOptional = false,
isRequired = false,
isDisabled = false,
disabledMessage,
value,
onChange,
changeAction,
isLoading = false,
min,
max,
dateConstraints,
placeholder: placeholderFromProps,
size: sizeProp,
status,
statusVariant = 'attached',
labelTooltip,
hasClear = false,
numberOfMonths = 1,
weekStartsOn,
format = 'date_long',
calendar,
width,
containerXstyle,
containerClassName,
containerStyle,
controlXstyle,
controlClassName,
controlStyle,
ref,
...restProps
}: DateInputProps) {
const {rest, container} = useFieldInputStyling('DateInput', 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 isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const placeholder =
placeholderFromProps ?? t('@astryx.dateInput.placeholder');
const size = useSize(sizeProp, 'md');
const generatedID = useId();
const id = idProp ?? generatedID;
const fieldLabelID = useId();
const inputLabelID = useId();
const descriptionID = useId();
const statusMessageID = useId();
const calendarDescriptionID = useId();
const inputRef = useRef<HTMLInputElement | null>(null);
const calendarRef = useRef<CalendarHandle | null>(null);
const inputGroup = useInputGroup();
const [, startTransition] = useTransition();
const [optimisticValue, setOptimisticValue] = useOptimistic(value);
const isBusy = isLoading || optimisticValue !== value;
// The busy Spinner is decorative; this control announces its busy start
// (spec:AST-086 FR8).
useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), inputRef);
const isEffectivelyDisabled = isDisabled || isBusy;
// A disabled or busy field never renders native `disabled` (spec:AST-085
// FR1): the input and calendar button stay focusable via aria-disabled.
// Typing is blocked with readOnly and value mutation guards; calendar
// activation is blocked by the isEffectivelyDisabled guards. The
// disabled-reason tooltip's listeners attach to the input container. 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 input, so always attach focus listeners.
focusTrigger: 'always',
isEnabled: showsDisabledMessage,
});
// Constraint checking for text input validation (reuses calendar logic)
const {isDateDisabled} = useCalendarConstraints({min, max, dateConstraints});
const fireChange = useCallback(
(newValue: ISODateString | undefined) => {
if (isEffectivelyDisabled) {
return;
}
onChange?.(newValue);
if (changeAction) {
startTransition(async () => {
setOptimisticValue(newValue);
await changeAction(newValue);
});
}
},
[
isEffectivelyDisabled,
onChange,
changeAction,
startTransition,
setOptimisticValue,
],
);
const clearTypedDate = useCallback(() => {
if (value !== undefined) {
fireChange(undefined);
}
}, [value, fireChange]);
const navigateToTypedDate = useCallback((date: ISODateString) => {
calendarRef.current?.navigateTo(date);
}, []);
const {
typedDate,
displayValue,
formatHint,
isPending,
isInvalid,
fieldStatus,
alertMessage,
handleChange: handleTypedChange,
commit: commitPendingInput,
handleFocus,
handleBlur,
reset: resetTypedInput,
} = useTypedDateField({
source: 'DateInput',
calendar,
format,
min,
max,
isDateDisabled,
value,
shownValue: optimisticValue,
onChange: fireChange,
onClear: clearTypedDate,
onTypedDate: navigateToTypedDate,
isDisabled: isEffectivelyDisabled,
status,
isStatusAnnounced: !inputGroup,
hasPlaceholder: placeholderFromProps != null,
});
const {statusIcon, describedBy: statusTooltipDescribedBy} =
useInputStatusIcon({
status: fieldStatus,
statusVariant,
isInGroup: !!inputGroup,
});
const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
inputLabelID,
[
description ? descriptionID : null,
typedDate.calendarDescription != null ? calendarDescriptionID : null,
statusVariant !== 'tooltip' && fieldStatus?.message
? statusMessageID
: null,
// The tooltip variant renders no message box; describe the input by the
// tooltip's content instead so the status is still announced.
statusTooltipDescribedBy,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
ariaDescribedByProp,
],
inputGroup,
);
const fieldElementRef = useRef<HTMLDivElement | null>(null);
// Set just before a close that focus already left the field for, so onHide
// does not pull focus back to the input.
const isFocusMovingAwayRef = useRef(false);
const outsidePress = useOutsidePress();
const popover = usePopover({
// A text input cannot be an invoker. Light dismiss would count a press in
// it as outside and close the calendar.
hasLightDismiss: false,
onShow: () => {
const field = fieldElementRef.current;
if (field == null) {
return;
}
outsidePress.start(
field,
// The label counts too: a press there focuses the input, which would
// otherwise close the calendar and reopen it on the same press.
path =>
isPressInsideOwnedLayer(path, field, popover.id) ||
path.some(target => isLabelFor(target, inputRef.current)),
// Called after usePopover has returned, so `popover` is assigned.
() => popover.hide(),
);
},
dialogLabel: t('@astryx.dateInput.dialogLabel'),
closeButtonLabel: t('@astryx.dateInput.closeCalendar'),
// Return focus to the 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. An outside press
// closes the calendar after the pointer event that moved focus, so if the
// user clicked another control — another field, anywhere — focus has
// already landed there; reclaiming it would fight their click.
onHide: () => {
outsidePress.stop();
const isFocusMovingAway = isFocusMovingAwayRef.current;
isFocusMovingAwayRef.current = false;
if (!isFocusMovingAway && isFocusDetached()) {
inputRef.current?.focus();
}
},
});
// Handle toggling the popover from button click (focus calendar)
const handleToggle = useCallback(() => {
if (!isEffectivelyDisabled) {
if (popover.isOpen) {
popover.hide();
} else {
popover.show();
}
}
}, [isEffectivelyDisabled, popover]);
// Handle opening the popover from input click (keep focus in input)
const handleInputClick = useCallback(() => {
if (!isEffectivelyDisabled && !popover.isOpen) {
popover.show({skipAutoFocus: true});
}
}, [isEffectivelyDisabled, popover]);
// Handle clear button click
const handleClear = useCallback(
(e?: React.MouseEvent<HTMLButtonElement>) => {
fireChange(undefined);
if (!e || e.detail === 0) {
inputRef.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(() => {
inputRef.current?.focus({preventScroll: true});
});
}
},
[fireChange],
);
// Handle date selection from calendar
const handleDateSelect = useCallback(
(selectedDate: ISODateString) => {
// An already-open calendar can outlive an enabled owner. Reject the
// whole selection, including dismissal, so its focused day stays put.
if (isDisabled) {
return;
}
fireChange(selectedDate);
resetTypedInput();
popover.hide();
},
[isDisabled, fireChange, resetTypedInput, popover],
);
const handleInputChange = useCallback(
(e: React.ChangeEvent<HTMLInputElement>) => {
handleTypedChange(e.target.value);
},
[handleTypedChange],
);
// A manual popover has no auto-popover exclusivity, so without this close
// the next field's calendar would open beside this one. Focus going nowhere
// (a window switch) leaves it open.
const handleFieldBlur = useCallback(
(e: React.FocusEvent<HTMLDivElement>) => {
const next = e.relatedTarget;
if (
!popover.isOpen ||
next == null ||
isFocusInsideOwnedLayer(next, fieldElementRef.current, popover.id)
) {
return;
}
isFocusMovingAwayRef.current = true;
noteOutsideDismissal(e.currentTarget.ownerDocument);
popover.hide();
},
[popover],
);
// Handle keyboard events on input
const handleInputKeyDown = useCallback(
(e: React.KeyboardEvent) => {
// An in-progress IME composition uses Enter to commit the candidate and
// Escape to cancel it; that composing keydown fires before
// compositionend, so without this guard a Korean/Japanese/Chinese user
// committing a syllable with Enter would instead commit the pending date
// (or Escape would close the calendar mid-composition). 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' && (isPending || 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();
commitPendingInput();
}
},
[popover, commitPendingInput, isEffectivelyDisabled, isPending],
);
const inputWrapper = (
<div
ref={el => {
fieldElementRef.current = el;
popover.triggerRef(el);
// Anchor + hover/focus listeners for the disabled-message tooltip.
// Handlers are gated internally by isEnabled, and anchor names
// compose, so attaching unconditionally is safe.
disabledMessageTooltip.ref(el);
}}
onBlur={handleFieldBlur}
{...(inputGroup ? inputGroupItemProps : undefined)}
{...mergeProps(
themeProps('date-input', {
size,
status: fieldStatus?.type ?? null,
disabled: isDisabled ? 'disabled' : null,
}),
stylex.props(
inputWrapperStyles.base,
inputWrapperStyles.textField,
sizeStyles[size],
// Disabled paint belongs to the disabled state only; a busy field
// keeps its ordinary paint and shows the Spinner (spec:AST-085
// FR6, family:buttons FR4).
isDisabled && inputWrapperStyles.disabled,
isEffectivelyDisabled && inputDisabledFocusStyles.inputFocusRing,
fieldStatus && inputStatusBorderStyles[fieldStatus.type],
fieldStatus &&
!isEffectivelyDisabled &&
inputStatusHoverShadowStyles[fieldStatus.type],
fieldStatus && inputStatusFocusWithinStyles[fieldStatus.type],
inputGroup && groupStyles.inGroup,
controlXstyle,
),
controlClassName,
controlStyle,
)}>
{inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
<button
type="button"
onClick={handleToggle}
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 toggle glyph itself, so a theme can
// restyle just this icon (color, size, hover) — and each open/closed
// state — via `defineTheme`. Same-element rules in @layer astryx-theme
// win over the icon's own base color/size, which a button-level target
// could not reach. Reflects the popover's open/closed state as a
// `data-state` attribute.
{...themeProps('date-input-toggle-icon', {
state: popover.isOpen ? 'expanded' : 'collapsed',
})}
/>
</button>
<input
{...controlProps}
ref={useMergedRefs(ref, inputRef)}
id={id}
type="text"
role="combobox"
value={displayValue}
onChange={handleInputChange}
onBlur={chainEventHandlers(handleBlur, onBlurProp)}
onFocus={chainEventHandlers(handleFocus, onFocusProp)}
onClick={
isEffectivelyDisabled
? undefined
: chainEventHandlers(handleInputClick, onClickProp)
}
onKeyDown={chainEventHandlers(handleInputKeyDown, onKeyDownProp)}
placeholder={formatHint ?? placeholder}
aria-disabled={isEffectivelyDisabled ? 'true' : undefined}
readOnly={isEffectivelyDisabled || undefined}
aria-labelledby={
ariaLabelledByProp != null
? joinAriaIDs(ariaLabelledBy ?? fieldLabelID, ariaLabelledByProp)
: ariaLabelledBy
}
aria-describedby={ariaDescribedBy}
aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={
fieldStatus?.type === 'error' || isInvalid ? '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,
isInvalid && styles.inputInvalid,
)}
/>
{/*
Announces a typed rejection that the field status does not announce.
The field status announces the rest.
*/}
<VisuallyHidden as="div" role="alert" aria-live="assertive">
{alertMessage}
</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}
{popover.render(
// The layer renders its children open or closed, so mount the
// calendar only while it is open; it opens on the current value.
!popover.isOpen ? null : (
<Calendar
handleRef={calendarRef}
calendar={typedDate.calendar}
mode="single"
value={optimisticValue ?? null}
onChange={handleDateSelect}
min={min}
max={max}
dateConstraints={dateConstraints}
numberOfMonths={numberOfMonths}
weekStartsOn={weekStartsOn}
/>
),
{placement: 'below', alignment: 'start'},
)}
{showsDisabledMessage &&
disabledMessageTooltip.renderTooltip(disabledMessage)}
</div>
);
if (inputGroup) {
return inputWrapper;
}
return (
<Field
{...container}
label={label}
isLabelHidden={isLabelHidden}
description={description}
inputID={id}
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
}
statusVariant={statusVariant}
labelTooltip={labelTooltip}
width={width}>
{inputWrapper}
</Field>
);
}
PointerDateField.displayName = 'PointerDateField';
/**
* A date picker that fits the pointer it is being used with.
*
* With a mouse or trackpad this is a text input you can type into, with a
* calendar in a popover — unchanged, and still the surface every existing
* consumer gets. With a finger it is a picker built for one: a bottom sheet
* holding one month per screen, swiped sideways, with month and year wheels
* behind the header title for the far jumps swiping is bad at.
*
* The props are identical either way — this is one component with two
* surfaces, not two components — so nothing at the call site changes, and a
* date typed on a laptop and a date thumbed on a phone are the same value.
*
* ## Why a runtime switch and not CSS
*
* The two surfaces are structurally different — a popover anchored to a text
* field versus a full-width sheet holding a scroller — so "render both, hide
* one" would double the DOM, double the tab stops, and mount two calendars.
* The condition is not layout either: it is *which interaction is faster*,
* and that depends on the pointer, which CSS cannot hand to JS.
*
* They are two components rather than one with a branch inside because the
* hook lists differ; keeping them separate is what lets each own its own.
*
* ## Hydration
*
* `useMediaQuery` reports false during SSR, so server HTML is always the
* pointer field and the swap happens after hydration. That is deliberately
* unobservable: both surfaces render the SAME closed field — a bordered input
* with a calendar icon and the formatted date — and differ only in what
* opens. Nothing moves; the field just starts opening a sheet.
*
* 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.
*
* @example
* ```
* <DateInput
* label="Event date"
* value={date}
* onChange={setDate}
* />
* ```
*/
export function DateInput(props: DateInputProps) {
const inputGroupState = use(InputGroupInternalContext);
const isDisabled = props.isDisabled || inputGroupState.isDisabled;
const isTouch = useMediaQuery(TOUCH_POINTER_QUERY);
useDevWarning(
'DateInput',
'`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} = useCalendarPresentation(
'DateInput',
props.calendar,
props.presentation,
props.nativePicker,
);
const surface = resolvePickerPresentation(presentation, isTouch);
const {
presentation: _presentation,
nativePicker: _nativePicker,
calendar: _calendar,
...rest
} = props;
switch (surface) {
case 'native':
return <NativeDateField {...rest} isDisabled={isDisabled} />;
case 'sheet':
return (
<TouchDateField
// Month indexes depend on the calendar. A new calendar remounts the sheet.
key={calendar}
{...rest}
calendar={calendar}
isDisabled={isDisabled}
/>
);
case 'desktop':
return (
<PointerDateField
{...rest}
calendar={calendar}
isDisabled={isDisabled}
/>
);
}
}
DateInput.displayName = 'DateInput';