@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/dist/hooks/useKeyboardHint.js

@@ -4,7 +4,7 @@
 
 /**
  * @file useKeyboardHint.tsx
- * @input Uses React, StyleX, Kbd, useLayer, i18n (useTranslator)
+ * @input Uses React, StyleX, Kbd, useLayer, i18n (useComponentTranslator)
  * @output Exports useKeyboardHint hook — ephemeral arrow-key navigation hint
  * @position Core hook; shows sighted keyboard users how to navigate composite
  *   widgets that use roving tabindex (single Tab stop, arrows inside)
@@ -21,12 +21,15 @@ import "../theme/tokens.stylex.js";
 import { colorVars, radiusVars, shadowVars, spacingVars, typeScaleVars } from "../theme/tokens.stylex.js";
 import { Kbd } from "../Kbd/index.js";
 import { useLayer } from "../Layer/useLayer.js";
-import { useTranslator } from "../i18n/index.js";
+import { registerEnglishFallback, useComponentTranslator } from "../i18n/useComponentTranslator.js";
+import english from "../i18n/generated-english/hooks/useKeyboardHint.generated.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+registerEnglishFallback(english);
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+
 // ---------------------------------------------------------------------------
 // Styles
 // ---------------------------------------------------------------------------
@@ -93,7 +96,7 @@ export function useKeyboardHint(options = {}) {
     dismissAfterMs = 3000,
     isEnabled = true
   } = options;
-  const t = useTranslator();
+  const t = useComponentTranslator();
   const timeoutRef = useRef(null);
   const dismissedRef = useRef(false);
   const isVisibleRef = useRef(false);
@@ -158,8 +161,14 @@ export function useKeyboardHint(options = {}) {
     if (!target.matches(':focus-visible')) {
       return;
     }
-    // Only show when focus enters from outside the container
     const container = e.currentTarget;
+    // React bubbles focus from portaled children (a sheet or popover opened
+    // from the row) to the container; that focus is not in the row, where
+    // the arrow keys work, so it neither shows nor spends the hint.
+    if (!container.contains(target)) {
+      return;
+    }
+    // Only show when focus enters from outside the container
     if (e.relatedTarget instanceof Node && container.contains(e.relatedTarget)) {
       return;
     }

package/dist/hooks/useListFocus.d.ts

@@ -87,6 +87,30 @@ export interface UseListFocusOptions {
      */
     hasCaretGuard?: boolean;
 }
+/**
+ * Options only Core components pass; this module's internal export, not
+ * re-exported from `hooks/index.ts`, so not public API.
+ */
+export interface InternalListFocusOptions extends UseListFocusOptions {
+    /**
+     * With `hasRovingTabIndex`, the owner places the one tab stop: returns the
+     * elements that share it, the stop first, enabled or not. After every
+     * commit and every keyboard move the hook gives the first `tabindex="0"`
+     * and the rest `tabindex="-1"`. For a group whose stop follows its own
+     * state, such as a radio group whose checked item keeps the stop even when
+     * that item, or the whole group, is disabled.
+     * Unset (the default): the first enabled item holds the stop, kept across
+     * renders, and no item holds it while every item is disabled.
+     */
+    tabStopOrder?: (list: HTMLElement) => ReadonlyArray<HTMLElement>;
+    /**
+     * Moves focus with the modality of the last input: after a pointer press a
+     * focused item shows no keyboard ring, and after a key press it does. Use it
+     * for a list whose items draw the ring and that opens from a pointer, such as
+     * a context menu. Unset (the default): a plain `focus()`.
+     */
+    focusFollowsLastInput?: boolean;
+}
 /**
  * Return type for useListFocus hook
  */
@@ -178,4 +202,9 @@ export interface UseListFocusReturn<T extends HTMLElement = HTMLElement> {
  * ```
  */
 export declare function useListFocus<T extends HTMLElement = HTMLElement>(options?: UseListFocusOptions): UseListFocusReturn<T>;
+/**
+ * {@link useListFocus} with the Core-only {@link InternalListFocusOptions}.
+ * Not re-exported from `hooks/index.ts`.
+ */
+export declare function useInternalListFocus<T extends HTMLElement = HTMLElement>(options?: InternalListFocusOptions): UseListFocusReturn<T>;
 //# sourceMappingURL=useListFocus.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useListFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useListFocus.ts"],"names":[],"mappings":"AAwBA;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAEtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,oBAAoB,CAAC;IAEnC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEnC;;OAEG;IACH,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;IAEhD;;;;OAIG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE3C;;OAEG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEnC;;OAEG;IACH,UAAU,EAAE,MAAM,OAAO,CAAC;IAE1B;;OAEG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC;IAEzB;;;;;;OAMG;IACH,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,OAAO,CAAC;IAE/C;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,WAAW,EAAE,CAAC;CAC/B;AA0GD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CAkbvB"}
+{"version":3,"file":"useListFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useListFocus.ts"],"names":[],"mappings":"AAyBA;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAEtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,oBAAoB,CAAC;IAEnC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAyB,SAAQ,mBAAmB;IACnE;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,aAAa,CAAC,WAAW,CAAC,CAAC;IACjE;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEnC;;OAEG;IACH,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;IAEhD;;;;OAIG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE3C;;OAEG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEnC;;OAEG;IACH,UAAU,EAAE,MAAM,OAAO,CAAC;IAE1B;;OAEG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC;IAEzB;;;;;;OAMG;IACH,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,OAAO,CAAC;IAE/C;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,WAAW,EAAE,CAAC;CAC/B;AA0GD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CAEvB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EACtE,OAAO,GAAE,wBAA6B,GACrC,kBAAkB,CAAC,CAAC,CAAC,CA6dvB"}

package/dist/hooks/useListFocus.js

@@ -20,6 +20,7 @@
 import { useCallback, useRef } from 'react';
 import { isRtlElement } from "./isRtlElement.js";
 import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
+import { focusForLastInput } from "../utils/focusReturn.js";
 
 /**
  * Navigation orientation for a linear list.
@@ -32,6 +33,11 @@ import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
  * Configuration for list focus behavior
  */
 
+/**
+ * Options only Core components pass; this module's internal export, not
+ * re-exported from `hooks/index.ts`, so not public API.
+ */
+
 /**
  * Return type for useListFocus hook
  */
@@ -177,6 +183,14 @@ function shouldDeferToCaret(target, key) {
  * ```
  */
 export function useListFocus(options = {}) {
+  return useInternalListFocus(options);
+}
+
+/**
+ * {@link useListFocus} with the Core-only {@link InternalListFocusOptions}.
+ * Not re-exported from `hooks/index.ts`.
+ */
+export function useInternalListFocus(options = {}) {
   const {
     itemSelector = '[role="menuitem"]',
     boundarySelector,
@@ -186,7 +200,9 @@ export function useListFocus(options = {}) {
     hasHomeEnd = true,
     hasPaging = false,
     hasRovingTabIndex = false,
-    hasCaretGuard = false
+    tabStopOrder,
+    hasCaretGuard = false,
+    focusFollowsLastInput = false
   } = options;
   const listRef = useRef(null);
 
@@ -292,6 +308,17 @@ export function useListFocus(options = {}) {
    * enabled; otherwise promote the first enabled item (tab-stop repair).
    */
   const syncTabStops = useCallback(() => {
+    const listEl = listRef.current;
+    if (listEl != null && tabStopOrder != null) {
+      const [stop, ...others] = tabStopOrder(listEl);
+      if (stop != null) {
+        setTabIndex(stop, 0);
+      }
+      for (const el of others) {
+        setTabIndex(el, -1);
+      }
+      return;
+    }
     const items = getItems();
     const enabled = items.filter(el => !isItemDisabled(el));
     if (enabled.length === 0) {
@@ -302,7 +329,7 @@ export function useListFocus(options = {}) {
     for (const el of items) {
       setTabIndex(el, el === tabbable ? 0 : -1);
     }
-  }, [getItems, isItemDisabled, setTabIndex]);
+  }, [getItems, isItemDisabled, setTabIndex, tabStopOrder]);
 
   // Keep the tab stop valid across renders (items added/removed, disabled
   // toggled). Runs after every commit but only when roving tabindex is on.
@@ -322,12 +349,20 @@ export function useListFocus(options = {}) {
       return;
     }
     if (hasRovingTabIndex) {
-      for (const el of items) {
+      // An owner-placed stop may sit on an element outside `items`, such as
+      // a disabled checked radio; it gives way to the target too.
+      const listEl = listRef.current;
+      const sharing = listEl != null && tabStopOrder != null ? [...items, ...tabStopOrder(listEl)] : items;
+      for (const el of sharing) {
         setTabIndex(el, el === target ? 0 : -1);
       }
     }
-    target.focus();
-  }, [hasRovingTabIndex, setTabIndex]);
+    if (focusFollowsLastInput) {
+      focusForLastInput(target);
+    } else {
+      target.focus();
+    }
+  }, [hasRovingTabIndex, setTabIndex, focusFollowsLastInput, tabStopOrder]);
 
   /**
    * Focus an item by index, clamping to valid range.
@@ -499,15 +534,23 @@ export function useListFocus(options = {}) {
     }
     const currentIndex = getCurrentIndex();
     const items = getItems();
+    let nextFrom = currentIndex === -1 ? 0 : currentIndex + 1;
+    let prevFrom = currentIndex === -1 ? items.length - 1 : currentIndex - 1;
+    // Focus on an owner-placed stop outside `items`, such as a disabled
+    // checked radio, moves to the enabled item beside it in document order.
+    const active = document.activeElement;
+    if (currentIndex === -1 && tabStopOrder != null && active != null && listRef.current?.contains(active)) {
+      const after = items.findIndex(item => (active.compareDocumentPosition(item) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0);
+      nextFrom = after === -1 ? items.length : after;
+      prevFrom = nextFrom - 1;
+    }
     if (isNext) {
-      const from = currentIndex === -1 ? 0 : currentIndex + 1;
-      const next = findEnabledIndex(items, from, 1, wrap);
+      const next = findEnabledIndex(items, nextFrom, 1, wrap);
       if (next !== -1) {
         focusIndex(items, next);
       }
     } else if (isPrev) {
-      const from = currentIndex === -1 ? items.length - 1 : currentIndex - 1;
-      const prev = findEnabledIndex(items, from, -1, wrap);
+      const prev = findEnabledIndex(items, prevFrom, -1, wrap);
       if (prev !== -1) {
         focusIndex(items, prev);
       }
@@ -521,7 +564,7 @@ export function useListFocus(options = {}) {
       focusPage(-1);
     }
     e.preventDefault();
-  }, [getCurrentIndex, getItems, wrap, orientation, hasHomeEnd, hasPaging, hasCaretGuard, findEnabledIndex, focusIndex, focusFirst, focusLast, focusPage, onEscape, ownsEvent]);
+  }, [getCurrentIndex, getItems, wrap, orientation, hasHomeEnd, hasPaging, hasCaretGuard, findEnabledIndex, focusIndex, focusFirst, focusLast, focusPage, onEscape, ownsEvent, tabStopOrder]);
   return {
     listRef,
     handleKeyDown,

package/dist/hooks/useLongPress.d.ts

@@ -11,6 +11,13 @@ export interface UseLongPressOptions {
     /** Movement past this distance (px, either axis) cancels the press. Defaults to 10. */
     moveCancelPx?: number;
 }
+/**
+ * @internal A press's own movement tolerance, for a core caller that decides
+ * it as the press starts (useMenuPress's trigger). Not in the hooks entry.
+ */
+export interface LongPressTolerance {
+    moveCancelPx?: number;
+}
 export interface UseLongPressHandlers {
     onTouchStart: (e: React.TouchEvent) => void;
     onTouchMove: (e: React.TouchEvent) => void;
@@ -36,5 +43,19 @@ export interface UseLongPressHandlers {
     /** Drop any pending press (a lift, a cancel, or the gesture moving on). */
     cancel: () => void;
 }
+/**
+ * @internal The handlers with a per-press tolerance on `start`, for a core
+ * caller that decides it as the press starts (useMenuPress's trigger). Not in
+ * the hooks entry: the public `useLongPress` takes its tolerance from
+ * `moveCancelPx`.
+ */
+export interface LongPressDetectorHandlers extends Omit<UseLongPressHandlers, 'start'> {
+    start: (point: {
+        x: number;
+        y: number;
+    }, tolerance?: LongPressTolerance) => void;
+}
 export declare function useLongPress(options: UseLongPressOptions): UseLongPressHandlers;
+/** @internal useLongPress with a per-press tolerance (LongPressDetectorHandlers). */
+export declare function useLongPressDetector(options: UseLongPressOptions): LongPressDetectorHandlers;
 //# sourceMappingURL=useLongPress.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useLongPress.d.ts","sourceRoot":"","sources":["../../src/hooks/useLongPress.ts"],"names":[],"mappings":"AAqCA,MAAM,WAAW,mBAAmB;IAClC,6EAA6E;IAC7E,WAAW,EAAE,CAAC,KAAK,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,KAAK,IAAI,CAAC;IACrD,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC5C,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC3C,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,aAAa,EAAE,MAAM,IAAI,CAAC;IAC1B;;;OAGG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,KAAK,IAAI,CAAC;IAC/C;;;;OAIG;IACH,MAAM,EAAE,CAAC,KAAK,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,KAAK,OAAO,CAAC;IACnD,2EAA2E;IAC3E,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,wBAAgB,YAAY,CAC1B,OAAO,EAAE,mBAAmB,GAC3B,oBAAoB,CAyGtB"}
+{"version":3,"file":"useLongPress.d.ts","sourceRoot":"","sources":["../../src/hooks/useLongPress.ts"],"names":[],"mappings":"AAuCA,MAAM,WAAW,mBAAmB;IAClC,6EAA6E;IAC7E,WAAW,EAAE,CAAC,KAAK,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,KAAK,IAAI,CAAC;IACrD,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC5C,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC3C,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,aAAa,EAAE,MAAM,IAAI,CAAC;IAC1B;;;OAGG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,KAAK,IAAI,CAAC;IAC/C;;;;OAIG;IACH,MAAM,EAAE,CAAC,KAAK,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,KAAK,OAAO,CAAC;IACnD,2EAA2E;IAC3E,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,yBAA0B,SAAQ,IAAI,CACrD,oBAAoB,EACpB,OAAO,CACR;IACC,KAAK,EAAE,CACL,KAAK,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,EAC7B,SAAS,CAAC,EAAE,kBAAkB,KAC3B,IAAI,CAAC;CACX;AAED,wBAAgB,YAAY,CAC1B,OAAO,EAAE,mBAAmB,GAC3B,oBAAoB,CAStB;AAED,qFAAqF;AACrF,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,mBAAmB,GAC3B,yBAAyB,CA0G3B"}

package/dist/hooks/useLongPress.js

@@ -11,29 +11,56 @@
  *   `useMenuPress` for the held-finger menu open
  *
  * SYNC: When modified, update the hooks barrel /packages/core/src/hooks/index.ts
- *
- * Detects a single-finger long-press: fires `onLongPress` with the press
- * start point after `delayMs`. Cancels if the finger moves past
- * `moveCancelPx` (treated as a scroll/drag), lifts, or the touch is
- * cancelled. The pending timer is also cleared on unmount.
- *
- * Two ways in, one detector. Spread the touch handlers onto an element, or —
- * when the caller already runs its own pointer-event machine, as
- * `useMenuPress` does — call `start`, `moveTo` and `cancel` from it. Either
- * way the hold duration, the movement tolerance and the timer are this
- * hook's, so a long press cannot come to mean one thing on a context menu
- * and another on a menu trigger.
- *
- * Motivation: iOS Safari never synthesizes a `contextmenu` event on
- * long-press, so long-press is the only touch affordance for opening
- * cursor-positioned surfaces.
  */
+
+// iOS Safari sends no `contextmenu` event on a long press. So a long press is
+// the only touch way to open a surface at the press point.
+//
+// A caller can spread the touch handlers, or call `start`, `moveTo` and
+// `cancel` from its own pointer events, as `useMenuPress` does. Both ways use
+// this hook's hold time, movement tolerance and timer, so a long press means
+// the same thing on a context menu and on a menu trigger.
+//
+// The defaults come from the long-press recognizer. The recognizer measures
+// its tolerance as a distance, as UIKit does. This hook measures it on each
+// axis. The context menu's own movement allowance is a guess and is not
+// measured yet (AST-094).
 import { useCallback, useEffect, useRef } from 'react';
+import { LONG_PRESS_ALLOWABLE_MOVEMENT_PX, LONG_PRESS_DURATION_MS } from "../motion/uikit/longPress.js";
+
+// The long-press numbers have one source, shared with the gesture
+// recognizers (motion/uikit/longPress.ts).
+const DEFAULT_DELAY_MS = LONG_PRESS_DURATION_MS;
+const DEFAULT_MOVE_CANCEL_PX = LONG_PRESS_ALLOWABLE_MOVEMENT_PX;
+
+/**
+ * @internal A press's own movement tolerance, for a core caller that decides
+ * it as the press starts (useMenuPress's trigger). Not in the hooks entry.
+ */
+
+/**
+ * @internal The handlers with a per-press tolerance on `start`, for a core
+ * caller that decides it as the press starts (useMenuPress's trigger). Not in
+ * the hooks entry: the public `useLongPress` takes its tolerance from
+ * `moveCancelPx`.
+ */
 
-// Default long-press tuning.
-const DEFAULT_DELAY_MS = 500;
-const DEFAULT_MOVE_CANCEL_PX = 10;
 export function useLongPress(options) {
+  const {
+    start,
+    ...handlers
+  } = useLongPressDetector(options);
+  // The public start takes only the point. A per-press tolerance stays
+  // internal to its core caller.
+  const startAt = useCallback(point => start(point), [start]);
+  return {
+    ...handlers,
+    start: startAt
+  };
+}
+
+/** @internal useLongPress with a per-press tolerance (LongPressDetectorHandlers). */
+export function useLongPressDetector(options) {
   const {
     onLongPress,
     disabled = false,
@@ -42,6 +69,8 @@ export function useLongPress(options) {
   } = options;
   const timerRef = useRef(null);
   const startRef = useRef(null);
+  // The press in progress's tolerance, when its caller chose one at start.
+  const pressToleranceRef = useRef(null);
   // Keep the latest callback without re-creating handlers on every render.
   const onLongPressRef = useRef(onLongPress);
   onLongPressRef.current = onLongPress;
@@ -52,17 +81,18 @@ export function useLongPress(options) {
     }
     startRef.current = null;
   }, []);
-  const start = useCallback(point => {
+  const start = useCallback((point, tolerance) => {
     if (disabled) {
       return;
     }
-    // Clear any stale timer first, THEN record the start point — clearing
-    // also nulls startRef, so order matters.
+    // Clear a stale timer first, then record the start point. The clear
+    // also sets startRef to null.
     clear();
     startRef.current = {
       x: point.x,
       y: point.y
     };
+    pressToleranceRef.current = tolerance ?? null;
     timerRef.current = setTimeout(() => {
       const from = startRef.current;
       if (from == null) {
@@ -79,8 +109,9 @@ export function useLongPress(options) {
     if (from == null) {
       return false;
     }
-    if (Math.abs(point.x - from.x) > moveCancelPx || Math.abs(point.y - from.y) > moveCancelPx) {
-      // Treat as a scroll/drag, not a long-press.
+    // This press's own tolerance when its caller chose one, on either axis.
+    const limit = pressToleranceRef.current?.moveCancelPx ?? moveCancelPx;
+    if (Math.abs(point.x - from.x) > limit || Math.abs(point.y - from.y) > limit) {
       clear();
       return false;
     }
@@ -91,7 +122,6 @@ export function useLongPress(options) {
       return;
     }
     if (e.touches.length !== 1) {
-      // Multi-touch cancels any pending long-press.
       clear();
       return;
     }
@@ -106,7 +136,6 @@ export function useLongPress(options) {
       return;
     }
     if (e.touches.length !== 1) {
-      // Multi-touch cancels the pending long-press.
       clear();
       return;
     }
@@ -116,8 +145,6 @@ export function useLongPress(options) {
       y: touch.clientY
     });
   }, [clear, moveTo]);
-
-  // Cancel any pending long-press timer on unmount.
   useEffect(() => clear, [clear]);
   return {
     onTouchStart,

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

@@ -1 +1 @@
-{"version":3,"file":"useMenuHover.d.ts","sourceRoot":"","sources":["../../src/hooks/useMenuHover.ts"],"names":[],"mappings":"AA+DA,UAAU,KAAK;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,UAAU,QAAQ;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAeD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,KAAK,EACb,MAAM,EAAE,QAAQ,GACf,OAAO,CAqBT;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAC,KAAK,IAAI,CAAC;IACpD,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE,YAAY,EAAE;QACZ,OAAO,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;QAC5C,YAAY,EAAE,MAAM,IAAI,CAAC;QACzB;;;WAGG;QACH,YAAY,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;QACjD,iDAAiD;QACjD,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,YAAY,EAAE;QACZ,YAAY,EAAE,MAAM,IAAI,CAAC;QACzB,YAAY,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;QACjD,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;KAC7C,CAAC;IACF,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACnC,uEAAuE;IACvE,UAAU,EAAE,MAAM,OAAO,CAAC;IAC1B;;;OAGG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,OAAO,CAAC;IAChC;;;;OAIG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,YAAY,EAAE,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;CAChD;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CAoWvB"}
+{"version":3,"file":"useMenuHover.d.ts","sourceRoot":"","sources":["../../src/hooks/useMenuHover.ts"],"names":[],"mappings":"AAoDA,UAAU,KAAK;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,UAAU,QAAQ;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAeD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,KAAK,EACb,MAAM,EAAE,QAAQ,GACf,OAAO,CAqBT;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAC,KAAK,IAAI,CAAC;IACpD,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE,YAAY,EAAE;QACZ,OAAO,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;QAC5C,YAAY,EAAE,MAAM,IAAI,CAAC;QACzB;;;WAGG;QACH,YAAY,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;QACjD,iDAAiD;QACjD,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,YAAY,EAAE;QACZ,YAAY,EAAE,MAAM,IAAI,CAAC;QACzB,YAAY,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;QACjD,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;KAC7C,CAAC;IACF,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACnC,uEAAuE;IACvE,UAAU,EAAE,MAAM,OAAO,CAAC;IAC1B;;;OAGG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,OAAO,CAAC;IAChC;;;;OAIG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,YAAY,EAAE,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;CAChD;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CAiWvB"}

package/dist/hooks/useMenuHover.js

@@ -4,37 +4,29 @@
 
 /**
  * @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.js";
 import { useListFocus } from "./useListFocus.js";
@@ -43,13 +35,10 @@ import { focusForLastInput } from "../utils/focusReturn.js";
 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;
 
@@ -168,10 +157,9 @@ export function useMenuHover(options) {
     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;
@@ -196,8 +184,8 @@ export function useMenuHover(options) {
     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]);
@@ -265,9 +253,10 @@ export function useMenuHover(options) {
     }
     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;
@@ -343,12 +332,9 @@ export function useMenuHover(options) {
         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;