@astryxdesign/core 0.7.5 → 0.7.6-canary.00146a7

package/src/gestures/useGestureRecognizer.ts

@@ -0,0 +1,305 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @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
+ * @position React face of packages/core/src/gestures
+ *
+ * The recognizer is created once and keeps its identity for the life of the
+ * component, so relationships set up at creation (`requireToFail`,
+ * `recognizeSimultaneouslyWith`) hold. The listener is read through a ref:
+ * 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.
+ *
+ * SYNC: When modified, update useGestureRecognizer.test.tsx and README.md.
+ */
+
+import {useEffect, useMemo, useRef, useState, type RefObject} from 'react';
+import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
+import {getGestureHost} from './GestureHost';
+import type {GestureRecognizer} from './GestureRecognizer';
+import {
+  createPressTracker,
+  vetoesSingleTap,
+  type PressTracker,
+  type PressTrackerOptions,
+} from './PressTracker';
+
+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.
+   * @default true
+   */
+  isEnabled?: boolean;
+  /** Let the host set touch-action (and long-press callout) styles. @default true */
+  manageStyle?: 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.
+ */
+function deferringResolution(
+  recognizer: GestureRecognizer,
+  body: () => void,
+): void {
+  const arena = recognizer.arena;
+  if (arena == null) {
+    body();
+    return;
+  }
+  arena.deferResolution(body);
+}
+
+/**
+ * Attach a recognizer to the element behind `ref`.
+ *
+ * @example
+ * ```
+ * const pan = useGestureRecognizer(
+ *   ref,
+ *   () => new PanGestureRecognizer({direction: 'vertical'}),
+ *   recognizer => {
+ *     ref.current.style.transform = `translateY(${recognizer.translation().y}px)`;
+ *   },
+ * );
+ * ```
+ */
+export function useGestureRecognizer<R extends GestureRecognizer>(
+  ref: RefObject<Element | null>,
+  create: () => R,
+  onGesture?: (recognizer: R) => void,
+  options: UseGestureRecognizerOptions = {},
+): R {
+  const [recognizer] = useState(create);
+  const onGestureRef = useRef(onGesture);
+  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).
+  useEffect(
+    () =>
+      recognizer.addListener(current => {
+        if (effectDepth === 0) {
+          onGestureRef.current?.(current);
+        }
+      }),
+    [recognizer],
+  );
+
+  // 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.
+  useIsomorphicLayoutEffect(() => {
+    driveFromEffect(() =>
+      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 => {
+      if (!isEnabled) {
+        return null;
+      }
+      const detach = getGestureHost(element.ownerDocument).attach(
+        element,
+        recognizer,
+        {manageStyle},
+      );
+      return () =>
+        driveFromEffect(() => deferringResolution(recognizer, detach));
+    },
+    [recognizer, manageStyle, isEnabled],
+  );
+
+  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;
+    },
+    [],
+  );
+}

package/src/hooks/index.ts

@@ -15,7 +15,11 @@ export {hasActiveFocusTrapEscape, useFocusTrap} from './useFocusTrap';
 export type {UseFocusTrapOptions, UseFocusTrapReturn} from './useFocusTrap';
 
 export {useAnnounce} from './useAnnounce';
-export type {AnnounceFn, AnnouncePoliteness} from './useAnnounce';
+export type {
+  AnnounceFn,
+  AnnouncePoliteness,
+  UseAnnounceOptions,
+} from './useAnnounce';
 
 export {useClipboard} from './useClipboard';
 export type {UseClipboardOptions, UseClipboardReturn} from './useClipboard';

package/src/hooks/menuPressMarker.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file menuPressMarker.ts
+ * @input None (a plain attribute-name constant)
+ * @output Exports MENU_PRESS_MARKER
+ * @position Dependency-free home of the public menu-press marker, so the press
+ *   feedback controller (utils/pressFeedback.ts) can read it without loading
+ *   the menu-press hook into every pressable component's bundle.
+ *   useMenuPress.ts re-exports it; the public path stays
+ *   `@astryxdesign/core/hooks`.
+ */
+
+/** Marks a menu root that carries the menu press model (useMenuPress). */
+export const MENU_PRESS_MARKER = 'data-astryx-menu-press';

package/src/hooks/modalAnnounce.ts

@@ -14,7 +14,11 @@
  *   handed to the channel exposed then, or held while an exiting modal still
  *   covers everything, and released at its real close; a covered modal is
  *   not written to; a caller inside a modal being presented in this commit
- *   waits one frame for the route. Loaded only by ModalAnnounceProvider, so
+ *   waits one frame for the route. Words move with their announcers'
+ *   receipts, one delivery per announcer, so an announcer can take back its
+ *   own share while it waits wherever it went: a `hasReplace` instance's
+ *   next message (FR9), a busy start overtaken by its outcome (FR8). Loaded
+ *   only by ModalAnnounceProvider, so
  *   a component that calls useAnnounce and renders no modal does not carry
  *   it.
  *
@@ -25,14 +29,18 @@ import {
   announceMessage,
   clearModalRegion,
   clearRegion,
+  forwardWaiting,
+  handleOf,
   installModalRoute,
   isOpenModal,
   modalRegion,
-  unexposedMessages,
-  withdrawFromModalRegion,
+  unexposedWords,
   writeModalRegion,
   type AnnouncePoliteness,
+  type AnnounceReceipt,
   type ModalAnnounceScope,
+  type WaitingWords,
+  type WithdrawAnnouncement,
 } from './useAnnounce';
 
 /**
@@ -153,20 +161,58 @@ function isAnyModalOpen(): boolean {
 // the accessibility tree for its exit but is still an open native modal, or
 // such a dialog covers the channel they would go to, so nothing is exposed
 // yet. They are delivered when a dialog closes (or theirs is exposed again).
-const held = new Map<HTMLDialogElement, Record<AnnouncePoliteness, string[]>>();
+// Each text keeps its announcers' receipts, so one taking its share back
+// leaves it for the others, and a receipt follows the words when they are
+// released; an entry is gone once delivered, so a receipt never reaches
+// equal words held later.
+interface HeldWords extends WaitingWords {
+  readonly receipts: AnnounceReceipt[];
+}
+const held = new Map<
+  HTMLDialogElement,
+  Record<AnnouncePoliteness, HeldWords[]>
+>();
 
+/** Hold `message` for `dialog`, for the announcer `receipt` stands for. */
 function hold(
   dialog: HTMLDialogElement,
   message: string,
   politeness: AnnouncePoliteness,
+  receipt: AnnounceReceipt,
 ): void {
   let slot = held.get(dialog);
   if (slot == null) {
     slot = {polite: [], assertive: []};
     held.set(dialog, slot);
   }
-  if (!slot[politeness].includes(message)) {
-    slot[politeness].push(message);
+  let words = slot[politeness].find(entry => entry.text === message);
+  if (words == null) {
+    words = {text: message, receipts: []};
+    slot[politeness].push(words);
+  }
+  words.receipts.push(receipt);
+  const entry = words;
+  receipt.withdraw = () => dropHeldShare(dialog, politeness, entry, receipt);
+}
+
+/** One announcer takes back its share of `words`, while they are held. */
+function dropHeldShare(
+  dialog: HTMLDialogElement,
+  politeness: AnnouncePoliteness,
+  words: HeldWords,
+  receipt: AnnounceReceipt,
+): void {
+  const slot = held.get(dialog);
+  const at = words.receipts.indexOf(receipt);
+  if (slot == null || !slot[politeness].includes(words) || at < 0) {
+    return;
+  }
+  words.receipts.splice(at, 1);
+  if (words.receipts.length === 0) {
+    slot[politeness] = slot[politeness].filter(entry => entry !== words);
+    if (slot.polite.length === 0 && slot.assertive.length === 0) {
+      held.delete(dialog);
+    }
   }
 }
 
@@ -193,15 +239,13 @@ function releaseHeld(dialog: HTMLDialogElement): void {
   }
   held.delete(dialog);
   for (const politeness of ['polite', 'assertive'] as const) {
-    if (slot[politeness].length > 0) {
-      const message = slot[politeness].join(' ');
-      if (isExposed(dialog)) {
-        announceInModalRouted(dialog, message, politeness);
-      } else {
-        // Holds again if still nothing is exposed.
-        deliverBeyond(dialog, message, politeness);
-      }
-    }
+    // One delivery per announcer, so each receipt follows its words.
+    forwardWaiting(slot[politeness], text =>
+      isExposed(dialog)
+        ? announceInModalRouted(dialog, text, politeness)
+        : // Holds again if still nothing is exposed.
+          deliverBeyond(dialog, text, politeness),
+    );
   }
 }
 
@@ -221,20 +265,20 @@ function deliverBeyond(
   dialog: HTMLDialogElement,
   message: string,
   politeness: AnnouncePoliteness,
-): void {
+): WithdrawAnnouncement | null {
   const next = nextExposedChannel(dialog);
   if (next === 'covered' || (next == null && isAnyModalOpen())) {
     // An exiting modal — this one, or one above the next candidate — is
     // still open and covers what is beneath it: nothing is exposed until
     // it closes.
-    hold(dialog, message, politeness);
-    return;
+    const receipt: AnnounceReceipt = {withdraw: null};
+    hold(dialog, message, politeness, receipt);
+    return handleOf(receipt);
   }
   if (next != null) {
-    announceInModalRouted(next, message, politeness);
-    return;
+    return announceInModalRouted(next, message, politeness);
   }
-  announceMessage(message, politeness);
+  return announceMessage(message, politeness);
 }
 
 /**
@@ -245,10 +289,11 @@ function deliverBeyond(
  */
 export function handOffUnexposed(dialog: HTMLDialogElement): void {
   for (const politeness of ['polite', 'assertive'] as const) {
-    const waiting = takeUnexposed(dialog, politeness);
-    if (waiting.length > 0) {
-      deliverBeyond(dialog, waiting.join(' '), politeness);
-    }
+    // One delivery per announcer, so each receipt follows its words and a
+    // `hasReplace` instance's next message can still take its own back.
+    forwardWaiting(takeUnexposed(dialog, politeness), text =>
+      deliverBeyond(dialog, text, politeness),
+    );
   }
 }
 
@@ -267,16 +312,19 @@ function withdrawFromModal(
   dropHeld(dialog, politeness);
 }
 
-/** Take the unexposed messages out of a dialog's region, clearing it. */
+/**
+ * Take the unexposed words out of a dialog's region, with their receipts,
+ * clearing it.
+ */
 function takeUnexposed(
   dialog: HTMLDialogElement,
   politeness: AnnouncePoliteness,
-): string[] {
+): WaitingWords[] {
   const region = modalRegion(dialog, politeness);
   if (region == null) {
     return [];
   }
-  const waiting = unexposedMessages(region);
+  const waiting = unexposedWords(region);
   clearModalRegion(dialog, politeness);
   return waiting;
 }
@@ -285,10 +333,9 @@ function announceInModalRouted(
   dialog: HTMLDialogElement,
   message: string,
   politeness: AnnouncePoliteness = 'polite',
-): void {
+): WithdrawAnnouncement | null {
   if (!isExposed(dialog)) {
-    deliverBeyond(dialog, message, politeness);
-    return;
+    return deliverBeyond(dialog, message, politeness);
   }
   const top = topExposedModal();
   if (top != null && top !== dialog && presented.includes(dialog)) {
@@ -296,35 +343,23 @@ function announceInModalRouted(
     // one closes, and a message announced meanwhile is not heard — the
     // container is clear before this modal is on top again.
     clearModalRegion(dialog, politeness);
-    return;
+    return null;
   }
-  writeModalRegion(dialog, message, politeness, {
+  return writeModalRegion(dialog, message, politeness, {
     isExposed: () => isExposed(dialog),
-    redirect: joined => deliverBeyond(dialog, joined, politeness),
+    redirect: waiting =>
+      forwardWaiting(waiting, text => deliverBeyond(dialog, text, politeness)),
   });
 }
 
-function withdrawFromModalPendingRouted(
-  dialog: HTMLDialogElement,
-  message: string,
-  politeness: AnnouncePoliteness,
-): void {
-  withdrawFromModalRegion(dialog, message, politeness);
-  const slot = held.get(dialog);
-  if (slot != null) {
-    slot[politeness] = slot[politeness].filter(text => text !== message);
-    if (slot.polite.length === 0 && slot.assertive.length === 0) {
-      held.delete(dialog);
-    }
-  }
-}
-
 // Messages from callers whose enclosing modal is being presented in this
 // commit, waiting one frame for the route; an empty message among them
 // withdraws the earlier ones of its urgency, as it would on a channel.
+// Each message keeps a receipt per announcer: before the frame, taking it
+// back drops that announcer's share; the frame points it at its write.
 interface Deferred {
   frame: number;
-  messages: Record<AnnouncePoliteness, string[]>;
+  words: Record<AnnouncePoliteness, HeldWords[]>;
   clears: Record<AnnouncePoliteness, boolean>;
 }
 const deferredByScope = new WeakMap<ModalAnnounceScope, Deferred>();
@@ -333,7 +368,7 @@ function deferUntilPresented(
   scope: ModalAnnounceScope,
   message: string,
   politeness: AnnouncePoliteness,
-): void {
+): WithdrawAnnouncement | null {
   let deferred = deferredByScope.get(scope);
   if (deferred == null) {
     const created: Deferred = {
@@ -348,29 +383,54 @@ function deferUntilPresented(
               clearRegion(urgency);
             }
           }
-          for (const text of created.messages[urgency]) {
-            if (opened != null) {
-              announceInModalRouted(opened, text, urgency);
-            } else {
-              announceMessage(text, urgency);
-            }
-          }
+          // One write per announcer, so each can take back its own share.
+          forwardWaiting(created.words[urgency], text =>
+            opened != null
+              ? announceInModalRouted(opened, text, urgency)
+              : announceMessage(text, urgency),
+          );
         }
       }),
-      messages: {polite: [], assertive: []},
+      words: {polite: [], assertive: []},
       clears: {polite: false, assertive: false},
     };
     deferred = created;
     deferredByScope.set(scope, deferred);
   }
+  const waiting = deferred;
   if (!message) {
-    deferred.messages[politeness] = [];
-    deferred.clears[politeness] = true;
-    return;
+    // Taken back: the receipts of what waited have nothing left to take.
+    for (const words of waiting.words[politeness]) {
+      for (const receipt of words.receipts) {
+        receipt.withdraw = null;
+      }
+    }
+    waiting.words[politeness] = [];
+    waiting.clears[politeness] = true;
+    return null;
   }
-  if (!deferred.messages[politeness].includes(message)) {
-    deferred.messages[politeness].push(message);
+  let words = waiting.words[politeness].find(entry => entry.text === message);
+  if (words == null) {
+    words = {text: message, receipts: []};
+    waiting.words[politeness].push(words);
   }
+  const entry = words;
+  const receipt: AnnounceReceipt = {withdraw: null};
+  receipt.withdraw = () => {
+    // Before the frame: drop this announcer's share of the waiting words.
+    const at = entry.receipts.indexOf(receipt);
+    if (at < 0) {
+      return;
+    }
+    entry.receipts.splice(at, 1);
+    if (entry.receipts.length === 0) {
+      waiting.words[politeness] = waiting.words[politeness].filter(
+        other => other !== entry,
+      );
+    }
+  };
+  entry.receipts.push(receipt);
+  return handleOf(receipt);
 }
 
 /**
@@ -400,7 +460,7 @@ function announceFromScope(
   scope: ModalAnnounceScope,
   message: string,
   politeness: AnnouncePoliteness,
-): void {
+): WithdrawAnnouncement | null {
   if (isBeingPresented(scope)) {
     // Announced in the commit that opens the enclosing modal — a field error
     // inside `{isOpen && <Dialog isOpen>}`, alone or inside an already-open
@@ -411,8 +471,7 @@ function announceFromScope(
     // (FR9). A caller inside a modal that is meant to be closed (its content
     // stays mounted) is not waiting for anything: it takes the route of
     // where it is now, joined with the frame's other messages.
-    deferUntilPresented(scope, message, politeness);
-    return;
+    return deferUntilPresented(scope, message, politeness);
   }
   const dialog = enclosingOpenModal(scope);
   if (!message) {
@@ -423,17 +482,15 @@ function announceFromScope(
     } else {
       clearRegion(politeness);
     }
-    return;
+    return null;
   }
   if (dialog != null) {
-    announceInModalRouted(dialog, message, politeness);
-    return;
+    return announceInModalRouted(dialog, message, politeness);
   }
-  announceMessage(message, politeness);
+  return announceMessage(message, politeness);
 }
 
 installModalRoute({
   announce: announceFromScope,
   announceInModal: announceInModalRouted,
-  withdrawFromModalPending: withdrawFromModalPendingRouted,
 });