@astryxdesign/core 0.1.7 → 0.1.8-canary.08a0957

package/src/Icon/Icon.tsx

@@ -111,51 +111,64 @@ const colorStyles = stylex.create({
 /**
  * Size styles for direct SVG icon components.
  * Uses width/height only — SVG components handle their own viewBox scaling.
+ *
+ * Sizes are expressed in `rem` (relative to the root font-size) so icons scale
+ * in step with text when the document font-size changes, matching the rest of
+ * the design system's rem-based type scale. Values are the px-equivalents at a
+ * 16px root: 12px → 0.75rem, 16px → 1rem, 20px → 1.25rem, 24px → 1.5rem.
  */
 const sizeStyles = stylex.create({
   xsm: {
-    width: 12,
-    height: 12,
+    width: '0.75rem',
+    height: '0.75rem',
   },
   sm: {
-    width: 16,
-    height: 16,
+    width: '1rem',
+    height: '1rem',
   },
   md: {
-    width: 20,
-    height: 20,
+    width: '1.25rem',
+    height: '1.25rem',
   },
   lg: {
-    width: 24,
-    height: 24,
+    width: '1.5rem',
+    height: '1.5rem',
   },
 });
 
 /**
  * Size styles for string-based (registry) icons.
  * Includes fontSize so that 1em-based icons from the registry scale correctly.
+ *
+ * Expressed in `rem` for the same reason as {@link sizeStyles} — icons track the
+ * root font-size instead of being locked to absolute pixels.
  */
 const spanSizeStyles = stylex.create({
+  /* eslint-disable @astryx/no-hardcoded-styles -- fontSize here sizes 1em-based
+     registry SVGs to the icon box; icons use their own 12/16/20/24 scale, not
+     the 14px-anchored textSizeVars type scale. Values are rem so icons track
+     the root font-size. */
   xsm: {
-    width: 12,
-    height: 12,
-    fontSize: 12,
+    width: '0.75rem',
+    height: '0.75rem',
+    fontSize: '0.75rem',
   },
   sm: {
-    width: 16,
-    height: 16,
-    fontSize: 16,
+    width: '1rem',
+    height: '1rem',
+    fontSize: '1rem',
   },
   md: {
-    width: 20,
-    height: 20,
-    fontSize: 20,
+    width: '1.25rem',
+    height: '1.25rem',
+    fontSize: '1.25rem',
   },
   lg: {
-    width: 24,
-    height: 24,
-    fontSize: 24,
+    width: '1.5rem',
+    height: '1.5rem',
+    fontSize: '1.5rem',
   },
+  /* eslint-enable @astryx/no-hardcoded-styles */
 });
 
 // =============================================================================
@@ -194,13 +207,57 @@ export interface IconProps extends Omit<
   color?: IconColor;
   /**
    * The size of the icon.
-   * - 'xsm': 12px
-   * - 'sm': 16px
-   * - 'md': 20px
-   * - 'lg': 24px
+   * - 'xsm': 0.75rem (12px at a 16px root)
+   * - 'sm': 1rem (16px at a 16px root)
+   * - 'md': 1.25rem (20px at a 16px root)
+   * - 'lg': 1.5rem (24px at a 16px root)
    * @default 'md'
    */
   size?: IconSize;
+  /**
+   * Accessible name for the icon. Set this only when the icon is MEANINGFUL on
+   * its own — a standalone status glyph or an icon-only indicator with no
+   * adjacent text conveying the same information. Providing it exposes the icon
+   * to assistive tech as `role="img"` with this string as the accessible name
+   * (via `aria-label`) and drops the default `aria-hidden="true"`.
+   *
+   * Omit it (the default) for decorative icons — the common case, e.g. an icon
+   * beside a text label — and the icon stays hidden from assistive tech
+   * (`aria-hidden="true"`). An empty string (`''`) is treated the same as
+   * omitting it (decorative), since an empty accessible name is meaningless.
+   *
+   * Don't set `label` when an interactive parent (Button, IconButton, link)
+   * already names the control — that produces a duplicate announcement.
+   *
+   * @example
+   * ```
+   * // Meaningful, standalone icon
+   * <Icon icon="success" label="Completed" />
+   *
+   * // Decorative icon (default) — omit label
+   * <Icon icon="search" />
+   * ```
+   */
+  label?: string;
+}
+
+/**
+ * Derives the ARIA attributes for an icon from its `label` prop.
+ *
+ * - Non-empty `label` → meaningful image: `role="img"` + `aria-label`, and no
+ *   `aria-hidden` (an `aria-hidden` element is removed from the accessibility
+ *   tree, so its accessible name would be ignored).
+ * - Omitted or empty `label` → decorative default: `aria-hidden="true"`.
+ *
+ * The result is spread BEFORE `{...props}` in both render modes so an explicit
+ * `aria-hidden` / `role` / `aria-label` from the consumer always wins.
+ */
+function getIconA11yProps(
+  label: string | undefined,
+): {role: 'img'; 'aria-label': string} | {'aria-hidden': 'true'} {
+  return label != null && label !== ''
+    ? {role: 'img', 'aria-label': label}
+    : {'aria-hidden': 'true'};
 }
 
 // =============================================================================
@@ -219,9 +276,14 @@ export function Icon({
   icon,
   color = 'inherit',
   size = 'md',
+  label,
   ref,
   ...props
 }: IconProps) {
+  // Derive ARIA from `label`: decorative (aria-hidden) by default, or a
+  // meaningful image (role="img" + aria-label) when `label` is non-empty.
+  const a11yProps = getIconA11yProps(label);
+
   // String mode: resolve from icon registry, wrap in styled span
   if (typeof icon === 'string') {
     return (
@@ -229,6 +291,7 @@ export function Icon({
         name={icon}
         color={color}
         size={size}
+        a11yProps={a11yProps}
         spanProps={props}
       />
     );
@@ -239,7 +302,10 @@ export function Icon({
   return (
     <IconComponent
       ref={ref}
-      aria-hidden="true"
+      // Derived a11y (decorative default or meaningful `label`) is spread
+      // BEFORE {...props} so an explicit aria-hidden/role/aria-label from the
+      // consumer still wins as an escape hatch.
+      {...a11yProps}
       {...mergeProps(
         themeProps('icon', {size, color}),
         stylex.props(styles.root, colorStyles[color], sizeStyles[size]),
@@ -266,11 +332,13 @@ function IconFromRegistry({
   name,
   color,
   size,
+  a11yProps,
   spanProps,
 }: {
   name: IconName;
   color: IconColor;
   size: IconSize;
+  a11yProps: {role: 'img'; 'aria-label': string} | {'aria-hidden': 'true'};
   spanProps?: Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'>;
 }) {
   const resolvedIcon = getIcon(name);
@@ -281,11 +349,11 @@ function IconFromRegistry({
 
   return (
     <span
-      // Decorative by default, but placed BEFORE the prop spread so consumers
-      // can override it (e.g. `aria-hidden={false}` + `role="img"` +
-      // `aria-label`) to expose a meaningful standalone icon. This matches
-      // component-mode Icon, which already sets aria-hidden before its spread.
-      aria-hidden="true"
+      // Derived a11y — decorative (aria-hidden) by default, or a meaningful
+      // image (role="img" + aria-label) when `label` is set. Placed BEFORE the
+      // prop spread so consumers can still override it with explicit
+      // aria-hidden/role/aria-label. This mirrors component-mode Icon.
+      {...a11yProps}
       {...(spanProps as React.HTMLAttributes<HTMLSpanElement>)}
       {...mergeProps(
         themeProps('icon', {size, color}),

package/src/Item/Item.doc.mjs

@@ -28,7 +28,7 @@ export const docs = {
       props: [
         {name: 'label', type: 'ReactNode', description: 'Primary text identifying this item. Accepts string (auto-truncated) or ReactNode (for rich content).', required: true},
         {name: 'marker', type: 'ReactNode', description: 'Marker rendered before startContent as a direct flex child. Use for list bullets/counters that need custom baseline alignment.'},
-        {name: 'startContent', type: 'ReactNode', description: 'Content rendered before the label/description area, such as an icon, avatar, or checkbox.', slotElements: [{__element: 'Avatar', props: {name: 'Ada Lovelace', size: 'xsmall'}}, {__element: 'Icon', props: {icon: 'info', size: 'sm', color: 'secondary'}}]},
+        {name: 'startContent', type: 'ReactNode', description: 'Content rendered before the label/description area, such as an icon, avatar, or checkbox.', slotElements: [{__element: 'Avatar', props: {name: 'Ada Lovelace', size: 'sm'}}, {__element: 'Icon', props: {icon: 'info', size: 'sm', color: 'secondary'}}]},
         {name: 'description', type: 'ReactNode', description: 'Secondary text: subtitle, description, or supporting info.'},
         {name: 'endContent', type: 'ReactNode', description: 'Content rendered after the label/description area, such as badges, metadata, timestamps, or action buttons.', slotElements: [{__element: 'Badge', props: {label: 3}}, {__element: 'Text', props: {color: 'secondary'}, children: '2h ago'}]},
         {name: 'as', type: "'div' | 'li' | 'span'", description: 'HTML element to render as the root.', default: "'div'"},

package/src/MobileNav/MobileNav.tsx

@@ -29,6 +29,7 @@
 import {
   useCallback,
   useEffect,
+  useId,
   useMemo,
   useRef,
   useState,
@@ -295,6 +296,10 @@ export function MobileNav({
   // Read from AppShell context as fallback
   const appShellMobile = useAppShellMobile();
   const isOpen = isOpenProp ?? appShellMobile.isMobileNavOpen;
+  // Share the id from AppShell context so the toggle's aria-controls resolves to
+  // this drawer; fall back to a locally generated id when used standalone.
+  const fallbackId = useId();
+  const dialogId = appShellMobile.mobileNavId || fallbackId;
   const onOpenChange = useMemo(
     () =>
       onOpenChangeProp ??
@@ -411,6 +416,7 @@ export function MobileNav({
   return (
     <dialog
       ref={mergeRefs(ref, dialogRef)}
+      id={dialogId}
       {...mergeProps(
         themeProps('mobile-nav', {side: resolvedSide}),
         stylex.props(
@@ -425,7 +431,12 @@ export function MobileNav({
       )}
       {...rest}
       data-testid={testId}
-      aria-label={label ?? (typeof header === 'string' ? header : t('@astryx.mobileNav.navigation'))}
+      aria-label={
+        label ??
+        (typeof header === 'string'
+          ? header
+          : t('@astryx.mobileNav.navigation'))
+      }
       onClick={composeEventHandlers(onClickProp, handleDialogClick)}
       onCancel={handleCancel}>
       {/* Drawer panel — tabIndex so showModal() focuses the drawer, not the close button */}

package/src/MobileNav/MobileNavToggle.test.tsx

@@ -0,0 +1,116 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MobileNavToggle.test.tsx
+ * @input Uses vitest, @testing-library/react, AppShell + SideNav
+ * @output Unit tests for MobileNavToggle ARIA wiring
+ * @position Testing; validates MobileNavToggle.tsx exposes aria-expanded and
+ *   aria-controls so screen-reader users know the drawer state and target.
+ *
+ * SYNC: When MobileNavToggle.tsx changes, update tests to match new behavior
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeAll,
+  beforeEach,
+  afterEach,
+} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {AppShell} from '../AppShell/AppShell';
+import {SideNav, SideNavItem, SideNavSection} from '../SideNav';
+
+// jsdom doesn't implement showModal/close on <dialog>, so we mock them
+beforeAll(() => {
+  HTMLDialogElement.prototype.showModal =
+    HTMLDialogElement.prototype.showModal ||
+    function (this: HTMLDialogElement) {
+      this.setAttribute('open', '');
+    };
+  HTMLDialogElement.prototype.close =
+    HTMLDialogElement.prototype.close ||
+    function (this: HTMLDialogElement) {
+      this.removeAttribute('open');
+    };
+});
+
+class MockResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+vi.stubGlobal('ResizeObserver', MockResizeObserver);
+
+function createMockMatchMedia(matches: boolean) {
+  return {
+    matches,
+    media: '',
+    onchange: null,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  };
+}
+
+beforeEach(() => {
+  // Below the breakpoint so the mobile nav (and its toggle) render.
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockReturnValue(createMockMatchMedia(true)),
+  );
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function TestShell() {
+  return (
+    <AppShell
+      sideNav={
+        <SideNav>
+          <SideNavSection title="Test" isHeaderHidden>
+            <SideNavItem label="Home" />
+          </SideNavSection>
+        </SideNav>
+      }
+      mobileNav={{breakpoint: 'md'}}>
+      <div>Content</div>
+    </AppShell>
+  );
+}
+
+describe('MobileNavToggle ARIA wiring', () => {
+  it('exposes aria-expanded="false" when the drawer is closed', () => {
+    render(<TestShell />);
+
+    const toggle = screen.getByRole('button', {name: /open navigation/i});
+    expect(toggle).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('exposes aria-expanded="true" after opening the drawer', () => {
+    render(<TestShell />);
+
+    const toggle = screen.getByRole('button', {name: /open navigation/i});
+    fireEvent.click(toggle);
+    expect(toggle).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it('references the nav drawer via aria-controls that resolves to the dialog', () => {
+    render(<TestShell />);
+
+    const toggle = screen.getByRole('button', {name: /open navigation/i});
+    const controls = toggle.getAttribute('aria-controls');
+    expect(controls).toBeTruthy();
+
+    const target = document.getElementById(controls!);
+    expect(target).not.toBeNull();
+    expect(target).toBe(screen.getAllByRole('dialog', {hidden: true})[0]);
+    expect(target?.tagName).toBe('DIALOG');
+  });
+});

package/src/MobileNav/MobileNavToggle.tsx

@@ -69,7 +69,13 @@ export function MobileNavToggle({
 }: MobileNavToggleProps) {
   const t = useTranslator();
   const label = labelFromProps ?? t('@astryx.mobileNav.toggle.open');
-  const {isMobile, isMobileNavEnabled, toggleMobileNav} = useAppShellMobile();
+  const {
+    isMobile,
+    isMobileNavEnabled,
+    isMobileNavOpen,
+    mobileNavId,
+    toggleMobileNav,
+  } = useAppShellMobile();
 
   // Don't render above the breakpoint or when mobile nav is disabled
   if (!isMobile || !isMobileNavEnabled) {
@@ -83,6 +89,8 @@ export function MobileNavToggle({
       label={label}
       icon={children ?? <Icon icon="menu" color="inherit" />}
       onClick={toggleMobileNav}
+      aria-expanded={isMobileNavOpen}
+      aria-controls={mobileNavId || undefined}
       data-testid={testId ?? 'mobile-nav-toggle'}
       xstyle={xstyle}
       className={className}

package/src/MultiSelector/MultiSelector.doc.mjs

@@ -99,7 +99,8 @@ export const docs = {
         {
           name: 'hasSearch',
           type: 'boolean',
-          description: 'Whether to show a search input for filtering options.',
+          description:
+            'Whether to show a search input for filtering options. As the user types, the match count (or "No results found") is announced to screen readers via a polite live region.',
         },
         {
           name: 'searchPlaceholder',
@@ -239,7 +240,8 @@ export const docsZh = {
         hasSearch: '是否显示用于过滤选项的搜索输入。',
         searchPlaceholder: '搜索输入的占位文本。',
         isDisabled: '禁用选择器。',
-        htmlName: '用于表单提交的 HTML name 属性。为每个已选值渲染一个隐藏输入，类似原生多选。',
+        htmlName:
+          '用于表单提交的 HTML name 属性。为每个已选值渲染一个隐藏输入，类似原生多选。',
         disabledMessage:
           '解释选择器被禁用的原因。与 isDisabled 一起使用时，悬停/键盘聚焦时显示工具提示，并通过 aria-disabled 保持触发器可聚焦（仍无法激活）。请使用此属性，而不是用 Tooltip 包裹被禁用的选择器。',
         isLabelHidden: '视觉上隐藏标签同时保持其可访问性。',

package/src/MultiSelector/MultiSelector.test.tsx

@@ -554,6 +554,82 @@ describe('MultiSelector', () => {
     expect(screen.getByText('No results found')).toBeInTheDocument();
   });
 
+  describe('result announcements', () => {
+    it('announces the match count politely while searching', async () => {
+      const user = userEvent.setup();
+      render(
+        <MultiSelector
+          label="Fruit"
+          options={defaultOptions}
+          value={EMPTY_VALUE}
+          onChange={() => {}}
+          hasSearch
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Fruit'}));
+      // "an" matches Banana and Orange.
+      await user.type(screen.getByRole('combobox', h), 'an');
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('2 results');
+      });
+    });
+
+    it('announces the singular form when one option matches', async () => {
+      const user = userEvent.setup();
+      render(
+        <MultiSelector
+          label="Fruit"
+          options={defaultOptions}
+          value={EMPTY_VALUE}
+          onChange={() => {}}
+          hasSearch
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Fruit'}));
+      // "app" matches only Apple. Anchored so it cannot pass on "1 results".
+      await user.type(screen.getByRole('combobox', h), 'app');
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent(/^1 result$/);
+      });
+    });
+
+    it('announces "No results found" when nothing matches', async () => {
+      const user = userEvent.setup();
+      render(
+        <MultiSelector
+          label="Fruit"
+          options={defaultOptions}
+          value={EMPTY_VALUE}
+          onChange={() => {}}
+          hasSearch
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Fruit'}));
+      await user.type(screen.getByRole('combobox', h), 'xyz');
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('No results found');
+      });
+    });
+
+    it('does not announce results until the user searches', async () => {
+      const user = userEvent.setup();
+      render(
+        <MultiSelector
+          label="Fruit"
+          options={defaultOptions}
+          value={EMPTY_VALUE}
+          onChange={() => {}}
+          hasSearch
+        />,
+      );
+      // Popover closed: nothing announced.
+      expect(politeRegion()?.textContent ?? '').toBe('');
+      // Open with an empty query: still nothing announced.
+      await user.click(screen.getByRole('button', {name: 'Fruit'}));
+      expect(politeRegion()?.textContent ?? '').toBe('');
+    });
+  });
+
   it('renders with description', () => {
     render(
       <MultiSelector
@@ -1072,7 +1148,9 @@ describe('MultiSelector', () => {
           />
         </form>,
       );
-      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+      expect([
+        ...new FormData(container.querySelector('form')!).keys(),
+      ]).toEqual([]);
     });
   });
 });

package/src/MultiSelector/MultiSelector.tsx

@@ -562,6 +562,23 @@ export interface MultiSelectorProps<
   'data-testid'?: string;
 }
 
+// Case-insensitive substring filter over the selectable options. Shared by the
+// `filteredItems` memo (rendering) and the search-change handler, which needs
+// the count for the *next* query synchronously to announce it exactly once per
+// keystroke rather than reacting to state in an effect.
+function filterOptionsByQuery(
+  items: MultiSelectorOptionData[],
+  query: string,
+): MultiSelectorOptionData[] {
+  if (!query) {
+    return items;
+  }
+  const q = query.toLowerCase();
+  return items.filter(item =>
+    (item.label ?? item.value).toLowerCase().includes(q),
+  );
+}
+
 /**
  * A multi-select dropdown component with checkboxes for choosing
  * multiple items from a list of options.
@@ -692,15 +709,10 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   );
 
   // Filter items by search query
-  const filteredItems = useMemo(() => {
-    if (!searchQuery) {
-      return selectableItems;
-    }
-    const query = searchQuery.toLowerCase();
-    return selectableItems.filter(item =>
-      (item.label ?? item.value).toLowerCase().includes(query),
-    );
-  }, [selectableItems, searchQuery]);
+  const filteredItems = useMemo(
+    () => filterOptionsByQuery(selectableItems, searchQuery),
+    [selectableItems, searchQuery],
+  );
 
   // Single source of truth for item order. Both the hook (keyboard navigation)
   // and renderOptions (DOM rendering) consume this list — no independent sorting.
@@ -772,8 +784,11 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   const handleLayerHide = useCallback(() => {
     setSearchQuery('');
     setSelectedAtOpen(null);
+    // Clear any lingering result count when the popover closes so stale status
+    // text does not linger in the a11y tree.
+    announce('');
     triggerRef.current?.focus();
-  }, []);
+  }, [announce]);
 
   const popover = usePopover({
     hasLightDismiss: true,
@@ -793,6 +808,30 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     // eslint-disable-next-line @eslint-react/exhaustive-deps -- mount-only: isDefaultOpen is not reactive
   }, []);
 
+  // Announce the filtered result count from the query-change handler (matching
+  // BaseTypeahead) rather than a reactive effect: computing the count for the
+  // next query here fires the announcement exactly once per keystroke and does
+  // not re-speak on unrelated re-renders. Reuses the announce instance shared
+  // with the selection-count announcements above.
+  const handleSearchChange = useCallback(
+    (event: React.ChangeEvent<HTMLInputElement>) => {
+      const nextQuery = event.target.value;
+      setSearchQuery(nextQuery);
+      if (nextQuery.length === 0) {
+        // Emptying the query clears the region rather than announcing a count.
+        announce('');
+        return;
+      }
+      const count = filterOptionsByQuery(selectableItems, nextQuery).length;
+      announce(
+        count === 0
+          ? 'No results found'
+          : `${count} result${count === 1 ? '' : 's'}`,
+      );
+    },
+    [announce, selectableItems],
+  );
+
   // Handle toggle
   // Clear all selected values. Shared by the clear button and the keyboard
   // Delete/Backspace path so clearing is reachable without a mouse.
@@ -1041,7 +1080,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
           aria-label={t('@astryx.multiSelector.searchOptions')}
           type="text"
           value={searchQuery}
-          onChange={e => setSearchQuery(e.target.value)}
+          onChange={handleSearchChange}
           onKeyDown={e => {
             // Arrow keys navigate options; Enter toggles; Escape/Tab close.
             // Space and Home/End are left to the input (type a space / move
@@ -1067,6 +1106,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     listboxId,
     searchQuery,
     searchPlaceholder,
+    handleSearchChange,
     onKeyDown,
     popover.isOpen,
     highlightedIndex,

package/src/NumberInput/NumberInput.doc.mjs

@@ -82,12 +82,12 @@ export const docs = {
     {
       name: 'startIcon',
       type: 'IconType',
-      description: 'Icon to display at the start of the input. See `npx astryx docs icons` for valid semantic names.',
+      description: 'Icon to display at the start of the input. See `astryx docs icons` for valid semantic names.',
     },
     {
       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: 'status',

package/src/NumberInput/NumberInput.tsx

@@ -311,8 +311,7 @@ type NumberInputPropsClearable = NumberInputPropsBase & {
 };
 
 export type NumberInputProps =
-  | NumberInputPropsNonClearable
-  | NumberInputPropsClearable;
+  NumberInputPropsNonClearable | NumberInputPropsClearable;
 
 /**
  * Parse and validate a string input as a number.