@astryxdesign/core 0.7.7-canary.bf14580 → 0.7.7-canary.c19ca12

package/src/Typeahead/TypeaheadItem.doc.mjs

@@ -43,7 +43,8 @@ export const docs = {
     {
       name: 'group',
       type: 'string',
-      description: 'Group label for grouping items visually.',
+      description:
+        'This prop has no effect. Set `item.auxiliaryData.group` on search-source items to group results in Typeahead or BaseTypeahead.',
     },
   ],
 };
@@ -79,7 +80,8 @@ export const docsZh = {
     {
       name: 'group',
       type: 'string',
-      description: '用于视觉分组的分组标签。',
+      description:
+        '此属性不影响渲染。要在 Typeahead 或 BaseTypeahead 中分组，请在搜索源返回的结果项上设置 `item.auxiliaryData.group`。',
     },
   ],
 };
@@ -94,6 +96,7 @@ export const docsDense = {
     icon: 'Icon/avatar before label.',
     description: 'Text below label.',
     isDisabled: 'Visually disabled.',
-    group: 'Group label for visual grouping.',
+    group:
+      'No effect. Group results via `item.auxiliaryData.group` in the search source.',
   },
 };

package/src/Typeahead/TypeaheadItem.tsx

@@ -54,7 +54,8 @@ export interface TypeaheadItemProps<
   isDisabled?: boolean;
 
   /**
-   * Group label for grouping items visually.
+   * This prop has no effect. Set `item.auxiliaryData.group` on search-source
+   * items to group results in Typeahead or BaseTypeahead.
    */
   group?: string;
 }

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;
+}