@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/gestures/fingerScroll.ts

@@ -0,0 +1,208 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file fingerScroll.ts
+ * @input A scroller (an element, or the document for the page's own scroll),
+ *   its document's scroll and scrollend events, and the gesture host's
+ *   finger record
+ * @output Exports watchFingerScrolls and isFingerScroll
+ * @position Finger-scroll watch of packages/core/src/gestures (useFingerScroll
+ *   reads it), in its own module so a page that never asks never ships it;
+ *   internal to the touch module, not in the gestures barrel
+ *
+ * A watched scroller's scroll is a finger's from a scroll event while a
+ * finger that landed inside it is down, until the scroller's own `scrollend`
+ * (the momentum after the lift is still the finger's). A scroll that ends
+ * while its finger still rests there stays the finger's until the lift. A
+ * scroll the program starts while no finger is down there (`scrollTo`, a
+ * status-bar tap) is not. Where the browser sends no `scrollend`, a quiet
+ * spell of `SCROLL_END_FALLBACK_MS` after its last scroll event ends a
+ * finger's scroll instead. The host keeps the one finger record; this module
+ * adds only passive scroll listeners, and only while something is watched.
+ */
+
+import {subscribeInput} from '../utils/inputStream';
+import {isCoarsePointer, watchCoarsePointer} from '../utils/coarsePointer';
+import type {GestureHost} from './GestureHost';
+
+/**
+ * Where the browser sends no `scrollend`, how long a finger-driven scroller
+ * stays quiet (no scroll event) before its scroll counts as ended, in ms:
+ * longer than the gap between a momentum scroll's events, short enough that
+ * a program's scroll right after it is not read as the finger's.
+ */
+const SCROLL_END_FALLBACK_MS = 150;
+
+interface Watch {
+  /** Watched scrollers, and how many watchers each has. */
+  readonly scrollers: Map<Node, number>;
+  /** Watched scrollers whose current scroll is a finger's. */
+  readonly fingerScrollers: Set<Node>;
+  /** Finger scrolls whose `scrollend` came while the finger still rested. */
+  readonly endedWhileDown: Set<Node>;
+  stop: (() => void) | null;
+}
+
+const watches = new WeakMap<GestureHost, Watch>();
+
+function start(host: GestureHost, watch: Watch): () => void {
+  const doc = host.document;
+  const scrollerOf = (event: Event): Node | null => {
+    const target = event.target === doc ? doc : event.target;
+    return target instanceof Node ? target : null;
+  };
+  // A finger's scroll ends at the scroller's scrollend, or, where the
+  // browser sends none, after a quiet spell.
+  const endScroll = (scroller: Node): void => {
+    if (!watch.fingerScrollers.has(scroller)) {
+      return;
+    }
+    if (host.isFingerDownIn(scroller)) {
+      // The finger still rests there: the scroll is its until the lift.
+      watch.endedWhileDown.add(scroller);
+    } else {
+      watch.fingerScrollers.delete(scroller);
+    }
+  };
+  const scrollEndFallbacks = new Map<Node, ReturnType<typeof setTimeout>>();
+  const clearScrollEndFallback = (scroller: Node): void => {
+    const timer = scrollEndFallbacks.get(scroller);
+    if (timer != null) {
+      clearTimeout(timer);
+      scrollEndFallbacks.delete(scroller);
+    }
+  };
+  const hasScrollEnd = (): boolean => {
+    const view = doc.defaultView;
+    return view != null && 'onscrollend' in view;
+  };
+  const onScroll = (event: Event): void => {
+    const scroller = scrollerOf(event);
+    // A recognizer's own scroll (a menu's edge autoscroll) is never the
+    // finger's, even with a finger resting inside.
+    if (
+      scroller == null ||
+      !watch.scrollers.has(scroller) ||
+      host.isOwnScroll(scroller)
+    ) {
+      return;
+    }
+    watch.endedWhileDown.delete(scroller);
+    if (host.isFingerDownIn(scroller)) {
+      watch.fingerScrollers.add(scroller);
+    }
+    if (watch.fingerScrollers.has(scroller) && !hasScrollEnd()) {
+      clearScrollEndFallback(scroller);
+      scrollEndFallbacks.set(
+        scroller,
+        setTimeout(() => {
+          scrollEndFallbacks.delete(scroller);
+          endScroll(scroller);
+        }, SCROLL_END_FALLBACK_MS),
+      );
+    }
+  };
+  const onScrollEnd = (event: Event): void => {
+    const scroller = scrollerOf(event);
+    if (scroller != null) {
+      endScroll(scroller);
+    }
+  };
+  // A scroll that ended while its finger rested ends with the lift.
+  const onFingers = (): void => {
+    for (const scroller of watch.endedWhileDown) {
+      if (!host.isFingerDownIn(scroller)) {
+        watch.endedWhileDown.delete(scroller);
+        watch.fingerScrollers.delete(scroller);
+      }
+    }
+  };
+  // Its listeners are on only while the primary pointer is coarse
+  // (`spec:AST-094` FR19, FR24): elsewhere no finger scrolls, as far as the
+  // touch presentation is concerned. Passive, on the window's capture phase
+  // through the shared input stream.
+  const view = doc.defaultView;
+  let unsubscribers: (() => void)[] = [];
+  const listen = (on: boolean): void => {
+    if (view == null || on === unsubscribers.length > 0) {
+      return;
+    }
+    if (on) {
+      unsubscribers = [
+        subscribeInput(view, 'scroll', onScroll),
+        subscribeInput(view, 'scrollend', onScrollEnd),
+      ];
+    } else {
+      for (const stop of unsubscribers.splice(0)) {
+        stop();
+      }
+      for (const scroller of [...scrollEndFallbacks.keys()]) {
+        clearScrollEndFallback(scroller);
+      }
+      watch.fingerScrollers.clear();
+      watch.endedWhileDown.clear();
+    }
+  };
+  const stopWatchingPointer = watchCoarsePointer(view, listen);
+  listen(isCoarsePointer(view));
+  const unsubscribe = host.onFingersChange(onFingers);
+  const release = host.retain();
+  return () => {
+    stopWatchingPointer();
+    listen(false);
+    unsubscribe();
+    release();
+  };
+}
+
+/**
+ * Keep track of whether the scrolls of `scroller` (an element in `host`'s
+ * document, or the document itself) are a finger's, for isFingerScroll,
+ * until the returned function runs.
+ * Internal: not exported from the package.
+ */
+export function watchFingerScrolls(
+  host: GestureHost,
+  scroller: Node,
+): () => void {
+  let watch = watches.get(host);
+  if (watch == null) {
+    watch = {
+      scrollers: new Map(),
+      fingerScrollers: new Set(),
+      endedWhileDown: new Set(),
+      stop: null,
+    };
+    watches.set(host, watch);
+  }
+  const owned = watch;
+  owned.scrollers.set(scroller, (owned.scrollers.get(scroller) ?? 0) + 1);
+  owned.stop ??= start(host, owned);
+  let isWatching = true;
+  return () => {
+    if (!isWatching) {
+      return;
+    }
+    isWatching = false;
+    const count = (owned.scrollers.get(scroller) ?? 1) - 1;
+    if (count > 0) {
+      owned.scrollers.set(scroller, count);
+      return;
+    }
+    owned.scrollers.delete(scroller);
+    owned.fingerScrollers.delete(scroller);
+    owned.endedWhileDown.delete(scroller);
+    if (owned.scrollers.size === 0) {
+      owned.stop?.();
+      owned.stop = null;
+    }
+  };
+}
+
+/**
+ * Whether the scroll now moving a watched `scroller` is a finger's.
+ * Internal: not exported from the package.
+ */
+export function isFingerScroll(host: GestureHost, scroller: Node): boolean {
+  return watches.get(host)?.fingerScrollers.has(scroller) === true;
+}

package/src/gestures/gestureSync.ts

@@ -0,0 +1,60 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file gestureSync.ts
+ * @input Nothing: module state and a React ref
+ * @output Exports useIsUnmountedRef, and the gesture-sync depth
+ *   (syncingGestures, isSyncingGestures) the gesture hooks read
+ * @position Internal helpers shared by useGestureRecognizer and
+ *   usePressTracker, so each hook imports only what it uses
+ *
+ * SYNC: When modified, update __tests__/useGestureRecognizer.test.tsx.
+ */
+
+import {useRef} from 'react';
+import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
+
+/**
+ * How many hooks are driving a recognizer from an Effect right now: an
+ * `isEnabled` sync, or the detach of a replaced node that cancels a gesture
+ * in flight. While one runs no hook's listener calls its caller's callback
+ * (react-component-runtime INV2, INV3): the recognizer it stops is cancelled
+ * silently, and what that stop unblocks (a recognizer that required it to
+ * fail) resolves in the arena's next pass, a microtask later, where its
+ * listener reports as usual (`deferringResolution` in useGestureRecognizer).
+ * A press tracker's callbacks wait for a microtask after it (usePressTracker).
+ */
+let syncingDepth = 0;
+
+/** Runs `body` as a gesture sync (see `syncingDepth`). */
+export function syncingGestures<T>(body: () => T): T {
+  syncingDepth += 1;
+  try {
+    return body();
+  } finally {
+    syncingDepth -= 1;
+  }
+}
+
+/** True while any gesture hook's sync runs. */
+export function isSyncingGestures(): boolean {
+  return syncingDepth > 0;
+}
+
+/**
+ * A flag that turns true when the component unmounts, before the cleanups of
+ * the effects declared after it run, so nothing reports from those cleanups.
+ */
+export function useIsUnmountedRef(): {readonly current: boolean} {
+  const isUnmountedRef = useRef(false);
+  // Syncs the flag with the component's mount.
+  useIsomorphicLayoutEffect(() => {
+    isUnmountedRef.current = false;
+    return () => {
+      isUnmountedRef.current = true;
+    };
+  }, []);
+  return isUnmountedRef;
+}

package/src/gestures/haptics.ts

@@ -26,7 +26,12 @@
  *   light impact at the moment of the tap. The switch itself never takes the
  *   touch (`pointer-events: none`; WebKit marks a switch's `touchstart`
  *   handled, which would stop a pan starting on it from scrolling the page),
- *   and its own events never reach the page.
+ *   its own events never bubble to the page (capture-phase listeners still
+ *   see its click; the gesture host's click swallower skips it by
+ *   attribute), and focus the label's activation gives it goes straight
+ *   back, so a later Space never toggles it. A label tied to its control
+ *   by `for`, or whose control is itself a switch, gets no switch; a label
+ *   wrapping its own control gets one, which hands each tap on to it.
  * - `playHaptic(kind)` vibrates where `navigator.vibrate` exists (Android
  *   browsers) with the kind's pattern, and does nothing elsewhere.
  *
@@ -38,9 +43,8 @@ import {
   HAPTIC_VIBRATION_PATTERNS,
   type HapticFeedbackKind,
 } from '../motion/uikit/gestures';
-
-/** Marks the hidden switch, so click handlers can recognize and ignore it. */
-export const HAPTIC_SWITCH_ATTRIBUTE = 'data-astryx-haptic-switch';
+import {isDisabledControl} from '../utils/pressDisabled';
+import {markHapticSwitch} from '../privateAttributes/hapticSwitch.stylex';
 
 /** Whether this browser vibrates at all. */
 export function canVibrate(): boolean {
@@ -79,14 +83,6 @@ const VISUALLY_HIDDEN =
 
 let nextLabelId = 0;
 
-/** A native disabled control, or one marked `aria-disabled`. */
-function isDisabledControl(control: HTMLElement): boolean {
-  return (
-    control.matches(':disabled') ||
-    control.getAttribute('aria-disabled') === 'true'
-  );
-}
-
 /** Whether `input` is a switch checkbox, which plays the tap haptic itself. */
 function isSwitch(input: HTMLInputElement): boolean {
   return input.type === 'checkbox' && input.hasAttribute('switch');
@@ -125,7 +121,7 @@ export function attachTapHaptic(label: HTMLLabelElement): () => void {
   const input = doc.createElement('input');
   input.type = 'checkbox';
   input.setAttribute('switch', '');
-  input.setAttribute(HAPTIC_SWITCH_ATTRIBUTE, '');
+  markHapticSwitch(input);
   input.setAttribute('aria-hidden', 'true');
   input.tabIndex = -1;
   input.style.cssText = VISUALLY_HIDDEN;

package/src/gestures/hostRegistry.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file hostRegistry.ts
+ * @input Documents, and the gesture host created for each
+ * @output Exports gestureHosts: each document's gesture host, once something
+ *   has asked getGestureHost for it
+ * @position Shared by GestureHost.ts, which creates and records the hosts, and
+ *   code that only asks a host that already exists (pageHold.ts), which then
+ *   imports nothing of the host itself.
+ *
+ * SYNC: When modified, update GestureHost.ts (getGestureHost) and pageHold.ts.
+ */
+
+import type {GestureHost} from './GestureHost';
+
+/** Each document's gesture host, recorded when getGestureHost creates it. */
+export const gestureHosts = new WeakMap<Document, GestureHost>();

package/src/gestures/index.ts

@@ -15,6 +15,8 @@ export type {
   GestureClock,
 } from './GestureArena';
 export {GestureHost, getGestureHost} from './GestureHost';
+export {holdPageScroll} from './pageHold';
+export type {PageScrollDecision} from './pageHold';
 export type {AttachOptions, GestureHostOptions} from './GestureHost';
 export {
   GestureRecognizer,
@@ -70,10 +72,9 @@ export {deriveTouchAction, gestureHostStyle} from './touchAction';
 export type {GestureHostStyle} from './touchAction';
 export type * from './types';
 export {DEFAULT_ENVIRONMENT} from './types';
-export {useGestureRecognizer, usePressTracker} from './useGestureRecognizer';
-export type {
-  UseGestureRecognizerOptions,
-  UsePressTrackerOptions,
-} from './useGestureRecognizer';
+export {useGestureRecognizer} from './useGestureRecognizer';
+export type {UseGestureRecognizerOptions} from './useGestureRecognizer';
+export {usePressTracker} from './usePressTracker';
+export type {UsePressTrackerOptions} from './usePressTracker';
 export {VelocityTracker} from './VelocityTracker';
 export type {VelocityTrackerOptions} from './VelocityTracker';

package/src/gestures/nativeScroll.ts

@@ -27,7 +27,11 @@
  * read fresh on every question, since a native scroll moves them.
  */
 
+import {isRtlElement} from '../hooks/isRtlElement';
 import type {NativeScrollProbe} from './types';
+import {parentAcrossShadow} from '../utils/flatTree';
+
+export {parentAcrossShadow};
 
 export interface AllowedPans {
   readonly x: boolean;
@@ -72,25 +76,6 @@ interface ChainEntry {
 const SCROLLABLE = new Set(['auto', 'scroll', 'overlay']);
 const EDGE_TOLERANCE = 1;
 
-/**
- * The node's parent in the flat tree: a slotted node's slot, then out of
- * shadow roots to their hosts, so a scroller inside a shadow tree around the
- * slot is found.
- */
-export function parentAcrossShadow(node: Node): Node | null {
-  const slot =
-    node instanceof Element || node instanceof Text ? node.assignedSlot : null;
-  if (slot != null) {
-    return slot;
-  }
-  if (node.parentNode != null) {
-    return node.parentNode instanceof ShadowRoot
-      ? node.parentNode.host
-      : node.parentNode;
-  }
-  return null;
-}
-
 interface Chain {
   readonly entries: ChainEntry[];
   /** touch-action allows some pan all the way up. */
@@ -136,7 +121,8 @@ function buildChain(target: Element): Chain {
         element,
         x: scrollsX && allowX,
         y: scrollsY && allowY,
-        isRtl: style.direction === 'rtl',
+        // The writing direction through core's one helper.
+        isRtl: isRtlElement(element as HTMLElement),
         stopsX: behaviorX !== 'auto',
         stopsY: behaviorY !== 'auto',
         isBeyondFixed,

package/src/gestures/pageHold.ts

@@ -0,0 +1,265 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file pageHold.ts
+ * @input A document, its gesture host if it has one (which touches a
+ *   recognizer owns), and a scroll lock's decision
+ * @output Exports holdPageScroll and PageScrollDecision
+ * @position Scroll-lock support of packages/core/src/gestures, in its own
+ *   module so a page without a scroll lock never ships it. It imports nothing
+ *   of the gesture host: it asks the document's host only if one exists, so a
+ *   scroll lock does not bring the host, its arena and its recognizers into
+ *   every overlay.
+ *
+ * While a hold is held, a one-finger pan that `decide` says would scroll the
+ * page, and that no recognizer owns, is cancelled for the rest of its touch;
+ * a second finger (pinch-zoom) never is. A document with no gesture host has
+ * no recognizer, so no touch there is owned. Holds stack per document. Only
+ * while one is held is there a non-passive `touchmove` listener, so a scroll
+ * lock costs nothing once it is released, and a touch scrolls as without
+ * the system. The primary pointer is read as a hold starts: where it is
+ * coarse the hold listens then, since Safari honours a blocking listener only
+ * when it was registered before the touch; where it is fine it registers no
+ * touch listener until a touch or pen contact. Either way it follows the
+ * pointer from then on.
+ *
+ * SYNC: When modified, update the gestures README ("Holding the page still").
+ */
+
+import {subscribeInput} from '../utils/inputStream';
+import {isCoarsePointer, watchCoarsePointer} from '../utils/coarsePointer';
+import {gestureHosts} from './hostRegistry';
+
+/**
+ * Decides, once per one-finger touch, whether its pan would scroll the page:
+ * `origin` is the innermost node under the finger (the composed path's first
+ * node, so a scroller inside a shadow root is seen), `dx` and `dy` the touch's
+ * movement once it clears a small slop. True cancels the touch's moves for as
+ * long as it lasts.
+ */
+export type PageScrollDecision = (
+  origin: EventTarget | null,
+  dx: number,
+  dy: number,
+) => boolean;
+
+/**
+ * How far a finger travels before a page-scroll hold judges its pan, in CSS
+ * px: enough that a swipe's first sample (a 2 px by 2 px wobble) does not fix
+ * the wrong axis, and still under WebKit's 10–11 px scroll claim, so the
+ * verdict comes before the browser commits to a scroll.
+ */
+const PAGE_HOLD_SLOP = 5;
+
+interface PageHolds {
+  readonly decisions: Set<{readonly decide: PageScrollDecision}>;
+  /** The one finger of the gesture the holds are judging. */
+  touch: {
+    /** Null until the finger's first move names it (see onPointerDown). */
+    readonly id: number | null;
+    readonly x: number;
+    readonly y: number;
+    verdict: boolean | null;
+  } | null;
+  readonly onPointerDown: (event: PointerEvent) => void;
+  readonly onTouchStart: (event: TouchEvent) => void;
+  readonly onTouchMove: (event: TouchEvent) => void;
+  /** The input stream subscriptions while held and the pointer is coarse. */
+  unsubscribers: (() => void)[];
+  /** The pointerdown subscription until the hold's first touch or pen contact. */
+  stopPointerDown: (() => void) | null;
+  stopWatchingPointer: (() => void) | null;
+}
+
+const holdsByDocument = new WeakMap<Document, PageHolds>();
+
+function fingersOf(event: TouchEvent): Touch[] {
+  return event.touches == null ? [] : Array.from(event.touches);
+}
+
+function createHolds(doc: Document): PageHolds {
+  const holds: PageHolds = {
+    decisions: new Set(),
+    touch: null,
+    unsubscribers: [],
+    stopPointerDown: null,
+    stopWatchingPointer: null,
+    onPointerDown: event => {
+      if (event.pointerType !== 'touch' && event.pointerType !== 'pen') {
+        return;
+      }
+      // The hold's first touch or pen contact reads the primary pointer and
+      // follows it from then on.
+      holds.stopPointerDown?.();
+      holds.stopPointerDown = null;
+      const view = doc.defaultView;
+      followPointer(doc, holds);
+      if (!isCoarsePointer(view)) {
+        return;
+      }
+      listen(doc, holds, true);
+      // An engine that sends this contact's touchstart first has passed it:
+      // the contact starts here, and its first move names its finger.
+      holds.touch = {
+        id: null,
+        x: event.clientX,
+        y: event.clientY,
+        verdict: null,
+      };
+    },
+    onTouchStart: event => {
+      const fingers = fingersOf(event);
+      const current = holds.touch;
+      // Only a finger already down keeps its record: a new touch that reuses
+      // the identifier starts afresh.
+      if (
+        current?.id != null &&
+        fingers.some(finger => finger.identifier === current.id) &&
+        !Array.from(event.changedTouches).some(
+          finger => finger.identifier === current.id,
+        )
+      ) {
+        // A second finger joins the held one: nothing is cancelled while two
+        // are down (a pinch), and the first keeps its verdict for the rest
+        // of its touch once it is alone again.
+        return;
+      }
+      const finger = fingers[0];
+      holds.touch =
+        fingers.length === 1 && finger != null
+          ? {
+              id: finger.identifier,
+              x: finger.clientX,
+              y: finger.clientY,
+              verdict: null,
+            }
+          : null;
+    },
+    onTouchMove: event => {
+      const fingers = fingersOf(event);
+      const finger = fingers[0];
+      if (holds.touch?.id === null && fingers.length === 1 && finger != null) {
+        holds.touch = {...holds.touch, id: finger.identifier};
+      }
+      const current = holds.touch;
+      // A second finger is a pinch: zooming the page stays available.
+      if (
+        fingers.length !== 1 ||
+        finger == null ||
+        current == null ||
+        finger.identifier !== current.id
+      ) {
+        return;
+      }
+      // A recognizer that owns the touch decides about its moves itself. The
+      // host is read on every move: one may be created after the hold began.
+      if (gestureHosts.get(doc)?.isTouchClaimed(current.id) === true) {
+        return;
+      }
+      if (current.verdict == null) {
+        const dx = finger.clientX - current.x;
+        const dy = finger.clientY - current.y;
+        if (Math.max(Math.abs(dx), Math.abs(dy)) < PAGE_HOLD_SLOP) {
+          return;
+        }
+        // The browser picks the scroller once per gesture; so do the holds.
+        const origin = event.composedPath()[0] ?? event.target;
+        current.verdict = [...holds.decisions].some(hold =>
+          hold.decide(origin, dx, dy),
+        );
+      }
+      if (current.verdict && event.cancelable) {
+        event.preventDefault();
+      }
+    },
+  };
+  return holds;
+}
+
+/**
+ * Follow the primary pointer while held, once: the holds listen while it is
+ * coarse and not while it is fine (`spec:AST-094` FR24).
+ */
+function followPointer(doc: Document, holds: PageHolds): void {
+  if (holds.stopWatchingPointer == null) {
+    holds.stopWatchingPointer = watchCoarsePointer(doc.defaultView, isCoarse =>
+      listen(doc, holds, isCoarse),
+    );
+  }
+}
+
+/**
+ * Turn the holds' listeners on or off: on only while one is held and the
+ * primary pointer is coarse (`spec:AST-094` FR19, FR24).
+ */
+function listen(doc: Document, holds: PageHolds, on: boolean): void {
+  const view = doc.defaultView;
+  if (view == null || on === holds.unsubscribers.length > 0) {
+    return;
+  }
+  if (on) {
+    // The window's capture phase, through the shared input stream, as the
+    // host listens; only the touchmove that cancels is non-passive.
+    holds.unsubscribers = [
+      subscribeInput(view, 'touchstart', holds.onTouchStart),
+      subscribeInput(view, 'touchmove', holds.onTouchMove, {cancels: true}),
+    ];
+  } else {
+    for (const unsubscribe of holds.unsubscribers.splice(0)) {
+      unsubscribe();
+    }
+    holds.touch = null;
+  }
+}
+
+/**
+ * Hold the page of `doc` still under a finger until the returned release runs
+ * (a scroll lock under a modal presentation): `holdPageScroll(document,
+ * decide)`. Never creates a gesture host. Where the primary pointer is
+ * coarse it listens as it starts, since Safari honours a blocking listener
+ * only when it was registered before the touch, and the first drag after an
+ * overlay opens is the one a hold is for; where it is fine it subscribes
+ * only to `pointerdown` and registers no touch listener until a touch or pen
+ * contact. Either way it follows the pointer while held.
+ * Proposed; pending owner review.
+ */
+export function holdPageScroll(
+  doc: Document,
+  decide: PageScrollDecision,
+): () => void {
+  let holds = holdsByDocument.get(doc);
+  if (holds == null) {
+    holds = createHolds(doc);
+    holdsByDocument.set(doc, holds);
+  }
+  const owned = holds;
+  const hold = {decide};
+  owned.decisions.add(hold);
+  const view = doc.defaultView;
+  if (owned.decisions.size === 1 && view != null) {
+    owned.stopPointerDown = subscribeInput(
+      view,
+      'pointerdown',
+      owned.onPointerDown,
+    );
+    if (isCoarsePointer(view)) {
+      followPointer(doc, owned);
+      listen(doc, owned, true);
+    }
+  }
+  let isHeld = true;
+  return () => {
+    if (!isHeld) {
+      return;
+    }
+    isHeld = false;
+    owned.decisions.delete(hold);
+    if (owned.decisions.size === 0) {
+      owned.stopPointerDown?.();
+      owned.stopPointerDown = null;
+      owned.stopWatchingPointer?.();
+      owned.stopWatchingPointer = null;
+      listen(doc, owned, false);
+    }
+  };
+}