@astryxdesign/core 0.4.6 → 0.4.7-canary.20bae6c

package/src/__tests__/complexComponentContract.test.tsx

@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+import {docs as DropdownMenuDocs} from '../DropdownMenu/DropdownMenu.doc.mjs';
+import {docs as HoverCardDocs} from '../HoverCard/HoverCard.doc.mjs';
+import {docs as LayoutDocs} from '../Layout/Layout.doc.mjs';
+import {docs as LightboxDocs} from '../Lightbox/Lightbox.doc.mjs';
+import {docs as LinkDocs} from '../Link/Link.doc.mjs';
+import {docs as MultiSelectorDocs} from '../MultiSelector/MultiSelector.doc.mjs';
+import {docs as PowerSearchDocs} from '../PowerSearch/PowerSearch.doc.mjs';
+import {docs as TokenizerDocs} from '../Tokenizer/Tokenizer.doc.mjs';
+import {docs as TooltipDocs} from '../Tooltip/Tooltip.doc.mjs';
+import {docs as TypeaheadDocs} from '../Typeahead/Typeahead.doc.mjs';
+
+// `docs` is the ComponentDoc union (single vs multi component); narrow it
+// for structural access to either the top-level props or the first
+// sub-component's props.
+function getProps(docs: unknown): {name: string}[] {
+  const doc = docs as {
+    props?: {name: string}[];
+    components?: {props?: {name: string}[]}[];
+  };
+  return doc.props || doc.components?.[0]?.props || [];
+}
+
+describe('Complex Component API Contract Drift (#4163)', () => {
+  it('documents search and tokenizer props across input components', () => {
+    const multiProps = getProps(MultiSelectorDocs).map(p => p.name);
+    const tokProps = getProps(TokenizerDocs).map(p => p.name);
+    const powerProps = getProps(PowerSearchDocs).map(p => p.name);
+    const typeProps = getProps(TypeaheadDocs).map(p => p.name);
+
+    expect(multiProps).toContain('startIcon');
+    expect(multiProps).toContain('hasClear');
+    expect(multiProps).toContain('isDefaultOpen');
+
+    expect(tokProps).toContain('startIcon');
+    expect(tokProps).toContain('tokenOverflowBehavior');
+
+    expect(powerProps).toContain('startIcon');
+    expect(powerProps).toContain('menuWidth');
+    expect(powerProps).toContain('maxOperatorMenuItems');
+    expect(powerProps).toContain('tokenOverflowBehavior');
+
+    expect(typeProps).toContain('startIcon');
+  });
+
+  it('documents Layout and DropdownMenu layout props', () => {
+    const layoutProps = getProps(LayoutDocs).map(p => p.name);
+    const dropProps = getProps(DropdownMenuDocs).map(p => p.name);
+
+    expect(layoutProps).toContain('contentWidth');
+    expect(layoutProps).toContain('padding');
+    expect(layoutProps).toContain('defaultHasDividers');
+
+    expect(dropProps).toContain('placement');
+  });
+
+  it('documents HoverCard and Tooltip open state props', () => {
+    const hoverProps = getProps(HoverCardDocs).map(p => p.name);
+    const toolProps = getProps(TooltipDocs).map(p => p.name);
+
+    expect(hoverProps).toContain('isOpen');
+    expect(toolProps).toContain('isOpen');
+  });
+
+  it('documents Link typography and Lightbox gallery props', () => {
+    const linkProps = getProps(LinkDocs).map(p => p.name);
+    const lightProps = getProps(LightboxDocs).map(p => p.name);
+
+    expect(linkProps).toContain('size');
+    expect(linkProps).toContain('weight');
+    expect(linkProps).toContain('color');
+    expect(linkProps).toContain('display');
+    expect(linkProps).toContain('maxLines');
+
+    expect(lightProps).toContain('defaultIndex');
+    expect(lightProps).toContain('hasAutoPlay');
+  });
+});

package/src/hooks/index.ts

@@ -56,6 +56,8 @@ export type {UseTypeaheadOptions, UseTypeaheadReturn} from './useTypeahead';
 
 export {useMediaQuery} from './useMediaQuery';
 
+export {useMergedRefs} from './useMergedRefs';
+
 export {useOverflow} from './useOverflow';
 export type {UseOverflowOptions, UseOverflowReturn} from './useOverflow';
 

package/src/hooks/useContainerReveal.doc.mjs

@@ -24,7 +24,7 @@ export const docs = {
     {
       name: 'getContainerProps',
       type: '(options?: ContainerRevealOptions) => {className?: string; style?: CSSProperties}',
-      description: 'Spread onto the container whose hover/focus-within drives the reveal. Accepts hoverDelay (ms the pointer must dwell before the reveal starts — a hover-intent gate like Tooltip\'s and HoverCard\'s delay, so a cursor sweeping across a list leaves nothing painted behind it) and forceState ("active" | "inactive") to pin the trigger state when a caller owns it — a motion gate, a scroll, a row whose menu is open. "inactive" still yields to keyboard focus and coarse pointers.',
+      description: 'Spread onto the container whose hover/focus-within drives the reveal. Accepts hoverDelay (ms the pointer must dwell before the reveal starts: a hover-intent gate like Tooltip\'s and HoverCard\'s delay, so a cursor sweeping across a list leaves nothing painted behind it) and forceState ("active" | "inactive") to pin the trigger state when a caller owns it: a motion gate, a scroll, or a row whose menu is open. "inactive" still yields to keyboard focus and coarse pointers.',
     },
     {
       name: 'getContentRevealProps',
@@ -61,7 +61,7 @@ export const docsDense = {
     'options.isEnabled': 'when false hook is inert: no container styles, content getters return no styles, content always shown. Read every render, so it can flip after mount.',
   },
   returnDescriptions: {
-    getContainerProps: 'spread onto container whose hover/focus-within drives reveal. Accepts hoverDelay (ms dwell before reveal starts — hover-intent gate like Tooltip / HoverCard delay) + forceState ("active" | "inactive") to pin trigger state when a caller owns it. "inactive" yields to keyboard focus + coarse pointers.',
+    getContainerProps: 'spread onto container whose hover/focus-within drives reveal. Accepts hoverDelay (ms dwell before reveal starts: hover-intent gate like Tooltip / HoverCard delay) + forceState ("active" | "inactive") to pin trigger state when a caller owns it. "inactive" yields to keyboard focus + coarse pointers.',
     getContentRevealProps: 'spread onto each revealed / concealed child. Accepts isRevealInverted (conceal-on-hover), isLayoutPreserved (reserve layout box while hidden) + forceVisibility ("shown" | "hidden") to pin this element regardless of container. "hidden" yields to focus.',
   },
   usage: {

package/src/hooks/useFocusTrap.ts

@@ -19,80 +19,26 @@
 import {useCallback, useEffect, useRef} from 'react';
 
 import {FOCUSABLE_SELECTOR} from './focusableSelector';
-import {isImeKeyEvent} from '../utils/ime';
+import {useLayerDismissal} from '../Layer/useLayerDismissal';
 
-/**
- * Module-level stack of active focus-trap Escape handlers.
- *
- * Every active `useFocusTrap` used to attach its own document-level `keydown`
- * listener with no coordination, so a single Escape press closed *every* open
- * layer at once (e.g. a popover nested inside a Dialog closed both). Tracking
- * traps in a shared stack lets only the top-most trap respond to Escape.
- *
- * "Top-most" is resolved by DOM containment first, push order second. Push
- * order alone is not reliable: React runs child effects before parent
- * effects, so when an outer and an inner (DOM-nested) trap mount in the SAME
- * commit, the inner trap pushes first and the outer trap would wrongly win a
- * pure last-pushed comparison.
- */
-interface EscapeStackEntry {
-  handler: () => void;
-  getContainer: () => HTMLElement | null;
-}
-
-const escapeStack: EscapeStackEntry[] = [];
-
-function pushEscapeHandler(entry: EscapeStackEntry): void {
-  escapeStack.push(entry);
-}
-
-function removeEscapeHandler(handler: () => void): void {
-  for (let i = escapeStack.length - 1; i >= 0; i--) {
-    if (escapeStack[i].handler === handler) {
-      escapeStack.splice(i, 1);
-      return;
-    }
-  }
-}
-
-/**
- * Resolve the top-most trap: walk the stack in push order, keeping the
- * deepest container by DOM containment. When a later entry's container
- * contains the current candidate's container, the candidate is nested inside
- * it and stays on top; otherwise the later push wins (containment for nested
- * traps, push order as the tiebreaker for unrelated ones).
- */
-function isTopEscapeHandler(handler: () => void): boolean {
-  if (escapeStack.length === 0) {
-    return false;
-  }
-  let top = escapeStack[0];
-  for (let i = 1; i < escapeStack.length; i++) {
-    const entry = escapeStack[i];
-    const topContainer = top.getContainer();
-    const entryContainer = entry.getContainer();
-    if (
-      topContainer != null &&
-      entryContainer != null &&
-      entryContainer !== topContainer &&
-      entryContainer.contains(topContainer)
-    ) {
-      // The current top is nested inside this entry — it stays on top.
-      continue;
-    }
-    top = entry;
-  }
-  return top.handler === handler;
-}
+// Escape-dismissible focus traps currently mounted. This is the whole state
+// behind `hasActiveFocusTrapEscape`, which predates the shared stack and must
+// keep answering about focus traps alone — the stack now carries families that
+// never trapped focus (tooltips, hover cards), and counting those would tell
+// callers a trap is above them when none is.
+let activeEscapeTrapCount = 0;
 
 /**
- * Whether any focus-trap Escape handler is currently active (i.e. a popover
- * layer is open). Other overlay primitives that manage their own Escape (e.g.
- * Dialog) can consult this to defer to a popover layered on top of them,
- * giving topmost-only dismissal until a full layer stack exists.
+ * Whether an Escape-dismissible focus trap is currently active — a Popover,
+ * menu or other trapped layer that would take an Escape press.
+ *
+ * @deprecated The focus trap no longer owns Escape coordination — every overlay
+ *   family shares one stack (`useLayerDismissal`), which routes each press to
+ *   the top-most layer. A layer that wants the same ordering should join the
+ *   stack rather than ask whether a trap exists.
  */
 export function hasActiveFocusTrapEscape(): boolean {
-  return escapeStack.length > 0;
+  return activeEscapeTrapCount > 0;
 }
 
 /**
@@ -243,6 +189,38 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
   // Track if focus change was triggered by keyboard (Tab key)
   const isKeyboardNavigationRef = useRef(false);
 
+  // Join the shared layer dismissal stack. The trap no longer listens for
+  // Escape itself: the stack owns one listener and routes each press to the
+  // top-most layer, so a popover inside a Dialog, a submenu inside a menu, and
+  // a modal inside a modal all peel off one at a time. A trap with no
+  // `onEscape` is not dismissible and stays off the stack, so a press flows
+  // past it to whatever is underneath.
+  // One expression drives both the stack registration and the deprecated
+  // `hasActiveFocusTrapEscape` count, so the two can never disagree about
+  // whether this trap is active.
+  const isEscapeTrap = isActive && onEscape != null;
+
+  useLayerDismissal({
+    isActive: isEscapeTrap,
+    onDismiss: () => {
+      onEscape?.();
+    },
+    // The trap renders nothing, so it cannot push a depth provider around its
+    // content; hand the stack the container instead so two DOM-nested traps
+    // still resolve in the right order.
+    getContainer: () => containerRef.current,
+  });
+
+  useEffect(() => {
+    if (!isEscapeTrap) {
+      return;
+    }
+    activeEscapeTrapCount += 1;
+    return () => {
+      activeEscapeTrapCount -= 1;
+    };
+  }, [isEscapeTrap]);
+
   /**
    * Focus the first focusable element.
    */
@@ -353,53 +331,25 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
   }, [isActive]);
 
   /**
-   * Handle Tab key to wrap focus at boundaries, and Escape to close.
-   * Also tracks that keyboard navigation is occurring.
+   * Handle Tab key to wrap focus at boundaries. Also tracks that keyboard
+   * navigation is occurring.
+   *
+   * No Escape here, and no IME guard: the shared stack owns the press, claims
+   * a composing Escape so no close request follows, and dismisses the trap
+   * through `onEscape` above. The trap renders no element of its own, so it
+   * has no `cancel` to answer either.
    */
   useEffect(() => {
     if (!isActive) {
       return;
     }
 
-    // Register this trap on the shared Escape stack so only the top-most
-    // active trap responds to Escape. A stable identity per active period is
-    // enough — we push on activate and remove on cleanup. The container is
-    // read lazily: the ref may not be attached yet at effect time, and the
-    // stack resolves top-most by DOM containment at keydown time.
-    const escapeHandler = () => {
-      onEscape?.();
-    };
-    if (onEscape) {
-      pushEscapeHandler({
-        handler: escapeHandler,
-        getContainer: () => containerRef.current,
-      });
-    }
-
     const handleKeyDown = (event: KeyboardEvent) => {
       const container = containerRef.current;
       if (!container) {
         return;
       }
 
-      if (event.key === 'Escape' && onEscape) {
-        // Ignore Escape that is cancelling an IME composition, already handled
-        // by a nested handler, or not targeting the top-most trap.
-        if (
-          event.defaultPrevented ||
-          isImeKeyEvent(event) ||
-          !isTopEscapeHandler(escapeHandler)
-        ) {
-          return;
-        }
-        // Mark handled and stop propagation so an outer layer (e.g. a Dialog
-        // hosting this popover) does not also dismiss on the same press.
-        event.preventDefault();
-        event.stopPropagation();
-        onEscape();
-        return;
-      }
-
       if (event.key === 'Tab') {
         // Mark that keyboard navigation is happening
         isKeyboardNavigationRef.current = true;
@@ -441,9 +391,6 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
 
     return () => {
       document.removeEventListener('keydown', handleKeyDown);
-      if (onEscape) {
-        removeEscapeHandler(escapeHandler);
-      }
     };
   }, [isActive, onEscape]);
 

package/src/hooks/useFocusTrapEscapeShim.test.tsx

@@ -0,0 +1,165 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useFocusTrapEscapeShim.test.tsx
+ * @input Uses vitest, @testing-library/react, useFocusTrap, Dialog, Lightbox,
+ *   MobileNav, Tooltip, Popover
+ * @output Tests that hasActiveFocusTrapEscape still means what it meant in
+ *   0.4.2 — an Escape-dismissible FOCUS TRAP is active, not "a layer is open"
+ * @position Testing; guards the deprecated public shim in useFocusTrap.ts
+ *
+ * The shim is public API. Its answer must not change now that Escape moved to
+ * the shared stack: `BottomSheetSwitcher` gates its own dismissal on it, so a
+ * shim that also counts tooltips, hover cards and dialogs tells the sheet a
+ * trap is above it when none is, and the sheet stops closing.
+ *
+ * SYNC: When useFocusTrap.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {render} from '@testing-library/react';
+
+import {hasActiveFocusTrapEscape, useFocusTrap} from './useFocusTrap';
+import {Dialog} from '../Dialog/Dialog';
+import {Lightbox} from '../Lightbox/Lightbox';
+import {MobileNav} from '../MobileNav/MobileNav';
+import {Popover} from '../Popover/Popover';
+import {Tooltip} from '../Tooltip/Tooltip';
+import {resetLayerStackForTests} from '../Layer/layerStack';
+
+beforeEach(() => {
+  HTMLDialogElement.prototype.showModal = vi.fn(function (
+    this: HTMLDialogElement,
+  ) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  });
+});
+
+afterEach(() => {
+  resetLayerStackForTests();
+});
+
+function Trap({
+  isActive = true,
+  hasEscape = true,
+  children,
+}: {
+  isActive?: boolean;
+  hasEscape?: boolean;
+  children?: React.ReactNode;
+}) {
+  const {containerRef} = useFocusTrap<HTMLDivElement>({
+    isActive,
+    onEscape: hasEscape ? () => {} : undefined,
+  });
+  return <div ref={containerRef}>{children}</div>;
+}
+
+describe('hasActiveFocusTrapEscape', () => {
+  it('is false with nothing mounted', () => {
+    expect(hasActiveFocusTrapEscape()).toBe(false);
+  });
+
+  it('is true for an active trap with an Escape handler', () => {
+    render(<Trap />);
+    expect(hasActiveFocusTrapEscape()).toBe(true);
+  });
+
+  it('is false for a trap with no Escape handler', () => {
+    render(<Trap hasEscape={false} />);
+    expect(hasActiveFocusTrapEscape()).toBe(false);
+  });
+
+  it('is false for an inactive trap', () => {
+    render(<Trap isActive={false} />);
+    expect(hasActiveFocusTrapEscape()).toBe(false);
+  });
+
+  it('is true for nested traps, and false again once both unmount', () => {
+    const {unmount} = render(
+      <Trap>
+        <Trap />
+      </Trap>,
+    );
+    expect(hasActiveFocusTrapEscape()).toBe(true);
+    unmount();
+    expect(hasActiveFocusTrapEscape()).toBe(false);
+  });
+
+  it('is true for an open Popover, which traps focus', () => {
+    render(
+      <Popover
+        isOpen={true}
+        onOpenChange={() => {}}
+        content="Popover body"
+        label="Popover">
+        <button type="button">Open</button>
+      </Popover>,
+    );
+    expect(hasActiveFocusTrapEscape()).toBe(true);
+  });
+
+  // The families below are all on the shared dismissal stack and none of them
+  // traps focus. Answering `true` for these is what broke the bottom sheet.
+  it('is false for an open Dialog', () => {
+    render(
+      <Dialog isOpen={true} onOpenChange={() => {}} aria-label="Dialog">
+        Body
+      </Dialog>,
+    );
+    expect(hasActiveFocusTrapEscape()).toBe(false);
+  });
+
+  it('is false for an open Lightbox', () => {
+    render(
+      <Lightbox
+        isOpen={true}
+        onOpenChange={() => {}}
+        media={{src: '/photo.jpg', alt: 'A photo'}}
+      />,
+    );
+    expect(hasActiveFocusTrapEscape()).toBe(false);
+  });
+
+  it('is false for an open MobileNav', () => {
+    render(
+      <MobileNav isOpen={true} onOpenChange={() => {}} label="Drawer">
+        <span>Nav</span>
+      </MobileNav>,
+    );
+    expect(hasActiveFocusTrapEscape()).toBe(false);
+  });
+
+  it('is false for a showing Tooltip', () => {
+    render(
+      <Tooltip content="Tip" isDefaultOpen={true}>
+        <button type="button">Trigger</button>
+      </Tooltip>,
+    );
+    expect(hasActiveFocusTrapEscape()).toBe(false);
+  });
+
+  it('is true for a Popover inside a Dialog, and false once the Popover closes', () => {
+    function Scene({isPopoverOpen}: {isPopoverOpen: boolean}) {
+      return (
+        <Dialog isOpen={true} onOpenChange={() => {}} aria-label="Dialog">
+          <Popover
+            isOpen={isPopoverOpen}
+            onOpenChange={() => {}}
+            content="Popover body"
+            label="Popover">
+            <button type="button">Open</button>
+          </Popover>
+        </Dialog>
+      );
+    }
+    const {rerender} = render(<Scene isPopoverOpen={true} />);
+    expect(hasActiveFocusTrapEscape()).toBe(true);
+
+    rerender(<Scene isPopoverOpen={false} />);
+    expect(hasActiveFocusTrapEscape()).toBe(false);
+  });
+});

package/src/hooks/useHotkeys.test.ts

@@ -67,6 +67,24 @@ describe('useHotkeys', () => {
     expect(onPress).toHaveBeenCalledTimes(1);
   });
 
+  it('reads a blank userAgentData.platform as unknown, not as non-Apple', () => {
+    // Builds that rewrite their client-hints identity expose the key with an
+    // empty value; navigator.platform is the only surface left that answers.
+    vi.stubGlobal('navigator', {
+      userAgentData: {platform: ''},
+      platform: 'MacIntel',
+    });
+    const onPress = vi.fn();
+    renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
+
+    press('k', {ctrlKey: true});
+    expect(onPress).not.toHaveBeenCalled();
+
+    const event = press('k', {metaKey: true});
+    expect(onPress).toHaveBeenCalledTimes(1);
+    expect(onPress).toHaveBeenCalledWith(event);
+  });
+
   it('does not fire a bare key when modifiers are held', () => {
     stubApplePlatform();
     const onPress = vi.fn();

package/src/hooks/useHotkeys.ts

@@ -73,8 +73,9 @@ const KEY_ALIASES: Record<string, string> = {
 
 /**
  * Detects whether the current platform is macOS/iOS.
- * Prefers the User-Agent Client Hints API when available (modern Chrome/Edge),
- * falls back to navigator.platform (deprecated but universally supported).
+ * Prefers the User-Agent Client Hints API when it names a platform (modern
+ * Chrome/Edge), falls back to navigator.platform (deprecated but universally
+ * supported) when it is absent or blank.
  * Mirrors the detection used by Kbd so displayed and handled shortcuts agree.
  */
 function isApplePlatform(): boolean {
@@ -83,7 +84,13 @@ function isApplePlatform(): boolean {
   }
   const uaData = 'userAgentData' in navigator ? navigator.userAgentData : null;
   if (uaData && typeof uaData === 'object' && 'platform' in uaData) {
-    return /mac/i.test((uaData as {platform: string}).platform ?? '');
+    const uaPlatform = (uaData as {platform?: unknown}).platform;
+    // A blank platform is no answer, not a negative one. Builds that rewrite
+    // their client-hints identity ship '', so fall through rather than
+    // reading it as "not Apple".
+    if (typeof uaPlatform === 'string' && uaPlatform.trim() !== '') {
+      return /mac/i.test(uaPlatform);
+    }
   }
   return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');
 }

package/src/hooks/useListFocus.doc.mjs

@@ -36,7 +36,7 @@ export const docs = {
     {
       name: 'options.onEscape',
       type: '() => void',
-      description: 'Callback when Escape key is pressed (e.g., close menu).',
+      description: 'Callback when Escape key is pressed (e.g., close menu). Supplying it also consumes the key (preventDefault); without it Escape passes through to the surrounding layer.',
       required: false,
     },
     {
@@ -144,7 +144,7 @@ export const docsDense = {
     'options.itemSelector': 'selector for focusable items in list.',
     'options.boundarySelector': "boundary selector for lists that contain nested lists (e.g. submenu flyouts); scopes items + key handling to this level.",
     'options.wrap': 'whether arrow navigation wraps around at ends.',
-    'options.onEscape': 'callback when Escape key pressed (e.g. close menu).',
+    'options.onEscape': 'callback when Escape key pressed (e.g. close menu). Also consumes the key; without it Escape passes through to the surrounding layer.',
     'options.orientation': "navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown, 'both' accepts all four arrows.",
     'options.hasHomeEnd': 'whether Home/End jump to first/last enabled item.',
     'options.isRtl': 'ArrowLeft/ArrowRight swap for horizontal nav (RTL). default: auto-detect from container computed direction; explicit boolean wins.',

package/src/hooks/useListFocus.test.tsx

@@ -3,14 +3,14 @@
 /**
  * @file useListFocus.test.tsx
  * @input Uses vitest, @testing-library/react, useListFocus hook
- * @output Unit tests for useListFocus disabled-item skipping, navigation, and
- *   RTL auto-detection
+ * @output Unit tests for useListFocus disabled-item skipping, navigation,
+ *   Escape consumption, and RTL auto-detection
  * @position Testing; validates useListFocus.ts keyboard navigation
  *
  * SYNC: When useListFocus.ts changes, update tests to match new behavior
  */
 
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, vi} from 'vitest';
 import type {KeyboardEvent as ReactKeyboardEvent} from 'react';
 import {render, screen, fireEvent} from '@testing-library/react';
 import {useListFocus} from './useListFocus';
@@ -525,3 +525,65 @@ describe('useListFocus boundarySelector (nested lists)', () => {
     expect(innerProbe).toHaveAttribute('data-owns', 'false');
   });
 });
+
+// A list inside a host that dismisses on Escape. The host's guard mirrors
+// `useFocusTrap`: it acts only on a key no inner handler has consumed.
+function EscapeHost({
+  onEscape,
+  onHostEscape,
+}: {
+  onEscape?: () => void;
+  onHostEscape: () => void;
+}) {
+  const {listRef, handleKeyDown} = useListFocus<HTMLDivElement>({onEscape});
+  return (
+    <div
+      data-testid="host"
+      onKeyDown={e => {
+        if (e.key === 'Escape' && !e.defaultPrevented) {
+          onHostEscape();
+        }
+      }}>
+      <div ref={listRef} role="menu" onKeyDown={handleKeyDown}>
+        <div role="menuitem" tabIndex={-1} data-testid="One">
+          One
+        </div>
+        <div role="menuitem" tabIndex={-1} data-testid="Two">
+          Two
+        </div>
+      </div>
+    </div>
+  );
+}
+
+describe('useListFocus Escape', () => {
+  it('leaves Escape to the host when no onEscape is supplied', () => {
+    const onHostEscape = vi.fn();
+    render(<EscapeHost onHostEscape={onHostEscape} />);
+
+    fireEvent.keyDown(screen.getByRole('menu'), {key: 'Escape'});
+    expect(onHostEscape).toHaveBeenCalledTimes(1);
+  });
+
+  it('consumes Escape and runs onEscape when one is supplied', () => {
+    const onEscape = vi.fn();
+    const onHostEscape = vi.fn();
+    render(<EscapeHost onEscape={onEscape} onHostEscape={onHostEscape} />);
+
+    fireEvent.keyDown(screen.getByRole('menu'), {key: 'Escape'});
+    expect(onEscape).toHaveBeenCalledTimes(1);
+    expect(onHostEscape).not.toHaveBeenCalled();
+  });
+
+  it('still consumes arrow keys with no onEscape (page-scroll suppression)', () => {
+    render(<EscapeHost onHostEscape={() => {}} />);
+    screen.getByTestId('One').focus();
+
+    // fireEvent returns false when a handler cancelled the event.
+    const wasCancelled = !fireEvent.keyDown(screen.getByRole('menu'), {
+      key: 'ArrowDown',
+    });
+    expect(wasCancelled).toBe(true);
+    expect(screen.getByTestId('Two')).toHaveFocus();
+  });
+});