@astryxdesign/core 0.1.8 → 0.1.9

package/src/Item/Item.test.tsx

@@ -31,18 +31,13 @@ describe('Item', () => {
   });
 
   it('renders marker', () => {
-    render(
-      <Item label="Item" marker={<span data-testid="marker">•</span>} />,
-    );
+    render(<Item label="Item" marker={<span data-testid="marker">•</span>} />);
     expect(screen.getByTestId('marker')).toBeInTheDocument();
   });
 
   it('renders startContent', () => {
     render(
-      <Item
-        label="Item"
-        startContent={<span data-testid="avatar">A</span>}
-      />,
+      <Item label="Item" startContent={<span data-testid="avatar">A</span>} />,
     );
     expect(screen.getByTestId('avatar')).toBeInTheDocument();
   });
@@ -255,12 +250,7 @@ describe('Item', () => {
   it('does not fire onClick when disabled item is clicked', async () => {
     const onClick = vi.fn();
     render(
-      <Item
-        label="Disabled"
-        onClick={onClick}
-        isDisabled
-        data-testid="item"
-      />,
+      <Item label="Disabled" onClick={onClick} isDisabled data-testid="item" />,
     );
     const item = screen.getByTestId('item');
     item.dispatchEvent(new MouseEvent('click', {bubbles: true}));
@@ -276,14 +266,46 @@ describe('Item', () => {
   // Selected state
   // ===========================================================================
 
-  it('applies aria-selected when isSelected', () => {
+  it('conveys selection via aria-current on the default div root', () => {
+    // aria-selected is invalid ARIA on a generic div (axe: aria-allowed-attr),
+    // so selection is exposed via aria-current, which is valid on any element.
     render(<Item label="Selected" isSelected data-testid="item" />);
-    expect(screen.getByTestId('item')).toHaveAttribute('aria-selected', 'true');
+    const item = screen.getByTestId('item');
+    expect(item).not.toHaveAttribute('aria-selected');
+    expect(item).toHaveAttribute('aria-current', 'true');
   });
 
-  it('does not apply aria-selected when not selected', () => {
-    render(<Item label="Not Selected" data-testid="item" />);
-    expect(screen.getByTestId('item')).not.toHaveAttribute('aria-selected');
+  it('applies aria-selected (not aria-current) when the role permits it', () => {
+    render(
+      <Item label="Selected" isSelected role="option" data-testid="item" />,
+    );
+    const item = screen.getByTestId('item');
+    expect(item).toHaveAttribute('aria-selected', 'true');
+    // A permitted role uses aria-selected; aria-current would be redundant.
+    expect(item).not.toHaveAttribute('aria-current');
+  });
+
+  it('falls back to aria-current when the role does not permit aria-selected', () => {
+    render(
+      <Item label="Selected" isSelected role="menuitem" data-testid="item" />,
+    );
+    const item = screen.getByTestId('item');
+    expect(item).not.toHaveAttribute('aria-selected');
+    expect(item).toHaveAttribute('aria-current', 'true');
+  });
+
+  it('applies neither aria-selected nor aria-current when not selected', () => {
+    render(<Item label="Not Selected" role="option" data-testid="item" />);
+    const item = screen.getByTestId('item');
+    expect(item).not.toHaveAttribute('aria-selected');
+    expect(item).not.toHaveAttribute('aria-current');
+  });
+
+  it('lets a consumer-provided aria-current win over the selection default', () => {
+    render(
+      <Item label="Step" isSelected aria-current="step" data-testid="item" />,
+    );
+    expect(screen.getByTestId('item')).toHaveAttribute('aria-current', 'step');
   });
 
   // ===========================================================================

package/src/Item/Item.tsx

@@ -131,7 +131,12 @@ export interface ItemProps extends BaseProps<HTMLElement> {
   isHighlighted?: boolean;
 
   /**
-   * Selected state.
+   * Selected state. Always applies the selected visual styling. When `role`
+   * permits it (option, tab, row, gridcell, columnheader, rowheader, treeitem)
+   * the state is exposed as `aria-selected`; otherwise (e.g. a listitem or a
+   * bare div, where `aria-selected` is invalid ARIA) it falls back to
+   * `aria-current="true"` so assistive tech is still told which item is
+   * selected. A consumer-provided `aria-current` always wins.
    * @default false
    */
   isSelected?: boolean;
@@ -148,6 +153,24 @@ export interface ItemProps extends BaseProps<HTMLElement> {
   'data-testid'?: string;
 }
 
+// =============================================================================
+// Constants
+// =============================================================================
+
+/**
+ * Roles on which WAI-ARIA permits the aria-selected attribute.
+ * https://www.w3.org/TR/wai-aria-1.2/#aria-selected
+ */
+const ARIA_SELECTED_ROLES = new Set([
+  'option',
+  'tab',
+  'row',
+  'gridcell',
+  'columnheader',
+  'rowheader',
+  'treeitem',
+]);
+
 // =============================================================================
 // Styles
 // =============================================================================
@@ -346,6 +369,11 @@ export function Item({
   // handles keyboard access. Skip the invisible button/anchor and put
   // onClick directly on the root element instead.
   const hasParentRole = role != null;
+  // aria-selected is only valid on selectable roles (option, tab, treeitem,
+  // grid cells). On the default div/li root the attribute is invalid ARIA
+  // (axe: aria-allowed-attr), so selection stays visual-only there — callers
+  // that need selection semantics pass a permitted role.
+  const allowsAriaSelected = role != null && ARIA_SELECTED_ROLES.has(role);
 
   const isStringLabel = typeof label === 'string';
   const isStringDescription = typeof description === 'string';
@@ -471,7 +499,15 @@ export function Item({
     <Component
       ref={ref as React.Ref<never>}
       {...restProps}
-      aria-selected={isSelected || undefined}
+      aria-selected={(allowsAriaSelected && isSelected) || undefined}
+      // aria-selected is invalid on roles that don't permit it (listitem, a
+      // bare div, etc.). For those, convey selection via aria-current — valid
+      // on any element — so the state still reaches AT. Written after
+      // {...restProps} so it must defer to a consumer-provided aria-current.
+      aria-current={
+        restProps['aria-current'] ??
+        (isSelected && !allowsAriaSelected ? true : undefined)
+      }
       aria-disabled={isDisabled || undefined}
       {...mergeProps(
         themeProps('item', {density, align}),

package/src/Layer/useLayer.tsx

@@ -100,6 +100,12 @@ export interface ContextRenderProps {
    * non-hashed selector for the layer.
    */
   role?: string;
+  /**
+   * Accessible name applied to the popover container via `aria-label`.
+   * Pair with `role` so layers with a named role (e.g. `'dialog'`) expose a
+   * proper name to assistive technology.
+   */
+  'aria-label'?: string;
   /**
    * StyleX styles for the popover container.
    */
@@ -525,6 +531,7 @@ export function useLayer(
         alignment = 'center',
         positioning = 'anchor',
         role,
+        'aria-label': ariaLabel,
         xstyle,
         className: extraClassName,
         style: extraStyle,
@@ -561,6 +568,7 @@ export function useLayer(
           ref={popoverRefCallback}
           id={id}
           role={role}
+          aria-label={ariaLabel}
           popover={lightDismiss ? 'auto' : 'manual'}
           className={combinedClassName}
           style={{...stylexResult.style, ...anchorStyle, ...extraStyle}}

package/src/List/List.test.tsx

@@ -436,11 +436,7 @@ describe('List', () => {
   it('sets target on anchor when provided', () => {
     const {container} = render(
       <List>
-        <ListItem
-          label="External"
-          href="https://example.com"
-          target="_blank"
-        />
+        <ListItem label="External" href="https://example.com" target="_blank" />
       </List>,
     );
     const anchor = container.querySelector('a');
@@ -500,17 +496,21 @@ describe('List', () => {
   // Selected state
   // ===========================================================================
 
-  it('applies aria-selected when isSelected', () => {
+  it('conveys selection via aria-current when isSelected', () => {
+    // aria-selected is not permitted on an li (role listitem, axe:
+    // aria-allowed-attr), so selection is exposed via aria-current — valid on
+    // any element — so screen-reader users are still told which item is chosen.
     const {container} = render(
       <List>
         <ListItem label="Selected" isSelected onClick={() => {}} />
       </List>,
     );
     const item = container.querySelector('.astryx-item');
-    expect(item).toHaveAttribute('aria-selected', 'true');
+    expect(item).not.toHaveAttribute('aria-selected');
+    expect(item).toHaveAttribute('aria-current', 'true');
   });
 
-  it('does not apply aria-selected when not selected', () => {
+  it('applies neither aria-selected nor aria-current when not selected', () => {
     const {container} = render(
       <List>
         <ListItem label="Not Selected" />
@@ -518,6 +518,7 @@ describe('List', () => {
     );
     const li = container.querySelector('li');
     expect(li).not.toHaveAttribute('aria-selected');
+    expect(li).not.toHaveAttribute('aria-current');
   });
 
   // ===========================================================================

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

@@ -10,7 +10,13 @@
  */
 
 import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
-import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import {
+  render,
+  screen,
+  fireEvent,
+  waitFor,
+  within,
+} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {MultiSelector} from './MultiSelector';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
@@ -360,6 +366,30 @@ describe('MultiSelector', () => {
     expect(activeId).toBeTruthy();
   });
 
+  it('End/Home jump the highlight to the last/first option (non-search)', async () => {
+    const user = userEvent.setup();
+    render(
+      <MultiSelector
+        label="Fruit"
+        options={defaultOptions}
+        value={[]}
+        onChange={() => {}}
+      />,
+    );
+
+    const trigger = screen.getByRole('combobox');
+    await user.click(trigger);
+    const options = screen.getAllByRole('option', h);
+
+    await user.keyboard('{End}');
+    expect(trigger).toHaveAttribute(
+      'aria-activedescendant',
+      options[options.length - 1].id,
+    );
+    await user.keyboard('{Home}');
+    expect(trigger).toHaveAttribute('aria-activedescendant', options[0].id);
+  });
+
   it('toggles item with Enter key', async () => {
     const user = userEvent.setup();
     const onChange = vi.fn();
@@ -535,6 +565,65 @@ describe('MultiSelector', () => {
     expect(options).toHaveLength(1);
   });
 
+  it('PageDown/PageUp jump the highlight to the last/first filtered option', async () => {
+    const user = userEvent.setup();
+    render(
+      <MultiSelector
+        label="Fruit"
+        options={defaultOptions}
+        value={[]}
+        onChange={() => {}}
+        hasSearch
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Fruit'}));
+    const searchInput = screen.getByRole('combobox', h);
+    // Filter to Banana and Orange so "last" means last *visible* option.
+    await user.type(searchInput, 'an');
+    const options = screen.getAllByRole('option', h);
+    expect(options).toHaveLength(2);
+
+    await user.keyboard('{PageDown}');
+    expect(searchInput).toHaveAttribute(
+      'aria-activedescendant',
+      options[options.length - 1].id,
+    );
+    await user.keyboard('{PageUp}');
+    expect(searchInput).toHaveAttribute('aria-activedescendant', options[0].id);
+  });
+
+  it('Home/End move the search caret, not the option highlight', async () => {
+    const user = userEvent.setup();
+    render(
+      <MultiSelector
+        label="Fruit"
+        options={defaultOptions}
+        value={[]}
+        onChange={() => {}}
+        hasSearch
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Fruit'}));
+    const searchInput = screen.getByRole<HTMLInputElement>('combobox', h);
+    await user.type(searchInput, 'an');
+    expect(searchInput.selectionStart).toBe(2);
+    const activeBefore = searchInput.getAttribute('aria-activedescendant');
+    // Home/End stay on the input for caret movement (APG editable combobox);
+    // the option highlight must not move.
+    await user.keyboard('{Home}');
+    expect(searchInput.selectionStart).toBe(0);
+    expect(searchInput.getAttribute('aria-activedescendant')).toBe(
+      activeBefore,
+    );
+    await user.keyboard('{End}');
+    expect(searchInput.selectionStart).toBe(2);
+    expect(searchInput.getAttribute('aria-activedescendant')).toBe(
+      activeBefore,
+    );
+  });
+
   it('shows empty state when search has no results', async () => {
     const user = userEvent.setup();
     render(
@@ -551,7 +640,85 @@ describe('MultiSelector', () => {
     const searchInput = screen.getByRole('combobox', h);
     await user.type(searchInput, 'xyz');
 
-    expect(screen.getByText('No results found')).toBeInTheDocument();
+    expect(
+      within(screen.getByRole('listbox', h)).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', () => {
@@ -1072,7 +1239,9 @@ describe('MultiSelector', () => {
           />
         </form>,
       );
-      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+      expect([
+        ...new FormData(container.querySelector('form')!).keys(),
+      ]).toEqual([]);
     });
   });
 });