An open source design system that's fully customizable and agent ready
TypeScript
fix(ComplexSelector): a light dismiss onto another control leaves focus there (#9740)
Cindy Zhangc6f44320f53b
diff --git a/.changeset/complexselector-light-dismiss-focus.md b/.changeset/complexselector-light-dismiss-focus.mdnew file mode 100644index 0000000000..ce6a0954f3--- /dev/null+++ b/.changeset/complexselector-light-dismiss-focus.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] Closing a `ComplexSelector` by clicking into another control now leaves focus in that control instead of pulling it back to the selector, as `Selector` and `MultiSelector` already do. Escape, a close from the content, or a click on nothing focusable still returns focus to the trigger. A caller-rendered trigger (`renderTrigger`) still gets focus back on every close.++@cixzhangdiff --git a/docs/specs/components/ComplexSelector/ComplexSelector.spec.md b/docs/specs/components/ComplexSelector/ComplexSelector.spec.mdindex 89e2fd6572..c6fddf5274 100644--- a/docs/specs/components/ComplexSelector/ComplexSelector.spec.md+++ b/docs/specs/components/ComplexSelector/ComplexSelector.spec.md@@ -108,20 +108,20 @@ Consumer migration instructions belong in consumer docs and release notes.## 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. 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 |+| 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`. 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@@ -165,7 +165,7 @@ durable constraints and their verification target.- **AR1 — Built-in name and state.** The trigger plays the combobox role and is named by the field's `label` unless the selector was given `aria-label` or `aria-labelledby`, which replaces it (`family:input-fields` FR10), and exposes its dialog popup (`aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`), required and invalid state, description/status references, busy state, and disabled state through `aria-disabled` while 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`, and `aria-disabled`, and name the control with `label` unless the selector was given `aria-label` or `aria-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, and every supported close route returns focus to the current trigger before `onOpenChange(false)` runs.+- **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-dismissal` FR9); a close caused by moving focus elsewhere leaves focus there; a caller's control gets focus back on every close route. Focus returns before `onOpenChange(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).@@ -228,20 +228,20 @@ not a ComplexSelector-owned painting surface or theme target.## 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"`; `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` |+| 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, "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 impactdiff --git a/docs/specs/components/MultiSelector/MultiSelector.spec.md b/docs/specs/components/MultiSelector/MultiSelector.spec.mdindex 6bb2a28f88..ca7054a1ee 100644--- a/docs/specs/components/MultiSelector/MultiSelector.spec.md+++ b/docs/specs/components/MultiSelector/MultiSelector.spec.md@@ -138,6 +138,7 @@ Complete prop syntax and examples remain in `MultiSelector.doc.mjs`.| FR12 | ArrowDown on the focused trigger opens the list; ArrowDown and ArrowUp move the highlight; Home and End jump to the first and last option without search, while with search they move the caret and PageDown and PageUp jump the highlight; Enter toggles the highlighted option except during input-method composition; Escape closes; Tab closes and moves focus on, except that while a query shows the search's clear button, forward Tab moves to that button and keeps the list open; with `hasClear` and without `hasSearch`, Delete or Backspace on the focused, closed trigger clears every value when one is selected. | Current source and tests || FR13 | The field has no root styling props: `control*` reaches the bordered control box around the trigger and `container*` the Field box (`family:input-fields` FR10); a press on the control box outside the trigger opens it; a caller `onClick` runs after the built-in toggle and a caller `onKeyDown` after the built-in keyboard model, and is skipped for keys that model handles and cancels; a caller `aria-describedby` joins the field description and a caller `aria-labelledby` follows the field's own name. With `renderTrigger`, `container*` and `control*` have no effect and warn. The trigger height is the shared element size for its size and MUST grow with a set text size (`spec:AST-102` FR4). Implementation gap: the height is fixed. | `family:input-fields` FR10; `spec:AST-102` FR4; current tests || FR14 | Each toggle, select-all, or clear announces politely: the all-selected message when every option ends selected, the cleared message when none does, and otherwise the selection count. Once a person searches, the match count (or the empty-results message, or the create row's label when it is the only result) is announced politely; no search result is announced while `isLoading` (the FR2 gap). With `htmlName` the field submits one entry per selected value. | `spec:AST-086`; current tests |+| FR15 | With the built-in trigger, on close focus returns 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 (`renderTrigger`) keeps FR8's focus return. | `family:overlay-dismissal` FR9; current tests |### Allowed variation@@ -327,6 +328,7 @@ empty-state content remains one shared tree.| FR12 | `MultiSelector.test.tsx` keyboard cases ("supports keyboard navigation with ArrowDown/ArrowUp", "End/Home jump the highlight to the last/first option (non-search)", "PageDown/PageUp jump the highlight to the last/first filtered option", "Home/End move the search caret, not the option highlight", "toggles item with Enter key", "does not toggle the highlighted option on a composing Enter (IME)", "closes on Escape", "closes combobox on Tab and moves focus to next element", "opens the listbox with ArrowDown from a focused trigger", the Delete and Backspace clear cases), and "tabs from the search input to the clear button (keeping the popup open) when a query is showing it" | Current source and tests | A key that does the wrong move, a composing Enter that toggles, or a clear with nothing selected fails. | `audit:MultiSelector/accessibility` || FR13 | `MultiSelector.fr10.test.tsx` cases; `MultiSelector.test.tsx` caller aria-labelledby cases | Control box; caller handlers; renderTrigger | A root styling prop, `control*` off the control box, a caller handler before the built-in one, or a lost caller name or description fails. Evidence gap: no test asserts that a caller `onKeyDown` is skipped for a key the built-in model cancels, or the trigger height or its growth with text size (the FR13 gap). | `audit:MultiSelector/layout` || FR14, ORD1 | `MultiSelector.test.tsx` announcements, result-announcement, count-text, and form-participation cases; hasCreate announcement cases | Toggle, select-all, clear; search counts; loading; form | A missing or wrong announcement, a search-result announcement while loading, or a wrong form entry fails. Evidence gap: no test asserts the `onChange`-before-`changeAction` order. | `audit:MultiSelector/behavior` |+| FR15 | `MultiSelector.test.tsx` "with the built-in trigger, a light dismiss onto another field leaves focus there, and Escape returns it to the trigger" | Escape; light dismiss onto another field | A trigger that takes focus back from another field, or loses it on Escape, fails. | `audit:MultiSelector/behavior` || PR1 | Evidence gap: no test asserts the absence of listeners or the timer bounds | — | — | `audit:MultiSelector/behavior` || Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and targets | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:MultiSelector/theming` |diff --git a/docs/specs/components/Selector/Selector.spec.md b/docs/specs/components/Selector/Selector.spec.mdindex 672c55f317..3e7bcdba80 100644--- a/docs/specs/components/Selector/Selector.spec.md+++ b/docs/specs/components/Selector/Selector.spec.md@@ -210,8 +210,8 @@ These requirements describe shipped behavior on current `main`.and the trigger uses `aria-haspopup="dialog"`.- **AR2 — Focus follows the active interaction model.** The anchored presentationkeeps the combobox relationship at the trigger/search control. The modal touch- presentation moves focus into its search control or listbox and restores focus- to the trigger when it closes.+ presentation moves focus into its search control or listbox. On close, focus+ returns to the trigger only when focus would otherwise be lost (`family:overlay-dismissal` FR9); a close caused by moving focus elsewhere leaves focus there.- **AR3 — Keyboard selection matches the visible set.** Arrow, Home/End,typeahead, search, Enter, Escape, and Tab behavior operate on the options aperson can currently perceive.@@ -340,18 +340,18 @@ new theming target.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |-| FR1, AR2, AR3 | `Selector.test.tsx` selection, focus, and keyboard suites | closed/open, search/non-search, disabled option | Removing selection wiring, focus movement, or keyboard behavior fails the named interaction tests | `audit:Selector/behavior` |-| FR2 | placement and selected-item geometry tests | default, explicit, RTL, transformed entry | Using the wrong positioning model fails the expected position-area or margin | `audit:Selector/behavior` |-| FR3, AV1 | Focused `Selector.test.tsx` computed-display checks plus guarded Chromium Storybook matrix and stable visual stories | popover/bottom sheet, narrow/wide, start/end, LTR/RTL, selected/unselected, check/radio | Empty output reserves width, visible output collapses, logical placement flips incorrectly, or row content overflows | `audit:Selector/design-rendered` |-| FR4, AR1, AR2 | presentation tests plus `aria-haspopup` source review | pointer, compact coarse pointer, search/non-search | Wrong Popover/dialog roles or focus destinations fail tests; `aria-haspopup` values require source/a11y review | `audit:Selector/accessibility` |-| AR1, AV2 | `Selector.listbox.a11y.test.tsx` and `Listbox.a11y.chromium.spec.ts` against the shared Listbox contract | popover/sheet, flat/grouped, selected/unselected, disabled, search, loading, custom RTL | A new or wider loss of role, listbox/option name, state, or ownership gates; the exact unnamed no-search sheet state remains known debt | `audit:Selector/accessibility` |-| FR5, FR6, AR1, AR2 (anchored), AR4 | `Selector.combobox.a11y.test.tsx` and `Selector.combobox.a11y.chromium.spec.ts` against the shared Combobox contract | closed, open with active option, read-only, busy, bottom-sheet open, search input with active option | The trigger or search input loses its role/name/state or popup kind, its open popup or active option relationship breaks, or read-only exposes a selection surface; the bottom-sheet trigger's `aria-controls` naming the inner listbox remains exact known debt | `audit:Selector/accessibility` |-| FR5 | loading, empty-state, and live-region tests | empty options, unmatched search, loading | Empty/no-results output appears or is announced while loading | `audit:Selector/behavior` |-| FR6, AR4 | read-only interaction, form, ARIA, and theme-state tests | search/non-search, clearable, open→read-only, disabled precedence | A value changes, popup or edit affordance remains, form value disappears, or read-only semantics are absent | `audit:Selector/accessibility` |-| FR7 | `Selector.test.tsx` press model suite | finger release over another option, finger/mouse release outside, listbox marker | The press option is selected, the listbox takes focus, a finger release outside closes the list, or the stray click selects | `audit:Selector/behavior` |-| source-build contract | `Selector.source-build.test.mjs` | package source compiled by consumer Babel | Moving evaluated StyleX values outside the supported source form fails compilation | `audit:Selector/code-health` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |+| FR1, AR2, AR3 | `Selector.test.tsx` selection, focus, and keyboard suites, including "leaves focus on the field a press moved it to" and "returns focus to the trigger when the press lands on nothing focusable" | closed/open, search/non-search, disabled option | Removing selection wiring, focus movement, or keyboard behavior fails the named interaction tests | `audit:Selector/behavior` |+| FR2 | placement and selected-item geometry tests | default, explicit, RTL, transformed entry | Using the wrong positioning model fails the expected position-area or margin | `audit:Selector/behavior` |+| FR3, AV1 | Focused `Selector.test.tsx` computed-display checks plus guarded Chromium Storybook matrix and stable visual stories | popover/bottom sheet, narrow/wide, start/end, LTR/RTL, selected/unselected, check/radio | Empty output reserves width, visible output collapses, logical placement flips incorrectly, or row content overflows | `audit:Selector/design-rendered` |+| FR4, AR1, AR2 | presentation tests plus `aria-haspopup` source review | pointer, compact coarse pointer, search/non-search | Wrong Popover/dialog roles or focus destinations fail tests; `aria-haspopup` values require source/a11y review | `audit:Selector/accessibility` |+| AR1, AV2 | `Selector.listbox.a11y.test.tsx` and `Listbox.a11y.chromium.spec.ts` against the shared Listbox contract | popover/sheet, flat/grouped, selected/unselected, disabled, search, loading, custom RTL | A new or wider loss of role, listbox/option name, state, or ownership gates; the exact unnamed no-search sheet state remains known debt | `audit:Selector/accessibility` |+| FR5, FR6, AR1, AR2 (anchored), AR4 | `Selector.combobox.a11y.test.tsx` and `Selector.combobox.a11y.chromium.spec.ts` against the shared Combobox contract | closed, open with active option, read-only, busy, bottom-sheet open, search input with active option | The trigger or search input loses its role/name/state or popup kind, its open popup or active option relationship breaks, or read-only exposes a selection surface; the bottom-sheet trigger's `aria-controls` naming the inner listbox remains exact known debt | `audit:Selector/accessibility` |+| FR5 | loading, empty-state, and live-region tests | empty options, unmatched search, loading | Empty/no-results output appears or is announced while loading | `audit:Selector/behavior` |+| FR6, AR4 | read-only interaction, form, ARIA, and theme-state tests | search/non-search, clearable, open→read-only, disabled precedence | A value changes, popup or edit affordance remains, form value disappears, or read-only semantics are absent | `audit:Selector/accessibility` |+| FR7 | `Selector.test.tsx` press model suite | finger release over another option, finger/mouse release outside, listbox marker | The press option is selected, the listbox takes focus, a finger release outside closes the list, or the stray click selects | `audit:Selector/behavior` |+| source-build contract | `Selector.source-build.test.mjs` | package source compiled by consumer Babel | Moving evaluated StyleX values outside the supported source form fails compilation | `audit:Selector/code-health` |## Decision logdiff --git a/packages/core/src/ComplexSelector/ComplexSelector.test.tsx b/packages/core/src/ComplexSelector/ComplexSelector.test.tsxindex ec83a825f9..9fceee79e2 100644--- a/packages/core/src/ComplexSelector/ComplexSelector.test.tsx+++ b/packages/core/src/ComplexSelector/ComplexSelector.test.tsx@@ -949,6 +949,80 @@ describe('ComplexSelector onOpenChange', () => {expect(onOpenChange.mock.calls).toEqual([[false]]);});+ describe('focus on close', () => {+ function lightDismiss(): void {+ const popover = screen+ .getByRole('dialog', {hidden: true})+ .closest('[popover]') as HTMLElement;+ act(() => {+ popover.dispatchEvent(+ Object.assign(new Event('toggle'), {+ oldState: 'open',+ newState: 'closed',+ }),+ );+ });+ }++ it('Escape and a close from the content return focus to the trigger', async () => {+ const user = userEvent.setup();+ const trigger = renderSelector(() => {});+ await user.click(trigger);+ await user.keyboard('{Escape}');+ expect(trigger).toHaveFocus();+ await user.click(trigger);+ await user.click(screen.getByRole('button', {name: 'Apply', ...h}));+ expect(trigger).toHaveFocus();+ });++ it('a light dismiss onto another control leaves focus there; onto nothing focusable it returns to the trigger', async () => {+ const user = userEvent.setup();+ render(+ <>+ <ComplexSelector label="View options" value={[]}>+ {() => <button type="button">Apply</button>}+ </ComplexSelector>+ <input aria-label="Notes" />+ </>,+ );+ const trigger = screen.getByRole('combobox', {name: 'View options'});+ const notes = screen.getByRole('textbox', {name: 'Notes'});+ await user.click(trigger);+ act(() => notes.focus());+ lightDismiss();+ expect(notes).toHaveFocus();++ await user.click(trigger);+ act(() => (document.activeElement as HTMLElement | null)?.blur());+ lightDismiss();+ expect(trigger).toHaveFocus();+ });++ it('a caller-rendered control gets focus back even after a light dismiss onto another control', async () => {+ const user = userEvent.setup();+ render(+ <>+ <ComplexSelector+ label="View options"+ value={[]}+ renderTrigger={props => (+ <button type="button" {...props}>+ Options+ </button>+ )}>+ {() => <button type="button">Apply</button>}+ </ComplexSelector>+ <input aria-label="Notes" />+ </>,+ );+ const opener = screen.getByRole('combobox', {name: 'View options'});+ await user.click(opener);+ act(() => screen.getByRole('textbox', {name: 'Notes'}).focus());+ lightDismiss();+ expect(opener).toHaveFocus();+ });+ });+it('reports opens and closes driven through the imperative handle', () => {const onOpenChange = vi.fn();const handleRef = React.createRef<ComplexSelectorHandle>();diff --git a/packages/core/src/ComplexSelector/ComplexSelector.tsx b/packages/core/src/ComplexSelector/ComplexSelector.tsxindex c013cb0fb6..642b6ff954 100644--- a/packages/core/src/ComplexSelector/ComplexSelector.tsx+++ b/packages/core/src/ComplexSelector/ComplexSelector.tsx@@ -35,6 +35,7 @@ import {} from '../Field/fieldParts';import {useDevWarning} from '../hooks/useDevWarning';import {mergeRefs} from '../utils/mergeRefs';+import {isFocusLost} from '../utils/focusReturn';import {useMergedRefs} from '../hooks/useMergedRefs';import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';import {Field, inputWrapperStyles} from '../Field';@@ -347,7 +348,10 @@ export interface ComplexSelectorRenderState {export interface ComplexSelectorHandle {/** Open the selector surface. No-op when disabled or already open. */open(): void;- /** Close the selector surface. Restores focus to the trigger. */+ /**+ * Close the selector surface. Focus returns to the trigger only when it+ * would otherwise be lost; a caller-rendered trigger always gets it back.+ */close(): void;/** Toggle the selector surface open or closed. */toggle(): void;@@ -630,12 +634,22 @@ export function ComplexSelector<Value>({onOpenChange?.(true);}, [onOpenChange]);+ // The popup's content element, read when it closes.+ const popupContentRef = useRef<HTMLElement | null>(null);+ const hasCallerTrigger = renderTrigger != null;const handlePopoverHide = useCallback(() => {- // Focus is restored first so a consumer that moves focus elsewhere from- // the callback wins, instead of being overwritten a line later.- triggerRef.current?.focus();+ const trigger = triggerRef.current;+ // A press that moved focus to another control keeps it there. A caller's+ // control always gets focus back. Focus moves before the callback, so a+ // consumer that moves it from the callback wins.+ if (+ hasCallerTrigger ||+ isFocusLost(popupContentRef.current, trigger?.ownerDocument)+ ) {+ trigger?.focus();+ }onOpenChange?.(false);- }, [onOpenChange]);+ }, [hasCallerTrigger, onOpenChange]);const popover = usePopover({dialogLabel: label,@@ -645,6 +659,7 @@ export function ComplexSelector<Value>({onShow: handlePopoverShow,onHide: handlePopoverHide,});+ popupContentRef.current = popover.contentRef.current;const isOpen = popover.isOpen;diff --git a/packages/core/src/MultiSelector/MultiSelector.test.tsx b/packages/core/src/MultiSelector/MultiSelector.test.tsxindex d280f5ada1..41fc3bef1f 100644--- a/packages/core/src/MultiSelector/MultiSelector.test.tsx+++ b/packages/core/src/MultiSelector/MultiSelector.test.tsx@@ -3612,6 +3612,44 @@ describe('MultiSelector popup theme target', () => {});});+describe('MultiSelector built-in trigger focus on close', () => {+ it('with the built-in trigger, a light dismiss onto another field leaves focus there, and Escape returns it to the trigger', async () => {+ const user = userEvent.setup();+ render(+ <>+ <MultiSelector+ label="Labels"+ options={['Bug', 'Feature', 'Docs']}+ value={[]}+ onChange={() => {}}+ />+ <input aria-label="Notes" />+ </>,+ );+ const trigger = screen.getByRole('combobox', {name: 'Labels'});+ await user.click(trigger);+ await user.keyboard('{Escape}');+ expect(trigger).toHaveFocus();++ await user.click(trigger);+ const notes = screen.getByRole('textbox', {name: 'Notes'});+ act(() => {+ notes.focus();+ });+ const popover = document.querySelector('[popover]') as HTMLElement;+ act(() => {+ popover.dispatchEvent(+ Object.assign(new Event('toggle'), {+ oldState: 'open',+ newState: 'closed',+ }),+ );+ });+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ expect(notes).toHaveFocus();+ });+});+describe('MultiSelector trigger render prop', () => {const OPTIONS = [{value: 'bug', label: 'Bug'},