Skip to content

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.md
new file mode 100644
index 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.
+
+@cixzhang
diff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.json
index 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.tsx
new file mode 100644
index 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.md
index 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 current
records linked below.
+- The List root's accessible name, list-id application, native passthrough, and
+ overflow scrolling — owned by `component:CommandPaletteList`.
## Public concepts
diff --git a/packages/core/src/CommandPalette/CommandPaletteList.spec.md b/packages/core/src/CommandPalette/CommandPaletteList.spec.md
new file mode 100644
index 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.tsx
index 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.tsx
index 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
* ```