@astryxdesign/core 0.7.7-canary.c0929c8 → 0.7.7-canary.c19ca12

package/dist/hooks/index.js

@@ -35,6 +35,7 @@ export { useClickableContainer, INTERACTIVE_SELECTORS, hasInteractiveAncestor, h
 export { useInputContainer } from "./useInputContainer.js";
 export { useInputStatusIcon } from "./useInputStatusIcon.js";
 export { useInteractiveRole } from "./useInteractiveRole.js";
+export { useAnimator } from "./useAnimator.js";
 export { useLongPress } from "./useLongPress.js";
 export { usePressFeedback } from "./usePressFeedback.js";
 export { useDevWarning } from "./useDevWarning.js";

package/dist/hooks/pressGroupContext.d.ts

@@ -0,0 +1,6 @@
+/**
+ * True inside a group whose tracker paints a pointer's press on its actions.
+ * Those actions take no `:active` paint, so one press never lights two.
+ */
+export declare const PressGroupContext: import("react").Context<boolean>;
+//# sourceMappingURL=pressGroupContext.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pressGroupContext.d.ts","sourceRoot":"","sources":["../../src/hooks/pressGroupContext.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,eAAO,MAAM,iBAAiB,kCAAuB,CAAC"}

package/dist/hooks/pressGroupContext.js

@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file pressGroupContext.ts
+ * @input Nothing
+ * @output PressGroupContext: true inside a group whose own tracker paints
+ *   its actions' press
+ * @position Internal; not exported from the hooks entry. AlertDialog
+ *   provides it around its tracked actions, and Button reads it.
+ */
+import { createContext } from 'react';
+
+/**
+ * True inside a group whose tracker paints a pointer's press on its actions.
+ * Those actions take no `:active` paint, so one press never lights two.
+ */
+export const PressGroupContext = /*#__PURE__*/createContext(false);
+PressGroupContext.displayName = 'PressGroupContext';

package/dist/hooks/useActionGroupTracking.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @file useActionGroupTracking.ts
+ * @input A ref to a group of sibling actions, the actions' selector, and the
+ *   component's tracking constants
+ * @output Exports useActionGroupTracking and ActionGroupTrackingOptions
+ * @position Internal hook, not exported from the hooks entry. A long press
+ *   drives the shared action-group tracker (hooks/actionGroupTracker.ts) for
+ *   a group that a held pointer slides across. AlertDialog consumes it.
+ *
+ * SYNC: When modified, update useActionGroupTracking.test.tsx
+ */
+import { type RefObject } from 'react';
+import { LongPressGestureRecognizer } from '../gestures/LongPressGestureRecognizer.js';
+import type { GestureTouch, PointerKind } from '../gestures/types.js';
+export interface ActionGroupTrackingOptions {
+    /** Selects the actions inside the tracked element. */
+    itemSelector: string;
+    /** How long after touch-down the touched action highlights, ms. */
+    highlightOnsetMs: number;
+    /**
+     * How far outside an action a finger keeps it highlighted, px. A mouse or a
+     * pen hit-tests the actions' exact rects.
+     */
+    highlightExpansion: number;
+    /** Pointers that are tracked; others keep the browser's click. @default every pointer */
+    pointerTypes?: ReadonlyArray<PointerKind>;
+    /** A press whose target this rejects is not tracked. */
+    shouldTrack?: (target: unknown) => boolean;
+    /** Off, nothing is attached and nothing is tracked. @default true */
+    isEnabled?: boolean;
+    /**
+     * Let the gesture host write the group's `touch-action` and refuse a text
+     * selection while a finger or a pen holds it.
+     * @default true
+     */
+    manageStyle?: boolean;
+    /** Runs the action under the finger at the lift. @default its own click */
+    onActivate?: (item: HTMLElement) => void;
+}
+/**
+ * The group's press: a long press that a second finger on the group ends with
+ * nothing acting. A plain long press ignores a second finger.
+ */
+declare class ActionGroupPress extends LongPressGestureRecognizer {
+    protected acceptsTouch(touch: GestureTouch): boolean;
+}
+/**
+ * Track a held pointer on the group behind `ref` across the actions inside
+ * it, through the shared action-group tracker.
+ */
+export declare function useActionGroupTracking(ref: RefObject<HTMLElement | null>, options: ActionGroupTrackingOptions): ActionGroupPress;
+export {};
+//# sourceMappingURL=useActionGroupTracking.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useActionGroupTracking.d.ts","sourceRoot":"","sources":["../../src/hooks/useActionGroupTracking.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,OAAO,EAA8B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAElE,OAAO,EAAC,0BAA0B,EAAC,MAAM,wCAAwC,CAAC;AAElF,OAAO,KAAK,EAAC,YAAY,EAAE,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAOjE,MAAM,WAAW,0BAA0B;IACzC,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yFAAyF;IACzF,YAAY,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC1C,wDAAwD;IACxD,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IAC3C,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;CAC1C;AASD;;;GAGG;AACH,cAAM,gBAAiB,SAAQ,0BAA0B;cACpC,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO;CAO9D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAClC,OAAO,EAAE,0BAA0B,GAClC,gBAAgB,CAoHlB"}

package/dist/hooks/useActionGroupTracking.js

@@ -0,0 +1,174 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useActionGroupTracking.ts
+ * @input A ref to a group of sibling actions, the actions' selector, and the
+ *   component's tracking constants
+ * @output Exports useActionGroupTracking and ActionGroupTrackingOptions
+ * @position Internal hook, not exported from the hooks entry. A long press
+ *   drives the shared action-group tracker (hooks/actionGroupTracker.ts) for
+ *   a group that a held pointer slides across. AlertDialog consumes it.
+ *
+ * SYNC: When modified, update useActionGroupTracking.test.tsx
+ */
+import { useEffect, useRef, useState } from 'react';
+import { isActive } from "../gestures/GestureRecognizer.js";
+import { LongPressGestureRecognizer } from "../gestures/LongPressGestureRecognizer.js";
+import { lockSelection } from "../utils/selectionLock.js";
+import { useGestureRecognizer } from "../gestures/useGestureRecognizer.js";
+import { UIKIT_PRESS } from "../motion/uikit/gestures.js";
+import { isIosWebKit } from "../utils/touchQueries.js";
+import { createActionGroupTracker } from "./actionGroupTracker.js";
+import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
+const PRESS = UIKIT_PRESS;
+
+/** The ref handed to the recognizer while tracking is off: no element. */
+const DETACHED = {
+  current: null
+};
+const EVERY_POINTER = ['touch', 'pen', 'mouse'];
+
+/**
+ * The group's press: a long press that a second finger on the group ends with
+ * nothing acting. A plain long press ignores a second finger.
+ */
+class ActionGroupPress extends LongPressGestureRecognizer {
+  acceptsTouch(touch) {
+    if (isActive(this.state)) {
+      this.setState('cancelled');
+      return false;
+    }
+    return super.acceptsTouch(touch);
+  }
+}
+
+/**
+ * Track a held pointer on the group behind `ref` across the actions inside
+ * it, through the shared action-group tracker.
+ */
+export function useActionGroupTracking(ref, options) {
+  const optionsRef = useRef(options);
+  // Keeps the recognizer's delegate and the tracker, which run outside
+  // render, reading the latest options.
+  useIsomorphicLayoutEffect(() => {
+    optionsRef.current = options;
+  });
+  // The pointer that started the current press. Only a finger gets the hit
+  // expansion; a mouse or a pen hit-tests the actions' exact rects.
+  const pointerRef = useRef('touch');
+  const landedRef = useRef(null);
+  const [tracker] = useState(() => createActionGroupTracker(() => ({
+    roots: () => [ref.current],
+    itemSelector: optionsRef.current.itemSelector,
+    highlightExpansion: pointerRef.current === 'touch' ? optionsRef.current.highlightExpansion : 0,
+    onActivate: optionsRef.current.onActivate,
+    // The browser's own click for a press the group ran is taken, so the
+    // action runs once. The gesture host swallows it for a press it claims.
+    // This covers one it does not claim, a mouse under a coarse pointer.
+    swallowsNativeClick: true
+  })));
+  const isEnabled = options.isEnabled ?? true;
+  // Synchronizes the tracker with tracking on and mounted. Turning tracking
+  // off, or unmounting, drops a tracked press and ends its release fades.
+  // The host reports no cancellation to a disabled recognizer, and the lift
+  // that runs an action often closes the owner before its fade ends.
+  useEffect(() => () => {
+    tracker.cancel();
+    tracker.dispose();
+  }, [tracker, isEnabled]);
+  return useGestureRecognizer(isEnabled ? ref : DETACHED, () => new ActionGroupPress({
+    name: 'ActionGroupTracking',
+    minimumPressDuration: options.highlightOnsetMs,
+    allowableMovement: Number.POSITIVE_INFINITY,
+    allowedPointerTypes: options.pointerTypes ?? EVERY_POINTER,
+    delaysTouchesBegan: true,
+    // The hold picks an action, so a held finger or pen starts no text
+    // selection and opens no callout while down. A long press brings this
+    // lock by default; this hold has no minimum duration, so it names it.
+    selectionLock: lockSelection,
+    shouldReceiveTouch: (recognizer, touch) => {
+      if (recognizer.numberOfTouches === 0) {
+        pointerRef.current = touch.pointerType;
+        const target = touch.target;
+        landedRef.current = typeof target?.nodeType === 'number' ? target : null;
+      }
+      return receiveTouch(recognizer, touch, optionsRef.current);
+    }
+  }), recognizer => {
+    switch (recognizer.state) {
+      case 'began':
+        {
+          const {
+            x,
+            y
+          } = recognizer.location();
+          tracker.begin(x, y, {
+            landed: landedRef.current
+          });
+          break;
+        }
+      case 'changed':
+        {
+          const {
+            x,
+            y
+          } = recognizer.location();
+          tracker.move(x, y);
+          break;
+        }
+      case 'ended':
+        {
+          const doc = ref.current?.ownerDocument;
+          const focusedBefore = doc?.activeElement ?? null;
+          const beganOn = tracker.beganOn;
+          // Whether a click on the lifted action would focus it. A mouse's or
+          // a pen's pointerdown already gave the engine's answer, on the action
+          // it began on. A tap focuses on a later mousedown, which the claimed
+          // touch cancels, so the platform answers for a finger.
+          // iOS WebKit focuses no tapped button; Chromium and Firefox do.
+          const clickFocuses = pointerRef.current === 'touch' ? !isIosWebKit(doc?.defaultView) : beganOn != null && focusedBefore === beganOn;
+          const lifted = tracker.end();
+          // The lift runs the action's own click(), which moves no focus. So
+          // focus moves to the lifted action, unless its click moved focus.
+          if (clickFocuses && lifted != null && lifted.isConnected && doc?.activeElement === focusedBefore && focusedBefore !== lifted) {
+            lifted.focus({
+              preventScroll: true,
+              focusVisible: false
+            });
+          }
+          break;
+        }
+      case 'cancelled':
+        tracker.cancel();
+        break;
+      case 'possible':
+      case 'failed':
+        // Listeners are not called for these.
+        break;
+    }
+  }, {
+    isEnabled,
+    manageStyle: options.manageStyle ?? true,
+    actionGroup: true
+  });
+}
+
+/**
+ * The recognizer's should-receive delegate. It also picks the press's clock.
+ * Inside a scroller the press waits the content-touch delay and fails past
+ * the slop, so the scroller takes a flick. Elsewhere it begins at once, with
+ * no movement limit.
+ */
+function receiveTouch(recognizer, touch, options) {
+  if (options.shouldTrack?.(touch.target) === false) {
+    return false;
+  }
+  if (recognizer.numberOfTouches === 0) {
+    const isInsideScroller = touch.scroll?.isInsideScroller === true;
+    recognizer.minimumPressDuration = isInsideScroller ? PRESS.contentTouchDelay.value : options.highlightOnsetMs;
+    recognizer.allowableMovement = isInsideScroller ? PRESS.slop.value : Number.POSITIVE_INFINITY;
+  }
+  return true;
+}

package/dist/hooks/useAnimator.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @file useAnimator.ts
+ * @input React (useState), the element ref the caller owns, the public
+ *   animator factory (animator/createAnimator.ts) and useAttachment
+ * @output Exports `useAnimator(ref)`: the public animator for the element
+ *   behind `ref`
+ * @position Public hook, exported from `@astryxdesign/core/hooks`. A thin
+ *   wrapper over `createAnimator` with no behavior of its own.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/useAnimator.test.tsx
+ * - /packages/core/src/hooks/useAnimator.doc.mjs
+ */
+import { type RefObject } from 'react';
+import { type AnimatorHandle } from '../animator/createAnimator.js';
+/**
+ * Animates the element behind `ref` with the motion Core uses. Call
+ * `animate`, `decay`, `set`, `get`, `getVelocity` or `stop` on the returned
+ * animator from event handlers and effects. Pass the same `ref` to a gesture
+ * hook to drag and animate one element.
+ *
+ * The hook makes the animator once, and animating never re-renders the
+ * component. After each commit, the animator follows the element behind
+ * `ref`, also a node that replaces it. An unmount stops running motion and
+ * drops the values. A remount, or a node that replaces the element, starts
+ * at rest. While no element is attached, every call does nothing, and
+ * `animate` and `decay` resolve at once.
+ *
+ * @example
+ * ```
+ * const ref = useRef<HTMLDivElement>(null);
+ * const animator = useAnimator(ref);
+ * return (
+ *   <div ref={ref} onClick={() => animator.animate({scale: 1.2})}>
+ *     Card
+ *   </div>
+ * );
+ * ```
+ */
+export declare function useAnimator(ref: RefObject<HTMLElement | null>): AnimatorHandle;
+//# sourceMappingURL=useAnimator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useAnimator.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnimator.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAW,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC/C,OAAO,EAEL,KAAK,cAAc,EACpB,MAAM,4BAA4B,CAAC;AAGpC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,GACjC,cAAc,CAehB"}

package/dist/hooks/useAnimator.js

@@ -0,0 +1,70 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useAnimator.ts
+ * @input React (useState), the element ref the caller owns, the public
+ *   animator factory (animator/createAnimator.ts) and useAttachment
+ * @output Exports `useAnimator(ref)`: the public animator for the element
+ *   behind `ref`
+ * @position Public hook, exported from `@astryxdesign/core/hooks`. A thin
+ *   wrapper over `createAnimator` with no behavior of its own.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/useAnimator.test.tsx
+ * - /packages/core/src/hooks/useAnimator.doc.mjs
+ */
+import { useState } from 'react';
+import { createAttachableAnimator } from "../animator/createAnimator.js";
+import { useAttachment } from "./useAttachment.js";
+
+/**
+ * Animates the element behind `ref` with the motion Core uses. Call
+ * `animate`, `decay`, `set`, `get`, `getVelocity` or `stop` on the returned
+ * animator from event handlers and effects. Pass the same `ref` to a gesture
+ * hook to drag and animate one element.
+ *
+ * The hook makes the animator once, and animating never re-renders the
+ * component. After each commit, the animator follows the element behind
+ * `ref`, also a node that replaces it. An unmount stops running motion and
+ * drops the values. A remount, or a node that replaces the element, starts
+ * at rest. While no element is attached, every call does nothing, and
+ * `animate` and `decay` resolve at once.
+ *
+ * @example
+ * ```
+ * const ref = useRef<HTMLDivElement>(null);
+ * const animator = useAnimator(ref);
+ * return (
+ *   <div ref={ref} onClick={() => animator.animate({scale: 1.2})}>
+ *     Card
+ *   </div>
+ * );
+ * ```
+ */
+export function useAnimator(ref) {
+  const [{
+    handle,
+    attach
+  }] = useState(() => {
+    const {
+      animator,
+      attach: attachElement
+    } = createAttachableAnimator();
+    // The handle without `destroy`: the hook owns the element's lifetime.
+    const {
+      destroy: _destroy,
+      ...handle
+    } = animator;
+    return {
+      handle,
+      attach: element => {
+        attachElement(element);
+        return () => attachElement(null);
+      }
+    };
+  });
+  useAttachment(ref, attach, null);
+  return handle;
+}

package/dist/hooks/useAttachment.d.ts

@@ -5,7 +5,7 @@
  * @output Exports useAttachment and useAttachmentPair (two elements): they keep
  *   the attach function bound to the nodes the refs hold across commits
  * @position Internal React helper, not in hooks/index.ts: the one attach and
- *   release lifecycle of the gesture hooks and the pager
+ *   release lifecycle of the gesture hooks, the pager and useAnimator
  *
  * SYNC: When modified, update gestures/__tests__/useGestureRecognizer.test.tsx,
  * gestures/__tests__/useFingerScroll.test.tsx and

package/dist/hooks/useAttachment.js

@@ -9,7 +9,7 @@
  * @output Exports useAttachment and useAttachmentPair (two elements): they keep
  *   the attach function bound to the nodes the refs hold across commits
  * @position Internal React helper, not in hooks/index.ts: the one attach and
- *   release lifecycle of the gesture hooks and the pager
+ *   release lifecycle of the gesture hooks, the pager and useAnimator
  *
  * SYNC: When modified, update gestures/__tests__/useGestureRecognizer.test.tsx,
  * gestures/__tests__/useFingerScroll.test.tsx and

package/dist/hooks/useHighlightedOptionScroll.d.ts

@@ -9,6 +9,12 @@ interface UseHighlightedOptionScrollOptions {
      */
     itemCount?: number;
 }
+/**
+ * Highlights the hovered option at `index`. `onHighlight` runs when the hover
+ * takes effect: at once, or after the pointer moves or presses when a
+ * keyboard move holds the highlight.
+ */
+export type HighlightFromHover = (index: number, onHighlight?: () => void) => void;
 /**
  * Keep the highlighted option visible during keyboard navigation — but not for
  * hover highlights. Hover must highlight only: scrollIntoView moves the next
@@ -16,7 +22,11 @@ interface UseHighlightedOptionScrollOptions {
  * scrolls again — a runaway auto-scroll loop with no user input.
  * Keyboard paths call the raw setter directly and keep their scrolling; hover
  * paths call the returned callback.
+ *
+ * A keyboard move holds the highlight. A key that scrolls the list moves rows
+ * under a still mouse, and the browser reports the row under it as entered;
+ * that row takes the highlight only once the pointer moves or presses.
  */
-export declare function useHighlightedOptionScroll({ isOpen, highlightedIndex, setHighlightedIndex, getOptionId, itemCount, }: UseHighlightedOptionScrollOptions): (index: number) => void;
+export declare function useHighlightedOptionScroll({ isOpen, highlightedIndex, setHighlightedIndex, getOptionId, itemCount, }: UseHighlightedOptionScrollOptions): HighlightFromHover;
 export {};
 //# sourceMappingURL=useHighlightedOptionScroll.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useHighlightedOptionScroll.d.ts","sourceRoot":"","sources":["../../src/hooks/useHighlightedOptionScroll.ts"],"names":[],"mappings":"AAiBA,UAAU,iCAAiC;IACzC,MAAM,EAAE,OAAO,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACvC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,MAAM,EACN,gBAAgB,EAChB,mBAAmB,EACnB,WAAW,EACX,SAAS,GACV,EAAE,iCAAiC,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CA2B7D"}
+{"version":3,"file":"useHighlightedOptionScroll.d.ts","sourceRoot":"","sources":["../../src/hooks/useHighlightedOptionScroll.ts"],"names":[],"mappings":"AAkBA,UAAU,iCAAiC;IACzC,MAAM,EAAE,OAAO,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACvC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,MAAM,IAAI,KACrB,IAAI,CAAC;AAOV;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,MAAM,EACN,gBAAgB,EAChB,mBAAmB,EACnB,WAAW,EACX,SAAS,GACV,EAAE,iCAAiC,GAAG,kBAAkB,CAmHxD"}

package/dist/hooks/useHighlightedOptionScroll.js

@@ -8,11 +8,19 @@
  *   option-id resolver for the owning listbox
  * @output Exports useHighlightedOptionScroll: keeps the highlighted option
  *   scrolled into view for keyboard navigation while hover-driven highlights
- *   never scroll
+ *   never scroll, and a hover after a keyboard move waits for the pointer to
+ *   move or press; the hover callback is stable while `setHighlightedIndex` is
  * @position Internal hook; used by useCombobox, useMultiCombobox,
  *   BaseTypeahead, and DateTimeInput — the owners of combobox highlight state
  */
 import { useCallback, useEffect, useRef } from 'react';
+
+/**
+ * Highlights the hovered option at `index`. `onHighlight` runs when the hover
+ * takes effect: at once, or after the pointer moves or presses when a
+ * keyboard move holds the highlight.
+ */
+
 /**
  * Keep the highlighted option visible during keyboard navigation — but not for
  * hover highlights. Hover must highlight only: scrollIntoView moves the next
@@ -20,6 +28,10 @@ import { useCallback, useEffect, useRef } from 'react';
  * scrolls again — a runaway auto-scroll loop with no user input.
  * Keyboard paths call the raw setter directly and keep their scrolling; hover
  * paths call the returned callback.
+ *
+ * A keyboard move holds the highlight. A key that scrolls the list moves rows
+ * under a still mouse, and the browser reports the row under it as entered;
+ * that row takes the highlight only once the pointer moves or presses.
  */
 export function useHighlightedOptionScroll({
   isOpen,
@@ -28,24 +40,113 @@ export function useHighlightedOptionScroll({
   getOptionId,
   itemCount
 }) {
-  const hoverHighlightRef = useRef(false);
-  const highlightFromHover = useCallback(index => {
-    if (index !== highlightedIndex) {
-      hoverHighlightRef.current = true;
+  // The callback reads no render state, so memoized rows keep one function.
+  const hoveredIndexRef = useRef(null);
+  const shownIndexRef = useRef(highlightedIndex);
+  // The hover that came while a keyboard move held the highlight.
+  const waitingHoverRef = useRef(null);
+  // Set only while a keyboard move holds the highlight.
+  const removeHoldListenersRef = useRef(null);
+  const setHighlightedIndexRef = useRef(setHighlightedIndex);
+  // The pointer's last screen position a hold saw, kept across holds.
+  const lastPointerRef = useRef(null);
+  const applyHover = useCallback(hover => {
+    hoveredIndexRef.current = hover.index;
+    setHighlightedIndexRef.current(hover.index);
+    hover.onHighlight?.();
+  }, []);
+  const endHold = useCallback(() => {
+    removeHoldListenersRef.current?.();
+    removeHoldListenersRef.current = null;
+  }, []);
+  const releaseHold = useCallback(() => {
+    endHold();
+    const waiting = waitingHoverRef.current;
+    waitingHoverRef.current = null;
+    if (waiting != null) {
+      applyHover(waiting);
+    }
+  }, [applyHover, endHold]);
+
+  // Holds the highlight until the pointer moves or presses. The listeners
+  // live only while the hold does. Movement is read by screen coordinates: a
+  // scroll moves the rows, not the pointer. The browser reports a row as
+  // entered before the move that reaches it, so the first real move gives
+  // that row the highlight. A press releases at once, so a held press lights
+  // the pressed row.
+  const startHold = useCallback(() => {
+    waitingHoverRef.current = null;
+    if (removeHoldListenersRef.current != null) {
+      return;
     }
+    const onPointerMove = event => {
+      const last = lastPointerRef.current;
+      lastPointerRef.current = {
+        x: event.screenX,
+        y: event.screenY
+      };
+      if (last != null && last.x === event.screenX && last.y === event.screenY) {
+        return;
+      }
+      releaseHold();
+    };
+    const options = {
+      capture: true,
+      passive: true
+    };
+    document.addEventListener('pointermove', onPointerMove, options);
+    document.addEventListener('pointerdown', releaseHold, options);
+    removeHoldListenersRef.current = () => {
+      document.removeEventListener('pointermove', onPointerMove, options);
+      document.removeEventListener('pointerdown', releaseHold, options);
+    };
+  }, [releaseHold]);
+  const highlightFromHover = useCallback((index, onHighlight) => {
+    if (removeHoldListenersRef.current != null) {
+      waitingHoverRef.current = {
+        index,
+        onHighlight
+      };
+      return;
+    }
+    hoveredIndexRef.current = index;
     setHighlightedIndex(index);
-  }, [highlightedIndex, setHighlightedIndex]);
+    onHighlight?.();
+  }, [setHighlightedIndex]);
+
+  // Effect: keeps the hold's document listeners calling the current setter.
+  useEffect(() => {
+    setHighlightedIndexRef.current = setHighlightedIndex;
+  }, [setHighlightedIndex]);
+
+  // Effect: removes the hold's document listeners on unmount.
+  useEffect(() => endHold, [endHold]);
+
+  // Effect: scrolls the highlighted option into view in the document, and
+  // starts or ends the hold on its document listeners.
   useEffect(() => {
-    if (hoverHighlightRef.current) {
-      hoverHighlightRef.current = false;
+    // Only a move to the hovered row came from the hover. A hover on the row
+    // already highlighted changes nothing, so a later run for the same row
+    // (a new list) still scrolls it into view.
+    const hasMoved = shownIndexRef.current !== highlightedIndex;
+    shownIndexRef.current = highlightedIndex;
+    const isFromHover = hasMoved && hoveredIndexRef.current === highlightedIndex;
+    hoveredIndexRef.current = null;
+    if (isFromHover) {
       return;
     }
-    if (!isOpen || highlightedIndex < 0) {
+    // A cleared highlight, a closed list, or a list that is not shown (a
+    // closed CommandPalette reports itself as open) has nothing to hold.
+    const option = isOpen && highlightedIndex >= 0 ? document.getElementById(getOptionId(highlightedIndex)) : null;
+    if (option == null) {
+      waitingHoverRef.current = null;
+      endHold();
       return;
     }
-    document.getElementById(getOptionId(highlightedIndex))?.scrollIntoView?.({
+    startHold();
+    option.scrollIntoView?.({
       block: 'nearest'
     });
-  }, [isOpen, highlightedIndex, getOptionId, itemCount]);
+  }, [isOpen, highlightedIndex, getOptionId, itemCount, endHold, startHold]);
   return highlightFromHover;
 }

package/dist/hooks/useInputStatusIcon.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import { type IconSize } from '../Icon/index.js';
+import { type IconSize } from '../Icon/Icon.js';
 import type { InputStatus } from '../Field/types.js';
 import type { FieldStatusPlacement } from '../Field/fieldStatusPlacement.js';
 export interface UseInputStatusIconOptions {

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

@@ -1 +1 @@
-{"version":3,"file":"useInputStatusIcon.d.ts","sourceRoot":"","sources":["../../src/hooks/useInputStatusIcon.tsx"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,EAAsB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAC3D,OAAO,KAAK,EAAC,WAAW,EAAkB,MAAM,gBAAgB,CAAC;AAKjE,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,+BAA+B,CAAC;AA8DxE,MAAM,WAAW,yBAAyB;IACxC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yDAAyD;IACzD,aAAa,CAAC,EAAE,oBAAoB,CAAC;IACrC,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,UAAU,EAAE,SAAS,CAAC;IACtB;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,MAAM,EACN,aAA0B,EAC1B,SAAiB,EACjB,IAAW,GACZ,EAAE,yBAAyB,GAAG,wBAAwB,CAoGtD"}
+{"version":3,"file":"useInputStatusIcon.d.ts","sourceRoot":"","sources":["../../src/hooks/useInputStatusIcon.tsx"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,EAAO,KAAK,QAAQ,EAAC,MAAM,cAAc,CAAC;AAEjD,OAAO,KAAK,EAAC,WAAW,EAAkB,MAAM,gBAAgB,CAAC;AAKjE,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,+BAA+B,CAAC;AA8DxE,MAAM,WAAW,yBAAyB;IACxC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yDAAyD;IACzD,aAAa,CAAC,EAAE,oBAAoB,CAAC;IACrC,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,UAAU,EAAE,SAAS,CAAC;IACtB;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,MAAM,EACN,aAA0B,EAC1B,SAAiB,EACjB,IAAW,GACZ,EAAE,yBAAyB,GAAG,wBAAwB,CAoGtD"}

package/dist/hooks/useInputStatusIcon.js

@@ -13,8 +13,8 @@
  */
 import { useCallback, useEffect, useState } from 'react';
 import * as stylex from '@stylexjs/stylex';
-import { Icon } from "../Icon/index.js";
-import { useTooltip } from "../Tooltip/index.js";
+import { Icon } from "../Icon/Icon.js";
+import { useTooltip } from "../Tooltip/useTooltip.js";
 import "../theme/tokens.stylex.js";
 import { radiusVars } from "../theme/tokens.stylex.js";
 import { themeProps } from "../utils/themeProps.js";

package/dist/hooks/useLongPress.d.ts

@@ -21,8 +21,12 @@ export interface LongPressTolerance {
 export interface UseLongPressHandlers {
     onTouchStart: (e: React.TouchEvent) => void;
     onTouchMove: (e: React.TouchEvent) => void;
-    onTouchEnd: () => void;
-    onTouchCancel: () => void;
+    /**
+     * The lift. Pass the event, so a press it is stamped past (its timer held
+     * back by a busy page) still reports first. Spreading the handlers does.
+     */
+    onTouchEnd: (e?: React.TouchEvent) => void;
+    onTouchCancel: (e?: React.TouchEvent) => void;
     /**
      * Begin detection at a point, for a caller driving this from its own
      * pointer events rather than the touch handlers above.

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

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"useLongPress.d.ts","sourceRoot":"","sources":["../../src/hooks/useLongPress.ts"],"names":[],"mappings":"AA+EA,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;;;OAGG;IACH,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC3C,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC9C;;;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,CAuL3B"}