@astryxdesign/core 0.1.8 → 0.1.9

package/src/CheckboxList/CheckboxListItem.doc.mjs

@@ -7,14 +7,22 @@ export const docs = {
   subComponentOf: 'CheckboxList',
   displayName: 'Checkbox List Item',
   isHiddenFromOverview: true,
-  description: 'Individual checkbox item with label, description, and end content slot. Works in collection mode (inside CheckboxList) or standalone mode (inside List).',
+  description:
+    'Individual checkbox item with label, description, and end content slot. Works in collection mode (inside CheckboxList) or standalone mode (inside List).',
   props: [
     {
       name: 'label',
-      type: 'string',
-      description: 'Primary text label for the item.',
+      type: 'ReactNode',
+      description:
+        'Primary text label for the item. A plain string names the checkbox automatically; a rich (ReactNode) label should be paired with aria-label so screen readers get a concise name.',
       required: true,
     },
+    {
+      name: 'aria-label',
+      type: 'string',
+      description:
+        'Plain-text accessible name for the checkbox when label is a ReactNode. Applied to the checkbox control. Without it, rich-label items all announce as the generic "Checkbox" to screen readers.',
+    },
     {
       name: 'value',
       type: 'string',
@@ -69,13 +77,24 @@ export const docs = {
       description: 'Direct check handler (standalone mode only).',
     },
   ],
+  examples: [
+    {
+      label: 'Rich label with an accessible name',
+      code: `<CheckboxListItem
+  label={<span>Pro plan <Badge label="Recommended" /></span>}
+  aria-label="Pro plan"
+  value="pro"
+/>`,
+    },
+  ],
 };
 
 export const docsZh = {
   name: 'CheckboxListItem',
   isHiddenFromOverview: true,
   displayName: 'Checkbox List Item',
-  description: '单个复选框选项，包含标签、描述和尾部内容插槽。可在集合模式或独立模式下使用。',
+  description:
+    '单个复选框选项，包含标签、描述和尾部内容插槽。可在集合模式或独立模式下使用。',
   props: [
     {
       name: 'label',
@@ -83,6 +102,12 @@ export const docsZh = {
       description: '选项的主要文本标签。',
       required: true,
     },
+    {
+      name: 'aria-label',
+      type: 'string',
+      description:
+        '当 label 是 ReactNode 时，复选框的纯文本无障碍名称。缺少它时，富标签选项都会向屏幕阅读器播报为通用的 "Checkbox"。',
+    },
     {
       name: 'value',
       type: 'string',
@@ -128,9 +153,12 @@ export const docsDense = {
   name: 'CheckboxListItem',
   isHiddenFromOverview: true,
   displayName: 'Checkbox List Item',
-  description: 'Individual checkbox item w/ label, description, end content slot.',
+  description:
+    'Individual checkbox item w/ label, description, end content slot.',
   propDescriptions: {
     label: 'Primary text label for item.',
+    'aria-label':
+      'Plain-text checkbox name when label is a ReactNode. Without it, rich-label items all announce as "Checkbox".',
     value: 'Identity key (required inside CheckboxList).',
     description: 'Secondary text below label.',
     endContent: 'Content rendered after label area.',

package/src/CheckboxList/CheckboxListItem.tsx

@@ -22,6 +22,7 @@ import type {StyleXStyles} from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
 import {composeEventHandlers} from '../utils';
+import {useDevWarning} from '../hooks/useDevWarning';
 import {CheckboxInput} from '../CheckboxInput/CheckboxInput';
 import {ListItem} from '../List/ListItem';
 import {ListContext} from '../List/ListContext';
@@ -51,6 +52,25 @@ export interface CheckboxListItemProps extends BaseProps<HTMLLIElement> {
    * child components control their own text behavior).
    */
   label: ReactNode;
+  /**
+   * Plain-text accessible name for the checkbox when `label` is a ReactNode.
+   *
+   * A string `label` names the checkbox automatically. A rich (ReactNode)
+   * `label` cannot, so pass a concise string equivalent via the standard
+   * `aria-label` — otherwise the checkbox falls back to the generic name
+   * "Checkbox" and every rich-label item in a list announces identically to
+   * screen readers. Applied to the checkbox control, not the row.
+   *
+   * @example
+   * ```
+   * <CheckboxListItem
+   *   label={<span>Pro plan <Badge label="Recommended" /></span>}
+   *   aria-label="Pro plan"
+   *   value="pro"
+   * />
+   * ```
+   */
+  'aria-label'?: string;
   /**
    * Identity key for collection mode (REQUIRED inside CheckboxList).
    * Throws a runtime error if missing when used inside CheckboxList.
@@ -119,6 +139,7 @@ export interface CheckboxListItemProps extends BaseProps<HTMLLIElement> {
  */
 export function CheckboxListItem({
   label,
+  'aria-label': ariaLabel,
   value,
   description,
   endContent,
@@ -142,6 +163,25 @@ export function CheckboxListItem({
     );
   }
 
+  // Accessible name for the (visually hidden) checkbox label. A string
+  // `label` names it directly; a rich label needs `aria-label`.
+  const checkboxLabel =
+    ariaLabel ??
+    (typeof label === 'string'
+      ? label
+      : t('@astryx.checkboxList.item.checkbox'));
+
+  // Dev-time guardrail: a rich label without `aria-label` leaves the
+  // checkbox with the generic name "Checkbox".
+  useDevWarning(
+    'CheckboxListItem',
+    '`label` is a ReactNode, so the checkbox falls ' +
+      'back to the generic accessible name "Checkbox". Pass ' +
+      '`aria-label` with a concise string equivalent of the visible ' +
+      'label so screen readers can tell items apart.',
+    typeof label !== 'string' && ariaLabel == null,
+  );
+
   // Density from list context for checkbox sizing
   const listCtx = use(ListContext);
   const density = listCtx?.density ?? 'balanced';
@@ -226,11 +266,7 @@ export function CheckboxListItem({
       style={style}
       startContent={
         <CheckboxInput
-          label={
-            typeof label === 'string'
-              ? label
-              : t('@astryx.checkboxList.item.checkbox')
-          }
+          label={checkboxLabel}
           isLabelHidden
           value={resolvedChecked}
           onChange={() => handleToggle()}

package/src/ClickableCard/ClickableCard.doc.mjs

@@ -28,6 +28,7 @@ export const docs = {
     {name: 'children', type: 'ReactNode', description: 'Card content.'},
     {name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Inner padding.', default: '4'},
     {name: 'variant', type: "'default' | 'transparent' | 'muted' | 'blue' | 'cyan' | 'gray' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow'", description: 'Background color variant.', default: "'default'"},
+    {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: 'Resting shadow depth. Often raised to signal the whole card is clickable.', default: "'none'"},
     {name: 'width', type: 'SizeValue', description: 'Card width.'},
     {name: 'height', type: 'SizeValue', description: 'Card height.'},
     {name: 'maxWidth', type: 'SizeValue', description: 'Maximum card width.'},
@@ -73,6 +74,7 @@ export const docsDense = {
     isDisabled: 'disables card',
     padding: 'inner padding',
     variant: 'background color variant',
+    elevation: 'resting shadow depth: none|low|med|high; often raised to signal clickability',
     width: 'card width',
     height: 'card height',
     maxWidth: 'max card width',

package/src/ClickableCard/ClickableCard.test.tsx

@@ -106,4 +106,38 @@ describe('ClickableCard', () => {
     const link = screen.getByRole('link', {name: 'Disabled link'});
     expect(link).toHaveAttribute('aria-disabled', 'true');
   });
+
+  describe('elevation', () => {
+    it('forwards a distinct elevation class to the card for each level', () => {
+      const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {
+        const {container} = render(
+          <ClickableCard label="Card" elevation={elevation}>
+            Content
+          </ClickableCard>,
+        );
+        return container.firstElementChild!.className;
+      };
+      const classes = new Set([
+        classFor('none'),
+        classFor('low'),
+        classFor('med'),
+        classFor('high'),
+      ]);
+      expect(classes.size).toBe(4);
+    });
+
+    it('defaults to flat (elevation none)', () => {
+      const {container: def} = render(
+        <ClickableCard label="Card">Content</ClickableCard>,
+      );
+      const {container: none} = render(
+        <ClickableCard label="Card" elevation="none">
+          Content
+        </ClickableCard>,
+      );
+      expect(def.firstElementChild!.className).toBe(
+        none.firstElementChild!.className,
+      );
+    });
+  });
 });

package/src/ClickableCard/ClickableCard.tsx

@@ -14,6 +14,7 @@
  * - /apps/storybook/stories/ClickableCard.stories.tsx (storybook stories)
  * - /packages/cli/templates/blocks/components/Card/ClickableCardShowcase.tsx (showcase block)
  * - /packages/cli/templates/blocks/components/Card/ClickableCardWithNestedButton.tsx (block)
+ * - /packages/cli/templates/blocks/components/Card/ClickableCardElevated.tsx (block)
  *
  * Composes Card for all visual styling (radius, padding, variants,
  * container tokens, theming). Adds an interactive wrapper with
@@ -37,7 +38,7 @@ import {
   durationVars,
   easeVars,
 } from '../theme/tokens.stylex';
-import type {SizeValue, SpacingStep} from '../utils/types';
+import type {SizeValue, SpacingStep, Elevation} from '../utils/types';
 import {mergeProps, mergeRefs} from '../utils';
 import {Card} from '../Card/Card';
 import type {CardVariant} from '../Card/Card';
@@ -78,13 +79,13 @@ const styles = stylex.create({
       backgroundColor: 'transparent',
     },
     ':active::after': {
-      backgroundColor: 'color-mix(in srgb, currentColor 10%, transparent)',
+      backgroundColor: colorVars['--color-overlay-pressed'],
     },
   },
   hoverOnPointer: {
     '@media (hover: hover)': {
       ':hover::after': {
-        backgroundColor: 'color-mix(in srgb, currentColor 5%, transparent)',
+        backgroundColor: colorVars['--color-overlay-hover'],
       },
     },
   },
@@ -197,6 +198,13 @@ export interface ClickableCardProps extends BaseProps {
    */
   variant?: CardVariant;
 
+  /**
+   * Resting elevation — the shadow depth the card sits at. Often raised to
+   * signal that the whole card is clickable.
+   * @default 'none'
+   */
+  elevation?: Elevation;
+
   /** Width of the card. */
   width?: SizeValue;
 
@@ -253,6 +261,7 @@ export function ClickableCard({
   children,
   padding,
   variant = 'default',
+  elevation = 'none',
   width,
   height,
   maxWidth,
@@ -297,6 +306,7 @@ export function ClickableCard({
       maxWidth={maxWidth}
       padding={padding}
       variant={variant}
+      elevation={elevation}
       {...mergeProps(themeProps('clickable-card', {variant}), {
         className: classNameProp,
         style,

package/src/CodeBlock/CodeBlock.test.tsx

@@ -210,6 +210,62 @@ describe('CodeBlock', () => {
     expect(document.getElementById(controlsId as string)).not.toBeNull();
   });
 
+  it('makes the collapsed region inert so the scroll container is unreachable', () => {
+    render(
+      <CodeBlock
+        code={LONG_CODE}
+        language="javascript"
+        title="example"
+        isCollapsible
+      />,
+    );
+    const header = screen
+      .getAllByRole('button')
+      .find(el => el.hasAttribute('aria-expanded'))!;
+    const region = document.getElementById(
+      header.getAttribute('aria-controls') as string,
+    )!;
+    // Expanded: the region is not inert and the scroll container is reachable.
+    expect(region).not.toHaveAttribute('inert');
+
+    fireEvent.click(header);
+    expect(header).toHaveAttribute('aria-expanded', 'false');
+    // Collapsed: the wrapper is inert, so the keyboard-focusable scroll
+    // container (tabIndex=0) inside it drops out of the tab order and the
+    // accessibility tree instead of remaining an invisible tab stop.
+    expect(region).toHaveAttribute('inert');
+    const scrollContainer = screen.getByRole('group');
+    expect(scrollContainer.closest('[inert]')).toBe(region);
+  });
+
+  it('restores focusability of the scroll container after expanding again', () => {
+    render(
+      <CodeBlock
+        code={LONG_CODE}
+        language="javascript"
+        title="example"
+        isCollapsible
+      />,
+    );
+    const header = screen
+      .getAllByRole('button')
+      .find(el => el.hasAttribute('aria-expanded'))!;
+    const region = document.getElementById(
+      header.getAttribute('aria-controls') as string,
+    )!;
+    // Collapse, then expand again.
+    fireEvent.click(header);
+    expect(region).toHaveAttribute('inert');
+    fireEvent.click(header);
+    expect(header).toHaveAttribute('aria-expanded', 'true');
+    // Expanded again: inert is removed and the scroll container is a
+    // keyboard-focusable group once more.
+    expect(region).not.toHaveAttribute('inert');
+    const scrollContainer = screen.getByRole('group');
+    expect(scrollContainer.closest('[inert]')).toBeNull();
+    expect(scrollContainer).toHaveAttribute('tabindex', '0');
+  });
+
   it('applies a per-instance syntax theme via the syntaxTheme prop', () => {
     const {container} = render(
       <CodeBlock

package/src/CodeBlock/CodeBlock.tsx

@@ -807,7 +807,9 @@ export function CodeBlock({
         e.stopPropagation();
         void handleCopy();
       }}
-      aria-label={copied ? t('@astryx.codeBlock.copied') : t('@astryx.codeBlock.copyCode')}
+      aria-label={
+        copied ? t('@astryx.codeBlock.copied') : t('@astryx.codeBlock.copyCode')
+      }
       {...stylex.props(
         styles.copyButton,
         !showHeader && styles.copyButtonAbsolute,
@@ -923,6 +925,12 @@ export function CodeBlock({
       {canCollapse ? (
         <div
           id={regionId}
+          // While collapsed, the region is only hidden visually (0fr grid
+          // row); inert also removes it from the tab order and accessibility
+          // tree so keyboard users cannot Tab into the invisible scroll
+          // container (tabIndex=0). aria-controls pointing at an inert
+          // element remains a valid, resolvable reference.
+          inert={isCollapsed ? true : undefined}
           {...stylex.props(
             styles.collapseGrid,
             isCollapsed && styles.collapseGridCollapsed,

package/src/CommandPalette/CommandPalette.doc.mjs

@@ -145,6 +145,7 @@ export const docs = {
       {className: 'astryx-command-palette-empty'},
       {className: 'astryx-command-palette-footer'},
       {className: 'astryx-command-palette-group'},
+      {className: 'astryx-command-palette-group-heading'},
       {className: 'astryx-command-palette-input'},
       {className: 'astryx-command-palette-item'},
       {className: 'astryx-command-palette-list'},

package/src/CommandPalette/CommandPalette.tsx

@@ -268,6 +268,7 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
   label: labelFromProps,
   width = 640,
   maxHeight = 480,
+  ...rest
 }: CommandPaletteProps<T>) {
   const t = useTranslator();
   const label = labelFromProps ?? t('@astryx.commandPalette.label');
@@ -527,7 +528,8 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
       width={width}
       maxHeight={maxHeight}
       purpose="info"
-      aria-label={label}>
+      aria-label={label}
+      {...rest}>
       <CommandPaletteContext value={contextValue}>
         <Layout
           defaultHasDividers

package/src/CommandPalette/CommandPaletteGroup.test.tsx

@@ -9,6 +9,8 @@
 import {describe, it, expect} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {CommandPaletteGroup} from './CommandPaletteGroup';
+import {defineTheme} from '../theme/defineTheme';
+import {generateThemeCSSFlat} from '../theme/generateThemeRules';
 
 describe('CommandPaletteGroup', () => {
   it('renders heading', () => {
@@ -51,4 +53,73 @@ describe('CommandPaletteGroup', () => {
       'true',
     );
   });
+
+  // ===========================================================================
+  // Heading theme target
+  // ===========================================================================
+
+  describe('heading theme target', () => {
+    it('renders the astryx-command-palette-group-heading target on the heading', () => {
+      render(
+        <CommandPaletteGroup heading="Suggestions">
+          <div>Item</div>
+        </CommandPaletteGroup>,
+      );
+      const heading = screen.getByText('Suggestions');
+
+      // The root carries `astryx-command-palette-group`; this is the stable
+      // handle on the heading itself, so a theme can style just the heading
+      // without a fragile structural selector.
+      expect(heading).toHaveClass('astryx-command-palette-group-heading');
+    });
+
+    it('keeps the heading target distinct from the group root target', () => {
+      render(
+        <CommandPaletteGroup heading="Suggestions">
+          <div>Item</div>
+        </CommandPaletteGroup>,
+      );
+      const root = screen.getByRole('group');
+      const heading = screen.getByText('Suggestions');
+
+      expect(root).toHaveClass('astryx-command-palette-group');
+      expect(root).not.toHaveClass('astryx-command-palette-group-heading');
+      expect(heading).not.toHaveClass('astryx-command-palette-group');
+    });
+
+    it('leaves the heading decorative (additive target only)', () => {
+      // The target adds a class and nothing else — the heading stays
+      // aria-hidden so grouping remains announced via the root's aria-label.
+      render(
+        <CommandPaletteGroup heading="Suggestions">
+          <div>Item</div>
+        </CommandPaletteGroup>,
+      );
+      expect(screen.getByText('Suggestions')).toHaveAttribute(
+        'aria-hidden',
+        'true',
+      );
+    });
+
+    it('exposes command-palette-group-heading as a themeable defineTheme target', () => {
+      // The generated CSS proves the target is reachable by a theme: jsdom
+      // cannot resolve the @layer cascade, so the DOM-class assertions above
+      // and this generation assertion together cover the seam.
+      const theme = defineTheme({
+        name: 'command-palette-group-heading-test',
+        components: {
+          'command-palette-group-heading': {
+            base: {
+              paddingBlock: 'var(--spacing-2)',
+              fontWeight: 'var(--font-weight-bold)',
+            },
+          },
+        },
+      });
+      const css = generateThemeCSSFlat(theme);
+      expect(css).toContain('.astryx-command-palette-group-heading {');
+      expect(css).toContain('padding-block: var(--spacing-2)');
+      expect(css).toContain('font-weight: var(--font-weight-bold)');
+    });
+  });
 });

package/src/CommandPalette/CommandPaletteGroup.tsx

@@ -90,7 +90,18 @@ export function CommandPaletteGroup({
         style,
       )}
       {...props}>
-      <div aria-hidden="true" {...stylex.props(styles.heading)}>
+      <div
+        aria-hidden="true"
+        {...mergeProps(
+          // Stable theme target for the group heading text. The root carries
+          // `astryx-command-palette-group`, but the heading itself had no
+          // handle, so a theme could only reach it through a fragile structural
+          // selector. This adds an `astryx-command-palette-group-heading` class
+          // so `defineTheme` can scope overrides (e.g. heading typography) to
+          // the heading alone.
+          themeProps('command-palette-group-heading'),
+          stylex.props(styles.heading),
+        )}>
         {heading}
       </div>
       {children}

package/src/CommandPalette/CommandPaletteInput.doc.mjs

@@ -7,7 +7,8 @@ export const docs = {
   subComponentOf: 'CommandPalette',
   displayName: 'Command Palette Input',
   isHiddenFromOverview: true,
-  description: 'Search input slot. Auto-focuses on mount. Wires to command palette context when used inside CommandPalette.',
+  description:
+    'Search input slot. Auto-focuses on mount. Wires to command palette context when used inside CommandPalette.',
   props: [
     {
       name: 'placeholder',
@@ -15,16 +16,24 @@ export const docs = {
       description: 'Placeholder text for the input.',
       default: "'Search...'",
     },
+    {
+      name: 'label',
+      type: 'string',
+      description:
+        'Accessible label for the combobox input, announced by screen readers. Falls back to the placeholder text when omitted.',
+    },
     {
       name: 'hasAutoFocus',
       type: 'boolean',
-      description: 'Auto-focus the input when mounted. Automatically disabled when inside an inline command palette.',
+      description:
+        'Auto-focus the input when mounted. Automatically disabled when inside an inline command palette.',
       default: 'true',
     },
     {
       name: 'endContent',
       type: 'ReactNode',
-      description: 'Content rendered at the trailing end of the input, after the spinner. Use for clear buttons or keyboard shortcut hints.',
+      description:
+        'Content rendered at the trailing end of the input, after the spinner. Use for clear buttons or keyboard shortcut hints.',
       slotElements: [
         {
           __element: 'Icon',
@@ -44,17 +53,20 @@ export const docs = {
     {
       name: 'value',
       type: 'string',
-      description: 'Search value. When omitted inside CommandPalette, reads from context.',
+      description:
+        'Search value. When omitted inside CommandPalette, reads from context.',
     },
     {
       name: 'onValueChange',
       type: '(value: string) => void',
-      description: 'Called when search value changes. When omitted inside CommandPalette, writes to context.',
+      description:
+        'Called when search value changes. When omitted inside CommandPalette, writes to context.',
     },
     {
       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: {
@@ -69,9 +81,11 @@ export const docsZh = {
   name: 'CommandPaletteInput',
   isHiddenFromOverview: true,
   displayName: 'Command Palette Input',
-  description: '搜索输入插槽。挂载时自动聚焦。在 CommandPalette 内使用时连接到上下文。',
+  description:
+    '搜索输入插槽。挂载时自动聚焦。在 CommandPalette 内使用时连接到上下文。',
   propDescriptions: {
     placeholder: '输入框的占位文本。',
+    label: '组合框输入的无障碍标签，供屏幕阅读器朗读。省略时回退到占位文本。',
     hasAutoFocus: '挂载时自动聚焦输入框。内联命令面板中自动禁用。',
     endContent: '渲染在输入框末尾的内容，位于加载指示器之后。',
     value: '搜索值。在 CommandPalette 内省略时从上下文读取。',
@@ -84,13 +98,16 @@ export const docsDense = {
   name: 'CommandPaletteInput',
   isHiddenFromOverview: true,
   displayName: 'Command Palette Input',
-  description: 'search input; auto-focus on mount; wires to context inside CommandPalette',
+  description:
+    'search input; auto-focus on mount; wires to context inside CommandPalette',
   propDescriptions: {
     placeholder: 'input placeholder text',
+    label: 'accessible label for the combobox; falls back to placeholder',
     hasAutoFocus: 'auto-focus on mount; auto-disabled in inline mode',
     endContent: 'trailing content after spinner',
     value: 'search value; reads context when omitted inside palette',
-    onValueChange: 'called on change; writes context when omitted inside palette',
+    onValueChange:
+      'called on change; writes context when omitted inside palette',
     xstyle: 'StyleX layout styles; must be stylex.create() value',
   },
 };

package/src/CommandPalette/CommandPaletteInput.test.tsx

@@ -32,6 +32,40 @@ describe('CommandPaletteInput', () => {
     expect(screen.getByRole('combobox')).toBeInTheDocument();
   });
 
+  it('has an accessible name by default', () => {
+    render(<CommandPaletteInput />);
+    expect(screen.getByRole('combobox')).toHaveAttribute(
+      'aria-label',
+      'Search…',
+    );
+  });
+
+  it('uses the label prop as the accessible name', () => {
+    render(<CommandPaletteInput label="Search commands" />);
+    const input = screen.getByRole('combobox');
+    expect(input).toHaveAttribute('aria-label', 'Search commands');
+    // The label prop does not affect the visible placeholder
+    expect(input).toHaveAttribute('placeholder', 'Search…');
+  });
+
+  it('falls back to a custom placeholder for the accessible name', () => {
+    render(<CommandPaletteInput placeholder="Type a command..." />);
+    expect(screen.getByRole('combobox')).toHaveAttribute(
+      'aria-label',
+      'Type a command...',
+    );
+  });
+
+  it('lets a consumer-passed aria-label override the default', () => {
+    render(
+      <CommandPaletteInput label="Search commands" aria-label="Custom name" />,
+    );
+    expect(screen.getByRole('combobox')).toHaveAttribute(
+      'aria-label',
+      'Custom name',
+    );
+  });
+
   it('calls onValueChange when typing', () => {
     const handleChange = vi.fn();
     render(<CommandPaletteInput onValueChange={handleChange} />);

package/src/CommandPalette/CommandPaletteInput.tsx

@@ -109,6 +109,13 @@ export interface CommandPaletteInputProps extends Omit<
    */
   placeholder?: string;
 
+  /**
+   * Accessible label for the combobox input, announced by screen readers.
+   * Falls back to the placeholder text (`'Search…'` by default), since a
+   * placeholder alone is not a reliable accessible name.
+   */
+  label?: string;
+
   /**
    * Whether to auto-focus the input when mounted.
    * @default true
@@ -149,6 +156,7 @@ export function CommandPaletteInput({
   value: controlledValue,
   onValueChange,
   placeholder: placeholderFromProps,
+  label,
   hasAutoFocus = true,
   endContent,
   onChange,
@@ -215,6 +223,9 @@ export function CommandPaletteInput({
             ? ctx.getItemId(ctx.highlightedIndex)
             : undefined
         }
+        // A placeholder alone is not a reliable accessible name; give the
+        // combobox an explicit one (consumer aria-label via rest props wins).
+        aria-label={label ?? placeholder}
         placeholder={placeholder}
         value={value}
         data-autofocus={effectiveAutoFocus || undefined}