An open source design system that's fully customizable and agent ready
TypeScript
// 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 {
createMotionEngine,
SETTLE_THRESHOLD,
type Animator as MotionEngine,
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: MotionEngine = createMotionEngine(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 spring roles registered as their module loaded, so this call
// registers nothing new.
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;
}