An open source design system that's fully customizable and agent ready
schema_version: 4 template_version: 1 kind: system-spec id: spec:AST-043 authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-09-24 phase: accepted owners: [imdreamrunner] affects_architecture: [architecture:public-component-api] affects_families: [family:input-fields] affects_contributing: [] affects_consumer_docs: []
Date and time input presentation system spec
Intent
One prop question — which surface collects the value — currently has two answers:
ContextMenu,DropdownMenu,MoreMenu,Selector, andMultiSelectorusepresentation('popover' | 'bottom-sheet' | 'adaptive').DateInput,DateTimeInput, andTimeInputusenativePicker('touch' | 'always' | 'never'), which names only the native surface and hides that Astryx-on-desktop, Astryx-on-touch (bottom sheet), and — forTimeInput— a plain text field with no picker are different surfaces.
This spec gives the three date/time inputs a presentation prop whose values
distinguish every surface, preserves today's default and deprecated-prop
behavior exactly, and deprecates — but does not remove — nativePicker. No
existing record owns this cross-component vocabulary (searched: component
contracts, architecture:public-component-api, family:input-fields,
nativePicker / presentation / AdaptivePresentation in code and records).
Non-goals
- Any surface's appearance, anatomy, or interaction — unchanged and owned by
each component, except the new surfaces DEC-3 approves. Eligibility/fallback
behavior changes only as FR2 states (for
native). - Renaming menu/selector
presentationor theiradaptive(OQ1). - Removing
nativePicker— its concrete mapping remains owned here, while the deprecation record, cleanup id, Changeset, paired-minor treatment, and migration evidence followspec:AST-017FR28–FR44 and the codemod followsspec:AST-040.
Requirements
FR1 — Prop, values, and surfaces.
DateInput,DateTimeInput, andTimeInputMUST accept optionalpresentation, default'adaptive-native':Value Fine pointer Coarse pointer text-inputText field Text field popoverAstryx desktop Astryx desktop bottom-sheetAstryx sheet Astryx sheet nativeNative Native adaptive-bottom-sheetAstryx desktop Astryx sheet adaptive-nativeAstryx desktop Native (FR2) Surface DateInputDateTimeInputTimeInputText field — (not accepted) — (not accepted) Typed field (today's never)Astryx desktop Typed field + calendar popover Typed fields + date/time popovers — (fine resolves via Text field; popoveris not a distinctTimeInputsurface)Astryx sheet BottomSheet calendar BottomSheet date/time wheels BottomSheet time wheels (DEC-3) Native Browser/OS date picker Browser/OS date + time pickers Browser/OS time picker text-inputisTimeInput-only (maintainer-confirmed: imdreamrunner, 2026-09-25) — it exists solely for its releasednever(FR3); a picker-less date field has no released need and would silently drop the calendar affordance:DateInputandDateTimeInputMUST NOT accept it — their exportedpresentationtypes exclude it, so it is a compile-time error, with no runtime surface defined for it. Their five values are `popover | bottom-sheet | native | adaptive-bottom-sheet |
adaptive-native; only TimeInput` accepts all six.
Coarse uses the inputs' existing pointer test, no width condition. Forced
values (popover on coarse, bottom-sheet where not reached today, and
text-input on TimeInput) MUST render the named surface, never silently
substitute another. In a calendar other than gregory or iso8601,
DateInput and DateTimeInput resolve native and adaptive-native to
Astryx desktop on a fine pointer and Astryx sheet on a coarse pointer (FR2,
spec:AST-111 FR15).
FR2 — Fallback split for native. Explicit
presentation="native"MUST always show the native surface, with no eligibility fallbacks — a state the native control cannot express (seconds, non-default step/increment, preset time options, no usable native control) is the caller's explicit choice. The one exception is the calendar: with a calendar other thangregoryoriso8601, explicitnativeuses the Astryx surface and warns in development (spec:AST-111FR15).presentation="adaptive-native"— including the default andnativePicker="touch"— MUST keep the released fallbacks: in those same states it falls back to the component's Astryx surface (per-segment forDateTimeInput: date may go native while time falls back), exactly as released today. DeprecatednativePicker="always"without an explicitpresentationis the third case (FR3): it MUST keep its own released fallbacks, so its behavior does not change — only an explicitpresentation="native"opts into no-fallback.FR3 — Default and
nativePickerpreserved exactly. Omitting both props MUST behave as today'snativePicker="touch".nativePickerand its exported types MUST remain, marked@deprecated, resolving exactly as released for unmigrated and migrated callsites alike:nativePickerDateInput/DateTimeInputTimeInputtouchadaptive-nativeadaptive-nativealwaysnative(legacy, FR2)native(legacy, FR2)neveradaptive-bottom-sheettext-inputalwaysmaps to thenativesurface on every pointer, except in a calendar other thangregoryoriso8601(FR2), but retains the released eligibility fallbacks (FR2):hasSeconds, non-default step/increment, preset time options, or no usable native control keep the Astryx surface, exactly as released. It is therefore not identical to explicitpresentation="native", which never falls back; migration (codemod or by hand) topresentation="native"is what changes those states, deliberately. (TimeInput's releasedneveris the typed field on every pointer; a sheet forTimeInputcomes only from explicitpresentation="bottom-sheet" | "adaptive-bottom-sheet".) Preserving the prop with equivalent meaning is nonbreaking (spec:AST-017FR4).FR4 — Precedence. If both props are set,
presentationMUST win andnativePickerMUST be ignored, regardless of order or pointer. A development-only warning SHOULD name the FR3 replacement whenevernativePickeris used, and MUST NOT fire in production.FR5 — Docs and types agree. Each component's consumer docs (en + zh), exported types, and Storybook controls MUST show FR1 values/default (six values on
TimeInput, five onDateInput/DateTimeInput) andnativePickeronly as deprecated with its FR3 replacement.
Platform support
- Floor: unchanged (
spec:AST-013, each component); no value renders no picker (FR2'sadaptive-nativefallback guarantees an Astryx surface). - Browser evidence: each FR1 value on fine/coarse browsers, plus FR2 fallback states, because jsdom reports neither pointer type nor native pickers.
Current-state impact
packages/core/src/{DateInput,DateTimeInput,TimeInput}: addpresentation, deprecatenativePicker(FR1–FR4); docs/types (FR5); DEC-3 new surfaces; implementing PR adds thespec:AST-017FR8 migration + nonbreaking Changeset. Menu/selector components: unchanged.
Verification
| Contract | Verification | Representative states | Mutation or failure expectation |
|---|---|---|---|
| FR1 | Unit tests per input + real-browser check | Per-component values × fine/coarse, incl. forced + TimeInput sheet; text-input type-rejected outside TimeInput |
Wrong/substituted surface fails |
| FR2 | Unit tests, native requested | Seconds, step≠default, presets, no usable native: explicit native stays native; adaptive-native and deprecated always fall back |
Any eligibility fallback under explicit native, or none under adaptive-native/always, fails |
| FR3–FR4 | Unit tests: default, deprecated, dual-prop | Omitted; touch/always/never per component; both props, any order |
Mapping drift (incl. TimeInput:never→sheet) or nativePicker winning fails |
| FR5 | Doc/type consistency tests | All 3 components, en + zh | Documented-but-untyped value/default fails |
Decision log
DEC-1 — Unify on presentation; values name the surface
Reference: spec:AST-043/DEC-1
Decider: imdreamrunner, 2026-09-24
Builders already meet presentation on menus/selectors for this question.
Rejected: literal rename to 'touch'|'always'|'never' (hides desktop vs
sheet vs text field), one astryx value (same loss), shared 'adaptive'
(hides sheet vs native), two coexisting props with overlapping meaning.
DEC-2 — Default adaptive-native; deprecate, don't remove
Reference: spec:AST-043/DEC-2
Decider: imdreamrunner, 2026-09-24
adaptive-native is today's default renamed; nativePicker stays working
(FR3/FR4) — removal is the breaking event, not the rename. Rejected:
defaulting to adaptive-bottom-sheet, and nativePicker winning over
presentation.
DEC-3 — Forced surfaces and TimeInput sheet approved
Reference: spec:AST-043/DEC-3
Decider: cixzhang, 2026-09-24
Forced popover on coarse, bottom-sheet on fine, and a new TimeInput
bottom sheet (the time half of DateTimeInput's sheet) are approved new
surfaces. This closes the former open question on FR1's forced reach;
implementation may rely on FR1 as written.
Open questions
- OQ1 — Menu/selector rename (
human-api): later rename theiradaptivetoadaptive-bottom-sheetunder this deprecation pattern? Out of scope.