An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 4 kind: component id: component:DateRangeInput authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-09-14 owners: [cixzhang] review_triggers: [theming] verified_by: [ packages/core/src/DateRangeInput/DateRangeInput.test.tsx, packages/core/src/DateRangeInput/DateRangeInput.calendar.test.tsx, packages/core/src/DateRangeInput/DateRangeInput.ssr.test.tsx, packages/core/src/Calendar/Calendar.calendarSystems.test.tsx, packages/core/src/theme/themingTargets.test.ts, packages/core/src/DateRangeInput/tests/DateRangeInputReflow.interaction.browser.spec.ts, scripts/check-knowledge.mjs, ] modules: [] families: [family:input-fields, family:overlay-dismissal] design_specs: [] architecture: [architecture:component-theming-surface] contributing: []
system_specs: [spec:AST-013/FR12, spec:AST-020, spec:AST-111]
DateRangeInput component contract
Intent
DateRangeInput presents one controlled date range through a labeled field surface. Its trigger opens a Calendar-backed Popover and may include a list of quick-select presets beside that calendar, or above it when the two do not fit side by side. The trigger text and the calendar show the application's calendar system, and the range stays Gregorian ISO dates.
Compatibility and migration
- Released default preserved:
yes; canonical DateRangeInput behavior is unchanged - The
calendarprop is additive; it defaults to the provider's calendar, elsegregory, so a field without a provider calendar keeps its Gregorian text. A provider locale with a-u-ca-keyword keeps Gregorian dates (spec:AST-111DEC-2); setcalendarto choose one - 0.7.0 removes the
date-range-input-clear-iconalias; the shared clear glyph remains available throughinput-clear-icon - The preset constraint correction remains unchanged
- Controlled/uncontrolled behavior: unchanged; DateRangeInput remains controlled
- Migration decision: replace the removed theme key and CSS class with
input-clear-iconand.astryx-input-clear-icon, or runastryx upgrade --from 0.6.3 --apply --path .
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- The composite date-range field surface and its range-display trigger.
- The optional preset list, each preset action, and reflection of a preset's current and disabled states.
- Converting a selected Calendar range or preset into
onChangeandchangeActionoutput.
Does not own / non-goals
- Label, description, and status presentation — owned by
component:Fieldandcomponent:FieldStatus. - Calendar-grid rendering and date-cell interaction — owned by
component:Calendar. - Layer hosting and dismissal — owned by
component:Popoverandfamily:overlay-dismissal. - Shared clear-button presentation — owned by
component:Field.
Public concepts
| Concept | Closed values or states | Meaning | Availability | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| calendar | a CalendarSystem (spec:AST-111 FR1) |
The calendar system the trigger text and the popover Calendar show | Trigger and Calendar | 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 |
This contract also records the existing preset-list anatomy and its additive theming surface.
Behavioral and layout contract
| ID | Candidate invariant | Basis | Review state |
|---|---|---|---|
| FR1 | DateRangeInput MUST present the controlled value and emit range changes without maintaining a competing selected range. |
Current source, docs, and focused tests | Verified current behavior |
| FR2 | When presets are present, each preset remains an independent button in one labeled group; the applied preset reflects current state and a preset whose endpoint violates min, max, or dateConstraints, or whose range violates minRangeSpan or maxRangeSpan, reflects disabled state. |
Current source, accessibility comments, and focused tests | Verified current behavior |
| FR3 | The preset group and each preset button expose stable theme targets; selected and disabled are states of the preset-button target rather than separate targets. | architecture:component-theming-surface; consumer demand for preset theming |
Approved additive contract |
| FR4 | Adding theme targets MUST NOT change the Popover, Calendar, button, focus, or selection semantics those elements already own. | Composition boundary and compatibility goal | Approved additive contract |
| FR5 | When the preset group and a one-month calendar do not fit side by side in the layer, the preset group stacks above the calendar, and every month grid and the month navigation stay inside the layer (spec:AST-020 FR1, WCAG 2.2 SC 1.4.10). Visual order matches DOM order. When they fit, the presets stay beside the calendar. When the content is taller than the layer's viewport cap, it scrolls inside the layer. |
spec:AST-020 FR1; 390 px, 390 × 664 px and 440 px reflow checks |
Verified current behavior |
| FR6 | The trigger text, its accessible name, and the popover Calendar show the resolved calendar (spec:AST-111 FR2, FR17): the trigger writes each end of the range in the calendar, with the year when either end falls outside the current calendar year, and the Calendar lays out calendar months. The field has no typed entry. value, onChange, min, max, presets, and span bounds stay Gregorian ISO dates (spec:AST-111 FR3). |
spec:AST-111 FR3, FR17; current source and calendar tests |
Verified current behavior |
Allowed variation
- AV1 — Preset content. A caller may omit presets or provide any number of labeled ranges.
- AV2 — Calendar layout. Calendar month count, date constraints, and range bounds may vary without changing preset target identity.
- AV3 — Theme output. Themes may restyle the preset group and buttons while the component's button semantics and state remain unchanged.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Calendar | The trigger text and the Calendar show the resolved calendar; values stay Gregorian ISO. | Calendar, locale, digits |
| No presets | No preset group or preset-button target renders. | Calendar configuration |
| Presets, no match | Every button carries the preset target with no selected state. | Preset count and labels |
| Applied preset | The matching button carries aria-current="true" and the target's selected state. |
Selected range |
| Disabled preset | A preset that violates an endpoint date constraint or a range-span constraint is disabled per spec:AST-085 and carries the target's disabled state. |
Constraint source |
Transformation and precedence order
- ORD1 — Preset state. Resolve each preset's range once, compare it with the
controlled value, evaluate
min,max, anddateConstraintsagainst both endpoints, evaluateminRangeSpanandmaxRangeSpanagainst the full range, then reflect selected and disabled state on the same preset-button target. - ORD2 — Preset activation. An enabled preset emits the already-resolved range; activation does not resolve the preset again.
Endpoint constraints match Calendar selection: they apply to the preset's start and end, not every date between them.
Performance and resources
No new performance or resource constraint is introduced.
Accessibility contract
- AR1 — Preset semantics. Presets remain native buttons in one labeled group, navigated independently by Tab.
- AR2 — Current state. The applied preset remains exposed with
aria-current="true"; theme state reflection is additive. - AR3 — Disabled state. A preset that violates an endpoint date constraint or
a range-span constraint is disabled and stays focusable (
spec:AST-085); theme state reflection does not replace that behavior.
Implementation gap: in dark mode the applied preset's label on its muted accent fill measures 3.88:1 on the popover surface, under 4.5:1.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Field surface | Presents one coherent input boundary. | Current source and input-field family | Prominent | FR1 |
| Calendar popover | Provides range selection without changing field ownership. | Popover and Calendar components | Prominent | FR1, FR4 |
| Preset sidebar | Groups optional shortcuts beside the calendar. | Current source and public docs | Supporting | FR2, FR3 |
| Preset button | Presents one quick-select range and its current/disabled state. | Current source and public docs | Supporting | FR2–FR4, AR1–AR3 |
Theming anatomy
{
"Label": {
"delegatesTo": {"owner": "component:Field", "target": "field-label"}
},
"Field surface": {"target": "date-range-input"},
"Trigger button": {
"none": {
"reason": "unsettled: The composite field surface has a target, but the inner range-display button has no separate current target."
}
},
"Calendar icon": {"target": "date-range-input-toggle-icon"},
"Calendar popover": {
"delegatesTo": {"owner": "component:Popover", "target": "popover"}
},
"Preset sidebar": {"target": "date-range-input-presets"},
"Preset button": {"target": "date-range-input-preset"},
"Clear button": {
"delegatesTo": {"owner": "component:Field", "target": "input-clear-button"}
},
"Status message": {
"delegatesTo": {"owner": "component:FieldStatus", "target": "field-status"}
}
}
Family and system relationships
family:input-fieldsowns field sizing, status placement, loading, disabled reasons, and end-control geometry.family:overlay-dismissalowns the Popover dismissal stack.architecture:component-theming-surfaceowns target admission, state reflection, and anatomy mapping.spec:AST-111owns calendar selection, Gregorian ISO values, and theTemporalboundary; FR6 projects its FR3 and FR17.component:Calendarowns the popover grid in the calendar.
spec:AST-013 FR12 exception — calendars that need Temporal
- Capability: trigger text and the popover Calendar 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 shows Gregorian dates and 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 text works withoutTemporal. - Evidence: real Chromium and Firefox with native
Temporal, and real Chromium, Firefox, and WebKit withTemporalremoved, with and without a polyfill, showing the Persian trigger text. - Owner:
nynexman4464. - Review condition: Safari ships
Temporal.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, FR2, AR1–AR3 | DateRangeInput.test.tsx; disabled-preset focusability (AR3) pending conformance |
no match, applied preset, endpoint-invalid preset, span-invalid preset | Semantics or state attributes disappear | audit:DateRangeInput/presets |
| FR3, FR4 | DateRangeInput.test.tsx, themingTargets.test.ts, generated probe theme |
group target, selected button, disabled button | Target class/state is missing, undocumented, or placed on the wrong element | audit:DateRangeInput/theming |
| FR5 | DateRangeInputReflow.interaction.browser.spec.ts |
390 px page with presets and two months; desktop page | The calendar or its navigation crosses the layer edge, or the presets leave the calendar's side at desktop width | audit:DateRangeInput/reflow |
| FR6 | DateRangeInput.calendar.test.tsx ("writes the trigger text and its accessible name in the Persian calendar", "shows the year when the range leaves the current calendar year", "opens a Persian popover calendar and reports Gregorian ISO dates", and the cases without Temporal); Calendar.calendarSystems.test.tsx "DateRangeInput opens its popover calendar in the calendar"; real Chromium, Firefox, and WebKit trigger text |
Persian, Buddhist, a range across a calendar year, no Temporal |
Trigger text or Calendar in another calendar, or a non-ISO value, fails | audit:DateRangeInput/behavior |
| Theming anatomy map | scripts/check-knowledge.mjs |
all documented anatomy | Target ownership or anatomy names drift | audit:DateRangeInput/theming |
Decision log
DEC-1 — Preset group and buttons are public theme anatomy
Reference: component:DateRangeInput/DEC-1
Decider: cixzhang, 2026-09-14
The optional preset sidebar and each quick-select button are stable,
consumer-recognizable parts. date-range-input-presets belongs on the group
that owns sidebar presentation; date-range-input-preset belongs on each
button, with selected and disabled reflected as states rather than separate
targets. The target additions preserve default visuals and button semantics;
preset constraint enforcement follows FR2 and ORD1–ORD2.
Open questions
- OQ1 — Should the inner range-display trigger receive its own target, or remain
represented only by the composite field surface? (
human-api)
Content boundary
This file does not duplicate the consumer prop table, usage examples, Calendar or Popover contracts, current audit results, or downstream theme implementation.