@astryxdesign/core 0.7.1-canary.ff40b78 → 0.7.1

package/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 (
     <div
       ref={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'),

package/src/CommandPalette/CommandPaletteList.doc.mjs

@@ -7,7 +7,7 @@ export const docs = {
   subComponentOf: 'CommandPalette',
   displayName: 'Command Palette List',
   isHiddenFromOverview: true,
-  description: 'Scrollable results container. Renders as a listbox for ARIA. Contains CommandPaletteItem and CommandPaletteGroup children.',
+  description: 'Scrollable results container. Renders as a listbox standalone, and inside CommandPalette while selectable results exist. Contains CommandPaletteItem and CommandPaletteGroup children.',
   props: [
     {
       name: 'children',
@@ -42,7 +42,7 @@ export const docsZh = {
   name: 'CommandPaletteList',
   isHiddenFromOverview: true,
   displayName: 'Command Palette List',
-  description: '可滚动的结果容器。作为 listbox 渲染以符合 ARIA 规范。',
+  description: '可滚动的结果容器。独立使用时，以及在 CommandPalette 中存在可选结果时，作为 listbox 渲染。',
   propDescriptions: {
     children: '条目、分组和空状态。',
     label: 'listbox 的无障碍标签。',
@@ -54,7 +54,7 @@ export const docsDense = {
   name: 'CommandPaletteList',
   isHiddenFromOverview: true,
   displayName: 'Command Palette List',
-  description: 'scrollable results container; role=listbox',
+  description: 'scrollable results container; role=listbox standalone, and in CommandPalette only while results exist',
   propDescriptions: {
     children: 'items, groups, empty states',
     label: 'a11y label for listbox',

package/src/CommandPalette/CommandPaletteList.spec.md

@@ -36,15 +36,15 @@ system_specs: []
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                              |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | None changes. One named listbox container for result options, rendered by CommandPalette or directly for a standalone results list.                                                   |
-| Behavior                | The root is a `listbox` named by `label` or the translated default; inside CommandPalette it 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`.                                                                 |
+| 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.
 
@@ -56,9 +56,10 @@ 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
+- 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
 
@@ -69,7 +70,8 @@ Consumer migration instructions belong in consumer docs and release notes.
 **Owns**
 
 - The listbox root and its accessible name from `label`, falling back to the
-  translated default.
+  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
@@ -91,31 +93,32 @@ Consumer migration instructions belong in consumer docs and release notes.
 | 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).                       |
+| 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, 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                          |
+| 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 listbox root.
+  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. |
+| 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
 
@@ -139,9 +142,11 @@ Consumer migration instructions belong in consumer docs and release notes.
 - **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.
+- **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
 
@@ -163,17 +168,17 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Verification map
 
-| Contract | Verification                                                                            | Representative states                      | Mutation or failure expectation                                                                                | Audit section                      |
-| -------- | --------------------------------------------------------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
-| FR1      | `CommandPaletteList.test.tsx`                                                           | standalone root with ref, class, and style | Disconnecting `ref`, or dropping the consumer class or the list target, fails focused DOM assertions.          | `audit:CommandPaletteList/api`     |
-| FR2, AR1 | `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` |
+| 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.
+keyboard, or visual decision; AR4 applies the WAI-ARIA 1.2 listbox rule.
 
 ## Open questions
 

package/src/CommandPalette/CommandPaletteList.test.tsx

@@ -11,8 +11,35 @@ import {createRef} from 'react';
 import {render, screen} from '@testing-library/react';
 import {createStaticSource} from '@astryxdesign/core/Typeahead';
 import {CommandPalette} from './CommandPalette';
+import {
+  CommandPaletteContext,
+  type CommandPaletteContextValue,
+} from './CommandPaletteContext';
 import {CommandPaletteList} from './CommandPaletteList';
 
+function makeContext(
+  overrides: Partial<CommandPaletteContextValue> = {},
+): CommandPaletteContextValue {
+  return {
+    search: '',
+    setSearch: () => {},
+    value: '',
+    setValue: () => {},
+    listId: 'command-list',
+    highlightedIndex: -1,
+    setHighlightedIndex: () => {},
+    getItemId: index => `command-item-${index}`,
+    selectableItems: [],
+    searchResults: [],
+    selectItem: () => {},
+    onKeyDown: () => {},
+    onClose: () => {},
+    isOpen: true,
+    isBusy: false,
+    ...overrides,
+  };
+}
+
 describe('CommandPaletteList', () => {
   it('renders children', () => {
     render(
@@ -34,6 +61,59 @@ describe('CommandPaletteList', () => {
     expect(screen.getByRole('listbox')).toBeInTheDocument();
   });
 
+  it('carries the stable list theme target', () => {
+    render(
+      <CommandPaletteList>
+        <div>Item</div>
+      </CommandPaletteList>,
+    );
+    expect(screen.getByRole('listbox')).toHaveClass(
+      'astryx-command-palette-list',
+    );
+  });
+
+  it('preserves the consumer id when used standalone', () => {
+    render(
+      <CommandPaletteList id="custom-commands">
+        <div>Item</div>
+      </CommandPaletteList>,
+    );
+
+    expect(screen.getByRole('listbox')).toHaveAttribute(
+      'id',
+      'custom-commands',
+    );
+  });
+
+  it('inside a palette, is a listbox only while it holds selectable results', () => {
+    const {rerender} = render(
+      <CommandPaletteContext value={makeContext()}>
+        <CommandPaletteList>
+          <div>No results</div>
+        </CommandPaletteList>
+      </CommandPaletteContext>,
+    );
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
+    expect(screen.getByText('No results').parentElement).not.toHaveAttribute(
+      'aria-label',
+    );
+
+    rerender(
+      <CommandPaletteContext
+        value={makeContext({
+          selectableItems: [{value: 'open', label: 'Open'}],
+        })}>
+        <CommandPaletteList>
+          <div>Open</div>
+        </CommandPaletteList>
+      </CommandPaletteContext>,
+    );
+    expect(screen.getByRole('listbox', {name: 'Commands'})).toHaveAttribute(
+      'id',
+      'command-list',
+    );
+  });
+
   it('has default aria-label', () => {
     render(
       <CommandPaletteList>

package/src/CommandPalette/CommandPaletteList.tsx

@@ -53,8 +53,10 @@ export interface CommandPaletteListProps extends BaseProps<HTMLDivElement> {
 }
 
 /**
- * Scrollable results container for the command palette.
- * Renders as a listbox for ARIA compliance.
+ * Scrollable results container for the command palette. Standalone composition
+ * renders as a listbox. Inside CommandPalette, listbox semantics are present
+ * only while selectable results exist; empty and pending states retain the same
+ * styled container without exposing an empty interactive popup.
  *
  * When used inside CommandPalette, automatically gets the correct
  * ID for aria-controls linking with the input.
@@ -84,14 +86,17 @@ export function CommandPaletteList({
   const t = useTranslator();
   const label = labelFromProps ?? t('@astryx.commandPalette.list.label');
   const ctx = useCommandPaletteContext();
+  // Inside CommandPalette the list is a listbox only while it holds selectable
+  // results; standalone composition is always a listbox.
+  const hasListbox = ctx ? ctx.selectableItems.length > 0 : true;
 
   return (
     <div
       ref={ref}
       {...props}
-      id={ctx?.listId}
-      role="listbox"
-      aria-label={label}
+      id={ctx?.listId ?? props.id}
+      role={hasListbox ? 'listbox' : undefined}
+      aria-label={hasListbox ? label : undefined}
       {...mergeProps(
         themeProps('command-palette-list'),
         stylex.props(styles.list, xstyle),