@astryxdesign/core 0.7.8 → 0.7.9-canary.07992bb

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/useMenuPress.ts

@@ -6,7 +6,8 @@
  * @file useMenuPress.ts
  * @input The menu root, its trigger, the enabled-row selector, and callbacks
  *   for opening, highlighting, activating and dismissing
- * @output useMenuPress, the marker attributes, and the activation mark
+ * @output useMenuPress, the marker attributes, the activation mark, and the
+ *   internal useDropdownMenuPress entry with its touch model
  * @position Core hook for DropdownMenu, ContextMenu, DropdownMenuSubMenu,
  *   Selector and MenuBottomSheetActionList. The transition table lives in
  *   menuPressGesture.ts.
@@ -29,10 +30,10 @@ import {
 import {currentGesture} from '../Layer/gestureCounter';
 import {
   IDLE_MENU_PRESS,
-  menuPressStep,
-  type MenuPressEffect,
-  type MenuPressEvent,
-  type MenuPressGesture,
+  menuPressTransition,
+  type MenuPressOutcome,
+  type MenuPressInput,
+  type MenuPressState,
   type MenuPressPointerType,
 } from './menuPressGesture';
 import {MENU_PRESS_MARKER} from './menuPressMarker';
@@ -45,6 +46,12 @@ import {edgeAutoscroll} from '../utils/edgeAutoscroll';
 import {focusForLastInput} from '../utils/focusReturn';
 import {useInteractionModalityTrackingFor} from '../utils/interactionModality';
 import {LONG_PRESS_DURATION_MS} from '../motion/uikit/longPress';
+import {
+  clearMenuPressLit,
+  holdMenuPressPaint,
+  markMenuPressLit,
+  releaseMenuPressPaint,
+} from '../privateAttributes/menuPressLit.stylex';
 import {
   __resetClickGuardForTest,
   armClickGuard,
@@ -235,6 +242,44 @@ interface ResolvedPoint {
   isOnTrigger: boolean;
 }
 
+/**
+ * DropdownMenu's options for the press model: everything the public hook
+ * takes, plus its touch model. DropdownMenu reaches the touch model through
+ * its `presentation`, so the public hook has no such option.
+ *
+ * @internal
+ */
+export interface DropdownMenuPressOptions extends UseMenuPressOptions {
+  /**
+   * How the finger that opened the menu from the trigger picks.
+   * `'pointer'`: its opening press follows the settle rule. `'uikit'`: it
+   * picks only after UIMenu's handoff distance, so the row that appeared
+   * under it never acts on a still lift. A mouse is unaffected.
+   * @default 'pointer'
+   */
+  touchModel?: 'pointer' | 'uikit';
+}
+
+/**
+ * What core's own menus get from {@link useDropdownMenuPress}: the public
+ * return. Not exported from the hooks entry point.
+ *
+ * @internal
+ */
+export type DropdownMenuPressReturn = UseMenuPressReturn;
+
+/**
+ * Where a pointer is, for a finger's handoff distance. Positions reach the
+ * machine only under `touchModel: 'uikit'`. Without them, it keeps the settle
+ * rule.
+ */
+function handoffPosition(
+  event: PointerEvent,
+  hasHandoff: boolean,
+): {x?: number; y?: number} {
+  return hasHandoff ? {x: event.clientX, y: event.clientY} : {};
+}
+
 /**
  * The press model for a menu: the row under the release acts, the highlight
  * follows a held pointer, and a mouse opens the menu on press.
@@ -271,13 +316,30 @@ interface ResolvedPoint {
  * ```
  */
 export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
+  // The touch model is DropdownMenu's alone; an untyped caller's
+  // `touchModel` does not reach the model.
+  const {touchModel: _touchModel, ...publicOptions} =
+    options as DropdownMenuPressOptions;
+  return useDropdownMenuPress({...publicOptions, touchModel: 'pointer'});
+}
+
+/**
+ * The press model with DropdownMenu's touch model
+ * ({@link DropdownMenuPressOptions.touchModel}). Not exported from the hooks
+ * entry point.
+ *
+ * @internal
+ */
+export function useDropdownMenuPress(
+  options: DropdownMenuPressOptions,
+): DropdownMenuPressReturn {
   const optionsRef = useRef(options);
   optionsRef.current = options;
   // The highlight, and the hover focus of the rows in this menu, follow the
   // last input, which this tracks for the menu's own document.
   useInteractionModalityTrackingFor(options.menuRef);
 
-  const gestureRef = useRef<MenuPressGesture<HTMLElement>>(IDLE_MENU_PRESS);
+  const gestureRef = useRef<MenuPressState<HTMLElement>>(IDLE_MENU_PRESS);
   const pointerIdRef = useRef<number | null>(null);
   const detachRef = useRef<(() => void) | null>(null);
   // `useLongPress` detects the held finger, as in ContextMenu, so the hold
@@ -374,8 +436,18 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
     autoscrollRef.current = null;
   }, [autoscroll]);
 
+  const litRowRef = useRef<HTMLElement | null>(null);
+  const heldMenuRef = useRef<HTMLElement | null>(null);
   const endGesture = useCallback(() => {
     longPressApiRef.current?.cancel();
+    if (litRowRef.current != null) {
+      clearMenuPressLit(litRowRef.current);
+      litRowRef.current = null;
+    }
+    if (heldMenuRef.current != null) {
+      releaseMenuPressPaint(heldMenuRef.current);
+      heldMenuRef.current = null;
+    }
     touchMovePreventerRef.current?.();
     touchMovePreventerRef.current = null;
     stopAutoscroll();
@@ -388,7 +460,34 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
 
   const highlight = useCallback(
     (row: HTMLElement | null) => {
+      // A held finger or pen marks the row it lights, for the row's pressed
+      // paint. A held mouse keeps the hover tint, as on a desktop.
+      const gesture = gestureRef.current;
+      const isHeld =
+        gesture.phase !== 'idle' && gesture.pointerType !== 'mouse';
+      const lit = isHeld ? row : null;
+      if (litRowRef.current !== lit) {
+        if (litRowRef.current != null) {
+          clearMenuPressLit(litRowRef.current);
+        }
+        litRowRef.current = lit;
+        if (lit != null) {
+          markMenuPressLit(lit);
+        }
+      }
       const {onHighlight, menuRef} = optionsRef.current;
+      // The row the press began on stays :active where a pointer hovers, so
+      // the menu holds every row but the lit one off that paint.
+      const held = isHeld ? menuRef.current : null;
+      if (heldMenuRef.current !== held) {
+        if (heldMenuRef.current != null) {
+          releaseMenuPressPaint(heldMenuRef.current);
+        }
+        heldMenuRef.current = held;
+        if (held != null) {
+          holdMenuPressPaint(held);
+        }
+      }
       if (onHighlight != null) {
         onHighlight(row);
         return;
@@ -449,13 +548,13 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
 
   // Declared before `step` so the mutual recursion through refs type-checks.
   const stepRef = useRef<
-    (event: MenuPressEvent<HTMLElement>, native?: PointerEvent) => void
+    (event: MenuPressInput<HTMLElement>, native?: PointerEvent) => void
   >(() => {});
 
   const applyEffect = useCallback(
     (
-      effect: MenuPressEffect<HTMLElement>,
-      gesture: MenuPressGesture<HTMLElement>,
+      effect: MenuPressOutcome<HTMLElement>,
+      gesture: MenuPressState<HTMLElement>,
       native: PointerEvent | undefined,
     ) => {
       const doc = getDocument();
@@ -511,8 +610,8 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
   );
 
   const step = useCallback(
-    (event: MenuPressEvent<HTMLElement>, native?: PointerEvent) => {
-      const result = menuPressStep(gestureRef.current, event);
+    (event: MenuPressInput<HTMLElement>, native?: PointerEvent) => {
+      const result = menuPressTransition(gestureRef.current, event);
       gestureRef.current = result.gesture;
       applyEffect(result.effect, result.gesture, native);
     },
@@ -619,6 +718,10 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
             row: point.row,
             isInMenu: point.isInMenu,
             time: Date.now(),
+            ...handoffPosition(
+              event,
+              optionsRef.current.touchModel === 'uikit',
+            ),
           },
           event,
         );
@@ -636,6 +739,10 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
             isInMenu: point.isInMenu,
             isOnTrigger: point.isOnTrigger,
             time: Date.now(),
+            ...handoffPosition(
+              event,
+              optionsRef.current.touchModel === 'uikit',
+            ),
           },
           event,
         );