@astryxdesign/core 0.4.1 → 0.4.2-canary.464a445

package/src/TopNav/TopNavMegaMenu.test.tsx

@@ -9,6 +9,8 @@
  * SYNC: When TopNavMegaMenu changes, update tests to match new behavior
  */
 
+import * as stylex from '@stylexjs/stylex';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {describe, it, expect, vi, beforeAll, afterAll, afterEach} from 'vitest';
 import {render, screen, act, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
@@ -817,3 +819,44 @@ describe('TopNavMegaMenuItem', () => {
     expect(screen.getByRole('link', {name: /Analytics/})).toBeInTheDocument();
   });
 });
+
+// =============================================================================
+// The shared focus ring (#4654) — see the note in SideNav.test.tsx: jsdom will
+// not derive `:focus-visible` here, so what is pinned is that the focusable
+// element composes the shared utility's classes rather than falling back to
+// the browser's own outline.
+// =============================================================================
+
+const sharedFocusRingClasses = stylex
+  .props(focusOutlineStyles.focusVisible)
+  .className!.split(' ');
+
+function expectSharedFocusRing(el: Element) {
+  const classes = el.className.split(' ');
+  for (const c of sharedFocusRingClasses) {
+    expect(classes).toContain(c);
+  }
+}
+
+describe('TopNavMegaMenu — drawer focus ring', () => {
+  it('draws the shared ring on the drawer section header', () => {
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMegaMenu
+          label="Products"
+          items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+        />
+      </TopNavRenderContext>,
+    );
+    expectSharedFocusRing(screen.getByRole('button', {name: 'Products'}));
+  });
+
+  it('draws the shared ring on a drawer item', () => {
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMegaMenuItem title="Analytics" href="/analytics" />
+      </TopNavRenderContext>,
+    );
+    expectSharedFocusRing(screen.getByRole('link', {name: /Analytics/}));
+  });
+});

package/src/TopNav/TopNavMegaMenu.tsx

@@ -50,6 +50,7 @@ import {
   borderVars,
 } from '../theme/tokens.stylex';
 import {usePopover} from '../Popover/usePopover';
+import {useMenuHover} from '../hooks/useMenuHover';
 import {Grid} from '../Grid/Grid';
 import {Icon} from '../Icon';
 import {mergeProps, mergeRefs} from '../utils';
@@ -370,7 +371,9 @@ TopNavMegaMenu.displayName = 'TopNavMegaMenu';
 // DefaultMegaMenu — desktop popover mode
 // =============================================================================
 
-const CLICK_GUARD_MS = 500;
+/** The panel is a grid of links, not `role="menuitem"` rows. */
+const PANEL_ITEM_SELECTOR =
+  'a[href], button:not([disabled]), [tabindex]:not([tabindex="-1"])';
 
 function DefaultMegaMenu({
   ref,
@@ -382,19 +385,13 @@ function DefaultMegaMenu({
   onOpenChange,
 }: TopNavMegaMenuProps) {
   const slot = useTopNavSlot();
-  const showTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const hideTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const triggerButtonRef = useRef<HTMLButtonElement | null>(null);
-  const hoverOpenedAtRef = useRef(0);
-  const stickyRef = useRef(false);
 
   const handlePopoverShow = useCallback(() => {
     onOpenChange?.(true);
   }, [onOpenChange]);
 
   const handlePopoverHide = useCallback(() => {
-    hoverOpenedAtRef.current = 0;
-    stickyRef.current = false;
     onOpenChange?.(false);
   }, [onOpenChange]);
 
@@ -430,107 +427,31 @@ function DefaultMegaMenu({
     };
   }, [popover]);
 
-  const clearTimeouts = useCallback(() => {
-    if (showTimeoutRef.current) {
-      clearTimeout(showTimeoutRef.current);
-      showTimeoutRef.current = null;
-    }
-    if (hideTimeoutRef.current) {
-      clearTimeout(hideTimeoutRef.current);
-      hideTimeoutRef.current = null;
-    }
-  }, []);
-
-  const scheduleShow = useCallback(() => {
-    clearTimeouts();
-    showTimeoutRef.current = setTimeout(() => {
-      hoverOpenedAtRef.current = Date.now();
-      popover.show({skipAutoFocus: true});
-    }, delay);
-  }, [clearTimeouts, delay, popover]);
-
-  const scheduleHide = useCallback(() => {
-    clearTimeouts();
-    hideTimeoutRef.current = setTimeout(() => {
-      popover.hide();
-    }, hideDelay);
-  }, [clearTimeouts, hideDelay, popover]);
-
-  const focusFirstPanelItem = useCallback(() => {
-    popover.contentRef.current
-      ?.querySelector<HTMLElement>(
-        'a[href], button:not([disabled]), [tabindex]:not([tabindex="-1"])',
-      )
-      ?.focus();
-  }, [popover.contentRef]);
-
-  const handleTriggerMouseEnter = useCallback(() => {
-    clearTimeouts();
-    if (!popover.isOpen) {
-      scheduleShow();
-    }
-  }, [clearTimeouts, popover.isOpen, scheduleShow]);
-
-  const handlePanelMouseEnter = useCallback(() => {
-    clearTimeouts();
-  }, [clearTimeouts]);
-
-  const handleMouseLeave = useCallback(() => {
-    if (!stickyRef.current) {
-      scheduleHide();
-    }
-  }, [scheduleHide]);
-
-  const handleClick = useCallback(
-    (event: React.MouseEvent<HTMLButtonElement>) => {
-      // Cancel the native invoker toggle so this guard is the single source of
-      // truth for trigger activation. popoverTarget still establishes the
-      // invoker relationship used by native light-dismiss and stacking.
-      event.preventDefault();
-      clearTimeouts();
-
-      if (event.detail === 0) {
-        stickyRef.current = true;
-        hoverOpenedAtRef.current = 0;
-        if (popover.isOpen) {
-          focusFirstPanelItem();
-        } else {
-          popover.show();
-        }
-      } else if (!popover.isOpen) {
-        stickyRef.current = true;
-        popover.show({skipAutoFocus: true});
-      } else if (Date.now() - hoverOpenedAtRef.current < CLICK_GUARD_MS) {
-        // A click that naturally follows a hover-open confirms the open state
-        // instead of toggling the panel shut. From here it behaves like any
-        // other click-open and stays pinned until explicit dismissal.
-        stickyRef.current = true;
-        hoverOpenedAtRef.current = 0;
-      } else {
-        popover.hide();
-        triggerButtonRef.current?.focus();
-      }
-    },
-    [clearTimeouts, focusFirstPanelItem, popover],
-  );
-
-  useEffect(() => {
-    return () => {
-      clearTimeouts();
-    };
-  }, [clearTimeouts]);
+  const {
+    triggerProps: hoverTriggerProps,
+    contentProps,
+    menuRef,
+    setTriggerEl,
+  } = useMenuHover<HTMLDivElement>({
+    show: popover.show,
+    hide: popover.hide,
+    isOpen: popover.isOpen,
+    isEnabled: true,
+    showDelay: delay,
+    hideDelay,
+    itemSelector: PANEL_ITEM_SELECTOR,
+    // Trigger sits outside an auto popover; the invoker relationship exempts it
+    // from light dismiss.
+    popoverId: popover.id,
+  });
 
   return (
     <>
       <button
-        ref={mergeRefs(triggerButtonRef, ref)}
+        ref={mergeRefs(triggerButtonRef, setTriggerEl, ref)}
         type="button"
         {...popover.triggerProps}
-        // Native invoker prevents trigger light-dismiss.
-        popoverTarget={popover.id}
-        onClick={handleClick}
-        onMouseEnter={handleTriggerMouseEnter}
-        onMouseLeave={handleMouseLeave}
+        {...hoverTriggerProps}
         {...mergeProps(
           themeProps('top-nav-mega-menu'),
           focusOutlineProps.focusVisible(
@@ -551,10 +472,10 @@ function DefaultMegaMenu({
           // 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).
+          ref={menuRef}
           role="group"
           aria-label={label}
-          onMouseEnter={handlePanelMouseEnter}
-          onMouseLeave={handleMouseLeave}
+          {...contentProps}
           {...stylex.props(styles.panelContainer)}>
           <div {...stylex.props(styles.panelContent)}>
             {/* Menu items section */}
@@ -602,7 +523,10 @@ function DrawerMegaMenu({
         aria-controls={`${menuId}-items`}
         {...mergeProps(
           themeProps('top-nav-mega-menu', {mode: 'drawer'}),
-          stylex.props(navItemStyles.item, styles.drawerHeader),
+          focusOutlineProps.focusVisible(
+            navItemStyles.item,
+            styles.drawerHeader,
+          ),
         )}>
         {label}
         <Icon

package/src/TopNav/TopNavMegaMenuItem.tsx

@@ -215,7 +215,7 @@ export function TopNavMegaMenuItem({
         {...elementProps}
         {...mergeProps(
           themeProps('top-nav-mega-menu-item', {mode: 'drawer'}),
-          stylex.props(navItemStyles.item, styles.drawerItem),
+          focusOutlineProps.focusVisible(navItemStyles.item, styles.drawerItem),
         )}>
         {icon && <div {...stylex.props(styles.drawerItemIcon)}>{icon}</div>}
         <div {...stylex.props(styles.drawerItemContent)}>

package/src/TopNav/TopNavMenu.test.tsx

@@ -12,6 +12,9 @@
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import * as stylex from '@stylexjs/stylex';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
+import {TopNavRenderContext} from './TopNavRenderContext';
 import {TopNavMenu} from './TopNavMenu';
 
 const mockItems = [
@@ -171,3 +174,41 @@ describe('keyboard navigation (APG menu pattern)', () => {
     expect(trigger).toHaveAttribute('aria-expanded', 'false');
   });
 });
+
+// =============================================================================
+// The shared focus ring (#4654) — see the note in SideNav.test.tsx: jsdom will
+// not derive `:focus-visible` here, so what is pinned is that the focusable
+// element composes the shared utility's classes rather than falling back to
+// the browser's own outline.
+// =============================================================================
+
+const sharedFocusRingClasses = stylex
+  .props(focusOutlineStyles.focusVisible)
+  .className!.split(' ');
+
+function expectSharedFocusRing(el: Element) {
+  const classes = el.className.split(' ');
+  for (const c of sharedFocusRingClasses) {
+    expect(classes).toContain(c);
+  }
+}
+
+describe('TopNavMenu — drawer focus ring', () => {
+  it('draws the shared ring on the drawer section header', () => {
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMenu label="Products" items={mockItems} />
+      </TopNavRenderContext>,
+    );
+    expectSharedFocusRing(screen.getByRole('button', {name: /Products/}));
+  });
+
+  it('draws the shared ring on a drawer item', () => {
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMenu label="Products" items={mockItems} />
+      </TopNavRenderContext>,
+    );
+    expectSharedFocusRing(screen.getByRole('link', {name: /Analytics/}));
+  });
+});

package/src/TopNav/TopNavMenu.tsx

@@ -342,7 +342,7 @@ export function TopNavMenu({
     role: 'none',
   });
 
-  const {triggerProps, contentProps, menuRef, setTriggerEl} =
+  const {triggerProps, contentProps, menuRef, setTriggerEl, close} =
     useMenuHover<HTMLDivElement>({
       show: popover.show,
       hide: popover.hide,
@@ -350,6 +350,9 @@ export function TopNavMenu({
       isEnabled: true,
       showDelay: delay,
       hideDelay,
+      // Trigger sits outside an auto popover; the invoker relationship exempts
+      // it from light dismiss.
+      popoverId: popover.id,
     });
 
   const setTriggerRef = mergeRefs<HTMLButtonElement>(
@@ -368,7 +371,8 @@ export function TopNavMenu({
     useListFocus<HTMLDivElement>({
       itemSelector: '[role="menuitem"]',
       hasRovingTabIndex: true,
-      onEscape: popover.hide,
+      // Not popover.hide: Escape must also restore focus to the trigger.
+      onEscape: close,
     });
 
   // First-character typeahead over the menu items (menus-11).
@@ -432,7 +436,10 @@ export function TopNavMenu({
           onClick={() => setDrawerExpanded(v => !v)}
           aria-expanded={drawerExpanded}
           aria-controls={`${menuId}-items`}
-          {...stylex.props(navItemStyles.item, drawerStyles.header)}>
+          {...focusOutlineProps.focusVisible(
+            navItemStyles.item,
+            drawerStyles.header,
+          )}>
           {label}
           <Icon
             icon="chevronDown"
@@ -459,7 +466,10 @@ export function TopNavMenu({
                   item.onClick?.();
                   closeMobileNav();
                 }}
-                {...stylex.props(navItemStyles.item, drawerStyles.item)}>
+                {...focusOutlineProps.focusVisible(
+                  navItemStyles.item,
+                  drawerStyles.item,
+                )}>
                 {item.icon && (
                   <span {...stylex.props(drawerStyles.itemIcon)}>
                     {item.icon}

package/src/TreeList/TreeList.doc.mjs

@@ -33,6 +33,7 @@ export const docs = {
     vars: [
       {name: '--tree-list-indent', description: 'Per-level indentation step. Each nesting level indents its rows by this distance, and the guide lines follow it so they stay aligned. Set it on the `tree-list` target to retune the metric (e.g. `var(--spacing-5)` for a wider indent).', default: 'var(--spacing-4)'},
       {name: '--tree-list-row-gap', description: 'Vertical gap between adjacent rows. Default `2px` (var(--spacing-0-5)) gives a subtle separation; set it on the `tree-list` target to widen or close the gap. The connector guides span the gap automatically (the line stays continuous) and do not overhang the last row, so no guide-height tuning is needed.', default: 'var(--spacing-0-5)'},
+      {name: '--_tree-indent', description: 'Distance one row is indented, computed per row from --tree-list-indent and the row depth. Set --tree-list-indent to retune indentation; this is the resolved value.', default: '0px', private: true},
     ],
   },
   components: [

package/src/hooks/index.ts

@@ -11,7 +11,11 @@
  * SYNC: When modified, update this header
  */
 
-export {useFocusTrap} from './useFocusTrap';
+export {
+  hasActiveFocusTrapEscape,
+  isImeKeyEvent,
+  useFocusTrap,
+} from './useFocusTrap';
 export type {UseFocusTrapOptions, UseFocusTrapReturn} from './useFocusTrap';
 
 export {useAnnounce} from './useAnnounce';

package/src/hooks/useFocusTrap.test.tsx

@@ -192,6 +192,22 @@ describe('useFocusTrap tabbable model (infra-8)', () => {
     fireEvent.keyDown(document, {key: 'Tab'});
     expect(screen.getByTestId('first')).toHaveFocus();
   });
+
+  it('keeps a programmatic focus target when the trap has no tabbable controls', () => {
+    render(
+      <Trap>
+        <div tabIndex={-1} data-testid="programmatic-target">
+          Read-only dialog content
+        </div>
+      </Trap>,
+    );
+    const target = screen.getByTestId('programmatic-target');
+    target.focus();
+
+    expect(fireEvent.keyDown(target, {key: 'Tab'})).toBe(false);
+    expect(target).toHaveFocus();
+    expect(screen.getByTestId('outside')).not.toHaveFocus();
+  });
 });
 
 describe('FOCUSABLE_SELECTOR href matching', () => {

package/src/hooks/useFocusTrap.ts

@@ -332,12 +332,21 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
         lastFocusRef.current = target as Element;
       } else if (isKeyboardNavigationRef.current) {
         // Focus escaped via keyboard - redirect it back
-        focusFirstDescendant(container);
+        const focusedFirst = focusFirstDescendant(container);
 
         // If we're back at the same element (Shift+Tab from first element),
         // try focusing the last element instead
-        if (lastFocusRef.current === document.activeElement) {
+        if (focusedFirst && lastFocusRef.current === document.activeElement) {
           focusLastDescendant(container);
+        } else if (
+          !focusedFirst &&
+          lastFocusRef.current instanceof HTMLElement &&
+          container.contains(lastFocusRef.current)
+        ) {
+          // A modal surface may intentionally have no tabbable controls and
+          // place initial focus on a tabIndex={-1} heading or panel. Preserve
+          // that programmatic focus target instead of letting Tab escape.
+          attemptFocus(lastFocusRef.current);
         }
 
         lastFocusRef.current = document.activeElement;
@@ -410,6 +419,15 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
 
         const focusable = getFocusableElements(container);
         if (focusable.length === 0) {
+          // There is nowhere to advance to. Keep focus on the current
+          // programmatic target (for example a dialog panel with tabIndex=-1)
+          // rather than allowing the browser to move into background content.
+          event.preventDefault();
+          const active = document.activeElement;
+          if (active instanceof HTMLElement && container.contains(active)) {
+            lastFocusRef.current = active;
+          }
+          isKeyboardNavigationRef.current = false;
           return;
         }