@astryxdesign/core 0.1.8 → 0.1.9-canary.08c278e

package/src/CheckboxList/CheckboxList.test.tsx

@@ -9,7 +9,7 @@
  * SYNC: When CheckboxList.tsx or CheckboxListItem.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {
   render,
   screen,
@@ -20,8 +20,16 @@ import {
 import userEvent from '@testing-library/user-event';
 import {CheckboxList} from './CheckboxList';
 import {CheckboxListItem} from './CheckboxListItem';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import {List} from '../List/List';
 
+// FieldStatus announces status messages through the persistent useAnnounce
+// singletons; remove them between tests so role/aria-live queries in this
+// file never match a leftover region.
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
+
 // Mock showPopover/hidePopover (not implemented in jsdom) so the tooltip layer
 // reflects its open state via a `popover-open` attribute the tests can assert.
 beforeEach(() => {
@@ -437,6 +445,71 @@ describe('CheckboxListItem standalone mode', () => {
   });
 });
 
+describe('CheckboxListItem accessible name', () => {
+  it('names the checkbox from a string label', () => {
+    render(
+      <CheckboxList label="Preferences" value={[]} onChange={() => {}}>
+        <CheckboxListItem label="Option A" value="a" />
+      </CheckboxList>,
+    );
+    expect(
+      screen.getByRole('checkbox', {name: 'Option A'}),
+    ).toBeInTheDocument();
+  });
+
+  it('names the checkbox from aria-label when the label is a ReactNode', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    render(
+      <CheckboxList label="Plans" value={[]} onChange={() => {}}>
+        <CheckboxListItem
+          label={
+            <span>
+              Pro plan <em>(recommended)</em>
+            </span>
+          }
+          aria-label="Pro plan"
+          value="pro"
+        />
+      </CheckboxList>,
+    );
+    expect(
+      screen.getByRole('checkbox', {name: 'Pro plan'}),
+    ).toBeInTheDocument();
+    // A named checkbox needs no dev guidance.
+    expect(warnSpy).not.toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+
+  it('warns once when a ReactNode label has no aria-label', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const richLabel = (
+      <span>
+        Pro plan <em>(recommended)</em>
+      </span>
+    );
+    const {rerender} = render(
+      <CheckboxList label="Plans" value={[]} onChange={() => {}}>
+        <CheckboxListItem label={richLabel} value="pro" />
+      </CheckboxList>,
+    );
+    // Falls back to the generic name, and tells the developer how to fix it.
+    expect(
+      screen.getByRole('checkbox', {name: 'Checkbox'}),
+    ).toBeInTheDocument();
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(String(warnSpy.mock.calls[0]?.[0])).toContain('aria-label');
+
+    // Warn once per item instance — re-renders don't repeat it.
+    rerender(
+      <CheckboxList label="Plans" value={['pro']} onChange={() => {}}>
+        <CheckboxListItem label={richLabel} value="pro" />
+      </CheckboxList>,
+    );
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    warnSpy.mockRestore();
+  });
+});
+
 describe('CheckboxListItem ARIA props', () => {
   it('conveys checked state via the inner checkbox, not aria-checked on the listitem', () => {
     render(
@@ -567,7 +640,7 @@ describe('CheckboxListItem ARIA props', () => {
     expect(changeAction).toHaveBeenCalledWith(['a']);
   });
 
-  it('forwards arbitrary aria attributes to the list item DOM element', () => {
+  it('forwards arbitrary aria attributes to the list item, but aria-label names the checkbox', () => {
     render(
       <List>
         <CheckboxListItem
@@ -578,8 +651,13 @@ describe('CheckboxListItem ARIA props', () => {
       </List>,
     );
     const item = screen.getByRole('listitem');
+    // Arbitrary aria-* still forward to the row...
     expect(item).toHaveAttribute('aria-describedby', 'help-text');
-    expect(item).toHaveAttribute('aria-label', 'custom label');
+    // ...but aria-label names the checkbox control, not the row.
+    expect(item).not.toHaveAttribute('aria-label');
+    expect(
+      screen.getByRole('checkbox', {name: 'custom label'}),
+    ).toBeInTheDocument();
   });
 
   describe('disabledMessage', () => {

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

@@ -296,7 +296,7 @@ const styles = stylex.create({
   copyButtonAbsolute: {
     position: 'absolute',
     top: spacingVars['--spacing-2'],
-    right: spacingVars['--spacing-2'],
+    insetInlineEnd: spacingVars['--spacing-2'],
   },
 });
 
@@ -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}