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

package/src/animator/createAnimator.doc.mjs

@@ -0,0 +1,153 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'createAnimator',
+  displayName: 'createAnimator',
+  // A factory documented as a hook: listed with the utilities, beside its
+  // hook, not as a tile in the components gallery.
+  group: 'Utilities',
+  keywords: [
+    'animate',
+    'animation',
+    'animator',
+    'spring',
+    'decay',
+    'momentum',
+    'fling',
+    'motion',
+    'transform',
+    'opacity',
+    'vanilla',
+    'factory',
+  ],
+  params: [
+    {
+      name: 'element',
+      type: 'HTMLElement',
+      description:
+        'The element to animate. The animator writes its `translate`, `scale`, `rotate` and `opacity`, and while it moves an inline `will-change` for them, merged with any it already has and restored 500 ms after its last motion; nothing else, so lay it out and style it as usual. Use one animator per element: two on one element overwrite each other.',
+      required: true,
+    },
+  ],
+  returns: [
+    {
+      name: 'animate',
+      type: '(target: {x?, y?, scale?, rotate?, opacity?}, options?: {velocity?}) => Promise<void>',
+      description:
+        "Springs the given channels to `target` from wherever they are on screen, on the state-change motion Astryx's components use, and resolves when they arrive (or as soon as a later call takes them over). `x` and `y` are px, `scale` is 1 at the element's size, `rotate` is degrees and `opacity` runs from 0 to 1. Pass `velocity` (units per second, such as a drag's release velocity) to start with it; without it a channel keeps the velocity it has on screen, so interrupting a motion never jumps.",
+    },
+    {
+      name: 'decay',
+      type: '(velocity: {x?, y?, scale?, rotate?, opacity?}) => Promise<void>',
+      description:
+        "Coasts the given channels from a release velocity in their units per second, slowing as a scroll view's momentum does, and resolves when they stop (or as soon as a later call takes any of them over); opacity stops at 0 or 1. The distance follows from the velocity: use it to fling something away, then remove or reset it.",
+    },
+    {
+      name: 'set',
+      type: '(values: {x?, y?, scale?, rotate?, opacity?}) => void',
+      description:
+        'Puts the given channels at these values at once, ending their motion: follow a finger with it, frame by frame.',
+    },
+    {
+      name: 'get',
+      type: '() => {x, y, scale, rotate, opacity}',
+      description: "Every channel's value on screen now.",
+    },
+    {
+      name: 'getVelocity',
+      type: '() => {x, y, scale, rotate, opacity}',
+      description:
+        "Every channel's velocity on screen now, in units per second.",
+    },
+    {
+      name: 'stop',
+      type: '() => void',
+      description: 'Halts every channel where it is on screen.',
+    },
+    {
+      name: 'destroy',
+      type: '() => void',
+      description:
+        'Stops every motion and lets the element go; the element keeps the values it shows. Call it when you remove the element or no longer animate it.',
+    },
+  ],
+  usage: {
+    description:
+      "Animates one element with the motion Astryx's own components use, without React. `animate` springs an element to new values on the state-change motion, `decay` flings it with the momentum of a released scroll view, and `set` moves it directly, so a card can follow a finger, snap back and be thrown away. Use the `useAnimator` hook in React. 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.",
+    bestPractices: [
+      {
+        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: true,
+        description:
+          '`await` the promise before removing an element you animate out, and call `destroy` once it is gone.',
+      },
+      {
+        guidance: false,
+        description:
+          'Read the element\u2019s position from layout while it moves: `get` gives the value on screen, wherever the motion runs.',
+      },
+    ],
+    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: ['useAnimator', 'useAnimatedLayout'],
+  importPath: '@astryxdesign/core',
+  category: 'interaction',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    "Animates one element (x, y, scale, rotate, opacity) with Astryx's motion, without React.",
+  paramDescriptions: {
+    element: 'The element to animate; one animator per element.',
+  },
+  returnDescriptions: {
+    animate:
+      '(target, {velocity?}) => Promise<void>; springs on the state-change motion.',
+    decay:
+      '({x?, y?, scale?, rotate?, opacity?}) => Promise<void>; coasts from a release velocity.',
+    set: '(values) => void; jumps, ending motion.',
+    get: '() => every value on screen.',
+    getVelocity: '() => every velocity on screen.',
+    stop: '() => void; halts where it is.',
+    destroy: '() => void; lets the element go.',
+  },
+  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: 'Read layout for the position mid-motion; use get.',
+      },
+    ],
+  },
+};

package/src/animator/createAnimator.ts

@@ -0,0 +1,324 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file createAnimator.ts
+ * @input An element; the internal motion animator (motion/animator.ts), the
+ *   `springs.stateChange` motion role and the momentum coast (motion/coast.ts)
+ * @output The public animator: `createAnimator`, the `AnimatorHandle` it
+ *   returns, and their value types
+ * @position Public entry point, re-exported from the package root. The
+ *   `useAnimator` hook wraps it. Importing it does no DOM work.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/animator/createAnimator.test.ts
+ * - /packages/core/src/animator/createAnimator.doc.mjs
+ * - /packages/core/src/hooks/useAnimator.ts
+ */
+
+import {
+  createMotionAnimator,
+  SETTLE_THRESHOLD,
+  type Animator as MotionAnimator,
+  type MotionCurve,
+  type MotionProperty,
+  type MotionValues,
+} from '../motion/animator';
+import {coast} from '../motion/coast';
+import {solveDecay} from '../motion/decay';
+import {registerSpringsTable, springs} from '../motion/uikit/springs';
+
+/**
+ * A channel the animator drives. `x` and `y` translate the element (px).
+ * `scale` scales it about its transform origin (1 is its size). `rotate`
+ * turns it (degrees, clockwise), and `opacity` fades it (0 to 1).
+ */
+export type AnimatorChannel = 'x' | 'y' | 'scale' | 'rotate' | 'opacity';
+
+/**
+ * Values by channel. A velocity uses the same keys, in units per second:
+ * px/s, scale per second, deg/s, opacity per second.
+ */
+export type AnimatorValues = Partial<Record<AnimatorChannel, number>>;
+
+/** Every channel's value (or velocity), as `get` and `getVelocity` read it. */
+export type AnimatorSnapshot = Readonly<Record<AnimatorChannel, number>>;
+
+/** Options of `AnimatorHandle.animate`. */
+export interface AnimatorAnimateOptions {
+  /**
+   * Each channel's velocity at the start, such as a drag's release velocity.
+   * A channel without one keeps the
+   * velocity it has on screen, so an `animate` that interrupts another
+   * carries on smoothly.
+   */
+  velocity?: AnimatorValues;
+}
+
+/**
+ * A release velocity for `AnimatorHandle.decay`, per channel, in its units
+ * per second. That is px/s for `x` and `y`, and degrees per second for
+ * `rotate`. `scale` and `opacity` take their units per second.
+ */
+export type AnimatorDecayVelocity = AnimatorValues;
+
+/**
+ * Animates one element. Each method acts on the channels it is given and
+ * leaves the others where they are.
+ */
+export interface AnimatorHandle {
+  /**
+   * Springs the given channels to `target` on the `springs.stateChange`
+   * motion role, from wherever they are on screen. The promise resolves when
+   * they arrive, or as soon as a later `animate`, `decay`, `set` or `stop`
+   * takes any of them over.
+   */
+  animate(
+    target: AnimatorValues,
+    options?: AnimatorAnimateOptions,
+  ): Promise<void>;
+  /**
+   * Coasts the given channels from a release velocity, slowing as a scroll
+   * view's momentum does. It resolves when they stop, or when another call
+   * takes them over. The distance follows from the velocity alone: there are
+   * no bounds, except that opacity stops at 0 or 1.
+   */
+  decay(velocity: AnimatorDecayVelocity): Promise<void>;
+  /**
+   * Puts the given channels at these values at once, ending their motion:
+   * the per-frame write of a drag.
+   */
+  set(values: AnimatorValues): void;
+  /** Every channel's value on screen now. */
+  get(): AnimatorSnapshot;
+  /** Every channel's velocity on screen now, in units per second. */
+  getVelocity(): AnimatorSnapshot;
+  /** Halts every channel where it is on screen. */
+  stop(): void;
+}
+
+/** What `createAnimator` returns: the handle, and `destroy`. */
+export interface Animator extends AnimatorHandle {
+  /**
+   * Stops every motion and lets go of the element; the element keeps the
+   * values it shows. The animator does nothing after this.
+   */
+  destroy(): void;
+}
+
+const CHANNELS: ReadonlyArray<AnimatorChannel> = [
+  'x',
+  'y',
+  'scale',
+  'rotate',
+  'opacity',
+];
+
+/** The values of the channels the public API names, and nothing else. */
+function motionValues(values: AnimatorValues | undefined): MotionValues {
+  const out: MotionValues = {};
+  if (values == null) {
+    return out;
+  }
+  for (const channel of CHANNELS) {
+    const value = values[channel];
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      out[channel] = value;
+    }
+  }
+  return out;
+}
+
+/**
+ * A coast from `from` at `velocity` on the momentum decay a scroll view
+ * uses, ending at rest. The theme does not change this decay. An opacity
+ * coast stops at 0 or 1.
+ */
+function momentum(
+  from: number,
+  velocity: number,
+  threshold: number,
+  isUnit: boolean,
+): MotionCurve {
+  const glide = solveDecay({from, velocity});
+  const edge = !isUnit ? null : glide.rest < 0 ? 0 : glide.rest > 1 ? 1 : null;
+  const hit = edge == null ? null : glide.timeToReach(edge);
+  const duration = hit ?? glide.settleTime(threshold);
+  const end = edge ?? glide.rest;
+  return {
+    duration,
+    at: t => (t >= duration ? end : glide.value(t)),
+    velocity: t => (t >= duration ? 0 : glide.velocity(t)),
+  };
+}
+
+function snapshot(
+  read: (channel: AnimatorChannel) => number,
+): AnimatorSnapshot {
+  return {
+    x: read('x'),
+    y: read('y'),
+    scale: read('scale'),
+    rotate: read('rotate'),
+    opacity: read('opacity'),
+  };
+}
+
+/**
+ * Resolves once every motion of one call has finished, or as soon as any of
+ * them is interrupted (`finished` resolves `false`). A later call that takes
+ * over one channel ends the whole call where it stopped, as one `animate`
+ * does. The other channels move on.
+ */
+async function settledOrTakenOver(
+  moving: ReadonlyArray<Promise<boolean>>,
+): Promise<void> {
+  if (moving.length === 0) {
+    return;
+  }
+  await new Promise<void>(resolve => {
+    let left = moving.length;
+    for (const finished of moving) {
+      void finished.then(completed => {
+        left -= 1;
+        if (!completed || left === 0) {
+          resolve();
+        }
+      });
+    }
+  });
+}
+
+/**
+ * An animator whose element is attached later, through `attach`. It is the
+ * one construction `createAnimator` and `useAnimator` share, so the hook has
+ * no behavior of its own. Not exported from the package.
+ */
+export function createAttachableAnimator(): {
+  readonly animator: Animator;
+  readonly attach: (element: HTMLElement | null) => void;
+} {
+  const motion: MotionAnimator = createMotionAnimator(null);
+  // Calls do nothing while no element is attached, before the ref attaches
+  // or after it lets go. They also do nothing after destroy, and animate and
+  // decay then resolve at once.
+  let element: HTMLElement | null = null;
+  let destroyed = false;
+  const inactive = () => destroyed || element == null;
+  const animator: Animator = {
+    async animate(target, options) {
+      const to = motionValues(target);
+      if (inactive() || Object.keys(to).length === 0) {
+        return;
+      }
+      // The role registry is written on first use, never on import.
+      registerSpringsTable();
+      const velocity = motionValues(options?.velocity);
+      await motion.animate(to, {
+        spring: springs.stateChange,
+        ...(Object.keys(velocity).length > 0 ? {velocity} : {}),
+      }).finished;
+    },
+    async decay(velocity) {
+      if (inactive()) {
+        return;
+      }
+      const given = motionValues(velocity);
+      // The translate axes coast as a throw, which Reduce Motion lets
+      // continue. The others coast as a transition, which it replaces.
+      const translate = coast(motion, {x: given.x, y: given.y});
+      const others: Partial<Record<MotionProperty | 'scale', MotionCurve>> = {};
+      for (const channel of ['scale', 'rotate', 'opacity'] as const) {
+        const v0 = given[channel];
+        if (v0 != null) {
+          const property = channel === 'scale' ? 'scaleX' : channel;
+          others[channel] = momentum(
+            motion.get(property),
+            v0,
+            SETTLE_THRESHOLD[property],
+            channel === 'opacity',
+          );
+        }
+      }
+      const moving: Promise<boolean>[] = [];
+      if (Object.keys(translate).length > 0) {
+        moving.push(motion.decay(translate).finished);
+      }
+      if (Object.keys(others).length > 0) {
+        moving.push(motion.play(others).finished);
+      }
+      await settledOrTakenOver(moving);
+    },
+    set(values) {
+      if (!inactive()) {
+        motion.set(motionValues(values));
+      }
+    },
+    get() {
+      return snapshot(channel => motion.get(channel));
+    },
+    getVelocity() {
+      return snapshot(channel => motion.getVelocity(channel));
+    },
+    stop() {
+      if (!inactive()) {
+        motion.stop();
+      }
+    },
+    destroy() {
+      if (!destroyed) {
+        destroyed = true;
+        // Halts every channel where it shows, so the element keeps those
+        // values and nothing reads as moving, then lets go of it.
+        motion.stop();
+        motion.dispose();
+      }
+    },
+  };
+  return {
+    animator,
+    attach: next => {
+      if (destroyed || next === element) {
+        return;
+      }
+      if (element != null) {
+        // The old node takes its values with it, so the next node, or a
+        // remount, starts at rest.
+        motion.attach(null);
+        motion.stop();
+        motion.set(motionValues(REST));
+      }
+      element = next;
+      motion.attach(next);
+    },
+  };
+}
+
+/** A new or remounted element starts from these values. */
+const REST = {x: 0, y: 0, scale: 1, rotate: 0, opacity: 1} as const;
+
+/**
+ * Animates `element` with the motion Core uses. `animate` springs channels to
+ * a target on the state-change motion, and `decay` coasts them from a release
+ * velocity. `set` jumps them, `get` and `getVelocity` read them, `stop` halts
+ * them, and `destroy` lets the element go. Under Reduce Motion every call is
+ * planned. A move becomes a short cross-fade on a touch screen, and it lands
+ * at once with a mouse.
+ *
+ * Use one animator per element: two on one element overwrite each other.
+ *
+ * @example
+ * ```
+ * const card = document.querySelector('.card');
+ * const animator = createAnimator(card);
+ * await animator.animate({x: 0, rotate: 0}, {velocity: {x: -900}});
+ * animator.decay({x: 2400});
+ * animator.destroy();
+ * ```
+ */
+export function createAnimator(element: HTMLElement): Animator {
+  const {animator, attach} = createAttachableAnimator();
+  attach(element);
+  return animator;
+}

package/src/gestures/GestureHost.ts

@@ -179,6 +179,7 @@ import {
 import {subscribeInput} from '../utils/inputStream';
 import {isPrimaryClick} from '../utils/primaryClick';
 import {
+  type DragSelectionHold,
   type DragSelectionReleaseOptions,
   lockDragSelection,
   locksSelectionFor,
@@ -590,7 +591,7 @@ function wheelPixels(
  * A trackpad's precise deltas, a third of their legacy `wheelDelta` in
  * Chromium and WebKit, read as a trackpad's.
  */
-function scrollTypeOf(wheel: WheelEvent): ScrollType {
+export function scrollTypeOf(wheel: WheelEvent): ScrollType {
   if (wheel.deltaMode !== 0 || wheel.shiftKey) {
     return 'discrete';
   }
@@ -710,10 +711,7 @@ export class GestureHost {
     (options?: DragSelectionReleaseOptions) => void
   >();
   /** Each claimed contact's drag hold, until its lift or a give-back. */
-  private readonly claimHolds = new Map<
-    number,
-    (options?: DragSelectionReleaseOptions) => void
-  >();
+  private readonly claimHolds = new Map<number, DragSelectionHold>();
   private readonly presentedHitTesting: 'auto' | 'always' | 'never';
   /**
    * Contacts sent to what is drawn instead of what the engine hit, by host
@@ -3747,10 +3745,13 @@ export class GestureHost {
     }
     this.pointerIds.delete(event.pointerId);
     this.pointerKinds.delete(event.pointerId);
+    const hold = this.claimHolds.get(id);
     this.unlockSelection(id);
     const dispositions = this.arena.ended([
       {id, x: event.clientX, y: event.clientY, time: eventTime(event)},
     ]);
+    // A selection the lift's own handlers made stays, as a click's does.
+    hold?.keepLiftSelection();
     // A retargeted tap's own click arms the click guard for the engine's.
     const landed = this.retargeted.get(id);
     this.retargeted.delete(id);

package/src/gestures/PressTracker.ts

@@ -47,7 +47,8 @@
  */
 
 import {UIKIT_CONTROL, UIKIT_PAN, UIKIT_PRESS} from '../motion/uikit/gestures';
-import {timing} from '../motion/uikit/timing';
+// Importing the whole table bundles its curves into each press-tracking control.
+import {press as pressClocks} from '../motion/uikit/timing';
 import {travel} from './geometry';
 import type {GestureRecognizer, SelectionLock} from './GestureRecognizer';
 import type {TapGestureRecognizer} from './TapGestureRecognizer';
@@ -154,7 +155,7 @@ export const PRESS_PROFILES = {
     // The shared press styles release every surface on the deselect clock
     // until a control runs its own release (UIButton's 250 ms), so a
     // painter's `fading` never outlasts the fade it shows.
-    releaseMs: timing.press.highlightOutMs,
+    releaseMs: pressClocks.highlightOutMs,
   },
   /**
    * A table or collection cell: inside a scroll view it highlights after the
@@ -165,7 +166,7 @@ export const PRESS_PROFILES = {
     highlightDelay: 'inScrollers',
     cancelTravel: UIKIT_PAN.hysteresis.value,
     quickTapFlash: 0,
-    releaseMs: timing.press.highlightOutMs,
+    releaseMs: pressClocks.highlightOutMs,
   },
 } as const satisfies Record<string, PressProfile>;
 

package/src/gestures/README.md

@@ -96,6 +96,10 @@ Once a drag has claimed its finger, a second finger never breaks it.
 | `PinchGestureRecognizer`         | `UIPinchGestureRecognizer`         | continuous | `scale` (settable, to re-base it), `velocity` in scale per second, `focalPoint()`                                                                                                                                  |
 | `ScreenEdgePanGestureRecognizer` | `UIScreenEdgePanGestureRecognizer` | continuous | `edges`: `leading` / `trailing`, resolved against the view's writing direction; attached to an edge zone the view lies within; fails as soon as the touch lands outside every requested edge band; a finger's only |
 
+Each recognizer reports what it is in `kind` (`'tap'`, `'longPress'`,
+`'pan'`, `'screenEdgePan'`, `'swipe'`, `'pinch'`): code tells the family apart by it, never by `instanceof`
+(`architecture:react-component-runtime` INV13).
+
 A recognizer created with `claimsTouches: false` is a watcher (a tab bar
 that minimizes while the page scrolls): it never claims, so its element gets
 only passive listeners and a scroll never waits for it; it prevents no other
@@ -174,7 +178,9 @@ innerPan.requireToFail(edgePan);
 ## Touches in the view: `createPressTracker`
 
 A pressable control's view-level touch handling, with `UIControl`
-semantics:
+semantics, built by `createPressTracker(options)`: a factory, as
+`architecture:react-component-runtime` INV13 asks of the touch modules outside
+the recognizer family (`VelocityTracker` is still a class, its one listed gap):
 
 - `touchDown`, `touchDragInside` / `touchDragOutside`, `touchDragEnter` /
   `touchDragExit`, `touchUpInside` / `touchUpOutside`, `touchCancel`.
@@ -436,9 +442,9 @@ no scroll.
 
 ### Holding the page still
 
-A scroll lock may hold the page with `holdPageScroll(document, decide)` from
-`pageHold.ts`, which returns the release (none does yet: `useScrollLock`
-does not call it). It lives in its own module, so a page without a scroll
+A scroll lock (`useScrollLock`) holds the page with
+`holdPageScroll(document, decide)` from `pageHold.ts`, which returns the
+release. It lives in its own module, so a page without a scroll
 lock never ships it, and it imports nothing of the gesture host: it asks the
 document's host whether a recognizer owns a touch only if a host exists, and
 a document without one has no recognizer to own it. A hold reads the

package/src/hooks/ModalAnnounceProvider.tsx

@@ -133,6 +133,7 @@ export function ModalAnnounceProvider({
     );
     sessionRef.current = {dialog, stop};
   }, [dialogRef, isOpen]);
+  // Releases the presentation watch and the held announcements on unmount.
   useEffect(
     () => () => {
       const session = sessionRef.current;