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

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/Lightbox/Lightbox.tsx

@@ -199,7 +199,7 @@ const styles = stylex.create({
   closeButton: {
     position: 'absolute',
     top: spacingVars['--spacing-3'],
-    right: spacingVars['--spacing-3'],
+    insetInlineEnd: spacingVars['--spacing-3'],
     zIndex: 1,
   },
   navButton: {
@@ -209,15 +209,15 @@ const styles = stylex.create({
     zIndex: 1,
   },
   navPrev: {
-    left: spacingVars['--spacing-3'],
+    insetInlineStart: spacingVars['--spacing-3'],
   },
   navNext: {
-    right: spacingVars['--spacing-3'],
+    insetInlineEnd: spacingVars['--spacing-3'],
   },
   counter: {
     position: 'absolute',
     top: spacingVars['--spacing-3'],
-    left: spacingVars['--spacing-3'],
+    insetInlineStart: spacingVars['--spacing-3'],
     color: colorVars['--color-on-dark'],
     fontSize: typeScaleVars['--text-body-size'],
     lineHeight: typeScaleVars['--text-body-leading'],

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',
@@ -154,6 +155,13 @@ export const docs = {
           type: "{type: 'error' | 'warning' | 'success', message?: string}",
           description: 'Validation status with an optional message.',
         },
+        {
+          name: 'statusVariant',
+          type: "'attached' | 'detached'",
+          description:
+            'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+          default: "'attached'",
+        },
         {
           name: 'renderOption',
           type: '(option: MultiSelectorOptionData) => ReactNode',
@@ -239,7 +247,8 @@ export const docsZh = {
         hasSearch: '是否显示用于过滤选项的搜索输入。',
         searchPlaceholder: '搜索输入的占位文本。',
         isDisabled: '禁用选择器。',
-        htmlName: '用于表单提交的 HTML name 属性。为每个已选值渲染一个隐藏输入，类似原生多选。',
+        htmlName:
+          '用于表单提交的 HTML name 属性。为每个已选值渲染一个隐藏输入，类似原生多选。',
         disabledMessage:
           '解释选择器被禁用的原因。与 isDisabled 一起使用时，悬停/键盘聚焦时显示工具提示，并通过 aria-disabled 保持触发器可聚焦（仍无法激活）。请使用此属性，而不是用 Tooltip 包裹被禁用的选择器。',
         isLabelHidden: '视觉上隐藏标签同时保持其可访问性。',
@@ -248,6 +257,7 @@ export const docsZh = {
         isRequired: '将字段标记为必填。',
         isLoading: '在触发器中显示加载旋转器。',
         status: '带可选消息的验证状态。',
+        statusVariant: '状态消息的放置方式：attached 直接叠加在输入框下方；detached 作为独立元素浮于下方并留有间距。',
         renderOption:
           '每个可选选项的自定义渲染函数。不会用于分隔线、分组或全选行。',
         xstyle: '布局自定义的 StyleX 样式，必须是 stylex.create() 值。',
@@ -373,6 +383,7 @@ export const docsDense = {
         isRequired: 'marks required',
         isLoading: 'spinner in trigger',
         status: 'validation status w/ optional message',
+        statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
         renderOption:
           'custom render fn per selectable option; not dividers/sections/select-all',
         xstyle: 'StyleX layout styles; stylex.create() only',

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,32 @@ describe('MultiSelector', () => {
           />
         </form>,
       );
-      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+      expect([
+        ...new FormData(container.querySelector('form')!).keys(),
+      ]).toEqual([]);
     });
   });
 });
+
+
+describe('MultiSelector statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <MultiSelector label="Fruit" options={['Apple', 'Banana']} value={[]} onChange={() => {}} status={{type: 'error', message: 'Required'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <MultiSelector label="Fruit" options={['Apple', 'Banana']} value={[]} onChange={() => {}} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});