Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
33.1 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file useMenuPress.ts
 * @input The menu root, its trigger, the enabled-row selector, and callbacks
 *   for opening, highlighting, activating and dismissing
 * @output useMenuPress, the marker attributes, the activation mark, and the
 *   internal useDropdownMenuPress entry with its touch model
 * @position Core hook for DropdownMenu, ContextMenu, DropdownMenuSubMenu,
 *   Selector and MenuBottomSheetActionList. The transition table lives in
 *   menuPressGesture.ts.
 *
 * SYNC: When modified, update:
 * - /packages/core/src/hooks/index.ts
 * - /packages/core/src/hooks/useMenuPress.doc.mjs
 * - /packages/core/src/hooks/useMenuPress.test.tsx
 * - /packages/core/src/hooks/menuPressGesture.ts
 */

import {
  useCallback,
  useEffect,
  useMemo,
  useRef,
  useState,
  type RefObject,
} from 'react';
import {currentGesture} from '../Layer/gestureCounter';
import {isInputShield} from '../Layer/inputHold';
import {
  IDLE_MENU_PRESS,
  menuPressTransition,
  type MenuPressOutcome,
  type MenuPressInput,
  type MenuPressState,
  type MenuPressPointerType,
} from './menuPressGesture';
import {MENU_PRESS_MARKER} from './menuPressMarker';
import {
  useLongPressDetector,
  type LongPressDetectorHandlers,
  type LongPressTolerance,
} from './useLongPress';
import {edgeAutoscroll} from '../utils/edgeAutoscroll';
import {focusForLastInput} from '../utils/focusReturn';
import {useInteractionModalityTrackingFor} from '../utils/interactionModality';
import {LONG_PRESS_DURATION_MS} from '../motion/uikit/longPress';
import {
  clearMenuPressLit,
  holdMenuPressPaint,
  markMenuPressLit,
  releaseMenuPressPaint,
} from '../privateAttributes/menuPressLit.stylex';
import {
  __resetClickGuardForTest,
  armClickGuard,
  CLICK_GUARD_WINDOW_MS,
  withoutClickGuard,
} from '../utils/clickGuard';

export {MENU_PRESS_MARKER};
const MENU_PRESS_ROOT_SELECTOR = `[${MENU_PRESS_MARKER}]`;
/**
 * Carried by a menu root that another root renders beside itself rather than
 * inside it, naming that root's `id`: the menu of a sub-menu with a header or
 * footer, in a dialog beside the root's menu, is nested in that root for the
 * press model, as a flyout inside the root's DOM is. Nothing else beside the
 * root carries it, so a picker placed in a header or footer stays its own root.
 */
export const MENU_PRESS_SURFACE_ATTR = 'data-astryx-menu-press-surface';

/**
 * How long after a tracked release the browser's click is still swallowed:
 * the shared click guard's window (utils/clickGuard.ts).
 */
export const MENU_PRESS_STRAY_CLICK_MS = CLICK_GUARD_WINDOW_MS;
/** How long a finger must rest on the trigger before the menu opens under it. */
export const MENU_PRESS_LONG_PRESS_MS = LONG_PRESS_DURATION_MS;
/**
 * How far a finger held on a DropdownMenu trigger may move before the open,
 * in CSS px, under every primary pointer. A native menu still opens after a
 * 12 pt move. ContextMenu keeps the long press's own allowable movement.
 */
export const MENU_PRESS_TRIGGER_DRIFT_PX = 13;

/** A held finger on the trigger gets the same drift allowance under every primary pointer. */
const TRIGGER_TOLERANCE: LongPressTolerance = {
  moveCancelPx: MENU_PRESS_TRIGGER_DRIFT_PX,
};
/** Distance from a scrolling menu's edge within which a resting pointer scrolls. */
export const MENU_PRESS_AUTOSCROLL_ZONE_PX = 24;
const AUTOSCROLL_STEP_PX = 6;
const AUTOSCROLL_INTERVAL_MS = 16;

const FOCUSABLE_ROW_SELECTOR =
  '[tabindex], a[href], button, input, select, textarea, [contenteditable]';
const INNER_CONTROL_SELECTOR = 'a[href], button, [tabindex]';

let isModelActivation = false;

/**
 * Whether a menu row activation dispatched by the press model is in flight.
 * True for the synchronous extent of that dispatch, so a row that forwards
 * the activation to a control inside it (a link) can tell the model's click
 * from the browser's stray one.
 */
export function isMenuPressActivation(): boolean {
  return isModelActivation;
}

/** Test-only: forget an armed click guard between cases. */
export function __resetMenuPressForTest(): void {
  __resetClickGuardForTest();
}

export interface UseMenuPressOptions {
  /** The menu (or listbox) root: the surface whose rows the press picks from. */
  menuRef: RefObject<HTMLElement | null>;
  /** The control that opens the menu, when the press may start there. */
  triggerRef?: RefObject<HTMLElement | null>;
  /**
   * Selector matching the ENABLED rows. A pointer over anything else inside
   * the menu — a divider, a heading, a disabled row — highlights nothing.
   */
  itemSelector: string;
  /**
   * A mouse pressed the trigger, or a finger has rested on it for the
   * long-press delay: open the menu under the held pointer. Return whether
   * it opened; a `false` (the press closed an open menu instead) ends the
   * gesture. The click the trigger receives for this same gesture is reported
   * by {@link UseMenuPressReturn.isTriggerClickFromPress} so the caller can
   * leave it alone.
   */
  onTriggerPress?: (pointerType: MenuPressPointerType) => boolean;
  /**
   * Move the highlight. `null` clears it. Defaults to moving DOM focus with
   * `preventScroll` onto the row (or the control inside it), and onto the
   * menu root when there is no row — a picker that highlights through
   * `aria-activedescendant` supplies its own.
   */
  onHighlight?: (row: HTMLElement | null) => void;
  /**
   * Act on the row under the release. Defaults to dispatching a click on the
   * row that carries the release's button and modifier keys, so the row acts
   * exactly as its own click would.
   */
  onActivate?: (row: HTMLElement, release: PointerEvent) => void;
  /** A MOUSE was released outside the menu with nothing acting: close it. */
  onDismiss?: () => void;
  /**
   * The element to scroll while a tracked pointer rests near its edge.
   * Defaults to the menu root when it overflows; return `null` for none.
   */
  getScroller?: () => HTMLElement | null;
  /**
   * Resolve the element under a viewport point. Defaults to
   * `elementFromPoint` on the menu's own document or shadow root, falling back
   * to the event target where the document lacks it (jsdom). A test seam.
   */
  hitTest?: (x: number, y: number) => Element | null;
  /** @default 500 */
  longPressDelayMs?: number;
  /** Whether the model is live. @default true */
  isEnabled?: boolean;
}

export interface UseMenuPressReturn {
  /** Spread onto the menu root: claims presses that begin inside it. */
  menuProps: {
    onPointerDown: (event: React.PointerEvent<HTMLElement>) => void;
    [MENU_PRESS_MARKER]: '';
  };
  /** Spread onto the trigger: a mouse press opens; a held finger opens. */
  triggerProps: {
    onPointerDown: (event: React.PointerEvent<HTMLElement>) => void;
    onContextMenu: (event: React.MouseEvent<HTMLElement>) => void;
  };
  /**
   * Whether the click reaching the trigger belongs to the gesture that just
   * pressed it — the press already opened or closed the menu, so the click
   * must neither toggle nor reopen it.
   */
  isTriggerClickFromPress: () => boolean;
  /** End the gesture in flight with nothing acting (the menu closed). */
  cancel: () => void;
}

function normalizePointerType(type: string): MenuPressPointerType | null {
  return type === 'mouse' || type === 'touch' || type === 'pen' ? type : null;
}

function isRowFocusable(row: HTMLElement): boolean {
  return row.matches(FOCUSABLE_ROW_SELECTOR);
}

/** The outermost marked root: a flyout is a DOM descendant of its parent menu. */
function getOutermostRoot(menu: HTMLElement): HTMLElement {
  let root = menu;
  for (;;) {
    const parent =
      root.parentElement?.closest<HTMLElement>(MENU_PRESS_ROOT_SELECTOR) ??
      getSurfaceOwner(root);
    if (parent == null || parent === root) {
      return root;
    }
    root = parent;
  }
}

/**
 * The menu root that renders `menu` beside itself, if any (see
 * `MENU_PRESS_SURFACE_ATTR`). Read off the menu itself, never an ancestor, so
 * a root placed in a region of that surface is not adopted.
 */
function getSurfaceOwner(menu: HTMLElement): HTMLElement | null {
  const ownerId = menu.getAttribute(MENU_PRESS_SURFACE_ATTR);
  if (!ownerId) {
    return null;
  }
  const owner = menu.ownerDocument.getElementById(ownerId);
  return owner?.matches(MENU_PRESS_ROOT_SELECTOR) === true ? owner : null;
}

/**
 * Whether `element` is inside the menu tree whose outermost root is `root`:
 * inside the root itself, or inside a menu nested in it through a surface
 * the root renders beside itself. Anything else in such a surface (a header
 * field, say) is outside the menu, as the root's own regions are.
 */
function isInMenuTree(element: Element, root: HTMLElement): boolean {
  if (root.contains(element)) {
    return true;
  }
  const owner = element.closest<HTMLElement>(MENU_PRESS_ROOT_SELECTOR);
  return owner != null && getOutermostRoot(owner) === root;
}

interface ResolvedPoint {
  row: HTMLElement | null;
  isInMenu: boolean;
  isOnTrigger: boolean;
}

/**
 * DropdownMenu's options for the press model: everything the public hook
 * takes, plus its touch model. DropdownMenu reaches the touch model through
 * its `presentation`, so the public hook has no such option.
 *
 * @internal
 */
export interface DropdownMenuPressOptions extends UseMenuPressOptions {
  /**
   * How the finger that opened the menu from the trigger picks.
   * `'pointer'`: its opening press follows the settle rule. `'uikit'`: it
   * picks only after UIMenu's handoff distance, so the row that appeared
   * under it never acts on a still lift. A mouse is unaffected.
   * @default 'pointer'
   */
  touchModel?: 'pointer' | 'uikit';
}

/**
 * What core's own menus get from {@link useDropdownMenuPress}: the public
 * return. Not exported from the hooks entry point.
 *
 * @internal
 */
export type DropdownMenuPressReturn = UseMenuPressReturn;

/**
 * Where a pointer is, for a finger's handoff distance. Positions reach the
 * machine only under `touchModel: 'uikit'`. Without them, it keeps the settle
 * rule.
 */
function handoffPosition(
  event: PointerEvent,
  hasHandoff: boolean,
): {x?: number; y?: number} {
  return hasHandoff ? {x: event.clientX, y: event.clientY} : {};
}

/**
 * The press model for a menu: the row under the release acts, the highlight
 * follows a held pointer, and a mouse opens the menu on press.
 *
 * - The document tracks the pointer by `pointerId`. A finger's events stay
 *   with the element it landed on, so the menu never sees a finger that slid
 *   onto it.
 * - The release acts on its row as the row's own click would, with the
 *   release's button and modifier keys.
 * - The browser's stray `click` after a tracked release is swallowed at the
 *   window, in the capture phase. A click with `detail === 0` always passes.
 * - A finger held on the trigger opens the menu after the long-press delay.
 *   The settle rule in menuPressGesture.ts decides if that release can act.
 * - `pointercancel`, a second pointer, or a window blur ends the gesture, and
 *   nothing acts.
 * - A pointer that rests near the edge of an overflowing menu scrolls it.
 * - The root carries `data-astryx-menu-press`, so a nested flyout can tell
 *   which level owns a press.
 *
 * @example
 * ```
 * const menuPress = useMenuPress({
 *   menuRef: listRef,
 *   triggerRef: buttonRef,
 *   itemSelector: MENU_ITEM_SELECTOR,
 *   onTriggerPress: () => openMenu(),
 *   onDismiss: closeMenu,
 * });
 * <button {...menuPress.triggerProps} onClick={e => {
 *   if (menuPress.isTriggerClickFromPress()) return;
 *   toggle();
 * }} />
 * <div ref={listRef} role="menu" {...menuPress.menuProps}>…</div>
 * ```
 */
export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
  // The touch model is DropdownMenu's alone; an untyped caller's
  // `touchModel` does not reach the model.
  const {touchModel: _touchModel, ...publicOptions} =
    options as DropdownMenuPressOptions;
  return useDropdownMenuPress({...publicOptions, touchModel: 'pointer'});
}

/**
 * The press model with DropdownMenu's touch model
 * ({@link DropdownMenuPressOptions.touchModel}). Not exported from the hooks
 * entry point.
 *
 * @internal
 */
export function useDropdownMenuPress(
  options: DropdownMenuPressOptions,
): DropdownMenuPressReturn {
  const optionsRef = useRef(options);
  optionsRef.current = options;
  // The highlight, and the hover focus of the rows in this menu, follow the
  // last input, which this tracks for the menu's own document.
  useInteractionModalityTrackingFor(options.menuRef);

  const gestureRef = useRef<MenuPressState<HTMLElement>>(IDLE_MENU_PRESS);
  const pointerIdRef = useRef<number | null>(null);
  const detachRef = useRef<(() => void) | null>(null);
  // `useLongPress` detects the held finger, as in ContextMenu, so the hold
  // time and the movement tolerance have one home. A ref holds the handle,
  // because the pointer handlers below are stable and the hook is created
  // after `fireLongPress`.
  const longPressApiRef = useRef<LongPressDetectorHandlers | null>(null);
  const touchMovePreventerRef = useRef<(() => void) | null>(null);
  // The edge autoscroll running now: its scroller, its direction, and the
  // re-read of the row under the resting pointer after each step.
  const autoscrollRef = useRef<{
    scroller: HTMLElement;
    direction: 1 | -1;
    reread: () => void;
  } | null>(null);
  const [autoscroll] = useState(() =>
    edgeAutoscroll({
      intervalMs: AUTOSCROLL_INTERVAL_MS,
      immediate: true,
      step: () => (autoscrollRef.current?.direction ?? 0) * AUTOSCROLL_STEP_PX,
      apply: delta => {
        const running = autoscrollRef.current;
        if (running == null) {
          return 0;
        }
        const before = running.scroller.scrollTop;
        running.scroller.scrollTop = before + delta;
        const moved = running.scroller.scrollTop - before;
        if (moved === 0) {
          // The edge is reached. There is nothing more to show.
          autoscrollRef.current = null;
          return 0;
        }
        running.reread();
        return moved;
      },
    }),
  );
  const lastPointerEventRef = useRef<PointerEvent | null>(null);
  const triggerGestureRef = useRef<number | null>(null);
  // The second pointer that ended a gesture must not start the next one.
  const ignoredPointerIdRef = useRef<number | null>(null);

  const getDocument = useCallback((): Document => {
    return (
      optionsRef.current.menuRef.current?.ownerDocument ??
      optionsRef.current.triggerRef?.current?.ownerDocument ??
      document
    );
  }, []);

  const resolvePoint = useCallback(
    (event: PointerEvent): ResolvedPoint => {
      const {menuRef, triggerRef, itemSelector, hitTest} = optionsRef.current;
      const menu = menuRef.current;
      const doc = getDocument();
      let element: Element | null;
      if (hitTest != null) {
        element = hitTest(event.clientX, event.clientY);
      } else if (typeof doc.elementFromPoint === 'function') {
        // Hit-test in the menu's own tree: inside a shadow root the document
        // answers with the shadow host, never the row under the pointer.
        const tree = menu?.getRootNode();
        const scope: Pick<Document, 'elementFromPoint' | 'elementsFromPoint'> =
          tree != null &&
          tree !== doc &&
          typeof (tree as ShadowRoot).elementFromPoint === 'function'
            ? (tree as ShadowRoot)
            : doc;
        element = scope.elementFromPoint(event.clientX, event.clientY);
        if (
          isInputShield(element) &&
          typeof scope.elementsFromPoint === 'function'
        ) {
          // An input hold's shield covers the viewport while the menu enters.
          // It keeps new input away, but the press in flight still reaches the
          // row under it. So the hit test sees through that shield only.
          element =
            scope
              .elementsFromPoint(event.clientX, event.clientY)
              .find(candidate => !isInputShield(candidate)) ?? null;
        }
      } else {
        element = event.target instanceof Element ? event.target : null;
      }
      const root = menu == null ? null : getOutermostRoot(menu);
      const isInMenu =
        root != null && element != null && isInMenuTree(element, root);
      const trigger = triggerRef?.current ?? null;
      const isOnTrigger =
        trigger != null && element != null && trigger.contains(element);
      let row: HTMLElement | null = null;
      if (isInMenu && element != null) {
        row = element.closest<HTMLElement>(itemSelector);
        if (row != null && !isInMenuTree(row, root)) {
          row = null;
        }
      }
      return {row, isInMenu, isOnTrigger};
    },
    [getDocument],
  );

  const stopAutoscroll = useCallback(() => {
    autoscroll.stop();
    autoscrollRef.current = null;
  }, [autoscroll]);

  const litRowRef = useRef<HTMLElement | null>(null);
  const heldMenuRef = useRef<HTMLElement | null>(null);
  const endGesture = useCallback(() => {
    longPressApiRef.current?.cancel();
    if (litRowRef.current != null) {
      clearMenuPressLit(litRowRef.current);
      litRowRef.current = null;
    }
    if (heldMenuRef.current != null) {
      releaseMenuPressPaint(heldMenuRef.current);
      heldMenuRef.current = null;
    }
    touchMovePreventerRef.current?.();
    touchMovePreventerRef.current = null;
    stopAutoscroll();
    detachRef.current?.();
    detachRef.current = null;
    pointerIdRef.current = null;
    lastPointerEventRef.current = null;
    gestureRef.current = IDLE_MENU_PRESS;
  }, [stopAutoscroll]);

  const highlight = useCallback(
    (row: HTMLElement | null) => {
      // A held finger or pen marks the row it lights, for the row's pressed
      // paint. A held mouse keeps the hover tint, as on a desktop.
      const gesture = gestureRef.current;
      const isHeld =
        gesture.phase !== 'idle' && gesture.pointerType !== 'mouse';
      const lit = isHeld ? row : null;
      if (litRowRef.current !== lit) {
        if (litRowRef.current != null) {
          clearMenuPressLit(litRowRef.current);
        }
        litRowRef.current = lit;
        if (lit != null) {
          markMenuPressLit(lit);
        }
      }
      const {onHighlight, menuRef} = optionsRef.current;
      // The row the press began on stays :active where a pointer hovers, so
      // the menu holds every row but the lit one off that paint.
      const held = isHeld ? menuRef.current : null;
      if (heldMenuRef.current !== held) {
        if (heldMenuRef.current != null) {
          releaseMenuPressPaint(heldMenuRef.current);
        }
        heldMenuRef.current = held;
        if (held != null) {
          holdMenuPressPaint(held);
        }
      }
      if (onHighlight != null) {
        onHighlight(row);
        return;
      }
      // In a menu the highlight is focus. A row that takes no focus is
      // highlighted through its inner control. Over nothing, the menu root
      // holds focus, so no row is lit. A held press is pointer input, so the
      // row must not match :focus-visible. A plain focus() would keep the
      // modality of the earlier focus.
      const target =
        row == null
          ? menuRef.current
          : isRowFocusable(row)
            ? row
            : row.querySelector<HTMLElement>(INNER_CONTROL_SELECTOR);
      if (target != null && target !== getDocument().activeElement) {
        focusForLastInput(target, {preventScroll: true});
      }
    },
    [getDocument],
  );

  const activate = useCallback((row: HTMLElement, release: PointerEvent) => {
    // Every click this dispatches passes the shared click guard.
    withoutClickGuard(() => {
      const {onActivate} = optionsRef.current;
      isModelActivation = true;
      try {
        if (onActivate != null) {
          onActivate(row, release);
          return;
        }
        // The row acts as its own click would. `detail: 0` marks a dispatched
        // activation, as a keyboard's does, so the click guard lets it pass.
        // The button and the modifiers are the release's.
        row.dispatchEvent(
          new MouseEvent('click', {
            bubbles: true,
            cancelable: true,
            composed: true,
            detail: 0,
            button: release.button,
            clientX: release.clientX,
            clientY: release.clientY,
            screenX: release.screenX,
            screenY: release.screenY,
            ctrlKey: release.ctrlKey,
            shiftKey: release.shiftKey,
            altKey: release.altKey,
            metaKey: release.metaKey,
          }),
        );
      } finally {
        isModelActivation = false;
      }
    });
  }, []);

  // Declared before `step` so the mutual recursion through refs type-checks.
  const stepRef = useRef<
    (event: MenuPressInput<HTMLElement>, native?: PointerEvent) => void
  >(() => {});

  const applyEffect = useCallback(
    (
      effect: MenuPressOutcome<HTMLElement>,
      gesture: MenuPressState<HTMLElement>,
      native: PointerEvent | undefined,
    ) => {
      const doc = getDocument();
      switch (effect.type) {
        case 'none':
          return;
        case 'open': {
          const pointerType =
            gesture.phase === 'open' ? gesture.pointerType : 'mouse';
          triggerGestureRef.current = currentGesture();
          const didOpen =
            optionsRef.current.onTriggerPress?.(pointerType) ?? false;
          if (!didOpen) {
            endGesture();
          }
          return;
        }
        case 'highlight':
          highlight(effect.row);
          return;
        case 'clear':
          highlight(null);
          return;
        case 'act': {
          // Detach before acting: the activation usually closes the menu.
          endGesture();
          // Once armed, the one swallower stays installed.
          armClickGuard(doc, {
            staysInstalled: true,
            cancelsTouchEnd: native?.pointerType === 'touch',
          });
          if (native != null) {
            activate(effect.row, native);
          }
          return;
        }
        case 'settle': {
          endGesture();
          if (effect.stray) {
            armClickGuard(doc, {
              staysInstalled: true,
              cancelsTouchEnd: native?.pointerType === 'touch',
            });
          }
          if (effect.dismiss) {
            optionsRef.current.onDismiss?.();
          }
          return;
        }
      }
    },
    [activate, endGesture, getDocument, highlight],
  );

  const step = useCallback(
    (event: MenuPressInput<HTMLElement>, native?: PointerEvent) => {
      const result = menuPressTransition(gestureRef.current, event);
      gestureRef.current = result.gesture;
      applyEffect(result.effect, result.gesture, native);
    },
    [applyEffect],
  );
  stepRef.current = step;

  const getScroller = useCallback((): HTMLElement | null => {
    const {getScroller: custom, menuRef} = optionsRef.current;
    if (custom != null) {
      return custom();
    }
    const menu = menuRef.current;
    if (menu == null) {
      return null;
    }
    return menu.scrollHeight > menu.clientHeight + 1 ? menu : null;
  }, []);

  const updateAutoscroll = useCallback(
    (event: PointerEvent) => {
      if (gestureRef.current.phase !== 'tracking') {
        stopAutoscroll();
        return;
      }
      const scroller = getScroller();
      if (scroller == null) {
        stopAutoscroll();
        return;
      }
      const rect = scroller.getBoundingClientRect();
      if (rect.height <= 0) {
        stopAutoscroll();
        return;
      }
      let direction: 1 | -1 | 0 = 0;
      if (event.clientY <= rect.top + MENU_PRESS_AUTOSCROLL_ZONE_PX) {
        direction = -1;
      } else if (event.clientY >= rect.bottom - MENU_PRESS_AUTOSCROLL_ZONE_PX) {
        direction = 1;
      }
      if (direction === 0) {
        stopAutoscroll();
        return;
      }
      if (autoscrollRef.current?.direction === direction) {
        return;
      }
      stopAutoscroll();
      autoscrollRef.current = {
        scroller,
        direction,
        // The rows moved under the resting pointer: re-read the row under it.
        reread: () => {
          const last = lastPointerEventRef.current;
          if (last != null) {
            const point = resolvePoint(last);
            stepRef.current(
              {
                type: 'move',
                row: point.row,
                isInMenu: point.isInMenu,
                time: Date.now(),
              },
              last,
            );
          }
        },
      };
      autoscroll.update();
    },
    [autoscroll, getScroller, resolvePoint, stopAutoscroll],
  );

  const attach = useCallback(
    (pointerId: number) => {
      detachRef.current?.();
      const doc = getDocument();
      const view = doc.defaultView;
      pointerIdRef.current = pointerId;

      const onMove = (event: PointerEvent) => {
        if (event.pointerId !== pointerIdRef.current) {
          return;
        }
        lastPointerEventRef.current = event;
        const gesture = gestureRef.current;
        if (gesture.phase === 'triggerPress') {
          // A finger that moves past the drift allowance is scrolling, not
          // holding.
          const isPending = longPressApiRef.current?.moveTo({
            x: event.clientX,
            y: event.clientY,
          });
          if (isPending === false) {
            stepRef.current({type: 'cancel'});
          }
          return;
        }
        const point = resolvePoint(event);
        stepRef.current(
          {
            type: 'move',
            row: point.row,
            isInMenu: point.isInMenu,
            time: Date.now(),
            ...handoffPosition(
              event,
              optionsRef.current.touchModel === 'uikit',
            ),
          },
          event,
        );
        updateAutoscroll(event);
      };
      const onUp = (event: PointerEvent) => {
        if (event.pointerId !== pointerIdRef.current) {
          return;
        }
        const point = resolvePoint(event);
        stepRef.current(
          {
            type: 'up',
            row: point.row,
            isInMenu: point.isInMenu,
            isOnTrigger: point.isOnTrigger,
            time: Date.now(),
            ...handoffPosition(
              event,
              optionsRef.current.touchModel === 'uikit',
            ),
          },
          event,
        );
      };
      const onCancel = (event: PointerEvent) => {
        if (event.pointerId !== pointerIdRef.current) {
          return;
        }
        stepRef.current({type: 'cancel'});
      };
      const onOtherPointerDown = (event: PointerEvent) => {
        // A second pointer ends the gesture: two fingers are a pinch or a
        // scroll, never a pick.
        if (event.pointerId !== pointerIdRef.current) {
          ignoredPointerIdRef.current = event.pointerId;
          stepRef.current({type: 'cancel'});
        }
      };
      const onBlur = () => {
        stepRef.current({type: 'cancel'});
      };

      doc.addEventListener('pointermove', onMove, true);
      doc.addEventListener('pointerup', onUp, true);
      doc.addEventListener('pointercancel', onCancel, true);
      doc.addEventListener('pointerdown', onOtherPointerDown, true);
      view?.addEventListener('blur', onBlur);
      detachRef.current = () => {
        doc.removeEventListener('pointermove', onMove, true);
        doc.removeEventListener('pointerup', onUp, true);
        doc.removeEventListener('pointercancel', onCancel, true);
        doc.removeEventListener('pointerdown', onOtherPointerDown, true);
        view?.removeEventListener('blur', onBlur);
      };
    },
    [getDocument, resolvePoint, updateAutoscroll],
  );

  const fireLongPress = useCallback(() => {
    const gesture = gestureRef.current;
    if (gesture.phase !== 'triggerPress') {
      return;
    }
    triggerGestureRef.current = currentGesture();
    const didOpen =
      optionsRef.current.onTriggerPress?.(gesture.pointerType) ?? false;
    if (!didOpen) {
      step({type: 'cancel'});
      return;
    }
    // `touch-action` on the trigger was decided when the finger landed; the
    // page must not scroll under a finger that is now driving a menu.
    const doc = getDocument();
    const prevent = (event: TouchEvent) => {
      if (event.cancelable) {
        event.preventDefault();
      }
    };
    doc.addEventListener('touchmove', prevent, {passive: false, capture: true});
    touchMovePreventerRef.current = () => {
      doc.removeEventListener('touchmove', prevent, true);
    };
    step({type: 'opened', time: Date.now()});
  }, [getDocument, step]);

  // The same long-press detector as ContextMenu, driven from the pointer
  // stream this model already observes. Only its hold time, movement
  // tolerance and timer are used. The trigger uses one drift allowance under
  // every primary pointer, so no menu, row or trigger reads the pointer query.
  longPressApiRef.current = useLongPressDetector({
    onLongPress: fireLongPress,
    delayMs: options.longPressDelayMs ?? MENU_PRESS_LONG_PRESS_MS,
  });

  const handleMenuPointerDown = useCallback(
    (event: React.PointerEvent<HTMLElement>) => {
      const {menuRef, isEnabled = true} = optionsRef.current;
      const menu = menuRef.current;
      if (!isEnabled || menu == null) {
        return;
      }
      if (event.pointerId === ignoredPointerIdRef.current) {
        ignoredPointerIdRef.current = null;
        return;
      }
      if (gestureRef.current.phase !== 'idle') {
        // A second pointer landed inside the menu.
        step({type: 'cancel'});
        return;
      }
      const pointerType = normalizePointerType(event.pointerType);
      if (pointerType == null) {
        return;
      }
      if (pointerType === 'mouse' && event.button !== 0) {
        return;
      }
      // The innermost model owns the press: a flyout is a DOM descendant of
      // its parent menu, and both would otherwise track the same pointer.
      const target = event.target as Element | null;
      if (target?.closest(MENU_PRESS_ROOT_SELECTOR) !== menu) {
        return;
      }
      if (pointerType !== 'mouse') {
        // Cancelling pointerdown stops the compatibility mouse events that a
        // finger fires at its landing row when it lifts. That mousedown would
        // light the origin row again. touch-action controls scrolling, so
        // scrolling does not change.
        event.preventDefault();
      }
      const native = event.nativeEvent;
      attach(native.pointerId);
      lastPointerEventRef.current = native;
      const point = resolvePoint(native);
      step(
        {
          type: 'down',
          target: 'menu',
          pointerType,
          row: point.row,
          time: Date.now(),
        },
        native,
      );
    },
    [attach, resolvePoint, step],
  );

  const handleTriggerPointerDown = useCallback(
    (event: React.PointerEvent<HTMLElement>) => {
      const {isEnabled = true} = optionsRef.current;
      if (event.pointerId === ignoredPointerIdRef.current) {
        ignoredPointerIdRef.current = null;
        return;
      }
      if (!isEnabled || gestureRef.current.phase !== 'idle') {
        return;
      }
      const pointerType = normalizePointerType(event.pointerType);
      if (pointerType == null || event.button !== 0) {
        return;
      }
      if (pointerType === 'mouse' && event.ctrlKey) {
        // Control-click is the context menu's on macOS.
        return;
      }
      const native = event.nativeEvent;
      attach(native.pointerId);
      lastPointerEventRef.current = native;
      if (pointerType !== 'mouse') {
        longPressApiRef.current?.start(
          {x: native.clientX, y: native.clientY},
          TRIGGER_TOLERANCE,
        );
      }
      step(
        {
          type: 'down',
          target: 'trigger',
          pointerType,
          row: null,
          time: Date.now(),
        },
        native,
      );
    },
    [attach, step],
  );

  const handleTriggerContextMenu = useCallback(
    (event: React.MouseEvent<HTMLElement>) => {
      // A finger held on the trigger is opening the menu, not asking for the
      // browser's own context menu.
      const gesture = gestureRef.current;
      if (gesture.phase !== 'idle' && gesture.pointerType !== 'mouse') {
        event.preventDefault();
      }
    },
    [],
  );

  const isTriggerClickFromPress = useCallback((): boolean => {
    return (
      triggerGestureRef.current != null &&
      triggerGestureRef.current === currentGesture()
    );
  }, []);

  const cancel = useCallback(() => {
    if (gestureRef.current.phase !== 'idle') {
      step({type: 'cancel'});
    }
    endGesture();
  }, [endGesture, step]);

  // Syncs the document listeners of the menu gesture counter with this mount.
  // Unmount ends the gesture.
  useEffect(() => {
    // Install the gesture counter's listeners before the first press.
    currentGesture();
    return () => {
      endGesture();
    };
  }, [endGesture]);

  return useMemo<UseMenuPressReturn>(
    () => ({
      menuProps: {
        onPointerDown: handleMenuPointerDown,
        [MENU_PRESS_MARKER]: '',
      },
      triggerProps: {
        onPointerDown: handleTriggerPointerDown,
        onContextMenu: handleTriggerContextMenu,
      },
      isTriggerClickFromPress,
      cancel,
    }),
    [
      handleMenuPointerDown,
      handleTriggerPointerDown,
      handleTriggerContextMenu,
      isTriggerClickFromPress,
      cancel,
    ],
  );
}