An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:ComplexSelector authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-11-01 owners: [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/rtl-audit/targets.json, packages/core/src/theme/themingTargets.test.ts, scripts/check-knowledge.mjs, ] modules: [] families: [family:input-fields, family:overlay-dismissal] design_specs: [] architecture: [ architecture:public-component-api, architecture:component-theming-surface, architecture:layer-runtime, ] contributing: []
system_specs: [spec:AST-055, spec:AST-079/DEC-1, spec:AST-085, spec:AST-102]
ComplexSelector component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | The trigger plays the combobox role on both paths (DEC-1), and ComplexSelectorRenderTriggerProps carries role, aria-label, aria-required, and aria-disabled beside its existing ref, id, handlers, and popup props. Current source exports one controlled rich-selector shell, its public props and supporting types, an imperative handle, a content render function, an optional renderTrigger seam governed by spec:AST-055, and named container*/control* styling targets in place of root styling props. |
| 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 | 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. |
This table is a review projection; the body below is authoritative.
Intent
ComplexSelector is a controlled selector shell for choices whose accessible interaction structure is richer than a single list of options. It owns the field trigger or caller-rendered anchor, dialog popup, open and close lifecycle, focus return, optimistic value handoff, and shared field semantics. The caller owns the accessible structure and selection interaction rendered inside the popup.
Compatibility and migration
- Released default preserved:
no; the trigger's role is combobox - Compatibility class: accessibility correction; omitting
renderTriggerpreserves the built-in Field, DOM structure, targets, and interaction - Controlled/uncontrolled behavior: controlled only; the caller owns
value, while ComplexSelector supplies the committing helper - Migration decision: test code that finds the trigger with
getByRole('button')usesgetByRole('combobox'); no runtime migration
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- The built-in Field composition, one combobox trigger, loading and disclosure end controls, and the current
complex-selectortarget. - Popup visibility, the anchor relationship, logical placement and alignment, focus return, and
onOpenChangenotification. - The optimistic value and busy state exposed to caller-provided content while
changeActionis pending. - The
renderTriggerintegration local to ComplexSelector: dialog naming, click and ArrowDown opening, focus return, and the current handed-back props object. - The trailing indicator and popup surfaces exposed by the current
complex-selector-indicator-iconandcomplex-selector-popuptargets.
Does not own / non-goals
- The accessible role, keyboard model, and selection behavior inside
children— owned by the product callsite and the primitives it composes. - Shared Field label, description, requirement, validation, and status rendering — owned by
component:Fieldandfamily:input-fields. - General Icon rendering for semantic names and icon component types — owned by
component:Icon. - Arbitrary ReactNode content supplied through
startIcon— owned by the product callsite. - Shared layer hosting, positioning, native light dismissal, and Escape ordering — owned by
architecture:layer-runtimeandfamily:overlay-dismissal. - The cross-component caller-rendered-trigger API grammar — owned by
spec:AST-055.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| controlled selection | caller value; optimistic candidate value | Current value passed to children; commits call onChange and optional changeAction |
all paths | caller's value |
component:ComplexSelector |
stable | no uncontrolled fallback |
| content render state | open/closed; idle/busy; trigger id; content id | Lets caller content observe shell state without owning visibility | all paths | closed and idle | component:ComplexSelector |
stable | current shell state is supplied on every render |
| trigger ownership | built-in; caller-rendered | Chooses whether ComplexSelector renders Field/combobox chrome or renders one caller control unwrapped | caller-rendered when renderTrigger is present |
built-in | spec:AST-055 |
stable | caller-rendered path wins; built-in chrome is absent |
| built-in variant | input; secondary; ghost |
Bordered field, secondary-button, or ghost-button trigger representation | built-in path only | input |
component:ComplexSelector |
stable | unsupported values are rejected by TypeScript |
| built-in size | sm; md; lg |
Resolves trigger height through shared element-size tokens | built-in path only | md |
component:ComplexSelector |
stable | unsupported values are rejected by TypeScript |
| start content | absent; semantic icon name; icon component type; arbitrary ReactNode | Optional leading trigger content | built-in path only | absent | component:ComplexSelector |
stable | icon-capable values delegate to Icon; arbitrary content renders directly |
| field metadata | visible/hidden label; description absent/present; optional/required/neither; tooltip | Supplies built-in Field naming and supporting information | built-in path; required state also reaches a caller-rendered control | visible label; neither required | family:input-fields |
stable | isRequired and isOptional resolve to one required state on the combobox |
| availability | enabled; disabled | Disabled blocks click, ArrowDown, and imperative opening | aria-disabled with a kept tab stop on both paths |
enabled | component:ComplexSelector |
stable | disabled guards every opening route and press on both paths |
| busy | idle; external loading; pending Action | Exposes aria-busy, a built-in Spinner, and isBusy to content |
Spinner only on built-in path; state remains available to content | idle | family:input-fields |
stable | external and transition busy resolve to one state |
| validation | absent; warning; error; success | Supplies Field status; error also exposes invalid state on the built-in trigger | built-in path only | absent | family:input-fields |
stable | unsupported values are rejected by TypeScript |
| status placement | attached; detached; tooltip |
Chooses Field status presentation | built-in path only; secondary and ghost map attached to detached | attached for input; detached for secondary and ghost |
family:input-fields |
stable | a secondary or ghost attached request resolves to detached |
| popup placement | above; below; start; end |
Logical side where the popup is requested | all paths; layer runtime may choose a fallback | below |
architecture:layer-runtime |
stable | unsupported values are rejected by TypeScript |
| popup alignment | start; center; end |
Logical alignment along the placement axis | all paths | start |
architecture:layer-runtime |
stable | unsupported values are rejected by TypeScript |
| visibility control | trigger actions; content close; imperative open/close/toggle; observation callback |
Keeps one component-owned visibility state and reports every transition | all paths | closed | component:ComplexSelector |
stable | disabled guards opening; closing an already closed popup is a no-op |
| caller DOM/style inputs | inherited BaseProps supplied or omitted; container* and control* part styles |
DOM, data, ARIA, and event inputs accepted by ComplexSelector, plus named part styling | BaseProps reach the primary semantic control on both paths; part styles apply on the built-in path | omitted | family:input-fields |
stable | root xstyle/className/style are a type error; part styles under renderTrigger have no effect and warn in development |
Behavioral and layout contract
| 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. With attached status the trigger row MUST show the status icon in place of the chevron; with tooltip status it MUST show, in place of the chevron, a focusable status button that holds the message and describes the 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. With the built-in trigger, closing returns focus to the trigger only when focus would otherwise be lost (family:overlay-dismissal FR9); a close caused by moving focus elsewhere leaves focus there; a caller's control gets focus back on every close (spec:AST-055 AR3). |
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
- AV1 — Popup content. Caller-provided content may use any accessible selection structure without becoming ComplexSelector-owned anatomy.
- AV2 — Start content. Semantic icon names and icon component types render through Icon; arbitrary ReactNode content remains caller-owned.
- AV3 — Trigger element. Caller-rendered mode does not require a particular tag or Astryx component when the returned control can take focus and accept the supplied integration props.
- AV4 — Layer fallback. The current layer runtime may flip or constrain the requested placement to keep the popup reachable.
- AV5 — Status content. A status message may be absent; when present, Field owns its semantic presentation.
Representative states
| 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; 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 |
| closed/open | One popup remains anchored; disclosure state and focus return remain correct | Requested logical placement/alignment may differ |
| caller-rendered closed/open | One unwrapped caller control owns paint and focus; ComplexSelector owns behavior and popup | Caller chooses the control's element and representation |
| LTR/RTL and wide/320px | Logical alignment mirrors and no required control becomes unreachable | Layer fallback side and popup height may differ with available space |
Transformation and precedence order
- ORD1 — Trigger content.
triggerLabelresolves before callerplaceholder, which resolves before the translated selector placeholder. - ORD2 — Required semantics. Shared required resolution combines
isRequiredandisOptional; the resultingaria-requiredreaches the combobox trigger on both paths. - ORD3 — Status placement. Secondary and ghost convert requested/default attached status to detached before Field renders it; the input variant keeps the requested placement.
- ORD4 — Value Action. The commit helper calls
onChange, then starts the optional transition, exposes the optimistic value, and awaitschangeActionwhile the shared busy state is true. - ORD5 — Trigger ownership. Presence of
renderTriggerselects caller-rendered mode before built-in Field/trigger output; both open the same popup and use the same content and imperative handle. - ORD6 — DOM/style/event precedence. On both paths, inherited BaseProps reach the primary semantic control and the component's own trigger wiring wins over them. On the built-in path, a consumer
onClickruns before the toggle and can cancel it, a consumeronKeyDownruns after the built-in key handling,container*styles the Field box, andcontrol*styles the control box. On the caller-rendered path, consumer handlers run after the built-in handling and cannot cancel opening, andcontainer*/control*have no effect.
Performance and resources
- PR1 — One layer owner. Both trigger paths share one Popover instance and one mounted popup rather than duplicating layer state or listeners.
- PR2 — Optimistic state. The component derives busy state from React transition state and external loading without mirroring it through Effects.
Current measurements belong in the audit record; this subsection owns only durable constraints and their verification target.
Accessibility contract
- AR1 — Built-in name and state. The trigger plays the combobox role and is named by the field's
labelunless the selector was givenaria-labeloraria-labelledby, which replaces it (family:input-fieldsFR10), and exposes its dialog popup (aria-haspopup="dialog",aria-expanded,aria-controls), required and invalid state, description/status references, busy state, and disabled state througharia-disabledwhile it keeps its tab stop. - AR2 — Caller-rendered field. The handed-back trigger props carry the anchor ref, id, click and ArrowDown handlers,
role="combobox",aria-haspopup="dialog",aria-expanded,aria-controls,aria-busy,aria-required, andaria-disabled, and name the control withlabelunless the selector was givenaria-labeloraria-labelledby, because a combobox takes no name from its content; the caller control renders unwrapped as the only opener. - AR3 — Focus lifecycle. The popup autofocuses its content through the Popover owner. On close, the built-in trigger returns focus to the trigger only when focus would otherwise be lost (
family:overlay-dismissalFR9); a close caused by moving focus elsewhere leaves focus there; a caller's control gets focus back on every close route. Focus returns beforeonOpenChange(false)runs. - AR4 — Content responsibility. Caller content supplies the role, name, keyboard model, selected state, and focus navigation appropriate to its own selection pattern.
- AR5 — Direction and viewport. Logical placement and alignment mirror with inherited direction, and the scrollable popup content remains reachable at 320 CSS px.
- AR6 — One trigger role. Both paths expose the same combobox role with required, busy, and disabled state, so a person hears them whichever control opens the popup. Invalid state reaches the built-in trigger, which renders the status message (FR7).
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Field | Shared input label/support/status shell | component:Field, family:input-fields |
supporting | FR2, FR4, FR7 |
| Trigger | Bounded value/placeholder surface and opener | current component source and consumer docs | prominent | FR2–FR5 |
| Icon-rendered start icon | Optional semantic icon through Icon | component:Icon |
supporting | FR2, FR12 |
| Caller-rendered start content | Optional arbitrary React content with caller-owned representation | product callsite | context-dependent | FR2, FR12 |
| Busy Spinner | Processing representation without changing shell dimensions | family:input-fields and Spinner |
supporting | FR6 |
| Status | Shared warning/error/success representation and message | component:Field, family:input-fields |
supporting | FR7 |
| Indicator icon | Disclosure mark whose rotation reflects open/closed state | current component source and consumer docs | supporting | FR2, FR8, FR12 |
| Popup | Painted dialog surface anchored to the trigger | architecture:layer-runtime |
prominent | FR8–FR10 |
| 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 recorded.
Theming anatomy
{
"Field": {"delegatesTo": {"owner": "component:Field", "target": "field"}},
"Trigger": {"target": "complex-selector"},
"Icon-rendered start icon": {
"delegatesTo": {"owner": "component:Icon", "target": "icon"}
},
"Caller-rendered start content": {
"none": {
"reason": "intentional: Arbitrary ReactNode content is caller-owned and receives no ComplexSelector target."
}
},
"Indicator icon": {"target": "complex-selector-indicator-icon"},
"Popup": {"target": "complex-selector-popup"}
}
Busy Spinner and Status are transient/delegated states rather than named anatomy entries in current consumer docs. Caller-rendered mode replaces Field, Trigger, start content, busy Spinner, Status, and Indicator icon; the caller's control is not a ComplexSelector-owned painting surface or theme target.
Family and system relationships
spec:AST-055owns the cross-componentrenderTriggershape, one-element integration, disclosure, caller paint, anchoring, focus-return, and real-browser evidence requirements; ComplexSelector supplies the dialog-specific projection.family:input-fieldsowns shared field geometry, end-control separation, busy/Action flow, status placement, and FR10 prop targets; ComplexSelector adopts those concepts on the built-in path.spec:AST-085owns disabled-control focusability and inert presses; ComplexSelector applies it to the built-in trigger.spec:AST-079/DEC-1owns the shared selector trigger hierarchy that adds the secondary variant.family:overlay-dismissalowns shared Escape, light-dismiss, and close ordering; ComplexSelector participates through Popover.architecture:public-component-apiowns 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-surfaceowns anatomy qualification, local target mapping, and delegation.architecture:layer-runtimeowns the Popover host, logical position, fallback, native dismissal, and visibility reconciliation.spec:AST-059owns 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-090owns 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, 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", "shows the status icon in place of the chevron with attached status, and the chevron with detached", and "puts the tooltip-placement message in a focusable info-tip that describes the trigger"; 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, "Escape and a close from the content return focus to the trigger", "a light dismiss onto another control leaves focus there; onto nothing focusable it returns to the trigger", "a caller-rendered control gets focus back even after a light dismiss onto another control", "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-102FR4.
Decision log
DEC-1 — The trigger is a combobox field.
Decider:
cixzhang, 2026-10-24The trigger plays the combobox role, with a dialog popup, on both paths, so required and disabled state are valid on it and a caller-rendered control announces the same field state as the built-in trigger. Disabled follows
spec:AST-085.Rejected: a disclosure button whose API is narrowed to the states a button supports, because required is field state the selector already accepts.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, popup internals, or family/system rules. It links to their owners.