@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/hooks/useIndicatorFocusRing.tsx

@@ -10,43 +10,19 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts (exports)
- *
- * A checkbox or radio focuses a native `<input>` that is `opacity: 0`, so the
- * visible focus indicator has to appear on the picture beside it — and that
- * picture is a themeable indicator, which is what makes "who draws the ring"
- * awkward:
- *
- * - Only the indicator's own element can shape the ring: `outline` follows
- *   that element's `border-radius`. Draw it on a wrapper and the owner has to
- *   hardcode a guess about whatever indicator it hosts (RadioListItem used to
- *   carry `border-radius: 50%` for a circle it did not own).
- * - But an indicator supplied by a theme is third-party code. If drawing the
- *   ring is its job, a replacement that simply doesn't ships a control with no
- *   visible focus (WCAG 2.4.7) — and that is the DEFAULT outcome: the sample
- *   replacement in our own Storybook destructures `{state, size, isDisabled}`
- *   and drops the rest, which is what a theme author plausibly writes. Nothing
- *   can enforce otherwise; a component ignoring every prop is still assignable
- *   to `IndicatorComponent`, and branding the return type does not work either
- *   (JSX types every expression as `JSX.Element`).
- *
- * So the owner draws it, on the indicator's own element, imperatively at focus
- * time. No cooperation is required and none can be forgotten.
- *
- * Two details that are load-bearing, both measured rather than assumed:
- *
- * 1. **Inline style, not a class.** React replaces `className` wholesale on
- *    re-render, so an injected class disappears the moment the control changes
- *    state — pressing Space on a focused checkbox lost the ring. React
- *    reconciles `style` per property, so an `outline` set here survives.
- * 2. **`:focus-visible`, not `:focus`.** The CSS this replaces got
- *    keyboard-vs-pointer for free; an event handler has to ask. Checking the
- *    element keeps the browser's heuristic, including `focus({focusVisible:
- *    true})`, which a hand-rolled modality guess would miss.
- *
- * Imperative styling on an interaction event follows `useTableSelection`,
- * which sets row-selection styles the same way.
  */
 
+// The owner draws the ring on the indicator's own element, at focus time:
+// - Only that element can shape the ring, because `outline` follows its
+//   `border-radius`.
+// - A theme can replace the indicator, and a replacement can drop any prop.
+//   If the indicator drew the ring, such a replacement would have no visible
+//   focus. No type can make it keep the props.
+// - The ring is an inline style, not a class. React replaces `className` on
+//   re-render, but it updates `style` per property, so the outline stays.
+// - The handler checks `:focus-visible`, not focus. This keeps the browser's
+//   heuristic, including `focus({focusVisible: true})`.
+
 import {useCallback, useMemo} from 'react';
 import type {FocusEvent, RefObject} from 'react';
 import {
@@ -86,9 +62,8 @@ export function useIndicatorFocusRing(
 ): UseIndicatorFocusRingReturn {
   const paint = useCallback(
     (on: boolean) => {
-      // `firstElementChild`, not a search: the container holds the indicator
-      // and nothing else, so there is no ambiguity — and no way for a later
-      // sibling to quietly become the target.
+      // The container holds only the indicator, so its first child is the
+      // target. A later sibling can never become the target.
       const indicator = containerRef.current?.firstElementChild;
       if (indicator instanceof HTMLElement) {
         Object.assign(

package/src/hooks/useInputStatusIcon.tsx

@@ -10,39 +10,25 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts (exports)
- *
- * Centralizes the on-field status icon across the bordered inputs (TextInput,
- * TextArea, NumberInput, DateInput, DateTimeInput, DateRangeInput, TimeInput,
- * FileInput) so the three statusVariants behave consistently:
- *
- * - `attached`  → icon sits inside the control; the message box below carries
- *   the text.
- * - `detached`  → the detached message box renders its OWN leading icon, so the
- *   on-field icon is suppressed here to avoid a duplicate glyph.
- * - `tooltip`   → no message box renders; the status is surfaced through an
- *   info-tip on the on-field icon. The icon is a real focusable `<button>` so
- *   the status is reachable by every user, not just those with hover or a
- *   screen reader:
- *     - Keyboard (no AT): the button is in the tab order (WCAG 2.1.1) with a
- *       visible focus ring (WCAG 2.4.7); focusing it opens the tooltip.
- *     - Pointer: hover opens it (guarded to fine pointers).
- *     - Touch: hover is unavailable, so a tap toggles the tooltip open/closed.
- *     - Assistive tech: the button has an accessible name (its status type,
- *       WCAG 4.1.2) and is described by the message via `aria-describedby`.
- *     - Dismissible with Escape and hoverable (WCAG 1.4.13) via useTooltip.
  */
 
 import {useCallback, useEffect, useState} from 'react';
 import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Icon, type IconName, type IconSize} from '../Icon';
-import type {FieldStatusVariant} from '../FieldStatus/FieldStatus';
 import type {InputStatus, InputStatusType} from '../Field/types';
 import {useTooltip} from '../Tooltip';
-import {useTranslator} from '../i18n';
 import {radiusVars} from '../theme/tokens.stylex';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
+import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
+import {
+  registerEnglishFallback,
+  useComponentTranslator,
+} from '../i18n/useComponentTranslator';
+import english from '../i18n/generated-english/hooks/useInputStatusIcon.generated';
+
+registerEnglishFallback(english);
 
 /**
  * Maps each status type to its glyph. Shared so every input shows the same icon
@@ -86,12 +72,9 @@ const styles = stylex.create({
       default: 'pointer',
       ':is(:disabled,[aria-disabled="true"])': 'default',
     },
-    // Own the interactivity so the tooltip opens on hover even when the field
-    // renders this affordance inside a non-interactive trailing slot. TextArea
-    // positions its end slot as an absolute overlay with `pointer-events: none`
-    // (right for the decorative spinner/icon it was built for), which otherwise
-    // swallows this button's hover — keyboard focus still worked, pointer did
-    // not.
+    // The button owns its pointer events, so hover opens the tooltip in a
+    // non-interactive trailing slot. TextArea's end slot has
+    // `pointer-events: none`, which would block this button's hover.
     pointerEvents: 'auto',
     borderRadius: radiusVars['--radius-full'],
     // Not the shared offset: this button sits inside the field, and measured at
@@ -104,7 +87,7 @@ export interface UseInputStatusIconOptions {
   /** The input's status, or undefined when there is none. */
   status?: InputStatus;
   /** How the status is presented relative to the input. */
-  statusVariant?: FieldStatusVariant;
+  statusVariant?: FieldStatusPlacement;
   /** Whether the input is inside an InputGroup (which owns status rendering). */
   isInGroup?: boolean;
   /** Size of the on-field icon. @default 'md' */
@@ -132,7 +115,15 @@ export interface UseInputStatusIconReturn {
 
 /**
  * Builds the on-field status icon and its accessibility wiring for a bordered
- * input. See the file header for the per-variant behavior.
+ * input, so every bordered input shows status the same way:
+ * - `attached`: the icon is in the control, and the message box below has
+ *   the text.
+ * - `detached`: the message box shows its own leading icon, so this hook
+ *   shows none.
+ * - `tooltip`: no message box. The icon is a focusable `<button>` with an
+ *   info-tip, so every user can reach the status. Focus or a fine-pointer
+ *   hover opens it, and a tap toggles it on touch. Its accessible name is the
+ *   status type, and the message describes it. Escape dismisses it.
  */
 export function useInputStatusIcon({
   status,
@@ -140,7 +131,7 @@ export function useInputStatusIcon({
   isInGroup = false,
   size = 'md',
 }: UseInputStatusIconOptions): UseInputStatusIconReturn {
-  const t = useTranslator();
+  const t = useComponentTranslator();
   const isTooltipVariant = statusVariant === 'tooltip';
   const hasTooltip = isTooltipVariant && !!status?.message;
 
@@ -156,9 +147,8 @@ export function useInputStatusIcon({
     isOpen: tapOpen,
   });
 
-  // Re-hand control back to hover/focus once a tap-opened tooltip is dismissed
-  // (Escape/outside interaction), so subsequent pointer/keyboard use behaves
-  // normally.
+  // Give control back to hover and focus after a tap-opened tooltip is
+  // dismissed.
   const handleButtonBlur = useCallback(() => {
     setTapOpen(undefined);
   }, []);
@@ -177,9 +167,8 @@ export function useInputStatusIcon({
     setTapOpen(prev => (prev === true ? false : true));
   }, []);
 
-  // Dismiss a tap-opened tooltip on Escape and return to the uncontrolled
-  // state (useTooltip owns Escape for the uncontrolled case, but while we hold
-  // control via isOpen it does not, so mirror it here).
+  // Escape dismisses a tap-opened tooltip and returns to the uncontrolled
+  // state. useTooltip handles Escape only when it is uncontrolled.
   useEffect(() => {
     if (tapOpen !== true) {
       return;
@@ -207,11 +196,9 @@ export function useInputStatusIcon({
       icon={STATUS_ICON[status.type]}
       size={size}
       color={status.type}
-      // Stable theme target on the status glyph itself, so a theme can restyle
-      // just this icon (color, size) — and each status — via `defineTheme`.
-      // Same-element rules in @layer astryx-theme win over the icon's own base
-      // width/height/fontSize, which a field-level target could not reach.
-      // Shared by the attached and tooltip variants across all bordered inputs.
+      // A stable theme target on the glyph, so a theme can restyle this icon
+      // for each status. Same-element rules in @layer astryx-theme override
+      // the icon's base size, which a field-level target cannot reach.
       {...themeProps('input-status-icon', {size, status: status.type})}
     />
   );

package/src/hooks/useInteractiveRole.ts

@@ -4,24 +4,11 @@
 
 /**
  * @file useInteractiveRole.ts
- * @input Uses useInteractiveTrigger
- * @output Exports useInteractiveRole hook and InteractiveRole type
- * @position Hook utility; consumed by Token, Thumbnail, Item, ClickableCard, etc.
- *
- * Centralizes the "what element should I render as?" decision for
- * polymorphic components. The priority order:
- *
- *   1. href → 'link' (navigation always wins, unless disabled)
- *   2. onClick → 'button' (explicit interactivity)
- *   3. interactive trigger context → 'button' (implicit via parent)
- *   4. else → 'inert' (non-interactive)
- *
- * A disabled `href` is excluded at step 1 and therefore resolves via the
- * remaining steps — 'inert' when no onClick or context applies.
- *
- * This hook is the single place to add new context-based triggers
- * (e.g., Popover, DropdownMenu, Disclosure). Components that consume
- * this hook never need updating when new trigger contexts are added.
+ * @input useInteractiveTrigger
+ * @output useInteractiveRole hook and InteractiveRole type
+ * @position Hook utility for polymorphic components such as Token, Thumbnail,
+ *   Item and ClickableCard. Add new context-based triggers here, so the
+ *   components that use this hook need no change.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts (export)
@@ -90,13 +77,11 @@ export function useInteractiveRole({
 }: UseInteractiveRoleOptions): InteractiveRole {
   const contextRole = useInteractiveRoleContext();
 
-  // 1. href → link (unless disabled — a disabled href is skipped here and
-  // resolved by the checks below, landing on 'inert' if nothing else applies)
+  // A disabled href is skipped, so the checks below decide the role.
   if (href != null && !isDisabled) {
     return 'link';
   }
 
-  // 2. Explicit onClick → button
   if (onClick != null) {
     return 'button';
   }
@@ -106,6 +91,5 @@ export function useInteractiveRole({
     return contextRole;
   }
 
-  // 4. Nothing interactive → inert
   return 'inert';
 }

package/src/hooks/useKeyboardHint.tsx

@@ -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)
@@ -27,7 +27,13 @@ import {
 } from '../theme/tokens.stylex';
 import {Kbd} from '../Kbd';
 import {useLayer} from '../Layer/useLayer';
-import {useTranslator} from '../i18n';
+import {
+  registerEnglishFallback,
+  useComponentTranslator,
+} from '../i18n/useComponentTranslator';
+import english from '../i18n/generated-english/hooks/useKeyboardHint.generated';
+
+registerEnglishFallback(english);
 
 // ---------------------------------------------------------------------------
 // Types
@@ -181,7 +187,7 @@ export function useKeyboardHint(
     isEnabled = true,
   } = options;
 
-  const t = useTranslator();
+  const t = useComponentTranslator();
   const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const dismissedRef = useRef(false);
   const isVisibleRef = useRef(false);
@@ -259,8 +265,14 @@ export function useKeyboardHint(
       if (!target.matches(':focus-visible')) {
         return;
       }
-      // Only show when focus enters from outside the container
       const container = e.currentTarget as HTMLElement;
+      // 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)

package/src/hooks/useListFocus.ts

@@ -21,6 +21,7 @@
 import {useCallback, useRef} from 'react';
 import {isRtlElement} from './isRtlElement';
 import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
+import {focusForLastInput} from '../utils/focusReturn';
 
 /**
  * Navigation orientation for a linear list.
@@ -121,6 +122,31 @@ 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
  */
@@ -325,6 +351,16 @@ function shouldDeferToCaret(target: EventTarget | null, key: string): boolean {
  */
 export function useListFocus<T extends HTMLElement = HTMLElement>(
   options: UseListFocusOptions = {},
+): UseListFocusReturn<T> {
+  return useInternalListFocus<T>(options);
+}
+
+/**
+ * {@link useListFocus} with the Core-only {@link InternalListFocusOptions}.
+ * Not re-exported from `hooks/index.ts`.
+ */
+export function useInternalListFocus<T extends HTMLElement = HTMLElement>(
+  options: InternalListFocusOptions = {},
 ): UseListFocusReturn<T> {
   const {
     itemSelector = '[role="menuitem"]',
@@ -335,7 +371,9 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(
     hasHomeEnd = true,
     hasPaging = false,
     hasRovingTabIndex = false,
+    tabStopOrder,
     hasCaretGuard = false,
+    focusFollowsLastInput = false,
   } = options;
 
   const listRef = useRef<T>(null);
@@ -459,6 +497,17 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(
    * 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) {
@@ -469,7 +518,7 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(
     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.
@@ -490,13 +539,24 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(
         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();
+      if (focusFollowsLastInput) {
+        focusForLastInput(target);
+      } else {
+        target.focus();
+      }
     },
-    [hasRovingTabIndex, setTabIndex],
+    [hasRovingTabIndex, setTabIndex, focusFollowsLastInput, tabStopOrder],
   );
 
   /**
@@ -706,16 +766,34 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(
 
       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);
         }
@@ -746,6 +824,7 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(
       focusPage,
       onEscape,
       ownsEvent,
+      tabStopOrder,
     ],
   );
 

package/src/hooks/useLongPress.ts

@@ -11,29 +11,31 @@
  *   `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';
 
-// Default long-press tuning.
-const DEFAULT_DELAY_MS = 500;
-const DEFAULT_MOVE_CANCEL_PX = 10;
+// 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;
 
 export interface UseLongPressOptions {
   /** Fired with the touch start point once the press is held for `delayMs`. */
@@ -46,6 +48,14 @@ export interface UseLongPressOptions {
   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;
@@ -66,9 +76,39 @@ export interface UseLongPressHandlers {
   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 function useLongPress(
   options: UseLongPressOptions,
 ): UseLongPressHandlers {
+  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: {x: number; y: number}) => start(point),
+    [start],
+  );
+  return {...handlers, start: startAt};
+}
+
+/** @internal useLongPress with a per-press tolerance (LongPressDetectorHandlers). */
+export function useLongPressDetector(
+  options: UseLongPressOptions,
+): LongPressDetectorHandlers {
   const {
     onLongPress,
     disabled = false,
@@ -78,6 +118,8 @@ export function useLongPress(
 
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const startRef = useRef<{x: number; y: number} | null>(null);
+  // The press in progress's tolerance, when its caller chose one at start.
+  const pressToleranceRef = useRef<LongPressTolerance | null>(null);
   // Keep the latest callback without re-creating handlers on every render.
   const onLongPressRef = useRef(onLongPress);
   onLongPressRef.current = onLongPress;
@@ -91,14 +133,15 @@ export function useLongPress(
   }, []);
 
   const start = useCallback(
-    (point: {x: number; y: number}) => {
+    (point: {x: number; y: number}, tolerance?: LongPressTolerance) => {
       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) {
@@ -116,11 +159,12 @@ export function useLongPress(
       if (from == null) {
         return false;
       }
+      // 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) > moveCancelPx ||
-        Math.abs(point.y - from.y) > moveCancelPx
+        Math.abs(point.x - from.x) > limit ||
+        Math.abs(point.y - from.y) > limit
       ) {
-        // Treat as a scroll/drag, not a long-press.
         clear();
         return false;
       }
@@ -135,7 +179,6 @@ export function useLongPress(
         return;
       }
       if (e.touches.length !== 1) {
-        // Multi-touch cancels any pending long-press.
         clear();
         return;
       }
@@ -151,7 +194,6 @@ export function useLongPress(
         return;
       }
       if (e.touches.length !== 1) {
-        // Multi-touch cancels the pending long-press.
         clear();
         return;
       }
@@ -161,7 +203,6 @@ export function useLongPress(
     [clear, moveTo],
   );
 
-  // Cancel any pending long-press timer on unmount.
   useEffect(() => clear, [clear]);
 
   return {