@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/CommandPalette/CommandPaletteInput.spec.md

@@ -1,215 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:CommandPaletteInput
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-14
-owners: [cixzhang]
-review_triggers: [public-api, behavior, layout, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/CommandPalette/CommandPaletteInput.test.tsx,
-    apps/storybook/stories/CommandPaletteInput.stories.tsx,
-    apps/storybook/rtl-audit/targets.json,
-    packages/core/src/theme/themingTargets.test.ts,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [
-    architecture:component-test-sufficiency,
-    architecture:component-theming-surface,
-    architecture:interaction-modality,
-    architecture:public-component-api,
-  ]
-contributing: []
-system_specs: [spec:AST-017, spec:AST-020, spec:AST-056]
----
-
-# CommandPaletteInput component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                           |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract         | A query field with context-backed search state, optional trailing content, and a split wrapper/field attribute boundary.                                                                                           |
-| Behavior                | Standalone use without popup attributes is a searchbox; caller popup attributes or CommandPalette context supply combobox state and relationships.                                                                 |
-| End-user impact         | Screen-reader users receive role and popup state that match whether a controlled result popup exists.                                                                                                              |
-| Builder impact          | Context-owned popup semantics cannot be replaced through native passthrough props; standalone caller-owned popup semantics remain supported.                                                                       |
-| Compatibility/readiness | A `[fix]` restores no-popup semantics while preserving released caller-owned popup associations, and names the field "Search commands" by default instead of its placeholder; primary callback naming remains OQ1. |
-| Review checks           | Reject unassociated standalone combobox state, clobberable owned popup semantics, empty trailing chrome, or changed input ref routing.                                                                             |
-| Governing rules         | `architecture:public-component-api/INV2,INV5`; `spec:AST-017/FR1,FR3,FR5,FR53`; `spec:AST-020/FR1,FR2`; `spec:AST-056/AR2`; WCAG 2.2 4.1.2.                                                                        |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-CommandPaletteInput presents the text query for a command palette. It can bind
-to CommandPalette search and navigation context or act as an independent search
-field when no result-popup context is present.
-
-## Compatibility and migration
-
-- Released default preserved: `no` for no-popup standalone semantic output and
-  for the default accessible name; caller-owned popup associations and all other
-  CommandPalette output remain equivalent
-- Compatibility class: contract restoration under `spec:AST-017/FR1,FR3,FR5` for
-  standalone semantics, since no-popup standalone use has no released popup
-  association to preserve; accessibility behavior fix under `spec:AST-017/FR53`
-  for the default name
-- Controlled/uncontrolled behavior: unchanged
-- Migration decision: `role="combobox"` keeps the earlier standalone semantics,
-  and `label` or `aria-label` keeps a specific name; the primary callback naming
-  question remains OQ1
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- The arrangement inside Input: Search glyph, native Query field, Loading spinner
-  placement, and Trailing content.
-- The query field's role and popup state when CommandPalette context is present.
-- Context fallback for the search value, value updates, and keyboard navigation.
-
-**Does not own / non-goals**
-
-- The result popup, option collection, selection, or search orchestration — owned
-  by `component:CommandPalette` and its list/item parts.
-- Spinner and search-glyph rendering — delegated to Spinner and Icon.
-- Caller-provided trailing content behavior — owned by the product callsite.
-
-## Public concepts
-
-| Concept          | Closed values or states                                                              | Meaning                                          | Availability by variant/orientation/state | Default              | Owner                           | Stability | Invalid-value behavior                                       |
-| ---------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------ | ----------------------------------------- | -------------------- | ------------------------------- | --------- | ------------------------------------------------------------ |
-| Query binding    | explicit; CommandPalette context; native                                             | Source and destination of query text changes.    | All uses                                  | context, then native | `component:CommandPaletteInput` | Released  | Missing handlers leave native state                          |
-| Popup semantics  | standalone searchbox; standalone caller-owned popup; contextual CommandPalette popup | Whether the query field controls a result popup. | Context-dependent                         | standalone searchbox | `component:CommandPaletteInput` | Stable    | Standalone overrides persist; CommandPalette context wins    |
-| Trailing content | busy indicator; `endContent`; both; absent                                           | Supporting status or caller content after query. | All uses                                  | absent               | `component:CommandPaletteInput` | Released  | Boolean, empty-string, null, and undefined values are absent |
-
-## Behavioral and layout contract
-
-| ID  | Candidate invariant                                                                                                                                                                                                                                            | Basis                                                              | Draft review state                                         |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------- |
-| FR1 | Explicit `value` and `onValueChange` take precedence; otherwise CommandPalette context supplies search state; native uncontrolled state remains when neither exists.                                                                                           | Released source, docs, and tests                                   | Verified current behavior                                  |
-| FR2 | Consumer `onKeyDown` runs before contextual navigation; preventing the event, or an active IME composition, prevents contextual delegation.                                                                                                                    | Released source and tests                                          | Verified current behavior                                  |
-| FR3 | `ref` and native passthrough attributes reach the native query field; standalone caller-owned popup semantics persist, while CommandPalette context owns its popup role and relationships; `xstyle`, `className`, and `style` customize the surrounding Input. | Released source and docs; `architecture:public-component-api/INV5` | Verified current routing                                   |
-| FR4 | Pending state and renderable `endContent` share one trailing-content group; booleans, empty strings, null, and undefined do not create empty trailing chrome.                                                                                                  | React rendering semantics and current utility contract             | Verified current behavior                                  |
-| FR5 | Auto-focus is enabled by default and suppressed inside an inline Dialog; `hasAutoFocus={false}` suppresses both focus work and the autofocus marker.                                                                                                           | Released source, docs, and tests                                   | Verified current behavior; browser timing evidence remains |
-
-### Allowed variation
-
-- **AV1 — Query content.** Value, placeholder, label, and caller-provided trailing
-  content may vary without changing semantic ownership.
-- **AV2 — Delegated visuals.** Icon and Spinner may change internal markup while
-  preserving their public contracts.
-
-### Representative states
-
-| State                    | Required invariant                                                | Allowed variation                    |
-| ------------------------ | ----------------------------------------------------------------- | ------------------------------------ |
-| Standalone, no popup     | Named searchbox with no popup-only ARIA state.                    | Explicit value and change handler.   |
-| Standalone, caller popup | Caller role, state, relationships, and active descendant persist. | Caller-owned popup model.            |
-| Contextual, closed       | Named combobox references the list and reports collapsed state.   | Query value and trailing content.    |
-| Contextual, no results   | Named combobox reports collapsed state and references no list.    | Empty or pending message.            |
-| Contextual, open         | Named combobox references the list and reports expanded state.    | Highlighted option and result count. |
-| Contextual, highlighted  | Active descendant names the context-owned highlighted option.     | Highlighted index.                   |
-| Pending or trailing      | Supporting content remains at the logical trailing edge.          | Spinner, caller content, or both.    |
-| Inline Dialog            | Mount does not steal focus from the surrounding page.             | Query and result content.            |
-
-### Transformation and precedence order
-
-- **ORD1 — Search state.** Explicit props → CommandPalette context → native
-  uncontrolled state.
-- **ORD2 — Keyboard handling.** Consumer handler → default-prevented or
-  IME-composition check → CommandPalette context handler.
-- **ORD3 — Accessible name.** Native `aria-label` → `label` → the translated
-  default "Search commands" (DEC-1). Placeholder text is never the name.
-
-### Performance and resources
-
-- **PR1 — Focus scheduling.** At most one animation-frame focus request is
-  scheduled by a mounted eligible field; no listener or observer is retained.
-
-## Accessibility contract
-
-- **AR1 — Name.** The native query field always has an explicit accessible name
-  from ORD3 and never takes its name from placeholder text, satisfying
-  `spec:AST-056/AR2` and WCAG 2.2 4.1.2.
-- **AR2 — Role and popup state.** Standalone use without popup attributes exposes
-  a `searchbox` without popup-only state. Standalone callers that provide their
-  own popup relationships retain those semantics. CommandPalette context exposes
-  a `combobox` with context-owned expanded state, list relationship, autocomplete
-  mode, and active descendant, following `spec:AST-020/FR1,FR2` and the WAI-ARIA
-  combobox pattern. While the palette holds no selectable result, the field
-  reports collapsed state and has no list relationship or active descendant, and
-  an active descendant always names an existing option.
-- **AR3 — Semantic ownership.** With CommandPalette context, the field owns
-  `role`, `aria-expanded`, `aria-autocomplete`, `aria-controls`, and
-  `aria-activedescendant`, and these replace the same native passthrough props;
-  other ARIA props, including `aria-haspopup` and `aria-owns`, pass through.
-  Standalone caller-owned roles and relationships remain intact.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                                                | Representation authority                  | Hierarchy role | Component contract |
-| ---------------- | --------------------------------------------------------------------------------- | ----------------------------------------- | -------------- | ------------------ |
-| Input            | Arranges Search glyph, Query field, Loading spinner, and Trailing content inline. | Current source and public docs            | Prominent      | FR3, FR4           |
-| Search glyph     | Identifies the query affordance without adding a name.                            | Icon component                            | Supporting     | AR1                |
-| Query field      | Receives text, focus, name, and popup semantics.                                  | Current source and accessibility standard | Prominent      | FR1–FR3, AR1–AR3   |
-| Loading spinner  | Indicates a pending contextual search before Trailing content.                    | Spinner component                         | Supporting     | FR4                |
-| Trailing content | Keeps caller content at logical inline-end.                                       | Current source and public docs            | Supporting     | FR4                |
-
-## Family and system relationships
-
-- `component:CommandPalette` owns the result-popup context, aggregate composition,
-  and the open theming-reachability question; this component owns the default
-  Input's query-field semantics and binds them to that context.
-- `spec:AST-017` owns compatibility classification for the released standalone
-  caller-popup and no-popup cases.
-- `spec:AST-020` supplies the WCAG 2.2 and adopted-pattern evidence boundaries.
-- `spec:AST-056/AR2` requires a query-field name distinct from placeholder text;
-  ORD3 and AR1 satisfy it.
-
-## Verification map
-
-| Contract    | Verification                                              | Representative states                                  | Mutation or failure expectation                                                                                                                                | Audit section                        |
-| ----------- | --------------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
-| FR1–FR3     | `CommandPaletteInput.test.tsx`                            | explicit, context, prevented key, native, caller popup | Reversing state precedence, rerouting the ref, dropping standalone popup relationships, or allowing context semantics to be clobbered fails focused DOM tests. | `audit:CommandPaletteInput/testing`  |
-| FR4         | `CommandPaletteInput.test.tsx`                            | numeric, empty, busy, caller content                   | Truthiness routing creates empty chrome or moves numeric content away from the trailing edge.                                                                  | `audit:CommandPaletteInput/behavior` |
-| FR5         | focused unit tests plus exact-head browser evidence       | enabled, disabled, inline                              | Eligible focus is lost, disabled focus is scheduled, or inline mode steals focus.                                                                              | `audit:CommandPaletteInput/behavior` |
-| AR1–AR3     | unit tests, exact-head axe/browser run, and source review | standalone, open, closed, highlighted                  | Wrong role/state, consumer clobbering of an owned attribute, or a placeholder-derived name fails semantics and name assertions.                                | `audit:CommandPaletteInput/a11y`     |
-| Theming/RTL | target inventory, Storybook fixture, and RTL D2 audit     | standalone trailing content, contextual                | Target loss or physical ordering fails the owned fixture.                                                                                                      | `audit:CommandPaletteInput/theming`  |
-
-## Decision log
-
-### DEC-1 — The query field's default name is "Search commands"
-
-**Reference:** `component:CommandPaletteInput/DEC-1`
-**Decider:** `cixzhang`, 2026-10-14
-
-A screen-reader user reaching the field hears what it does, whatever the
-placeholder says or whether one is set. The default is a fixed, localizable
-"Search commands"; `label` and `aria-label` replace it, and placeholder text is
-never the name.
-
-Rejected: falling back to the placeholder, which a caller writes as a visual
-hint and AST-056 AR2 does not accept as a name.
-
-## Open questions
-
-- **OQ1 — How should the released `onValueChange(value)` primary callback and
-  native-event `onChange(event)` exception migrate to the shared `onChange`
-  callback grammar without breaking existing consumers?** (`human-api`)
-
-## 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.

package/src/CommandPalette/CommandPaletteItem.spec.md

@@ -1,223 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:CommandPaletteItem
-authority: draft
-archive_reason: null
-superseded_by: null
-approved_by: null
-approved_at: null
-owners: [cixzhang]
-review_triggers: [behavior, accessibility, public-api, compatibility, theming]
-verified_by:
-  [
-    packages/core/src/CommandPalette/CommandPaletteItem.test.tsx,
-    packages/core/src/CommandPalette/CommandPalette.test.tsx,
-    packages/core/src/theme/themingTargets.test.ts,
-    apps/storybook/stories/CommandPaletteItem.stories.tsx,
-    apps/storybook/rtl-audit/targets.json,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [
-    architecture:component-test-sufficiency,
-    architecture:component-theming-surface,
-    architecture:interaction-modality,
-    architecture:public-component-api,
-  ]
-contributing: []
-system_specs: [spec:AST-017, spec:AST-020]
----
-
-# CommandPaletteItem component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                            |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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.                                 |
-| 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`.      |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-CommandPaletteItem presents one command result as an option. CommandPalette
-context supplies composite state and keyboard ownership; the item owns its option
-semantics, visual states, pointer activation, native passthrough boundary, and
-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
-- Controlled/uncontrolled behavior: explicit item state still precedes context
-  state, 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.
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- The option root, item value marker, selected and disabled ARIA state, and
-  `command-palette-item` theme target.
-- Explicit → CommandPalette context → false precedence for highlighted and
-  selected visual state.
-- Pointer activation order, disabled suppression, and context selection/close.
-- Standalone highlighted-item scroll behavior and the inline-preview initial
-  scroll suppression.
-
-**Does not own / non-goals**
-
-- CommandPalette's listbox, query-field active descendant, arrow-key navigation,
-  Enter handling, search results, or root `onValueChange` callback.
-- Grouping, list layout, or caller-provided non-interactive item content.
-- A standalone composite listbox keyboard model; its direction remains OQ1.
-- Interactive descendants. Buttons and links are sibling actions or separate
-  commands, not content inside an option.
-
-## Public concepts
-
-| Concept       | Closed values or states                             | Meaning                                           | Availability             | Default | Owner                          | Stability | Invalid-value behavior                                    |
-| ------------- | --------------------------------------------------- | ------------------------------------------------- | ------------------------ | ------- | ------------------------------ | --------- | --------------------------------------------------------- |
-| Highlight     | explicit; context index; false                      | Active keyboard result, painted but not selected. | All uses                 | false   | `component:CommandPaletteItem` | Stable    | Unknown context value leaves every item unhighlighted.    |
-| Selection     | explicit; context value; false                      | Chosen value exposed through `aria-selected`.     | All uses                 | false   | `component:CommandPaletteItem` | Stable    | Duplicate values resolve ambiguously; values stay unique. |
-| Availability  | enabled; disabled                                   | Whether pointer activation is available.          | All uses                 | enabled | `component:CommandPaletteItem` | Stable    | Disabled suppresses consumer and component callbacks.     |
-| Item identity | context-generated id; standalone caller-provided id | DOM identity used by active-descendant or caller. | Contextual or standalone | absent  | component or caller            | Stable    | Context identity wins only for a registered item.         |
-
-## 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                                |
-
-### Allowed variation
-
-- **AV1 — Content.** Labels, icons, descriptions, and shortcut hints may vary
-  while remaining non-interactive.
-- **AV2 — Visual state.** Highlight, selection, and disabled state may occur
-  independently or together. The current selected paint masks highlighted paint
-  when both are true; OQ2 holds the visible-state remedy.
-- **AV3 — Layout.** Consumer `xstyle`, class, and style may adjust the single
-  root without replacing its option semantics.
-
-### Representative states
-
-| State                | Required invariant                                                        | Allowed variation                 |
-| -------------------- | ------------------------------------------------------------------------- | --------------------------------- |
-| Enabled standalone   | Caller id and native props persist; pointer activation reports locally.   | Content and visual state.         |
-| Disabled standalone  | `aria-disabled` is true and no click callback fires.                      | Content.                          |
-| Context highlighted  | Context item id matches active descendant and highlight is not selection. | Item index and content.           |
-| Context selected     | Matching value exposes `aria-selected=true`.                              | Highlight may be same or another. |
-| Consumer-cancelled   | Consumer click runs; local and context selection/close do not.            | Consumer side effect.             |
-| Inline initial state | Initial standalone highlight does not scroll the surrounding preview.     | Selected value and content.       |
-
-### Transformation and precedence order
-
-- **ORD1 — Visual state.** Explicit item prop → CommandPalette context → false.
-- **ORD2 — Pointer activation.** Disabled guard → consumer click → prevented
-  check → item `onSelect` → context select → context close.
-- **ORD3 — Identity.** Registered context id → standalone caller id → absent.
-
-### Performance and resources
-
-- **PR1 — Lookup.** Context matching remains bounded by the current flat result
-  list and performs no listener, observer, or per-item registry work.
-- **PR2 — Scroll ownership.** One owner scrolls a highlighted contextual item;
-  standalone items schedule no work when not highlighted.
-
-## Accessibility contract
-
-- **AR1 — Option semantics.** The root exposes `role=option`; its content or
-  caller label provides the accessible name, and `aria-selected` reports chosen
-  value rather than visual highlight.
-- **AR2 — Composite ownership.** Inside CommandPalette, the query field retains
-  focus and points to the context-generated item id; CommandPalette owns arrow
-  navigation 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.
-- **AR4 — Content.** Item children contain no nested button, link, or other
-  interactive 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.
-
-## 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      |
-
-## Family and system relationships
-
-- `component:CommandPalette` owns composite search, listbox, active-descendant,
-  keyboard, and close orchestration; this component binds one option to it.
-- `architecture:interaction-modality` owns shared pointer and keyboard behavior.
-- `architecture:public-component-api` owns native passthrough and released API
-  compatibility.
-- `architecture:component-theming-surface` owns the aggregate Item anatomy map
-  and stable `command-palette-item` target.
-- `spec:AST-017` classifies the victim-free corrections and 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 interactive
-  controls 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`  |
-
-## Decision log
-
-No component-local API, keyboard, or visual decision is settled in this draft.
-Objective corrections preserve the current public shape.
-
-## Open questions
-
-- **OQ1 — What standalone keyboard contract should CommandPaletteItem expose?**
-  (`human-api`) Current standalone use exposes an option and pointer activation
-  but no owning listbox keyboard model. Decide whether a public composite owner
-  must supply that model, the item should gain a different standalone role and
-  interaction contract, or standalone activation should enter a migration path.
-- **OQ2 — How should keyboard highlight remain visible when the item is also
-  selected?** (`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.
-
-## Content boundary
-
-This file does not duplicate consumer examples, audit scores, implementation
-steps, aggregate CommandPalette search/list behavior, or shared system rules.

package/src/CommandPalette/CommandPaletteList.spec.md

@@ -1,194 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:CommandPaletteList
-authority: draft
-archive_reason: null
-superseded_by: null
-approved_by: null
-approved_at: null
-owners: [cixzhang]
-review_triggers: [behavior, accessibility, public-api, theming]
-verified_by:
-  [
-    packages/core/src/CommandPalette/CommandPaletteList.test.tsx,
-    packages/core/src/CommandPalette/CommandPalette.test.tsx,
-    packages/core/src/theme/themingTargets.test.ts,
-    apps/storybook/stories/CommandPaletteList.stories.tsx,
-    apps/storybook/rtl-audit/verified-not-applicable.json,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [
-    architecture:component-test-sufficiency,
-    architecture:component-theming-surface,
-    architecture:public-component-api,
-  ]
-contributing: []
-system_specs: []
----
-
-# CommandPaletteList component contract
-
-## 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`.                                                                                           |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-CommandPaletteList is the scrolling results container of the command palette.
-Inside CommandPalette it is the listbox the query field controls. Standalone, it
-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
-- Controlled/uncontrolled behavior: not applicable; the list holds no state
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## 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.
-- 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
-  gaps.
-
-**Does not own / non-goals**
-
-- List-id generation, query-field focus, active descendant, arrow-key
-  navigation, hover highlight, Enter selection, search, and the choice between
-  results and the empty state — owned by `component:CommandPalette`.
-- The aggregate List anatomy entry and its `command-palette-list` target mapping
-  — owned by `component:CommandPalette`.
-- Option semantics, state, and activation; group semantics and headings — owned
-  by CommandPaletteItem and CommandPaletteGroup.
-- A standalone composite keyboard model; its direction remains OQ1.
-
-## 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.       |
-
-## 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                |
-
-### 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.
-
-### 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.  |
-
-### Transformation and precedence order
-
-- **ORD1 — Root attributes.** Consumer native props, then the component-owned
-  id, `listbox` role, and accessible name.
-- **ORD2 — Styling.** List target, then base styles with `xstyle`, then
-  consumer class, then consumer style.
-
-### Performance and resources
-
-- **PR1 — No work beyond render.** The list adds no state, effect, listener, or
-  observer; it reads translation and CommandPalette context during render only.
-
-## Accessibility contract
-
-- **AR1 — Name.** The listbox takes `label` as its accessible name and falls back
-  to the translated default when `label` is omitted.
-- **AR2 — Relationship.** Inside CommandPalette, the query field controls the
-  listbox through its id; CommandPalette owns focus and keyboard navigation under
-  its 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.
-- **AR4 — Empty content.** Inside CommandPalette, while no selectable result
-  exists, the root has no role and no accessible name, so screen readers meet the
-  empty or pending message as plain content and no empty popup; WAI-ARIA 1.2
-  requires a listbox to own options. A standalone list stays a listbox, and its
-  caller supplies the options.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                                                  | Representation authority       | Hierarchy role | Component contract |
-| ---------------- | ----------------------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
-| List             | Presents result options in one scrolling column with spacing-scale padding and gap. | Current source and public docs | Supporting     | FR1, FR4           |
-
-## Family and system relationships
-
-- `component:CommandPalette` owns list-id generation, keyboard navigation, hover
-  highlight, the aggregate anatomy, and the `command-palette-list` target
-  mapping; this component applies the id and paints the List.
-- `architecture:public-component-api` owns native passthrough, styling
-  composition, and refs.
-- `architecture:component-theming-surface` owns target qualification and the
-  aggregate List anatomy map.
-- `architecture:component-test-sufficiency` owns the evidence rules behind the
-  verification map below.
-
-## 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` |
-
-## 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.
-
-## Open questions
-
-- **OQ1 — What standalone keyboard contract should CommandPaletteList expose?**
-  (`human-api`) A standalone list exposes a listbox of options but no owning
-  keyboard model. Decide whether a public composite owner supplies that model,
-  the standalone composition takes a different role, or standalone use remains
-  pointer-only presentation.
-
-## 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.