An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:DateInput authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-31 owners: [cixzhang] review_triggers: [public-api, behavior, layout, theming, accessibility] verified_by: [ packages/core/src/DateInput/MonthScrollerSettle.test.tsx, packages/core/src/DateInput/DateInput.test.tsx, packages/core/src/DateInput/TouchDateToday.ssr.test.tsx, packages/core/src/DateInput/DateInput.fr10.test.tsx, packages/core/src/DateInput/DateInput.calendar.test.tsx, packages/core/src/DateInput/DateInput.calendarPresentation.test.tsx, packages/core/src/DateInput/DateInputTouch.calendar.test.tsx, packages/core/src/DateInput/DateInput.noTemporal.test.tsx, packages/core/src/utils/calendarSystem.test.ts, packages/core/src/utils/calendarDateParser.test.ts, packages/core/src/utils/calendarDateParser.roundtrip.test.ts, packages/core/src/DateInput/DateInputTouch.test.tsx, packages/core/src/DateInput/NativeDateField.test.tsx, packages/core/src/DateInput/PickerWheel.test.tsx, packages/core/src/DateInput/Presentation.test.tsx, packages/core/src/DateInput/Wheel.test.tsx, packages/core/src/DateInput/tests/WheelRest.a11y.chromium.spec.ts, packages/core/src/tests/BusyOwnerAnnouncement.test.tsx, packages/core/src/theme/themingTargets.test.ts, scripts/check-knowledge.mjs, ] modules: [] families: [family:input-fields, family:overlay-dismissal] design_specs: [design:reduced-motion/DR2, design:reduced-motion/DR3] architecture: [ architecture:component-theming-surface, architecture:interaction-modality, architecture:internationalization, architecture:public-component-api, architecture:public-component-api/INV16, architecture:react-component-runtime/INV13, ] contributing: [] system_specs: [ spec:AST-013/FR9, spec:AST-013/FR12, spec:AST-020/FR15, spec:AST-043, spec:AST-085, spec:AST-085/FR1, spec:AST-085/FR2, spec:AST-086, spec:AST-094/FR5, spec:AST-094/FR10, spec:AST-094/FR43, spec:AST-102, spec:AST-111,
]
DateInput component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | calendar selects the calendar system the field shows on every surface (spec:AST-111 FR2); every other API shape and default is as shipped, and every surface follows the input-field changeAction, disabled, and busy contracts. |
| Behavior | presentation selects the picker surface; an omitted value is adaptive-native; presentation wins over deprecated nativePicker; every committed path emits the same controlled ISO-date value and action feedback. The pointer field reads and writes typed dates in the resolved calendar and reports a typed date only when it is complete (FR20). With a calendar other than gregory or iso8601, a presentation that would show the native control shows the popover on a fine pointer and the bottom sheet on a coarse pointer, and the bottom sheet shows months of the calendar (FR21). |
| End-user impact | People type or pick one date using a surface suited to the primary pointer, in the calendar the application chooses. Disabled and busy fields stay focusable; a busy field keeps its ordinary paint with a Spinner while new commits are blocked. |
| Builder impact | Optional: set calendar on the field or its provider, and min and max on Buddhist and Minguo calendar fields. changeAction runs after onChange with optimistic busy feedback on every surface. |
| Compatibility/readiness | calendar is additive and the default stays Gregorian. Typed Gregorian entry fires onChange only for complete input and keeps an out-of-range date with its error; parseDateInput handles only unreadable text and dates the locale's order lacks, and a two-digit year reads within the 80 years before and 19 after the current year, 1946–2045 in 2026 (FR20). Calendars that need Temporal fall back to Gregorian where it is missing (the spec:AST-013 FR12 exception). Under a finger, the sheet wheels' markup changes (one strip of flat rows, faded by a layer inside the column). Under every presentation, keys step through the values in time order (FR17). Caller handlers while disabled, fixed field height, a clear control that drops focus, and month paging in the touch calendar are listed under Current-state impact. |
| Review checks | Reject a surface-mapping change, lost constraint, callback-order change, unlabeled field, native disabled, disabled paint on a busy-only field, unreachable disabled reason, changed close behavior, a theming target placed on the wrong owner, a typed date reported before it is complete, an adjusted typed date, or two rejection kinds that share a message. |
| Governing rules | spec:AST-043/FR1–FR5; spec:AST-085/FR1–FR6; spec:AST-086/FR3, FR4, FR6, FR8; spec:AST-111 FR2, FR3, FR9–FR16, AR2, AR3; spec:AST-013 FR12; family:input-fields/FR1–FR6, FR8–FR11; family:overlay-dismissal/FR1–FR7, including its recorded BottomSheet adoption gap; spec:AST-020/FR15; spec:AST-102/FR4; the four architecture records linked above. |
This table is a review projection; the body below is authoritative.
Intent
DateInput presents one controlled calendar date through a labeled input-field surface. A person may type the value or use a Calendar, bottom-sheet calendar, or browser/OS date picker selected by the public presentation contract.
Compatibility and migration
- Released default preserved:
yes - Compatibility class: additive
calendarprop with a Gregorian default; under a finger the sheet wheels' markup changes, and under every presentation keys step through the values in time order (FR17). Typed Gregorian entry firesonChangeonly for complete input, a nonbreaking fix that restores FR1's next-ISO-date contract; its rejection messages are additive; on Enter or blur,parseDateInputstill reads text the field cannot otherwise read and a date the locale's field order lacks, and a one- or three-digit year is not a date (FR20). A non-Gregorian calendar replaces the native control with the Astryx surface for the pointer, and an explicitnativewarns in development (FR21). A provider locale with a-u-ca-keyword keeps Gregorian dates (spec:AST-111DEC-2); setcalendarto choose one. - Controlled/uncontrolled behavior: unchanged; DateInput remains controlled by
value, withundefinedrepresenting no selected date - Migration decision:
spec:AST-043/DEC-1andspec:AST-043/DEC-2own thepresentationvocabulary, default, deprecatednativePickermapping, and precedence
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- Selecting the pointer, bottom-sheet, or native field surface from the resolved public presentation.
- Parsing typed dates, formatting committed dates, enforcing DateInput constraints,
and emitting one controlled ISO date or
undefined. - The DateInput field wrapper, calendar-toggle affordance, clear composition, and focus handoff between those controls and the selected picker surface.
- DateInput-specific composition of Field, Calendar, Popover, BottomSheet, and the browser/OS date control.
- The shared bottom-sheet picker wheel: how a wheel rests, commits, steps, turns, and looks wherever DateInput, TimeInput, or DateTimeInput renders it in a sheet (FR13–FR15, FR17, FR18, DEC-1, DEC-2), and DateInput's own month and year wheels (FR23).
- The disabled-reason Tooltip composition: DateInput renders the reason Tooltip
and links it from its focusable controls (
family:input-fieldsrepresentative matrix, "Member withdisabledMessage").
Does not own / non-goals
- Label, description, status, width, and shared clear-button presentation —
owned by
component:Field,component:FieldStatus, andfamily:input-fields. - Calendar-grid dates, navigation, and selection semantics — owned by
component:Calendar. - Weekday header names — set by
component:CalendarDD1; the bottom-sheet calendar shows them (FR19). - Popover hosting and topmost dismissal — owned by
component:Popoverandfamily:overlay-dismissal. - Bottom-sheet hosting and dismissal — owned by
component:BottomSheetand the overlay-dismissal family. The bottom-sheet surface inherits BottomSheet's recorded shared-dismissal adoption gap. - Cross-component picker vocabulary and deprecated-prop migration — owned by
spec:AST-043. - Browser/OS picker appearance, locale, momentum, or hit areas.
- A cylinder or other 3D wheel look: under a finger each sheet wheel's rows lie flat, and under a mouse the scrolling column keeps its tilt (DEC-2).
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| selected date | undefined or YYYY-MM-DD ISO date |
Controlled committed calendar date | Every surface | undefined |
component:DateInput |
stable | Types reject other values; unreadable typed text is announced and reverts on commit; a typed date the calendar does not have, or one out of range, is announced, shown, and kept for correction |
| presentation | popover, bottom-sheet, native, adaptive-bottom-sheet, adaptive-native |
Surface that collects the date | Every pointer; adaptive values resolve by primary pointer | adaptive-native |
spec:AST-043 |
stable | Types reject other values; DateInput has no text-only presentation |
| legacy native selection | touch, always, never |
Deprecated mapping to the released picker behavior | Used only when presentation is absent |
touch behavior |
spec:AST-043 |
deprecated, retained | presentation wins when both props are present |
| committed display | date, date_long, date_weekday, system_date, or formatter function |
Display shape for the committed ISO date | Closed field on every surface; never rewrites in-progress typed text; named formats other than system_date write the date in the resolved calendar |
date_long |
component:DateInput |
stable | Function output is displayed; unreadable output cannot be re-committed as typed text |
| calendar | a CalendarSystem (spec:AST-111 FR1) |
The calendar system the field shows dates in | Every surface; a calendar other than gregory or iso8601 replaces the native surface (FR21) |
the provider's resolved calendar, else gregory (spec:AST-111 FR2) |
spec:AST-111 |
stable | Resolves to gregory and warns once in development; a calendar that needs Temporal falls back to gregory where Temporal is missing |
| selectable range | optional min, max, and date-constraint predicates |
Dates that may commit | Every surface; native surfaces validate on commit when the OS cannot disable them | unbounded | component:DateInput with component:Calendar |
stable | A rejected date does not replace the controlled value and is announced where applicable |
| calendar configuration | one or two popover months; week start Sunday through Saturday | Calendar-grid layout | Week start applies to popover and bottom-sheet surfaces; month count applies only to the popover; neither is expressible by native pickers | one month, Sunday | component:DateInput with component:Calendar |
stable | Types close the value set |
| field state | enabled, disabled, disabled with reason, busy, optional, required, status | Shared field semantics and supporting presentation | Every surface, with surface-specific control mechanics | enabled, not busy | family:input-fields |
stable | Conflicting optional/required resolution follows the shared Field owner |
| clear affordance | absent or present while a committed value exists | Emits undefined and preserves the field interaction path |
Every surface when hasClear and a value are present; hidden while disabled or busy |
absent | component:DateInput with component:Field |
stable | No control renders when there is no value |
| field shell | standalone Field or admitted InputGroup child | Ownership of label, status, and outer geometry | Pointer surface supports both; other surfaces preserve the same public field semantics | standalone | family:input-fields |
stable | InputGroup context selects grouped adaptation |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | DateInput MUST present the controlled ISO value and emit onChange with the next ISO date or undefined without maintaining a competing committed value. |
Current source, docs, and focused tests |
| FR2 | The five presentation values MUST resolve to the fine/coarse surfaces in spec:AST-043/FR1, except as FR21 states for a calendar; omitting both presentation props MUST preserve adaptive-native. |
spec:AST-043/FR1–FR3; Presentation tests |
| FR3 | Explicit presentation MUST outrank deprecated nativePicker; the legacy values MUST retain their mappings and development-only warning from spec:AST-043/FR3–FR4. |
Current source, docs, and Presentation tests |
| FR4 | Adaptive resolution MUST use the primary pointer rather than viewport width or any-pointer availability, so tablets receive a touch surface and touchscreen laptops retain the typable field. | Current source, consumer docs, and surface-selection tests |
| FR5 | Text, Calendar, bottom-sheet, and native commit paths MUST enforce min, max, and dateConstraints; a rejected value MUST NOT replace the controlled value. |
Current source and all four focused suites |
| FR6 | Named committed formats MUST follow the InternationalizationProvider locale, the resolved calendar (FR20), and the shared Timestamp vocabulary; formatting MUST NOT rewrite in-progress typed text. Typed text MUST parse in the provider locale (architecture:internationalization INV1a, INV8); in a day-first locale, numeric text outside the locale-ordered forms is not a date, so no fixed month-first reading applies. The touch sheet's month heading and each month pane's name are stand-alone month labels: they start with a capital where CLDR's stand-alone context transform titlecases the month, as component:Calendar FR1 states for Calendar's. Implementation gap: a four-digit year written first (2026/01/12) parses in every locale. |
architecture:internationalization; current source, docs, locale tests; spec:AST-043/FR5 |
| FR7 | Every value-change path MUST call onChange before changeAction, present the proposed value optimistically, and expose one busy state while the Action is pending. |
family:input-fields/FR6; current source and focused tests |
| FR8 | The pointer field MUST open its Calendar from the input, calendar toggle, ArrowDown, or Alt+ArrowDown; Popover dismissal and focus return MUST remain owned by the shared Popover path. The open pointer Calendar stays open for a press on the field's input, clear button or label, or in the Calendar, and closes for a press elsewhere (architecture:layer-runtime) or for focus moving from anywhere in the field (its input, clear button or calendar toggle) to anything outside the field and the Calendar (family:overlay-dismissal AV4). |
Current source, Popover composition, keyboard/focus tests |
| FR9 | A pointer-surface Calendar selection MUST commit and close its Popover; a bottom-sheet Calendar selection MUST remain editable in the open sheet until Save closes the surface. | Current source and pointer/touch tests |
| FR10 | Standalone mode MUST compose Field; admitted InputGroup mode MUST remove competing Field chrome while preserving name, description, value, keyboard, focus, and editing semantics. The field has no root styling props; control* reaches the control box on every surface, and container* reaches the Field box where one renders (in a horizontal-labels FormLayout none renders and container* warns; inside an InputGroup it is dropped) (family:input-fields FR10). The field height is the shared element size for its size and MUST grow with a set text size (spec:AST-102 FR4). Implementation gap: the height is fixed. |
family:input-fields FR3, FR10; spec:AST-102 FR4; current source and tests |
| FR11 | Clear MUST emit undefined through the ordinary change pipeline. The pointer and bottom-sheet surfaces restore field focus using their shipped timing; the native surface MUST NOT reclaim focus because doing so reopens the OS picker. Implementation gap: when the field becomes disabled or busy while its clear control holds focus, the control unmounts and focus falls to the document body; spec:AST-085/FR4 requires focus to stay or move to a destination this record names. |
Current source and focused clear tests; spec:AST-085/FR4 |
| FR12 | No surface renders native disabled. A disabled field MUST stay focusable with aria-disabled, block typing, picking, clearing, and opening, describe its disabled reason when one is given, and take disabled paint. While busy (isLoading or a pending Action) the pointer and bottom-sheet surfaces expose aria-disabled and aria-busy, stay focusable, and block new commits; the native surface does the same for isLoading, and during a pending Action stays editable so the OS picker remains attached but rejects additional commits until the Action settles. A busy field that is not disabled keeps its ordinary paint and Spinner, shows no hover ring while commits are blocked, and keeps its keyboard focus ring. While disabled or busy, the field ignores Enter and blur and shows no typed rejection. Typed text whose date typing has not reported stays, and the next Enter or blur once the field is editable commits or rejects it; a new value replaces it. Text whose date typing already reported through onChange gives way to the field's value once the field is editable again, whether or not the change took it; a focused field keeps the text until the next Enter or blur. Caller handlers other than focus and blur MUST NOT run while the field is disabled (spec:AST-085 FR2). Implementation gap: only a caller onClick is skipped while disabled; caller key, paste, and pointer handlers (such as onKeyDown, onKeyUp, onPaste, and onPointerDown) still run on every surface, the native field included. |
spec:AST-085/FR1–FR6; family:input-fields/FR4–FR6; family:buttons/FR4; current source and focused tests |
| FR13 | A bottom-sheet picker wheel that comes to rest on a disabled row (outside min/max) MUST continue to the nearest enabled row, a tie going toward the committed row, and select it there. A wheel resting on its committed row MUST NOT select or commit, even when that row is outside the bounds, so opening a bounded sheet never changes an untouched value: a committed value outside the bounds stays, and an empty field stays empty. This holds for every wheel in the DateInput, TimeInput, and DateTimeInput sheets. |
DEC-1; UIDatePicker on the iOS 26.2 simulator; current source |
| FR14 | A shown bottom-sheet picker wheel whose value changes from outside, as when a bound clamps the time after another wheel turned, MUST turn onto the new row rather than jump to it, on springs.settle from rest, as a tap, a key or a program turn does: the wheel's main interaction is a gesture (spec:AST-094 FR45). The internal motion role picker.tapSpin.durationMs, UIKit's measured 300 ms, stays as the measured reference. Under a finger, a tapped row commits its value when its turn ends; a keyboard or assistive-technology activation commits at once. Implementation gap: without the touch presentation, the wheel is a scrolling column and a click or key turn plays the browser's smooth scroll. |
UIDatePicker on the iOS 26.2 simulator; current source |
| FR15 | Wherever the sheet shows, a sheet wheel's pan takes a trackpad's two-finger scroll, as spec:AST-094 FR43 allows a record to grant: the rows follow the fingers, coast on at the lift with the fingers' last speed, the coast starting from that speed (spec:AST-094 FR45), and rest on a row by FR13. A mouse-wheel notch turns the wheel one row, as an arrow key does, with no coast. A ctrl-scroll stays the page's zoom (spec:AST-094 FR43). Implementation gap: a trackpad drives the wheel only under a coarse primary pointer. |
spec:AST-094 FR43; current source |
| FR16 | Enter in the pointer field's text input commits typed text that has not been committed and is then held back, so a form never submits the value from before the commit. With no typed text pending, Enter is not prevented, so a form submits as it does from any text field, except on a disabled or busy field, where Enter does nothing (spec:AST-085 FR2). |
|
| FR17 | In a sheet wheel, Arrow, Page, Home and End move through the wheel's enabled values in time order, skipping disabled ones, and stop at the first or last enabled value; a key with no enabled value in its direction commits nothing, under every presentation. On a 12-hour hour wheel, time order follows the full time (12 PM comes before 1 PM), not the column's row order. | Owner decision (cixzhang, 2026-11-02); current source |
| FR18 | Under a finger, while a wheel coasts, snaps or turns, no row carries the selection band's accent mark; the mark returns on the row that comes to rest, as UIPickerView does (spec:AST-094 FR3). |
Owner decision (cixzhang, 2026-11-02); UIDatePicker on the iOS 26.2 simulator; current source |
| FR19 | The bottom-sheet calendar's weekday row MUST show the weekday names component:Calendar DD1 sets for the provider locale, in the order of the panes' day columns (weekStartsOn), so both pickers label a locale's columns alike. |
|
| FR20 | The pointer field reads and writes typed dates in the resolved calendar (spec:AST-111 FR2), and its Calendar shows that calendar. It reads the dates Intl.DateTimeFormat writes for the locale and calendar, in any Unicode decimal digits and with month and era names of the locale and English; in the Gregorian calendar, text that matches none of these forms, or that these forms read as a date the calendar does not have, still commits on Enter or blur when parseDateInput reads it, so 13/5/2026 in en-US commits as 13 May 2026 (spec:AST-111 FR9). A typed year is a year of the calendar (spec:AST-111 FR10). It rejects a date the calendar does not have and never adjusts it; a typed date outside min, max, or dateConstraints shows and announces an out-of-range error that writes the bounds in the calendar, and Enter or blur keeps both kinds of rejected text so the person can correct it, while unreadable text reverts (spec:AST-111 FR11). While a person types, onChange fires only for complete input, at most once for each distinct value in one typing session, and a one-digit day stays open until another digit, Enter, or blur, so a day the month lacks is never reported as another date; a two-digit year and input without a year commit on Enter or blur, in every calendar system, and a year of one or three digits is not a date: like other text the field cannot finish, Enter or blur keeps it and shows the unreadable message as the field status (spec:AST-111 FR12, AR3). Each rejection is announced once: a shown status announces itself, and the field's alert carries only a rejection that no status shows. date, date_long, and date_weekday write the committed text in the calendar and read back as the same date; system_date stays Gregorian ISO and the field reads ISO input with it (spec:AST-111 FR13). Text from a custom format function that the field cannot read back cannot be re-committed after an edit (spec:AST-111 FR14). Values stay Gregorian ISO dates (spec:AST-111 FR3). |
spec:AST-111 FR3, FR9–FR14; current source; parser, round-trip, and calendar typed-entry tests |
| FR21 | With a calendar other than gregory or iso8601, every presentation that would show the native control — adaptive-native, the default, deprecated touch and always, and an explicit native — shows the popover on a fine pointer and the bottom sheet on a coarse pointer, because the native control is Gregorian (spec:AST-111 FR15). An explicit native also warns once in development. The bottom sheet shows months of the calendar: each scroller pane lays out one calendar month with calendar labels and day names and the locale's digits, as component:Calendar shows it, and every pane keeps the six-row height, including the five- or six-day thirteenth month of the Coptic and Ethiopic calendars. The month wheel lists the months of the selected calendar year, leap months by name; a year change keeps the month when the new year has it and otherwise moves to its common counterpart (Adar I becomes Adar); year labels carry the era where the calendar has one, such as 令和8, and a year whose first and last days fall in different eras keeps one row, labeled with the era year of the date the wheels show: that year, the selected month, and the day the picker keeps, clamped to the month, else the month's first day. So 2019 reads 平成31 with January selected and 令和元 with July, and the row's text and accessible name change as the month wheel turns, while its size stays the same. The month and year heading takes its era from the same date when the shown month spans an era change, so January 1989 reads 昭和64年1月 for a kept day of 3; every other heading names the era of the month's middle day. A pane's grid name always takes the era of its month's middle day, so that pane reads 平成元年1月. The closed sheet field writes the committed text in the calendar (spec:AST-111 FR16). Values stay Gregorian ISO dates (spec:AST-111 FR3). |
spec:AST-111 FR3, FR15, FR16; current source; calendar presentation, touch calendar, and no-Temporal tests |
| FR22 | In the touch sheet, a month arrow at the range end is hidden; if it held focus, focus moves first to the other month arrow, or to the month-and-year button when both are hidden (spec:AST-085/FR4). |
spec:AST-085/FR4; current source and sheet arrow tests |
| FR23 | Under a coarse primary pointer, turning the bottom-sheet calendar's month or year wheel MUST move a chosen date to the wheels' month, keeping its day: a day that month lacks becomes the month's last day (January 31 becomes February 28), and the moved date MUST stay within min and max. A date that dateConstraints refuses is not chosen, and with no date chosen the wheels move only the calendar. A year that takes the shown month out of the range turns the month wheel onto the nearest reachable month by FR14. Opening the wheels changes nothing, and under a fine pointer the wheels move only the calendar. |
UIDatePicker on the iOS 26.2 simulator; current source |
Allowed variation
- AV1 — Field presentation. Label visibility, description, required/optional indicators, status placement, size, explicit width, and supported InputGroup composition may vary without changing the selected date.
- AV2 — Date reachability. Bounds, custom predicates, week start, month count, placeholder, and committed display format may vary within their public domains.
- AV3 — Surface selection. A caller may force any supported surface or retain the adaptive default; the resulting date value and shared field semantics remain the same.
- AV4 — Theme output. Themes may restyle admitted DateInput targets while shared Field, Calendar, Popover, BottomSheet, Icon, and clear-button owners retain their own targets and semantics.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| empty rest | Labelled field shows the placeholder and calendar affordance without a committed value. | Label, placeholder, size, width |
| committed rest | Field displays the controlled value in the selected committed format. | Format and locale |
| typing | Raw typed text remains visible until commit or reversion. | Parseable text form and locale |
| calendar | Every surface shows the resolved calendar, and the native control gives way to the popover or bottom sheet outside gregory and iso8601; values stay Gregorian ISO. |
Calendar, locale, digits |
| invalid typed text | Field reflects invalid state, announces the error, and preserves the prior committed value. A date the calendar does not have, or one out of range, also shows its message and stays in the field after Enter or blur. | Rejection kind |
| constrained date | Unreachable dates cannot commit on any surface. | Bound or predicate source |
| popover open | Input reflects expanded dialog state and the Calendar is reachable by pointer and keyboard. | Month count and week start |
| bottom sheet open | Touch calendar remains open across date corrections until Save. | Visible month and wheel state |
| native open/closed | Real date input retains its labelled controlled value while the browser/OS owns picker chrome. | Engine-provided picker |
| disabled | Focusable with aria-disabled and disabled paint; mutation and activation are blocked. |
With or without a reason |
| busy | aria-busy on the control; the composed Spinner is silent and the field announces its busy start once (spec:AST-086/FR8). The field keeps its ordinary paint, new commits are blocked, and the native picker stays focusable during a pending Action and may move its transient OS highlight without emitting another change. |
Explicit loading or pending Action |
| clearable | A committed value has one labelled clear action that emits undefined. |
Surface and value |
| status | Error, warning, or success remains named and uses shared status presentation. | Status type, message, placement |
| InputGroup | Group owns outer field chrome while DateInput preserves its field semantics. | Group prefix or suffix content |
Transformation and precedence order
- ORD1 — Surface. Resolve explicit
presentation; otherwise map deprecatednativePicker; otherwise useadaptive-native; with a calendar other thangregoryoriso8601, useadaptive-bottom-sheetin place ofnativeandadaptive-native(FR21); then resolve adaptive values from the primary pointer. - ORD2 — Display. While editing, display pending typed text; otherwise format the controlled or optimistic ISO value with the selected format, provider locale, and resolved calendar.
- ORD3 — Commit. Parse or receive the proposed date, reject it when constrained,
call
onChange, then startchangeActionwith the same proposed value and busy presentation. Typed text proposes a date while typing only when it is complete, and on Enter or blur otherwise (FR20). - ORD4 — Clear. Emit
undefinedthrough ORD3, then apply the selected surface's shipped focus policy: pointer and bottom-sheet fields reclaim focus, while the native field does not reopen the OS picker.
Performance and resources
- PR1 — Bounded calendar window. The bottom-sheet calendar mounts a bounded window of month panes around the visible month rather than the complete reachable century.
- PR2 — Scroll and gesture work. On the native month scroller, scroll-driven measurement and selection updates remain animation-frame throttled or settle-driven. On the month pager under a finger, a drag moves the month grid without a render, and the visible month is reported once per half-month crossed, during the drag and the settle that ends it. Listeners, frames, timers, and observers are cleaned up on deactivation or unmount. Implementation gap: under a finger the touch calendar moves through the native month scroller; it has no drag-driven month pager.
Accessibility contract
- AR1 — Field relationships. Every surface keeps an accessible label; required, description, status, disabled-reason, and busy relationships remain programmatically exposed through the shared Field contract.
- AR2 — Pointer combobox. The typable field exposes combobox state and a dialog popup; ArrowDown and Alt+ArrowDown open it, Escape dismisses it outside active IME composition, and focus is not reclaimed from an intentional destination.
- AR3 — Validation. Invalid typed or native selections are exposed without color
alone; rejected typed input uses an assertive alert and native rejection remains
described to assistive technology. Unreadable text, a date the calendar does not
have, and an out-of-range date each announce a different catalog message
(
spec:AST-111AR3); the last two also show it as the field's error status, in place of a callerstatuswhile the rejected text stays. - AR4 — Disabled and busy focus. A disabled or busy field remains focusable and
exposes its state on the focused control (
spec:AST-085/FR1, FR5); a disabled reason, when given, describes the field's focusable controls while all value mutation and picker activation stay blocked. - AR5 — Native control. The browser/OS date input remains the labelled value owner; the painted committed-value overlay is excluded from the accessibility tree.
- AR6 — Touch calendar. The bottom-sheet Calendar preserves one reachable day per month, arrow-key date movement, named weekday columns, selected/today semantics, single-tab-stop wheels, and exactly one reachable footer action for the visible surface.
- AR7 — Directionality. DateInput's own calendar and clear controls exchange logical
inline sides in RTL while preserving their labels and meanings; Calendar navigation
remains owned and verified by
component:Calendar. - AR8 — The month scroller is an APG grid (
spec:AST-020/FR15), as one composite control: each mounted month pane of the touch calendar's scroller is arole="grid"named for its month, with rows ofrole="gridcell"days, at most one day per pane holding a Tab stop,aria-selectedon the chosen day; ArrowLeft and ArrowRight move by a day following the reading direction, ArrowUp and ArrowDown by a week, Home and End to the ends of the week, PageUp and PageDown by a month, and Enter or Space picks the focused day. Named exception: Shift+PageUp and Shift+PageDown move by a year, as in the APG date picker dialog. Implementation gap: PageUp and PageDown do not page by a month, and Shift+PageUp and Shift+PageDown do not move by a year. - AR9 — The field names its calendar (
spec:AST-111AR2). The pointer field's accessible description names the calendar only when the field's resolved calendar differs from the provider's resolved calendar, elsegregory;gregoryandiso8601count as one calendar. Both are compared after the Gregorian fallback for a runtime withoutTemporal, so a calendar that falls back compares asgregory. With a calendar other thangregoryoriso8601and no callerplaceholder, the empty focused field shows an example date in the calendar's numeric pattern as its placeholder; a callerplaceholdershows in every state and replaces the hint. The example date is today when the field accepts it, else the nearest date it accepts.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Label and supporting text | Shared Field hierarchy surrounds one coherent input boundary. | family:input-fields and component:Field |
Supporting | FR10, AR1 |
| Field surface | One stable bordered input surface contains value and end controls. | family:input-fields/FR1–FR2 |
Prominent | FR1, FR7, FR10 |
| Calendar affordance | Communicates the picker path without replacing typed entry. | Current source and consumer docs | Supporting | FR8 |
| Calendar popover | Presents date selection while preserving Field ownership. | component:Calendar, component:Popover |
Prominent | FR5, FR8–FR9 |
| Bottom-sheet calendar | Presents the same date contract for a coarse pointer. | Current source and spec:AST-043; weekday names: component:Calendar DD1 |
Prominent | FR2, FR4, FR9, FR19, FR23 |
| Native picker | Hands picker chrome to the browser/OS while retaining DateInput field semantics. | spec:AST-043, browser/OS |
Prominent | FR2–FR6, AR5 |
| Clear, busy, and status controls | Use the shared input-family end-control and status relationships. | family:input-fields and shared primitives |
Supporting | FR7, FR11–FR12 |
Theming anatomy
{
"Label": {
"delegatesTo": {"owner": "component:Field", "target": "field-label"}
},
"Text input": {"target": "date-input"},
"Calendar icon": {"target": "date-input-toggle-icon"},
"Calendar popover": {
"delegatesTo": {"owner": "component:Popover", "target": "popover"}
},
"Clear button": {
"delegatesTo": {"owner": "component:Field", "target": "input-clear-button"}
},
"Status message": {
"delegatesTo": {"owner": "component:FieldStatus", "target": "field-status"}
}
}
The date-input target owns the composite field surface. The
date-input-toggle-icon target reflects collapsed and expanded states on the icon
itself. The shared input-clear-icon target owns clear-glyph theming; DateInput adds no
clear-glyph target of its own.
Family and system relationships
family:input-fieldsowns stable field sizing, end-control space, grouped adaptation, disabled reasons, loading, Transition Actions, status placement, base-prop and part-styling targets, and the iOS-only focus-zoom floor.family:overlay-dismissalowns topmost Popover and BottomSheet dismissal. DateInput's Popover path uses the shared owner; its bottom-sheet path inherits BottomSheet's recorded adoption gap. DateInput owns only selection, open-state requests, and focus policy.spec:AST-043owns the picker presentation vocabulary, default, native fallback, deprecated mapping, and precedence.spec:AST-085owns focusable disabled and busy controls: no nativedisabled, blocked change paths, distinct disabled and busy paint, and focus kept when a control becomes inactive.spec:AST-086owns busy announcements: the composed Spinner is silent and the field announces each busy start once.architecture:component-theming-surfaceowns target admission, painting-element placement, state reflection, and anatomy mapping.architecture:interaction-modalityowns input-modality principles; DateInput uses the primary pointer to choose an interaction surface rather than a width breakpoint.architecture:public-component-apiowns the package/export and public-prop boundary.spec:AST-111owns calendar selection, the supported calendars, Gregorian ISO values, theTemporalboundary, typed entry, and presentations in a calendar; FR20, FR21, AR3, and AR9 project its FR3, FR9–FR16, AR2, and AR3.component:Calendarowns the popover grid in the calendar.
spec:AST-013 FR12 exception — calendars that need Temporal
- Capability: typed entry, committed text, and the bottom sheet in
calendars other than
gregory,iso8601,buddhist,roc, andjapanese, which need the runtime'sTemporal. - Reduction: where
Temporalis missing, as in Safari on macOS and iOS, the field reads, writes, and shows Gregorian dates, its presentations resolve as they do forgregory, and it warns once in development, naming a polyfill (spec:AST-111FR5). An application that loads aTemporalpolyfill gets the full calendar. When a server and a browser usechineseordangiimplementations that disagree on a month start, React renders the differing text again on the client (spec:AST-111FR19). - Preserved obligations:
spec:AST-013FR7 and FR8, and FR9 outside thatchineseanddangicase. The Gregorian field keeps every interaction, label, and announcement, and Buddhist, Minguo, and Japanese entry and bottom sheets work withoutTemporal. - Evidence: real Chromium and Firefox typing in Persian, Hebrew, Japanese,
and Buddhist fields with native
Temporal, withTemporalremoved and a polyfill loaded, and withTemporalremoved and no polyfill; the Persian bottom sheet, the Hebrew wheels in a leap year, and the Japanese era wheel in real Chromium, Firefox, and WebKit in the same three modes. - Owner:
nynexman4464. - Review condition: Safari ships
Temporal.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, ORD2 | DateInput.test.tsx "displays formatted date when value is provided", "calls onChange on blur when input is valid", "calls onChange with undefined when input is cleared and blurred", "clears pending input when value changes externally"; NativeDateField.test.tsx "keeps the control's own value ISO", "fires onChange with the ISO date the control reports" |
Typed, cleared, external value; native | A committed value kept beside value, a non-ISO change, or pending text that survives an external change fails. |
audit:DateInput/behavior |
| FR2, FR3, FR4, ORD1 | Presentation.test.tsx cases; DateInputTouch.test.tsx surface-selection cases; NativeDateField.test.tsx nativePicker cases |
Each presentation on fine and coarse pointers; deprecated mappings; tablet and touchscreen laptop | A wrong surface, a lost deprecated mapping, nativePicker winning, or width-based resolution fails. Evidence gap: no test asserts the development warning. |
audit:DateInput/behavior |
| FR5 | DateInput.test.tsx min, max, and dateConstraints typed cases; DateInputTouch.test.tsx "disables days outside min/max and refuses to commit them", "honors custom date constraints"; NativeDateField.test.tsx "refuses an out-of-range date and announces it", "refuses a date dateConstraints rejects" |
Typed, sheet, native; bounds and predicates | A constrained date that commits on any surface fails. Evidence gap: no test asserts constraints on a popover Calendar pick. | audit:DateInput/behavior |
| FR6 | DateInput.test.tsx format cases, including "updates when the InternationalizationProvider locale changes (#5074)" and "does not apply format to in-progress typed input" and "typing a day-first date in en-GB never reports a month-first date"; dateParser.test.ts "in a day-first locale, never reads numeric text month-first outside the locale-ordered forms"; NativeDateField.test.tsx format and locale cases; DateInputTouch.test.tsx "updates the field and open picker when the provider locale changes"; calendarDateParser.test.ts "reads month and era names of the locale and English, in every width", "reads any Unicode decimal digits, in mixed scripts" |
Named and function formats; locale change; localized month names and digits | A format that ignores the locale or rewrites typed text, or a localized committed value that cannot be retyped, fails. | audit:DateInput/i18n |
| FR7, ORD3 | DateInput.test.tsx "runs changeAction after onChange for a typed date"; NativeDateField.test.tsx "runs changeAction after onChange and exposes the pending state"; DateInputTouch.test.tsx "runs changeAction and shows a busy state"; BusyOwnerAnnouncement.test.tsx DateInput cases; DateInputTouch.test.tsx "announces a busy start from a pick inside the open sheet, not behind it (spec:AST-086 FR8, Platform support)" |
Typed, native, sheet | An Action before onChange, a missing busy state, or a missing busy announcement fails. |
audit:DateInput/behavior |
| FR8, AR2 | DateInput.test.tsx "opens the calendar popover on ArrowDown (keyboard, forms-13)", "opens the calendar popover on Alt+ArrowDown (keyboard, forms-13)", "input has aria-expanded attribute", "combobox input has aria-haspopup="dialog" attribute", "moves focus into the calendar on each open from the toggle"; DateInputTouch.test.tsx "opens from the keyboard, APG combobox style"; DateInput.test.tsx "press inside and outside the open calendar" cases |
Pointer and touch fields | A missing open path, combobox state, or focus move fails. Evidence gap: no test asserts Escape outside IME composition on the popover. | audit:DateInput/accessibility |
| FR9 | DateInputTouch.test.tsx "commits the tapped day and LEAVES the sheet open", "lets a second tap correct the first, still without closing", "Save closes the sheet without touching the value" |
Sheet picks and Save | A sheet that closes on a pick or a Save that changes the value fails. Evidence gap: no test asserts that a popover Calendar pick closes the popover. | audit:DateInput/behavior |
| FR10 | DateInput.fr10.test.tsx styling and per-surface cases ("has no root styling props and has the container* and control* parts", "rejects root xstyle, className, and style at compile time", "keeps control* on the control box in a horizontal-labels FormLayout") and handler-composition cases; DateInput.test.tsx InputGroup cases; DateInputTouch.test.tsx "drops the Field wrapper inside an InputGroup" |
Standalone, grouped, horizontal labels; every surface | A root styling prop, control* off the control box, or Field chrome inside a group fails. Evidence gap: no test asserts the field height or its growth with text size (the FR10 gap). |
audit:DateInput/layout |
| FR11, ORD4 | DateInput.test.tsx hasClear cases; DateInputTouch.test.tsx "clears from the field", "returns focus to the field without letting the page scroll"; NativeDateField.test.tsx "clears the value without taking focus back", "runs clear through changeAction after onChange" |
Pointer, sheet, native clear | A clear that does not emit undefined, a native clear that takes focus, or a clear shown while disabled fails. Evidence gap: no test covers the clear control unmounting under focus (the FR11 gap). |
audit:DateInput/behavior |
| FR12, AR4 | DateInput.test.tsx disabled, loading, and disabledMessage cases (including "does not call a caller onClick while disabled (AST-085 FR2)" and "links the reason tooltip from the calendar button too (AST-085 FR5)"); DateInputTouch.test.tsx open-sheet disablement and disabled cases; NativeDateField.test.tsx "keeps a disabled control focusable and its toggle inert (AST-085 FR1, FR2)", "does not call a caller onClick while disabled (AST-085 FR2)"; DateInput.test.tsx disabled theme-state cases |
Disabled with and without a reason; loading; open picker becoming disabled | Native disabled, a change or open while disabled, a caller onClick while disabled, a reason not linked from each focusable control, or a missing aria-busy fails. Evidence gap: no test asserts that caller key, paste, or pointer handlers are skipped while disabled (the FR12 gap) or the busy-only paint. |
audit:DateInput/accessibility |
| FR12 | DateInput.test.tsx "typed text while the field is disabled or busy" cases and "keeps a cleared draft without committing it when the field becomes disabled (AST-085 FR2)" |
isLoading, isDisabled, and a changeAction save that takes or fails; unfinished, valid, reported, and cleared text; shown rejection; new value |
A commit, onChange, reset, or rejection while disabled or busy, a rejection that does not return once editable, typed text that outlives a new value, or reported text that outlives the lock fails. |
audit:DateInput/behavior |
| AR1, AR3, AR5 | DateInput.test.tsx label, required, description, status, and invalid-input cases ("announces an alert message when typed input is invalid", "resolves the invalid-date announcement from the i18n catalog"); NativeDateField.test.tsx "keeps the overlay out of the accessibility tree", "keeps the field labelled, required-marked, and ref-forwarded"; DateInputTouch.test.tsx "associates the label natively, so the field is named without ARIA" |
Every surface | A missing label, required, description, status, or invalid announcement, or an exposed native overlay, fails. | audit:DateInput/accessibility |
| AR6, AR8, PR1 | DateInputTouch.test.tsx calendar-surface cases ("mounts a window of months around the visible one, not the whole century", "leaves exactly one day per month tab-reachable", "gives a spilled date no tab stop in the pane that borrows it", "moves keyboard focus by date, across the month boundary", "follows the reading direction under RTL: ArrowLeft moves to the next day", "moves a week at a time with the vertical arrows", "labels the columns with three-letter weekday names", "marks the selection and today") and wheel cases ("is a single tab stop driven by the arrow keys", "shows exactly one footer action, and only the visible one is reachable") |
Touch calendar and wheels; RTL | A second Tab stop per month, a wrong arrow move, reversed RTL arrows, an unbounded month window, or more than one reachable footer action fails. Evidence gap: no test asserts Home, End, PageUp, PageDown, Shift+PageUp, Shift+PageDown (the AR8 gap), or Enter and Space on a day. | audit:DateInput/accessibility |
| AR7 | apps/storybook/rtl-audit/targets.json DateInput entry; DateInputTouch.test.tsx RTL scroll-offset cases |
RTL | A changed audit target or RTL offset fails. | audit:DateInput/rtl |
| PR2 | MonthScrollerSettle.test.tsx cases; DateInputTouch.test.tsx "a rest position between two months" cases |
Settle and re-snap | A scroller that never settles or corrects mid-gesture fails. Evidence gap: no test asserts listener, frame, and observer cleanup on unmount, drags a month pager, or counts the visible-month reports per half-month (the PR2 gap). | audit:DateInput/behavior |
| FR13 | Wheel.test.tsx, the wheel every sheet renders: "stopping below the minimum travels on to the minimum and commits it there", "stopping past the maximum travels back to the maximum", "a stop on another disabled row still travels to the bounds", "opening on a value outside the bounds parks on it without travelling or committing", "a drag that comes back to rest on a committed value outside the bounds stays there and commits nothing", "never commits a disabled row, even with nowhere valid to go", and nearestEnabledIndex "breaks a tie toward the committed row"; PickerWheel.test.tsx, the wheel under a finger: "turns on to the minimum after resting below it, and commits that", "opening on a value outside the bounds commits nothing", "rests back on a committed value outside the bounds and commits nothing"; WheelRest.a11y.chromium.spec.ts in the TimeInput sheet: "a wheel dragged below the minimum comes to rest on the minimum", "a wheel dragged onto a row inside the bounds commits that row"; DateInputTouch.test.tsx "bounds the year wheel to the reachable range" (rows outside the bounds are disabled). |
Below the minimum, above the maximum, on another disabled row; opened on a value outside the bounds and rested back on it after a drag; DateInput, TimeInput, and DateTimeInput sheets | A wheel that returns to its committed row, skips the nearest enabled row, breaks a tie away from the committed row, or commits on opening or on a rest back on its committed row fails. | audit:DateInput/behavior |
| FR14 | Wheel.test.tsx "turns onto a value set while it is shown, as a bound clamping the time after another wheel turned"; WheelRest.a11y.chromium.spec.ts in the TimeInput sheet: "a meridiem change past the maximum turns the hour wheel onto it, frame by frame"; PickerWheel.test.tsx, the wheel under a finger: "turns the wheel onto its row, as a bound clamping the time", "turns on from where the wheel is drawn when the value changes again during that turn", "turns onto a tapped row and commits it on arrival", "turns onto a tapped row on the settle spring, from rest, and commits it on arrival", "keeps the spring whatever the theme’s duration and easing tokens", "turns onto a key’s row on the same spring", "commits each arrow key at once, stepping from the row it is heading to", "commits a clicked row at once and never a disabled one". |
A bound clamping the value of a shown wheel after another wheel turned, in DateInput, TimeInput, and DateTimeInput sheets; a tapped row, an arrow key and a row click | A wheel that jumps to the new row fails, and so does a tap that commits at the lift, or a key or click that waits for a turn. | audit:DateInput/behavior |
| FR15 | WheelPinchZoom.a11y.chromium.spec.ts "a pinch over an open picker wheel zooms the page and changes no value"; DateInputTouch.test.tsx "leaves a two-finger pinch to the page over the wheels". PickerWheel.test.tsx "follows a trackpad’s fingers, coasts on at their lift and rests on a row, as a finger’s flick does", "rests on the nearest row after a slow trackpad drag that stops, without coasting", "turns one row for a mouse wheel’s notch, as an arrow key does, with no coast", "turns three rows for three notches, one each", "leaves a ctrl-wheel, a trackpad pinch, to the page"; Wheel.interaction.browser.spec.ts "one mouse-wheel notch turns the touch column one row, as an arrow key does; three turn it three" (Chromium) and the trackpad flick and slow stopped drag (WebKit, whose driver sends a trackpad's deltas). |
A trackpad scroll and its lift; a slow stopped trackpad drag; one and three mouse-wheel notches; a ctrl-scroll over an open wheel | A trackpad scroll that does not follow, a lift that stops dead or coasts at the browser's rate, a notch that turns more or less than one row or coasts, or a ctrl-scroll that turns the wheel fails. | audit:DateInput/behavior |
| FR16 | DateInput.test.tsx "Enter submits the form when nothing is typed, and commits typed text without submitting" "Enter on a disabled field does not submit the form" and "Enter on a busy field does not submit the form" |
Nothing typed; typed text; disabled; busy (isLoading) |
An Enter that is prevented with nothing typed, or that submits before typed text commits, fails. | — |
| FR17 | TimeInput/Presentation.test.tsx: "at a 12:00–17:00 bound, ArrowDown from 5 PM commits nothing and ArrowDown from 12 PM commits 1 PM, under a finger", "… under a mouse". Wheel.test.tsx, the column under a mouse, and PickerWheel.test.tsx, the wheel under a finger: "at a 12:00–17:00 bound, moves a key to the next enabled row and stops at the last one", "at a 12:00–17:00 bound on a 12-hour hour wheel, steps in time order: nothing after 5 PM, and 1 PM after 12 PM", "moves a key from a row outside the bounds onto the first enabled row in its direction". |
At a 12:00–17:00 bound, ArrowDown from 5 PM commits nothing and ArrowDown from 12 PM commits 1 PM, under a finger and a mouse | A key that commits a disabled value, leaves time order, or strands 12 PM fails. | audit:DateInput/behavior |
| FR18 | PickerWheel.test.tsx "marks no row while a fling coasts, then the row it rests on", "marks no row while the wheel snaps or turns, then the row it rests on". |
A fling's coast, a slow release's snap and a key's turn, each to its rest | A row that carries the band's accent mark while the wheel moves, or a rest with no marked row, fails. | audit:DateInput/behavior |
| FR19 | DateInputTouch.test.tsx "labels the columns with three-letter weekday names", "labels the columns in %s with the same names as the Calendar header" for fr-FR, pt-PT, pl-PL, and id-ID, "rotates the weekday header with weekStartsOn" |
English; a locale within Calendar DD1's four-character limit; locales above it; a locale with no shipped weekday data; weekStartsOn rotation |
A weekday row that differs from the Calendar header names for the same locale, or that does not rotate with weekStartsOn, fails. |
— |
| FR20, AR3, AR9 | calendarDateParser.test.ts reading, year, rejection-kind, completeness, committed-text, and calendar-name cases; calendarDateParser.roundtrip.test.ts committed text and format hint of every calendar in its native locale, English, and Swedish, sampled from 1900 through 2100; DateInput.calendar.test.tsx ("reports one Persian date typed in Persian digits, only when complete", "reads a plain Adar in a Hebrew leap year as Adar II", "reads Japanese era dates and rejects a year outside its era", "rejects a date the calendar does not have and keeps it on blur", "shows an out-of-range error with the bounds in the calendar", "announces a different message for each kind of rejection", "fires once for a day-first date typed one key at a time", "commits Gregorian text that only parseDateInput reads, on blur only", "commits a day-first date that does not exist month-first, on blur only", "commits a month-first date that does not exist day-first, on blur", "never falls back to a month-first reading in a day-first locale", "keeps a one-digit year on %s and announces it as invalid", "reports no date while %s %s text grows to a day the month lacks", "reports a retyped date again after the caller keeps its value", "still rejects a Gregorian date that does not exist in either order", "never reads a date that does not exist in another calendar with parseDateInput", "shows a format hint in the empty focused field", "shows a caller placeholder instead of the format hint", "uses max when max is before today", "uses min when min is after today", "uses the nearest weekday when today is a disabled Saturday", "names the calendar in the description", "names no calendar when the field uses the provider calendar", "names the Gregorian calendar inside a Persian provider", "names no calendar for an iso8601 field in a Gregorian provider", "names the Persian calendar without a provider calendar"); real Chromium and Firefox typing with native Temporal, a polyfill, and no Temporal |
Persian digits, Hebrew leap year, Japanese era change, Buddhist bounds, partial input, Gregorian day-first typing, a one-digit Gregorian year, no Temporal |
A typed date reported before it is complete, an adjusted date, a failed round trip, Gregorian text that FR20 says commits failing to commit on blur, a one-digit year that commits or reverts silently, a rejection announced twice, a shared rejection message, a missing hint, a hint that replaces a caller placeholder, a hint example the field rejects, a calendar description that is missing or that repeats the provider's calendar, or a non-ISO value fails. Evidence gap: no WebKit run; no server render and hydrate test. | audit:DateInput/behavior |
| FR21 | DateInput.calendarPresentation.test.tsx (every presentation and deprecated nativePicker value in Gregorian and Persian on fine and coarse pointers; "warns once when an explicit native cannot show the calendar"); DateInputTouch.calendar.test.tsx ("lays out a Persian month with its days, labels and locale digits", "shows Adar I and Adar II as separate months in a Hebrew leap year", "keeps six rows for the Ethiopic thirteenth month", "lists 13 months in a Hebrew leap year and 12 in a common year", "labels Japanese years with their era", and the month-model round trips); calendarSystem.test.ts formatCalendarYearLabel and calendarYearSpansEras cases (2019 in January and May, 1989 on January 3 and 22, 1926, 1912, and 2020); DateInputTouch.calendar.test.tsx "names the era of the shown month for a year with an era change" and the split-month heading cases (January 3, 1989; December 26, 1926); calendarSystem.test.ts formatCalendarMonthLabel kept-day cases; DateInput.noTemporal.test.tsx; real Chromium, Firefox, and WebKit bottom sheets and popovers with native Temporal, a polyfill, and no Temporal |
Persian, Hebrew leap and common years, Ethiopic thirteenth month, Japanese eras, no Temporal |
A native date control for a non-Gregorian calendar, a wheel with 12 months for a 13-month year, a pane of another height, a lost leap month, a missing era, a year with an era change labeled with an era other than that of the shown date, or a non-ISO value fails | audit:DateInput/behavior |
| FR22 | DateInputTouch.test.tsx "moves focus to the other arrow when the focused arrow reaches the end of the range and hides" and "moves focus to the other arrow when a swipe reaches the end of the range while an arrow holds focus" |
Sheet month arrows at the first and last month of a range | Focus left on a hidden arrow, or dropped to the document body, fails. | audit:DateInput/behavior |
| FR23 | DateInputTouch.test.tsx "under a finger: moves the chosen date with the wheels, keeping its day", "under a finger: clamps a day the new month lacks to its last day", "under a finger: takes a year change past the range on to its nearest reachable month, date and month wheel too", "under a finger: opening the wheels on a date outside the range changes nothing until a wheel moves", "under a finger: keeps a date a custom constraint refuses, while the calendar moves", "only moves the calendar when no date is chosen", "with a mouse the scrolling wheels move only the calendar, not the date", "under a finger: a date the wheels move runs changeAction after onChange, shows at once, and is busy (family:input-fields FR6)", "moves a date to another month keeping its day, within the month and the bounds"; MonthYearWheels.interaction.browser.spec.ts "a turn of the month wheel moves the chosen date, keeping its day", "the scrolling month wheel moves only the calendar, not the date"; DateInputTouch.calendar.test.tsx "moves a date by calendar months, keeping its day of the month" |
A month turn; a day the new month lacks; a year past the range; no date; a refused date; opened outside the range; a mouse | A wheel that leaves the chosen date behind, keeps a day the month lacks, leaves the range, chooses a refused date, changes the value on opening, or moves the date under a mouse fails. | audit:DateInput/behavior |
| Theming anatomy | DateInput.test.tsx clear-icon and calendar-toggle icon theme-target cases; themingTargets.test.ts; scripts/check-knowledge.mjs |
Toggle, clear glyph, disabled root | A missing or moved target, or a stale anatomy mapping, fails. | audit:DateInput/theming |
Current-state impact
- Caller handlers while disabled (FR12). Caller key, paste, and pointer
handlers run on a disabled field on every surface; only
onClickis skipped, againstspec:AST-085FR2. - Fixed field height (FR10). The field holds the shared element height
instead of growing with a set text size, against
spec:AST-102FR4. - Clear control under focus (FR11). A clear control that unmounts while
focused drops focus to the page, against
spec:AST-085FR4. - Selection tick haptics. Under a finger each row that reaches the band
ticks with a short vibration where the browser has the Vibration API, as on
Android. iOS Safari has none, so the tick is silent there (
spec:AST-094FR23). - Month paging (AR8). PageUp and PageDown do not page the touch calendar by a month, and Shift+PageUp and Shift+PageDown do not move it by a year, as AR8 states they do.
- Month pager (PR2). Under a finger the touch calendar moves through the native month scroller rather than a drag-driven pager.
Decision log
The governing presentation decisions are spec:AST-043/DEC-1 through DEC-3.
DEC-1 — A wheel resting on a disabled row continues to the nearest enabled row
Reference: component:DateInput/DEC-1
Decider: cixzhang, 2026-10-25
The bottom-sheet picker wheel rests as UIDatePicker's does: a wheel that stops on
a disabled row (outside min/max) continues to the nearest enabled row, a tie
going toward the committed row, and selects it there. It applies wherever the
wheel is rendered: DateInput's month and year wheels and the wheels of
DateTimeInput and TimeInput. Opening a bounded sheet never changes an untouched
value: a controlled value outside the bounds stays, and an empty field stays
empty.
Rejected: returning to the previous row, which makes the person scroll again to reach the bound.
DEC-2 — The sheet wheels' rows lie flat under a finger
Reference: component:DateInput/DEC-2
Decider: cixzhang, 2026-11-01
Under a finger, each sheet wheel in DateInput, TimeInput, and DateTimeInput lays its rows flat at the scrolling column's pitch and fades them toward its edges, without tipping or shrinking. The fade stops at 70% opacity at the edges, so every row in view meets WCAG AA contrast in every shipped theme. Under a mouse, the scrolling column tips and fades its rows on a scroll timeline.
Rejected: a UIPickerView-style cylinder look.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables or examples, current audit results, implementation steps, Calendar/Popover/BottomSheet internals, or input-family and presentation-system rules. It links to those owners and records only DateInput's observable composition and current evidence boundaries.