@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/dist/hooks/useMenuPress.d.ts

@@ -2,41 +2,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
@@ -46,8 +15,8 @@
  */
 import { type RefObject } from 'react';
 import { type MenuPressPointerType } from './menuPressGesture.js';
-/** Marks a menu root that carries this press model. */
-export declare const MENU_PRESS_MARKER = "data-astryx-menu-press";
+import { MENU_PRESS_MARKER } from './menuPressMarker.js';
+export { MENU_PRESS_MARKER };
 /**
  * Carried by a menu root that another root renders beside itself rather than
  * inside it, naming that root's `id`: the menu of a sub-menu with a header or
@@ -56,10 +25,19 @@ export declare const MENU_PRESS_MARKER = "data-astryx-menu-press";
  * root carries it, so a picker placed in a header or footer stays its own root.
  */
 export declare const MENU_PRESS_SURFACE_ATTR = "data-astryx-menu-press-surface";
-/** How long after a tracked release the browser's click is still swallowed. */
+/**
+ * How long after a tracked release the browser's click is still swallowed:
+ * the shared click guard's window (utils/clickGuard.ts).
+ */
 export declare const MENU_PRESS_STRAY_CLICK_MS = 400;
 /** How long a finger must rest on the trigger before the menu opens under it. */
 export declare const MENU_PRESS_LONG_PRESS_MS = 500;
+/**
+ * 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 declare const MENU_PRESS_TRIGGER_DRIFT_PX = 13;
 /** Distance from a scrolling menu's edge within which a resting pointer scrolls. */
 export declare const MENU_PRESS_AUTOSCROLL_ZONE_PX = 24;
 /**
@@ -69,7 +47,7 @@ export declare const MENU_PRESS_AUTOSCROLL_ZONE_PX = 24;
  * from the browser's stray one.
  */
 export declare function isMenuPressActivation(): boolean;
-/** Test-only: forget an armed swallower between cases. */
+/** Test-only: forget an armed click guard between cases. */
 export declare function __resetMenuPressForTest(): void;
 export interface UseMenuPressOptions {
     /** The menu (or listbox) root: the surface whose rows the press picks from. */
@@ -143,7 +121,22 @@ export interface UseMenuPressReturn {
 }
 /**
  * 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
  * ```

package/dist/hooks/useMenuPress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useMenuPress.d.ts","sourceRoot":"","sources":["../../src/hooks/useMenuPress.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAML,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,EAML,KAAK,oBAAoB,EAC1B,MAAM,oBAAoB,CAAC;AAM5B,uDAAuD;AACvD,eAAO,MAAM,iBAAiB,2BAA2B,CAAC;AAE1D;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AAExE,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAC7C,iFAAiF;AACjF,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,oFAAoF;AACpF,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAchD;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AA6DD,0DAA0D;AAC1D,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAMD,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACvC,uEAAuE;IACvE,UAAU,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC3C;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,CAAC,WAAW,EAAE,oBAAoB,KAAK,OAAO,CAAC;IAChE;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAChD;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;IAC/D,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;IACnD,mBAAmB;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,SAAS,EAAE;QACT,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;QAChE,CAAC,iBAAiB,CAAC,EAAE,EAAE,CAAC;KACzB,CAAC;IACF,yEAAyE;IACzE,YAAY,EAAE;QACZ,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;QAChE,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;KAC/D,CAAC;IACF;;;;OAIG;IACH,uBAAuB,EAAE,MAAM,OAAO,CAAC;IACvC,uEAAuE;IACvE,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAkED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CA2kB7E"}
+{"version":3,"file":"useMenuPress.d.ts","sourceRoot":"","sources":["../../src/hooks/useMenuPress.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAML,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,EAML,KAAK,oBAAoB,EAC1B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAC,iBAAiB,EAAC,MAAM,mBAAmB,CAAC;AAiBpD,OAAO,EAAC,iBAAiB,EAAC,CAAC;AAE3B;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AAExE;;;GAGG;AACH,eAAO,MAAM,yBAAyB,MAAwB,CAAC;AAC/D,iFAAiF;AACjF,eAAO,MAAM,wBAAwB,MAAyB,CAAC;AAC/D;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAM9C,oFAAoF;AACpF,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAUhD;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAED,4DAA4D;AAC5D,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACvC,uEAAuE;IACvE,UAAU,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC3C;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,CAAC,WAAW,EAAE,oBAAoB,KAAK,OAAO,CAAC;IAChE;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAChD;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;IAC/D,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;IACnD,mBAAmB;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,SAAS,EAAE;QACT,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;QAChE,CAAC,iBAAiB,CAAC,EAAE,EAAE,CAAC;KACzB,CAAC;IACF,yEAAyE;IACzE,YAAY,EAAE;QACZ,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;QAChE,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;KAC/D,CAAC;IACF;;;;OAIG;IACH,uBAAuB,EAAE,MAAM,OAAO,CAAC;IACvC,uEAAuE;IACvE,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AA0DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAwkB7E"}

package/dist/hooks/useMenuPress.js

@@ -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
@@ -51,13 +20,14 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { currentGesture } from "../Layer/gestureCounter.js";
 import { IDLE_MENU_PRESS, menuPressStep } from "./menuPressGesture.js";
-import { useLongPress } from "./useLongPress.js";
+import { MENU_PRESS_MARKER } from "./menuPressMarker.js";
+import { useLongPressDetector } from "./useLongPress.js";
 import { edgeAutoscroll } from "../utils/edgeAutoscroll.js";
 import { focusForLastInput } from "../utils/focusReturn.js";
-import { useInteractionModalityTracking } from "../utils/interactionModality.js";
-
-/** Marks a menu root that carries this press model. */
-export const MENU_PRESS_MARKER = 'data-astryx-menu-press';
+import { useInteractionModalityTrackingFor } from "../utils/interactionModality.js";
+import { LONG_PRESS_DURATION_MS } from "../motion/uikit/longPress.js";
+import { __resetClickGuardForTest, armClickGuard, CLICK_GUARD_WINDOW_MS, withoutClickGuard } from "../utils/clickGuard.js";
+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
@@ -68,21 +38,30 @@ 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 = {
+  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;
 const AUTOSCROLL_INTERVAL_MS = 16;
 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;
 
 /**
@@ -94,69 +73,11 @@ let isModelActivation = false;
 export function isMenuPressActivation() {
   return isModelActivation;
 }
-let swallower = null;
-function disarmStrayClick() {
-  if (swallower == null) {
-    return;
-  }
-  swallower.isArmed = false;
-  if (swallower.timer != null) {
-    clearTimeout(swallower.timer);
-    swallower.timer = null;
-  }
-}
-function onWindowClickCapture(event) {
-  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) {
-  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() {
-  disarmStrayClick();
+  __resetClickGuardForTest();
 }
-
-// =============================================================================
-// Options
-// =============================================================================
-
-// =============================================================================
-// Helpers
-// =============================================================================
-
 function normalizePointerType(type) {
   return type === 'mouse' || type === 'touch' || type === 'pen' ? type : null;
 }
@@ -203,13 +124,24 @@ function isInMenuTree(element, root) {
   const owner = element.closest(MENU_PRESS_ROOT_SELECTOR);
   return owner != null && getOutermostRoot(owner) === root;
 }
-// =============================================================================
-// 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
  * ```
@@ -231,16 +163,15 @@ export function useMenuPress(options) {
   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(IDLE_MENU_PRESS);
   const pointerIdRef = useRef(null);
   const detachRef = useRef(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.
+  // `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(null);
   const touchMovePreventerRef = useRef(null);
   // The edge autoscroll running now: its scroller, its direction, and the
@@ -259,7 +190,7 @@ export function useMenuPress(options) {
       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;
       }
@@ -336,12 +267,11 @@ export function useMenuPress(options) {
       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 : isRowFocusable(row) ? row : row.querySelector(INNER_CONTROL_SELECTOR);
     if (target != null && target !== getDocument().activeElement) {
       focusForLastInput(target, {
@@ -350,36 +280,39 @@ export function useMenuPress(options) {
     }
   }, [getDocument]);
   const activate = useCallback((row, release) => {
-    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.
@@ -409,7 +342,10 @@ export function useMenuPress(options) {
         {
           // 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);
           }
@@ -419,7 +355,9 @@ export function useMenuPress(options) {
         {
           endGesture();
           if (effect.stray) {
-            armStrayClick(doc);
+            armClickGuard(doc, {
+              staysInstalled: true
+            });
           }
           if (effect.dismiss) {
             optionsRef.current.onDismiss?.();
@@ -434,9 +372,6 @@ export function useMenuPress(options) {
     applyEffect(result.effect, result.gesture, native);
   }, [applyEffect]);
   stepRef.current = step;
-
-  // --- Edge autoscroll -----------------------------------------------
-
   const getScroller = useCallback(() => {
     const {
       getScroller: custom,
@@ -499,9 +434,6 @@ export function useMenuPress(options) {
     };
     autoscroll.update();
   }, [autoscroll, getScroller, resolvePoint, stopAutoscroll]);
-
-  // --- Document-level tracking ----------------------------------------------
-
   const attach = useCallback(pointerId => {
     detachRef.current?.();
     const doc = getDocument();
@@ -514,8 +446,8 @@ export function useMenuPress(options) {
       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
@@ -585,9 +517,6 @@ export function useMenuPress(options) {
       view?.removeEventListener('blur', onBlur);
     };
   }, [getDocument, resolvePoint, updateAutoscroll]);
-
-  // --- The held finger on the trigger ----------------------------
-
   const fireLongPress = useCallback(() => {
     const gesture = gestureRef.current;
     if (gesture.phase !== 'triggerPress') {
@@ -622,17 +551,14 @@ export function useMenuPress(options) {
     });
   }, [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 => {
     const {
       menuRef,
@@ -667,10 +593,10 @@ export function useMenuPress(options) {
       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;
@@ -711,7 +637,7 @@ export function useMenuPress(options) {
       longPressApiRef.current?.start({
         x: native.clientX,
         y: native.clientY
-      });
+      }, TRIGGER_TOLERANCE);
     }
     step({
       type: 'down',

package/dist/hooks/useOverflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useOverflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useOverflow.ts"],"names":[],"mappings":"AA4BA,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAE/B;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,eAAe,GAAG,aAAa,CAAC;CAC5C;AAED,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC7C,wDAAwD;IACxD,UAAU,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC3C,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAC;IACrB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAgKnB"}
+{"version":3,"file":"useOverflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useOverflow.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAE/B;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,eAAe,GAAG,aAAa,CAAC;CAC5C;AAED,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC7C,wDAAwD;IACxD,UAAU,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC3C,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAC;IACrB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAgKnB"}

package/dist/hooks/useOverflow.js

@@ -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/dist/hooks/useRenamedProp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useRenamedProp.d.ts","sourceRoot":"","sources":["../../src/hooks/useRenamedProp.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,eAAe,EAAE,CAAC,GAAG,SAAS,CAAC;IAC/B,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,EAChC,SAAS,EACT,UAAU,EACV,eAAe,EACf,WAAW,EACX,KAAK,GACN,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAqBvC"}
+{"version":3,"file":"useRenamedProp.d.ts","sourceRoot":"","sources":["../../src/hooks/useRenamedProp.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,eAAe,EAAE,CAAC,GAAG,SAAS,CAAC;IAC/B,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,EAChC,SAAS,EACT,UAAU,EACV,eAAe,EACf,WAAW,EACX,KAAK,GACN,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAqBvC"}

package/dist/hooks/useRenamedProp.js

@@ -6,24 +6,15 @@
  * @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.js";
 /**
  * Resolve a renamed prop: the replacement wins, the old name still works,

package/dist/hooks/useScrollOverflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useScrollOverflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useScrollOverflow.ts"],"names":[],"mappings":"AAmCA,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,aAAa,EAAE,OAAO,CAAC;IACvB,4DAA4D;IAC5D,WAAW,EAAE,OAAO,CAAC;IACrB,oDAAoD;IACpD,WAAW,EAAE,OAAO,CAAC;CACtB;AA4DD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB;IA/E/B,8DAA8D;mBAC/C,OAAO;IACtB,4DAA4D;iBAC/C,OAAO;IACpB,oDAAoD;iBACvC,OAAO;oBAgIb,WAAW,GAAG,IAAI;EA+B1B"}
+{"version":3,"file":"useScrollOverflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useScrollOverflow.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,aAAa,EAAE,OAAO,CAAC;IACvB,4DAA4D;IAC5D,WAAW,EAAE,OAAO,CAAC;IACrB,oDAAoD;IACpD,WAAW,EAAE,OAAO,CAAC;CACtB;AA4DD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB;IA/E/B,8DAA8D;mBAC/C,OAAO;IACtB,4DAA4D;iBAC/C,OAAO;IACpB,oDAAoD;iBACvC,OAAO;oBA+Hb,WAAW,GAAG,IAAI;EA+B1B"}