An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file TimeInput.tsx
* @input Uses React, Field, NativeTimeSegment, InputGroupContext, pointer media queries, and shared time utilities
* @output Exports TimeInput, TimeInputProps, and TimeInputNativePicker
* @position Core implementation; consumed by index.ts, tested by TimeInput.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/TimeInput/TimeInput.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/TimeInput/TimeInput.test.tsx (typed-field tests)
* - /packages/core/src/TimeInput/NativeTimeInput.test.tsx (native-picker tests)
* - /packages/core/src/TimeInput/index.ts (exports if types change)
* - /apps/storybook/stories/TimeInput.stories.tsx (storybook stories)
* - /packages/cli/assets/templates/blocks/components/TimeInput/ (showcase blocks)
*/
import {
use,
useId,
useState,
useCallback,
useEffect,
useRef,
useMemo,
useOptimistic,
useTransition,
type KeyboardEvent,
type FocusEvent,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
import {
colorVars,
sizeVars,
typographyVars,
typeScaleVars,
} from '../theme/tokens.stylex';
import {
Field,
InputClearButton,
type InputStatus,
inputWrapperStyles,
inputStatusBorderStyles,
inputStatusHoverShadowStyles,
inputStatusFocusWithinStyles,
} from '../Field';
import {Icon} from '../Icon';
import {Spinner} from '../Spinner';
import {VisuallyHidden} from '../VisuallyHidden';
import {
type ISOTimeString,
formatISOTime,
adjustTime,
isImeKeyEvent,
isTimeInRange,
mergeProps,
getInputARIA,
} from '../utils';
import {chainEventHandlers} from '../utils/chainEventHandlers';
import {joinAriaIDs} from '../utils/inputAria';
import {
useFieldInputStyling,
type FieldInputBaseProps,
} from '../Field/fieldParts';
import type {SizeValue} from '../utils/types';
import {useSize} from '../SizeContext/SizeContext';
import {useAnnounce} from '../hooks/useAnnounce';
import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
import {useInputContainer} from '../hooks/useInputContainer';
import {useMediaQuery} from '../hooks/useMediaQuery';
import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {useInputGroup} from '../InputGroup/InputGroupContext';
import {InputGroupInternalContext} from '../InputGroup/InputGroupInternalContext';
import {groupStyles, inputGroupItemProps} from '../InputGroup/groupStyles';
import {useTooltip} from '../Tooltip';
import {themeProps} from '../utils/themeProps';
import {useLocale} from '../i18n';
import {
formatLocaleTime,
parseLocaleTime,
resolveHourFormat,
} from '../utils/timeFormat';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {NativeTimeSegment} from '../DateTimeInput/NativeTimeSegment';
import {TouchTimeField} from './TouchTimeField';
import {
effectiveInputPresentation,
resolveInputPresentation,
type InputPresentation,
} from '../utils/inputPresentation';
import {useDevWarning} from '../hooks/useDevWarning';
import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
import {
registerEnglishFallback,
useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/TimeInput/TimeInput.generated';
registerEnglishFallback(english);
const TOUCH_POINTER_QUERY = '(pointer: coarse)';
const styles = stylex.create({
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'],
},
});
const sizeStyles = stylex.create({
sm: {
height: sizeVars['--size-element-sm'],
minWidth: 120,
},
md: {
height: sizeVars['--size-element-md'],
minWidth: 120,
},
lg: {
height: sizeVars['--size-element-lg'],
minWidth: 120,
},
});
export type TimeInputSize = keyof typeof sizeStyles;
export type TimeInputHourFormat = '12h' | '24h';
/** @deprecated Use {@link TimeInputPresentation} via the `presentation` prop. */
export type TimeInputNativePicker = 'touch' | 'always' | 'never';
/** Which surface TimeInput uses for time selection (`spec:AST-043` FR1). */
export type TimeInputPresentation = InputPresentation;
// Re-export shared types for convenience
export type {
InputStatus as TimeInputStatus,
InputStatusType as TimeInputStatusType,
} from '../Field';
export interface TimeInputProps extends Omit<
FieldInputBaseProps<HTMLInputElement>,
'onChange' | 'defaultValue'
> {
/** Ref forwarded to the time 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 input shows a tooltip with this text on hover and
* keyboard focus, and the input is described by it, so the reason is
* discoverable by keyboard and assistive technology. Typing and arrow-key
* adjustment stay blocked.
*
* Use this instead of wrapping a disabled input in `Tooltip`, so the
* reason is tied to the field.
*
* @example
* ```
* <TimeInput
* label="Start time"
* value={time}
* onChange={setTime}
* isDisabled
* disabledMessage="You need the Editor role to change this"
* />
* ```
*/
disabledMessage?: string;
/**
* The selected time in ISO format (HH:MM or HH:MM:SS).
*/
value?: ISOTimeString | undefined;
/**
* Callback fired when the time changes.
* Called with undefined when input is cleared.
*/
onChange?: (value: ISOTimeString | undefined) => void;
/**
* Async action on change. Fires after onChange.
*/
changeAction?: (value: ISOTimeString | undefined) => void | Promise<void>;
/**
* Whether the input is in a loading state.
* @default false
*/
isLoading?: boolean;
/**
* Minimum selectable time in ISO format.
*/
min?: ISOTimeString;
/**
* Maximum selectable time in ISO format.
*/
max?: ISOTimeString;
/**
* Whether to include seconds in the time input.
* @default false
*/
hasSeconds?: boolean;
/**
* Whether to show a clear button when a value is set.
* @default false
*/
hasClear?: boolean;
/**
* Whether to automatically focus the input on mount.
* @default false
*/
hasAutoFocus?: boolean;
/**
* Hour format for display.
* - '12h': Display as 12-hour with the locale's day period (e.g., "2:30 PM")
* - '24h': Display as 24-hour (e.g., "14:30")
*
* When unset, follows the `InternationalizationProvider` locale's hour
* cycle: `en-US` reads 12-hour, `en-GB` and `de-DE` read 24-hour. A
* per-user preference rides on the locale tag (`en-US-u-hc-h23`).
* @default the locale's hour cycle
*/
hourFormat?: TimeInputHourFormat;
/**
* Increment in minutes when using arrow keys. Steps are whole minutes: a
* fractional value leaves the time unchanged.
* @default 1
*/
increment?: number;
/**
* Which time-selection surface to use.
*
* - `'touch'`: browser/OS picker on coarse pointers, Astryx's typed field on
* fine pointers
* - `'always'`: browser/OS picker wherever `<input type="time">` is supported
* - `'never'`: Astryx's typed field everywhere
*
* Native time pickers cannot preserve seconds or Astryx's arrow-key cadence,
* so `hasSeconds` or `increment !== 1` keeps the typed field.
* @default 'touch'
* @deprecated Use `presentation` (`spec:AST-043` FR3):
* `'touch'` → `'adaptive-native'`, `'always'` → `'native'`,
* `'never'` → `'text-input'`. Still works exactly as released;
* `presentation` wins when both are set.
*/
nativePicker?: TimeInputNativePicker;
/**
* Which surface selects the time (`spec:AST-043` FR1).
*
* - `'text-input'`: Astryx's typed field only (today's `nativePicker="never"`)
* - `'popover'`: no distinct popover exists for TimeInput; resolves to the
* typed field (FR1 surface table)
* - `'bottom-sheet'`: Astryx's bottom-sheet time wheels on every pointer
* - `'native'`: the browser/OS `<input type="time">` on every pointer, with
* no Astryx fallback (FR2)
* - `'adaptive-bottom-sheet'`: typed field on a fine pointer, bottom sheet
* on a coarse pointer
* - `'adaptive-native'` (default): typed field on a fine pointer, browser/OS
* picker on a coarse pointer, keeping the released Astryx fallback
* (`hasSeconds` or `increment !== 1`) where native cannot express it (FR2)
*
* @default 'adaptive-native'
*/
presentation?: TimeInputPresentation;
/**
* Placeholder text shown when no time is selected.
* @default "Select a time"
*/
placeholder?: string;
/**
* The size of the input.
* - 'sm': Compact size (18px height)
* - 'md': Default size (26px height)
* @default 'md'
*/
size?: TimeInputSize;
/**
* 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;
}
/**
* A time input component with text input and keyboard navigation.
*
* @example
* ```
* <TimeInput
* label="Start time"
* value={time}
* onChange={setTime}
* hourFormat="12h"
* hasClear
* />
* ```
*/
function TimeField({
label,
isLabelHidden = false,
description,
isOptional = false,
isRequired = false,
isDisabled = false,
disabledMessage,
value,
onChange,
changeAction,
isLoading = false,
min,
max,
hasSeconds = false,
hasClear = false,
hasAutoFocus = false,
hourFormat = '12h',
increment = 1,
placeholder: placeholderFromProps,
size: sizeProp,
status,
statusVariant = 'attached',
labelTooltip,
width,
containerXstyle,
containerClassName,
containerStyle,
controlXstyle,
controlClassName,
controlStyle,
ref,
nativeMode = 'off',
...restProps
}: TimeInputProps & {nativeMode?: 'off' | 'adaptive' | 'forced' | 'legacy'}) {
const {rest, container} = useFieldInputStyling('TimeInput', restProps, {
containerXstyle,
containerClassName,
containerStyle,
});
const {
id: idProp,
'aria-describedby': ariaDescribedByProp,
'aria-labelledby': ariaLabelledByProp,
onFocus: onFocusProp,
onBlur: onBlurProp,
onKeyDown: onKeyDownProp,
...controlProps
} = rest;
const t = useComponentTranslator();
const locale = useLocale();
const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const placeholder =
placeholderFromProps ?? t('@astryx.timeInput.placeholder');
const size = useSize(sizeProp, 'md');
// `forced` (explicit `presentation="native"`, FR2): always native, no
// fallback. `adaptive` (`adaptive-native` coarse) and `legacy` (deprecated
// `nativePicker="always"`): iOS has no seconds wheel and treats step as
// validation rather than wheel cadence, so those keep the typed field —
// `legacy` on every pointer, exactly as released.
const usesNativeTimePicker =
nativeMode === 'forced' ||
((nativeMode === 'adaptive' || nativeMode === 'legacy') &&
!hasSeconds &&
increment === 1);
const generatedID = useId();
const id = idProp ?? generatedID;
const fieldLabelID = useId();
const inputLabelID = useId();
const descriptionID = useId();
const statusMessageID = useId();
const inputRef = useRef<HTMLInputElement | null>(null);
const mergedInputRef = useMergedRefs(ref, inputRef);
const containerRef = useRef<HTMLDivElement | 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'), containerRef);
// In grouped mode the status message renders as a visually-hidden node that
// exists only for aria-describedby. Announce it through the persistent
// useAnnounce live regions instead of role/aria-live on that node — a live
// region mounted together with its content is not reliably announced.
// Ungrouped mode delegates to Field -> FieldStatus, which announces itself.
const announce = useAnnounce();
// Syncs the live region with `status.message` when the field is in an
// InputGroup.
useEffect(() => {
if (inputGroup && status?.message) {
announce(
status.message,
status.type === 'error' ? 'assertive' : 'polite',
);
}
}, [announce, inputGroup, status?.message, status?.type]);
// A disabled field never renders native `disabled` (spec:AST-085 FR1): the
// input stays focusable via aria-disabled, and readOnly plus the value
// mutation guards block typing. The disabled-reason tooltip's listeners
// attach to the input container.
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,
});
// Status icon mapping
const {statusIcon, describedBy: statusTooltipDescribedBy} =
useInputStatusIcon({
status,
statusVariant,
isInGroup: !!inputGroup,
});
const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
inputLabelID,
[
description ? descriptionID : null,
statusVariant !== 'tooltip' && status?.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,
);
// A caller aria-labelledby names the control together with the field's own
// label (the Field label standalone, the group and input labels in a group).
const controlLabelledBy =
ariaLabelledByProp != null
? joinAriaIDs(ariaLabelledBy ?? fieldLabelID, ariaLabelledByProp)
: ariaLabelledBy;
// Pending input while user is typing (null = show formatted value)
const [pendingInput, setPendingInput] = useState<string | null>(null);
const [isFocused, setIsFocused] = useState(false);
const formatDisplayTime = useCallback(
(time: ISOTimeString, includeSeconds: boolean) =>
formatLocaleTime(time, locale, hourFormat, includeSeconds),
[locale, hourFormat],
);
// Unified change handler that fires both onChange and changeAction
const fireChange = useCallback(
(newValue: ISOTimeString | undefined) => {
onChange?.(newValue);
if (changeAction) {
startTransition(async () => {
setOptimisticValue(newValue);
await changeAction(newValue);
});
}
},
[onChange, changeAction, startTransition, setOptimisticValue],
);
// Display value: pending input if typing, otherwise formatted value
const displayValue = useMemo(() => {
if (pendingInput !== null) {
return pendingInput;
}
return optimisticValue
? formatDisplayTime(optimisticValue, hasSeconds)
: '';
}, [pendingInput, optimisticValue, formatDisplayTime, hasSeconds]);
// Check if current input is valid (for styling purposes)
const isInputValid = useMemo(() => {
// Only check pending input for validity styling
if (pendingInput === null || !pendingInput.trim()) {
return true;
}
const parsed = parseLocaleTime(pendingInput, locale, hasSeconds);
if (!parsed) {
return false;
}
// Also check min/max range
return isTimeInRange(parsed, min, max);
}, [pendingInput, locale, hasSeconds, min, max]);
// Placeholder that shows format hint when focused and empty
const displayPlaceholder = useMemo(() => {
if (isFocused && !displayValue) {
return hourFormat === '12h'
? t('@astryx.dateTimeInput.timeHint12h')
: t('@astryx.dateTimeInput.timeHint24h');
}
return placeholder;
}, [isFocused, displayValue, hourFormat, placeholder, t]);
// Handle input text change - update immediately if valid
const handleInputChange = useCallback(
(e: React.ChangeEvent<HTMLInputElement>) => {
// The input is never natively disabled (spec:AST-085 FR1), so guard
// value mutation explicitly (readOnly also blocks typing).
if (isDisabled) {
return;
}
const newValue = e.target.value;
setPendingInput(newValue);
// If the input is valid, update immediately (don't wait for blur)
const parsed = parseLocaleTime(newValue, locale, hasSeconds);
if (parsed && isTimeInRange(parsed, min, max) && parsed !== value) {
fireChange(parsed);
}
},
[locale, hasSeconds, min, max, value, fireChange, isDisabled],
);
// Handle focus
const handleFocus = useCallback(() => {
// A disabled 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 (isDisabled) {
return;
}
setIsFocused(true);
}, [isDisabled]);
// Handle blur - validate and clear pending input
const handleBlur = useCallback(
(_e: FocusEvent<HTMLInputElement>) => {
setIsFocused(false);
if (pendingInput === null) {
return;
}
// Disabled: keep the value, drop the draft (spec:AST-085 FR2).
if (isDisabled) {
setPendingInput(null);
return;
}
if (!pendingInput.trim()) {
// Empty input clears the value
if (value !== undefined) {
fireChange(undefined);
}
setPendingInput(null);
return;
}
const parsed = parseLocaleTime(pendingInput, locale, hasSeconds);
if (parsed && isTimeInRange(parsed, min, max)) {
// Valid time - update if different
if (parsed !== value) {
fireChange(parsed);
}
}
// Clear pending input - display will revert to formatted value
setPendingInput(null);
},
[pendingInput, isDisabled, value, fireChange, locale, hasSeconds, min, max],
);
// Handle keyboard navigation on input
// Enter in a focused disabled field would submit a surrounding form (FR2).
const preventDisabledEnter = (e: KeyboardEvent<HTMLInputElement>) => {
if (isDisabled && e.key === 'Enter') {
e.preventDefault();
}
};
const handleInputKeyDown = 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.
if (isImeKeyEvent(e.nativeEvent)) {
return;
}
// Arrow-key adjustment mutates the value; block it while disabled.
if (isDisabled) {
return;
}
if (e.key === 'ArrowUp' || e.key === 'ArrowDown') {
e.preventDefault();
// Get current time or default to now
let currentTime = value;
if (!currentTime) {
const now = new Date();
currentTime = formatISOTime(
{
hour: now.getHours(),
minute: now.getMinutes(),
second: now.getSeconds(),
},
hasSeconds,
);
}
const delta = e.key === 'ArrowUp' ? increment : -increment;
const newTime = adjustTime(currentTime, delta, hasSeconds);
// Check if within range
if (isTimeInRange(newTime, min, max)) {
// The step is the committed value now: drop any typed draft so the
// box shows the stepped time and blur cannot re-commit stale text
// over it.
setPendingInput(null);
fireChange(newTime);
// Stepping programmatically rewrites a plain textbox's value, and
// screen readers do not announce programmatic textbox changes — the
// new value must be spoken explicitly or stepping is silent
// (WCAG 4.1.2).
announce(formatDisplayTime(newTime, hasSeconds));
}
}
},
[
value,
hasSeconds,
increment,
min,
max,
fireChange,
isDisabled,
announce,
formatDisplayTime,
],
);
// Handle clear button click
const handleClear = useCallback(
(e?: React.MouseEvent<HTMLButtonElement>) => {
fireChange(undefined);
// Focusing a native time control reopens the OS picker on iOS.
if (!usesNativeTimePicker) {
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, usesNativeTimePicker],
);
// Focus input when clicking anywhere on the wrapper (icons, padding, etc.)
const {onClick: handleWrapperClick, onMouseUp: handleWrapperMouseUp} =
useInputContainer({
containerRef,
inputRef,
disabled: isDisabled,
});
const inputWrapper = (
<div
ref={el => {
containerRef.current = el;
// Anchor + hover/focus listeners for the disabled-message tooltip.
// Handlers are gated internally by isEnabled, so attaching
// unconditionally is safe.
disabledMessageTooltip.ref(el);
}}
onClick={usesNativeTimePicker ? undefined : handleWrapperClick}
onMouseUp={usesNativeTimePicker ? undefined : handleWrapperMouseUp}
{...(inputGroup ? inputGroupItemProps : undefined)}
{...mergeProps(
themeProps('time-input', {
size,
status: status?.type ?? null,
disabled: isDisabled ? 'disabled' : null,
}),
stylex.props(
inputWrapperStyles.base,
inputWrapperStyles.textField,
sizeStyles[size],
isDisabled && inputWrapperStyles.disabled,
isDisabled && inputDisabledFocusStyles.withinRing,
status && inputStatusBorderStyles[status.type],
status && !isDisabled && inputStatusHoverShadowStyles[status.type],
status && inputStatusFocusWithinStyles[status.type],
inputGroup && groupStyles.inGroup,
controlXstyle,
),
controlClassName,
controlStyle,
)}>
{inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
{inputGroup && description && (
<VisuallyHidden as="div" id={descriptionID}>
{description}
</VisuallyHidden>
)}
{inputGroup && status?.message && (
<VisuallyHidden as="div" id={statusMessageID}>
{status.message}
</VisuallyHidden>
)}
{usesNativeTimePicker ? (
<NativeTimeSegment
id={id}
inputRef={mergedInputRef}
value={optimisticValue}
onChange={fireChange}
placeholder={placeholder}
openPickerLabel={t('@astryx.timeInput.openPicker', {label})}
ariaLabelledBy={controlLabelledBy}
hasAutoFocus={hasAutoFocus}
min={min}
max={max}
hourFormat={hourFormat}
isEffectivelyDisabled={isDisabled}
isFocusableDisabled
isEffectivelyRequired={isEffectivelyRequired}
isBusy={isBusy}
statusType={status?.type}
ariaDescribedBy={ariaDescribedBy}
controlProps={{
...controlProps,
onFocus: onFocusProp,
onBlur: onBlurProp,
onKeyDown: chainEventHandlers(preventDisabledEnter, onKeyDownProp),
onClick: isDisabled ? undefined : controlProps.onClick,
}}
/>
) : (
<>
<div {...stylex.props(styles.icon)}>
<Icon icon="clock" size="sm" color="secondary" />
</div>
<input
{...controlProps}
ref={mergedInputRef}
id={id}
type="text"
value={displayValue}
onChange={handleInputChange}
onFocus={chainEventHandlers(handleFocus, onFocusProp)}
onBlur={chainEventHandlers(handleBlur, onBlurProp)}
onKeyDown={chainEventHandlers(
preventDisabledEnter,
handleInputKeyDown,
onKeyDownProp,
)}
placeholder={displayPlaceholder}
aria-disabled={isDisabled ? 'true' : undefined}
readOnly={isDisabled || undefined}
// The browser still dispatches a click on an aria-disabled input,
// so a caller's onClick is skipped too (spec:AST-085 FR2).
onClick={isDisabled ? undefined : controlProps.onClick}
autoFocus={hasAutoFocus}
data-autofocus={hasAutoFocus || undefined}
aria-describedby={ariaDescribedBy}
aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={
status?.type === 'error' || !isInputValid ? 'true' : undefined
}
aria-busy={isBusy || undefined}
aria-labelledby={controlLabelledBy}
{...stylex.props(
styles.input,
isDisabled && styles.inputDisabled,
!isInputValid && styles.inputInvalid,
)}
/>
{/*
Live region announcing invalid typed input to assistive technology.
The value silently reverts on blur, so without this a screen-reader
user would get no feedback that their entry was rejected (WCAG 3.3.1).
*/}
<VisuallyHidden as="div" role="alert" aria-live="assertive">
{!isInputValid ? t('@astryx.timeInput.invalidTime') : ''}
</VisuallyHidden>
</>
)}
{isBusy && <Spinner size="sm" aria-hidden="true" />}
{hasClear && optimisticValue && !isDisabled && (
<InputClearButton
label={t('@astryx.timeInput.clearLabel', {label})}
onClick={handleClear}
/>
)}
{statusIcon}
</div>
);
if (inputGroup) {
return (
<>
{inputWrapper}
{showsDisabledMessage &&
disabledMessageTooltip.renderTooltip(disabledMessage)}
</>
);
}
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={
status
? {
type: status.type,
message: status.message,
messageID: status.message ? statusMessageID : undefined,
}
: undefined
}
statusVariant={statusVariant}
labelTooltip={labelTooltip}
width={width}>
{inputWrapper}
{showsDisabledMessage &&
disabledMessageTooltip.renderTooltip(disabledMessage)}
</Field>
);
}
TimeField.displayName = 'TimeField';
/**
* A time input whose `presentation` prop chooses the selection surface
* (`spec:AST-043`); the deprecated `nativePicker` maps to the same surfaces
* (FR3).
*
* Base props (`ref`, `id`, `data-*`, `aria-*`, DOM event handlers) go to the time 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 TimeInput(props: TimeInputProps) {
const inputGroupState = use(InputGroupInternalContext);
const isDisabled = props.isDisabled || inputGroupState.isDisabled;
const isTouch = useMediaQuery(TOUCH_POINTER_QUERY);
useDevWarning(
'TimeInput',
'`nativePicker` is deprecated; use `presentation` instead (`touch` → `adaptive-native`, `always` → `native`, `never` → `text-input`). `presentation` wins when both are set.',
props.nativePicker !== undefined,
);
const effective = effectiveInputPresentation(
props.presentation,
props.nativePicker,
'time',
);
const locale = useLocale();
const {
presentation: _presentation,
nativePicker: _nativePicker,
...surfaceProps
} = props;
// Every surface gets the resolved hour format, so the typed text, the
// native field's resting text, and the sheet wheels agree.
const rest = {
...surfaceProps,
hourFormat: resolveHourFormat(locale, props.hourFormat),
};
if (effective === 'native') {
// Deprecated `always` keeps released fallbacks (FR2 legacy); only an
// explicit `presentation="native"` is forced.
return (
<TimeField
{...rest}
isDisabled={isDisabled}
nativeMode={
props.presentation === undefined && props.nativePicker === 'always'
? 'legacy'
: 'forced'
}
/>
);
}
switch (resolveInputPresentation(effective, isTouch)) {
case 'native':
// Only `adaptive-native` on a coarse pointer resolves here (FR2).
return (
<TimeField {...rest} isDisabled={isDisabled} nativeMode="adaptive" />
);
case 'sheet':
return <TouchTimeField {...rest} isDisabled={isDisabled} />;
case 'text-input':
case 'desktop':
return <TimeField {...rest} isDisabled={isDisabled} />;
}
}
TimeInput.displayName = 'TimeInput';