@astryxdesign/core 0.4.7 → 0.5.0-canary.32a62fd

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;
-    }
-  }
-}
+// 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;
 
 /**
- * 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;
-}
-
-/**
- * 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,67 +331,43 @@ 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;
 
         const focusable = getFocusableElements(container);
         if (focusable.length === 0) {
+          const active = document.activeElement;
+          if (!(active instanceof HTMLElement) || !container.contains(active)) {
+            // A layer can be open while focus legitimately sits outside it —
+            // a listbox popup anchored to its own input. Cancelling there
+            // would take Tab away from the whole page.
+            return;
+          }
           // 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;
-          }
+          lastFocusRef.current = active;
           isKeyboardNavigationRef.current = false;
           return;
         }
@@ -441,9 +395,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.ts

@@ -18,7 +18,8 @@
  * unless a hotkey opts in via `allowInInputs`.
  *
  * Platform-aware: `mod` maps to metaKey (⌘) on Apple platforms and
- * ctrlKey elsewhere — mirrors the detection used by Kbd.
+ * ctrlKey elsewhere, through the same isApplePlatform util Kbd reads, so
+ * displayed and handled shortcuts cannot disagree.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
@@ -26,6 +27,7 @@
  */
 
 import {useEffect, useRef} from 'react';
+import {isApplePlatform} from '../utils/isApplePlatform';
 
 /**
  * A single keyboard shortcut registration.
@@ -71,23 +73,6 @@ const KEY_ALIASES: Record<string, string> = {
   plus: '+',
 };
 
-/**
- * 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).
- * Mirrors the detection used by Kbd so displayed and handled shortcuts agree.
- */
-function isApplePlatform(): boolean {
-  if (typeof navigator === 'undefined') {
-    return false;
-  }
-  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 ?? '');
-  }
-  return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');
-}
-
 /**
  * Whether the event target is a typing surface where global shortcuts
  * should stay silent by default.

package/src/hooks/useMergedRefs.doc.mjs

@@ -0,0 +1,79 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useMergedRefs',
+  displayName: 'useMergedRefs',
+  keywords: [
+    'ref',
+    'refs',
+    'merge',
+    'forwardRef',
+    'callback ref',
+    'stable ref',
+  ],
+  params: [
+    {
+      name: 'refs',
+      type: 'Array<Ref<T> | undefined>',
+      description: 'Up to six refs that should all receive the same element.',
+      required: true,
+    },
+  ],
+  returns: [
+    {
+      name: 'ref',
+      type: 'RefCallback<T>',
+      description:
+        'A merged callback ref that remains stable until an input ref changes.',
+    },
+  ],
+  usage: {
+    description:
+      'Combines multiple object or callback refs into one stable callback ref. Use it when a component must forward a consumer ref while also attaching internal refs. Unlike calling mergeRefs during render, the callback identity stays stable across unrelated rerenders, so React does not detach and reattach the element.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use useMergedRefs when one element must receive both a forwarded ref and one or more internal refs.',
+      },
+      {
+        guidance: false,
+        description:
+          'Call mergeRefs directly in a JSX ref prop; that creates a new callback on every render and forces unnecessary detach and attach work.',
+      },
+    ],
+  },
+  relatedComponents: [],
+  relatedHooks: [],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'utility',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Combines object/callback refs into one stable callback ref. Identity changes only when an input ref changes, avoiding detach/attach churn from inline mergeRefs calls.',
+  paramDescriptions: {
+    refs: 'refs that should all receive the same element.',
+  },
+  returnDescriptions: {
+    ref: 'stable merged callback ref; changes only when an input ref changes.',
+  },
+  usage: {
+    description:
+      'Use when one element needs a forwarded consumer ref plus internal refs. Keeps the callback stable across unrelated rerenders.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use for a forwarded ref plus internal measurement, focus, or anchor refs.',
+      },
+      {
+        guidance: false,
+        description:
+          'Call mergeRefs inline in JSX; it forces ref detach/attach on every render.',
+      },
+    ],
+  },
+};

package/src/hooks/useMergedRefs.test.tsx

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useMergedRefs.test.tsx
+ * @input Uses vitest, @testing-library/react, useMergedRefs hook
+ * @output Unit tests for stable merged ref behavior
+ * @position Testing; validates useMergedRefs.ts
+ *
+ * SYNC: When useMergedRefs.ts changes, update tests to match new behavior
+ */
+
+import {renderHook} from '@testing-library/react';
+import {createRef} from 'react';
+import {describe, expect, it, vi} from 'vitest';
+import {useMergedRefs} from './useMergedRefs';
+
+describe('useMergedRefs', () => {
+  it('forwards values to callback and object refs', () => {
+    const callbackRef = vi.fn();
+    const objectRef = createRef<HTMLDivElement>();
+    const {result} = renderHook(() =>
+      useMergedRefs<HTMLDivElement>(callbackRef, objectRef),
+    );
+    const element = document.createElement('div');
+
+    const cleanup = result.current(element);
+
+    expect(callbackRef).toHaveBeenCalledWith(element);
+    expect(objectRef.current).toBe(element);
+
+    cleanup?.();
+    expect(callbackRef).toHaveBeenLastCalledWith(null);
+    expect(objectRef.current).toBeNull();
+  });
+
+  it('keeps the merged callback stable when input refs are unchanged', () => {
+    const callbackRef = vi.fn();
+    const objectRef = createRef<HTMLDivElement>();
+    const {result, rerender} = renderHook(() =>
+      useMergedRefs<HTMLDivElement>(callbackRef, objectRef),
+    );
+    const first = result.current;
+
+    rerender();
+
+    expect(result.current).toBe(first);
+  });
+
+  it('updates the merged callback when an input ref changes', () => {
+    const firstRef = vi.fn();
+    const secondRef = vi.fn();
+    const {result, rerender} = renderHook(
+      ({ref}) => useMergedRefs<HTMLDivElement>(ref),
+      {initialProps: {ref: firstRef}},
+    );
+    const first = result.current;
+
+    rerender({ref: secondRef});
+
+    expect(result.current).not.toBe(first);
+  });
+});

package/src/hooks/useMergedRefs.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useMergedRefs.ts
+ * @input React refs to combine into one stable callback ref
+ * @output Exports useMergedRefs
+ * @position Core hook; use when one element must receive multiple refs
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/useMergedRefs.doc.mjs
+ * - /packages/core/src/hooks/useMergedRefs.test.tsx
+ */
+
+import {useMemo, type Ref, type RefCallback} from 'react';
+import {mergeRefs} from '../utils/mergeRefs';
+
+/**
+ * Combine up to six refs into a callback ref whose identity changes only when
+ * one of the input refs changes.
+ */
+export function useMergedRefs<T>(
+  refA?: Ref<T>,
+  refB?: Ref<T>,
+  refC?: Ref<T>,
+  refD?: Ref<T>,
+  refE?: Ref<T>,
+  refF?: Ref<T>,
+): RefCallback<T> {
+  return useMemo(
+    () => mergeRefs(refA, refB, refC, refD, refE, refF),
+    [refA, refB, refC, refD, refE, refF],
+  );
+}

package/src/index.ts

@@ -55,6 +55,7 @@ export * from './NavIcon';
 export * from './NavMenu';
 export * from './Slider';
 export * from './Stack';
+export * from './Stepper';
 export * from './Switch';
 export * from './DateInput';
 export * from './DateTimeInput';

package/src/theme/MediaTheme.doc.mjs

@@ -68,7 +68,7 @@ export const docs = {
       {
         guidance: true,
         description:
-          'Prefer mode="auto" when the surface color comes from a theme token. A token named "inverted" is not guaranteed to be inverted, and auto measures what was actually painted instead of trusting the name — including deciding that a surface needs no media context at all.',
+          'Prefer mode="auto" when the surface color comes from a theme token. A token named "inverted" is not guaranteed to be inverted, and auto measures what was actually painted instead of trusting the name. It can even decide that a surface needs no media context at all.',
       },
       {
         guidance: true,
@@ -93,14 +93,14 @@ export const docs = {
       type: "'dark' | 'light' | 'auto' | 'off'",
       required: true,
       description:
-        'Surface luminance context: dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions), auto to decide from the painted surface — no media context when the ambient text already reads on the surface (3:1), otherwise the side that reads better — and off to turn it off explicitly. The element renders either way, so a surface can switch contexts without remounting children.',
+        'Surface luminance context: dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions), auto to decide from the painted surface (no media context when the ambient text already reads on the surface at 3:1, otherwise the side that reads better), and off to turn it off explicitly. The element renders either way, so a surface can switch contexts without remounting children.',
     },
     {
       name: 'fallback',
       type: "'dark' | 'light'",
       default: "'dark'",
       description:
-        'Which side auto uses when the surface cannot be measured: during SSR, on the first client frame, and whenever the backdrop is not knowable from CSS — most often a background-image, whose pixels need sampling (useImageMode) rather than a computed style. Ignored unless mode is auto.',
+        'Which side auto uses when the surface cannot be measured: during SSR, on the first client frame, and whenever the backdrop is not knowable from CSS, most often a background-image, whose pixels need sampling (useImageMode) rather than a computed style. Ignored unless mode is auto.',
     },
     {
       name: 'children',
@@ -126,7 +126,7 @@ export const docsDense = {
       {
         guidance: true,
         description:
-          'Prefer mode="auto" when surface color comes from a theme token — a token named "inverted" is not guaranteed to be; auto measures what was painted.',
+          'Prefer mode="auto" when surface color comes from a theme token; a token named "inverted" is not guaranteed to be; auto measures what was painted.',
       },
       {
         guidance: true,
@@ -148,6 +148,6 @@ export const docsDense = {
   propDescriptions: {
     mode: 'surface luminance context: dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions), auto to decide from painted surface (none if ambient text already reads at 3:1, else better-reading side), off to turn off explicitly (element still renders, so children never remount)',
     fallback:
-      'side auto uses when surface is unmeasurable (SSR, first frame, background-image — those need useImageMode sampling); ignored unless mode is auto',
+      'side auto uses when surface is unmeasurable (SSR, first frame, background-image, which needs useImageMode sampling); ignored unless mode is auto',
   },
 };