@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/hooks/useMenuHover.ts

@@ -4,38 +4,30 @@
 
 /**
  * @file useMenuHover.ts
- * @input Uses React hooks, useListFocus, useMediaQuery
- * @output Exports useMenuHover hook
- * @position Internal hook; used by nav heading components, TopNavMenu,
- *           TopNavMegaMenu and DropdownMenuSubMenu
- *
- * Hover as a progressive enhancement over standard popover behavior: click
- * toggles, Escape and outside-click close, arrows navigate; on top of that,
- * mouseenter opens after a delay and mouseleave closes one that hover opened.
- *
- * Three behaviors here are not obvious and are load-bearing:
- *
- * 1. Hover→click guard (#3121). A hover-opened menu is already open under the
- *    cursor when the pointer arrives, so the click that naturally follows would
- *    toggle it shut. Within `clickGuardMs` a click instead confirms it: the menu
- *    pins and behaves like a click-open from then on.
- *
- * 2. Focus moves synchronously. `useLayer.show()` calls `showPopover()` in the
- *    same tick and the layer's children are always mounted, so items are
- *    focusable the moment `show()` returns — a `requestAnimationFrame` here
- *    lands after paint and races anything else moving focus. Hover-opens are the
- *    exception: the pointer is driving, so focus stays on the trigger. The hook
- *    always passes `skipAutoFocus` and owns focus itself, because the popover's
- *    auto-focus targets the first *tabbable* node while a menu wants its first
- *    item — under roving tabindex those are different elements.
- *
- * 3. Native light dismiss. A `popover="auto"` is dismissed by the browser on
- *    pointer interaction outside the panel, and a trigger outside the panel
- *    counts — before React's click handler runs. `popoverId` makes the trigger
- *    the panel's invoker, which exempts it. jsdom implements neither light
- *    dismiss nor invokers, so that wiring is only verifiable in a browser.
+ * @input React hooks, useListFocus, useMediaQuery
+ * @output useMenuHover hook
+ * @position Internal hook for nav heading components, TopNavMenu,
+ *   TopNavMegaMenu and DropdownMenuSubMenu
  */
 
+// Hover adds to the standard popover behavior. A click toggles, Escape and an
+// outside click close, and arrows navigate. Also, mouseenter opens after a
+// delay, and mouseleave closes a menu that hover opened.
+//
+// - A hover-opened menu is open when the click that follows arrives. Within
+//   `clickGuardMs`, that click pins the menu and does not close it.
+// - Focus moves synchronously. `useLayer.show()` shows the popover in the
+//   same tick, and the items are always mounted. A frame delay lands after
+//   paint and races other focus moves. A hover open keeps focus on the
+//   trigger.
+// - The hook passes `skipAutoFocus` and moves focus itself. Popover
+//   auto-focus goes to the first tabbable node, but under roving tabindex a
+//   menu wants its first item.
+// - The browser light-dismisses a `popover="auto"` on a pointer press
+//   outside the panel, also on the trigger. `popoverId` makes the trigger the
+//   panel's invoker, which exempts it. jsdom has neither feature, so only a
+//   browser can test this.
+
 import {useCallback, useEffect, useRef} from 'react';
 import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
 import {useListFocus} from './useListFocus';
@@ -45,13 +37,10 @@ import {focusForLastInput} from '../utils/focusReturn';
 const DEFAULT_CLICK_GUARD_MS = 500;
 
 /**
- * How long after a close a mouseenter on the trigger is ignored.
- *
- * A panel positioned over its own trigger puts that trigger back under a
- * stationary pointer when it closes, and the browser fires a fresh mouseenter —
- * which reopened the menu the user had just dismissed. Time-bounded rather than
- * a one-shot flag, so a deliberate re-hover seconds later still opens; a real
- * mouseleave clears it early.
+ * How long after a close a mouseenter on the trigger is ignored. A panel over
+ * its own trigger puts the trigger back under a still pointer when it closes,
+ * and the browser fires a new mouseenter. A time limit, not a one-shot flag,
+ * lets a later re-hover open the menu. A real mouseleave clears it early.
  */
 const REOPEN_SUPPRESS_MS = 300;
 
@@ -251,10 +240,9 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
     const wasOpen = prevIsOpenRef.current;
     prevIsOpenRef.current = isOpen;
     if (wasOpen && !isOpen) {
-      // A hover-open scheduled before the close must not fire afterwards and
-      // reopen what just closed from elsewhere — e.g. the root menu's light
-      // dismiss closing a submenu flyout mid hover-intent (#6893). A fresh
-      // mouseenter still opens; only the stale timer is cancelled.
+      // Cancel a hover-open that was scheduled before the close. Otherwise it
+      // reopens a menu that closed from elsewhere, such as a submenu flyout
+      // that the root menu light-dismissed. A new mouseenter still opens.
       clearTimeouts();
       hoverModeRef.current = false;
       hoverOpenedAtRef.current = 0;
@@ -282,8 +270,8 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
     hide();
     const trigger = triggerElRef.current;
     if (menuHadFocus && trigger != null) {
-      // A pointer's pick leaves no keyboard ring on the trigger; a keyboard's
-      // keeps it (`architecture:interaction-modality` INV1).
+      // A pointer pick leaves no keyboard ring on the trigger. A keyboard pick
+      // keeps it.
       focusForLastInput(trigger);
     }
   }, [hide, menuRef]);
@@ -362,9 +350,10 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
       }
       clearTimeouts();
 
-      // Enter/Space arrive as a click with detail 0, and always open. A keyboard
-      // user reaches the trigger of an open menu only because a hover-open left
-      // focus behind; closing there would stranded them outside a visible menu.
+      // Enter and Space arrive as a click with detail 0, and always open. A
+      // keyboard user reaches the trigger of an open menu only when a
+      // hover-open left focus there. A close would leave them outside a
+      // visible menu.
       const isKeyboardActivation = event != null && event.detail === 0;
       if (isKeyboardActivation) {
         closedAtRef.current = 0;
@@ -458,12 +447,9 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
           clearTimeout(hideTimerRef.current);
         }
         hideTimerRef.current = setTimeout(() => {
-          // A pointer that stopped mid-diagonal, aiming at a row, is still
-          // heading for the flyout: pausing is not leaving, and that pause
-          // is the exact moment the triangle exists to protect. Re-arm
-          // instead of closing underneath it. A pointer parked here holds
-          // the flyout open the same way a pointer parked on the row does;
-          // the first move outside the triangle ends it.
+          // A pointer that stops mid-diagonal is still heading for the
+          // flyout. Restart the delay, and do not close under it. The first
+          // move outside the triangle ends this.
           if (isTracking && lastPoint != null && isInside(lastPoint)) {
             scheduleHide();
             return;

package/src/hooks/useMenuPress.ts

@@ -6,41 +6,10 @@
  * @file useMenuPress.ts
  * @input The menu root, its trigger, the enabled-row selector, and callbacks
  *   for opening, highlighting, activating and dismissing
- * @output Exports useMenuPress, the marker attribute, and the module-level
- *   activation mark
- * @position Core hook; mounted by DropdownMenu, ContextMenu,
- *   DropdownMenuSubMenu, Selector and MenuBottomSheetActionList. The pure
- *   transition table lives in menuPressGesture.ts.
- *
- * One press in a menu, from the trigger or from inside, owned end to end:
- *
- * - The pointer is tracked at DOCUMENT level by `pointerId`. A finger's
- *   pointer events stay with the element it landed on (implicit capture), so a
- *   menu container never sees a finger that slid onto it — the document does.
- * - The highlight follows the pointer (DOM focus with `preventScroll` in a
- *   menu, its indicator following the last input; a callback for a picker
- *   that highlights by index).
- * - The row under the RELEASE acts, the way its own click would, carrying the
- *   release's button and modifier keys.
- * - The browser's stray `click` for a tracked gesture is swallowed at the
- *   window in the capture phase, ahead of React's own listener. It arms at a
- *   tracked release and disarms at the next pointer press or after a short
- *   window; a click with `detail === 0` (a keyboard's or a screen reader's)
- *   always passes.
- * - A mouse press on the trigger opens the menu at once; a finger held on the
- *   trigger opens it after the long-press delay. The settle rule decides
- *   whether the opening gesture's release may act (see menuPressGesture.ts).
- * - `pointercancel`, a second pointer, or the window losing focus end the
- *   gesture with nothing acting; the model never re-implements scrolling.
- * - While a press is tracked in an overflowing menu, a pointer resting near
- *   the top or bottom edge scrolls the menu toward that edge (the shared
- *   timer of utils/edgeAutoscroll.ts).
- *
- * The menu root is marked `data-astryx-menu-press` so a nested flyout (a DOM
- * descendant of its parent menu) can tell which level owns a press, and so a
- * surface can be recognised as carrying this model. A menu the root renders
- * beside itself names the root with `data-astryx-menu-press-surface` and counts
- * as nested in it.
+ * @output useMenuPress, the marker attributes, and the activation mark
+ * @position Core hook for DropdownMenu, ContextMenu, DropdownMenuSubMenu,
+ *   Selector and MenuBottomSheetActionList. The transition table lives in
+ *   menuPressGesture.ts.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
@@ -66,13 +35,24 @@ import {
   type MenuPressGesture,
   type MenuPressPointerType,
 } from './menuPressGesture';
-import {useLongPress, type UseLongPressHandlers} from './useLongPress';
+import {MENU_PRESS_MARKER} from './menuPressMarker';
+import {
+  useLongPressDetector,
+  type LongPressDetectorHandlers,
+  type LongPressTolerance,
+} from './useLongPress';
 import {edgeAutoscroll} from '../utils/edgeAutoscroll';
 import {focusForLastInput} from '../utils/focusReturn';
-import {useInteractionModalityTracking} from '../utils/interactionModality';
+import {useInteractionModalityTrackingFor} from '../utils/interactionModality';
+import {LONG_PRESS_DURATION_MS} from '../motion/uikit/longPress';
+import {
+  __resetClickGuardForTest,
+  armClickGuard,
+  CLICK_GUARD_WINDOW_MS,
+  withoutClickGuard,
+} from '../utils/clickGuard';
 
-/** Marks a menu root that carries this press model. */
-export const MENU_PRESS_MARKER = 'data-astryx-menu-press';
+export {MENU_PRESS_MARKER};
 const MENU_PRESS_ROOT_SELECTOR = `[${MENU_PRESS_MARKER}]`;
 /**
  * Carried by a menu root that another root renders beside itself rather than
@@ -83,10 +63,24 @@ const MENU_PRESS_ROOT_SELECTOR = `[${MENU_PRESS_MARKER}]`;
  */
 export const MENU_PRESS_SURFACE_ATTR = 'data-astryx-menu-press-surface';
 
-/** How long after a tracked release the browser's click is still swallowed. */
-export const MENU_PRESS_STRAY_CLICK_MS = 400;
+/**
+ * How long after a tracked release the browser's click is still swallowed:
+ * the shared click guard's window (utils/clickGuard.ts).
+ */
+export const MENU_PRESS_STRAY_CLICK_MS = CLICK_GUARD_WINDOW_MS;
 /** How long a finger must rest on the trigger before the menu opens under it. */
-export const MENU_PRESS_LONG_PRESS_MS = 500;
+export const MENU_PRESS_LONG_PRESS_MS = LONG_PRESS_DURATION_MS;
+/**
+ * How far a finger held on a DropdownMenu trigger may move before the open,
+ * in CSS px, under every primary pointer. A native menu still opens after a
+ * 12 pt move. ContextMenu keeps the long press's own allowable movement.
+ */
+export const MENU_PRESS_TRIGGER_DRIFT_PX = 13;
+
+/** A held finger on the trigger gets the same drift allowance under every primary pointer. */
+const TRIGGER_TOLERANCE: LongPressTolerance = {
+  moveCancelPx: MENU_PRESS_TRIGGER_DRIFT_PX,
+};
 /** Distance from a scrolling menu's edge within which a resting pointer scrolls. */
 export const MENU_PRESS_AUTOSCROLL_ZONE_PX = 24;
 const AUTOSCROLL_STEP_PX = 6;
@@ -96,10 +90,6 @@ const FOCUSABLE_ROW_SELECTOR =
   '[tabindex], a[href], button, input, select, textarea, [contenteditable]';
 const INNER_CONTROL_SELECTOR = 'a[href], button, [tabindex]';
 
-// =============================================================================
-// Module state: the activation mark and the stray-click swallower
-// =============================================================================
-
 let isModelActivation = false;
 
 /**
@@ -112,74 +102,11 @@ export function isMenuPressActivation(): boolean {
   return isModelActivation;
 }
 
-interface StrayClickSwallower {
-  doc: Document;
-  isArmed: boolean;
-  timer: ReturnType<typeof setTimeout> | null;
-}
-
-let swallower: StrayClickSwallower | null = null;
-
-function disarmStrayClick(): void {
-  if (swallower == null) {
-    return;
-  }
-  swallower.isArmed = false;
-  if (swallower.timer != null) {
-    clearTimeout(swallower.timer);
-    swallower.timer = null;
-  }
-}
-
-function onWindowClickCapture(event: MouseEvent): void {
-  if (swallower == null || !swallower.isArmed) {
-    return;
-  }
-  // A keyboard's or a screen reader's activation reports detail 0, as does the
-  // model's own dispatch. Those are never the browser's stray click.
-  if (event.detail === 0 || isModelActivation) {
-    return;
-  }
-  event.preventDefault();
-  event.stopImmediatePropagation();
-  disarmStrayClick();
-}
-
-function armStrayClick(doc: Document): void {
-  const view = doc.defaultView;
-  if (view == null) {
-    return;
-  }
-  if (swallower == null || swallower.doc !== doc) {
-    if (swallower != null) {
-      swallower.doc.defaultView?.removeEventListener(
-        'click',
-        onWindowClickCapture,
-        true,
-      );
-      swallower.doc.removeEventListener('pointerdown', disarmStrayClick, true);
-    }
-    // The window, capture phase: ahead of React's root listener and of any
-    // document listener, so no framework sees the click.
-    view.addEventListener('click', onWindowClickCapture, true);
-    // The next press is a new gesture; its click must never be eaten.
-    doc.addEventListener('pointerdown', disarmStrayClick, true);
-    swallower = {doc, isArmed: false, timer: null};
-  }
-  disarmStrayClick();
-  swallower.isArmed = true;
-  swallower.timer = setTimeout(disarmStrayClick, MENU_PRESS_STRAY_CLICK_MS);
-}
-
-/** Test-only: forget an armed swallower between cases. */
+/** Test-only: forget an armed click guard between cases. */
 export function __resetMenuPressForTest(): void {
-  disarmStrayClick();
+  __resetClickGuardForTest();
 }
 
-// =============================================================================
-// Options
-// =============================================================================
-
 export interface UseMenuPressOptions {
   /** The menu (or listbox) root: the surface whose rows the press picks from. */
   menuRef: RefObject<HTMLElement | null>;
@@ -252,10 +179,6 @@ export interface UseMenuPressReturn {
   cancel: () => void;
 }
 
-// =============================================================================
-// Helpers
-// =============================================================================
-
 function normalizePointerType(type: string): MenuPressPointerType | null {
   return type === 'mouse' || type === 'touch' || type === 'pen' ? type : null;
 }
@@ -312,13 +235,24 @@ interface ResolvedPoint {
   isOnTrigger: boolean;
 }
 
-// =============================================================================
-// Hook
-// =============================================================================
-
 /**
  * The press model for a menu: the row under the release acts, the highlight
- * follows a held pointer, a mouse opens on press. See the file header.
+ * follows a held pointer, and a mouse opens the menu on press.
+ *
+ * - The document tracks the pointer by `pointerId`. A finger's events stay
+ *   with the element it landed on, so the menu never sees a finger that slid
+ *   onto it.
+ * - The release acts on its row as the row's own click would, with the
+ *   release's button and modifier keys.
+ * - The browser's stray `click` after a tracked release is swallowed at the
+ *   window, in the capture phase. A click with `detail === 0` always passes.
+ * - A finger held on the trigger opens the menu after the long-press delay.
+ *   The settle rule in menuPressGesture.ts decides if that release can act.
+ * - `pointercancel`, a second pointer, or a window blur ends the gesture, and
+ *   nothing acts.
+ * - A pointer that rests near the edge of an overflowing menu scrolls it.
+ * - The root carries `data-astryx-menu-press`, so a nested flyout can tell
+ *   which level owns a press.
  *
  * @example
  * ```
@@ -340,18 +274,17 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
   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 document.
-  useInteractionModalityTracking();
+  // last input, which this tracks for the menu's own document.
+  useInteractionModalityTrackingFor(options.menuRef);
 
   const gestureRef = useRef<MenuPressGesture<HTMLElement>>(IDLE_MENU_PRESS);
   const pointerIdRef = useRef<number | null>(null);
   const detachRef = useRef<(() => void) | null>(null);
-  // The held finger is detected by `useLongPress`, the same hook ContextMenu
-  // uses, so the hold duration and the movement tolerance have one home. The
-  // handle is held in a ref because the pointer handlers below are stable
-  // callbacks and the hook is created further down, once `fireLongPress`
-  // exists.
-  const longPressApiRef = useRef<UseLongPressHandlers | null>(null);
+  // `useLongPress` detects the held finger, as in ContextMenu, so the hold
+  // time and the movement tolerance have one home. A ref holds the handle,
+  // because the pointer handlers below are stable and the hook is created
+  // after `fireLongPress`.
+  const longPressApiRef = useRef<LongPressDetectorHandlers | null>(null);
   const touchMovePreventerRef = useRef<(() => void) | null>(null);
   // The edge autoscroll running now: its scroller, its direction, and the
   // re-read of the row under the resting pointer after each step.
@@ -374,7 +307,7 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
         running.scroller.scrollTop = before + delta;
         const moved = running.scroller.scrollTop - before;
         if (moved === 0) {
-          // The edge is reached; nothing more to reveal.
+          // The edge is reached. There is nothing more to show.
           autoscrollRef.current = null;
           return 0;
         }
@@ -460,12 +393,11 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
         onHighlight(row);
         return;
       }
-      // In a menu the highlight IS focus. A row whose root takes no
-      // focus is highlighted through the control inside it; over nothing,
-      // the menu root holds focus so no row is lit. The focus follows the
-      // last input (`architecture:interaction-modality` INV1): a held press
-      // is pointer input, so the row does not match :focus-visible, which a
-      // plain focus() would inherit from the focus before it.
+      // In a menu the highlight is focus. A row that takes no focus is
+      // highlighted through its inner control. Over nothing, the menu root
+      // holds focus, so no row is lit. A held press is pointer input, so the
+      // row must not match :focus-visible. A plain focus() would keep the
+      // modality of the earlier focus.
       const target =
         row == null
           ? menuRef.current
@@ -480,36 +412,39 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
   );
 
   const activate = useCallback((row: HTMLElement, release: PointerEvent) => {
-    const {onActivate} = optionsRef.current;
-    isModelActivation = true;
-    try {
-      if (onActivate != null) {
-        onActivate(row, release);
-        return;
+    // Every click this dispatches passes the shared click guard.
+    withoutClickGuard(() => {
+      const {onActivate} = optionsRef.current;
+      isModelActivation = true;
+      try {
+        if (onActivate != null) {
+          onActivate(row, release);
+          return;
+        }
+        // The row acts as its own click would. `detail: 0` marks a dispatched
+        // activation, as a keyboard's does, so the click guard lets it pass.
+        // The button and the modifiers are the release's.
+        row.dispatchEvent(
+          new MouseEvent('click', {
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+            detail: 0,
+            button: release.button,
+            clientX: release.clientX,
+            clientY: release.clientY,
+            screenX: release.screenX,
+            screenY: release.screenY,
+            ctrlKey: release.ctrlKey,
+            shiftKey: release.shiftKey,
+            altKey: release.altKey,
+            metaKey: release.metaKey,
+          }),
+        );
+      } finally {
+        isModelActivation = false;
       }
-      // The row acts as its own click would. `detail: 0` marks a dispatched
-      // activation, as a keyboard's does, so the stray-click swallower lets
-      // it through; the button and modifiers are the release's.
-      row.dispatchEvent(
-        new MouseEvent('click', {
-          bubbles: true,
-          cancelable: true,
-          composed: true,
-          detail: 0,
-          button: release.button,
-          clientX: release.clientX,
-          clientY: release.clientY,
-          screenX: release.screenX,
-          screenY: release.screenY,
-          ctrlKey: release.ctrlKey,
-          shiftKey: release.shiftKey,
-          altKey: release.altKey,
-          metaKey: release.metaKey,
-        }),
-      );
-    } finally {
-      isModelActivation = false;
-    }
+    });
   }, []);
 
   // Declared before `step` so the mutual recursion through refs type-checks.
@@ -547,7 +482,8 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
         case 'act': {
           // Detach before acting: the activation usually closes the menu.
           endGesture();
-          armStrayClick(doc);
+          // Once armed, the one swallower stays installed.
+          armClickGuard(doc, {staysInstalled: true});
           if (native != null) {
             activate(effect.row, native);
           }
@@ -556,7 +492,7 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
         case 'settle': {
           endGesture();
           if (effect.stray) {
-            armStrayClick(doc);
+            armClickGuard(doc, {staysInstalled: true});
           }
           if (effect.dismiss) {
             optionsRef.current.onDismiss?.();
@@ -578,8 +514,6 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
   );
   stepRef.current = step;
 
-  // --- Edge autoscroll -----------------------------------------------
-
   const getScroller = useCallback((): HTMLElement | null => {
     const {getScroller: custom, menuRef} = optionsRef.current;
     if (custom != null) {
@@ -647,8 +581,6 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
     [autoscroll, getScroller, resolvePoint, stopAutoscroll],
   );
 
-  // --- Document-level tracking ----------------------------------------------
-
   const attach = useCallback(
     (pointerId: number) => {
       detachRef.current?.();
@@ -663,8 +595,8 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
         lastPointerEventRef.current = event;
         const gesture = gestureRef.current;
         if (gesture.phase === 'triggerPress') {
-          // A finger that travels is scrolling, not holding. The tolerance is
-          // the shared hook's, so it cannot drift from ContextMenu's.
+          // A finger that moves past the drift allowance is scrolling, not
+          // holding.
           const isPending = longPressApiRef.current?.moveTo({
             x: event.clientX,
             y: event.clientY,
@@ -736,8 +668,6 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
     [getDocument, resolvePoint, updateAutoscroll],
   );
 
-  // --- The held finger on the trigger ----------------------------
-
   const fireLongPress = useCallback(() => {
     const gesture = gestureRef.current;
     if (gesture.phase !== 'triggerPress') {
@@ -765,17 +695,15 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
     step({type: 'opened', time: Date.now()});
   }, [getDocument, step]);
 
-  // One long-press detector for the system: the same hook ContextMenu spreads
-  // onto its trigger, driven here from the pointer stream this model already
-  // observes. Its touch handlers go unused; the hold duration, the movement
-  // tolerance and the timer are what matter, and they now have one home.
-  longPressApiRef.current = useLongPress({
+  // The same long-press detector as ContextMenu, driven from the pointer
+  // stream this model already observes. Only its hold time, movement
+  // tolerance and timer are used. The trigger uses one drift allowance under
+  // every primary pointer, so no menu, row or trigger reads the pointer query.
+  longPressApiRef.current = useLongPressDetector({
     onLongPress: fireLongPress,
     delayMs: options.longPressDelayMs ?? MENU_PRESS_LONG_PRESS_MS,
   });
 
-  // --- Handlers ------------------------------------------------------------
-
   const handleMenuPointerDown = useCallback(
     (event: React.PointerEvent<HTMLElement>) => {
       const {menuRef, isEnabled = true} = optionsRef.current;
@@ -806,10 +734,10 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
         return;
       }
       if (pointerType !== 'mouse') {
-        // Cancelling pointerdown suppresses the compatibility mouse events a
-        // finger would otherwise fire at the row it LANDED on when it lifts —
-        // the mousedown that would light the origin row a second time.
-        // Scrolling is governed by touch-action and is unaffected.
+        // Cancelling pointerdown stops the compatibility mouse events that a
+        // finger fires at its landing row when it lifts. That mousedown would
+        // light the origin row again. touch-action controls scrolling, so
+        // scrolling does not change.
         event.preventDefault();
       }
       const native = event.nativeEvent;
@@ -852,7 +780,10 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
       attach(native.pointerId);
       lastPointerEventRef.current = native;
       if (pointerType !== 'mouse') {
-        longPressApiRef.current?.start({x: native.clientX, y: native.clientY});
+        longPressApiRef.current?.start(
+          {x: native.clientX, y: native.clientY},
+          TRIGGER_TOLERANCE,
+        );
       }
       step(
         {

package/src/hooks/useOverflow.ts

@@ -6,14 +6,9 @@
  * @file useOverflow.ts
  * @input Uses React useState, useCallback, useRef; useIsomorphicLayoutEffect
  * @output Exports useOverflow hook for measuring and managing horizontal overflow
- * @position Core hook; used by OverflowList and consumers for overflow patterns
- *
- * Measures children rendered in a hidden container to determine how many fit
- * in the available width, without flickering. Observes both the visible and
- * hidden measurement containers so changes to available width or measured child
- * sizes recalculate the result. Supports an optional item cap (`maxVisibleItems`)
- * and bounded multi-row wrapping (`maxRows`); the fit/clamp/row-packing math
- * lives in the pure `computeOverflow` helper.
+ * @position Core hook; used by OverflowList and consumers for overflow patterns.
+ *   Hidden copies of the children are measured, so nothing flickers. The
+ *   fit, clamp and row math lives in the pure `computeOverflow` helper.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts

package/src/hooks/useRenamedProp.ts

@@ -6,25 +6,16 @@
  * @file useRenamedProp.ts
  * @input The component name, the old and new prop names, and both values
  * @output The value to use, with development warnings for the overlap
- * @position Core deprecation utility; the replacement-first half of a prop
- *   rename
- *
- * A released prop is a public promise, so a rename ships the replacement
- * first and keeps the old name working through the overlap (`spec:AST-017`
- * FR28–FR29, `architecture:public-component-api` INV9). This centralizes the
- * two things every such overlap owes: the new name wins when both are set,
- * and development says so rather than letting a caller wonder which one the
- * component read.
- *
- * Production behavior is unchanged either way — a warning is a builder
- * guardrail, never shipped noise (`spec:AST-017` FR29).
- *
- * SYNC: deliberately NOT exported from /packages/core/src/hooks/index.ts —
- * that barrel is re-exported wholesale from the package entry point, so
- * adding it there would ship a new public hook without `spec:AST-002`
- * admission. Import it by path from inside the package.
+ * @position Core deprecation utility for the overlap of a prop rename. It is
+ *   not in hooks/index.ts, because that barrel is public and a new public hook
+ *   needs admission (AST-002). Import it by path.
  */
 
+// A released prop is a public promise. So a rename ships the replacement
+// first and keeps the old name working for an overlap (AST-017). The new name
+// wins when both are set, and development says so. Production behavior does
+// not change.
+
 import {useDevWarning} from './useDevWarning';
 
 export interface RenamedPropOptions<T> {