An open source design system that's fully customizable and agent ready
TypeScript
[Component Audit] CommandPaletteItem: preserve option activation and identity (#7324)
Cindy Zhang80e8be2622c0
diff --git a/.changeset/command-palette-item-disabled.md b/.changeset/command-palette-item-disabled.mdnew file mode 100644index 0000000000..62b2fc25f5--- /dev/null+++ b/.changeset/command-palette-item-disabled.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] Keep standalone command-palette item IDs on the rendered option and suppress consumer click callbacks when an item is disabled.++@cixzhang @korkt-kimdiff --git a/apps/storybook/rtl-audit/targets.json b/apps/storybook/rtl-audit/targets.jsonindex 72f551ad39..fa9baf2631 100644--- a/apps/storybook/rtl-audit/targets.json+++ b/apps/storybook/rtl-audit/targets.json@@ -520,6 +520,11 @@"next": ".astryx-avatar-group-overflow"}},+ {+ "component": "CommandPaletteItem",+ "storyId": "core-commandpaletteitem--states",+ "dims": []+ },{"component": "CommandPaletteFooter","storyId": "core-commandpalettefooter--default",diff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.jsonindex f4049d21bf..ab2e63dcfe 100644--- a/apps/storybook/rtl-audit/verified-not-applicable.json+++ b/apps/storybook/rtl-audit/verified-not-applicable.json@@ -319,6 +319,15 @@"packages/core/src/Divider/Divider.tsx": "sha256:f302b5c9eecde40b486c09d49c71cb7dab158e2fcedcb38c0145671c45d9cf8d"}},+ {+ "component": "core/CommandPaletteItem",+ "reason": "CommandPaletteItem owns one inline flex option row with logical inline padding, logical start text alignment, and direction-neutral highlight, selection, disabled, and press paint. Its supported content is non-interactive text, icons, descriptions, and shortcut hints; it owns no directional glyph, side placement, reordering, horizontal scroll, drag, overlay, or horizontal keyboard behavior. The dedicated state fixture exercises every component-owned visual state without adding an RTL-specific dimension.",+ "evidence": {+ "apps/storybook/stories/CommandPaletteItem.stories.tsx": "sha256:9d5c2229f89da3ac53347078560b9ad57cfff7b20a3c71ad3fab2c338161dbf1",+ "packages/core/src/CommandPalette/CommandPaletteItem.tsx": "sha256:aee0fcaa7b9829e04317f1cab9708c045a1da0d9180e490d64c6a576c39d8f42",+ "packages/core/src/CommandPalette/index.ts": "sha256:ba38845bbde6d73172df2c0791ca513c9f2b7baab17440e066e783ff6cfc7558"+ }+ },{"component": "core/CommandPaletteGroup","reason": "CommandPaletteGroup owns a vertically stacked listbox group with logical inline padding and block spacing. Its visible heading and item content follow normal document direction; it renders no directional glyph, physical inline positioning, reordered controls, horizontal scrolling or dragging, side-placed overlay, or horizontal keyboard behavior. The dedicated fixtures exercise the supported composition and public heading theme target without adding a component-owned RTL dimension.",diff --git a/apps/storybook/stories/CommandPaletteItem.stories.tsx b/apps/storybook/stories/CommandPaletteItem.stories.tsxnew file mode 100644index 0000000000..c3bbc46ce1--- /dev/null+++ b/apps/storybook/stories/CommandPaletteItem.stories.tsx@@ -0,0 +1,46 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import type {Meta, StoryObj} from '@storybook/react';+import {+ CommandPaletteItem,+ CommandPaletteList,+} from '@astryxdesign/core/CommandPalette';+import {Kbd} from '@astryxdesign/core/Kbd';++const meta: Meta<typeof CommandPaletteItem> = {+ title: 'Core/CommandPaletteItem',+ component: CommandPaletteItem,+ tags: ['autodocs', 'visual-theme-matrix'],+ parameters: {+ layout: 'centered',+ },+};++export default meta;+type Story = StoryObj<typeof meta>;++/** Default, highlighted, selected, and disabled states in the supported listbox composition. */+export const States: Story = {+ render: () => (+ <CommandPaletteList+ label="Command item states"+ style={{inlineSize: 'min(22rem, calc(100vw - 2rem))'}}>+ <CommandPaletteItem value="open-file" onSelect={() => {}}>+ Open file+ <Kbd keys="mod+o" />+ </CommandPaletteItem>+ <CommandPaletteItem+ value="search-files"+ isHighlighted+ onSelect={() => {}}>+ Search files+ </CommandPaletteItem>+ <CommandPaletteItem value="settings" isSelected onSelect={() => {}}>+ Settings+ </CommandPaletteItem>+ <CommandPaletteItem value="archived" isDisabled onSelect={() => {}}>+ Archived command+ </CommandPaletteItem>+ </CommandPaletteList>+ ),+};diff --git a/packages/core/src/CommandPalette/CommandPalette.doc.mjs b/packages/core/src/CommandPalette/CommandPalette.doc.mjsindex 36328f3bef..927d771faf 100644--- a/packages/core/src/CommandPalette/CommandPalette.doc.mjs+++ b/packages/core/src/CommandPalette/CommandPalette.doc.mjs@@ -88,7 +88,8 @@ export const docs = {'dialog','navigation',],- description: 'Root component. Manages open state, search, keyboard navigation, and composition slots.',+ description:+ 'Root component. Manages open state, search, keyboard navigation, and composition slots.',// Intentionally a contained isInline preview, not playground.overlay: the// component stays visible on load and knobs stay live, whereas a real// showModal() overlay makes the page inert — see ComponentPlaygroundConfig.overlay@@ -116,13 +117,15 @@ export const docs = {{name: 'searchSource',type: 'SearchSource<T>',- description: 'Search source providing items via search(query) and bootstrap(). Use createStaticSource for static lists.',+ description:+ 'Search source providing items via search(query) and bootstrap(). Use createStaticSource for static lists.',required: true,},{name: 'input',type: 'ReactNode',- description: 'Input slot. Defaults to CommandPaletteInput with standard behavior.',+ description:+ 'Input slot. Defaults to CommandPaletteInput with standard behavior.',default: '<CommandPaletteInput />',slotElements: [{@@ -137,7 +140,8 @@ export const docs = {{name: 'footer',type: 'ReactNode',- description: 'Footer slot. Defaults to CommandPaletteFooter showing keyboard hints.',+ description:+ 'Footer slot. Defaults to CommandPaletteFooter showing keyboard hints.',default: '<CommandPaletteFooter />',slotElements: [{@@ -152,7 +156,8 @@ export const docs = {{name: 'renderItem',type: '(item: T, isSelected: boolean) => ReactNode',- description: 'Per-item render function. Auto-grouping by auxiliaryData.group is preserved. When omitted, renders label text.',+ description:+ 'Per-item render function for non-interactive presentation content such as labels, icons, descriptions, and shortcut hints. Do not return buttons or links inside the option. Auto-grouping by auxiliaryData.group is preserved. When omitted, renders label text.',},{name: 'emptySearchText',@@ -163,7 +168,8 @@ export const docs = {{name: 'emptyBootstrapText',type: 'ReactNode',- description: 'Content shown when there is no search query and bootstrap() returns nothing.',+ description:+ 'Content shown when there is no search query and bootstrap() returns nothing.',default: "'Type to search'",},{@@ -197,7 +203,8 @@ export const docs = {{name: 'isInline',type: 'boolean',- description: 'Renders command palette content inline without modal behavior. Automatically disables input auto-focus and initial highlighted-item auto-scroll. For documentation previews and showcases only.',+ description:+ 'Renders command palette content inline without modal behavior. Automatically disables input auto-focus and initial highlighted-item auto-scroll. For documentation previews and showcases only.',default: 'false',},],@@ -222,12 +229,34 @@ export const docs = {},usage: {anatomy,- description: 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',+ description:+ 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',bestPractices: [- { guidance: true, description: 'Provide a searchSource with bootstrap results so users see useful options before typing.' },- { guidance: true, description: 'Use auxiliaryData.group on items to automatically organize results into labeled sections.' },- { guidance: false, description: 'Use CommandPalette for simple dropdowns or menus; use Menu or Selector for inline selections.' },- { guidance: false, description: 'Add too many groups or items; curate results to keep the palette fast and scannable.' },+ {+ guidance: true,+ description:+ 'Provide a searchSource with bootstrap results so users see useful options before typing.',+ },+ {+ guidance: true,+ description:+ 'Use auxiliaryData.group on items to automatically organize results into labeled sections.',+ },+ {+ guidance: true,+ description:+ 'Keep renderItem content non-interactive; each rendered row is one option, so buttons and links cannot be nested inside it.',+ },+ {+ guidance: false,+ description:+ 'Use CommandPalette for simple dropdowns or menus; use Menu or Selector for inline selections.',+ },+ {+ guidance: false,+ description:+ 'Add too many groups or items; curate results to keep the palette fast and scannable.',+ },],},};@@ -236,12 +265,34 @@ export const docs = {export const docsZh = {usage: {anatomy,- description: 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',+ description:+ 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',bestPractices: [- { guidance: true, description: 'Provide a searchSource with bootstrap results so users see useful options before typing.' },- { guidance: true, description: 'Use auxiliaryData.group on items to automatically organize results into labeled sections.' },- { guidance: false, description: 'Use CommandPalette for simple dropdowns or menus; use Menu or Selector for inline selections.' },- { guidance: false, description: 'Add too many groups or items; curate results to keep the palette fast and scannable.' },+ {+ guidance: true,+ description:+ 'Provide a searchSource with bootstrap results so users see useful options before typing.',+ },+ {+ guidance: true,+ description:+ 'Use auxiliaryData.group on items to automatically organize results into labeled sections.',+ },+ {+ guidance: true,+ description:+ 'Keep renderItem content non-interactive; each rendered row is one option, so buttons and links cannot be nested inside it.',+ },+ {+ guidance: false,+ description:+ 'Use CommandPalette for simple dropdowns or menus; use Menu or Selector for inline selections.',+ },+ {+ guidance: false,+ description:+ 'Add too many groups or items; curate results to keep the palette fast and scannable.',+ },],},};@@ -252,12 +303,34 @@ export const docsDense = {'searchSource-driven command palette dialog; filtering, keyboard nav, grouping, selection; same SearchSource interface as Typeahead',usage: {anatomy,- description: 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',+ description:+ 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',bestPractices: [- { guidance: true, description: 'Provide a searchSource with bootstrap results so users see useful options before typing.' },- { guidance: true, description: 'Use auxiliaryData.group on items to automatically organize results into labeled sections.' },- { guidance: false, description: 'Use CommandPalette for simple dropdowns or menus; use Menu or Selector for inline selections.' },- { guidance: false, description: 'Add too many groups or items; curate results to keep the palette fast and scannable.' },+ {+ guidance: true,+ description:+ 'Provide a searchSource with bootstrap results so users see useful options before typing.',+ },+ {+ guidance: true,+ description:+ 'Use auxiliaryData.group on items to automatically organize results into labeled sections.',+ },+ {+ guidance: true,+ description:+ 'Keep renderItem content non-interactive; each rendered row is one option, so buttons and links cannot be nested inside it.',+ },+ {+ guidance: false,+ description:+ 'Use CommandPalette for simple dropdowns or menus; use Menu or Selector for inline selections.',+ },+ {+ guidance: false,+ description:+ 'Add too many groups or items; curate results to keep the palette fast and scannable.',+ },],},};diff --git a/packages/core/src/CommandPalette/CommandPalette.spec.md b/packages/core/src/CommandPalette/CommandPalette.spec.mdindex 417a15ea13..89aed414f3 100644--- a/packages/core/src/CommandPalette/CommandPalette.spec.md+++ b/packages/core/src/CommandPalette/CommandPalette.spec.md@@ -57,8 +57,8 @@ Consumer migration instructions belong in consumer docs and release notes.**Owns**-- Search orchestration and the current Input, List, Item, Group, Group heading,- Empty, and Footer parts and targets.+- Search orchestration and composition of the current Input, List, Item, Group,+ Group heading, Empty, and Footer parts and targets.- The native Query field rendered inside the default Input.**Does not own / non-goals**@@ -67,6 +67,8 @@ Consumer migration instructions belong in consumer docs and release notes.badges — owned by their respective components.- Caller-provided replacement Input, Footer, item content, or trailing inputcontent — owned by the product callsite.+- The Item option's passthrough, pointer, disabled, selected, highlighted, and+ standalone-scroll semantics — owned by `component:CommandPaletteItem`.- A `command-palette` root target — no such current target exists, and thisfactual backfill does not invent one.- Shared layer hosting, positioning, or lifecycle rules beyond the currentdiff --git a/packages/core/src/CommandPalette/CommandPalette.tsx b/packages/core/src/CommandPalette/CommandPalette.tsxindex d2468af8a5..9053af0386 100644--- a/packages/core/src/CommandPalette/CommandPalette.tsx+++ b/packages/core/src/CommandPalette/CommandPalette.tsx@@ -78,7 +78,9 @@ export interface CommandPaletteProps</*** Per-item render function. Receives the item and whether it is currently selected.- * Auto-grouping by `auxiliaryData.group` is preserved.+ * Return non-interactive presentation content; buttons and links cannot be+ * nested inside the rendered option. Auto-grouping by `auxiliaryData.group`+ * is preserved.* When omitted, renders each item's `label` text.*/renderItem?: (item: T, isSelected: boolean) => ReactNode;diff --git a/packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs b/packages/core/src/CommandPalette/CommandPaletteItem.doc.mjsindex 35152c02b9..1819cfb868 100644--- a/packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs+++ b/packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs@@ -7,47 +7,93 @@ export const docs = {subComponentOf: 'CommandPalette',displayName: 'Command Palette Item',isHiddenFromOverview: true,- description: 'A selectable item. Accepts arbitrary children for full rendering control. Registers with context for keyboard navigation when inside CommandPalette.',+ description:+ 'One option in a command palette result list. CommandPalette context supplies selection, highlight, identity, and close behavior.',+ usage: {+ description:+ 'Use CommandPaletteItem for one non-interactive result row inside CommandPaletteList or CommandPaletteGroup. CommandPalette owns the composite keyboard model; standalone items expose only their explicit visual state and pointer activation.',+ bestPractices: [+ {+ guidance: true,+ description:+ 'Keep each value unique within the result list so highlight, active-descendant identity, and selection resolve to the same item.',+ },+ {+ guidance: true,+ description:+ 'Use non-interactive child content such as icons, descriptions, and shortcut hints; activate the option itself instead of nesting buttons or links.',+ },+ {+ guidance: false,+ description:+ 'Treat isHighlighted as selection. Highlight is the active keyboard result; isSelected represents the chosen value.',+ },+ ],+ anatomy: [+ {+ name: 'Item',+ required: true,+ description:+ 'The option root that carries selection, disabled, item identity, interaction, and theme state.',+ },+ {+ name: 'Content',+ required: true,+ description:+ 'Caller-provided non-interactive label and supporting presentation.',+ },+ ],+ },+ theming: {+ targets: [{className: 'astryx-command-palette-item'}],+ },props: [{name: 'value',type: 'string',- description: 'Unique value for identification and selection.',+ description:+ 'Unique value used for item identity, highlight lookup, and selection.',required: true,},{name: 'children',type: 'ReactNode',- description: 'Item content: render icons, descriptions, keyboard shortcuts, etc.',+ description:+ 'Non-interactive item content such as a label, icon, description, or keyboard shortcut.',required: true,},{name: 'onSelect',type: '(value: string) => void',- description: 'Called when this item is selected via click or Enter.',+ description:+ 'Called after this item is activated by pointer. Keyboard selection in CommandPalette reports through CommandPalette onValueChange.',},{name: 'isHighlighted',type: 'boolean',- description: 'Whether this item has keyboard focus. Derived from context when inside CommandPalette.',+ description:+ 'Whether this item is the active keyboard result. Derived from context when omitted inside CommandPalette.',default: 'false',},{name: 'isSelected',type: 'boolean',- description: 'Whether this item is selected in picker mode.',+ description:+ 'Whether this item represents the selected value in picker mode.',default: 'false',},{name: 'isDisabled',type: 'boolean',- description: 'Whether the item is non-interactive.',+ description:+ 'Whether the item is unavailable and suppresses pointer activation.',default: 'false',},{name: 'xstyle',type: 'StyleXStyles',- description: 'StyleX styles for layout customization. Must be a stylex.create() value.',+ description:+ 'StyleX styles for layout customization. Must be a stylex.create() value.',},],playground: {@@ -62,14 +108,17 @@ export const docsZh = {name: 'CommandPaletteItem',isHiddenFromOverview: true,displayName: 'Command Palette Item',- description: '可选择的条目。接受任意子元素以实现完整的渲染控制。',+ description:+ '命令面板结果列表中的一个选项。CommandPalette 上下文提供选择、高亮、标识和关闭行为。',propDescriptions: {- value: '用于标识和选择的唯一值。',- children: '条目内容——渲染图标、描述、键盘快捷键等。',- onSelect: '通过点击或 Enter 选择此条目时调用。',- isHighlighted: '此条目是否具有键盘焦点。在 CommandPalette 内从上下文派生。',- isSelected: '此条目在选择器模式下是否被选中。',- isDisabled: '条目是否为非交互状态。',+ value: '用于条目标识、高亮查找和选择的唯一值。',+ children: '非交互式条目内容,例如标签、图标、描述或键盘快捷键。',+ onSelect:+ '通过指针激活此条目后调用。CommandPalette 中的键盘选择通过根组件的 onValueChange 报告。',+ isHighlighted:+ '此条目是否为当前键盘结果。在 CommandPalette 内省略时从上下文派生。',+ isSelected: '此条目是否代表选择器模式中的已选值。',+ isDisabled: '条目是否不可用并禁止指针激活。',xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',},};@@ -78,14 +127,16 @@ export const docsDense = {name: 'CommandPaletteItem',isHiddenFromOverview: true,displayName: 'Command Palette Item',- description: 'selectable item; arbitrary children; registers w/ context for kbd nav',+ description:+ 'one result option; context owns selection, highlight, identity, and close',propDescriptions: {- value: 'unique id for selection',- children: 'item content: icons, descriptions, shortcuts',- onSelect: 'called on click or Enter',- isHighlighted: 'keyboard focus; derived from context inside palette',- isSelected: 'selected in picker mode',- isDisabled: 'non-interactive',+ value: 'unique value for identity, highlight lookup, and selection',+ children: 'non-interactive label and supporting content',+ onSelect:+ 'called after pointer activation; palette keyboard selection uses root onValueChange',+ isHighlighted: 'active keyboard result; derived from context when omitted',+ isSelected: 'selected value in picker mode',+ isDisabled: 'unavailable; suppresses pointer activation',xstyle: 'StyleX layout styles; must be stylex.create() value',},};diff --git a/packages/core/src/CommandPalette/CommandPaletteItem.spec.md b/packages/core/src/CommandPalette/CommandPaletteItem.spec.mdnew file mode 100644index 0000000000..45e435538b--- /dev/null+++ b/packages/core/src/CommandPalette/CommandPaletteItem.spec.md@@ -0,0 +1,223 @@+---+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.diff --git a/packages/core/src/CommandPalette/CommandPaletteItem.test.tsx b/packages/core/src/CommandPalette/CommandPaletteItem.test.tsxindex 74e897aadb..dfc60dcd80 100644--- a/packages/core/src/CommandPalette/CommandPaletteItem.test.tsx+++ b/packages/core/src/CommandPalette/CommandPaletteItem.test.tsx@@ -6,9 +6,12 @@* @output Unit tests for CommandPaletteItem*/+import {createRef, type ReactElement} from 'react';import {afterEach, describe, it, expect, vi} from 'vitest';import {render, screen, fireEvent, waitFor} from '@testing-library/react';import {Dialog} from '../Dialog/Dialog';+import {CommandPaletteContext} from './CommandPaletteContext';+import type {CommandPaletteContextValue} from './CommandPaletteContext';import {CommandPaletteItem} from './CommandPaletteItem';const scrollIntoViewDescriptor = Object.getOwnPropertyDescriptor(@@ -38,11 +41,45 @@ afterEach(() => {}});+function makeContext(+ overrides: Partial<CommandPaletteContextValue> = {},+): CommandPaletteContextValue {+ return {+ search: '',+ setSearch: vi.fn(),+ value: '',+ setValue: vi.fn(),+ listId: 'command-list',+ highlightedIndex: -1,+ setHighlightedIndex: vi.fn(),+ getItemId: index => `command-item-${index}`,+ selectableItems: [{value: 'test', label: 'Item'}],+ searchResults: [],+ selectItem: vi.fn(),+ onKeyDown: vi.fn(),+ onClose: vi.fn(),+ isOpen: true,+ isBusy: false,+ ...overrides,+ };+}++function renderWithContext(+ item: ReactElement,+ overrides: Partial<CommandPaletteContextValue> = {},+) {+ const context = makeContext(overrides);+ return {+ context,+ ...render(+ <CommandPaletteContext value={context}>{item}</CommandPaletteContext>,+ ),+ };+}+describe('CommandPaletteItem', () => {it('renders children', () => {- render(- <CommandPaletteItem value="test">Test Item</CommandPaletteItem>,- );+ render(<CommandPaletteItem value="test">Test Item</CommandPaletteItem>);expect(screen.getByText('Test Item')).toBeInTheDocument();});@@ -62,6 +99,36 @@ describe('CommandPaletteItem', () => {expect(handleSelect).toHaveBeenCalledWith('test');});+ it('coordinates selection and close through CommandPalette context', () => {+ const handleSelect = vi.fn();+ const {context} = renderWithContext(+ <CommandPaletteItem value="test" onSelect={handleSelect}>+ Item+ </CommandPaletteItem>,+ );++ fireEvent.click(screen.getByRole('option'));++ expect(handleSelect).toHaveBeenCalledWith('test');+ expect(context.selectItem).toHaveBeenCalledWith('test');+ expect(context.onClose).toHaveBeenCalledTimes(1);+ });++ it('lets consumer click cancellation stop contextual selection and close', () => {+ const {context} = renderWithContext(+ <CommandPaletteItem+ value="test"+ onClick={event => event.preventDefault()}>+ Item+ </CommandPaletteItem>,+ );++ fireEvent.click(screen.getByRole('option'));++ expect(context.selectItem).not.toHaveBeenCalled();+ expect(context.onClose).not.toHaveBeenCalled();+ });+it('does not call onSelect when disabled', () => {const handleSelect = vi.fn();render(@@ -73,6 +140,94 @@ describe('CommandPaletteItem', () => {expect(handleSelect).not.toHaveBeenCalled();});+ it('does not call consumer click or selection handlers when disabled', () => {+ const handleClick = vi.fn();+ const handleSelect = vi.fn();+ render(+ <CommandPaletteItem+ value="test"+ isDisabled+ onClick={handleClick}+ onSelect={handleSelect}>+ Item+ </CommandPaletteItem>,+ );++ fireEvent.click(screen.getByRole('option'));++ expect(handleClick).not.toHaveBeenCalled();+ expect(handleSelect).not.toHaveBeenCalled();+ });++ it('lets a consumer cancel selection from onClick', () => {+ const handleSelect = vi.fn();+ render(+ <CommandPaletteItem+ value="test"+ onClick={event => event.preventDefault()}+ onSelect={handleSelect}>+ Item+ </CommandPaletteItem>,+ );++ fireEvent.click(screen.getByRole('option'));++ expect(handleSelect).not.toHaveBeenCalled();+ });++ it('derives selected state and item identity from context', () => {+ renderWithContext(+ <CommandPaletteItem value="test" id="consumer-id">+ Item+ </CommandPaletteItem>,+ {value: 'test'},+ );++ const item = screen.getByRole('option');+ expect(item).toHaveAttribute('id', 'command-item-0');+ expect(item).toHaveAttribute('aria-selected', 'true');+ });++ it('paints context-derived highlight when the item is not selected', () => {+ renderWithContext(+ <CommandPaletteItem value="test">Item</CommandPaletteItem>,+ {highlightedIndex: 0},+ );++ expect(getComputedStyle(screen.getByRole('option')).backgroundColor).toBe(+ 'var(--color-overlay-hover)',+ );+ });++ it('lets explicit visual state override context-derived state', () => {+ renderWithContext(+ <CommandPaletteItem value="test" isHighlighted={false} isSelected={false}>+ Item+ </CommandPaletteItem>,+ {value: 'test', highlightedIndex: 0},+ );++ const item = screen.getByRole('option');+ expect(item).toHaveAttribute('aria-selected', 'false');+ expect(getComputedStyle(item).backgroundColor).toBe('rgba(0, 0, 0, 0)');+ });++ it('protects owned option semantics from native passthrough props', () => {+ render(+ <CommandPaletteItem+ value="test"+ role="button"+ aria-selected={true}+ aria-disabled={true}>+ Item+ </CommandPaletteItem>,+ );++ const item = screen.getByRole('option');+ expect(item).toHaveAttribute('aria-selected', 'false');+ expect(item).not.toHaveAttribute('aria-disabled');+ });+it('sets aria-disabled when disabled', () => {render(<CommandPaletteItem value="test" isDisabled>@@ -157,10 +312,43 @@ describe('CommandPaletteItem', () => {});});- it('sets data-value attribute', () => {+ it('forwards ref and standalone DOM attributes to the option', () => {+ const ref = createRef<HTMLDivElement>();render(- <CommandPaletteItem value="my-value">Item</CommandPaletteItem>,+ <CommandPaletteItem+ ref={ref}+ value="test"+ id="standalone-item"+ aria-label="Open settings"+ data-kind="command">+ Item+ </CommandPaletteItem>,);++ const item = screen.getByRole('option', {name: 'Open settings'});+ expect(ref.current).toBe(item);+ expect(item).toHaveAttribute('id', 'standalone-item');+ expect(item).toHaveAttribute('data-kind', 'command');+ });++ it('carries the stable theme target and consumer styling on its root', () => {+ render(+ <CommandPaletteItem+ value="test"+ className="consumer-item"+ style={{marginBlockStart: '8px'}}>+ Item+ </CommandPaletteItem>,+ );++ const item = screen.getByRole('option');+ expect(item).toHaveClass('astryx-command-palette-item');+ expect(item).toHaveClass('consumer-item');+ expect(item).toHaveStyle({marginBlockStart: '8px'});+ });++ it('sets data-value attribute', () => {+ render(<CommandPaletteItem value="my-value">Item</CommandPaletteItem>);expect(screen.getByRole('option')).toHaveAttribute('data-value','my-value',diff --git a/packages/core/src/CommandPalette/CommandPaletteItem.tsx b/packages/core/src/CommandPalette/CommandPaletteItem.tsxindex 0a1fa645b4..344f861437 100644--- a/packages/core/src/CommandPalette/CommandPaletteItem.tsx+++ b/packages/core/src/CommandPalette/CommandPaletteItem.tsx@@ -74,7 +74,11 @@ export interface CommandPaletteItemProps extends Omit<ref?: React.Ref<HTMLDivElement>;/** Unique value for identification and selection. */value: string;- /** Called when this item is selected (via click or Enter). */+ /**+ * Called after this item is activated by pointer.+ * Keyboard selection inside CommandPalette reports through the root+ * `onValueChange` callback.+ */onSelect?: (value: string) => void;/*** Whether this item is visually highlighted (keyboard focus).@@ -92,7 +96,7 @@ export interface CommandPaletteItemProps extends Omit<* @default false*/isDisabled?: boolean;- /** Item content. Fully custom — render icons, descriptions, shortcuts, etc. */+ /** Non-interactive item content: labels, icons, descriptions, shortcuts, etc. */children: ReactNode;}@@ -100,9 +104,10 @@ export interface CommandPaletteItemProps extends Omit<* A selectable item in the command palette.* Accepts arbitrary children for full rendering control.*- * When used inside CommandPalette, registers with context for- * keyboard navigation and selection. Can also be used- * standalone with explicit isHighlighted/isSelected props.+ * When used inside CommandPalette, context supplies identity, highlight,+ * selection, and close behavior. Standalone use supports explicit visual+ * state and pointer activation but does not provide a composite listbox+ * keyboard model.** @compositionHint Place inside CommandPaletteList or CommandPaletteGroup.*@@ -124,6 +129,7 @@ export function CommandPaletteItem({xstyle,className,style,+ id: idProp,onClick: onClickProp,onMouseEnter: onMouseEnterProp,...props@@ -174,27 +180,26 @@ export function CommandPaletteItem({}, [ctx, isHighlighted, isInlineDialog]);const handleClick = useCallback(() => {- if (isDisabled) {- return;- }onSelect?.(value);if (ctx) {ctx.selectItem(value);ctx.onClose();}- }, [isDisabled, value, onSelect, ctx]);+ }, [value, onSelect, ctx]);return (<divref={useMergedRefs(ref, itemRef)}{...props}- id={ctx && itemIndex >= 0 ? ctx.getItemId(itemIndex) : undefined}+ id={ctx && itemIndex >= 0 ? ctx.getItemId(itemIndex) : idProp}role="option"aria-selected={isSelected}aria-disabled={isDisabled || undefined}data-value={value}{...pressable}- onClick={composeEventHandlers(onClickProp, handleClick)}+ onClick={+ isDisabled ? undefined : composeEventHandlers(onClickProp, handleClick)+ }onMouseEnter={onMouseEnterProp}{...mergeProps(themeProps('command-palette-item'),