@astryxdesign/core 0.7.7 → 0.7.8-canary.0588a13

package/src/hooks/scrollLockTouchGuard.ts

@@ -0,0 +1,149 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file scrollLockTouchGuard.ts
+ * @input The node under a finger and the pan's direction, while a scroll lock
+ *   holds the page; the native-scroll probe's edge test (gestures/nativeScroll)
+ * @output isPanAbsorbedBeforePage and isPageZoomedIn, for the page hold
+ * @position Internal hook utility; gestures/pageHold calls it for
+ *   useScrollLock.
+ */
+
+// iOS Safari scrolls an `overflow: hidden` page under a finger.
+// The page hold cancels each pan that would reach the page. This walk decides
+// which pans those are. A scroller that can move in the pan's direction takes
+// the pan. A scroller at its edge that contains its overscroll also takes it.
+// The walk follows flat-tree parents. It ends at a top-layer or fixed-position
+// element, whose containing block is the viewport, so its untaken pans go to
+// the page.
+
+import {canElementScroll} from '../gestures/nativeScroll';
+import {parentAcrossShadow} from '../utils/flatTree';
+
+/**
+ * Whether `element` itself takes a pan. It does when it can still scroll that
+ * way, or when its `overscroll-behavior` contains the overscroll at its edge.
+ */
+function takesPan(
+  element: Element,
+  style: CSSStyleDeclaration,
+  isVertical: boolean,
+  dx: number,
+  dy: number,
+): boolean {
+  const x = isVertical ? 0 : dx;
+  const y = isVertical ? dy : 0;
+  if (canElementScroll(element, x, y)) {
+    return true;
+  }
+  // A scroller at its edge can still move the other way. A box that does not
+  // scroll, or whose content fits, cannot. Its pan goes on along the chain.
+  if (!canElementScroll(element, -x, -y)) {
+    return false;
+  }
+  const behavior = isVertical
+    ? style.overscrollBehaviorY
+    : style.overscrollBehaviorX;
+  return behavior === 'contain' || behavior === 'none';
+}
+
+/**
+ * Whether `element` is in the state that a pseudo-class names (`:modal`,
+ * `:popover-open`). An engine without the pseudo-class has no element in that
+ * state. Its `matches` throws on the selector, so the engine is not asked.
+ * Other errors surface.
+ */
+function isInState(element: Element, pseudoClass: string): boolean {
+  const css = element.ownerDocument.defaultView?.CSS;
+  return (
+    typeof css?.supports === 'function' &&
+    css.supports(`selector(${pseudoClass})`) &&
+    element.matches(pseudoClass)
+  );
+}
+
+/**
+ * Whether a pan that `element` does not take goes to the viewport, not to its
+ * DOM parent. The browser chains scrolling along containing blocks. A
+ * top-layer element (an open modal dialog or popover) or a fixed-position one
+ * has the viewport as its containing block. So a Dialog inside a scrolling
+ * container gives an untaken pan to the page.
+ */
+function chainsToViewport(
+  element: Element,
+  style: CSSStyleDeclaration,
+): boolean {
+  return (
+    style.position === 'fixed' ||
+    isInState(element, ':modal') ||
+    isInState(element, ':popover-open')
+  );
+}
+
+/**
+ * Whether the page is pinch-zoomed in (`visualViewport.scale > 1`). A
+ * one-finger drag then pans the zoomed view, which a zoomed-in reader needs
+ * around an open overlay. The value is read per touch, so a pinch during the
+ * lock counts from the next drag.
+ */
+export function isPageZoomedIn(doc: Document): boolean {
+  return (doc.defaultView?.visualViewport?.scale ?? 1) > 1;
+}
+
+/**
+ * Whether `element` is a native control that takes a finger's drag itself. A
+ * range input moves its thumb, so the drag never reaches the page.
+ */
+function takesDragItself(element: Element): boolean {
+  // `:disabled` also covers a slider inside a disabled fieldset.
+  return element.matches('input[type="range"]:not(:disabled)');
+}
+
+/**
+ * Whether a scroller in the scroll chain of `target` takes a pan of (`dx`,
+ * `dy`) before the page does.
+ */
+export function isPanAbsorbedBeforePage(
+  target: EventTarget | null,
+  dx: number,
+  dy: number,
+): boolean {
+  if (!(target instanceof Node)) {
+    return false;
+  }
+  const doc = target.ownerDocument ?? document;
+  const view = doc.defaultView;
+  if (view == null) {
+    return false;
+  }
+  const isVertical = Math.abs(dy) >= Math.abs(dx);
+  for (
+    let node: Node | null = target;
+    node != null;
+    node = parentAcrossShadow(node)
+  ) {
+    if (!(node instanceof Element)) {
+      continue;
+    }
+    if (takesDragItself(node)) {
+      return true;
+    }
+    if (
+      node === doc.documentElement ||
+      node === doc.body ||
+      node === doc.scrollingElement
+    ) {
+      break;
+    }
+    const style = view.getComputedStyle(node);
+    if (takesPan(node, style, isVertical, dx, dy)) {
+      return true;
+    }
+    if (chainsToViewport(node, style)) {
+      break;
+    }
+  }
+  return false;
+}

package/src/hooks/scrollbarGutter.ts

@@ -2,7 +2,8 @@
 
 /**
  * @file scrollbarGutter.ts
- * @input The element a scroll lock pins, plus live layout measurements
+ * @input The element whose width a scroll lock holds, plus live layout
+ *   measurements
  * @output holdScrollbarGutter and the ScrollbarGutterHold it returns
  * @position Internal hook utility; used by useScrollLock and MobileNav so that
  *   locking background scroll does not resize the layout viewport.
@@ -16,6 +17,8 @@
 // engines without `scrollbar-gutter`, and it applies only when a measurement
 // shows that the element moved.
 
+import {claimRootScrollStyle} from './rootScrollStyles';
+
 const NOOP: ScrollbarGutterHold = {
   settle() {},
   release() {},
@@ -23,14 +26,23 @@ const NOOP: ScrollbarGutterHold = {
 
 export interface ScrollbarGutterHold {
   /**
-   * Call once the lock's own styles are applied: measures whether the element
-   * grew anyway and, only then, pads the difference away.
+   * Call once the lock's own styles apply. It holds the gutter open, or,
+   * without `scrollbar-gutter`, pads away only the width the element gained.
    */
   settle(): void;
   /** Call on unlock: restores everything this hold changed. */
   release(): void;
 }
 
+/** Whether the engine reserves a gutter for `scrollbar-gutter: stable`. */
+function supportsScrollbarGutter(): boolean {
+  return (
+    typeof CSS !== 'undefined' &&
+    typeof CSS.supports === 'function' &&
+    CSS.supports('scrollbar-gutter', 'stable')
+  );
+}
+
 /**
  * Keeps `element`'s content box the width it is right now, across a scroll
  * lock that is about to hide the document's scrollbar.
@@ -40,8 +52,8 @@ export interface ScrollbarGutterHold {
  * ScrollbarGutterHold.release} on unlock:
  *
  * ```
- * const hold = holdScrollbarGutter(document.body);
- * body.style.position = 'fixed';
+ * const hold = holdScrollbarGutter(document.documentElement);
+ * document.documentElement.style.overflow = 'hidden';
  * hold.settle();
  * ```
  *
@@ -56,28 +68,37 @@ export function holdScrollbarGutter(element: HTMLElement): ScrollbarGutterHold {
   const root = document.documentElement;
   const viewportWidth = root.clientWidth;
 
-  // 0 means "no layout to measure" (jsdom, and any non-visual environment),
-  // not "the scrollbar is as wide as the window".
-  if (viewportWidth === 0) {
+  // 0 means that there is no layout to measure, as in jsdom. An overlay
+  // scrollbar takes no space, so there is nothing to hold. A gutter held open
+  // on such a page would add space that was never there.
+  if (viewportWidth === 0 || window.innerWidth <= viewportWidth) {
     return NOOP;
   }
 
-  const previousGutter = root.style.scrollbarGutter;
+  if (supportsScrollbarGutter()) {
+    // The gutter holds the width by construction, so the lock forces no second
+    // layout. Each hold is a stacked claim, so one release keeps the gutter
+    // that another hold still needs.
+    let releaseGutter: (() => void) | null = null;
+    return {
+      settle() {
+        releaseGutter ??= claimRootScrollStyle({scrollbarGutter: 'stable'});
+      },
+      release() {
+        releaseGutter?.();
+        releaseGutter = null;
+      },
+    };
+  }
+
+  // An engine without `scrollbar-gutter`: measure the element now, again
+  // once the lock's styles apply, and pad away what it grew. This is the one
+  // path that reads layout after a write.
   const previousPadding = element.style.paddingRight;
   const widthBefore = element.getBoundingClientRect().width;
-
-  let heldGutter = false;
   let padded = false;
   let settled = false;
 
-  // Only when a space-taking scrollbar is actually there. Holding the gutter
-  // open on a page that never had one would carve out 15px that was never
-  // reserved — the same shift, in the other direction.
-  if (window.innerWidth > viewportWidth) {
-    root.style.scrollbarGutter = 'stable';
-    heldGutter = true;
-  }
-
   return {
     settle() {
       if (settled) {
@@ -86,9 +107,7 @@ export function holdScrollbarGutter(element: HTMLElement): ScrollbarGutterHold {
       settled = true;
 
       // What the lock actually did to this element, rather than what we
-      // assumed it would do. 0 on any engine where the gutter held — and on a
-      // page that already sets `scrollbar-gutter: stable` itself, where the
-      // scrollbar was never taking the space back.
+      // assumed it would do.
       const grew = element.getBoundingClientRect().width - widthBefore;
       if (grew <= 0) {
         return;
@@ -105,10 +124,6 @@ export function holdScrollbarGutter(element: HTMLElement): ScrollbarGutterHold {
         element.style.paddingRight = previousPadding;
         padded = false;
       }
-      if (heldGutter) {
-        root.style.scrollbarGutter = previousGutter;
-        heldGutter = false;
-      }
     },
   };
 }

package/src/hooks/useActionGroupTracking.ts

@@ -0,0 +1,224 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useActionGroupTracking.ts
+ * @input A ref to a group of sibling actions, the actions' selector, and the
+ *   component's tracking constants
+ * @output Exports useActionGroupTracking and ActionGroupTrackingOptions
+ * @position Internal hook, not exported from the hooks entry. A long press
+ *   drives the shared action-group tracker (hooks/actionGroupTracker.ts) for
+ *   a group that a held pointer slides across. AlertDialog consumes it.
+ *
+ * SYNC: When modified, update useActionGroupTracking.test.tsx
+ */
+
+import {useEffect, useRef, useState, type RefObject} from 'react';
+import {isActive} from '../gestures/GestureRecognizer';
+import {LongPressGestureRecognizer} from '../gestures/LongPressGestureRecognizer';
+import {lockSelection} from '../utils/selectionLock';
+import type {GestureTouch, PointerKind} from '../gestures/types';
+import {useGestureRecognizer} from '../gestures/useGestureRecognizer';
+import {UIKIT_PRESS} from '../motion/uikit/gestures';
+import {isIosWebKit} from '../utils/touchQueries';
+import {createActionGroupTracker} from './actionGroupTracker';
+import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
+
+export interface ActionGroupTrackingOptions {
+  /** Selects the actions inside the tracked element. */
+  itemSelector: string;
+  /** How long after touch-down the touched action highlights, ms. */
+  highlightOnsetMs: number;
+  /**
+   * How far outside an action a finger keeps it highlighted, px. A mouse or a
+   * pen hit-tests the actions' exact rects.
+   */
+  highlightExpansion: number;
+  /** Pointers that are tracked; others keep the browser's click. @default every pointer */
+  pointerTypes?: ReadonlyArray<PointerKind>;
+  /** A press whose target this rejects is not tracked. */
+  shouldTrack?: (target: unknown) => boolean;
+  /** Off, nothing is attached and nothing is tracked. @default true */
+  isEnabled?: boolean;
+  /**
+   * Let the gesture host write the group's `touch-action` and refuse a text
+   * selection while a finger or a pen holds it.
+   * @default true
+   */
+  manageStyle?: boolean;
+  /** Runs the action under the finger at the lift. @default its own click */
+  onActivate?: (item: HTMLElement) => void;
+}
+
+const PRESS = UIKIT_PRESS;
+
+/** The ref handed to the recognizer while tracking is off: no element. */
+const DETACHED: RefObject<Element | null> = {current: null};
+
+const EVERY_POINTER: ReadonlyArray<PointerKind> = ['touch', 'pen', 'mouse'];
+
+/**
+ * The group's press: a long press that a second finger on the group ends with
+ * nothing acting. A plain long press ignores a second finger.
+ */
+class ActionGroupPress extends LongPressGestureRecognizer {
+  protected override acceptsTouch(touch: GestureTouch): boolean {
+    if (isActive(this.state)) {
+      this.setState('cancelled');
+      return false;
+    }
+    return super.acceptsTouch(touch);
+  }
+}
+
+/**
+ * Track a held pointer on the group behind `ref` across the actions inside
+ * it, through the shared action-group tracker.
+ */
+export function useActionGroupTracking(
+  ref: RefObject<HTMLElement | null>,
+  options: ActionGroupTrackingOptions,
+): ActionGroupPress {
+  const optionsRef = useRef(options);
+  // Keeps the recognizer's delegate and the tracker, which run outside
+  // render, reading the latest options.
+  useIsomorphicLayoutEffect(() => {
+    optionsRef.current = options;
+  });
+  // The pointer that started the current press. Only a finger gets the hit
+  // expansion; a mouse or a pen hit-tests the actions' exact rects.
+  const pointerRef = useRef<PointerKind>('touch');
+  const landedRef = useRef<Node | null>(null);
+  const [tracker] = useState(() =>
+    createActionGroupTracker(() => ({
+      roots: () => [ref.current],
+      itemSelector: optionsRef.current.itemSelector,
+      highlightExpansion:
+        pointerRef.current === 'touch'
+          ? optionsRef.current.highlightExpansion
+          : 0,
+      onActivate: optionsRef.current.onActivate,
+      // The browser's own click for a press the group ran is taken, so the
+      // action runs once. The gesture host swallows it for a press it claims.
+      // This covers one it does not claim, a mouse under a coarse pointer.
+      swallowsNativeClick: true,
+    })),
+  );
+  const isEnabled = options.isEnabled ?? true;
+  // Synchronizes the tracker with tracking on and mounted. Turning tracking
+  // off, or unmounting, drops a tracked press and ends its release fades.
+  // The host reports no cancellation to a disabled recognizer, and the lift
+  // that runs an action often closes the owner before its fade ends.
+  useEffect(
+    () => () => {
+      tracker.cancel();
+      tracker.dispose();
+    },
+    [tracker, isEnabled],
+  );
+
+  return useGestureRecognizer(
+    isEnabled ? ref : DETACHED,
+    () =>
+      new ActionGroupPress({
+        name: 'ActionGroupTracking',
+        minimumPressDuration: options.highlightOnsetMs,
+        allowableMovement: Number.POSITIVE_INFINITY,
+        allowedPointerTypes: options.pointerTypes ?? EVERY_POINTER,
+        delaysTouchesBegan: true,
+        // The hold picks an action, so a held finger or pen starts no text
+        // selection and opens no callout while down. A long press brings this
+        // lock by default; this hold has no minimum duration, so it names it.
+        selectionLock: lockSelection,
+        shouldReceiveTouch: (recognizer, touch) => {
+          if (recognizer.numberOfTouches === 0) {
+            pointerRef.current = touch.pointerType;
+            const target = touch.target as Node | null;
+            landedRef.current =
+              typeof target?.nodeType === 'number' ? target : null;
+          }
+          return receiveTouch(recognizer, touch, optionsRef.current);
+        },
+      }),
+    recognizer => {
+      switch (recognizer.state) {
+        case 'began': {
+          const {x, y} = recognizer.location();
+          tracker.begin(x, y, {landed: landedRef.current});
+          break;
+        }
+        case 'changed': {
+          const {x, y} = recognizer.location();
+          tracker.move(x, y);
+          break;
+        }
+        case 'ended': {
+          const doc = ref.current?.ownerDocument;
+          const focusedBefore = doc?.activeElement ?? null;
+          const beganOn = tracker.beganOn;
+          // Whether a click on the lifted action would focus it. A mouse's or
+          // a pen's pointerdown already gave the engine's answer, on the action
+          // it began on. A tap focuses on a later mousedown, which the claimed
+          // touch cancels, so the platform answers for a finger.
+          // iOS WebKit focuses no tapped button; Chromium and Firefox do.
+          const clickFocuses =
+            pointerRef.current === 'touch'
+              ? !isIosWebKit(doc?.defaultView)
+              : beganOn != null && focusedBefore === beganOn;
+          const lifted = tracker.end();
+          // The lift runs the action's own click(), which moves no focus. So
+          // focus moves to the lifted action, unless its click moved focus.
+          if (
+            clickFocuses &&
+            lifted != null &&
+            lifted.isConnected &&
+            doc?.activeElement === focusedBefore &&
+            focusedBefore !== lifted
+          ) {
+            lifted.focus({preventScroll: true, focusVisible: false});
+          }
+          break;
+        }
+        case 'cancelled':
+          tracker.cancel();
+          break;
+        case 'possible':
+        case 'failed':
+          // Listeners are not called for these.
+          break;
+      }
+    },
+    {
+      isEnabled,
+      manageStyle: options.manageStyle ?? true,
+      actionGroup: true,
+    },
+  );
+}
+
+/**
+ * The recognizer's should-receive delegate. It also picks the press's clock.
+ * Inside a scroller the press waits the content-touch delay and fails past
+ * the slop, so the scroller takes a flick. Elsewhere it begins at once, with
+ * no movement limit.
+ */
+function receiveTouch(
+  recognizer: LongPressGestureRecognizer,
+  touch: GestureTouch,
+  options: ActionGroupTrackingOptions,
+): boolean {
+  if (options.shouldTrack?.(touch.target) === false) {
+    return false;
+  }
+  if (recognizer.numberOfTouches === 0) {
+    const isInsideScroller = touch.scroll?.isInsideScroller === true;
+    recognizer.minimumPressDuration = isInsideScroller
+      ? PRESS.contentTouchDelay.value
+      : options.highlightOnsetMs;
+    recognizer.allowableMovement = isInsideScroller
+      ? PRESS.slop.value
+      : Number.POSITIVE_INFINITY;
+  }
+  return true;
+}

package/src/hooks/useAnimator.doc.mjs

@@ -0,0 +1,109 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useAnimator',
+  displayName: 'useAnimator',
+  keywords: [
+    'animate',
+    'animation',
+    'animator',
+    'spring',
+    'decay',
+    'momentum',
+    'fling',
+    'motion',
+    'transform',
+    'opacity',
+    'drag',
+    'card',
+  ],
+  params: [
+    {
+      name: 'ref',
+      type: 'RefObject<HTMLElement | null>',
+      description:
+        'The ref of the one element to animate, the same ref you pass to the element: another hook, such as a gesture hook, can take it too, so a drag and an animation share one element. After every render the animator follows the element behind it. When the element unmounts its motion stops and its values return to rest, so a remount starts at rest, and so does a node that replaces it. Before the element mounts, and while it is unmounted, every call does nothing and `animate` and `decay` resolve at once.',
+      required: true,
+    },
+  ],
+  returns: [
+    {
+      name: 'animator',
+      type: 'AnimatorHandle',
+      description:
+        "The element's animator, the same object on every render: `animate(target, {velocity?})` springs channels to a target on the state-change motion Astryx's components use, `decay(velocity)` coasts them from a release velocity, `set(values)` jumps them, `get()` and `getVelocity()` read them, and `stop()` halts them. The channels are `x` and `y` (px), `scale` (1 at the element's size), `rotate` (degrees) and `opacity` (0 to 1). `animate` and `decay` return a promise that resolves when the motion ends. Calling it never re-renders the component. Calls before the ref attaches do nothing and resolve at once.",
+    },
+  ],
+  usage: {
+    description:
+      "Animates one element with the motion Astryx's own components use. Call `animator.animate` to spring an element to new values on the state-change motion, `animator.decay` to fling it with the momentum of a released scroll view, and `animator.set` to move it directly, so a card can follow a finger, snap back and be thrown away. To animate an area's layout as its items change, use `useAnimatedLayout`; for what a component already animates, such as a sheet's detents or a carousel's snapping, use the component's own props. Outside React, use `createAnimator`.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Call the animator from event handlers and effects: it lives outside render, so animating never re-renders the component.',
+      },
+      {
+        guidance: true,
+        description:
+          'Start every `animate` that follows a drag with the release velocity, so the element carries on as it was thrown.',
+      },
+      {
+        guidance: true,
+        description:
+          'Reach every state an animation shows without the animation too: a key, a button or a menu item that calls the same code.',
+      },
+      {
+        guidance: false,
+        description:
+          'Keep the animated values in React state: read them with `animator.get()` when you need them.',
+      },
+    ],
+    accessibility: [
+      {
+        name: 'Keyboard and assistive technology',
+        category: 'Keyboard',
+        description:
+          'An animator moves an element; it adds no way to act. Give every action an animation stands for a control a keyboard and a screen reader can reach, such as a button that discards a card, and have it call `animate`, which Reduce Motion turns into a fade in place. Keep `decay` for a throw the person made: Reduce Motion keeps the momentum of a coast, as it continues that throw. Keep focus on an element that stays on screen: move it before you fling its element away.',
+      },
+      {
+        name: 'Reduce Motion',
+        category: 'Content',
+        criterion: '2.3.3 Animation from Interactions',
+        description:
+          'When the person asks for reduced motion, every call is planned for them. On a touch screen a move or a scale becomes a short opacity cross-fade: the element fades out where it was and fades back in where it lands. With a mouse it lands at once. A decay of `x` and `y` keeps its momentum, as it continues the throw the person made; a decay of `scale`, `rotate` or `opacity` is planned like a move. No option turns this off.',
+      },
+    ],
+  },
+  relatedHooks: ['useAnimatedLayout'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'interaction',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    "Animates the element behind ref (x, y, scale, rotate, opacity) with Astryx's motion; returns the animator.",
+  paramDescriptions: {
+    ref: 'The element ref; share it with a gesture hook to drag and animate one element.',
+  },
+  returnDescriptions: {
+    animator:
+      'animate(target, {velocity?}), decay(velocity), set, get, getVelocity, stop; stable, never re-renders.',
+  },
+  usage: {
+    description:
+      'Spring with animate, fling with decay, follow a finger with set. Reduce Motion: a cross-fade on touch, at once with a mouse; decay keeps its momentum.',
+    bestPractices: [
+      {
+        guidance: true,
+        description: 'Pass the release velocity to animate after a drag.',
+      },
+      {
+        guidance: false,
+        description: 'Keep animated values in state; read animator.get().',
+      },
+    ],
+  },
+};

package/src/hooks/useAnimator.ts

@@ -0,0 +1,67 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useAnimator.ts
+ * @input React (useState), the element ref the caller owns, the public
+ *   animator factory (animator/createAnimator.ts) and useAttachment
+ * @output Exports `useAnimator(ref)`: the public animator for the element
+ *   behind `ref`
+ * @position Public hook, exported from `@astryxdesign/core/hooks`. A thin
+ *   wrapper over `createAnimator` with no behavior of its own.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/useAnimator.test.tsx
+ * - /packages/core/src/hooks/useAnimator.doc.mjs
+ */
+
+import {useState, type RefObject} from 'react';
+import {
+  createAttachableAnimator,
+  type AnimatorHandle,
+} from '../animator/createAnimator';
+import {useAttachment} from './useAttachment';
+
+/**
+ * Animates the element behind `ref` with the motion Core uses. Call
+ * `animate`, `decay`, `set`, `get`, `getVelocity` or `stop` on the returned
+ * animator from event handlers and effects. Pass the same `ref` to a gesture
+ * hook to drag and animate one element.
+ *
+ * The hook makes the animator once, and animating never re-renders the
+ * component. After each commit, the animator follows the element behind
+ * `ref`, also a node that replaces it. An unmount stops running motion and
+ * drops the values. A remount, or a node that replaces the element, starts
+ * at rest. While no element is attached, every call does nothing, and
+ * `animate` and `decay` resolve at once.
+ *
+ * @example
+ * ```
+ * const ref = useRef<HTMLDivElement>(null);
+ * const animator = useAnimator(ref);
+ * return (
+ *   <div ref={ref} onClick={() => animator.animate({scale: 1.2})}>
+ *     Card
+ *   </div>
+ * );
+ * ```
+ */
+export function useAnimator(
+  ref: RefObject<HTMLElement | null>,
+): AnimatorHandle {
+  const [{handle, attach}] = useState(() => {
+    const {animator, attach: attachElement} = createAttachableAnimator();
+    // The handle without `destroy`: the hook owns the element's lifetime.
+    const {destroy: _destroy, ...handle} = animator;
+    return {
+      handle,
+      attach: (element: HTMLElement) => {
+        attachElement(element);
+        return () => attachElement(null);
+      },
+    };
+  });
+  useAttachment(ref, attach, null);
+  return handle;
+}

package/src/hooks/useAnnounceRenderedText.ts

@@ -135,6 +135,7 @@ export function useAnnounceRenderedText(
   );
   const isFirstRunRef = useRef(true);
 
+  // Syncs the live region with the rendered text.
   // No dependency array: the text lives in the DOM, and a caller can change it
   // without a prop that this hook sees. One text read per render is cheap, and
   // the dedupe below makes later renders no-ops.