@astryxdesign/core 0.1.8 → 0.1.9-canary.09e9ddd

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/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',