An open source design system that's fully customizable and agent ready
TypeScript
[Component Audit] CommandPaletteList: make listbox evidence and composition guidance trustworthy (#7370)
Cindy Zhang1e883f86e7aa
diff --git a/.changeset/command-palette-list-composition-docs.md b/.changeset/command-palette-list-composition-docs.mdnew file mode 100644index 0000000000..e312a84946--- /dev/null+++ b/.changeset/command-palette-list-composition-docs.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[docs] Describe `CommandPaletteList` as the list `CommandPalette` renders itself, and as a component to render directly only for a standalone results list.++@cixzhangdiff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.jsonindex 74bdb3ecd2..f4049d21bf 100644--- a/apps/storybook/rtl-audit/verified-not-applicable.json+++ b/apps/storybook/rtl-audit/verified-not-applicable.json@@ -327,5 +327,14 @@"packages/core/src/CommandPalette/CommandPaletteGroup.tsx": "sha256:7c9a33733d68a42ea57a928a4d6ed20caa2562f53cb2340fe8122071bcc95924","packages/core/src/CommandPalette/index.ts": "sha256:ba38845bbde6d73172df2c0791ca513c9f2b7baab17440e066e783ff6cfc7558"}+ },+ {+ "component": "core/CommandPaletteList",+ "reason": "CommandPaletteList owns one vertically stacked results container that scrolls on the block axis, with symmetric padding and block-axis gaps. It renders no directional glyph, physical inline positioning, reordered controls, horizontal scrolling or dragging, side-placed overlay, or horizontal keyboard behavior; item and group content follow normal document direction, and CommandPalette owns arrow-key navigation. The dedicated fixtures exercise the standalone listbox and the scrolling palette composition without adding a component-owned RTL dimension.",+ "evidence": {+ "apps/storybook/stories/CommandPaletteList.stories.tsx": "sha256:5311530b408d5888acd198e24672c351b6249f1eb950c33de3922c45457f68fc",+ "packages/core/src/CommandPalette/CommandPaletteList.tsx": "sha256:bf8c2633c96f30f50863aec083dcaea689c00c4107c55ab58aa793d87a1ba65d",+ "packages/core/src/CommandPalette/index.ts": "sha256:ba38845bbde6d73172df2c0791ca513c9f2b7baab17440e066e783ff6cfc7558"+ }}]diff --git a/apps/storybook/stories/CommandPaletteList.stories.tsx b/apps/storybook/stories/CommandPaletteList.stories.tsxnew file mode 100644index 0000000000..a0e1014f68--- /dev/null+++ b/apps/storybook/stories/CommandPaletteList.stories.tsx@@ -0,0 +1,65 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {useMemo} from 'react';+import type {Meta, StoryObj} from '@storybook/react';+import {+ CommandPalette,+ CommandPaletteItem,+ CommandPaletteList,+} from '@astryxdesign/core/CommandPalette';+import {createStaticSource} from '@astryxdesign/core/Typeahead';++const meta: Meta<typeof CommandPaletteList> = {+ title: 'Core/CommandPaletteList',+ component: CommandPaletteList,+ tags: ['autodocs'],+ parameters: {+ layout: 'centered',+ },+};++export default meta;+type Story = StoryObj<typeof meta>;++/** A standalone results listbox with its translated default name. */+export const Default: Story = {+ render: () => (+ <CommandPaletteList>+ <CommandPaletteItem value="home" onSelect={() => {}}>+ Go home+ </CommandPaletteItem>+ <CommandPaletteItem value="settings" onSelect={() => {}}>+ Open settings+ </CommandPaletteItem>+ <CommandPaletteItem value="profile" onSelect={() => {}}>+ View profile+ </CommandPaletteItem>+ </CommandPaletteList>+ ),+};++/** More results than fit: the list scrolls inside CommandPalette. */+export const ScrollingResults: Story = {+ render: function Render() {+ const source = useMemo(+ () =>+ createStaticSource(+ Array.from({length: 24}, (_, index) => ({+ id: `command-${index + 1}`,+ label: `Command ${index + 1}`,+ })),+ ),+ [],+ );+ return (+ <CommandPalette+ isOpen+ isInline+ onOpenChange={() => {}}+ searchSource={source}+ width={480}+ maxHeight={320}+ />+ );+ },+};diff --git a/packages/core/src/CommandPalette/CommandPalette.spec.md b/packages/core/src/CommandPalette/CommandPalette.spec.mdindex 810cc9b1ac..417a15ea13 100644--- a/packages/core/src/CommandPalette/CommandPalette.spec.md+++ b/packages/core/src/CommandPalette/CommandPalette.spec.md@@ -71,6 +71,8 @@ Consumer migration instructions belong in consumer docs and release notes.factual backfill does not invent one.- Shared layer hosting, positioning, or lifecycle rules beyond the currentrecords linked below.+- The List root's accessible name, list-id application, native passthrough, and+ overflow scrolling — owned by `component:CommandPaletteList`.## Public conceptsdiff --git a/packages/core/src/CommandPalette/CommandPaletteList.spec.md b/packages/core/src/CommandPalette/CommandPaletteList.spec.mdnew file mode 100644index 0000000000..5a04244d3a--- /dev/null+++ b/packages/core/src/CommandPalette/CommandPaletteList.spec.md@@ -0,0 +1,189 @@+---+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 carries the context list id that 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 | Observational draft with no runtime change. A standalone caller `id` is overwritten (FR1), an empty list keeps the listbox role (AR4), and 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`+- Compatibility class: observational record only; runtime, DOM, 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.+- 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; absent | DOM id the CommandPalette query field references. | Inside CommandPalette; standalone | Context id inside CommandPalette; absent standalone | `component:CommandPalette` | Stable | A standalone caller `id` is overwritten (FR1 gap). |++## 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, an absent id replaces a caller `id`. | Released source; `architecture:public-component-api/INV5,INV6,INV8` | Ref and styling verified by focused tests; the standalone `id` conflicts with INV5 |+| FR2 | 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. | Released source and docs; WAI-ARIA 1.2 `listbox` | Role and name verified by focused tests; consumer-prop precedence is source-verified; the role also applies with no option (AR4) |+| 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 listbox root.+- **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. |++### 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.** The root keeps `role=listbox` when its children contain+ no option, as in CommandPalette's empty states. WAI-ARIA 1.2 requires a listbox+ to own options, so this is an open conflict, not a contract.++## 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 | `CommandPaletteList.test.tsx` | default and caller label | Removing the role or name 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.++## 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.diff --git a/packages/core/src/CommandPalette/CommandPaletteList.test.tsx b/packages/core/src/CommandPalette/CommandPaletteList.test.tsxindex 1be7731690..0f93b26aea 100644--- a/packages/core/src/CommandPalette/CommandPaletteList.test.tsx+++ b/packages/core/src/CommandPalette/CommandPaletteList.test.tsx@@ -7,7 +7,10 @@*/import {describe, it, expect} from 'vitest';+import {createRef} from 'react';import {render, screen} from '@testing-library/react';+import {createStaticSource} from '@astryxdesign/core/Typeahead';+import {CommandPalette} from './CommandPalette';import {CommandPaletteList} from './CommandPaletteList';describe('CommandPaletteList', () => {@@ -54,4 +57,48 @@ describe('CommandPaletteList', () => {'Search results',);});++ it('is the listbox that the CommandPalette query field controls', async () => {+ render(+ <CommandPalette+ isOpen+ isInline+ onOpenChange={() => {}}+ searchSource={createStaticSource([{id: 'home', label: 'Home'}])}+ />,+ );++ const listbox = await screen.findByRole('listbox');+ expect(listbox.id).not.toBe('');+ expect(screen.getByRole('combobox')).toHaveAttribute(+ 'aria-controls',+ listbox.id,+ );+ });++ it('connects ref to the listbox element', () => {+ const ref = createRef<HTMLDivElement>();+ render(+ <CommandPaletteList ref={ref}>+ <div>Item</div>+ </CommandPaletteList>,+ );++ expect(ref.current).toBe(screen.getByRole('listbox'));+ });++ it('combines consumer className and style with the list theme target', () => {+ render(+ <CommandPaletteList className="product-results" style={{minHeight: 120}}>+ <div>Item</div>+ </CommandPaletteList>,+ );++ const listbox = screen.getByRole('listbox');+ expect(listbox).toHaveClass(+ 'astryx-command-palette-list',+ 'product-results',+ );+ expect(listbox).toHaveStyle({minHeight: '120px'});+ });});diff --git a/packages/core/src/CommandPalette/CommandPaletteList.tsx b/packages/core/src/CommandPalette/CommandPaletteList.tsxindex 4a5e4c1204..9382c36a26 100644--- a/packages/core/src/CommandPalette/CommandPaletteList.tsx+++ b/packages/core/src/CommandPalette/CommandPaletteList.tsx@@ -59,8 +59,9 @@ export interface CommandPaletteListProps extends BaseProps<HTMLDivElement> {* When used inside CommandPalette, automatically gets the correct* ID for aria-controls linking with the input.*- * @compositionHint Place inside CommandPalette, after CommandPaletteInput.- * Contains CommandPaletteItem and CommandPaletteGroup children.+ * @compositionHint CommandPalette renders its own list after its input; render+ * this list directly only for a standalone results list. Contains+ * CommandPaletteItem and CommandPaletteGroup children.** @example* ```