@astryxdesign/core 0.1.7 → 0.1.8-canary.0c4d8d7

package/src/TopNav/TopNav.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {fireEvent, render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TopNav} from './TopNav';
 import {TopNavRenderContext} from './TopNavRenderContext';
@@ -297,6 +297,85 @@ describe('TopNavHeading', () => {
     render(<TopNavHeading heading="Test" ref={ref} />);
     expect(ref).toHaveBeenCalledWith(expect.any(HTMLElement));
   });
+
+  // ===========================================================================
+  // Menu popover semantics — the popup must not be announced as a modal
+  // dialog, and role="menu" must be scoped to the actual menu items so the
+  // heading button is not an invalid child of the menu.
+  // ===========================================================================
+
+  // The popover layer keeps `popover` content display:none in jsdom even
+  // when open, hiding it from role queries — so these tests assert the
+  // popup's ARIA semantics at the DOM level instead.
+  describe('menu popover semantics', () => {
+    const menuItems = (
+      <>
+        <div role="menuitem">Alpha</div>
+        <div role="menuitem">Beta</div>
+      </>
+    );
+
+    it('does not wrap the heading menu popup in a modal dialog', async () => {
+      const user = userEvent.setup();
+      render(<TopNavHeading heading="My App" menu={menuItems} />);
+      await user.click(screen.getByRole('button', {name: 'Open menu'}));
+      expect(document.querySelector('[role="dialog"]')).toBeNull();
+      expect(document.querySelector('[aria-modal="true"]')).toBeNull();
+    });
+
+    it('scopes role="menu" to only menuitem children with an accessible name', async () => {
+      const user = userEvent.setup();
+      render(<TopNavHeading heading="My App" menu={menuItems} />);
+      await user.click(screen.getByRole('button', {name: 'Open menu'}));
+      const menu = document.querySelector('[role="menu"]');
+      expect(menu).not.toBeNull();
+      expect(menu).toHaveAttribute('aria-label', 'My App');
+      const children = Array.from(menu!.children);
+      expect(children.length).toBeGreaterThan(0);
+      for (const child of children) {
+        expect(child).toHaveAttribute('role', 'menuitem');
+      }
+    });
+
+    it('keeps the popup heading button outside the menu and closes on click', async () => {
+      const user = userEvent.setup();
+      render(<TopNavHeading heading="My App" menu={menuItems} />);
+      const trigger = screen.getByRole('button', {name: 'Open menu'});
+      await user.click(trigger);
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+      const menu = document.querySelector('[role="menu"]');
+      expect(menu).not.toBeNull();
+      // The heading replica button in the popup is a sibling of the menu,
+      // not an invalid menu child.
+      const headingButton = Array.from(
+        document.querySelectorAll('button'),
+      ).find(b => b !== trigger && b.textContent?.includes('My App'));
+      expect(headingButton).toBeDefined();
+      expect(menu!.contains(headingButton!)).toBe(false);
+      // Clicking it still closes the popup.
+      fireEvent.click(headingButton!);
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    it('applies the same semantics in mixed mode (menu + hrefs)', async () => {
+      const user = userEvent.setup();
+      render(
+        <TopNavHeading
+          heading="Product"
+          headingHref="/product"
+          menu={menuItems}
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Open menu'}));
+      expect(document.querySelector('[role="dialog"]')).toBeNull();
+      const menu = document.querySelector('[role="menu"]');
+      expect(menu).not.toBeNull();
+      expect(menu).toHaveAttribute('aria-label', 'Product');
+      for (const child of Array.from(menu!.children)) {
+        expect(child).toHaveAttribute('role', 'menuitem');
+      }
+    });
+  });
 });
 
 describe('NavIcon', () => {

package/src/TopNav/TopNavHeading.tsx

@@ -332,6 +332,10 @@ export function TopNavHeading({
 
   const popover = usePopover({
     dialogLabel: t('@astryx.topNav.heading.dialogLabel'),
+    // The popup exposes its own role="menu" semantics; a role="dialog"
+    // aria-modal wrapper would announce "dialog, Navigation menu" around a
+    // menu (the anti-pattern removed in a478a3dcf).
+    role: 'none',
     hasCloseButton: false,
   });
 
@@ -511,13 +515,19 @@ export function TopNavHeading({
         {popover.render(
           <div
             ref={menuRef}
-            role="menu"
             {...stylex.props(styles.popoverContent)}
             {...contentProps}>
             {popoverHeadingContent}
-            <NavHeadingCloseContext value={closeMenuCtx}>
-              {menu}
-            </NavHeadingCloseContext>
+            {/* The menu role is scoped to the actual menu items so the
+                heading button above stays a valid sibling, not an invalid
+                child of a role="menu" element. */}
+            <div
+              role="menu"
+              aria-label={heading ?? t('@astryx.topNav.heading.dialogLabel')}>
+              <NavHeadingCloseContext value={closeMenuCtx}>
+                {menu}
+              </NavHeadingCloseContext>
+            </div>
           </div>,
           {
             placement: 'below',
@@ -575,13 +585,19 @@ export function TopNavHeading({
         {popover.render(
           <div
             ref={menuRef}
-            role="menu"
             {...stylex.props(styles.popoverContent)}
             {...contentProps}>
             {popoverHeadingContent}
-            <NavHeadingCloseContext value={closeMenuCtx}>
-              {menu}
-            </NavHeadingCloseContext>
+            {/* The menu role is scoped to the actual menu items so the
+                heading button above stays a valid sibling, not an invalid
+                child of a role="menu" element. */}
+            <div
+              role="menu"
+              aria-label={heading ?? t('@astryx.topNav.heading.dialogLabel')}>
+              <NavHeadingCloseContext value={closeMenuCtx}>
+                {menu}
+              </NavHeadingCloseContext>
+            </div>
           </div>,
           {
             placement: 'below',

package/src/TopNav/TopNavMegaMenu.test.tsx

@@ -9,7 +9,7 @@
  * SYNC: When TopNavMegaMenu changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi} from 'vitest';
+import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TopNavMegaMenu} from './TopNavMegaMenu';
@@ -75,6 +75,154 @@ describe('TopNavMegaMenu — default mode', () => {
   });
 });
 
+// =============================================================================
+// Popup semantics (default mode)
+// =============================================================================
+
+describe('TopNavMegaMenu — popup semantics', () => {
+  // Mock the Popover API (not implemented in jsdom).
+  const originalMatches = HTMLElement.prototype.matches;
+
+  beforeAll(() => {
+    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);
+    });
+    // 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);
+    };
+  });
+
+  afterAll(() => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (HTMLElement.prototype as any).matches = originalMatches;
+  });
+
+  it('trigger aria-controls resolves to the popup element', async () => {
+    const user = userEvent.setup();
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+      />,
+    );
+
+    const trigger = screen.getByRole('button', {name: 'Products'});
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+    // aria-controls must be present and point at the real popup element.
+    const controlsId = trigger.getAttribute('aria-controls');
+    expect(controlsId).toBeTruthy();
+    const popup = document.getElementById(controlsId as string);
+    expect(popup).not.toBeNull();
+
+    await user.click(trigger);
+
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    // The referenced element is the popup that contains the panel content.
+    expect(popup).toContainElement(
+      screen.getByRole('group', {name: 'Products', hidden: true}),
+    );
+  });
+
+  it('does not wrap the panel in a role="dialog" aria-modal element', async () => {
+    const user = userEvent.setup();
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    // Focus stays on the trigger while the panel is open, so a modal dialog
+    // wrapper would tell assistive tech the focused control is inert.
+    expect(
+      screen.queryByRole('dialog', {hidden: true}),
+    ).not.toBeInTheDocument();
+    expect(document.querySelector('[aria-modal="true"]')).toBeNull();
+  });
+
+  it('does not expose role="menu" — a link grid is not an ARIA menu', async () => {
+    const user = userEvent.setup();
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        items={
+          <>
+            <TopNavMegaMenuItem title="Analytics" href="/analytics" />
+            <TopNavMegaMenuItem title="Reports" href="/reports" />
+          </>
+        }
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    // Per the WAI-ARIA APG, mega menu panels of navigation links must not use
+    // the menu role (reserved for action menus with menuitem children).
+    expect(screen.queryByRole('menu', {hidden: true})).not.toBeInTheDocument();
+    expect(screen.queryAllByRole('menuitem', {hidden: true})).toHaveLength(0);
+  });
+
+  it('exposes the panel as a labeled group', async () => {
+    const user = userEvent.setup();
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    expect(
+      screen.getByRole('group', {name: 'Products', hidden: true}),
+    ).toBeInTheDocument();
+  });
+
+  it('keeps item links with accessible names inside the panel', async () => {
+    const user = userEvent.setup();
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        items={
+          <>
+            <TopNavMegaMenuItem title="Analytics" href="/analytics" />
+            <TopNavMegaMenuItem title="Reports" href="/reports" />
+          </>
+        }
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    const analytics = screen.getByRole('link', {
+      name: /Analytics/,
+      hidden: true,
+    });
+    expect(analytics).toHaveAttribute('href', '/analytics');
+    expect(
+      screen.getByRole('link', {name: /Reports/, hidden: true}),
+    ).toHaveAttribute('href', '/reports');
+  });
+});
+
 // =============================================================================
 // Mobile-bar mode — should be hidden
 // =============================================================================

package/src/TopNav/TopNavMegaMenu.tsx

@@ -354,7 +354,11 @@ function DefaultMegaMenu({
   }, [onOpenChange]);
 
   const popover = usePopover({
-    dialogLabel: label,
+    // role: 'none' — the panel exposes its own role="group" labeled by
+    // `label`. Focus stays on the trigger while the panel is open, so a
+    // role="dialog" aria-modal="true" wrapper would announce an unnamed
+    // modal dialog around a grid of links.
+    role: 'none',
     // hasSurface: false — mega menu provides its own surface (panelContainer)
     // with border-top and custom overflow. Animation is applied via the
     // render() call's xstyle prop (panelAnimation), not the hook options.
@@ -434,8 +438,7 @@ function DefaultMegaMenu({
       <button
         ref={mergeRefs(triggerButtonRef, ref)}
         type="button"
-        aria-haspopup="true"
-        aria-expanded={popover.isOpen}
+        {...popover.triggerProps}
         onClick={handleClick}
         onMouseEnter={handleMouseEnter}
         onMouseLeave={handleMouseLeave}
@@ -454,7 +457,10 @@ function DefaultMegaMenu({
       </button>
       {popover.render(
         <div
-          role="menu"
+          // role="group" — a mega menu is a browsing grid of links, not an
+          // ARIA menu of menuitems (per the WAI-ARIA APG, the menu role is
+          // for action menus; link mega menus are the documented anti-case).
+          role="group"
           aria-label={label}
           onMouseEnter={handleMouseEnter}
           onMouseLeave={handleMouseLeave}

package/src/TopNav/TopNavMenu.test.tsx

@@ -9,8 +9,9 @@
  * SYNC: When TopNavMenu changes, update tests to match new behavior
  */
 
-import {describe, it, expect} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import {TopNavMenu} from './TopNavMenu';
 
 const mockItems = [
@@ -32,10 +33,13 @@ describe('TopNavMenu', () => {
     expect(screen.getByRole('button', {name: 'Products'})).toBeInTheDocument();
   });
 
-  it('trigger has aria-haspopup attribute', () => {
+  it('trigger announces a menu popup, not a dialog', () => {
     render(<TopNavMenu label="Products" items={mockItems} />);
     const trigger = screen.getByRole('button', {name: 'Products'});
-    expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
+    // usePopover with role:'none' emits aria-haspopup="true" (the ARIA
+    // synonym for "menu") because the exposed semantics of the popup are its
+    // child role="menu", not a dialog.
+    expect(trigger).toHaveAttribute('aria-haspopup', 'true');
   });
 
   it('renders with custom items', () => {
@@ -57,3 +61,113 @@ describe('TopNavMenu', () => {
     expect(screen.getByRole('button', {name: 'Menu'})).toBeInTheDocument();
   });
 });
+
+describe('menu semantics (APG)', () => {
+  it('does not wrap the popup in a role="dialog" / aria-modal shell', () => {
+    render(<TopNavMenu label="Products" items={mockItems} />);
+    // The popup's exposed semantics are the role="menu" container itself —
+    // no dialog wrapper, no aria-modal.
+    expect(
+      screen.queryByRole('dialog', {hidden: true}),
+    ).not.toBeInTheDocument();
+    expect(document.querySelector('[aria-modal]')).toBeNull();
+    expect(
+      screen.getByRole('menu', {name: 'Products', hidden: true}),
+    ).toBeInTheDocument();
+  });
+});
+
+describe('keyboard navigation (APG menu pattern)', () => {
+  it('exposes exactly one tab stop among menu items (roving tabindex)', async () => {
+    const user = userEvent.setup();
+    render(<TopNavMenu label="Products" items={mockItems} />);
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    const items = screen.getAllByRole('menuitem', {hidden: true});
+    expect(items).toHaveLength(2);
+    const tabbable = items.filter(el => el.getAttribute('tabindex') === '0');
+    expect(tabbable).toHaveLength(1);
+  });
+
+  it('moves focus with ArrowDown/ArrowUp and the tab stop follows', async () => {
+    const user = userEvent.setup();
+    render(<TopNavMenu label="Products" items={mockItems} />);
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    const menu = screen.getByRole('menu', {hidden: true});
+    const items = screen.getAllByRole('menuitem', {hidden: true});
+    items[0].focus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(items[1]).toHaveFocus();
+    expect(items[1]).toHaveAttribute('tabindex', '0');
+    expect(items[0]).toHaveAttribute('tabindex', '-1');
+
+    fireEvent.keyDown(menu, {key: 'ArrowUp'});
+    expect(items[0]).toHaveFocus();
+    expect(items[0]).toHaveAttribute('tabindex', '0');
+    expect(items[1]).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('wraps focus at both ends', async () => {
+    const user = userEvent.setup();
+    render(<TopNavMenu label="Products" items={mockItems} />);
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    const menu = screen.getByRole('menu', {hidden: true});
+    const items = screen.getAllByRole('menuitem', {hidden: true});
+
+    items[1].focus();
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(items[0]).toHaveFocus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowUp'});
+    expect(items[1]).toHaveFocus();
+  });
+
+  it('typeahead moves focus to the item matching the typed character', async () => {
+    const user = userEvent.setup();
+    render(<TopNavMenu label="Products" items={mockItems} />);
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    const menu = screen.getByRole('menu', {hidden: true});
+    fireEvent.keyDown(menu, {key: 'm'});
+    expect(
+      screen.getByRole('menuitem', {name: /Messaging/, hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('activates a focused onClick-only item with Enter', async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    render(<TopNavMenu label="Menu" items={[{title: 'Action', onClick}]} />);
+    await user.click(screen.getByRole('button', {name: 'Menu'}));
+
+    const item = screen.getByRole('menuitem', {hidden: true});
+    item.focus();
+    fireEvent.keyDown(item, {key: 'Enter'});
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+
+  it('still activates an item on click', async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    render(<TopNavMenu label="Menu" items={[{title: 'Action', onClick}]} />);
+    await user.click(screen.getByRole('button', {name: 'Menu'}));
+
+    await user.click(screen.getByRole('menuitem', {hidden: true}));
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+
+  it('closes the menu with Escape', async () => {
+    const user = userEvent.setup();
+    render(<TopNavMenu label="Products" items={mockItems} />);
+    const trigger = screen.getByRole('button', {name: 'Products'});
+    await user.click(trigger);
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+    const menu = screen.getByRole('menu', {hidden: true});
+    fireEvent.keyDown(menu, {key: 'Escape'});
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+  });
+});

package/src/TopNav/TopNavMenu.tsx

@@ -4,7 +4,8 @@
 
 /**
  * @file TopNavMenu.tsx
- * @input Uses React, StyleX, useHoverCard, TopNavItem tokens
+ * @input Uses React, StyleX, usePopover, useMenuHover, useListFocus,
+ *   useTypeahead, TopNavItem tokens
  * @output Exports TopNavMenu component and related types
  * @position Navigation item with hover-triggered overflow menu for TopNav
  *
@@ -15,10 +16,18 @@
  * - /packages/cli/templates/blocks/components/TopNav/ (showcase blocks)
  */
 
-import React, {useId, useRef, useState, type ReactNode} from 'react';
+import React, {
+  useCallback,
+  useId,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {usePopover} from '../Popover/usePopover';
 import {useMenuHover} from '../hooks/useMenuHover';
+import {useListFocus} from '../hooks/useListFocus';
+import {useTypeahead} from '../hooks/useTypeahead';
 import {getIcon} from '../Icon/globalIconRegistry';
 import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
@@ -332,7 +341,10 @@ export function TopNavMenu({
   const triggerButtonRef = useRef<HTMLButtonElement | null>(null);
 
   const popover = usePopover({
-    dialogLabel: label,
+    // The popup's own role="menu" is the exposed semantics; a modal dialog
+    // wrapper would announce an unnamed dialog around the menu and make the
+    // trigger claim aria-haspopup="dialog" for menu content (see TabMenu).
+    role: 'none',
     xstyle: styles.menuOffset,
   });
 
@@ -353,6 +365,65 @@ export function TopNavMenu({
     ref,
   );
 
+  // The desktop popup is a composite menu widget per the APG menu pattern:
+  // a single roving tab stop with ArrowUp/ArrowDown traversal (wrapping),
+  // Home/End, and first-character typeahead. The hook owns item tabindex —
+  // items render tabIndex={-1} and exactly one is promoted to 0. The
+  // composition mirrors NavHeadingMenu.
+  const {listRef, handleKeyDown, handleFocus, focusItem} =
+    useListFocus<HTMLDivElement>({
+      itemSelector: '[role="menuitem"]',
+      hasRovingTabIndex: true,
+      onEscape: popover.hide,
+    });
+
+  // First-character typeahead over the menu items (menus-11).
+  const getMenuItems = useCallback(
+    (): HTMLElement[] =>
+      listRef.current
+        ? Array.from(
+            listRef.current.querySelectorAll<HTMLElement>('[role="menuitem"]'),
+          )
+        : [],
+    [listRef],
+  );
+  const typeahead = useTypeahead({
+    getItemLabels: () => getMenuItems().map(el => el.textContent),
+    onMatch: focusItem,
+    getCurrentIndex: () =>
+      getMenuItems().findIndex(
+        el =>
+          el === document.activeElement || el.contains(document.activeElement),
+      ),
+  });
+
+  // Extend useListFocus with Enter/Space activation. Items rendered without an
+  // `href` are `<div role="menuitem">` elements, which have no native keyboard
+  // activation — without this, Enter/Space on a focused onClick-only item does
+  // nothing. Anchor items (with `href`) already activate on Enter natively.
+  const menuKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === 'Enter' || e.key === ' ') {
+        const focused = document.activeElement as HTMLElement | null;
+        if (focused?.getAttribute('role') === 'menuitem') {
+          e.preventDefault();
+          focused.click();
+          return;
+        }
+      }
+      if (typeahead.onKeyDown(e)) {
+        e.preventDefault();
+        return;
+      }
+      handleKeyDown(e);
+    },
+    [handleKeyDown, typeahead],
+  );
+
+  // Menu container carries both the hover hook's ref (for its open/close
+  // focus management) and the list-focus ref (for roving tabindex/typeahead).
+  const setMenuRef = mergeRefs<HTMLDivElement>(menuRef, listRef);
+
   // Mobile bar: hide menus entirely
   if (renderMode === 'mobile-bar') {
     return null;
@@ -437,10 +508,15 @@ export function TopNavMenu({
       </button>
       {popover.render(
         <div
-          ref={menuRef}
+          ref={setMenuRef}
           role="menu"
           aria-label={label}
           {...contentProps}
+          // After the contentProps spread so the full APG composition (roving
+          // tabindex + typeahead + Enter/Space activation) replaces the hover
+          // hook's basic arrow-key handler.
+          onKeyDown={menuKeyDown}
+          onFocus={handleFocus}
           {...stylex.props(styles.menuContainer)}>
           {items.map(item => {
             const Element = item.href ? 'a' : 'div';
@@ -448,7 +524,9 @@ export function TopNavMenu({
               <Element
                 key={getMenuItemKey(item)}
                 role="menuitem"
-                tabIndex={popover.isOpen ? 0 : -1}
+                // Single tab stop: useListFocus owns the roving tabindex and
+                // promotes exactly one item to 0.
+                tabIndex={-1}
                 href={item.href}
                 onClick={item.onClick}
                 {...stylex.props(styles.menuItem)}>

package/src/TreeList/TreeList.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TreeList} from './TreeList';
 import type {TreeListItemData} from './TreeListTypes';
@@ -251,6 +251,37 @@ describe('TreeList', () => {
     expect(screen.getByText('Leaf')).toBeInTheDocument();
   });
 
+  // ===========================================================================
+  // Focus-visible outline scoping (regression: focusing a parent row must not
+  // leak the ring onto descendant rows — see #4130)
+  // ===========================================================================
+
+  it('scopes the focus-visible outline to the focused row, not its descendants', () => {
+    render(<TreeList items={deepItems} />);
+    const root = screen.getByText('Root').closest('li')!;
+    const mid = screen.getByText('Mid').closest('li')!;
+    const leaf = screen.getByText('Leaf').closest('li')!;
+
+    // A keydown before .focus() establishes keyboard modality so jsdom's
+    // :focus-visible heuristic applies deterministically, regardless of
+    // pointer events left over from other tests in this file.
+    fireEvent.keyDown(document.body, {key: 'Tab'});
+    root.focus();
+    expect(root).toHaveFocus();
+
+    expect(
+      getComputedStyle(root).getPropertyValue('--_tree-focus-outline'),
+    ).toContain('solid');
+    // Mid and Leaf are DOM descendants of Root's <li> (nested <ul role="group">
+    // subtrees) — their own outline var must stay unset, not inherit Root's.
+    expect(
+      getComputedStyle(mid).getPropertyValue('--_tree-focus-outline'),
+    ).toBe('none');
+    expect(
+      getComputedStyle(leaf).getPropertyValue('--_tree-focus-outline'),
+    ).toBe('none');
+  });
+
   // ===========================================================================
   // Interactive items
   // ===========================================================================