@astryxdesign/core 0.7.7 → 0.7.8-canary.30b1896

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

@@ -0,0 +1 @@
+{"version":3,"file":"scrollLockTouchGuard.d.ts","sourceRoot":"","sources":["../../src/hooks/scrollLockTouchGuard.ts"],"names":[],"mappings":"AAqHA;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAErD;AAWD;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,WAAW,GAAG,IAAI,EAC1B,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACT,OAAO,CAqCT"}

package/dist/hooks/scrollLockTouchGuard.js

@@ -0,0 +1,134 @@
+// 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
+ * @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 { parentAcrossShadow } from "../utils/flatTree.js";
+import { isRtlElement } from "./isRtlElement.js";
+const SCROLLABLE = new Set(['auto', 'scroll']);
+
+/** Overflow at or below this many px is a box that fits, not a scroller. */
+const EDGE_TOLERANCE = 1;
+function canMoveY(element, dy, range) {
+  // A finger moving down drags the content down: scrollTop decreases.
+  return dy > 0 ? element.scrollTop > EDGE_TOLERANCE - 0.5 : element.scrollTop < range - EDGE_TOLERANCE + 0.5;
+}
+function canMoveX(element, dx, range, isRtl) {
+  const min = isRtl ? -range : 0;
+  const max = isRtl ? 0 : range;
+  // A finger moving right drags the content right: scrollLeft decreases.
+  return dx > 0 ? element.scrollLeft > min + EDGE_TOLERANCE - 0.5 : element.scrollLeft < max - EDGE_TOLERANCE + 0.5;
+}
+
+/**
+ * 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, style, isVertical, dx, dy) {
+  if (!SCROLLABLE.has(isVertical ? style.overflowY : style.overflowX)) {
+    return false;
+  }
+  const range = isVertical ? element.scrollHeight - element.clientHeight : element.scrollWidth - element.clientWidth;
+  // Content that fits has nothing to scroll. The pan goes on to the next
+  // scroller in the chain, and at last to the page.
+  if (range <= EDGE_TOLERANCE) {
+    return false;
+  }
+  const canMove = isVertical ? canMoveY(element, dy, range) : canMoveX(element, dx, range, isRtlElement(element));
+  if (canMove) {
+    return true;
+  }
+  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, pseudoClass) {
+  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, style) {
+  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) {
+  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) {
+  // `: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, dx, dy) {
+  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 = 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/dist/hooks/scrollbarGutter.d.ts

@@ -1,7 +1,7 @@
 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. */
@@ -16,8 +16,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();
  * ```
  *

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

@@ -1 +1 @@
-{"version":3,"file":"scrollbarGutter.d.ts","sourceRoot":"","sources":["../../src/hooks/scrollbarGutter.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,MAAM,IAAI,IAAI,CAAC;IACf,6DAA6D;IAC7D,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,mBAAmB,CA+D7E"}
+{"version":3,"file":"scrollbarGutter.d.ts","sourceRoot":"","sources":["../../src/hooks/scrollbarGutter.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,MAAM,IAAI,IAAI,CAAC;IACf,6DAA6D;IAC7D,OAAO,IAAI,IAAI,CAAC;CACjB;AAWD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,mBAAmB,CAkE7E"}

package/dist/hooks/scrollbarGutter.js

@@ -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,10 +17,16 @@
 // engines without `scrollbar-gutter`, and it applies only when a measurement
 // shows that the element moved.
 
+import { claimRootScrollStyle } from "./rootScrollStyles.js";
 const NOOP = {
   settle() {},
   release() {}
 };
+/** Whether the engine reserves a gutter for `scrollbar-gutter: stable`. */
+function supportsScrollbarGutter() {
+  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.
@@ -29,8 +36,8 @@ const NOOP = {
  * 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();
  * ```
  *
@@ -44,25 +51,37 @@ export function holdScrollbarGutter(element) {
   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 = 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) {
@@ -71,9 +90,7 @@ export function holdScrollbarGutter(element) {
       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;
@@ -87,10 +104,6 @@ export function holdScrollbarGutter(element) {
         element.style.paddingRight = previousPadding;
         padded = false;
       }
-      if (heldGutter) {
-        root.style.scrollbarGutter = previousGutter;
-        heldGutter = false;
-      }
     }
   };
 }

package/dist/hooks/useActionGroupTracking.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @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 { type RefObject } from 'react';
+import { LongPressGestureRecognizer } from '../gestures/LongPressGestureRecognizer.js';
+import type { GestureTouch, PointerKind } from '../gestures/types.js';
+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;
+}
+/**
+ * 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.
+ */
+declare class ActionGroupPress extends LongPressGestureRecognizer {
+    protected acceptsTouch(touch: GestureTouch): boolean;
+}
+/**
+ * Track a held pointer on the group behind `ref` across the actions inside
+ * it, through the shared action-group tracker.
+ */
+export declare function useActionGroupTracking(ref: RefObject<HTMLElement | null>, options: ActionGroupTrackingOptions): ActionGroupPress;
+export {};
+//# sourceMappingURL=useActionGroupTracking.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useActionGroupTracking.d.ts","sourceRoot":"","sources":["../../src/hooks/useActionGroupTracking.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,OAAO,EAA8B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAElE,OAAO,EAAC,0BAA0B,EAAC,MAAM,wCAAwC,CAAC;AAElF,OAAO,KAAK,EAAC,YAAY,EAAE,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAOjE,MAAM,WAAW,0BAA0B;IACzC,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yFAAyF;IACzF,YAAY,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC1C,wDAAwD;IACxD,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IAC3C,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;CAC1C;AASD;;;GAGG;AACH,cAAM,gBAAiB,SAAQ,0BAA0B;cACpC,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO;CAO9D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAClC,OAAO,EAAE,0BAA0B,GAClC,gBAAgB,CAoHlB"}

package/dist/hooks/useActionGroupTracking.js

@@ -0,0 +1,174 @@
+// 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 } from 'react';
+import { isActive } from "../gestures/GestureRecognizer.js";
+import { LongPressGestureRecognizer } from "../gestures/LongPressGestureRecognizer.js";
+import { lockSelection } from "../utils/selectionLock.js";
+import { useGestureRecognizer } from "../gestures/useGestureRecognizer.js";
+import { UIKIT_PRESS } from "../motion/uikit/gestures.js";
+import { isIosWebKit } from "../utils/touchQueries.js";
+import { createActionGroupTracker } from "./actionGroupTracker.js";
+import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
+const PRESS = UIKIT_PRESS;
+
+/** The ref handed to the recognizer while tracking is off: no element. */
+const DETACHED = {
+  current: null
+};
+const EVERY_POINTER = ['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 {
+  acceptsTouch(touch) {
+    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, options) {
+  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('touch');
+  const landedRef = useRef(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;
+        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, touch, options) {
+  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/dist/hooks/useAnimator.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @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 { type RefObject } from 'react';
+import { type AnimatorHandle } from '../animator/createAnimator.js';
+/**
+ * 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 declare function useAnimator(ref: RefObject<HTMLElement | null>): AnimatorHandle;
+//# sourceMappingURL=useAnimator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useAnimator.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnimator.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAW,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC/C,OAAO,EAEL,KAAK,cAAc,EACpB,MAAM,4BAA4B,CAAC;AAGpC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,GACjC,cAAc,CAehB"}

package/dist/hooks/useAnimator.js

@@ -0,0 +1,70 @@
+// 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 } from 'react';
+import { createAttachableAnimator } from "../animator/createAnimator.js";
+import { useAttachment } from "./useAttachment.js";
+
+/**
+ * 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) {
+  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 => {
+        attachElement(element);
+        return () => attachElement(null);
+      }
+    };
+  });
+  useAttachment(ref, attach, null);
+  return handle;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"useAnnounceRenderedText.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnnounceRenderedText.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAcH,OAAO,EAA8B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAClE,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AAgCvB,MAAM,WAAW,2BAA2B;IAC1C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,UAAU,CAAC;CACvB;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAOzD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAClC,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,EACE,eAAuB,EACvB,UAAqB,EACrB,QAAQ,EAAE,aAAa,GACxB,GAAE,2BAAgC,GAClC,IAAI,CAoDN"}
+{"version":3,"file":"useAnnounceRenderedText.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnnounceRenderedText.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAcH,OAAO,EAA8B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAClE,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AAgCvB,MAAM,WAAW,2BAA2B;IAC1C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,UAAU,CAAC;CACvB;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAOzD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAClC,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,EACE,eAAuB,EACvB,UAAqB,EACrB,QAAQ,EAAE,aAAa,GACxB,GAAE,2BAAgC,GAClC,IAAI,CAqDN"}

package/dist/hooks/useAnnounceRenderedText.js

@@ -95,6 +95,7 @@ export function useAnnounceRenderedText(ref, isShown, occasion, {
   const [renderedWithPage] = useState(() => isHydrating || document.readyState !== 'complete');
   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.

package/dist/hooks/useAttachment.d.ts

@@ -5,7 +5,7 @@
  * @output Exports useAttachment and useAttachmentPair (two elements): they keep
  *   the attach function bound to the nodes the refs hold across commits
  * @position Internal React helper, not in hooks/index.ts: the one attach and
- *   release lifecycle of the gesture hooks and the pager
+ *   release lifecycle of the gesture hooks, the pager and useAnimator
  *
  * SYNC: When modified, update gestures/__tests__/useGestureRecognizer.test.tsx,
  * gestures/__tests__/useFingerScroll.test.tsx and

package/dist/hooks/useAttachment.js

@@ -9,7 +9,7 @@
  * @output Exports useAttachment and useAttachmentPair (two elements): they keep
  *   the attach function bound to the nodes the refs hold across commits
  * @position Internal React helper, not in hooks/index.ts: the one attach and
- *   release lifecycle of the gesture hooks and the pager
+ *   release lifecycle of the gesture hooks, the pager and useAnimator
  *
  * SYNC: When modified, update gestures/__tests__/useGestureRecognizer.test.tsx,
  * gestures/__tests__/useFingerScroll.test.tsx and

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

@@ -1 +1 @@
-{"version":3,"file":"useAutoMediaMode.d.ts","sourceRoot":"","sources":["../../src/hooks/useAutoMediaMode.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AACrC,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,gBAAgB,CAAC;AAMzC,+EAA+E;AAC/E,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;AA4EzD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,IAAI,EAChB,OAAO,EAAE,IAAI,GAAG,IAAI,EACpB,MAAM,EAAE,IAAI,GAAG,IAAI,EACnB,OAAO,EAAE,IAAI,GAAG,IAAI,GACnB,iBAAiB,GAAG,IAAI,CAe1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAClC,SAAS,EAAE,OAAO,GACjB,iBAAiB,GAAG,IAAI,CAmD1B"}
+{"version":3,"file":"useAutoMediaMode.d.ts","sourceRoot":"","sources":["../../src/hooks/useAutoMediaMode.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AACrC,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,gBAAgB,CAAC;AAMzC,+EAA+E;AAC/E,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;AA4EzD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,IAAI,EAChB,OAAO,EAAE,IAAI,GAAG,IAAI,EACpB,MAAM,EAAE,IAAI,GAAG,IAAI,EACnB,OAAO,EAAE,IAAI,GAAG,IAAI,GACnB,iBAAiB,GAAG,IAAI,CAe1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAClC,SAAS,EAAE,OAAO,GACjB,iBAAiB,GAAG,IAAI,CAoD1B"}