@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/gestures/recognizerInternals.ts

@@ -0,0 +1,77 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file recognizerInternals.ts
+ * @input GestureRecognizer
+ * @output internals(recognizer): the members the arena, the host and the
+ *   React hooks drive, and RecognizerFamily, the brand the host reads instead
+ *   of `instanceof`
+ * @position Internal to packages/core/src/gestures; never exported from the
+ *   package
+ *
+ * A recognizer's arena plumbing (its arena, a pending recognition, touch
+ * delivery, approved transitions) is `protected` on the class, so the
+ * published type offers it to subclasses only. The arena and the host reach
+ * it through this view, and so do the React hooks, for the arena an Effect's
+ * stop defers its resolution to.
+ *
+ * SYNC: When modified, update the `protected` members of GestureRecognizer.ts.
+ */
+
+import type {GestureArena} from './GestureArena';
+import type {GestureRecognizer} from './GestureRecognizer';
+import type {GestureEventContext, GestureState, GestureTouch} from './types';
+
+/**
+ * The kinds of recognizer the host and touch-action treat specially. Each of
+ * those classes brands itself (a subclass inherits the brand), so the host
+ * never imports a recognizer class: a page ships only the recognizers it
+ * constructs.
+ */
+export type RecognizerFamily = 'tap' | 'longPress' | 'pan';
+
+/** The members of a recognizer only the gesture system calls. */
+export interface RecognizerInternals {
+  /** The recognizer's family, when the host treats it specially. */
+  readonly family?: RecognizerFamily;
+  arena: GestureArena | null;
+  pending: 'began' | 'ended' | null;
+  readonly seenTouchIds: Set<number>;
+  readonly acceptsTouchInput: boolean;
+  requiresFailureOf(other: GestureRecognizer): boolean;
+  allowsSimultaneous(other: GestureRecognizer): boolean;
+  shouldBegin(): boolean;
+  keepsTouch(touchId: number): boolean;
+  wantsTouch(touch: GestureTouch): boolean;
+  deliverBegan(
+    touches: ReadonlyArray<GestureTouch>,
+    event: GestureEventContext,
+  ): void;
+  deliverBeganElsewhere(
+    touches: ReadonlyArray<GestureTouch>,
+    event: GestureEventContext,
+  ): void;
+  deliverMoved(
+    touches: ReadonlyArray<GestureTouch>,
+    event: GestureEventContext,
+  ): void;
+  deliverEnded(
+    touches: ReadonlyArray<GestureTouch>,
+    event: GestureEventContext,
+  ): void;
+  deliverCancelled(
+    touches: ReadonlyArray<GestureTouch>,
+    event: GestureEventContext,
+  ): void;
+  deliverTakenByBrowser(
+    touches: ReadonlyArray<GestureTouch>,
+    event: GestureEventContext,
+  ): void;
+  applyState(next: GestureState): void;
+  resetToPossible(): void;
+}
+
+/** The gesture system's view of `recognizer`. */
+export function internals(recognizer: GestureRecognizer): RecognizerInternals {
+  return recognizer as unknown as RecognizerInternals;
+}

package/src/gestures/selectionLock.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file selectionLock.ts
+ * @input The selection lock in utils/selectionLock.ts
+ * @output Re-exports lockSelection and locksSelectionFor
+ * @position A transition re-export: the selection lock moved to utils with
+ *   the shared input stream (utils/inputStream.ts), and stacks based below
+ *   that move still import it from here. Remove it once they have moved up.
+ */
+
+export {lockSelection, locksSelectionFor} from '../utils/selectionLock';

package/src/gestures/touchAction.ts

@@ -4,9 +4,10 @@
  * @file touchAction.ts
  * @input The recognizers attached to one element
  * @output Exports deriveTouchAction (the element's `touch-action`),
- *   gestureHostStyle (the inline style a host sets for its recognizers),
- *   intersectTouchAction (what both a derived and a caller's value allow) and
- *   holdSelectionStyle (the selection and callout lock for one held press)
+ *   gestureHostStyle (the inline style a host sets for its recognizers) and
+ *   intersectTouchAction (what both a derived and a caller's value allow).
+ *   The selection and callout lock for one held press is the recognizer's
+ *   own `selectionLock` (gestures/selectionLock.ts), which the host calls
  * @position Browser negotiation of packages/core/src/gestures, pure so a
  *   server render can emit the same style the client would set
  *
@@ -30,8 +31,14 @@
  */
 
 import type {GestureRecognizer, NativeTouchBehavior} from './GestureRecognizer';
+import {internals} from './recognizerInternals';
 
-/** The intersection of what each touch recognizer leaves the browser. */
+/**
+ * The intersection of what each touch recognizer leaves the browser. A
+ * watcher (`claimsTouches: false`) never takes a touch, so it leaves the
+ * browser everything: its direction restricts no scroll (`spec:AST-094`
+ * FR20, DEC-7).
+ */
 export function combinedNativeBehavior(
   recognizers: ReadonlyArray<GestureRecognizer>,
 ): NativeTouchBehavior {
@@ -40,7 +47,7 @@ export function combinedNativeBehavior(
   let pinchZoom = true;
   let doubleTapZoom = true;
   for (const recognizer of recognizers) {
-    if (!recognizer.acceptsTouchInput) {
+    if (!internals(recognizer).acceptsTouchInput || !recognizer.claimsTouches) {
       continue;
     }
     const behavior = recognizer.nativeTouchBehavior;
@@ -170,22 +177,3 @@ export function intersectTouchAction(derived: string, caller: string): string {
   }
   return parts.length === 0 ? 'none' : parts.join(' ');
 }
-
-/**
- * The lock a host applies for one press only, from touch-down to the lift or
- * a cancel, on an element whose hold does something (a long press): no iOS
- * callout and no text-selection start under the held finger, as a
- * long-pressed row in UIKit selects no text (spec:AST-094 FR41). Null where
- * the hold does nothing, so a long press there selects natively.
- */
-export function holdSelectionStyle(
-  recognizers: ReadonlyArray<GestureRecognizer>,
-): GestureHostStyle | null {
-  const holds = recognizers.some(
-    recognizer =>
-      recognizer.kind === 'longPress' && recognizer.acceptsTouchInput,
-  );
-  return holds
-    ? {WebkitTouchCallout: 'none', WebkitUserSelect: 'none', userSelect: 'none'}
-    : null;
-}

package/src/gestures/types.ts

@@ -9,6 +9,8 @@
  * @position Shared vocabulary of packages/core/src/gestures; no runtime code
  */
 
+import type {SelectionLock} from './GestureRecognizer';
+
 /**
  * UIGestureRecognizer.State. A discrete recognizer goes straight from
  * `possible` to `ended` (UIKit's `.recognized` is the same value).
@@ -172,6 +174,22 @@ export interface TouchConsumer {
    * (attached above this consumer) from beginning for a touch on it.
    */
   allowsAncestorRecognizer?(recognizer: unknown): boolean;
+  /**
+   * Whether the consumer holds this touch now (a control whose press was
+   * delivered for that touch): the host cancels the browser's pan for that
+   * finger only, as UIKit's `touchesShouldCancel(in:)` is false for a
+   * tracking control. A move before the press is delivered, and another
+   * finger the consumer is not tracking, still scroll.
+   */
+  keepsTouch?(touchId: number): boolean;
+  /**
+   * A control whose own record defines a hold action (a stepper's
+   * hold-repeat) brings the lock that turns text selection and the callout
+   * off for that press only, as a recognizer created with one does
+   * (`spec:AST-094` FR41). A control whose hold does nothing leaves it
+   * undefined and keeps the browser's long-press selection.
+   */
+  readonly selectionLock?: SelectionLock;
   /**
    * Whether the consumer takes touches now (a disabled control does not).
    * The host listens only while something enabled is attached

package/src/gestures/useFingerScroll.ts

@@ -0,0 +1,78 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useFingerScroll.ts
+ * @input A scroller (a ref to an element, or the document for the page) and
+ *   the document's gesture host
+ * @output useFingerScroll: whether the scroller's current scroll is a
+ *   finger's, read at any moment
+ * @position Gesture hook of packages/core/src/gestures, over the
+ *   finger-scroll watch (fingerScroll.ts), kept on the scroller's node by
+ *   the gesture hooks' shared attachment (hooks/useAttachment.ts). An internal
+ *   piece of the touch
+ *   module with no public API, not in the gestures barrel: a scroll-driven
+ *   component (a tab bar that minimizes, a header that collapses, a picker
+ *   that commits at rest) imports it from here, so it ships only where used
+ *
+ * A scroll is a finger's from a scroll event while a finger that landed
+ * inside the scroller is down, until the scroller's `scrollend` (the lift
+ * starts the momentum, which is still the finger's), or, where the browser
+ * sends no `scrollend`, until a 150 ms fallback after the last scroll event.
+ * A scroll with no finger down, or a recognizer's own scroll, is the
+ * program's, even right after a tap. A
+ * component that reacts to the person's scrolling only (a tab bar that
+ * minimizes as the page scrolls down) reads this instead of listening to
+ * touches itself.
+ *
+ * SYNC: When modified, update __tests__/useFingerScroll.test.tsx.
+ */
+
+import {useCallback, useRef, type RefObject} from 'react';
+import {isFingerScroll, watchFingerScrolls} from './fingerScroll';
+import {getGestureHost} from './GestureHost';
+import {useAttachment} from '../hooks/useAttachment';
+
+function isDocument(value: unknown): value is Document {
+  return typeof Document !== 'undefined' && value instanceof Document;
+}
+
+/** The document a scroller is in: itself, for the page's own scroll. */
+function documentOf(node: Element | Document): Document {
+  return isDocument(node) ? node : node.ownerDocument;
+}
+
+/**
+ * Watch a scroller's finger scrolls. Pass a ref to a scrolling element, or
+ * the document for the page's own scroll. Returns a reader, stable across
+ * renders: `true` while the scroller's scroll is a finger's.
+ * Internal: not exported from the package.
+ */
+export function useFingerScroll(
+  scroller: RefObject<Element | null> | Document,
+): () => boolean {
+  /** The node the watch is on now, for the reader. */
+  const watchedRef = useRef<Element | Document | null>(null);
+  // Keeps the finger-scroll watch on the node the scroller names after each
+  // commit (useAttachment): a ref that now points at another element moves
+  // the watch to it, and unmounting releases it.
+  useAttachment<Element | Document>(
+    isDocument(scroller) ? {current: scroller} : scroller,
+    node => {
+      watchedRef.current = node;
+      const stop = watchFingerScrolls(getGestureHost(documentOf(node)), node);
+      return () => {
+        stop();
+        watchedRef.current = null;
+      };
+    },
+    null,
+  );
+  return useCallback(() => {
+    const node = watchedRef.current;
+    return (
+      node != null && isFingerScroll(getGestureHost(documentOf(node)), node)
+    );
+  }, []);
+}

package/src/gestures/useGestureRecognizer.ts

@@ -4,9 +4,10 @@
 
 /**
  * @file useGestureRecognizer.ts
- * @input An element ref, a recognizer factory and a gesture listener; or an
- *   element ref and press tracker options
- * @output Exports useGestureRecognizer and usePressTracker
+ * @input An element ref, a recognizer factory and a gesture listener
+ * @output Exports useGestureRecognizer (usePressTracker lives in
+ *   usePressTracker.ts, so a gesture-only component never imports the press
+ *   tracker)
  * @position React face of packages/core/src/gestures
  *
  * The recognizer is created once and keeps its identity for the life of the
@@ -15,68 +16,62 @@
  * passing a new function each render re-attaches nothing, and a gesture
  * costs no React render at all — the listener runs inside the input event
  * and writes to the DOM itself. The recognizer attaches in a layout effect,
- * so its `touch-action` is in place before the browser can see a finger.
+ * so its `touch-action` is in place before the browser can see a finger, and
+ * re-attaches on any commit that finds another element behind the ref. After
+ * unmount neither hook calls the consumer back.
  *
  * SYNC: When modified, update useGestureRecognizer.test.tsx and README.md.
  */
 
-import {useEffect, useMemo, useRef, useState, type RefObject} from 'react';
+import {useEffect, useRef, useState, type RefObject} from 'react';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {getGestureHost} from './GestureHost';
 import type {GestureRecognizer} from './GestureRecognizer';
+import {useAttachment} from '../hooks/useAttachment';
 import {
-  createPressTracker,
-  vetoesSingleTap,
-  type PressTracker,
-  type PressTrackerOptions,
-} from './PressTracker';
+  isSyncingGestures,
+  syncingGestures,
+  useIsUnmountedRef,
+} from './gestureSync';
+import {internals} from './recognizerInternals';
 
 export interface UseGestureRecognizerOptions {
   /**
    * Live toggle; turning it off mid-gesture cancels the gesture. That cancel
    * does not call `onGesture`: it comes from the render that turned the
-   * recognizer off, and the code that turned it off already knows.
+   * recognizer off, and the code that turned it off already knows. A
+   * recognizer that required this one to fail resolves just after that
+   * render and reports as usual.
    * @default true
    */
   isEnabled?: boolean;
   /** Let the host set touch-action (and long-press callout) styles. @default true */
   manageStyle?: boolean;
+  /**
+   * Accepted and ignored: every attachment reads each event's pointer
+   * (`spec:AST-094` FR43). Kept so callers written before FR43 compile.
+   * @deprecated
+   */
+  perEventPointer?: boolean;
+  /**
+   * The element is an action group, sibling actions a held pointer slides
+   * across (`family:action-groups` FR5): the host serves it where the
+   * primary pointer is fine too (`AttachOptions.actionGroup`).
+   * @default false
+   */
+  actionGroup?: boolean;
 }
 
 /**
- * How many Effects are driving the gesture system right now (an `isEnabled`
- * sync, a detach, a press tracker's release or host update). While one runs
- * no hook calls its caller back (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`).
- */
-let effectDepth = 0;
-
-/** Runs `drive` as an Effect's work on the gesture system (see effectDepth). */
-function driveFromEffect(drive: () => void): void {
-  effectDepth += 1;
-  try {
-    drive();
-  } finally {
-    effectDepth -= 1;
-  }
-}
-
-/**
- * Runs `body`, which stops `recognizer` from an Effect, with its arena leaving
- * what the stop unblocks to a pass a microtask later
- * (GestureArena.deferResolution): a recognizer that required the stopped one
- * to fail recognizes there, outside the Effect, and its listener reports as
- * usual. A recognizer that has met no touch has no arena, and nothing waits on
- * it.
+ * Runs `body` with the recognizer's arena leaving what it unblocks to the
+ * next pass, outside the Effect (GestureArena.deferResolution). A recognizer
+ * that has met no touch has no arena, and nothing waits on it.
  */
 function deferringResolution(
   recognizer: GestureRecognizer,
   body: () => void,
 ): void {
-  const arena = recognizer.arena;
+  const {arena} = internals(recognizer);
   if (arena == null) {
     body();
     return;
@@ -98,6 +93,7 @@ function deferringResolution(
  * );
  * ```
  */
+
 export function useGestureRecognizer<R extends GestureRecognizer>(
   ref: RefObject<Element | null>,
   create: () => R,
@@ -106,200 +102,65 @@ export function useGestureRecognizer<R extends GestureRecognizer>(
 ): R {
   const [recognizer] = useState(create);
   const onGestureRef = useRef(onGesture);
+  // Syncs the listener's ref with the caller's newest callback.
   useIsomorphicLayoutEffect(() => {
     onGestureRef.current = onGesture;
   });
-  const {isEnabled = true, manageStyle = true} = options;
-
-  // Syncs the recognizer's target-action listeners with the caller's
-  // callback (read through a ref, so a new function re-subscribes nothing).
+  const {
+    isEnabled = true,
+    manageStyle = true,
+    perEventPointer = false,
+    actionGroup = false,
+  } = options;
+  const isUnmountedRef = useIsUnmountedRef();
+
+  // Syncs the recognizer's target-action listener with this component. The
+  // listener runs inside input events, never during a render or an Effect,
+  // and goes quiet once the component unmounts.
   useEffect(
     () =>
       recognizer.addListener(current => {
-        if (effectDepth === 0) {
+        if (!isUnmountedRef.current && !isSyncingGestures()) {
           onGestureRef.current?.(current);
         }
       }),
-    [recognizer],
+    [recognizer, isUnmountedRef],
   );
 
-  // Syncs the recognizer's `isEnabled` (UIKit's). It runs first, so disabling
-  // cancels a gesture in flight before its attachment goes, and that cancel,
-  // with whatever it settles in the arena, reaches no caller callback.
+  // Syncs the recognizer's `isEnabled` with the option. It runs first,
+  // under the guard, so disabling cancels a gesture in flight before its
+  // attachment goes.
   useIsomorphicLayoutEffect(() => {
-    driveFromEffect(() =>
-      deferringResolution(recognizer, () => recognizer.setEnabled(isEnabled)),
-    );
+    syncingGestures(() => {
+      deferringResolution(recognizer, () => {
+        recognizer.setEnabled(isEnabled);
+      });
+    });
   }, [recognizer, isEnabled]);
 
-  // Syncs the document's gesture host with the element behind `ref`: attached
-  // while enabled, re-attached when the node is replaced. A disabled gesture
-  // is not attached at all: no listener and no `touch-action` of its own on
-  // the element (spec:AST-094 FR24). Detaching (an unmount, a replaced node)
-  // cancels a gesture in flight, and that cancel, run in an Effect, reaches
-  // no caller callback (react-component-runtime INV2).
-  useNodeAttachment(
+  // Syncs the document's gesture host with the element behind `ref`. A
+  // disabled gesture is not attached at all: no listener and no
+  // `touch-action` of its own on the element (spec:AST-094 FR24). A replaced
+  // node is released and the new one attached; detaching cancels a gesture in
+  // progress from a layout effect, and that cancel reaches no caller callback
+  // (react-component-runtime INV2, INV3).
+  useAttachment(
     ref,
     element => {
       if (!isEnabled) {
-        return null;
+        return () => {};
       }
       const detach = getGestureHost(element.ownerDocument).attach(
         element,
         recognizer,
-        {manageStyle},
+        {manageStyle, perEventPointer, actionGroup},
       );
-      return () =>
-        driveFromEffect(() => deferringResolution(recognizer, detach));
+      return () => {
+        syncingGestures(() => deferringResolution(recognizer, detach));
+      };
     },
-    [recognizer, manageStyle, isEnabled],
+    `${manageStyle}:${perEventPointer}:${isEnabled}:${actionGroup}`,
   );
 
   return recognizer;
 }
-
-export type UsePressTrackerOptions = Omit<
-  PressTrackerOptions,
-  'getBounds' | 'view'
->;
-
-/**
- * Track presses on the element behind `ref` with UIControl semantics. The
- * callbacks are read through a ref, like a recognizer's listener. Releasing
- * the element (unmount, or a replaced node) ends any press without calling
- * them: that release runs in an Effect, which never calls a caller's
- * callback (react-component-runtime INV2, INV3).
- */
-export function usePressTracker(
-  ref: RefObject<Element | null>,
-  options: UsePressTrackerOptions = {},
-): PressTracker {
-  const optionsRef = useRef(options);
-  useIsomorphicLayoutEffect(() => {
-    optionsRef.current = options;
-  });
-  const {trackingExpansion, highlightDelay, cancelTravel, quickTapFlash} =
-    options;
-  // The tracker reads these four when it is built: a change rebuilds it (the
-  // attachment below moves to the new one and disposes the old), and the new
-  // values apply from the next touch. The callbacks, the brake included, are
-  // read through the ref on every touch.
-  const tracker = useMemo(
-    () =>
-      createPressTracker({
-        getBounds: () => ref.current?.getBoundingClientRect() ?? null,
-        get view() {
-          return ref.current;
-        },
-        onControlEvent: (event, touch) => {
-          if (effectDepth === 0) {
-            optionsRef.current.onControlEvent?.(event, touch);
-          }
-        },
-        onHighlightChange: isHighlighted => {
-          if (effectDepth === 0) {
-            optionsRef.current.onHighlightChange?.(isHighlighted);
-          }
-        },
-        trackingExpansion,
-        highlightDelay,
-        cancelTravel,
-        quickTapFlash,
-        // The caller's veto, read on every touch, else the tracker's own.
-        vetoesAncestorRecognizer: recognizer =>
-          (optionsRef.current.vetoesAncestorRecognizer ?? vetoesSingleTap)(
-            recognizer,
-          ),
-        isEnabled: () => optionsRef.current.isEnabled?.() ?? true,
-        // A finger that brakes a scroll it set moving presses nothing
-        // (GestureHost.isScrollBraking), unless the caller decides; the tracker
-        // asks only for a finger (spec:AST-094 FR11).
-        isBraking: touch => {
-          const element = ref.current;
-          return (
-            optionsRef.current.isBraking?.(touch) ??
-            (element != null &&
-              getGestureHost(element.ownerDocument).isScrollBraking(element))
-          );
-        },
-      }),
-    [ref, trackingExpansion, highlightDelay, cancelTravel, quickTapFlash],
-  );
-
-  // Syncs the document's gesture host with the element behind `ref`: the
-  // tracker is its press consumer, moved when the node is replaced, and a
-  // press in progress ends with it.
-  useNodeAttachment(
-    ref,
-    element => {
-      const detach = getGestureHost(element.ownerDocument).attachConsumer(
-        element,
-        tracker,
-      );
-      return () =>
-        driveFromEffect(() => {
-          detach();
-          tracker.dispose();
-        });
-    },
-    [tracker],
-  );
-
-  // Syncs the host's listeners with the tracker's enabled state, which can
-  // change with any render: the host listens only while an enabled control
-  // is attached (spec:AST-094 FR24).
-  useIsomorphicLayoutEffect(() => {
-    const element = ref.current;
-    if (element != null) {
-      driveFromEffect(() =>
-        getGestureHost(element.ownerDocument).update(element),
-      );
-    }
-  });
-
-  return tracker;
-}
-
-/**
- * Keeps `attach` applied to the element behind `ref`: checked after every
- * render, so a replaced node (a re-keyed or swapped element) is detached and
- * the new one attached, a removed one detached, and a change in `deps`
- * re-attaches (`architecture:react-component-runtime` INV6). Costs no render.
- * `attach` returns its detach, or null for nothing attached.
- */
-function useNodeAttachment<T extends Element>(
-  ref: RefObject<T | null>,
-  attach: (element: T) => (() => void) | null,
-  deps: ReadonlyArray<unknown>,
-): void {
-  const attachedRef = useRef<{
-    element: T;
-    deps: ReadonlyArray<unknown>;
-    detach: (() => void) | null;
-  } | null>(null);
-  // Syncs the attachment with the DOM node the caller's ref holds after
-  // this commit.
-  useIsomorphicLayoutEffect(() => {
-    const element = ref.current;
-    const current = attachedRef.current;
-    if (
-      current != null &&
-      current.element === element &&
-      current.deps.length === deps.length &&
-      current.deps.every((dep, index) => Object.is(dep, deps[index]))
-    ) {
-      return;
-    }
-    current?.detach?.();
-    attachedRef.current =
-      element == null ? null : {element, deps, detach: attach(element)};
-  });
-  // Detaches at unmount.
-  useIsomorphicLayoutEffect(
-    () => () => {
-      attachedRef.current?.detach?.();
-      attachedRef.current = null;
-    },
-    [],
-  );
-}