An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): DateTimeInput records its shipped contract as current (#8878)
Cindy Zhanga7ecf842f751
diff --git a/docs/families/input-fields.md b/docs/families/input-fields.mdindex 05f41dd493..cb97069008 100644--- a/docs/families/input-fields.md+++ b/docs/families/input-fields.md@@ -366,7 +366,6 @@ DEC-6 does not require unrelated components to add a new floor.| FileInput | control box | native file input | native file input | `control*` || DateInput (pointer, native, touch) | control box | control box | date input | `control*` || DateRangeInput | control box | control box; `ref` on a trigger button | range trigger | `control*` |- | DateTimeInput (pointer, touch) | control box | control box | date-time input | `control*` || Selector | control box | trigger button | trigger button | `control*` || MultiSelector | control box | not forwarded | trigger button | `control*` || ComplexSelector | control box | control box | trigger button | `control*` |diff --git a/packages/core/src/DateTimeInput/DateTimeInput.spec.md b/packages/core/src/DateTimeInput/DateTimeInput.spec.mdindex 929385d1d3..19501bb98f 100644--- a/packages/core/src/DateTimeInput/DateTimeInput.spec.md+++ b/packages/core/src/DateTimeInput/DateTimeInput.spec.md@@ -3,11 +3,11 @@ schema_version: 3template_version: 7kind: componentid: component:DateTimeInput-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-10-30owners: [cixzhang]review_triggers: [public-api, behavior, layout, theming, accessibility]verified_by:@@ -16,30 +16,37 @@ verified_by:packages/core/src/DateTimeInput/DateTimeInputTouch.test.tsx,packages/core/src/DateTimeInput/NativePickerSegments.test.tsx,packages/core/src/DateTimeInput/Presentation.test.tsx,+ packages/core/src/DateTimeInput/DateTimeInput.fr10.test.tsx,+ 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: []-architecture: [architecture:component-theming-surface]+architecture:+ [+ architecture:component-theming-surface,+ architecture:internationalization,+ architecture:public-component-api,+ ]contributing: []-system_specs: [spec:AST-043]+system_specs: [spec:AST-043, spec:AST-085, spec:AST-086, spec:AST-102]---# DateTimeInput component contract## Contract at a glance-| Area | Contract |-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| Public contract | One controlled ISO date-time value presented through coordinated date and time segments; `presentation` selects Astryx, native, or adaptive picker surfaces. |-| Behavior | Date and time changes emit one combined value; clear emits `undefined`; controlled empty state remains empty in every rendered picker. |-| End-user impact | People selecting a date and time see one value reflected consistently in the closed field and the active picker, including after clearing. |-| Builder impact | None. |-| Compatibility/readiness | Released defaults and deprecated `nativePicker` behavior remain unchanged. The presentation matrix is governed by current `spec:AST-043`; component-local observations remain draft pending owner review. |-| Review checks | Reject competing picker selection, date/time output that is not one valid combined value, presentation precedence drift, lost per-segment fallback, or broken segment accessibility. |-| Governing rules | `spec:AST-043`, `family:input-fields`, `family:overlay-dismissal`, and objective platform accessibility standards. |+| Area | Contract |+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | One controlled ISO date-time value presented through coordinated date and time segments; `presentation` selects Astryx, native, or adaptive picker surfaces. |+| Behavior | Date and time changes emit one combined value; clear emits `undefined`; controlled empty state remains empty in every rendered picker. |+| End-user impact | People selecting a date and time see one value reflected consistently in the closed field and the active picker, including after clearing. |+| Builder impact | None. |+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. The presentation matrix and deprecated `nativePicker` mapping follow `spec:AST-043`. Fixed segment height, locale time text and parsing, busy paint, and caller handlers while disabled are listed under Current-state impact. |+| Review checks | Reject competing picker selection, date/time output that is not one valid combined value, presentation precedence drift, lost per-segment fallback, or broken segment accessibility. |+| Governing rules | `spec:AST-043`, `family:input-fields`, `family:overlay-dismissal`, `spec:AST-085`, `spec:AST-086` FR8, and objective platform accessibility standards. |This table is a review projection; the body below is authoritative.@@ -71,13 +78,16 @@ Consumer migration instructions belong in consumer docs and release notes.- Applying component-local date-time bounds, date constraints, time precision,typed-time stepping, and optional preset-time behavior.- Emitting `onChange` before an optional optimistic `changeAction`.+- The disabled-reason Tooltip composition, which `family:input-fields` assigns+ to the member.**Does not own / non-goals**-- Field label, description, status, disabled-reason, and clear-button presentation —- owned by `component:Field` and `component:FieldStatus`.+- Field label, description, status, and clear-button presentation —+ owned by Field under `family:input-fields` (shared owner section) and+ `component:FieldStatus`.- Calendar-grid rendering and date-cell interaction — owned by- `component:Calendar`.+ Calendar.- Popover and sheet hosting or dismissal — owned by the composed layer componentsand `family:overlay-dismissal`.- Cross-component picker-presentation vocabulary and deprecated-prop mapping —@@ -95,18 +105,17 @@ Consumer migration instructions belong in consumer docs and release notes.## Behavioral and layout contract-Draft requirements identify their basis so observed code is not mistaken for an-intentional decision.--| ID | Candidate invariant | Basis | Draft review state |-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------ |-| FR1 | DateTimeInput MUST reflect one controlled date-time value across its visible segments and active picker, and MUST NOT reveal a competing selected date after the parent accepts a clear. | Public docs, controlled component seam, current source, focused tests | Verified observation; owner approval pending |-| FR2 | Every committed date or time change MUST emit one valid combined ISO date-time value; clearing MUST emit `undefined`; changing time while no date is committed MUST emit nothing. | Public types, docs, current source, focused tests | Verified observation; owner approval pending |-| FR3 | `presentation`, deprecated `nativePicker`, precedence, pointer adaptation, forced surfaces, and per-segment native fallbacks MUST follow `spec:AST-043` FR1–FR4. | `spec:AST-043` | Inherited current authority |-| FR4 | When `changeAction` is present, every value-change path MUST call `onChange` first, show the proposed controlled value optimistically, and contribute to one busy state until the controlled value accepts or replaces it. | `family:input-fields/FR6` | Inherited current authority |-| FR5 | The two pointer segments share one row while each retains its intrinsic basis; when the container is narrower, flex wrapping moves them into separate full-width rows. | Public docs, current source, focused layout tests | Verify rendered geometry; class-level behavior covered |-| FR6 | Date-time bounds and date constraints MUST prevent invalid commits. Native controls MAY receive platform hints, but JavaScript validation remains the final commit boundary; calendar-only options MAY be unavailable on native surfaces. | Public docs, current source, focused presentation tests | Verified observation; owner approval pending |-| FR7 | A preset-time listbox MUST remain optional, preserve typed entry, expose one selected option independently from keyboard highlight, and limit offered values to the selected date's effective minimum and maximum. | Public docs, current source, focused interaction tests | Verified observation; owner approval pending |+| ID | Invariant | Basis |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |+| FR1 | DateTimeInput MUST reflect one controlled date-time value across its visible segments and active picker, and MUST NOT reveal a competing selected date after the parent accepts a clear. | Public docs, controlled component seam, current source, focused tests |+| FR2 | Every committed date or time change MUST emit one valid combined ISO date-time value; clearing MUST emit `undefined`; changing time while no date is committed MUST emit nothing. | Public types, docs, current source, focused tests |+| FR3 | `presentation`, deprecated `nativePicker`, precedence, pointer adaptation, forced surfaces, and per-segment native fallbacks MUST follow `spec:AST-043` FR1–FR4. | `spec:AST-043` |+| FR4 | When `changeAction` is present, every value-change path MUST call `onChange` first, show the proposed controlled value optimistically, and contribute to one busy state until the controlled value accepts or replaces it. | `family:input-fields/FR6` |+| FR5 | The two pointer segments share one row while each retains its intrinsic basis; when the container is narrower, flex wrapping moves them into separate full-width rows. Each segment is the shared element height for its size, as a minimum that grows with a set text size under `spec:AST-102` FR4. Implementation gap: the height is fixed at that size. | Public docs, current source, focused layout tests; `spec:AST-102` FR4 |+| FR6 | Date-time bounds and date constraints MUST prevent invalid commits. Native controls MAY receive platform hints, but JavaScript validation remains the final commit boundary; calendar-only options MAY be unavailable on native surfaces. | Public docs, current source, focused presentation tests |+| FR7 | A preset-time listbox MUST remain optional, preserve typed entry, expose one selected option independently from keyboard highlight, and limit offered values to the selected date's effective minimum and maximum. Time text and typed times MUST follow the active locale's digits, separator, and day-period words (`architecture:internationalization` INV1a, INV8). Implementation gap: time text, preset options, and the stepped-time announcement use ASCII digits, a `:` separator, and a fixed English "AM"/"PM", and the typed time parser takes no locale. | Public docs, current source, focused interaction tests; `architecture:internationalization` INV1a, INV8 |+| FR8 | Base props and `ref` MUST reach the date segment's input; a caller `aria-describedby` joins the component's own descriptions, and a caller DOM handler runs after the field's own handler. `container*` reaches the Field box and `control*` the segment row; root `xstyle`, `className`, and `style` are not accepted. | `family:input-fields` FR10; `DateTimeInput.fr10.test.tsx` |+| FR9 | A disabled field MUST keep both segments focusable with `aria-disabled` and no native `disabled`, block every value-changing path, keep the calendar button's tab stop, and paint the keyboard focus ring. Explicit `isLoading` makes every surface inert the same way; a pending `changeAction` does so only on the popover surface, and the bottom sheet and any field with a native date segment keep accepting edits. The busy start is announced once. Implementation gap: a caller `onKeyDown` and other DOM handlers on the date segment still run while disabled (`spec:AST-085` FR2). Implementation gap: a busy field that is not disabled takes the disabled paint (half opacity), on every surface while `isLoading` and on the popover while a `changeAction` is pending, against `spec:AST-085` FR6. | `spec:AST-085` FR1, FR2, FR6; `spec:AST-086` FR8; current source and tests |### Allowed variation@@ -119,13 +128,13 @@ intentional decision.### Representative states-| State | Required invariant | Allowed variation |-| --------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------ |-| Empty | Both segments and every active picker expose no committed selection. | Placeholder and selected surface. |-| Date-time value | Date segment, time segment, and active picker reflect the same committed value. | Locale, hour format, and time precision. |-| Cleared after picker change | Closed field is empty and reopening the picker reveals no selected date or retained committed time. | Picker focus date may remain navigational. |-| Busy | Proposed value remains visible; mutation paths are unavailable; both editable segments expose busy. | Explicit loading or pending action source. |-| Focusable disabled | Both segments remain focusable enough to expose the reason while every value-changing path stays blocked. | Disabled-reason text. |+| State | Required invariant | Allowed variation |+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |+| Empty | Both segments and every active picker expose no committed selection. | Placeholder and selected surface. |+| Date-time value | Date segment, time segment, and active picker reflect the same committed value. | Locale, hour format, and time precision. |+| Cleared after picker change | Closed field is empty and reopening the picker reveals no selected date or retained committed time. | Picker focus date may remain navigational. |+| Busy | Proposed value remains visible; both editable segments expose busy. With explicit `isLoading`, mutation paths are unavailable on every surface; with a pending `changeAction`, only on the popover surface. | Explicit loading or pending action source. |+| Focusable disabled | Both segments stay focusable with `aria-disabled` while every value-changing path stays blocked. | Disabled-reason text. |### Transformation and precedence order@@ -220,24 +229,38 @@ leading clock glyph uses `date-time-input-clock-icon`.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- |-| FR1–FR2 | `DateTimeInput.test.tsx` | empty, calendar selection, typed date/time, clear | A stale Calendar selection, partial output, or invalid mutation makes a public-state test fail. | `audit:DateTimeInput/behavior` |-| FR3, FR6 | `Presentation.test.tsx`, `NativePickerSegments.test.tsx`, `DateTimeInputTouch.test.tsx` | forced, adaptive, legacy, native fallback, constrained commit | A substituted surface, precedence drift, or invalid commit makes a presentation test fail. | `audit:DateTimeInput/surfaces` |-| FR4, AR4 | `DateTimeInput.test.tsx`, `DateTimeInputTouch.test.tsx` | pending, loading, disabled reason | Mutation during busy/disabled state or stale optimistic output makes a state test fail. | `audit:DateTimeInput/state` |-| FR5 | `DateTimeInput.test.tsx` | intrinsic row, narrow-container wrap classes | Removing the intrinsic basis or wrap styles makes the class-level layout assertions fail; rendered geometry remains review evidence. | `audit:DateTimeInput/layout` |-| FR7, AR1–AR3 | `DateTimeInput.test.tsx`, `DateTimeInputTouch.test.tsx` | popovers, time options, keyboard/focus | Wrong role, name, state, keyboard behavior, or focus behavior makes a focused interaction test fail. | `audit:DateTimeInput/interaction` |-| Theming anatomy map | `scripts/check-knowledge.mjs`, `themingTargets.test.ts` | root, segments, icons, listbox, options | Missing, undocumented, or wrongly placed targets fail knowledge or target checks. | `audit:DateTimeInput/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |+| FR1–FR2 | `DateTimeInput.test.tsx` | empty, calendar selection, typed date/time, clear | A stale Calendar selection, partial output, or invalid mutation makes a public-state test fail. | `audit:DateTimeInput/behavior` |+| FR3, FR6 | `Presentation.test.tsx`, `NativePickerSegments.test.tsx`, `DateTimeInputTouch.test.tsx` | forced, adaptive, legacy, native fallback, constrained commit | A substituted surface, precedence drift, or invalid commit makes a presentation test fail. | `audit:DateTimeInput/surfaces` |+| FR4, FR9, AR4 | `DateTimeInput.test.tsx`, `DateTimeInputTouch.test.tsx`; `BusyOwnerAnnouncement.test.tsx` DateTimeInput case | pending, loading, disabled reason | Mutation during busy/disabled state or stale optimistic output makes a state test fail. Evidence gap: no test asserts that caller handlers still run while disabled. | `audit:DateTimeInput/state` |+| FR5 | `DateTimeInput.test.tsx` | intrinsic row, narrow-container wrap classes | Removing the intrinsic basis or wrap styles makes the class-level layout assertions fail; rendered geometry remains review evidence. Evidence gap: no test asserts segment heights or text growth. | `audit:DateTimeInput/layout` |+| FR7, AR1–AR3 | `DateTimeInput.test.tsx`, `DateTimeInputTouch.test.tsx` | popovers, time options, keyboard/focus | Wrong role, name, state, keyboard behavior, or focus behavior makes a focused interaction test fail. Evidence gap: no test asserts locale-specific time text or parsing. | `audit:DateTimeInput/interaction` |+| FR8 | `DateTimeInput.fr10.test.tsx` | each surface; caller id, describedby, onClick, onKeyDown | A base prop off the date input, a dropped caller description, or styling on the wrong part fails. | `audit:DateTimeInput/api` |+| Theming anatomy map | `scripts/check-knowledge.mjs`, `themingTargets.test.ts` | root, segments, icons, listbox, options | Missing, undocumented, or wrongly placed targets fail knowledge or target checks. | `audit:DateTimeInput/theming` |++## Current-state impact++- **Fixed height (FR5).** Segments hold the fixed shared element height instead+ of growing with a set text size, against `spec:AST-102` FR4.+- **Time text and parsing (FR7).** Time text, preset options, and the stepped+ announcement use ASCII digits, a `:` separator, and English "AM"/"PM", and+ typed times parse without the locale, against+ `architecture:internationalization` INV1a and INV8.+- **Busy paint (FR9).** A busy field that is not disabled takes the disabled+ half-opacity paint, against `spec:AST-085` FR6.+- **Caller handlers while disabled (FR9).** Caller DOM handlers on the date+ segment, such as `onKeyDown`, still run while disabled, against+ `spec:AST-085` FR2.## Decision log-No component-local decision is asserted by this draft. Current cross-component-picker decisions remain in `spec:AST-043`.+No component-local decision. Cross-component picker decisions live in+`spec:AST-043`.## Open questions-None. Owner review may accept, amend, or reject the observational component-local-rows without changing inherited current authority.+None.## Content boundary