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

package/src/hooks/useActionGroupTracking.ts

@@ -0,0 +1,224 @@
+// 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, type RefObject} from 'react';
+import {isActive} from '../gestures/GestureRecognizer';
+import {LongPressGestureRecognizer} from '../gestures/LongPressGestureRecognizer';
+import {lockSelection} from '../utils/selectionLock';
+import type {GestureTouch, PointerKind} from '../gestures/types';
+import {useGestureRecognizer} from '../gestures/useGestureRecognizer';
+import {UIKIT_PRESS} from '../motion/uikit/gestures';
+import {isIosWebKit} from '../utils/touchQueries';
+import {createActionGroupTracker} from './actionGroupTracker';
+import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
+
+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;
+}
+
+const PRESS = UIKIT_PRESS;
+
+/** The ref handed to the recognizer while tracking is off: no element. */
+const DETACHED: RefObject<Element | null> = {current: null};
+
+const EVERY_POINTER: ReadonlyArray<PointerKind> = ['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 {
+  protected override acceptsTouch(touch: GestureTouch): boolean {
+    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: RefObject<HTMLElement | null>,
+  options: ActionGroupTrackingOptions,
+): ActionGroupPress {
+  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<PointerKind>('touch');
+  const landedRef = useRef<Node | null>(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 as Node | null;
+            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: LongPressGestureRecognizer,
+  touch: GestureTouch,
+  options: ActionGroupTrackingOptions,
+): boolean {
+  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/src/hooks/useAnimator.doc.mjs

@@ -0,0 +1,109 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useAnimator',
+  displayName: 'useAnimator',
+  keywords: [
+    'animate',
+    'animation',
+    'animator',
+    'spring',
+    'decay',
+    'momentum',
+    'fling',
+    'motion',
+    'transform',
+    'opacity',
+    'drag',
+    'card',
+  ],
+  params: [
+    {
+      name: 'ref',
+      type: 'RefObject<HTMLElement | null>',
+      description:
+        'The ref of the one element to animate, the same ref you pass to the element: another hook, such as a gesture hook, can take it too, so a drag and an animation share one element. After every render the animator follows the element behind it. When the element unmounts its motion stops and its values return to rest, so a remount starts at rest, and so does a node that replaces it. Before the element mounts, and while it is unmounted, every call does nothing and `animate` and `decay` resolve at once.',
+      required: true,
+    },
+  ],
+  returns: [
+    {
+      name: 'animator',
+      type: 'AnimatorHandle',
+      description:
+        "The element's animator, the same object on every render: `animate(target, {velocity?})` springs channels to a target on the state-change motion Astryx's components use, `decay(velocity)` coasts them from a release velocity, `set(values)` jumps them, `get()` and `getVelocity()` read them, and `stop()` halts them. The channels are `x` and `y` (px), `scale` (1 at the element's size), `rotate` (degrees) and `opacity` (0 to 1). `animate` and `decay` return a promise that resolves when the motion ends. Calling it never re-renders the component. Calls before the ref attaches do nothing and resolve at once.",
+    },
+  ],
+  usage: {
+    description:
+      "Animates one element with the motion Astryx's own components use. Call `animator.animate` to spring an element to new values on the state-change motion, `animator.decay` to fling it with the momentum of a released scroll view, and `animator.set` to move it directly, so a card can follow a finger, snap back and be thrown away. To animate an area's layout as its items change, use `useAnimatedLayout`; for what a component already animates, such as a sheet's detents or a carousel's snapping, use the component's own props. Outside React, use `createAnimator`.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Call the animator from event handlers and effects: it lives outside render, so animating never re-renders the component.',
+      },
+      {
+        guidance: true,
+        description:
+          'Start every `animate` that follows a drag with the release velocity, so the element carries on as it was thrown.',
+      },
+      {
+        guidance: true,
+        description:
+          'Reach every state an animation shows without the animation too: a key, a button or a menu item that calls the same code.',
+      },
+      {
+        guidance: false,
+        description:
+          'Keep the animated values in React state: read them with `animator.get()` when you need them.',
+      },
+    ],
+    accessibility: [
+      {
+        name: 'Keyboard and assistive technology',
+        category: 'Keyboard',
+        description:
+          'An animator moves an element; it adds no way to act. Give every action an animation stands for a control a keyboard and a screen reader can reach, such as a button that discards a card, and have it call `animate`, which Reduce Motion turns into a fade in place. Keep `decay` for a throw the person made: Reduce Motion keeps the momentum of a coast, as it continues that throw. Keep focus on an element that stays on screen: move it before you fling its element away.',
+      },
+      {
+        name: 'Reduce Motion',
+        category: 'Content',
+        criterion: '2.3.3 Animation from Interactions',
+        description:
+          'When the person asks for reduced motion, every call is planned for them. On a touch screen a move or a scale becomes a short opacity cross-fade: the element fades out where it was and fades back in where it lands. With a mouse it lands at once. A decay of `x` and `y` keeps its momentum, as it continues the throw the person made; a decay of `scale`, `rotate` or `opacity` is planned like a move. No option turns this off.',
+      },
+    ],
+  },
+  relatedHooks: ['useAnimatedLayout'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'interaction',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    "Animates the element behind ref (x, y, scale, rotate, opacity) with Astryx's motion; returns the animator.",
+  paramDescriptions: {
+    ref: 'The element ref; share it with a gesture hook to drag and animate one element.',
+  },
+  returnDescriptions: {
+    animator:
+      'animate(target, {velocity?}), decay(velocity), set, get, getVelocity, stop; stable, never re-renders.',
+  },
+  usage: {
+    description:
+      'Spring with animate, fling with decay, follow a finger with set. Reduce Motion: a cross-fade on touch, at once with a mouse; decay keeps its momentum.',
+    bestPractices: [
+      {
+        guidance: true,
+        description: 'Pass the release velocity to animate after a drag.',
+      },
+      {
+        guidance: false,
+        description: 'Keep animated values in state; read animator.get().',
+      },
+    ],
+  },
+};

package/src/hooks/useAnimator.ts

@@ -0,0 +1,67 @@
+// 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, type RefObject} from 'react';
+import {
+  createAttachableAnimator,
+  type AnimatorHandle,
+} from '../animator/createAnimator';
+import {useAttachment} from './useAttachment';
+
+/**
+ * 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: RefObject<HTMLElement | null>,
+): AnimatorHandle {
+  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: HTMLElement) => {
+        attachElement(element);
+        return () => attachElement(null);
+      },
+    };
+  });
+  useAttachment(ref, attach, null);
+  return handle;
+}

package/src/hooks/useAttachment.ts

@@ -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/src/hooks/useHighlightedOptionScroll.ts

@@ -8,7 +8,8 @@
  *   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
  */
@@ -27,6 +28,21 @@ 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;
+
+interface WaitingHover {
+  index: number;
+  onHighlight?: () => void;
+}
+
 /**
  * Keep the highlighted option visible during keyboard navigation — but not for
  * hover highlights. Hover must highlight only: scrollIntoView moves the next
@@ -34,6 +50,10 @@ 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 function useHighlightedOptionScroll({
   isOpen,
@@ -41,31 +61,119 @@ export function useHighlightedOptionScroll({
   setHighlightedIndex,
   getOptionId,
   itemCount,
-}: UseHighlightedOptionScrollOptions): (index: number) => void {
-  const hoverHighlightRef = useRef(false);
+}: UseHighlightedOptionScrollOptions): HighlightFromHover {
+  // The callback reads no render state, so memoized rows keep one function.
+  const hoveredIndexRef = useRef<number | null>(null);
+  const shownIndexRef = useRef(highlightedIndex);
+  // The hover that came while a keyboard move held the highlight.
+  const waitingHoverRef = useRef<WaitingHover | null>(null);
+  // Set only while a keyboard move holds the highlight.
+  const removeHoldListenersRef = useRef<(() => void) | null>(null);
+  const setHighlightedIndexRef = useRef(setHighlightedIndex);
+  // The pointer's last screen position a hold saw, kept across holds.
+  const lastPointerRef = useRef<{x: number; y: number} | null>(null);
+
+  const applyHover = useCallback((hover: WaitingHover) => {
+    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: PointerEvent) => {
+      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} as const;
+    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: number) => {
-      if (index !== highlightedIndex) {
-        hoverHighlightRef.current = true;
+  const highlightFromHover = useCallback<HighlightFromHover>(
+    (index, onHighlight) => {
+      if (removeHoldListenersRef.current != null) {
+        waitingHoverRef.current = {index, onHighlight};
+        return;
       }
+      hoveredIndexRef.current = index;
       setHighlightedIndex(index);
+      onHighlight?.();
     },
-    [highlightedIndex, setHighlightedIndex],
+    [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?.({block: 'nearest'});
-  }, [isOpen, highlightedIndex, getOptionId, itemCount]);
+    startHold();
+    option.scrollIntoView?.({block: 'nearest'});
+  }, [isOpen, highlightedIndex, getOptionId, itemCount, endHold, startHold]);
 
   return highlightFromHover;
 }

package/src/hooks/useInputStatusIcon.tsx

@@ -15,9 +15,10 @@
 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 {Icon, type IconSize} from '../Icon/Icon';
+import type {IconName} from '../Icon/globalIconRegistry';
 import type {InputStatus, InputStatusType} from '../Field/types';
-import {useTooltip} from '../Tooltip';
+import {useTooltip} from '../Tooltip/useTooltip';
 import {radiusVars} from '../theme/tokens.stylex';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';

package/src/hooks/useLongPress.doc.mjs

@@ -59,7 +59,7 @@ export const docs = {
   ],
   usage: {
     description:
-      'Detects a single-finger press-and-hold and reports where it happened, so touch users can reach affordances that a pointer gets from right-click. iOS Safari never synthesizes a contextmenu event on long-press, which makes this the only touch route into a cursor-positioned surface such as ContextMenu. The press cancels on movement, lift, multi-touch or unmount.',
+      'Detects a single-finger press-and-hold and reports where it happened, so touch users can reach affordances that a pointer gets from right-click. iOS Safari never synthesizes a contextmenu event on long-press, which makes this the only touch route into a cursor-positioned surface such as ContextMenu. The press cancels on movement, lift, multi-touch or unmount. The hold is timed on the touch events\u2019 own timestamps: when a busy page handles the lift late, a finger held for the full delay still reports its long press, before the lift acts.',
     bestPractices: [
       {
         guidance: true,
@@ -102,7 +102,7 @@ export const docsDense = {
   },
   usage: {
     description:
-      'Touch press-and-hold for affordances a pointer reaches by right-click (e.g. ContextMenu). Reports the point so the surface opens under the finger.',
+      "Touch press-and-hold for affordances a pointer reaches by right-click (e.g. ContextMenu). Reports the point so the surface opens under the finger. Timed on the touch events' timestamps: a busy page delays the report, never drops it.",
     bestPractices: [
       {
         guidance: true,