@astryxdesign/core 0.7.8 → 0.7.9-canary.0200dfe

package/src/hooks/useFocusTrap.ts

@@ -5,7 +5,8 @@
 /**
  * @file useFocusTrap.ts
  * @input Uses React useCallback, useEffect, useRef
- * @output Exports useFocusTrap, the deprecated Escape-state shim, and an
+ * @output Exports useFocusTrap, the internal focus-region Tab containment it
+ *   composes, the deprecated Escape-state shim, and an
  *   internal compatibility-signal hook
  * @position Core hook; used by dialogs, modals, date pickers
  *
@@ -63,6 +64,19 @@ export function useFocusTrapEscapeCompatibilitySignal(isActive: boolean): void {
   }, [isActive]);
 }
 
+/**
+ * Whether an element is shown as a popover. jsdom and browsers without the
+ * Popover API do not recognize `:popover-open`, and nothing is popover-open
+ * there.
+ */
+function isPopoverOpen(el: Element): boolean {
+  try {
+    return el.matches(':popover-open');
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Whether an element is currently perceivable/focusable — excludes ones hidden
  * via `display:none`/`visibility:hidden` or inside an `inert`/`hidden` subtree,
@@ -77,6 +91,18 @@ function isVisiblyFocusable(el: HTMLElement): boolean {
   if (el.hidden || el.closest('[hidden]')) {
     return false;
   }
+  // A closed <dialog> renders nothing, so nothing inside it can take focus.
+  // A dialog shown with showPopover() (a non-modal sheet or drawer) never
+  // sets `open`, so it counts as shown while it is popover-open.
+  for (
+    let dialog = el.closest('dialog');
+    dialog != null;
+    dialog = dialog.parentElement?.closest('dialog') ?? null
+  ) {
+    if (!dialog.open && !isPopoverOpen(dialog)) {
+      return false;
+    }
+  }
   // closest() matches the element itself as well as any ancestor.
   if (el.closest('[aria-hidden="true"]')) {
     return false;
@@ -125,6 +151,15 @@ function isHTMLElement(node: Node | null): node is HTMLElement {
   return view != null && node instanceof view.HTMLElement;
 }
 
+/**
+ * Whether node `a` comes before node `b` in document order.
+ */
+function precedes(a: Node, b: Node): boolean {
+  return (
+    (a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0
+  );
+}
+
 /**
  * Attempt to focus an element. Returns true if focus was successful.
  */
@@ -137,6 +172,18 @@ function attemptFocus(element: HTMLElement): boolean {
   return element.ownerDocument.activeElement === element;
 }
 
+/**
+ * Wrap focus to `target` for a Tab press, and cancel the press only when the
+ * target took focus. A target the browser refuses (inert behind a modal
+ * layered over this region) leaves the press to the browser instead of
+ * stranding focus where it was.
+ */
+function wrapFocus(event: KeyboardEvent, target: HTMLElement): void {
+  if (attemptFocus(target)) {
+    event.preventDefault();
+  }
+}
+
 /**
  * Focus the first focusable descendant of a container.
  * Returns true if a focusable element was found and focused.
@@ -165,6 +212,223 @@ function focusLastDescendant(container: HTMLElement): boolean {
   return false;
 }
 
+// Containers of the focus regions currently active, in every document. A Tab
+// is answered by the innermost region that holds focus, so regions that nest
+// in the DOM never fight over one key press.
+const activeRegionContainers = new Set<HTMLElement>();
+
+function hasInnerRegionHolding(
+  container: HTMLElement,
+  active: Element,
+): boolean {
+  // An open <dialog> nested in the region that holds focus is its own focus
+  // context (a modal step over a covered sheet): it answers Tab, not us.
+  const dialog = active.closest('dialog[open]');
+  if (dialog != null && dialog !== container && container.contains(dialog)) {
+    return true;
+  }
+  for (const other of activeRegionContainers) {
+    if (
+      other !== container &&
+      container.contains(other) &&
+      other.contains(active)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Tab containment for a focus region: Tab and Shift+Tab pressed inside wrap at
+ * either end, and a Tab that starts outside is left to the page. When regions
+ * nest, the innermost one holding focus answers.
+ *
+ * `useFocusTrap` composes this. Dialog, BottomSheet and Lightbox call it
+ * directly, because their native lifecycle already owns focus entry and
+ * return. Internal: not re-exported from `hooks`.
+ */
+export function useFocusRegionContainment(
+  containerRef: React.RefObject<HTMLElement | null>,
+  isActive: boolean,
+): void {
+  const lastFocusRef = useRef<Element | null>(null);
+  // Track if focus change was triggered by keyboard (Tab key)
+  const isKeyboardNavigationRef = useRef(false);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!isActive || container == null) {
+      return;
+    }
+    activeRegionContainers.add(container);
+    return () => {
+      activeRegionContainers.delete(container);
+    };
+  }, [containerRef, isActive]);
+
+  /**
+   * Handle focus events - redirect focus back into container if it escapes.
+   * Only redirects for keyboard navigation, not mouse clicks.
+   */
+  useEffect(() => {
+    if (!isActive) {
+      return;
+    }
+
+    const doc = trapDocument(containerRef.current);
+
+    const handleFocus = (event: FocusEvent) => {
+      const container = containerRef.current;
+      if (!container) {
+        return;
+      }
+
+      const target = event.target as Node;
+
+      if (container.contains(target)) {
+        // Focus is inside the container - track it
+        lastFocusRef.current = target as Element;
+      } else if (isKeyboardNavigationRef.current) {
+        // Focus escaped via keyboard - redirect it back
+        const focusedFirst = focusFirstDescendant(container);
+
+        // If we're back at the same element (Shift+Tab from first element),
+        // try focusing the last element instead
+        if (focusedFirst && lastFocusRef.current === doc.activeElement) {
+          focusLastDescendant(container);
+        } else if (
+          !focusedFirst &&
+          isHTMLElement(lastFocusRef.current) &&
+          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 = doc.activeElement;
+      }
+      // If focus escaped via mouse click, don't redirect - let light dismiss handle it
+
+      // Reset keyboard navigation flag
+      isKeyboardNavigationRef.current = false;
+    };
+
+    // Use capture phase to intercept focus before it settles
+    doc.addEventListener('focus', handleFocus, true);
+
+    return () => {
+      doc.removeEventListener('focus', handleFocus, true);
+    };
+  }, [containerRef, isActive]);
+
+  /**
+   * Handle Tab key to wrap focus at boundaries. Also tracks that keyboard
+   * navigation is occurring.
+   *
+   * No Escape here, and no IME guard: the shared layer dismissal stack owns
+   * that press, and each surface that applies a region decides its own
+   * dismissal (`useFocusTrap` through its `onEscape`).
+   */
+  useEffect(() => {
+    if (!isActive) {
+      return;
+    }
+
+    const doc = trapDocument(containerRef.current);
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      const container = containerRef.current;
+      if (!container) {
+        return;
+      }
+
+      if (event.key === 'Tab') {
+        if (event.defaultPrevented) {
+          // A control that handles Tab itself (an editor that indents) keeps
+          // focus where it is.
+          return;
+        }
+        const active = doc.activeElement;
+        // Any focused node counts, not only HTML elements: an SVG control
+        // inside the container is still inside.
+        if (active == null || !container.contains(active)) {
+          // The trap contains focus that is inside it; it does not pull in a
+          // Tab pressed elsewhere on the page. A layer can be open while focus
+          // legitimately sits outside it — a listbox popup anchored to its own
+          // input, a non-modal popover beside the content it annotates — and
+          // capturing that Tab would take the rest of the page away from
+          // keyboard users.
+          return;
+        }
+
+        if (hasInnerRegionHolding(container, active)) {
+          // A region nested in this one (a Dialog opened from a Dialog, a
+          // Popover inside a Drawer) holds focus; that region answers Tab.
+          return;
+        }
+
+        // Mark that keyboard navigation is leaving from inside the trap, so a
+        // focus that lands outside is redirected back in.
+        isKeyboardNavigationRef.current = true;
+
+        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();
+          lastFocusRef.current = active;
+          isKeyboardNavigationRef.current = false;
+          return;
+        }
+
+        const first = focusable[0];
+        const last = focusable[focusable.length - 1];
+
+        if (doc.activeElement === container) {
+          // Programmatic initial focus can sit on the trap container itself
+          // (for example a dialog panel with no content controls). Move into
+          // the tabbable cycle instead of letting Tab escape to the page.
+          wrapFocus(event, event.shiftKey ? last : first);
+          return;
+        }
+
+        // Programmatic focus can also sit on an element that is not a Tab stop
+        // (a dialog title with tabIndex -1). Its place in document order
+        // decides the edge: nothing tabbable before it means Shift+Tab is
+        // leaving the region, nothing after it means Tab is.
+        const isProgrammaticStop = !(focusable as Element[]).includes(active);
+        if (event.shiftKey) {
+          // Shift+Tab: if on (or before) the first element, wrap to last
+          if (
+            active === first ||
+            (isProgrammaticStop && precedes(active, first))
+          ) {
+            wrapFocus(event, last);
+          }
+        } else {
+          // Tab: if on (or after) the last element, wrap to first
+          if (
+            active === last ||
+            (isProgrammaticStop && precedes(last, active))
+          ) {
+            wrapFocus(event, first);
+          }
+        }
+      }
+    };
+
+    doc.addEventListener('keydown', handleKeyDown);
+
+    return () => {
+      doc.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [containerRef, isActive]);
+}
+
 /**
  * Configuration for focus trap behavior
  */
@@ -255,9 +519,9 @@ export function useFocusTrapInternal<T extends HTMLElement = HTMLElement>(
   getRestoreTargetRef.current = getRestoreTarget;
 
   const containerRef = useRef<T | null>(null);
-  const lastFocusRef = useRef<Element | null>(null);
-  // Track if focus change was triggered by keyboard (Tab key)
-  const isKeyboardNavigationRef = useRef(false);
+
+  // Tab and Shift+Tab wrap inside the container while the trap is active.
+  useFocusRegionContainment(containerRef, isActive);
 
   // 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
@@ -365,153 +629,6 @@ export function useFocusTrapInternal<T extends HTMLElement = HTMLElement>(
     };
   }, [isActive]);
 
-  /**
-   * Handle focus events - redirect focus back into container if it escapes.
-   * Only redirects for keyboard navigation, not mouse clicks.
-   */
-  useEffect(() => {
-    if (!isActive) {
-      return;
-    }
-
-    const doc = trapDocument(containerRef.current);
-
-    const handleFocus = (event: FocusEvent) => {
-      const container = containerRef.current;
-      if (!container) {
-        return;
-      }
-
-      const target = event.target as Node;
-
-      if (container.contains(target)) {
-        // Focus is inside the container - track it
-        lastFocusRef.current = target as Element;
-      } else if (isKeyboardNavigationRef.current) {
-        // Focus escaped via keyboard - redirect it back
-        const focusedFirst = focusFirstDescendant(container);
-
-        // If we're back at the same element (Shift+Tab from first element),
-        // try focusing the last element instead
-        if (focusedFirst && lastFocusRef.current === doc.activeElement) {
-          focusLastDescendant(container);
-        } else if (
-          !focusedFirst &&
-          isHTMLElement(lastFocusRef.current) &&
-          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 = doc.activeElement;
-      }
-      // If focus escaped via mouse click, don't redirect - let light dismiss handle it
-
-      // Reset keyboard navigation flag
-      isKeyboardNavigationRef.current = false;
-    };
-
-    // Use capture phase to intercept focus before it settles
-    doc.addEventListener('focus', handleFocus, true);
-
-    return () => {
-      doc.removeEventListener('focus', handleFocus, true);
-    };
-  }, [isActive]);
-
-  /**
-   * 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;
-    }
-
-    const doc = trapDocument(containerRef.current);
-
-    const handleKeyDown = (event: KeyboardEvent) => {
-      const container = containerRef.current;
-      if (!container) {
-        return;
-      }
-
-      if (event.key === 'Tab') {
-        const active = doc.activeElement;
-        // Any focused node counts, not only HTML elements: an SVG control
-        // inside the container is still inside.
-        if (active == null || !container.contains(active)) {
-          // The trap contains focus that is inside it; it does not pull in a
-          // Tab pressed elsewhere on the page. A layer can be open while focus
-          // legitimately sits outside it — a listbox popup anchored to its own
-          // input, a non-modal popover beside the content it annotates — and
-          // capturing that Tab would take the rest of the page away from
-          // keyboard users.
-          return;
-        }
-
-        // Mark that keyboard navigation is leaving from inside the trap, so a
-        // focus that lands outside is redirected back in.
-        isKeyboardNavigationRef.current = true;
-
-        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();
-          lastFocusRef.current = active;
-          isKeyboardNavigationRef.current = false;
-          return;
-        }
-
-        const first = focusable[0];
-        const last = focusable[focusable.length - 1];
-
-        if (doc.activeElement === container) {
-          // Programmatic initial focus can sit on the trap container itself
-          // (for example a dialog panel with no content controls). Move into
-          // the tabbable cycle instead of letting Tab escape to the page.
-          event.preventDefault();
-          if (event.shiftKey) {
-            last.focus();
-          } else {
-            first.focus();
-          }
-          return;
-        }
-
-        if (event.shiftKey) {
-          // Shift+Tab: if on first element, wrap to last
-          if (doc.activeElement === first) {
-            event.preventDefault();
-            last.focus();
-          }
-        } else {
-          // Tab: if on last element, wrap to first
-          if (doc.activeElement === last) {
-            event.preventDefault();
-            first.focus();
-          }
-        }
-      }
-    };
-
-    doc.addEventListener('keydown', handleKeyDown);
-
-    return () => {
-      doc.removeEventListener('keydown', handleKeyDown);
-    };
-  }, [isActive, onEscape]);
-
   return {
     containerRef,
     focusFirst,

package/src/hooks/useKeyboardHighlight.ts

@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useKeyboardHighlight.ts
+ * @input The owning combobox's shared modality reader and its keydown and
+ *   option-hover handlers
+ * @output Exports useKeyboardHighlight: whether the last highlight move came
+ *   from keyboard input, the handlers wrapped to record each move, and the
+ *   recorder for other paths that move the highlight
+ * @position Internal hook; used by Selector and MultiSelector to draw
+ *   keyboard-only highlight paint
+ */
+
+import {useCallback, useState} from 'react';
+import type {InteractionModality} from '../utils/interactionModality';
+
+interface KeyboardHighlight<
+  KeyArgs extends unknown[],
+  HoverArgs extends unknown[],
+> {
+  /** The last highlight move came from keyboard input. */
+  isKeyboardHighlight: boolean;
+  /** Records the current input for a path that moves the highlight. */
+  noteHighlightMove: () => void;
+  onKeyDown: (...args: KeyArgs) => void;
+  onItemMouseEnter: (...args: HoverArgs) => void;
+}
+
+/**
+ * A highlight moves from both keys and the pointer, but keyboard-only paint
+ * follows the shared interaction modality. The hook reads that modality each
+ * time the highlight moves.
+ */
+export function useKeyboardHighlight<
+  KeyArgs extends unknown[],
+  HoverArgs extends unknown[],
+>(
+  readModality: () => InteractionModality,
+  onKeyDown: (...args: KeyArgs) => void,
+  onItemMouseEnter: (...args: HoverArgs) => void,
+): KeyboardHighlight<KeyArgs, HoverArgs> {
+  const [isKeyboardHighlight, setIsKeyboardHighlight] = useState(
+    () => readModality() === 'keyboard',
+  );
+  const noteHighlightMove = useCallback(
+    () => setIsKeyboardHighlight(readModality() === 'keyboard'),
+    [readModality],
+  );
+  const handleKeyDown = useCallback(
+    (...args: KeyArgs) => {
+      onKeyDown(...args);
+      noteHighlightMove();
+    },
+    [onKeyDown, noteHighlightMove],
+  );
+  const handleItemMouseEnter = useCallback(
+    (...args: HoverArgs) => {
+      onItemMouseEnter(...args);
+      noteHighlightMove();
+    },
+    [onItemMouseEnter, noteHighlightMove],
+  );
+  return {
+    isKeyboardHighlight,
+    noteHighlightMove,
+    onKeyDown: handleKeyDown,
+    onItemMouseEnter: handleItemMouseEnter,
+  };
+}

package/src/hooks/useMediaQuery.ts

@@ -4,24 +4,61 @@
 
 /**
  * @file useMediaQuery.ts
- * @input Uses React useSyncExternalStore, useCallback
+ * @input Uses React useSyncExternalStore, useCallback, and watchMediaQuery
+ *   (utils/coarsePointer.ts)
  * @output Exports useMediaQuery hook for responsive breakpoint detection
  * @position Core hook; used by consumers for responsive patterns
  *
  * SSR-safe media query hook that subscribes to window.matchMedia changes
  * via useSyncExternalStore — the canonical React pattern for external
- * browser state.
+ * browser state. Every caller of a query shares one watch.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
  */
 
 import {useCallback, useSyncExternalStore} from 'react';
+import {watchMediaQuery} from '../utils/coarsePointer';
+
+interface SharedWatch {
+  readers: Set<() => void>;
+  stop: () => void;
+}
+
+const watches = new Map<string, SharedWatch>();
+
+function subscribeToQuery(query: string, reader: () => void): () => void {
+  // A DOM without `matchMedia`, such as a test DOM, has nothing to watch.
+  if (typeof window.matchMedia !== 'function') {
+    return () => {};
+  }
+  let watch = watches.get(query);
+  if (watch == null) {
+    const readers = new Set<() => void>();
+    const stop = watchMediaQuery(window, query, () => {
+      for (const each of Array.from(readers)) {
+        each();
+      }
+    });
+    watch = {readers, stop};
+    watches.set(query, watch);
+  }
+  const entry = watch;
+  entry.readers.add(reader);
+  return () => {
+    entry.readers.delete(reader);
+    if (entry.readers.size === 0 && watches.get(query) === entry) {
+      entry.stop();
+      watches.delete(query);
+    }
+  };
+}
 
 /**
  * SSR-safe media query hook.
  * Returns whether the given media query matches. Where the window has no
- * `matchMedia`, as in a test DOM, it returns `serverDefault`.
+ * `matchMedia`, as in a test DOM, it returns `serverDefault`. All callers of
+ * the same query share one listener.
  *
  * @param query - CSS media query string
  * @param serverDefault - Value to return during SSR. Pass a server-side hint
@@ -35,15 +72,7 @@ import {useCallback, useSyncExternalStore} from 'react';
  */
 export function useMediaQuery(query: string, serverDefault = false): boolean {
   const subscribe = useCallback(
-    (onStoreChange: () => void) => {
-      // A DOM without `matchMedia`, such as a test DOM, has nothing to watch.
-      if (typeof window.matchMedia !== 'function') {
-        return () => {};
-      }
-      const mql = window.matchMedia(query);
-      mql.addEventListener('change', onStoreChange);
-      return () => mql.removeEventListener('change', onStoreChange);
-    },
+    (onStoreChange: () => void) => subscribeToQuery(query, onStoreChange),
     [query],
   );