An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): ComplexSelector records its shipped contract as current (#9345)
Cindy Zhang75094f759e10
diff --git a/docs/families/input-fields.md b/docs/families/input-fields.mdindex 4a20ce5d9f..96a341c226 100644--- a/docs/families/input-fields.md+++ b/docs/families/input-fields.md@@ -361,15 +361,14 @@ DEC-6 does not require unrelated components to add a new floor.below accepts root `xstyle`/`className`/`style`, and none accepts `container*`or `control*`. Today's targets:- | Component | Root styling reaches | Base props reach | Primary semantic control | Root styling migrates to |- | --------------- | -------------------- | -------------------------------------- | ------------------------ | ------------------------ |- | FileInput | control box | native file input | native file input | `control*` |- | DateRangeInput | control box | control box; `ref` on a trigger button | range trigger | `control*` |- | Selector | control box | trigger button | trigger button | `control*` |- | ComplexSelector | control box | control box | trigger button | `control*` |- | Typeahead | Field | Field | combobox input | `container*` |- | Tokenizer | Field | Field | combobox input | `container*` |- | Slider | Field | not forwarded; `ref` on the track | slider control | `container*` |+ | Component | Root styling reaches | Base props reach | Primary semantic control | Root styling migrates to |+ | -------------- | -------------------- | -------------------------------------- | ------------------------ | ------------------------ |+ | FileInput | control box | native file input | native file input | `control*` |+ | DateRangeInput | control box | control box; `ref` on a trigger button | range trigger | `control*` |+ | Selector | control box | trigger button | trigger button | `control*` |+ | Typeahead | Field | Field | combobox input | `container*` |+ | Tokenizer | Field | Field | combobox input | `container*` |+ | Slider | Field | not forwarded; `ref` on the track | slider control | `container*` |Conformance is an approved removal of rootstyling; an `astryx upgrade` codemod rewrites each component's root styling todiff --git a/docs/specs/components/ComplexSelector/ComplexSelector.spec.md b/docs/specs/components/ComplexSelector/ComplexSelector.spec.mdindex 07ecebcf21..89e2fd6572 100644--- a/docs/specs/components/ComplexSelector/ComplexSelector.spec.md+++ b/docs/specs/components/ComplexSelector/ComplexSelector.spec.md@@ -3,21 +3,21 @@ schema_version: 3template_version: 7kind: componentid: component:ComplexSelector-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-11-01owners: [cixzhang]review_triggers: [public-api, behavior, layout, theming, accessibility]verified_by:[packages/core/src/ComplexSelector/ComplexSelector.test.tsx,+ packages/core/src/ComplexSelector/ComplexSelector.fr10.test.tsx,+ packages/core/src/ComplexSelector/ComplexSelector.focusableDisabled.test.tsx,packages/core/src/ComplexSelector/__tests__/ComplexSelector.a11y.chromium.spec.ts,- apps/storybook/stories/ComplexSelector.stories.tsx,apps/storybook/rtl-audit/targets.json,- packages/core/src/Field/Field.test.tsx,- packages/core/src/Icon/Icon.test.tsx,+ packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]modules: []@@ -30,7 +30,7 @@ architecture:architecture:layer-runtime,]contributing: []-system_specs: [spec:AST-055, spec:AST-079/DEC-1, spec:AST-085]+system_specs: [spec:AST-055, spec:AST-079/DEC-1, spec:AST-085, spec:AST-102]---# ComplexSelector component contract@@ -43,7 +43,7 @@ system_specs: [spec:AST-055, spec:AST-079/DEC-1, spec:AST-085]| Behavior | The built-in path composes Field, one combobox trigger whose popup is a dialog, an indicator, and a mounted dialog popup. The caller-rendered path replaces the Field and built-in trigger chrome with one unwrapped caller control that carries the same combobox role and state, while ComplexSelector keeps anchoring, open state, popup wiring, focus return, and the popup. || End-user impact | People selecting through rich custom content receive one named combobox trigger that announces required, busy, and disabled state (and invalid state on the built-in trigger), keyboard and pointer opening, focus restoration, and a popup that remains reachable across logical placement and viewport direction. || Builder impact | Builders provide controlled value plus custom dialog content. They may use the built-in field trigger, call the imperative handle, or spread one exported trigger-props object onto a caller-rendered control, which then becomes the selector's combobox field. Test code that finds the trigger with `getByRole('button')` uses `getByRole('combobox')`. |-| Compatibility/readiness | The built-in Field composition is preserved when `renderTrigger` is absent, and the trigger plays the combobox role on both paths (DEC-1). Caller-rendered mode is additive and implemented under current `spec:AST-055`. This record stays a draft until an owner approves it. |+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. The fixed trigger height is listed under Current-state impact. || Review checks | Reject a second or wrapped interactive trigger, a trigger role other than combobox, ARIA the combobox role does not support, missing popup or disabled state, lost focus return, a popup anchored to a different box or outside the inline viewport, suppressed BaseProps, physical-direction placement, or a status that loses its semantic message. || Governing rules | `spec:AST-055/FR1–FR7, AR1–AR4`; `architecture:public-component-api/INV1, INV3, INV5–INV9`; `family:input-fields/FR1–FR8, FR10`; `spec:AST-085/FR1, FR2, FR4`; `spec:AST-079/DEC-1`; `family:overlay-dismissal`; `architecture:component-theming-surface`; `architecture:layer-runtime`. |@@ -108,23 +108,20 @@ 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. A `current` contract contains no unresolved rows.--| ID | Candidate invariant | Basis | Draft review state |-| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |-| FR1 | ComplexSelector MUST remain controlled: `children` receives the current or optimistic value, a committing helper, a closing helper, and live shell state; the committing helper calls `onChange` before an optional `changeAction`. | Current source, tests, `family:input-fields/FR6` | Verified current behavior |-| FR2 | The built-in path MUST render Field, one combobox trigger whose popup is a dialog, an optional start slot, a disclosure/loading end area, and one mounted popup. The popup is hidden while closed and shown while open. | Current source, docs, tests, `architecture:layer-runtime` | Verified current behavior |-| FR3 | The built-in trigger MUST resolve `sm`, `md`, and `lg` from shared element-size tokens. Input, secondary, and ghost variants MUST preserve the same open, close, value, busy, and popup behavior. | Current source, docs, tests, `family:input-fields` | Verified current behavior |-| FR4 | Built-in Field metadata MUST name and describe the combobox trigger and preserve description, status, validation, and requirement semantics; required state reaches the trigger as `aria-required`, which the combobox role supports. | Current source, Field contract, DEC-1, WCAG 2.2 4.1.2 | Verified current behavior |-| FR5 | Explicit disabled MUST expose `aria-disabled` on the trigger, built-in or caller-rendered, while it keeps its tab stop, and MUST make click, ArrowDown, imperative `open`, and imperative `toggle` no-ops; a press on a disabled trigger reaches no handler. | Current source, tests, `spec:AST-085/FR1, FR2, FR4` | Verified current behavior |-| FR6 | External `isLoading` or a pending `changeAction` MUST resolve to one busy state. The built-in path renders one decorative Spinner, exposes `aria-busy`, and announces the busy start once; caller content receives `isBusy`; caller-rendered mode receives current `aria-busy`. | Current source, docs, tests, `family:input-fields/FR5–FR6` | Verified current behavior |-| FR7 | Warning, error, and success MUST delegate to Field status. Error MUST expose `aria-invalid` on the built-in trigger. Secondary and ghost with requested attached status MUST resolve to detached status. | Current source, tests, `family:input-fields/FR8` | Verified current behavior |-| FR8 | Trigger click toggles the popup; ArrowDown opens a closed popup; content and the imperative handle can close it; every open/close route reports through `onOpenChange`; closing returns focus to the current trigger. | Current source, tests, `family:overlay-dismissal` | Verified current behavior |-| FR9 | Placement and alignment MUST remain logical. The popup MUST anchor to the current trigger and keep content reachable through the current layer-runtime fallback and scroll behavior. | Current source, RTL target, browser test, layer architecture, WCAG 2.2 1.4.10 | Verification requires passing logical RTL placement and exact-head 320px browser receipts |-| FR10 | With `renderTrigger`, the caller control MUST render unwrapped as the only opener, replace Field and built-in chrome, and carry the exported ref, handlers, combobox role, popup props (`aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`), name, busy, required, and disabled state, plus the caller's inherited BaseProps. It anchors the popup, receives focus return, and preserves the same content, handle, and open-change behavior. | `spec:AST-055/FR1–FR7, AR1–AR4`, DEC-1, current source and tests | Verified current behavior |-| FR11 | The trigger MUST play the combobox role on both paths so every emitted ARIA state is supported, and accepted BaseProps plus component availability state MUST NOT disappear silently when trigger ownership changes. | DEC-1, `architecture:public-component-api/INV3, INV5–INV7`, WCAG 2.2 4.1.2 | Verified current behavior |-| FR12 | Built-in Trigger, Indicator icon, and Popup MUST carry the local `complex-selector`, `complex-selector-indicator-icon`, and `complex-selector-popup` targets on their painting elements. Delegated and caller-owned content MUST keep its existing owner. | Current source, docs, theming architecture, target tests | Verified current behavior |+| ID | Invariant | Basis |+| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |+| FR1 | ComplexSelector MUST remain controlled: `children` receives the current or optimistic value, a committing helper, a closing helper, and live shell state; the committing helper calls `onChange` before an optional `changeAction`. | Current source, tests, `family:input-fields/FR6` |+| FR2 | The built-in path MUST render Field, one combobox trigger whose popup is a dialog, an optional start slot, a disclosure/loading end area, and one mounted popup. The popup is hidden while closed and shown while open. | Current source, docs, tests, `architecture:layer-runtime` |+| FR3 | The built-in trigger resolves `sm`, `md`, and `lg` from shared element-size tokens, and its height MUST grow with a set text size (`spec:AST-102` FR4). Implementation gap: the height is fixed at the token. Input, secondary, and ghost variants preserve the same open, close, value, busy, and popup behavior. | Current source, docs, tests; `family:input-fields`; `spec:AST-102` FR4 |+| FR4 | Built-in Field metadata MUST name and describe the combobox trigger and preserve description, status, validation, and requirement semantics; required state reaches the trigger as `aria-required`, which the combobox role supports. | Current source; `component:Field`; DEC-1 |+| FR5 | Explicit disabled MUST expose `aria-disabled` on the trigger, built-in or caller-rendered, while it keeps its tab stop, and MUST make click, ArrowDown, imperative `open`, and imperative `toggle` no-ops; a press on a disabled trigger reaches no handler. | Current source, tests, `spec:AST-085/FR1, FR2, FR4` |+| FR6 | External `isLoading` or a pending `changeAction` MUST resolve to one busy state. The built-in path renders one decorative Spinner, exposes `aria-busy`, and announces the busy start once; caller content receives `isBusy`; caller-rendered mode receives current `aria-busy`. | Current source, docs, tests, `family:input-fields/FR5–FR6` |+| FR7 | Warning, error, and success MUST delegate to Field status. Error MUST expose `aria-invalid` on the built-in trigger. Secondary and ghost with requested attached status MUST resolve to detached status. | Current source, tests, `family:input-fields/FR8` |+| FR8 | Trigger click toggles the popup; ArrowDown opens a closed popup; content and the imperative handle can close it; every open/close route reports through `onOpenChange`; closing returns focus to the current trigger. | Current source, tests, `family:overlay-dismissal` |+| FR9 | Placement and alignment stay logical. The popup anchors to the current trigger, keeps clearance on the edge facing it (carried across a flip), and keeps content reachable through the layer-runtime fallback and scroll behavior. | Current source; `architecture:layer-runtime` |+| FR10 | With `renderTrigger`, the caller control MUST render unwrapped as the only opener, replace Field and built-in chrome, and carry the exported ref, handlers, combobox role, popup props (`aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`), name, busy, required, and disabled state, plus the caller's inherited BaseProps. It anchors the popup, receives focus return, and preserves the same content, handle, and open-change behavior. | `spec:AST-055/FR1–FR7, AR1–AR4`, DEC-1, current source and tests |+| FR11 | The trigger MUST play the combobox role on both paths so every emitted ARIA state is supported, and accepted BaseProps plus component availability state MUST NOT disappear silently when trigger ownership changes. A caller `onClick` on the built-in trigger runs before the toggle and can cancel opening with `preventDefault()`, the cancellation the prop documents (`family:input-fields` DEC-8). | DEC-1; `architecture:public-component-api` INV3, INV5–INV7; `family:input-fields` DEC-8 |+| FR12 | Built-in Trigger, Indicator icon, and Popup MUST carry the local `complex-selector`, `complex-selector-indicator-icon`, and `complex-selector-popup` targets on their painting elements. Delegated and caller-owned content MUST keep its existing owner. | Current source, docs, theming architecture, target tests |### Allowed variation@@ -139,7 +136,7 @@ intentional decision. A `current` contract contains no unresolved rows.| State | Required invariant | Allowed variation || -------------------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- || built-in empty/selected/overflow | Field and trigger stay bounded; placeholder/value remains named; long content does not widen the field | Caller-owned value content may differ |-| input/secondary/ghost × sm/md/lg | Size tokens and shell behavior remain coherent | Secondary and ghost take their button treatments |+| input/secondary/ghost × sm/md/lg | Size tokens and shell behavior remain coherent; today the height is fixed at the token, the FR3 gap | Secondary and ghost take their button treatments || disabled | Built-in trigger exposes `aria-disabled`, keeps its tab stop, and no open path succeeds | The caller-rendered control carries the same state || external/transition busy | One busy state reaches ARIA and content; built-in dimensions remain stable | Busy source may be `isLoading` or a pending Action || warning/error/success | Field owns status; error exposes invalid state | Message may be absent |@@ -188,7 +185,7 @@ durable constraints and their verification target.| Caller-rendered trigger | Caller-owned control paint, focus indicator, and open-state representation | `spec:AST-055`; caller selects representation | prominent | FR10, AR2–AR3 |The component implements design requirements without copying their rationale.-No component-local subjective design decision is introduced by this draft.+No component-local subjective design decision is recorded.### Theming anatomy@@ -226,26 +223,36 @@ not a ComplexSelector-owned painting surface or theme target.- `architecture:public-component-api` owns public export reachability, BaseProps preservation, styling composition, and event composition; DEC-1 keeps the trigger's role and state the same on both paths.- `architecture:component-theming-surface` owns anatomy qualification, local target mapping, and delegation.- `architecture:layer-runtime` owns the Popover host, logical position, fallback, native dismissal, and visibility reconciliation.+- `spec:AST-059` owns the viewport cap, gutters, and any declared app inset the popup inherits; the popup's 480px content cap is a lower cap under it. `spec:AST-090` owns the layer exit the popup inherits.- Field and Icon retain ownership of their delegated targets and representation.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |-| FR1, FR6 | `ComplexSelector.test.tsx` value/Action tests | controlled value; optimistic pending; external loading | Callback order changes, optimistic value disappears, or busy state diverges. | `audit:ComplexSelector/behavior` |-| FR2–FR4, FR7, FR12 | component/Field/Icon tests, docs, target guards, audit matrix, and axe report | input/secondary/ghost; sm/md/lg; empty/value/overflow; required; all statuses | Owned anatomy, target, naming, description, invalid, or status behavior disappears, or unsupported required ARIA is emitted. | `audit:ComplexSelector/anatomy` |-| FR5, AR1, AR6 | `ComplexSelector.focusableDisabled.test.tsx`, the trigger-semantics suite in `ComplexSelector.test.tsx`, and the audit matrix | enabled/disabled × built-in/caller-rendered | A disabled path opens or reaches a handler, loses its tab stop, or either path drops `aria-disabled`. | `audit:ComplexSelector/accessibility` |-| FR8, AR3 | focused open-change, light-dismiss, Escape, content-close, handle, and focus-return tests | click; ArrowDown; selection; Escape; light dismiss; handle | Open/close notification duplicates or disappears, or focus falls to body instead of the trigger. | `audit:ComplexSelector/accessibility` |-| FR9, AR5 | RTL D4 target plus `ComplexSelector.a11y.chromium.spec.ts` | LTR/RTL; logical start; wide/320px; layer fallback | Popup aligns to the physical wrong side, loses its anchor, overflows horizontally, or becomes unreachable. | `audit:ComplexSelector/rtl-responsive` |-| FR10, AR2–AR3 | render-trigger unit suite and exact-head Chromium focus/anchor receipts | caller button closed/open; focus-visible; LTR/RTL; narrow | A second/wrapped opener appears, disclosure is missing, focus paint has no owner box, or popup loses the anchor. | `audit:ComplexSelector/accessibility` |-| FR11, ORD6, DEC-1 | trigger-semantics suite, `ComplexSelector.fr10.test.tsx`, and the audit matrix axe report | required, invalid, and disabled states; BaseProps across both trigger paths | A trigger loses the combobox role, emits ARIA the role does not support, or suppresses accepted inputs. | `audit:ComplexSelector/public-api` |-| Theming anatomy map | `scripts/check-knowledge.mjs` and theming target inventories | built-in anatomy; caller-rendered replacement | Missing, extra, stale, or multiply assigned mappings pass validation. | `audit:ComplexSelector/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |+| FR1, FR6, ORD4 | `ComplexSelector.test.tsx` "renders custom content with value and commits through onChange", "runs changeAction through the provided onChange helper", commit-helper disabled cases, "passes a close helper to composed content"; "keeps the disabled and busy state on an Astryx Button control" | Controlled value; Action; disabled helpers; busy | A commit that skips `onChange`, an Action before it, a helper that commits while disabled, or a lost busy state fails. Evidence gap: no test asserts the busy announcement or the optimistic value. | `audit:ComplexSelector/behavior` |+| FR2, FR3 | `ComplexSelector.test.tsx` "defaults to md and reflects explicit trigger sizes", "renders a ghost toolbar trigger with a start icon", "applies distinct trigger chrome to the secondary variant" | Sizes; variants; start icon | A wrong size, a missing start slot, or a variant without its chrome fails. Evidence gap: no test asserts the trigger height or its growth with text size (the FR3 gap). | `audit:ComplexSelector/anatomy` |+| FR4, AR1 | `ComplexSelector.test.tsx` trigger-semantics cases ("exposes the built-in trigger as a combobox that carries required state", "names the built-in trigger with the field label when the caller gives no name", the caller aria-label and aria-labelledby cases, "names the trigger by its label and shows the chosen value as its content", "keeps the field label as the name when the trigger shows the placeholder"); `ComplexSelector.fr10.test.tsx` "keeps a caller aria-describedby alongside the field description" | Named, described, required; caller names | A trigger not named or described by the field, a lost required state, or a caller name ignored fails. | `audit:ComplexSelector/accessibility` |+| FR5, AR6 | `ComplexSelector.focusableDisabled.test.tsx` cases; `ComplexSelector.test.tsx` "does not open via the imperative handle when disabled", "spreads the combobox role, required, and disabled state onto a caller control" | Disabled built-in and caller control | Native `disabled`, a lost Tab stop, an open or handler reached while disabled, a lost focus when disabled while focused, or a caller control without `aria-disabled` fails. | `audit:ComplexSelector/accessibility` |+| FR7, ORD3 | `ComplexSelector.test.tsx` statusVariant cases, including `forces detached when variant="%s" even if statusVariant="attached"`; `ComplexSelector.a11y.chromium.spec.ts` matrix rest frame (`aria-invalid` on the invalid trigger) | Attached, detached, tooltip | A status that leaves Field, a tooltip message not describing the trigger, an info-tip press that opens the popup, an attached status on secondary or ghost, or an invalid trigger without `aria-invalid` fails. | `audit:ComplexSelector/anatomy` |+| FR8, AR3 | `ComplexSelector.test.tsx` onOpenChange cases, "does not reopen from the trigger click that follows light dismiss", "exposes imperative open, close, toggle, and isOpen via handleRef"; `ComplexSelector.test.tsx` "opens against the caller control and returns focus to it on close" | Click, ArrowDown, Escape, light dismiss, content close, handle | A missing or repeated open-change report, a reopen from a dismissing click, or focus that does not return fails. | `audit:ComplexSelector/accessibility` |+| FR9, AR5 | `ComplexSelector.test.tsx` "gives the popup clearance on the edge facing the trigger, which a flip carries to the other side", "supports end-aligned popup positioning"; `ComplexSelector.a11y.chromium.spec.ts`; `apps/storybook/rtl-audit/targets.json` ComplexSelector entry | Start and end alignment; flip; RTL | A popup without clearance, on the wrong side, off its anchor, or past the inline viewport at 320 CSS px (the audit's narrow and coarse open frames) fails. | `audit:ComplexSelector/rtl-responsive` |+| FR10, AR2, ORD5 | `ComplexSelector.test.tsx` trigger render prop cases; `ComplexSelector.fr10.test.tsx` renderTrigger cases | Caller control closed and open; ArrowDown; base props | A wrapped or second opener, missing popup props, lost base props or ref, or focus not returned fails. | `audit:ComplexSelector/accessibility` |+| FR11, ORD6 | `ComplexSelector.fr10.test.tsx` props-type and target cases ("puts control* on the bordered control box around the trigger, not on the trigger or the popup", "lets a caller onClick on the trigger cancel opening, as before", "opens from a press on the control box outside the trigger button", "keeps the built-in keyboard model and still hands every key to a caller onKeyDown") | Control box; caller handlers | A root styling prop, `control*` off the control box, a dropped caller key handler, or a caller `onClick` that cannot cancel opening fails. | `audit:ComplexSelector/public-api` |+| FR12 | `ComplexSelector.test.tsx` popup theme-target cases and "defaults to md and reflects explicit trigger sizes" (read from `.astryx-complex-selector`); `themingTargets.test.ts` | Popup surface; `contentXstyle` | A popup target off the painting surface, a missing `complex-selector` target, or a rendered class absent from the documented targets fails. Evidence gap: no test asserts the indicator-icon target. | `audit:ComplexSelector/theming` |+| ORD1, ORD2, PR1, PR2 | ORD1 and ORD2 are covered by the FR4 row. Evidence gap: no test asserts the `triggerLabel` precedence, the single layer owner, or the absence of mirrored state | — | — | `audit:ComplexSelector/behavior` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Built-in anatomy; caller-rendered replacement | Missing, extra, stale, or multiply assigned mappings fail repository validation. | `audit:ComplexSelector/theming` |++## Current-state impact++- **Fixed trigger height (FR3).** The built-in trigger holds the shared element+ height instead of growing with a set text size, against `spec:AST-102` FR4.## Decision log- **DEC-1 — The trigger is a combobox field.**- **Decider:** cixzhang, 2026-10-24+ **Decider:** `cixzhang`, 2026-10-24The trigger plays the combobox role, with a dialog popup, on both paths, sorequired and disabled state are valid on it and a caller-rendered control