@astryxdesign/core 0.1.7 → 0.1.8-canary.c5fa19b

package/src/DropdownMenu/DropdownMenuRadioItem.tsx

@@ -0,0 +1,232 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file DropdownMenuRadioItem.tsx
+ * @input React, stylex, Item + Icon + DropdownMenu context + tokens from core
+ * @output DropdownMenuRadioItem — a single option in a radio group.
+ * @position Sub-component; must be used inside a DropdownMenuRadioGroup.
+ *
+ * A menu item representing one option in a single-select group
+ * (role="menuitemradio"). The row owns the role and aria-checked; there is no
+ * nested native <input> (per the WAI-ARIA menuitemradio pattern). Selection
+ * state + onChange come from DropdownMenuRadioGroupContext. Keyboard nav +
+ * Enter/Space activation come from the parent DropdownMenu.
+ *
+ * The round radio visual (circle + center dot) is decorative (aria-hidden) —
+ * the row owns the checked state. Its size is derived from the menu's item size
+ * and it swaps to the inline-end of the row on coarse-pointer (touch) devices
+ * via CSS `order`. The dot is a shaped element, not an icon (a filled circle
+ * has no registry glyph).
+ */
+
+import {useCallback, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {renderIconSlot, type IconType} from '../Icon';
+import {Item} from '../Item';
+import {useDropdownMenuContext} from './DropdownMenuContext';
+import {
+  colorVars,
+  spacingVars,
+  durationVars,
+  easeVars,
+  borderVars,
+} from '../theme/tokens.stylex';
+import {mergeProps, themeProps} from '../utils';
+import type {BaseProps} from '../BaseProps';
+import {useDropdownMenuRadioGroupContext} from './DropdownMenuContext';
+
+const styles = stylex.create({
+  root: {
+    width: '100%',
+    borderRadius: `max(0px, calc(var(--_dropdown-menu-radius, ${spacingVars['--spacing-2']}) - var(--_dropdown-menu-padding, ${spacingVars['--spacing-1']})))`,
+    color: colorVars['--color-text-primary'],
+    backgroundColor: {
+      default: 'transparent',
+      ':focus': colorVars['--color-overlay-hover'],
+      ':hover': colorVars['--color-overlay-hover'],
+    },
+    cursor: 'pointer',
+    outline: 'none',
+  },
+  disabled: {
+    opacity: 0.5,
+    cursor: 'not-allowed',
+  },
+  // Rendered in Item's `marker` slot as a raw flex child. On touch it moves to
+  // the inline-end of the row via `order`.
+  circle: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexShrink: 0,
+    boxSizing: 'border-box',
+    borderWidth: borderVars['--border-width'],
+    borderStyle: 'solid',
+    borderRadius: '50%',
+    transitionProperty: 'background-color, border-color',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    order: {
+      default: 0,
+      '@media (pointer: coarse)': 1,
+    },
+    marginInlineStart: {
+      default: 0,
+      '@media (pointer: coarse)': 'auto',
+    },
+  },
+  unchecked: {
+    borderColor: colorVars['--color-border-emphasized'],
+    backgroundColor: colorVars['--color-background-surface'],
+  },
+  checked: {
+    borderColor: colorVars['--color-accent'],
+    backgroundColor: colorVars['--color-accent'],
+  },
+  dot: {
+    borderRadius: '50%',
+    backgroundColor: colorVars['--color-on-accent'],
+  },
+});
+
+const circleSizeStyles = stylex.create({
+  sm: {width: 18, height: 18},
+  md: {width: 22, height: 22},
+});
+
+const dotSizeStyles = stylex.create({
+  sm: {width: 6, height: 6},
+  md: {width: 8, height: 8},
+});
+
+export interface DropdownMenuRadioItemProps extends Omit<
+  BaseProps,
+  'role' | 'aria-checked' | 'tabIndex'
+> {
+  /**
+   * The value this item represents within its group. The group's `value`
+   * matches against this to determine the checked state.
+   */
+  value: string;
+  /**
+   * Primary label text identifying the option.
+   */
+  label: ReactNode;
+  /**
+   * Secondary description text displayed below the label.
+   */
+  description?: ReactNode;
+  /**
+   * Icon to display before the label. Accepts a semantic icon name (see
+   * `npx astryx docs icons`) or a rendered node.
+   */
+  icon?: ReactNode | IconType;
+  /**
+   * Whether this individual radio item is disabled. Disabled items stay
+   * focusable (via `aria-disabled`) so they remain discoverable by keyboard
+   * and assistive technology, but selection is blocked.
+   * @default false
+   */
+  isDisabled?: boolean;
+  /**
+   * Content to render after the label and description, such as a badge or
+   * metadata.
+   */
+  endContent?: ReactNode;
+}
+
+/**
+ * A single option in a DropdownMenuRadioGroup (role="menuitemradio").
+ *
+ * @example
+ * ```
+ * <DropdownMenuRadioGroup value={sort} onChange={setSort} aria-label="Sort by">
+ *   <DropdownMenuRadioItem value="newest" label="Newest" />
+ *   <DropdownMenuRadioItem value="oldest" label="Oldest" icon="clock" />
+ * </DropdownMenuRadioGroup>
+ * ```
+ */
+export function DropdownMenuRadioItem({
+  value,
+  label,
+  description,
+  icon,
+  isDisabled = false,
+  endContent,
+  xstyle,
+  className,
+  style,
+  ...rest
+}: DropdownMenuRadioItemProps) {
+  const menuCtx = useDropdownMenuContext();
+  const groupCtx = useDropdownMenuRadioGroupContext();
+  if (!groupCtx) {
+    throw new Error(
+      'DropdownMenuRadioItem must be used within a DropdownMenuRadioGroup',
+    );
+  }
+  const menuSize = menuCtx?.menuSize ?? 'md';
+  const controlSize = menuSize === 'sm' ? 'sm' : 'md';
+  const isChecked = groupCtx.value === value;
+
+  const handleClick = useCallback(() => {
+    if (isDisabled) {
+      return;
+    }
+    groupCtx.onChange(value);
+    if (groupCtx.hasCloseOnSelect) {
+      menuCtx?.closeMenu();
+    }
+  }, [isDisabled, groupCtx, value, menuCtx]);
+
+  return (
+    <Item
+      {...rest}
+      role="menuitemradio"
+      aria-checked={isChecked}
+      tabIndex={isDisabled ? undefined : -1}
+      marker={
+        <span
+          aria-hidden="true"
+          {...mergeProps(
+            themeProps('dropdown-menu-radio', {
+              size: controlSize,
+              checked: isChecked ? 'checked' : null,
+              disabled: isDisabled ? 'disabled' : null,
+            }),
+            stylex.props(
+              styles.circle,
+              circleSizeStyles[controlSize],
+              isChecked ? styles.checked : styles.unchecked,
+            ),
+          )}>
+          {isChecked && (
+            <span {...stylex.props(styles.dot, dotSizeStyles[controlSize])} />
+          )}
+        </span>
+      }
+      startContent={
+        icon
+          ? renderIconSlot(icon, {size: 'sm', color: 'secondary'})
+          : undefined
+      }
+      label={label}
+      description={description}
+      endContent={endContent}
+      onClick={handleClick}
+      isDisabled={isDisabled}
+      xstyle={[styles.root, isDisabled && styles.disabled, xstyle]}
+      {...mergeProps(themeProps('dropdown-menu-item', {size: menuSize}), {
+        className,
+        style,
+      })}
+    />
+  );
+}
+
+DropdownMenuRadioItem.displayName = 'DropdownMenuRadioItem';

package/src/DropdownMenu/DropdownMenuSelectable.test.tsx

@@ -0,0 +1,163 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DropdownMenuSelectable.test.tsx
+ * @input vitest, @testing-library/react, DropdownMenu + selectable items
+ * @output Unit tests for DropdownMenuCheckboxItem / RadioGroup / RadioItem (#3829)
+ */
+
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {DropdownMenu} from './DropdownMenu';
+import {DropdownMenuCheckboxItem} from './DropdownMenuCheckboxItem';
+import {DropdownMenuRadioGroup} from './DropdownMenuRadioGroup';
+import {DropdownMenuRadioItem} from './DropdownMenuRadioItem';
+
+beforeEach(() => {
+  HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+    this.setAttribute('popover-open', '');
+    const event = new Event('toggle', {bubbles: false});
+    Object.defineProperty(event, 'newState', {value: 'open'});
+    this.dispatchEvent(event);
+  });
+  HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+    this.removeAttribute('popover-open');
+    const event = new Event('toggle', {bubbles: false});
+    Object.defineProperty(event, 'newState', {value: 'closed'});
+    this.dispatchEvent(event);
+  });
+  const originalMatches = HTMLElement.prototype.matches;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (HTMLElement.prototype as any).matches = function (
+    selector: string,
+  ): boolean {
+    if (selector === ':popover-open') {
+      return this.hasAttribute('popover-open');
+    }
+    return originalMatches.call(this, selector);
+  };
+});
+
+describe('DropdownMenuCheckboxItem', () => {
+  it('renders role menuitemcheckbox and reflects checked state', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'View'}}>
+        <DropdownMenuCheckboxItem label="Show archived" value={true} />
+      </DropdownMenu>,
+    );
+    await user.click(screen.getByRole('button', {name: /View/}));
+    expect(
+      screen.getByRole('menuitemcheckbox', {
+        name: /Show archived/,
+        hidden: true,
+      }),
+    ).toHaveAttribute('aria-checked', 'true');
+  });
+
+  it('calls onChange with the toggled value on click', async () => {
+    const user = userEvent.setup();
+    const onChangeSpy = vi.fn();
+    render(
+      <DropdownMenu button={{label: 'View'}}>
+        <DropdownMenuCheckboxItem
+          label="Show archived"
+          value={false}
+          onChange={onChangeSpy}
+        />
+      </DropdownMenu>,
+    );
+    await user.click(screen.getByRole('button', {name: /View/}));
+    await user.click(
+      screen.getByRole('menuitemcheckbox', {
+        name: /Show archived/,
+        hidden: true,
+      }),
+    );
+    expect(onChangeSpy).toHaveBeenCalledWith(true);
+  });
+
+  it('does not toggle when disabled', async () => {
+    const user = userEvent.setup();
+    const onChangeSpy = vi.fn();
+    render(
+      <DropdownMenu button={{label: 'View'}}>
+        <DropdownMenuCheckboxItem
+          label="Show archived"
+          value={false}
+          onChange={onChangeSpy}
+          isDisabled
+        />
+      </DropdownMenu>,
+    );
+    await user.click(screen.getByRole('button', {name: /View/}));
+    const item = screen.getByRole('menuitemcheckbox', {
+      name: /Show archived/,
+      hidden: true,
+    });
+    expect(item).toHaveAttribute('aria-disabled', 'true');
+    await user.click(item);
+    expect(onChangeSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe('DropdownMenuRadioGroup / RadioItem', () => {
+  it('renders a named group with radios reflecting the selected value', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Sort'}}>
+        <DropdownMenuRadioGroup
+          value="newest"
+          onChange={() => {}}
+          aria-label="Sort by">
+          <DropdownMenuRadioItem value="newest" label="Newest" />
+          <DropdownMenuRadioItem value="oldest" label="Oldest" />
+        </DropdownMenuRadioGroup>
+      </DropdownMenu>,
+    );
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}),
+    ).toHaveAttribute('aria-checked', 'true');
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Oldest', hidden: true}),
+    ).toHaveAttribute('aria-checked', 'false');
+    expect(
+      screen.getByRole('group', {name: 'Sort by', hidden: true}),
+    ).toBeInTheDocument();
+  });
+
+  it('calls onChange with the selected value', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(
+      <DropdownMenu button={{label: 'Sort'}}>
+        <DropdownMenuRadioGroup
+          value="newest"
+          onChange={onChange}
+          aria-label="Sort by">
+          <DropdownMenuRadioItem value="newest" label="Newest" />
+          <DropdownMenuRadioItem value="oldest" label="Oldest" />
+        </DropdownMenuRadioGroup>
+      </DropdownMenu>,
+    );
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    await user.click(
+      screen.getByRole('menuitemradio', {name: 'Oldest', hidden: true}),
+    );
+    expect(onChange).toHaveBeenCalledWith('oldest');
+  });
+
+  it('throws when a radio item is used outside a group', () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    expect(() =>
+      render(
+        <DropdownMenu button={{label: 'Sort'}}>
+          <DropdownMenuRadioItem value="x" label="X" />
+        </DropdownMenu>,
+      ),
+    ).toThrow(/DropdownMenuRadioGroup/);
+    spy.mockRestore();
+  });
+});

package/src/DropdownMenu/index.ts

@@ -18,7 +18,27 @@ export {
   type DropdownMenuOption,
 } from './DropdownMenu';
 
+export {DropdownMenuItem, type DropdownMenuItemProps} from './DropdownMenuItem';
+
+// Selectable items — checkbox (independent) and radio (single-select group).
+export {
+  DropdownMenuCheckboxItem,
+  type DropdownMenuCheckboxItemProps,
+} from './DropdownMenuCheckboxItem';
+export {
+  DropdownMenuRadioGroup,
+  type DropdownMenuRadioGroupProps,
+} from './DropdownMenuRadioGroup';
+export {
+  DropdownMenuRadioItem,
+  type DropdownMenuRadioItemProps,
+} from './DropdownMenuRadioItem';
+
+// Menu-coordination context — public so consumers can build custom menu items
+// that read the menu size / close the menu.
 export {
-  DropdownMenuItem,
-  type DropdownMenuItemProps,
-} from './DropdownMenuItem';
+  DropdownMenuContext,
+  useDropdownMenuContext,
+  type DropdownMenuContextValue,
+  type DropdownMenuSize,
+} from './DropdownMenuContext';

package/src/DropdownMenu/menuItemRoles.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file menuItemRoles.ts
+ * @output Shared menu-item role set + focus selector.
+ * @position Internal; used by DropdownMenu and ContextMenu so their
+ *   roving-focus, typeahead, and Enter/Space activation stay in sync.
+ *
+ * Includes the selectable items (menuitemradio/menuitemcheckbox) alongside
+ * plain menuitem so checkbox/radio rows are reachable by arrow keys, typeahead,
+ * and Enter/Space — not just role="menuitem".
+ */
+
+export const MENU_ITEM_ROLES: ReadonlySet<string> = new Set([
+  'menuitem',
+  'menuitemradio',
+  'menuitemcheckbox',
+]);
+
+export const MENU_ITEM_SELECTOR: string = [...MENU_ITEM_ROLES]
+  .map(role => `[role="${role}"]:not([aria-disabled="true"])`)
+  .join(',');

package/src/Field/Field.doc.mjs

@@ -95,7 +95,7 @@ export const docs = {
     {
       name: 'labelIcon',
       type: 'IconType',
-      description: 'Icon to display before the label text. See `npx astryx docs icons` for valid semantic names.',
+      description: 'Icon to display before the label text. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'labelTooltip',

package/src/Field/FieldLabel.doc.mjs

@@ -48,7 +48,7 @@ export const docs = {
     {
       name: 'labelIcon',
       type: 'IconType',
-      description: 'Icon before the label text. See `npx astryx docs icons` for valid semantic names.',
+      description: 'Icon before the label text. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'labelTooltip',

package/src/Icon/Icon.doc.mjs

@@ -34,6 +34,11 @@ export const docs = {
       description: 'Icon size.',
       default: "'md'",
     },
+    {
+      name: 'label',
+      type: 'string',
+      description: 'Accessible name for a MEANINGFUL, standalone icon (a status glyph or icon-only indicator with no adjacent text). Setting it exposes the icon to screen readers as role="img" with this text as the accessible name (aria-label) and removes the default aria-hidden. Omit it (default) for decorative icons and the icon stays hidden from assistive tech (aria-hidden="true"). This is the accessible-name / alt-text prop for icons — one prop instead of manually setting aria-label + role + aria-hidden. An empty string is treated as decorative. Do not set it when an interactive parent (Button, IconButton, link) already names the control.',
+    },
   ],
   theming: {
     targets: [
@@ -45,6 +50,7 @@ export const docs = {
     bestPractices: [
       { guidance: true, description: 'Use semantic icon names when available; they adapt to theme changes automatically.' },
       { guidance: true, description: 'Pair icons with text labels for accessibility; icon-only elements need an accessible label.' },
+      { guidance: true, description: 'For a meaningful standalone icon (no adjacent text), give it an accessible name via the `label` prop — it sets role="img" + aria-label and unhides the icon.' },
       { guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },
       { guidance: true, description: 'Be mindful of context; decorative icons in compact components can distract rather than help.' },
       { guidance: false, description: 'Use icons as the sole means of conveying meaning; always provide a text alternative.' },
@@ -79,6 +85,11 @@ export const docsZh = {
       description: '图标尺寸。',
       default: "'md'",
     },
+    {
+      name: 'label',
+      type: 'string',
+      description: '有含义的独立图标的可访问名称（无相邻文字的状态图标或纯图标指示器）。设置后会将图标以 role="img" 暴露给辅助技术，并以该文本作为可访问名称（aria-label），同时移除默认的 aria-hidden。省略（默认）用于装饰性图标，图标对辅助技术保持隐藏（aria-hidden="true"）。空字符串按装饰性处理。当交互式父元素（Button、IconButton、链接）已命名该控件时请勿设置。',
+    },
   ],
   theming: {
     targets: [
@@ -123,5 +134,6 @@ export const docsDense = {
     icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
     color: 'Color variant mapped to Astryx icon color tokens.',
     size: 'Icon size.',
+    label: 'Accessible name for a meaningful, standalone icon. Sets role="img" + aria-label and drops the default aria-hidden. Omit (default) for decorative icons (stays aria-hidden). Empty string = decorative. The accessible-name/alt-text prop for icons.',
   },
 };

package/src/Icon/Icon.test.tsx

@@ -96,6 +96,52 @@ describe('Icon', () => {
     expect(screen.getByTestId('icon')).toBeInTheDocument();
   });
 
+  it('sizes component-mode icons in rem so they scale with root font-size', () => {
+    const sizes = {
+      xsm: '0.75rem',
+      sm: '1rem',
+      md: '1.25rem',
+      lg: '1.5rem',
+    } as const;
+    for (const [size, expected] of Object.entries(sizes)) {
+      const {unmount} = render(
+        <Icon
+          icon={TestIcon}
+          size={size as keyof typeof sizes}
+          data-testid="icon"
+        />,
+      );
+      const style = getComputedStyle(screen.getByTestId('icon'));
+      expect(style.width).toBe(expected);
+      expect(style.height).toBe(expected);
+      unmount();
+    }
+  });
+
+  it('sizes registry (string-mode) icons in rem, including fontSize', () => {
+    const sizes = {
+      xsm: '0.75rem',
+      sm: '1rem',
+      md: '1.25rem',
+      lg: '1.5rem',
+    } as const;
+    for (const [size, expected] of Object.entries(sizes)) {
+      const {unmount} = render(
+        <Icon
+          icon="check"
+          size={size as keyof typeof sizes}
+          data-testid="icon"
+        />,
+      );
+      const style = getComputedStyle(screen.getByTestId('icon'));
+      expect(style.width).toBe(expected);
+      expect(style.height).toBe(expected);
+      // fontSize is expressed in rem so 1em-based registry icons scale too.
+      expect(style.fontSize).toBe(expected);
+      unmount();
+    }
+  });
+
   it('forwards ref correctly', () => {
     const ref = vi.fn();
     render(<Icon icon={TestIcon} ref={ref} />);
@@ -137,4 +183,100 @@ describe('Icon', () => {
     expect(icon).toHaveAttribute('aria-label', 'Done');
     expect(icon).toHaveAttribute('aria-hidden', 'false');
   });
+
+  describe('label (accessible name)', () => {
+    it('makes a component-mode icon meaningful: role="img" + aria-label, no aria-hidden', () => {
+      render(<Icon icon={TestIcon} label="Completed" data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('role', 'img');
+      expect(icon).toHaveAttribute('aria-label', 'Completed');
+      expect(icon).not.toHaveAttribute('aria-hidden');
+    });
+
+    it('makes a string-mode (registry) icon meaningful: role="img" + aria-label, no aria-hidden', () => {
+      render(<Icon icon="check" label="Completed" data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('role', 'img');
+      expect(icon).toHaveAttribute('aria-label', 'Completed');
+      expect(icon).not.toHaveAttribute('aria-hidden');
+    });
+
+    it('keeps the decorative default when label is omitted (component mode)', () => {
+      render(<Icon icon={TestIcon} data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+      expect(icon).not.toHaveAttribute('role');
+      expect(icon).not.toHaveAttribute('aria-label');
+    });
+
+    it('keeps the decorative default when label is omitted (string mode)', () => {
+      render(<Icon icon="check" data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+      expect(icon).not.toHaveAttribute('role');
+      expect(icon).not.toHaveAttribute('aria-label');
+    });
+
+    it('treats an empty string label as decorative (component mode)', () => {
+      render(<Icon icon={TestIcon} label="" data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+      expect(icon).not.toHaveAttribute('role');
+      expect(icon).not.toHaveAttribute('aria-label');
+    });
+
+    it('treats an empty string label as decorative (string mode)', () => {
+      render(<Icon icon="check" label="" data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+      expect(icon).not.toHaveAttribute('role');
+      expect(icon).not.toHaveAttribute('aria-label');
+    });
+
+    it('lets an explicit aria-hidden win over label (component mode)', () => {
+      render(
+        <Icon icon={TestIcon} label="Close" aria-hidden data-testid="icon" />,
+      );
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+    });
+
+    it('lets an explicit aria-hidden win over label (string mode)', () => {
+      render(
+        <Icon icon="check" label="Close" aria-hidden data-testid="icon" />,
+      );
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+    });
+
+    it('lets an explicit aria-label override the label-derived name (component mode)', () => {
+      render(
+        <Icon
+          icon={TestIcon}
+          label="Close"
+          aria-label="Dismiss"
+          data-testid="icon"
+        />,
+      );
+      expect(screen.getByTestId('icon')).toHaveAttribute(
+        'aria-label',
+        'Dismiss',
+      );
+    });
+
+    it('lets an explicit role override the label-derived role (string mode)', () => {
+      render(
+        <Icon
+          icon="check"
+          label="Close"
+          role="presentation"
+          data-testid="icon"
+        />,
+      );
+      expect(screen.getByTestId('icon')).toHaveAttribute(
+        'role',
+        'presentation',
+      );
+    });
+  });
 });