Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(spec): AST-043 unify date/time input presentation, deprecate nativePicker (#6614)

Xinzi Zhou0899f21aeb53
diff --git a/docs/specs/AST-043-input-presentation/spec.md b/docs/specs/AST-043-input-presentation/spec.md
new file mode 100644
index 0000000000..3bb0300244
--- /dev/null
+++ b/docs/specs/AST-043-input-presentation/spec.md
@@ -0,0 +1,177 @@
+---
+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`, and `MultiSelector`
+ use `presentation` (`'popover' | 'bottom-sheet' | 'adaptive'`).
+- `DateInput`, `DateTimeInput`, and `TimeInput` use `nativePicker`
+ (`'touch' | 'always' | 'never'`), which names only the native surface and
+ hides that Astryx-on-desktop, Astryx-on-touch (bottom sheet), and — for
+ `TimeInput` — 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 `presentation` or their `adaptive` (OQ1).
+- Removing `nativePicker` — breaking under `spec:AST-017`, needs its own
+ record. Migration tooling follows `spec:AST-017` FR8 using the FR3 mapping.
+
+## Requirements
+
+- **FR1 — Prop, values, and surfaces.** `DateInput`, `DateTimeInput`, and
+ `TimeInput` MUST accept optional `presentation`, default
+ `'adaptive-native'`:
+
+ | Value | Fine pointer | Coarse pointer |
+ | ----------------------- | -------------- | -------------- |
+ | `text-input` | Text field | Text field |
+ | `popover` | Astryx desktop | Astryx desktop |
+ | `bottom-sheet` | Astryx sheet | Astryx sheet |
+ | `native` | Native | Native |
+ | `adaptive-bottom-sheet` | Astryx desktop | Astryx sheet |
+ | `adaptive-native` | Astryx desktop | Native (FR2) |
+
+ | Surface | `DateInput` | `DateTimeInput` | `TimeInput` |
+ | -------------- | ------------------------------ | --------------------------------- | --------------------------------------------------------------------------------- |
+ | Text field | Typed field, no picker | Typed fields, no picker | Typed field (today's `never`) |
+ | Astryx desktop | Typed field + calendar popover | Typed fields + date/time popovers | — (fine resolves via Text field; `popover` is not a distinct `TimeInput` surface) |
+ | 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 |
+
+ Coarse uses the inputs' existing pointer test, no width condition. Forced
+ values (`popover` on coarse, `bottom-sheet`/`text-input` where not reached
+ today) MUST render the named surface, never silently substitute another.
+
+- **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.
+ `presentation="adaptive-native"` — including the default and
+ `nativePicker="touch"` — MUST keep the released fallbacks: in those same
+ states it falls back to the component's Astryx surface (per-segment for
+ `DateTimeInput`: date may go native while time falls back), exactly as
+ released today. Deprecated `nativePicker="always"` without an explicit
+ `presentation` is the third case (FR3): it MUST keep its own released
+ fallbacks, so its behavior does not change — only an explicit
+ `presentation="native"` opts into no-fallback.
+
+- **FR3 — Default and `nativePicker` preserved exactly.** Omitting both props
+ MUST behave as today's `nativePicker="touch"`. `nativePicker` and its
+ exported types MUST remain, marked `@deprecated`, resolving exactly as
+ released for unmigrated and migrated callsites alike:
+
+ | `nativePicker` | `DateInput` / `DateTimeInput` | `TimeInput` |
+ | -------------- | ----------------------------- | ---------------------- |
+ | `touch` | `adaptive-native` | `adaptive-native` |
+ | `always` | `native` (legacy, FR2) | `native` (legacy, FR2) |
+ | `never` | `adaptive-bottom-sheet` | `text-input` |
+
+ `always` maps to the `native` surface on every pointer 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
+ explicit `presentation="native"`, which never falls back; migration
+ (codemod or by hand) to `presentation="native"` is what changes those
+ states, deliberately. (`TimeInput`'s released `never` is the typed field on
+ every pointer; a sheet for `TimeInput` comes only from explicit
+ `presentation="bottom-sheet" | "adaptive-bottom-sheet"`.) Preserving the
+ prop with equivalent meaning is nonbreaking (`spec:AST-017` FR4).
+
+- **FR4 — Precedence.** If both props are set, `presentation` MUST win and
+ `nativePicker` MUST be ignored, regardless of order or pointer. A
+ development-only warning SHOULD name the FR3 replacement whenever
+ `nativePicker` is 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) and `nativePicker` only as deprecated with its FR3 replacement.
+
+### Platform support
+
+- Floor: unchanged (`spec:AST-013`, each component); no value renders no
+ picker (FR2's `adaptive-native` fallback 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}`: add `presentation`,
+ deprecate `nativePicker` (FR1–FR4); docs/types (FR5); DEC-3 new surfaces;
+ implementing PR adds the `spec:AST-017` FR8 migration + nonbreaking
+ Changeset. Menu/selector components: unchanged.
+
+## Verification
+
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| -------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| FR1 | Unit tests per input + real-browser check | 6 values × fine/coarse, incl. forced + `TimeInput` sheet | 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 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 their `adaptive`
+ to `adaptive-bottom-sheet` under this deprecation pattern? Out of scope.