@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/dist/gestures/useFingerScroll.js

@@ -0,0 +1,70 @@
+// 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 } from 'react';
+import { isFingerScroll, watchFingerScrolls } from "./fingerScroll.js";
+import { getGestureHost } from "./GestureHost.js";
+import { useAttachment } from "../hooks/useAttachment.js";
+function isDocument(value) {
+  return typeof Document !== 'undefined' && value instanceof Document;
+}
+
+/** The document a scroller is in: itself, for the page's own scroll. */
+function documentOf(node) {
+  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) {
+  /** The node the watch is on now, for the reader. */
+  const watchedRef = useRef(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(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/dist/gestures/useGestureRecognizer.d.ts

@@ -1,8 +1,9 @@
 /**
  * @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
@@ -11,23 +12,39 @@
  * 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 { type RefObject } from 'react';
 import type { GestureRecognizer } from './GestureRecognizer.js';
-import { type PressTracker, type PressTrackerOptions } from './PressTracker.js';
 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;
 }
 /**
  * Attach a recognizer to the element behind `ref`.
@@ -44,13 +61,4 @@ export interface UseGestureRecognizerOptions {
  * ```
  */
 export declare function useGestureRecognizer<R extends GestureRecognizer>(ref: RefObject<Element | null>, create: () => R, onGesture?: (recognizer: R) => void, options?: UseGestureRecognizerOptions): R;
-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 declare function usePressTracker(ref: RefObject<Element | null>, options?: UsePressTrackerOptions): PressTracker;
 //# sourceMappingURL=useGestureRecognizer.d.ts.map

package/dist/gestures/useGestureRecognizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useGestureRecognizer.d.ts","sourceRoot":"","sources":["../../src/gestures/useGestureRecognizer.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAuC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAG3E,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACzB,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,2BAA2B;IAC1C;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,mFAAmF;IACnF,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AA2CD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,iBAAiB,EAC9D,GAAG,EAAE,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC,EAC9B,MAAM,EAAE,MAAM,CAAC,EACf,SAAS,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC,KAAK,IAAI,EACnC,OAAO,GAAE,2BAAgC,GACxC,CAAC,CAqDH;AAED,MAAM,MAAM,sBAAsB,GAAG,IAAI,CACvC,mBAAmB,EACnB,WAAW,GAAG,MAAM,CACrB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC,EAC9B,OAAO,GAAE,sBAA2B,GACnC,YAAY,CAqFd"}
+{"version":3,"file":"useGestureRecognizer.d.ts","sourceRoot":"","sources":["../../src/gestures/useGestureRecognizer.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAA8B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAGlE,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AAS3D,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,mFAAmF;IACnF,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAmBD;;;;;;;;;;;;;GAaG;AAEH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,iBAAiB,EAC9D,GAAG,EAAE,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC,EAC9B,MAAM,EAAE,MAAM,CAAC,EACf,SAAS,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC,KAAK,IAAI,EACnC,OAAO,GAAE,2BAAgC,GACxC,CAAC,CAgEH"}

package/dist/gestures/useGestureRecognizer.js

@@ -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,45 +16,27 @@
  * 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 } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { useIsomorphicLayoutEffect } from "../hooks/useIsomorphicLayoutEffect.js";
 import { getGestureHost } from "./GestureHost.js";
-import { createPressTracker, vetoesSingleTap } from "./PressTracker.js";
+import { useAttachment } from "../hooks/useAttachment.js";
+import { isSyncingGestures, syncingGestures, useIsUnmountedRef } from "./gestureSync.js";
+import { internals } from "./recognizerInternals.js";
 /**
- * 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) {
-  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, body) {
-  const arena = recognizer.arena;
+  const {
+    arena
+  } = internals(recognizer);
   if (arena == null) {
     body();
     return;
@@ -75,152 +58,60 @@ function deferringResolution(recognizer, body) {
  * );
  * ```
  */
+
 export function useGestureRecognizer(ref, create, onGesture, options = {}) {
   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
+    manageStyle = true,
+    perEventPointer = false,
+    actionGroup = false
   } = options;
+  const isUnmountedRef = useIsUnmountedRef();
 
-  // Syncs the recognizer's target-action listeners with the caller's
-  // callback (read through a ref, so a new function re-subscribes nothing).
+  // 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(ref, element => {
+  // 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
-    });
-    return () => driveFromEffect(() => deferringResolution(recognizer, detach));
-  }, [recognizer, manageStyle, isEnabled]);
-  return recognizer;
-}
-/**
- * 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, options = {}) {
-  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();
+      manageStyle,
+      perEventPointer,
+      actionGroup
     });
-  }, [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(ref, attach, deps) {
-  const attachedRef = useRef(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)
+    return () => {
+      syncingGestures(() => deferringResolution(recognizer, detach));
     };
-  });
-  // Detaches at unmount.
-  useIsomorphicLayoutEffect(() => () => {
-    attachedRef.current?.detach?.();
-    attachedRef.current = null;
-  }, []);
+  }, `${manageStyle}:${perEventPointer}:${isEnabled}:${actionGroup}`);
+  return recognizer;
 }

package/dist/gestures/usePressTracker.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @file usePressTracker.ts
+ * @input An element ref and press tracker options
+ * @output Exports usePressTracker
+ * @position React face of packages/core/src/gestures' PressTracker, in its
+ *   own module so a component that only recognizes gestures never imports
+ *   the press tracker
+ *
+ * The callbacks and the profile are read through refs: one tracker serves
+ * the component's life, so a profile change applies from the tracker's next
+ * read and never ends a press in progress. After unmount the tracker calls
+ * nothing back.
+ *
+ * SYNC: When modified, update useGestureRecognizer.test.tsx and README.md.
+ */
+import { type RefObject } from 'react';
+import { type PressTracker, type PressTrackerOptions } from './PressTracker.js';
+export type UsePressTrackerOptions = Omit<PressTrackerOptions, 'getBounds' | 'view'> & {
+    /**
+     * Accepted and ignored: every attachment reads each event's pointer
+     * (`spec:AST-094` FR43). Kept so callers written before FR43 compile.
+     * @deprecated
+     */
+    perEventPointer?: boolean;
+};
+/**
+ * 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 declare function usePressTracker(ref: RefObject<Element | null>, options?: UsePressTrackerOptions): PressTracker;
+//# sourceMappingURL=usePressTracker.d.ts.map

package/dist/gestures/usePressTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePressTracker.d.ts","sourceRoot":"","sources":["../../src/gestures/usePressTracker.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAA4B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAIhE,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACzB,MAAM,gBAAgB,CAAC;AAQxB,MAAM,MAAM,sBAAsB,GAAG,IAAI,CACvC,mBAAmB,EACnB,WAAW,GAAG,MAAM,CACrB,GAAG;IACF;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC,EAC9B,OAAO,GAAE,sBAA2B,GACnC,YAAY,CAwJd"}

package/dist/gestures/usePressTracker.js

@@ -0,0 +1,168 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file usePressTracker.ts
+ * @input An element ref and press tracker options
+ * @output Exports usePressTracker
+ * @position React face of packages/core/src/gestures' PressTracker, in its
+ *   own module so a component that only recognizes gestures never imports
+ *   the press tracker
+ *
+ * The callbacks and the profile are read through refs: one tracker serves
+ * the component's life, so a profile change applies from the tracker's next
+ * read and never ends a press in progress. After unmount the tracker calls
+ * nothing back.
+ *
+ * SYNC: When modified, update useGestureRecognizer.test.tsx and README.md.
+ */
+import { useMemo, useRef, useState } from 'react';
+import { useIsomorphicLayoutEffect } from "../hooks/useIsomorphicLayoutEffect.js";
+import { UIKIT_CONTROL } from "../motion/uikit/gestures.js";
+import { getGestureHost } from "./GestureHost.js";
+import { createPressTracker, vetoesSingleTap } from "./PressTracker.js";
+import { useAttachment } from "../hooks/useAttachment.js";
+import { isSyncingGestures, syncingGestures, useIsUnmountedRef } from "./gestureSync.js";
+/**
+ * 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, options = {}) {
+  const optionsRef = useRef(options);
+  // True while an Effect releases the tracker, so the press it ends reaches
+  // no caller callback.
+  const isReleasingRef = useRef(false);
+  // The ref is read through a ref too: a caller may pass a new ref object
+  // on a render, and the one tracker must follow it.
+  const refRef = useRef(ref);
+  // Syncs the options and ref refs with the newest render.
+  useIsomorphicLayoutEffect(() => {
+    optionsRef.current = options;
+    refRef.current = ref;
+  });
+  const isUnmountedRef = useIsUnmountedRef();
+  const {
+    perEventPointer = false
+  } = options;
+  // Calls a caller callback: never while an Effect releases the tracker or
+  // after unmount. While any gesture hook's isEnabled sync runs (turning off
+  // a recognizer the press waits on resolves the press in that arena pass,
+  // inside the Effect), the call waits for a microtask after it, in order,
+  // so the press still ends, un-highlighted, outside the Effect
+  // (react-component-runtime INV2).
+  const [deliver] = useState(() => call => {
+    if (isReleasingRef.current || isUnmountedRef.current) {
+      return;
+    }
+    if (!isSyncingGestures()) {
+      call();
+      return;
+    }
+    queueMicrotask(() => {
+      if (!isUnmountedRef.current) {
+        call();
+      }
+    });
+  });
+  // One tracker for the component's life, reading its profile through the
+  // options ref: a profile change never rebuilds it, so a press in progress
+  // survives it (the change applies from the tracker's next read).
+  // `keepsTouch` is the exception, fixed when the tracker is created: it
+  // decides whether the host gives the element a blocking touchmove.
+  const [tracker] = useState(() => createPressTracker({
+    getBounds: () => {
+      const element = refRef.current.current;
+      return element == null ? null : getGestureHost(element.ownerDocument).presentedRect(element);
+    },
+    get view() {
+      return refRef.current.current;
+    },
+    onControlEvent: (event, touch) => deliver(() => optionsRef.current.onControlEvent?.(event, touch)),
+    onHighlightChange: isHighlighted => deliver(() => optionsRef.current.onHighlightChange?.(isHighlighted)),
+    trackingExpansion: options.trackingExpansion,
+    get highlightDelay() {
+      return optionsRef.current.highlightDelay;
+    },
+    get cancelTravel() {
+      return optionsRef.current.cancelTravel;
+    },
+    get quickTapFlash() {
+      return optionsRef.current.quickTapFlash;
+    },
+    keepsTouch: options.keepsTouch,
+    get selectionLock() {
+      return optionsRef.current.selectionLock;
+    },
+    // 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,
+    // The caller's brake, or the host's: a touch that stops a flick
+    // presses nothing, as a UIKit control in a decelerating scroll view.
+    isBraking: touch => {
+      const own = optionsRef.current.isBraking;
+      if (own != null) {
+        return own(touch);
+      }
+      const element = refRef.current.current;
+      return element != null && getGestureHost(element.ownerDocument).isScrollBraking(element);
+    }
+  }));
+  const {
+    trackingExpansion
+  } = options;
+  // Syncs the tracker's tracking expansion with the option.
+  useIsomorphicLayoutEffect(() => {
+    tracker.trackingExpansion = trackingExpansion ?? UIKIT_CONTROL.trackingExpansion.value;
+  }, [tracker, trackingExpansion]);
+
+  // Syncs the host's press consumer with the element behind `ref`.
+  // Releasing the element (a replaced node, unmount) disposes the press,
+  // which un-highlights a control it was holding.
+  const attachment = useMemo(() => ({
+    tracker,
+    perEventPointer
+  }), [tracker, perEventPointer]);
+  useAttachment(ref, element => {
+    const detach = getGestureHost(element.ownerDocument).attachConsumer(element, attachment.tracker, {
+      perEventPointer: attachment.perEventPointer
+    });
+    return () => {
+      isReleasingRef.current = true;
+      try {
+        detach();
+        tracker.dispose();
+      } finally {
+        isReleasingRef.current = false;
+      }
+    };
+  }, attachment);
+
+  // 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). A control disabled under a finger ends
+  // that press here, inside the release guard: a disabled control tracks no
+  // touch, and this Effect calls back no caller, whether the host stops
+  // listening or another control keeps it listening.
+  useIsomorphicLayoutEffect(() => {
+    const element = refRef.current.current;
+    isReleasingRef.current = true;
+    try {
+      if (tracker.isTracking && !(optionsRef.current.isEnabled?.() ?? true)) {
+        tracker.dispose();
+      }
+      if (element != null) {
+        // The update's arena pass can settle other recognizers and trackers
+        // too: it runs as a gesture sync, so none calls its caller back from
+        // this Effect.
+        syncingGestures(() => getGestureHost(element.ownerDocument).update(element));
+      }
+    } finally {
+      isReleasingRef.current = false;
+    }
+  });
+  return tracker;
+}

package/dist/hooks/ModalAnnounceProvider.d.ts

@@ -1,7 +1,7 @@
 /**
  * @file ModalAnnounceProvider.tsx
- * @input Uses React context, effects and the exposure and delivery
- *   internals of useAnnounce
+ * @input Uses React context, effects, the exposure and delivery internals of
+ *   useAnnounce, and the shared MutationObserver
  * @output Exports ModalAnnounceProvider, the element every Astryx component
  *   that owns a native <dialog> renders around its content
  * @position Core a11y internal (spec:AST-086 FR14). Its own module so only
@@ -30,10 +30,9 @@ import { type ReactNode, type RefObject } from 'react';
 export declare function ModalAnnounceProvider({ dialogRef, isOpen, children, }: {
     dialogRef: RefObject<HTMLDialogElement | null>;
     /**
-     * The owner's intent for this render: open as a modal (or presented as a
-     * modal step). A non-modal surface — a scrimless Drawer shown with
-     * `showPopover()`, a scrimless sheet — passes `false`: it is not an FR14
-     * modal, and callers inside it route as the page does.
+     * The owner's intent for this render: open as a modal, or presented as a
+     * modal step. A non-modal surface, such as a scrimless Drawer or sheet,
+     * passes `false`. Callers inside it route as the page does.
      */
     isOpen: boolean;
     children: ReactNode;

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

@@ -1 +1 @@
-{"version":3,"file":"ModalAnnounceProvider.d.ts","sourceRoot":"","sources":["../../src/hooks/ModalAnnounceProvider.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAKL,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAWf;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,SAAS,EACT,MAAM,EACN,QAAQ,GACT,EAAE;IACD,SAAS,EAAE,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAC/C;;;;;OAKG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,SAAS,CAyFZ"}
+{"version":3,"file":"ModalAnnounceProvider.d.ts","sourceRoot":"","sources":["../../src/hooks/ModalAnnounceProvider.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAKL,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAYf;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,SAAS,EACT,MAAM,EACN,QAAQ,GACT,EAAE;IACD,SAAS,EAAE,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAC/C;;;;OAIG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,SAAS,CAyFZ"}