An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): CommandPalette records its shipped contract as current (#9306)
Cindy Zhang27ccfe043b3a
diff --git a/docs/specs/components/CommandPalette/CommandPalette.spec.md b/docs/specs/components/CommandPalette/CommandPalette.spec.mdindex 4dff2ab531..cf2b3ee252 100644--- a/docs/specs/components/CommandPalette/CommandPalette.spec.md+++ b/docs/specs/components/CommandPalette/CommandPalette.spec.md@@ -3,11 +3,11 @@ schema_version: 3template_version: 7kind: componentid: component:CommandPalette-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: [behavior, theming, accessibility]verified_by:@@ -40,15 +40,15 @@ system_specs: [spec:AST-056]## Contract at a glance-| Area | Contract |-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| Public contract | Prop and visual APIs are unchanged. The result surface exposes listbox semantics only with selectable results; the query input has a real default name; rich Empty content remains ordinary. |-| Behavior | Modal Escape delegates to Dialog; query-field Home/End and IME remain native; result changes reset stale highlight; Empty announcements mirror rendered content. |-| End-user impact | Nested dismissal and native text entry are preserved; assistive technology receives the visible empty message, an independent query-field name, and only existing active options. |-| Builder impact | None; no migration or new caller choice. |-| Compatibility/readiness | Visual output is preserved. Empty-result ARIA, query-field accessible naming, empty-state announcement, and highlight reset behavior are corrected and verified. |-| Review checks | Reject local modal Escape handling, IME routing, Home/End result navigation, empty listboxes, stale active descendants, placeholder-only names, mismatched Empty announcements, or gaps. |-| Governing rules | `family:overlay-dismissal/FR1`, `FR2`, `FR4`, `FR5`; `spec:AST-056/FR3`, `AR1`, `AR2`; existing public component and delegated-owner contracts. |+| Area | Contract |+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | `CommandPalette` with its documented props and slots, composed from `CommandPaletteInput`, `CommandPaletteList`, `CommandPaletteItem`, `CommandPaletteGroup`, `CommandPaletteEmpty`, and `CommandPaletteFooter`, inside a Dialog. |+| Behavior | Searchable commands in a Dialog: a combobox query field, a listbox of results only while selectable results exist, an empty message otherwise, and a keyboard-guidance footer. Modal Escape belongs to Dialog's shared dismissal. |+| End-user impact | Keyboard and screen-reader users search and run commands with native text editing kept intact, hear the empty message that is shown, and close nested layers one Escape at a time. |+| Builder impact | None. |+| Compatibility/readiness | Records shipped behavior; no public change. AR1's caller `aria-label` rule is an implementation gap in `component:CommandPaletteList`, listed in its Current-state impact; two owner questions stay open (OQ2 asks whether INV5 should state this composite-semantics reading family-wide). |+| Review checks | Reject local modal Escape handling, IME routing, Home/End result navigation, empty listboxes, stale active descendants, placeholder-only names, mismatched Empty announcements, or gaps. |+| Governing rules | `family:overlay-dismissal/FR1`, `FR2`, `FR4`, `FR5`; `spec:AST-056/FR3`, `AR1`, `AR2`; existing public component and delegated-owner contracts. |This table is a review projection; the body below is authoritative.@@ -60,19 +60,19 @@ surface and modal dismissal ordering to Dialog.## Compatibility and migration-- Released default preserved: `yes` for props and visual output-- Compatibility class: behavioral and accessibility correction; empty states- conditionally omit listbox, expanded, controls, and active-descendant ARIA- attributes until selectable results exist; the default query accessible name- is independent of its placeholder; empty-search announcements mirror the- rendered content; public props, styling, targets, and visible defaults remain- unchanged-- Controlled/uncontrolled behavior: unchanged-- Migration decision: adopts `family:overlay-dismissal/FR1`, `FR2`, `FR4`, and- `FR5` through Dialog; no caller migration+- Released default preserved: `yes`+- Compatibility class: records shipped behavior; no public change+- Controlled/uncontrolled behavior: as documented in `CommandPalette.doc.mjs`+- Migration decision: noneConsumer migration instructions belong in consumer docs and release notes.+## Current-state impact++- **The List replaces a caller's name (AR1).** A builder's explicit+ `aria-label` does not name the List today; `component:CommandPaletteList`+ records the gap.+## Ownership boundary**Owns**@@ -89,12 +89,14 @@ Consumer migration instructions belong in consumer docs and release notes.content — owned by the product callsite.- The Item option's passthrough, pointer, disabled, selected, highlighted, andstandalone-scroll semantics — owned by `component:CommandPaletteItem`.-- A `command-palette` root target — no such current target exists, and this- factual backfill does not invent one.+- A `command-palette` root target — no such target exists.- Shared layer hosting, positioning, or lifecycle rules beyond the currentrecords linked below.- The List root's accessible name, list-id application, native passthrough, andoverflow scrolling — owned by `component:CommandPaletteList`.+- The Group's role, name, and heading — owned by `component:CommandPaletteGroup`;+ the Footer's guidance — owned by `component:CommandPaletteFooter`; the Empty+ surface — owned by `component:CommandPaletteEmpty`.## Public concepts@@ -103,16 +105,16 @@ documented in `CommandPalette.doc.mjs` and its subcomponent docs.## Behavioral and layout contract-| ID | Candidate invariant | Basis | Draft review state |-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |-| FR1 | The current default render places Input and Footer around a result surface inside a delegated Dialog. That surface is a List listbox while Items exist and an ordinary Empty container otherwise. | Current source, docs, tests, and ARIA required-child rule | Verified current anatomy and valid rich Empty semantics |-| FR2 | Input, List, Item, Group, Group heading, Empty, and Footer carry the seven current `command-palette-*` targets documented below; no `command-palette` root target exists. | Current source and target docs | Verified current inventory and focused placement coverage |-| FR3 | The default Input delegates its Search glyph to Icon and pending Loading spinner to Spinner; the default Footer delegates keyboard shortcuts to Kbd; the containing surface delegates to Dialog. | Current source and component docs | Verified current composition; no ownership change |-| FR4 | Query field is a distinct native text field inside Input and currently has no separate public target. The `command-palette-input` target is on the surrounding search region, not the native field. | Current source and target docs | Verified current reachability; long-term theming intent remains unsettled |-| FR5 | A modal palette leaves Escape unclaimed for Dialog's shared dismissal stack so a nested member handles the first press; inline previews close locally because they do not register as layers. | `family:overlay-dismissal/FR1`, `FR2`, `FR4`, `FR5` | Verified by nested and inline integration tests |-| FR6 | The editable query field keeps Home and End for native caret movement, uses PageUp and PageDown for first/last result navigation, and does not route active IME composition keys to commands. | WAI-ARIA editable combobox convention; objective IME integrity | Verified by user-event navigation and composition-key tests |-| FR7 | A committed result set resets highlight before exposure; the query input emits active-descendant only for an index that exists in the current selectable set. | WAI-ARIA active-descendant integrity | Verified across populated, empty, and repopulated results |-| FR8 | Empty search announcements mirror rendered `emptySearchText`, including rich caller content; the query input's default accessible name is independent of its placeholder. | `spec:AST-056/FR3`, `AR1`, `AR2` | Verified by live-region and accessible-name tests |+| ID | Invariant | Basis |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |+| FR1 | The default render places Input and Footer around a result surface inside a delegated Dialog. That surface is a List listbox while Items exist and an ordinary Empty container otherwise. | Current source, docs, tests, and ARIA required-child rule |+| FR2 | Input, List, Item, Group, Group heading, Empty, and Footer carry the seven current `command-palette-*` targets documented below; no `command-palette` root target exists. | Current source and target docs |+| FR3 | The default Input delegates its Search glyph to Icon and pending Loading spinner to Spinner; the default Footer delegates keyboard shortcuts to Kbd; the containing surface delegates to Dialog. | Current source and component docs |+| FR4 | Query field is a distinct native text field inside Input and has no separate public target. The `command-palette-input` target is on the surrounding search region, not the native field. | Current source and target docs |+| FR5 | A modal palette leaves Escape unclaimed for Dialog's shared dismissal stack so a nested member handles the first press; inline previews close locally because they do not register as layers. | `family:overlay-dismissal/FR1`, `FR2`, `FR4`, `FR5` |+| FR6 | The editable query field keeps Home and End for native caret movement, uses PageUp and PageDown for first/last result navigation, and does not route active IME composition keys to commands. | WAI-ARIA editable combobox convention; objective IME integrity |+| FR7 | A committed result set resets highlight before exposure; the query input emits active-descendant only for an index that exists in the current selectable set. | WAI-ARIA active-descendant integrity |+| FR8 | Empty search announcements mirror rendered `emptySearchText`, including rich caller content; the query input's default accessible name is independent of its placeholder. | `spec:AST-056/FR3`, `AR1`, `AR2` |### Allowed variation@@ -136,17 +138,21 @@ documented in `CommandPalette.doc.mjs` and its subcomponent docs.### Transformation and precedence order-- No new search, selection, layout, or styling precedence rule is introduced.+- No search, selection, layout, or styling precedence rule beyond FR1–FR8.### Performance and resources-- No new performance or resource rule is introduced.+- No resource rule.## Accessibility contract- **AR1 — Named composite.** The containing Dialog, combobox, populated listbox,groups, options, busy status, empty state, and keyboard guidance preserve their- owned accessible names and roles. When no selectable results exist, the result+ owned accessible names and roles. A caller's explicit `aria-label` names a List or+ Group (`architecture:public-component-api` INV5); the `listbox` and `option`+ roles and option state stay component-owned, as+ `component:CommandPaletteInput` AR3 records. `component:CommandPaletteList`+ records where today's List replaces a caller's name. When no selectable results exist, the resultsurface and combobox omit listbox, expanded, controls, and active-descendantsemantics so rich Empty content stays ordinary non-nested content.- **AR2 — Topmost Escape.** A modal palette delegates unclaimed Escape presses to@@ -184,8 +190,7 @@ documented in `CommandPalette.doc.mjs` and its subcomponent docs.| Keyboard shortcut | Presents one shortcut as painted key badges in the default Footer. | `component:Kbd` | Supporting | FR3 |The native Query field is separate from the Input region that carries-`command-palette-input`. Its current lack of a direct target is observed-reachability, not a decision that it must remain unthemeable.+`command-palette-input`. It has no direct target; whether it should is OQ1.### Theming anatomy@@ -221,15 +226,15 @@ reachability, not a decision that it must remain unthemeable.```The seven local targets are current public seams. The delegated parts retain-their existing component owners. The Query field `none` disposition records a-current audit gap and does not authorize a new target.+their existing component owners. The Query field `none` disposition is+unsettled (OQ1) and does not authorize a new target.## Family and system relationships- `architecture:component-theming-surface` owns anatomy qualification, targetmapping, delegation, and factual `none` dispositions.- `architecture:public-component-api` owns the stable props and composition- surface; this documentation adds no API.+ surface.- `architecture:interaction-modality/INV4` owns supported-modality pathreachability; the exact query-key details follow objective editable-comboboxand IME composition standards.@@ -244,35 +249,41 @@ current audit gap and does not authorize a new target.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |-| FR1, AR1 | CommandPalette root and subcomponent suites plus exact-head Chromium evidence | Default, grouped, empty, pending, rich Empty, and replaced slots | Exposing an empty listbox, leaving empty Input popup attributes, or nesting rich Empty controls under option semantics fails focused role and hosted axe assertions. | `audit:CommandPalette/anatomy` |-| FR2 | Focused subcomponent suites and `themingTargets.test.ts` | Seven local targets at their owned elements | Removing or moving a current target fails a focused placement assertion or the global inventory. | `audit:CommandPalette/theming` |-| FR3 | `CommandPaletteInput.test.tsx`, `CommandPaletteFooter.test.tsx`, and browser evidence | Default Search glyph, pending spinner, and Footer Kbd | Replacing or removing the delegated Icon, Spinner, or Kbd instance fails a composed-owner assertion and changes the exact-head evidence inventory. | `audit:CommandPalette/theming` |-| FR4 | `CommandPaletteInput.test.tsx` and source inspection | Native query field with idle and pending Input | Removing the field fails combobox tests; adding a field target requires an explicit map update. | `audit:CommandPalette/anatomy` |-| FR5, AR2, AR3 | `CommandPalette.test.tsx` | Modal host with nested layer; inline preview | Restoring local modal Escape handling closes the host instead of the nested surface; removing the inline branch loses preview closing. | `audit:CommandPalette/interaction` |-| FR6, AR4 | `CommandPalette.test.tsx` and `CommandPaletteInput.test.tsx` | Home, End, PageDown, Enter, and active IME composition | Routing Home/End to results or forwarding a composing command key fails user-event and native composition assertions. | `audit:CommandPalette/interaction` |-| FR7, AR7 | `CommandPalette.test.tsx` and `CommandPaletteInput.test.tsx` | Populated, empty, and repopulated result sets | Preserving an out-of-range highlight or emitting its nonexistent active descendant fails transition and direct bounds assertions. | `audit:CommandPalette/a11y` |-| FR8, AR5, AR6 | `CommandPalette.test.tsx`, `CommandPaletteInput.test.tsx`, and i18n checks | Rich caller Empty content; default and caller query names | Announcing catalog copy over rendered caller content or naming the query only through placeholder text fails live-region, name, and catalog assertions. | `audit:CommandPalette/a11y` |-| Theming anatomy map | `scripts/check-knowledge.mjs` and exact-head Chromium evidence | Canonical anatomy and seven current local targets | Missing, extra, prefixed, stale, alias-backed, or visually absent mappings fail repository validation or browser sensor counts. | `audit:CommandPalette/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |+| FR1, AR1 | CommandPalette root and subcomponent suites | Default, grouped, empty, pending, rich Empty, and replaced slots | Exposing an empty listbox, leaving empty Input popup attributes, or nesting rich Empty controls under option semantics fails focused role assertions. | `audit:CommandPalette/anatomy` |+| FR2 | Focused subcomponent suites and `themingTargets.test.ts` | Seven local targets at their owned elements | Removing or moving a current target fails a focused placement assertion or the global inventory. | `audit:CommandPalette/theming` |+| FR3 | `CommandPaletteInput.test.tsx` and `CommandPaletteFooter.test.tsx` | Default Search glyph, pending spinner, and Footer Kbd | Replacing or removing the delegated Icon, Spinner, or Kbd instance fails a composed-owner assertion. | `audit:CommandPalette/theming` |+| FR4 | `CommandPaletteInput.test.tsx` | Native query field with idle and pending Input | Removing the field fails combobox tests; adding a field target requires an explicit map update. | `audit:CommandPalette/anatomy` |+| FR5, AR2, AR3 | `CommandPalette.test.tsx` | Modal host with nested layer; inline preview | Restoring local modal Escape handling closes the host instead of the nested surface; removing the inline branch loses preview closing. | `audit:CommandPalette/interaction` |+| FR6, AR4 | `CommandPalette.test.tsx` and `CommandPaletteInput.test.tsx` | Home, End, PageDown, Enter, and active IME composition | Routing Home/End to results or forwarding a composing command key fails user-event and native composition assertions. | `audit:CommandPalette/interaction` |+| FR7, AR7 | `CommandPalette.test.tsx` and `CommandPaletteInput.test.tsx` | Populated, empty, and repopulated result sets | Preserving an out-of-range highlight or emitting its nonexistent active descendant fails transition and direct bounds assertions. | `audit:CommandPalette/a11y` |+| FR8, AR5, AR6 | `CommandPalette.test.tsx`, `CommandPaletteInput.test.tsx`, and i18n checks | Rich caller Empty content; default and caller query names | Announcing catalog copy over rendered caller content or naming the query only through placeholder text fails live-region, name, and catalog assertions. | `audit:CommandPalette/a11y` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and seven current local targets | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. Gap: no check fails if a mapped part stops painting. | `audit:CommandPalette/theming` |Focused target-placement assertions cover all seven local targets. The composedInput and Footer tests also pin the delegated Search Icon, pending Spinner, and-four default Kbd shortcuts; exact-head browser evidence verifies the same owned-anatomy across light, dark, LTR, RTL, and narrow rendering.+four default Kbd shortcuts.## Decision log-None. This draft records current facts and introduces no component-local design,-layer, API, or theming decision.+No component-local decision is recorded.## Open questions- **OQ1 — Should Query field gain a stable public theming target?** (`human-api`)- Its current lack of direct reachability is an audit gap, not settled intent.+ It has no direct target today, and no owner has decided whether it should.+- **OQ2 — Should `architecture:public-component-api` INV5 state the+ composite-semantics reading family-wide?** (`human-api`) Inside a composite+ such as CommandPalette, roles like `combobox`, `listbox`, and `option` and+ option state are component-owned and replace a caller's, as+ `component:CommandPaletteInput` AR3 records, while a caller's explicit name+ still wins. Stating it in INV5 would make every composite follow it; leaving+ it here keeps it a CommandPalette reading that other composites may not+ share.## Content boundaryThis file does not duplicate consumer prop tables/examples, shared layer or-modality rules, current audit results, or implementation steps. It links to+modality rules, or implementation steps. It links totheir owners.diff --git a/docs/specs/components/CommandPalette/CommandPaletteEmpty.spec.md b/docs/specs/components/CommandPalette/CommandPaletteEmpty.spec.mdindex cd324b8612..1ec47de01b 100644--- a/docs/specs/components/CommandPalette/CommandPaletteEmpty.spec.md+++ b/docs/specs/components/CommandPalette/CommandPaletteEmpty.spec.md@@ -3,11 +3,11 @@ schema_version: 3template_version: 7kind: componentid: component:CommandPaletteEmpty-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, theming, accessibility, testing]verified_by:@@ -42,8 +42,8 @@ system_specs: [spec:AST-029, spec:AST-056]| Public contract | `CommandPaletteEmpty` / `CommandPaletteEmptyProps`: required `children`, `BaseProps<HTMLDivElement>`, and a root `ref`. || Behavior | One ordinary container centers caller content as supporting text. CommandPalette renders it for the no-query and no-results branches; it owns no role, state, announcement, or interaction. || End-user impact | People who reach a palette dead end read the message, and any caller link stays ordinary reachable content rather than an option. |-| Builder impact | None. Caller content, host attributes, and styling inputs compose on the root. |-| Compatibility/readiness | Observational patch contract. Runtime behavior, exports, and the target name are unchanged; authority stays `draft` until exact-head owner approval. |+| Builder impact | None. |+| Compatibility/readiness | Records shipped behavior; no public change. Evidence still pending for the claims listed as read from source. || Review checks | Reject a component-owned role or live region, option semantics around caller content, dropped root inputs, a target moved off the painted root, or content that overflows its host inline axis. || Governing rules | `architecture:public-component-api/INV1,INV5–INV8`; `architecture:component-theming-surface/INV2–INV6`; `spec:AST-056/FR3`, `AR1` for the parent's announcement; WCAG 2.2 SC 1.4.3 and 1.4.10. |@@ -61,8 +61,8 @@ Consumer syntax and examples belong in `CommandPaletteEmpty.doc.mjs`.## Compatibility and migration-- Released default preserved: yes — one centered, ordinary message container.-- Compatibility class: observational patch; no public surface changes.+- Released default preserved: `yes`+- Compatibility class: records shipped behavior; no public change- Controlled/uncontrolled behavior: not applicable.- Migration decision: none.@@ -97,17 +97,14 @@ Consumer migration instructions belong in consumer docs and release notes.## Behavioral and layout contract-Draft requirements identify their basis so observed code is not mistaken for an-intentional decision.--| ID | Candidate invariant | Basis | Draft review state |-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------ |-| FR1 | The component MUST render its children inside one container element that centers them on both axes with centered text, supporting type, body font family, and secondary text color. | Current source, consumer docs, and focused tests | verify |-| FR2 | CommandPalette MUST render this component with `emptyBootstrapText` when there is no query and no result, and with `emptySearchText` when a query has no result. | Current CommandPalette source and tests | verify |-| FR3 | The root MUST carry no component-owned role, live region, or focus stop, so caller links and controls remain ordinary content. | WAI-ARIA 1.2 listbox owned-children rule; current source and Chromium evidence | verify |-| FR4 | Caller text MUST wrap inside the host's inline size, including a single unbroken token, so no message forces inline scrolling or clipping at 320 CSS px. | WCAG 2.2 SC 1.4.10; Chromium evidence | verify |-| FR5 | The painted root MUST carry the `command-palette-empty` target; component styles apply before caller `xstyle`. | `architecture:component-theming-surface/INV2–INV6`; source and focused tests | verify |-| FR6 | Accepted ref, DOM/data/ARIA, class, style, events, and `xstyle` MUST reach or compose on the root. | `architecture:public-component-api/INV5–INV8`; focused tests | verify |+| ID | Invariant | Basis |+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |+| FR1 | The component MUST render its children inside one container element that centers them on both axes with centered text, supporting type, body font family, and secondary text color. | Current source, consumer docs, and focused tests |+| FR2 | CommandPalette MUST render this component with `emptyBootstrapText` when there is no query and no result, and with `emptySearchText` when a query has no result. | Current source and tests |+| FR3 | The root MUST carry no component-owned role, live region, or focus stop, so caller links and controls remain ordinary content. | WAI-ARIA 1.2 listbox owned-children rule; current source and tests |+| FR4 | Caller text MUST wrap inside the host's inline size, including a single unbroken token, so no message forces inline scrolling or clipping at 320 CSS px. | WCAG 2.2 SC 1.4.10; current source |+| FR5 | The painted root MUST carry the `command-palette-empty` target; component styles apply before caller `xstyle`. | `architecture:component-theming-surface/INV2–INV6`; source and focused tests |+| FR6 | Accepted ref, DOM/data/ARIA, class, style, events, and `xstyle` MUST reach or compose on the root. | `architecture:public-component-api/INV5–INV8`; focused tests |### Allowed variation@@ -147,11 +144,12 @@ intentional decision.## Design relationships-| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |-| ---------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------- | ------------------ |-| Empty message | Presents the dead-end message as supporting text centered in the results. | Current source tokens; no component-local visual decision settled | supporting | FR1, FR4, FR5 |+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ---------------- | ------------------------------------------------------------------------- | ------------------------ | -------------- | ------------------ |+| Empty message | Presents the dead-end message as supporting text centered in the results. | Current source tokens | supporting | FR1, FR4, FR5 |-No component-local visual decision is settled by this draft.+No component-local design decision is recorded. The aggregate CommandPalette+anatomy map, owned by `component:CommandPalette`, maps the Empty part.## Family and system relationships@@ -161,23 +159,29 @@ No component-local visual decision is settled by this draft.evidence.- `spec:AST-056/FR3` and `AR1` require CommandPalette to announce theempty-search message it rendered; this component supplies the rendered node.-- CommandPalette and CommandPaletteList draft records describe the parent- branches and empty result surface; they are observational context, not- authority for this contract.-- `spec:AST-029` keeps this observational draft separate from the audit receipt.+- `component:CommandPalette` and `component:CommandPaletteList` own the parent+ branches and the empty result surface.+- `spec:AST-029` owns the audit evidence inventory this record's verification+ map follows.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------ |-| FR1, FR5–FR6 | `CommandPaletteEmpty.test.tsx`; `themingTargets.test.ts` | text and element children; root inputs | A dropped input, a moved target, or lost children fails the focused assertions. | `audit:CommandPaletteEmpty/§2,§3,§4` |-| FR2, FR3, AR1 | `CommandPalette.test.tsx`; `CommandPaletteList.test.tsx`; exact-head Chromium receipts | bootstrap, search, rich content, modal and inline | Exposing a listbox, adding a role, or announcing other text than the rendered message fails assertions. | `audit:CommandPaletteEmpty/§1,§4` |-| FR4, AR2 | Exact-head Chromium receipts and contrast pairs | long and translated text; 320 px; themes and modes | Inline overflow or clipping fails the reflow sensor; ratios are recorded per frame. | `audit:CommandPaletteEmpty/§5,§10` |-| PR1 | Source review and the presentational lint rule | every state | A hook or lifecycle mechanism fails the lint rule. | `audit:CommandPaletteEmpty/§7` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------- | -------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |+| FR1, FR5–FR6 | `CommandPaletteEmpty.test.tsx`; `themingTargets.test.ts` | text and element children; root inputs | A dropped input, a moved target, or lost children fails the focused assertions. | `audit:CommandPaletteEmpty/§2,§3,§4` |+| FR2, FR3, AR1 | `CommandPalette.test.tsx`; `CommandPaletteList.test.tsx` | bootstrap, search, rich content, modal and inline | Exposing a listbox, adding a role, or announcing other text than the rendered message fails assertions. | `audit:CommandPaletteEmpty/§1,§4` |+| FR4, AR2 | `CommandPaletteEmptyAudit.a11y.chromium.spec.ts` | Narrow and wide viewports; light and dark; forced colors; rich content | A case with horizontal overflow at 320 CSS px fails the audit manifest test. Gap: the audit records message contrast without gating on it, so contrast below 4.5:1 does not fail. | `audit:CommandPaletteEmpty/accessibility` |+| PR1 | Source review | Every state | Gap: no automated check fails if CommandPaletteEmpty adds a hook, listener, or Effect. | `audit:CommandPaletteEmpty/behavior` |++Read from source, with no focused test yet:++- FR1: centering, supporting type, body font, and secondary text color.+- AR2: message contrast in each theme and mode.+- PR1: no hook, listener, or lifecycle of the component's own.## Decision log-None. This draft records current facts and introduces no product decision.+No component-local decision is recorded.## Open questions@@ -185,6 +189,5 @@ None.## Content boundary-This file does not duplicate consumer prop tables/examples, current audit scores,-screenshot matrices, implementation steps, or system rules. The audit pull request-owns the closed run evidence required by `spec:AST-029/FR5`.+This file does not duplicate consumer prop tables/examples, implementation+steps, or system rules. It links to their owners.diff --git a/docs/specs/components/CommandPalette/CommandPaletteFooter.spec.md b/docs/specs/components/CommandPalette/CommandPaletteFooter.spec.mdnew file mode 100644index 0000000000..8273ed6bb1--- /dev/null+++ b/docs/specs/components/CommandPalette/CommandPaletteFooter.spec.md@@ -0,0 +1,150 @@+---+schema_version: 3+template_version: 7+kind: component+id: component:CommandPaletteFooter+authority: current+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-11-01+owners: [cixzhang]+review_triggers: [public-api, behavior, accessibility, theming]+verified_by:+ [+ packages/core/src/CommandPalette/CommandPaletteFooter.test.tsx,+ packages/core/src/CommandPalette/__tests__/CommandPaletteFooter.a11y.chromium.spec.ts,+ ]+modules: []+families: []+design_specs: []+architecture:+ [architecture:component-theming-surface, architecture:public-component-api]+contributing: []+system_specs: []+---++# CommandPaletteFooter component contract++## Contract at a glance++| Area | Contract |+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | `CommandPaletteFooter` with optional `children`, `ref`, `xstyle`, `className`, `style`, and root DOM props. |+| Behavior | A footer row of keyboard guidance: by default, the navigate, select, and close shortcuts with translated labels; `children` replace them. |+| End-user impact | People see which keys move through, run, and close the palette. |+| Builder impact | None. |+| Compatibility/readiness | Records shipped behavior; no public change. |+| Review checks | Reject a footer that takes a role or name of its own, a lost default shortcut, or guidance that cannot wrap. |+| Governing rules | `component:Kbd`; `architecture:public-component-api`; `architecture:component-theming-surface`. |++This table is a review projection; the body below is authoritative.++## Intent++CommandPaletteFooter is the guidance row at the bottom of a CommandPalette.+Consumer usage lives in `CommandPaletteFooter.doc.mjs`.++## Compatibility and migration++- Released default preserved: `yes`+- Compatibility class: records shipped behavior; no public change+- Controlled/uncontrolled behavior: not applicable+- Migration decision: none++Consumer migration instructions belong in consumer docs and release notes.++## Ownership boundary++**Owns**++- The footer root, its layout, supporting text style, and the+ `command-palette-footer` target (FR1, FR3).+- The default guidance and its replacement by `children` (FR2).+- Root ref, DOM props, and styling (FR4).++**Does not own / non-goals**++- Painting each shortcut — owned by `component:Kbd`.+- The keyboard behavior the guidance describes — owned by+ `component:CommandPalette`.++## Public concepts++No component-local concept beyond the consumer props.++## Behavioral and layout contract++| ID | Invariant | Basis |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |+| FR1 | The root is a wrapping row of supporting text in the secondary color, with no role or name of its own. | Current source and tests |+| FR2 | Without `children`, the root shows three hints in order: Up and Down with the translated navigate label, Enter with select, and Escape with close, each shortcut a `Kbd`. `children` replace all three. | Current source and tests |+| FR3 | The root carries the `command-palette-footer` target. | Current source and tests |+| FR4 | `ref`, DOM props, `className`, `style`, and `xstyle` reach the root, with the caller's class after the generated ones. | Current source and tests |++### Allowed variation++- **AV1 — Guidance.** Callers may replace the default hints.+- **AV2 — Translation.** Label text follows the active locale.++### Representative states++| State | Required invariant | Allowed variation |+| -------------- | ------------------------------------------- | ----------------- |+| Default | Navigate, select, and close hints in order. | Locale. |+| Custom | `children` replace the defaults. | Content. |+| Narrow surface | Hints wrap onto more lines. | Line count. |++### Transformation and precedence order++- **ORD1 — Content.** `children` when given, otherwise the default hints.++### Performance and resources++- No resource rule.++## Accessibility contract++- **AR1 — No owned semantics.** The footer adds no role, name, or focus+ target; each shortcut's semantics are Kbd's.++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ----------------- | -------------------------------------- | ------------------------ | -------------- | ------------------ |+| Footer | A wrapping row of supporting guidance. | Current source | Supporting | FR1, FR3 |+| Keyboard shortcut | Shows one shortcut. | `component:Kbd` | Supporting | FR2 |++The aggregate CommandPalette anatomy map, owned by `component:CommandPalette`,+maps the Footer and Keyboard shortcut parts.++## Family and system relationships++- `component:Kbd` owns shortcut painting and semantics.+- `component:CommandPalette` owns the keyboard behavior the guidance names.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| -------- | --------------------------------------------------------------------------------------- | --------------------- | -------------------------------------------------- | --------------------------------------- |+| FR1, AR1 | `CommandPaletteFooter.test.tsx` wrap test; `CommandPaletteFooter.a11y.chromium.spec.ts` | narrow; LTR and RTL | A role or name on the root, or no wrapping, fails. | `audit:CommandPaletteFooter/layout` |+| FR2 | `CommandPaletteFooter.test.tsx` default-labels and custom-children tests | default; custom | A lost hint or ignored children fails. | `audit:CommandPaletteFooter/behavior` |+| FR3 | `CommandPaletteFooter.test.tsx` "carries the stable theme target on its single root" | any | A missing target fails. | `audit:CommandPaletteFooter/theming` |+| FR4 | `CommandPaletteFooter.test.tsx` className, xstyle, style, ref, and DOM-prop tests | root inputs | A dropped input fails. | `audit:CommandPaletteFooter/public-api` |++Read from source, with no focused test yet:++- FR1: the supporting type and secondary color.++## Decision log++No component-local decision is recorded.++## Open questions++None.++## Content boundary++This file does not duplicate consumer prop tables or examples, or+CommandPalette's search and keyboard behavior. It links to their owners.diff --git a/docs/specs/components/CommandPalette/CommandPaletteGroup.spec.md b/docs/specs/components/CommandPalette/CommandPaletteGroup.spec.mdnew file mode 100644index 0000000000..5957d2bf67--- /dev/null+++ b/docs/specs/components/CommandPalette/CommandPaletteGroup.spec.md@@ -0,0 +1,155 @@+---+schema_version: 3+template_version: 7+kind: component+id: component:CommandPaletteGroup+authority: current+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-11-01+owners: [cixzhang]+review_triggers: [public-api, behavior, accessibility, theming]+verified_by:+ [+ packages/core/src/CommandPalette/CommandPaletteGroup.test.tsx,+ packages/core/src/theme/themingTargets.test.ts,+ ]+modules: []+families: []+design_specs: []+architecture:+ [architecture:component-theming-surface, architecture:public-component-api]+contributing: []+system_specs: []+---++# CommandPaletteGroup component contract++## Contract at a glance++| Area | Contract |+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |+| Public contract | `CommandPaletteGroup` with a required string `heading`, `children`, `ref`, `xstyle`, `className`, `style`, and root DOM props. |+| Behavior | A `group` of command results named by `heading`, with the heading shown as a visual label above them. |+| End-user impact | Related commands appear under a visible heading, and screen-reader users hear the group's name when they move into it. |+| Builder impact | None. |+| Compatibility/readiness | Records shipped behavior; no public change. |+| Review checks | Reject an unnamed group, a heading read twice, or a heading target that merges with the group target. |+| Governing rules | `component:CommandPalette`; `architecture:public-component-api` INV5; `architecture:component-theming-surface`. |++This table is a review projection; the body below is authoritative.++## Intent++CommandPaletteGroup gathers related command results under a heading inside a+CommandPalette list. Consumer usage lives in `CommandPaletteGroup.doc.mjs`.++## Compatibility and migration++- Released default preserved: `yes`+- Compatibility class: records shipped behavior; no public change+- Controlled/uncontrolled behavior: not applicable+- Migration decision: none++Consumer migration instructions belong in consumer docs and release notes.++## Current-state impact++None.++## Ownership boundary++**Owns**++- The group root, its role and name, and the `command-palette-group` target+ (FR1, FR3).+- The visual heading and its `command-palette-group-heading` target (FR2, FR3).+- Root ref, DOM props, and styling (FR4).++**Does not own / non-goals**++- Option semantics and activation — owned by `component:CommandPaletteItem`.+- The list, search, and keyboard navigation — owned by+ `component:CommandPalette` and `component:CommandPaletteList`.++## Public concepts++No component-local concept beyond the consumer props.++## Behavioral and layout contract++| ID | Invariant | Basis |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |+| FR1 | The root has `role="group"` and is named by `heading` through `aria-label`, unless the caller supplies its own `role` or `aria-label` (FR4), and lays its heading and children out in one column. | Current source and tests |+| FR2 | The heading renders `heading` as supporting text before the children and is hidden from assistive technology, so the name is read once. | Current source and tests |+| FR3 | The root carries `command-palette-group` and the heading carries the separate `command-palette-group-heading` target. | Current source and tests |+| FR4 | `ref`, DOM props, `className`, `style`, and `xstyle` reach the root, and a caller's explicit `role` or `aria-label` reaches it (`architecture:public-component-api` INV5). | Current source |++### Allowed variation++- **AV1 — Content.** The heading text and the grouped items vary.+- **AV2 — Theme.** Themes restyle the group and the heading separately.++### Representative states++| State | Required invariant | Allowed variation |+| --------------- | ------------------------------------------- | ----------------- |+| Grouped results | A named group with a hidden visual heading. | Items. |++### Transformation and precedence order++- No precedence rule.++### Performance and resources++- No resource rule.++## Accessibility contract++- **AR1 — Named group.** The group is named by `heading` (FR1), unless the+ caller supplies its own `aria-label` (FR4).+- **AR2 — One reading.** The visual heading is hidden from assistive+ technology, so the name is not repeated (FR2).++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ---------------- | -------------------------------------- | ------------------------ | -------------- | ------------------ |+| Group | Gathers related results in one column. | Current source | Supporting | FR1, FR3 |+| Group heading | Labels the group with supporting text. | Current source | Supporting | FR2, FR3 |++The aggregate CommandPalette anatomy map, owned by `component:CommandPalette`,+maps the Group and Group heading parts to these targets.++## Family and system relationships++- `component:CommandPalette` owns the aggregate anatomy and the composite+ keyboard model; `component:CommandPaletteItem` owns the options inside.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| -------- | ----------------------------------------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------- |+| FR1, AR1 | `CommandPaletteGroup.test.tsx` "has group role with aria-label" | grouped results | A missing role or name fails. | `audit:CommandPaletteGroup/accessibility` |+| FR2, AR2 | `CommandPaletteGroup.test.tsx` heading, `aria-hidden`, and decorative-heading tests | grouped results | A heading exposed to assistive technology fails. | `audit:CommandPaletteGroup/accessibility` |+| FR3 | `CommandPaletteGroup.test.tsx` heading-target tests; `themingTargets.test.ts` | grouped results | A missing or merged target fails. | `audit:CommandPaletteGroup/theming` |+| FR4 | Source review | Caller inputs | Gap: no test covers `ref`, DOM props, `className`, `style`, `xstyle`, or a caller `role` or `aria-label`. | `audit:CommandPaletteGroup/api` |++Read from source, with no focused test yet:++- FR1: the one-column layout.+- FR4: `ref`, DOM props, `className`, `style`, and `xstyle` on the root.++## Decision log++No component-local decision is recorded.++## Open questions++None.++## Content boundary++This file does not duplicate consumer prop tables or examples, or+CommandPalette's search and keyboard behavior. It links to their owners.diff --git a/docs/specs/components/CommandPalette/CommandPaletteItem.spec.md b/docs/specs/components/CommandPalette/CommandPaletteItem.spec.mdindex 45e435538b..d90a5a937f 100644--- a/docs/specs/components/CommandPalette/CommandPaletteItem.spec.md+++ b/docs/specs/components/CommandPalette/CommandPaletteItem.spec.md@@ -3,11 +3,11 @@ schema_version: 3template_version: 7kind: componentid: component:CommandPaletteItem-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: [behavior, accessibility, public-api, compatibility, theming]verified_by:@@ -42,8 +42,8 @@ system_specs: [spec:AST-017, spec:AST-020]| Public contract | One result option with context-backed identity, highlight, selection, and close behavior; explicit standalone visual state and pointer activation remain available. || Behavior | Consumer click runs first; cancellation stops selection; successful activation reports locally, updates context, and closes; disabled items run no click callbacks. || End-user impact | Disabled commands cannot activate, and keyboard focus, selected value, and option identity remain distinct and consistently exposed. |-| Builder impact | Values stay unique; children stay non-interactive; CommandPalette owns composite keyboard navigation and reports keyboard selection through root `onValueChange`. |-| Compatibility/readiness | Victim-free `[fix]` restores promised disabled and native-passthrough behavior; the standalone keyboard contract remains unsettled. |+| Builder impact | None. |+| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps, listed under Current-state impact; two owner questions stay open. || Review checks | Reject disabled activation, dropped standalone DOM identity, highlight-as-selection ARIA, nested interactive children, or a second context scroll owner. || Governing rules | `architecture:public-component-api/INV5,INV7`; `architecture:interaction-modality`; `spec:AST-017/FR1,FR3,FR5`; `spec:AST-020/FR1,FR2`; WAI-ARIA 1.2 `option`. |@@ -59,21 +59,25 @@ standalone scroll behavior.## Compatibility and migration- Released default preserved: `yes`-- Compatibility class: victim-free contract restoration under- `spec:AST-017/FR1,FR3,FR5`; `isDisabled` already promises a non-interactive- item and the native `BaseProps` seam already promises standalone DOM props+- Compatibility class: records shipped behavior; no public change- Controlled/uncontrolled behavior: explicit item state still precedes contextstate, then the existing false default-- Migration decision: none for these corrections; OQ1 holds any change to the- standalone keyboard contract-- Documentation compatibility: item `onSelect` reports pointer activation only.- No public runtime path delivers Enter to it — CommandPalette mints rows without- item callbacks and standalone items have no keyboard owner — so describing- keyboard selection through root `onValueChange` leaves no released consumer- behind (`spec:AST-017/FR1,FR5`). OQ1 owns any standalone keyboard path.+- Migration decision: none; OQ1 holds any change to the standalone keyboard+ contract. Item `onSelect` reports pointer activation only; keyboard selection+ is reported through the root's `onValueChange`.Consumer migration instructions belong in consumer docs and release notes.+## Current-state impact++- **A standalone option has no keyboard model.** Outside CommandPalette the+ item exposes `role=option` and pointer activation but no owning listbox+ keyboard model, so a keyboard user cannot reach or activate it; WAI-ARIA 1.2+ options belong to a composite that owns their keyboard interaction (AR5, OQ1).+- **Selected paint hides keyboard highlight.** When an item is both highlighted+ and selected, the selected background masks the highlighted one, so the+ keyboard position is not visible on that item (AV2, OQ2).+## Ownership boundary**Owns**@@ -106,13 +110,13 @@ Consumer migration instructions belong in consumer docs and release notes.## Behavioral and layout contract-| ID | Candidate invariant | Basis | Draft review state |-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------------------- |-| FR1 | Native props and `ref` reach the option root. CommandPalette context owns registered-item id, role, selected state, disabled state, and value marker; standalone caller id persists. | Released source and `architecture:public-component-api/INV5` | Verified by focused DOM tests |-| FR2 | Pointer activation runs consumer `onClick`, then stops when prevented; otherwise it calls item `onSelect`, then context selection and close. Disabled items run none of those paths. | Released callbacks and disabled promise | Verified; mutation-resistant |-| FR3 | Explicit `isHighlighted` and `isSelected` precede context-derived values, then false. Highlight paints active state only; selection alone drives `aria-selected`. | Released source, docs, and listbox semantics | State semantics tested; precedence tested; combined paint gap remains OQ2 |-| FR4 | Context owns highlighted-item scrolling. Outside context, a highlighted item scrolls nearest, except an initially highlighted item inside an inline Dialog does not scroll. | Released source and regression history | Verified by focused Effect tests |-| FR5 | Children provide the option's label and supporting presentation, without nested interactive descendants. | Option semantics and `spec:AST-020/FR1,FR2` | Documented; exact-head a11y remains a gate |+| ID | Invariant | Basis |+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |+| FR1 | Native props and `ref` reach the option root. The `option` role, selected state, and disabled state replace a caller's: inside CommandPalette because composite semantics are component-owned and replace passthrough, as `component:CommandPaletteInput` AR3 records, and standalone by this record's own rule. CommandPalette context owns the registered-item id and value marker; a standalone caller id persists. | Current source and tests; `architecture:public-component-api` |+| FR2 | Pointer activation runs consumer `onClick`, then stops when prevented; otherwise it calls item `onSelect`, then context selection and close. Disabled items run none of those paths. | Current source and tests |+| FR3 | Explicit `isHighlighted` and `isSelected` precede context-derived values, then false. Highlight paints active state only; selection alone drives `aria-selected`. | Current source, tests, and docs |+| FR4 | Context owns highlighted-item scrolling. Outside context, a highlighted item scrolls nearest, except an initially highlighted item inside an inline Dialog does not scroll. | Current source and tests |+| FR5 | Children provide the option's label and supporting presentation, without nested interactive descendants. | Option semantics and `spec:AST-020/FR1,FR2` |### Allowed variation@@ -151,29 +155,28 @@ Consumer migration instructions belong in consumer docs and release notes.## Accessibility contract-- **AR1 — Option semantics.** The root exposes `role=option`; its content or+- **AR1 — Option semantics.** The root exposes `role=option` (FR1); its content orcaller label provides the accessible name, and `aria-selected` reports chosenvalue rather than visual highlight.- **AR2 — Composite ownership.** Inside CommandPalette, the query field retainsfocus and points to the context-generated item id; CommandPalette owns arrownavigation and Enter selection under its adopted listbox/combobox model.- **AR3 — Disabled state.** Disabled items expose `aria-disabled=true` and- suppress every pointer activation callback. Source inspection confirms the- interaction overlay is omitted; exact-head browser evidence remains the paint- gate.+ suppress every pointer activation callback, and the interaction overlay is+ omitted.- **AR4 — Content.** Item children contain no nested button, link, or otherinteractive descendant whose semantics would be lost when the `option`role makes its descendants presentational, following WAI-ARIA 1.2 and`spec:AST-020/FR1,FR2`.- **AR5 — Standalone gap.** A standalone option has no owning composite keyboard- model. OQ1 must settle that public contract before runtime semantics change.+ model (Current-state impact; OQ1).## Design relationships-| Anatomy | Design requirement | Representation authority | Hierarchy role | Component contract |-| ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |-| Item | Paints enabled, highlighted, selected, disabled, and press states on one root. Selected currently masks highlight when both apply (OQ2). | Current source and public docs | Prominent | FR1–FR4, AR1–AR3 |-| Content | Supplies the option name and non-interactive supporting presentation. | Product callsite | Supporting | FR5, AR1, AR4 |+| Anatomy | Design requirement | Representation authority | Hierarchy role | Component contract |+| ------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | -------------- | ------------------ |+| Item | Paints enabled, highlighted, selected, disabled, and press states on one root. Selected masks highlight when both apply (OQ2). | Current source and public docs | Prominent | FR1–FR4, AR1–AR3 |+| Content | Supplies the option name and non-interactive supporting presentation. | Product callsite | Supporting | FR5, AR1, AR4 |## Family and system relationships@@ -184,26 +187,31 @@ Consumer migration instructions belong in consumer docs and release notes.compatibility.- `architecture:component-theming-surface` owns the aggregate Item anatomy mapand stable `command-palette-item` target.-- `spec:AST-017` classifies the victim-free corrections and holds OQ1 against- silent released-contract changes.+- `spec:AST-017` holds OQ1 against silent released-contract changes.- `spec:AST-020` supplies accessibility evidence and adopted-pattern boundaries.- WAI-ARIA 1.2 option semantics make descendants presentational, so interactivecontrols do not belong inside this option root.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ----------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------- |-| FR1, FR3, AR1–AR2 | `CommandPaletteItem.test.tsx`, `CommandPalette.test.tsx` | standalone; context highlighted/selected | Dropped id/ref/native prop, clobberable role/state, or highlight-as-selection fails focused DOM assertions. | `audit:CommandPaletteItem/a11y` |-| FR2, AR3 | `CommandPaletteItem.test.tsx` | enabled; disabled; consumer-cancelled; contextual | Disabled consumer activation, ignored cancellation, missing local report, selection, or close fails tests. | `audit:CommandPaletteItem/behavior` |-| FR4 | `CommandPaletteItem.test.tsx`, `CommandPalette.test.tsx` | standalone; inline initial; changed highlight | Lost nearest scrolling, duplicate contextual scrolling, or initial inline scroll fails Effect assertions. | `audit:CommandPaletteItem/behavior` |-| FR5, AR4 | public docs, dedicated Storybook states, exact-head a11y/browser evidence | label; shortcut; disabled | Interactive descendant guidance regresses or supported composition fails exact-head accessibility evidence. | `audit:CommandPaletteItem/a11y` |-| Theme/RTL | focused class assertion, `themingTargets.test.ts`, Storybook fixture, RTL verified N/A | all visual states | Target loss fails inventory/DOM tests; any new directional behavior requires a non-empty RTL dimension. | `audit:CommandPaletteItem/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ----------------- | ------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------- |+| FR1, FR3, AR1–AR2 | `CommandPaletteItem.test.tsx`, `CommandPalette.test.tsx` | standalone; context highlighted/selected | Dropped id/ref/native prop, clobberable role/state, or highlight-as-selection fails focused DOM assertions. | `audit:CommandPaletteItem/a11y` |+| FR2, AR3 | `CommandPaletteItem.test.tsx` | enabled; disabled; consumer-cancelled; contextual | Disabled consumer activation, ignored cancellation, missing local report, selection, or close fails tests. | `audit:CommandPaletteItem/behavior` |+| FR4, PR2 | `CommandPaletteItem.test.tsx`, `CommandPalette.test.tsx` | standalone; inline initial; changed highlight | Lost nearest scrolling, duplicate contextual scrolling, or initial inline scroll fails Effect assertions. | `audit:CommandPaletteItem/behavior` |+| Theme/RTL | focused class assertion, `themingTargets.test.ts`, RTL verified N/A | all visual states | Target loss fails inventory/DOM tests; any new directional behavior requires a non-empty RTL dimension. | `audit:CommandPaletteItem/theming` |+| FR5, AR4 | Source review | Item children | Gap: no check fails if item children contain a nested interactive descendant. | `audit:CommandPaletteItem/accessibility` |+| AR5 | Source review | Standalone item | Gap: no standalone keyboard model exists to test (OQ1). | `audit:CommandPaletteItem/accessibility` |+| PR1 | Source review | Inside CommandPalette | Gap: no automated check fails if context matching adds a listener, an observer, or per-item registry work. | `audit:CommandPaletteItem/behavior` |++Read from source, with no focused test yet:++- FR5, AR4: children carrying no interactive descendant.+- AR3: the omitted interaction overlay on a disabled item.## Decision log-No component-local API, keyboard, or visual decision is settled in this draft.-Objective corrections preserve the current public shape.+No component-local decision is recorded.## Open questions@@ -214,10 +222,9 @@ Objective corrections preserve the current public shape.interaction contract, or standalone activation should enter a migration path.- **OQ2 — How should keyboard highlight remain visible when the item is alsoselected?** (`human-design`) Current selected background paint follows and- masks the highlighted background. Real-browser pixels must confirm the gap;- any appearance remedy requires owner direction and a separate visual change.+ masks the highlighted background; any appearance remedy needs owner+ direction.## Content boundary-This file does not duplicate consumer examples, audit scores, implementation-steps, aggregate CommandPalette search/list behavior, or shared system rules.+This file does not duplicate consumer examples, implementation steps, aggregate CommandPalette search/list behavior, or shared system rules.diff --git a/docs/specs/components/CommandPalette/CommandPaletteList.spec.md b/docs/specs/components/CommandPalette/CommandPaletteList.spec.mdindex 1e6920770a..c082624349 100644--- a/docs/specs/components/CommandPalette/CommandPaletteList.spec.md+++ b/docs/specs/components/CommandPalette/CommandPaletteList.spec.md@@ -3,11 +3,11 @@ schema_version: 3template_version: 7kind: componentid: component:CommandPaletteList-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: [behavior, accessibility, public-api, theming]verified_by:@@ -36,15 +36,15 @@ system_specs: []## Contract at a glance-| Area | Contract |-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| Public contract | None changes. One named listbox container for result options, rendered by CommandPalette or directly for a standalone results list. |-| Behavior | The root is a `listbox` named by `label` or the translated default; inside CommandPalette it is one only while selectable results exist, and carries the context list id the query field controls. |-| End-user impact | Screen-reader users reach a named results list from the query field; overflowing results scroll inside the list instead of growing the palette. |-| Builder impact | None. CommandPalette renders its own list; standalone compositions render items and groups directly inside this one. |-| Compatibility/readiness | Draft. Inside CommandPalette an empty or pending result surface drops the listbox role and name (AR4, an accessibility fix); a standalone caller `id` is kept (FR1); the standalone keyboard model remains OQ1. |-| Review checks | Reject a second list-id owner, a role or name that consumer props can replace, dropped native or styling inputs, or a list target moved off the scrolling root. |-| Governing rules | `architecture:public-component-api/INV5,INV6,INV8`; `architecture:component-theming-surface`; WAI-ARIA 1.2 `listbox`. |+| Area | Contract |+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | `CommandPaletteList` with `label`, `children`, `ref`, `xstyle`, `className`, `style`, and root DOM props: the named listbox of results that CommandPalette renders, or a standalone results list. |+| Behavior | The root is a `listbox` named by a caller's `aria-label`, else `label`, else the translated default (the caller's `aria-label` is an FR2 gap today); inside CommandPalette it is one only while selectable results exist, and carries the context list id the query field controls. |+| End-user impact | Screen-reader users reach a named results list from the query field; overflowing results scroll inside the list instead of growing the palette. |+| Builder impact | A builder's explicit `aria-label` is meant to name the list; today the component's name replaces it (FR2 gap). |+| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps, listed under Current-state impact; one owner question stays open. |+| Review checks | Reject a second list-id owner, a `listbox` role a caller can replace, a caller `aria-label` that does not reach the root, dropped native or styling inputs, or a list target moved off the scrolling root. |+| Governing rules | `architecture:public-component-api/INV5,INV6,INV8`; `architecture:component-theming-surface`; WAI-ARIA 1.2 `listbox`. |This table is a review projection; the body below is authoritative.@@ -56,22 +56,30 @@ presents a named results listbox around caller-provided option content.## Compatibility and migration-- Released default preserved: `yes`, except inside CommandPalette while no- selectable result exists, where the root no longer exposes an empty listbox-- Compatibility class: accessibility behavior fix (`spec:AST-017/FR53`); styling,- target, and public API are unchanged+- Released default preserved: `yes`+- Compatibility class: records shipped behavior; no public change- Controlled/uncontrolled behavior: not applicable; the list holds no state- Migration decision: noneConsumer migration instructions belong in consumer docs and release notes.+## Current-state impact++- **A standalone list has no keyboard model.** A standalone list exposes a+ listbox of options with no owning keyboard model, so a keyboard user cannot+ move through its options; WAI-ARIA 1.2 gives a listbox's keyboard interaction+ to its owner (AR3, OQ1).+- **The list replaces a caller's name (FR2).** Consumer props spread before+ the component's accessible name, so a builder's explicit `aria-label` never+ names the list, where `architecture:public-component-api` INV5 lets it.+## Ownership boundary**Owns**-- The listbox root and its accessible name from `label`, falling back to the- translated default, and dropping both inside CommandPalette while no selectable- result exists.+- The listbox root and its accessible name from a caller's `aria-label`, else+ `label`, else the translated default (FR2), and dropping both inside+ CommandPalette while no selectable result exists.- Applying the CommandPalette context list id to the root.- Native passthrough, `ref`, and styling-input composition on the root.- Block-axis scrolling of overflowing children, with spacing-scale padding and@@ -90,40 +98,41 @@ Consumer migration instructions belong in consumer docs and release notes.## Public concepts-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |-| --------------- | ---------------------------------- | ------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------- | ------------------------------ | --------- | ------------------------------------------------------------------------ |-| Accessible name | caller `label`; translated default | Name announced for the results listbox. | All uses | `@astryx.commandPalette.list.label` ("Commands" in English) | `component:CommandPaletteList` | Stable | An empty `label` leaves the listbox unnamed; callers supply a real name. |-| List identity | context list id; caller `id` | DOM id the CommandPalette query field references. | Inside CommandPalette; standalone | Context id inside CommandPalette; caller `id` standalone | `component:CommandPalette` | Stable | Inside CommandPalette a caller `id` is replaced by the context id. |+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |+| --------------- | ------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------- | ------------------------------ | --------- | ------------------------------------------------------------------------ |+| Accessible name | caller `aria-label`; caller `label`; translated default | Name announced for the results listbox. | All uses | `@astryx.commandPalette.list.label` ("Commands" in English) | `component:CommandPaletteList` | Stable | An empty `label` leaves the listbox unnamed; callers supply a real name. |+| List identity | context list id; caller `id` | DOM id the CommandPalette query field references. | Inside CommandPalette; standalone | Context id inside CommandPalette; caller `id` standalone | `component:CommandPalette` | Stable | Inside CommandPalette a caller `id` is replaced by the context id. |## Behavioral and layout contract-| ID | Candidate invariant | Basis | Draft review state |-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |-| FR1 | Native props and `ref` reach the listbox root, and consumer `className` and `style` combine with the list target and base styles. Inside CommandPalette the root id is the context list id; standalone, a caller `id` is kept. | Released source; `architecture:public-component-api/INV5,INV6,INV8` | Ref, styling, and the standalone `id` verified by focused tests |-| FR2 | Standalone, and inside CommandPalette while at least one selectable result exists, the root exposes `role=listbox` with an accessible name from `label`, falling back to the translated default; consumer `role` and `aria-label` props do not replace them. Otherwise AR4 applies. | Released source and docs; WAI-ARIA 1.2 `listbox` | Role and name verified by focused tests, with and without palette results; consumer-prop precedence is source-verified |-| FR3 | Inside CommandPalette, the query field's `aria-controls` names the listbox id. | Released source and component docs | Verified by a focused composition test |-| FR4 | The root lays out children in one column with spacing-scale padding and gaps, grows within a flex parent, caps its height at the parent's height, and scrolls overflowing children inside itself. | Released source and component docs | Source-verified; the scrolling fixture renders it in a browser, but scroll geometry is not yet measured |+| ID | Invariant | Basis |+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |+| FR1 | Native props and `ref` reach the listbox root, and consumer `className` and `style` combine with the list target and base styles. Inside CommandPalette the root id is the context list id; standalone, a caller `id` is kept. | Current source and tests |+| FR2 | Standalone, and inside CommandPalette while at least one selectable result exists, the root exposes `role=listbox`, which a caller's `role` does not replace: inside CommandPalette because composite semantics are component-owned and replace passthrough, as `component:CommandPaletteInput` AR3 records, and standalone by this record's own rule, named by a caller's explicit `aria-label`, else `label`, else the translated default (`architecture:public-component-api` INV5). Implementation gap: the component's name replaces a caller's `aria-label` (Current-state impact). Otherwise AR4 applies. | Current source and tests |+| FR3 | Inside CommandPalette, the query field's `aria-controls` names the listbox id. | Current source and tests |+| FR4 | The root lays out children in one column with spacing-scale padding and gaps, grows within a flex parent, caps its height at the parent's height, and scrolls overflowing children inside itself. | Current source |### Allowed variation- **AV1 — Children.** Items, groups, and empty states may vary in count, order,and content without changing the root, except as AR4 states.- **AV2 — Layout.** Consumer `xstyle`, class, and style may adjust the root- without replacing its role, name, id, or target.+ without replacing its role, id, or target.### Representative states-| State | Required invariant | Allowed variation |-| --------------------- | ------------------------------------------------------------------------------ | -------------------------- |-| Standalone results | The listbox is named by `label` or the translated default. | Item count and grouping. |-| Inside CommandPalette | The root id equals the query field's `aria-controls` value. | Results count and groups. |-| Overflowing results | Results scroll inside the list instead of growing past the container. | Container and item height. |-| Empty palette results | Inside CommandPalette with no selectable result, the root has no role or name. | Empty or pending message. |+| State | Required invariant | Allowed variation |+| --------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------- |+| Standalone results | The listbox is named by a caller's `aria-label`, else `label`, else the translated default (FR2 gap for `aria-label`). | Item count and grouping. |+| Inside CommandPalette | The root id equals the query field's `aria-controls` value. | Results count and groups. |+| Overflowing results | Results scroll inside the list instead of growing past the container. | Container and item height. |+| Empty palette results | Inside CommandPalette with no selectable result, the root has no role or name. | Empty or pending message. |### Transformation and precedence order- **ORD1 — Root attributes.** Consumer native props, then the component-owned- id, `listbox` role, and accessible name.+ id and `listbox` role; the accessible name applies unless the caller supplies+ its own `aria-label` (FR2; today it replaces the caller's).- **ORD2 — Styling.** List target, then base styles with `xstyle`, thenconsumer class, then consumer style.@@ -134,14 +143,13 @@ Consumer migration instructions belong in consumer docs and release notes.## Accessibility contract-- **AR1 — Name.** The listbox takes `label` as its accessible name and falls back- to the translated default when `label` is omitted.+- **AR1 — Name.** The listbox takes a caller's explicit `aria-label`, else+ `label`, else the translated default, as its accessible name (FR2 gap).- **AR2 — Relationship.** Inside CommandPalette, the query field controls thelistbox through its id; CommandPalette owns focus and keyboard navigation underits combobox model.- **AR3 — Standalone gap.** A standalone list exposes a listbox of options with- no owning keyboard model. OQ1 must settle that contract before runtime- semantics change.+ no owning keyboard model (Current-state impact; OQ1).- **AR4 — Empty content.** Inside CommandPalette, while no selectable resultexists, the root has no role and no accessible name, so screen readers meet theempty or pending message as plain content and no empty popup; WAI-ARIA 1.2@@ -168,17 +176,23 @@ Consumer migration instructions belong in consumer docs and release notes.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------- |-| FR1 | `CommandPaletteList.test.tsx` | standalone root with ref, class, and style | Disconnecting `ref`, or dropping the consumer class or the list target, fails focused DOM assertions. | `audit:CommandPaletteList/api` |-| FR2, AR1, AR4 | `CommandPaletteList.test.tsx` | default and caller label; palette with and without results | Removing the role or name, or keeping them on an empty palette surface, fails the role and name assertions. | `audit:CommandPaletteList/a11y` |-| FR3, AR2 | `CommandPaletteList.test.tsx`, `CommandPalette.test.tsx` | inline CommandPalette | Dropping the context id breaks the query-field relationship assertion. | `audit:CommandPaletteList/a11y` |-| FR4 | Storybook fixtures, `themingTargets.test.ts`, exact-head accessibility and RTL evidence | standalone list; scrolling palette | Losing the target fails the target inventory; any new directional behavior requires a non-empty RTL dimension. | `audit:CommandPaletteList/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------- | -------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |+| FR1 | `CommandPaletteList.test.tsx` | standalone root with ref, class, and style | Disconnecting `ref`, or dropping the consumer class or the list target, fails focused DOM assertions. | `audit:CommandPaletteList/api` |+| FR2, AR1, AR4 | `CommandPaletteList.test.tsx` | default and caller label; palette with and without results | Removing the role or name, or keeping them on an empty palette surface, fails the role and name assertions. Gap: no test covers a caller `role` or `aria-label`. | `audit:CommandPaletteList/a11y` |+| FR3, AR2 | `CommandPaletteList.test.tsx`, `CommandPalette.test.tsx` | inline CommandPalette | Dropping the context id breaks the query-field relationship assertion. | `audit:CommandPaletteList/a11y` |+| FR4 | `themingTargets.test.ts`; RTL verified not applicable | standalone list | Losing the target fails the target inventory. | `audit:CommandPaletteList/theming` |+| AR3 | Source review | Standalone list | Gap: no standalone keyboard model exists to test (OQ1). | `audit:CommandPaletteList/accessibility` |+| PR1 | Source review | Every state | Gap: no automated check fails if the list adds state, an effect, a listener, or an observer. | `audit:CommandPaletteList/behavior` |++Read from source, with no focused test yet:++- FR4: the one-column layout, spacing, height cap, and inner scrolling.+- PR1: no state, Effect, listener, or observer.## Decision log-None. This draft records current facts and settles no component-local API,-keyboard, or visual decision; AR4 applies the WAI-ARIA 1.2 listbox rule.+No component-local decision is recorded.## Open questions@@ -190,5 +204,5 @@ keyboard, or visual decision; AR4 applies the WAI-ARIA 1.2 listbox rule.## Content boundary-This file does not duplicate consumer prop tables/examples, current audit-results, implementation steps, or family/system rules. It links to their owners.+This file does not duplicate consumer prop tables/examples, implementation+steps, or family/system rules. It links to their owners.