@voila.dev/motion 0.0.0-stage → 5.0.0

package/src/animate/controls.ts

@@ -0,0 +1,76 @@
+import type { AnimationControls, AnimationState } from "#/animate/types.ts";
+
+/**
+ * `finished` and the `then` that makes controls awaitable:
+ * `await animate(…)` waits for the end, the way Motion's controls do.
+ */
+export function thenable(
+	finished: Promise<void>,
+): Pick<AnimationControls, "finished" | "then"> {
+	return {
+		finished,
+		// biome-ignore lint/suspicious/noThenProperty: controls are awaitable on purpose.
+		then: (onFulfilled, onRejected) => finished.then(onFulfilled, onRejected),
+	};
+}
+
+/**
+ * One set of controls over many animations: the properties of one element,
+ * the elements of a selector, the segments of a sequence. They share a clock
+ * (every child's `time` counts from the same start), so scrubbing the group
+ * scrubs each child at the same moment.
+ */
+export function groupControls(
+	children: readonly AnimationControls[],
+): AnimationControls {
+	const finished = Promise.all(children.map((child) => child.finished)).then(
+		() => undefined,
+	);
+	function each(action: (child: AnimationControls) => void) {
+		return () => {
+			for (const child of children) action(child);
+		};
+	}
+	return {
+		...thenable(finished),
+		get time() {
+			return Math.max(0, ...children.map((child) => child.time));
+		},
+		set time(seconds) {
+			for (const child of children) child.time = seconds;
+		},
+		get speed() {
+			return children[0]?.speed ?? 1;
+		},
+		set speed(rate) {
+			for (const child of children) child.speed = rate;
+		},
+		get duration() {
+			return Math.max(0, ...children.map((child) => child.duration));
+		},
+		get state(): AnimationState {
+			const states = new Set(children.map((child) => child.state));
+			if (states.has("running")) return "running";
+			return states.has("paused") ? "paused" : "finished";
+		},
+		play: each((child) => child.play()),
+		pause: each((child) => child.pause()),
+		stop: each((child) => child.stop()),
+		cancel: each((child) => child.cancel()),
+		complete: each((child) => child.complete()),
+		attachTimeline(timeline) {
+			const attached = children.filter((child) =>
+				child.attachTimeline(timeline),
+			);
+			if (attached.length === children.length) return true;
+			// All or nothing: a half-native group would drift from its JS half.
+			for (const child of attached) child.attachTimeline(document.timeline);
+			return false;
+		},
+	};
+}
+
+/** The controls of an animation that had nothing to animate, or jumped: already finished. */
+export function finishedControls(): AnimationControls {
+	return groupControls([]);
+}

package/src/animate/dom.ts

@@ -0,0 +1,166 @@
+import { shouldReduceMotion } from "#/accessibility/reduced-motion.ts";
+import { finishedControls, groupControls } from "#/animate/controls.ts";
+import type { JsAnimation, JsAnimationConfig } from "#/animate/js-animation.ts";
+import {
+	beginTransform,
+	commitTransform,
+	committedTransform,
+	cssName,
+	isMovement,
+	TRANSFORMS,
+	withUnit,
+} from "#/animate/style.ts";
+import type {
+	AnimationControls,
+	AnimationOptions,
+	DOMKeyframes,
+	KeyframeValue,
+} from "#/animate/types.ts";
+import { waapiAnimation } from "#/animate/waapi.ts";
+
+/** Attributes an SVG element animates in JavaScript: `d` morphs, the rest are geometry. */
+const SVG_ATTRIBUTES: Readonly<Record<string, string>> = {
+	d: "d",
+	points: "points",
+	viewBox: "viewBox",
+	cx: "cx",
+	cy: "cy",
+	r: "r",
+	rx: "rx",
+	ry: "ry",
+	x1: "x1",
+	y1: "y1",
+	x2: "x2",
+	y2: "y2",
+	attrX: "x",
+	attrY: "y",
+	attrWidth: "width",
+	attrHeight: "height",
+};
+
+/**
+ * Plays what the browser can't (SVG attributes, CSS variables) on the frame
+ * loop. Injected, so an entry that only needs the browser's half never loads
+ * the interpolators.
+ */
+export type ScriptedChannel = (
+	config: JsAnimationConfig<KeyframeValue>,
+) => JsAnimation<KeyframeValue>;
+
+const running = new WeakMap<Element, Map<string, JsAnimation<KeyframeValue>>>();
+
+interface Channel {
+	read(): KeyframeValue;
+	write(value: KeyframeValue): void;
+	readonly native: boolean;
+}
+
+function channelOf(element: Element, key: string): Channel {
+	const style = (element as HTMLElement).style;
+	const attribute =
+		element instanceof SVGElement ? SVG_ATTRIBUTES[key] : undefined;
+	if (TRANSFORMS[key]) {
+		return {
+			read: () => committedTransform(element, key),
+			write: (value) => commitTransform(element, key, value),
+			native: true,
+		};
+	}
+	if (attribute) {
+		return {
+			read: () => element.getAttribute(attribute) ?? "",
+			write: (value) => element.setAttribute(attribute, String(value)),
+			native: false,
+		};
+	}
+	const name = cssName(key);
+	return {
+		read: () => getComputedStyle(element).getPropertyValue(name).trim(),
+		write: (value) => style.setProperty(name, withUnit(key, value)),
+		// An unregistered custom property only animates discretely in the browser.
+		native: !key.startsWith("--"),
+	};
+}
+
+function asTarget(read: KeyframeValue, target: KeyframeValue): KeyframeValue {
+	return typeof target === "number" && typeof read === "string"
+		? Number.parseFloat(read) || 0
+		: read;
+}
+
+function animateChannel(
+	element: Element,
+	key: string,
+	value: KeyframeValue | readonly KeyframeValue[],
+	options: AnimationOptions,
+	delay: number,
+	scripted: ScriptedChannel | undefined,
+): AnimationControls {
+	const channel = channelOf(element, key);
+	const list: readonly KeyframeValue[] = Array.isArray(value) ? value : [value];
+	const target = list.at(-1) as KeyframeValue;
+	const animations = running.get(element) ?? new Map();
+	running.set(element, animations);
+	const previous = animations.get(key);
+	const now = previous?.current();
+	previous?.stop();
+	const from = now?.value ?? asTarget(channel.read(), target);
+	const keyframes = list.length > 1 ? list : [from, target];
+	if (
+		(shouldReduceMotion(options.reducedMotion) && isMovement(key)) ||
+		(!channel.native && !scripted)
+	) {
+		channel.write(target);
+		return finishedControls();
+	}
+	const reduced = shouldReduceMotion(options.reducedMotion)
+		? { ...options, type: "tween" as const, bounce: 0 }
+		: options;
+	const config = {
+		keyframes,
+		options: reduced,
+		delay,
+		velocity: list.length > 1 ? 0 : (now?.velocity ?? 0),
+	};
+	const transform = TRANSFORMS[key];
+	if (transform) beginTransform(element, key);
+	const animation = channel.native
+		? waapiAnimation({
+				...config,
+				element,
+				property: transform?.property ?? key,
+				format: (frame) =>
+					transform
+						? transform.alone(withUnit(key, frame))
+						: withUnit(key, frame),
+				composite: transform ? "add" : "replace",
+				commit: channel.write,
+			})
+		: (scripted as ScriptedChannel)({ ...config, apply: channel.write });
+	animations.set(key, animation);
+	animation.finished.then(() => {
+		if (animations.get(key) === animation) animations.delete(key);
+	});
+	return animation;
+}
+
+/** Every key of every element, each its own animation, under one set of controls. */
+export function animateElements(
+	elements: readonly Element[],
+	keyframes: DOMKeyframes,
+	options: AnimationOptions,
+	scripted?: ScriptedChannel,
+): AnimationControls {
+	const { delay } = options;
+	return groupControls(
+		elements.flatMap((element, index) => {
+			const start =
+				typeof delay === "function"
+					? delay(index, elements.length)
+					: (delay ?? 0);
+			return Object.entries(keyframes).map(([key, value]) =>
+				animateChannel(element, key, value, options, start, scripted),
+			);
+		}),
+	);
+}

package/src/animate/js-animation.ts

@@ -0,0 +1,151 @@
+import { thenable } from "#/animate/controls.ts";
+import { iterationTime, planGenerator, totalDuration } from "#/animate/plan.ts";
+import type {
+	AnimationControls,
+	AnimationOptions,
+	AnimationState,
+} from "#/animate/types.ts";
+import { cancelFrame, type FrameData, frame, now } from "#/frame/frame.ts";
+import { mix } from "#/interpolate/mix.ts";
+
+export interface JsAnimationConfig<T> {
+	/** At least two: the caller resolves a lone target against the current value. */
+	readonly keyframes: readonly T[];
+	readonly options: AnimationOptions;
+	/** Seconds. */
+	readonly delay: number;
+	/** The velocity the value has now, carried into a spring. */
+	readonly velocity: number;
+	apply(value: T): void;
+	onComplete?(): void;
+}
+
+export interface JsAnimation<T> extends AnimationControls {
+	/** The value and velocity at the current time: where an interruption starts from. */
+	current(): { readonly value: T; readonly velocity: number };
+}
+
+/**
+ * An animation stepped by the frame loop: plain values, objects, SVG
+ * attributes and CSS variables — whatever the Web Animations API can't play.
+ */
+export function jsAnimation<T>(config: JsAnimationConfig<T>): JsAnimation<T> {
+	const { keyframes, options, delay, apply } = config;
+	const { generator, positional } = planGenerator(
+		keyframes,
+		options,
+		config.velocity,
+	);
+	const segments = positional
+		? keyframes.slice(1).map((to, index) => mix(keyframes[index] as T, to as T))
+		: [];
+	const active = totalDuration(generator.duration, options);
+	const duration = delay + active;
+	const endsReversed =
+		options.repeatType === "reverse" && (options.repeat ?? 0) % 2 === 1;
+	const last = keyframes[endsReversed ? 0 : keyframes.length - 1] as T;
+
+	let time = 0;
+	let speed = 1;
+	let state: AnimationState = "running";
+	let previous = now();
+	let resolve: () => void = () => {};
+	const finished = new Promise<void>((done) => {
+		resolve = done;
+	});
+
+	function valueAt(position: number): T {
+		if (!positional) return position as T;
+		const index = Math.min(
+			Math.max(Math.floor(position), 0),
+			segments.length - 1,
+		);
+		return (segments[index] as (progress: number) => T)(position - index);
+	}
+
+	function sample() {
+		const elapsed = Math.max(0, time - delay);
+		return generator.at(iterationTime(elapsed, generator.duration, options));
+	}
+
+	function render() {
+		if (time < delay) return;
+		apply(time >= duration ? last : valueAt(sample().value));
+	}
+
+	function settle(next: AnimationState) {
+		state = next;
+		cancelFrame(tick);
+		resolve();
+	}
+
+	function tick(data: FrameData) {
+		time = Math.max(0, time + ((data.timestamp - previous) / 1000) * speed);
+		previous = data.timestamp;
+		if (time < duration) {
+			render();
+			return;
+		}
+		time = duration;
+		render();
+		settle("finished");
+		config.onComplete?.();
+	}
+
+	function play() {
+		if (state === "running") return;
+		previous = now();
+		state = "running";
+		frame.update(tick, true);
+	}
+
+	frame.update(tick, true);
+	render();
+
+	return {
+		...thenable(finished),
+		get time() {
+			return time;
+		},
+		set time(seconds) {
+			time = Math.min(Math.max(seconds, 0), duration);
+			render();
+		},
+		get speed() {
+			return speed;
+		},
+		set speed(rate) {
+			speed = rate;
+		},
+		duration,
+		get state() {
+			return state;
+		},
+		play,
+		pause() {
+			if (state !== "running") return;
+			state = "paused";
+			cancelFrame(tick);
+		},
+		stop: () => settle("finished"),
+		cancel() {
+			apply(keyframes[0] as T);
+			settle("finished");
+		},
+		complete() {
+			if (state === "finished") return;
+			time = duration;
+			render();
+			settle("finished");
+			config.onComplete?.();
+		},
+		attachTimeline: () => false,
+		current() {
+			const { value, velocity } = sample();
+			return {
+				value: time < delay ? (keyframes[0] as T) : valueAt(value),
+				velocity: positional || time < delay ? 0 : velocity,
+			};
+		},
+	};
+}

package/src/animate/plan.ts

@@ -0,0 +1,74 @@
+import type { AnimationOptions } from "#/animate/types.ts";
+import { spring } from "#/generators/spring.ts";
+import { tween } from "#/generators/tween.ts";
+import type { Generator } from "#/generators/types.ts";
+
+const DEFAULT_TWEEN_DURATION = 0.3;
+
+/**
+ * The motion of one channel, as a generator. Two numbers spring in their own
+ * units, so the velocity a value already has carries into the new motion.
+ * Anything else (colours, paths, several keyframes) moves a position along
+ * the keyframe list — 0 at the first, 1 at the second… — and the caller mixes
+ * the keyframes at that position.
+ */
+export function planGenerator(
+	keyframes: readonly unknown[],
+	options: AnimationOptions,
+	velocity = 0,
+): { readonly generator: Generator; readonly positional: boolean } {
+	const numeric = keyframes.every((frame) => typeof frame === "number");
+	const springs =
+		options.type !== "tween" && keyframes.length === 2 && !options.ease;
+	if (numeric) {
+		const values = keyframes as readonly number[];
+		const generator = springs
+			? spring({
+					...options,
+					from: values[0] ?? 0,
+					to: values[1] ?? 0,
+					velocity: options.velocity ?? velocity,
+				})
+			: tween({
+					keyframes: values,
+					duration: options.duration ?? DEFAULT_TWEEN_DURATION,
+					ease: options.ease,
+					times: options.times,
+				});
+		return { generator, positional: false };
+	}
+	const positions = keyframes.map((_frame, index) => index);
+	const generator = springs
+		? spring({ ...options, from: 0, to: 1 })
+		: tween({
+				keyframes: positions,
+				duration: options.duration ?? DEFAULT_TWEEN_DURATION,
+				ease: options.ease,
+				times: options.times,
+			});
+	return { generator, positional: true };
+}
+
+/** The elapsed time within the current repetition, playing backwards on odd ones when they reverse. */
+export function iterationTime(
+	elapsed: number,
+	duration: number,
+	options: AnimationOptions,
+): number {
+	const repeat = options.repeat ?? 0;
+	if (repeat === 0 || duration === 0) return Math.min(elapsed, duration);
+	const total = duration * (repeat + 1);
+	const clamped = Math.min(elapsed, total);
+	const iteration = Math.min(Math.floor(clamped / duration), repeat);
+	const within = clamped - iteration * duration;
+	return options.repeatType === "reverse" && iteration % 2 === 1
+		? duration - within
+		: within;
+}
+
+export function totalDuration(
+	duration: number,
+	options: AnimationOptions,
+): number {
+	return duration * ((options.repeat ?? 0) + 1);
+}

package/src/animate/style.ts

@@ -0,0 +1,131 @@
+import type { KeyframeValue } from "#/animate/types.ts";
+
+type TransformProperty = "translate" | "scale" | "rotate";
+
+interface TransformChannel {
+	readonly property: TransformProperty;
+	readonly unit: string;
+	readonly identity: number;
+	/** The channel alone as a value of its property, the other axes at identity. */
+	readonly alone: (value: string) => string;
+}
+
+/**
+ * The independent transforms. Each animates its CSS property alone with
+ * `composite: "add"`, so `x` and `y` run as two compositor animations that
+ * sum, and one can be interrupted without touching the other.
+ */
+export const TRANSFORMS: Readonly<Record<string, TransformChannel>> = {
+	x: { property: "translate", unit: "px", identity: 0, alone: (v) => `${v}` },
+	y: {
+		property: "translate",
+		unit: "px",
+		identity: 0,
+		alone: (v) => `0px ${v}`,
+	},
+	z: {
+		property: "translate",
+		unit: "px",
+		identity: 0,
+		alone: (v) => `0px 0px ${v}`,
+	},
+	scale: { property: "scale", unit: "", identity: 1, alone: (v) => `${v}` },
+	scaleX: { property: "scale", unit: "", identity: 1, alone: (v) => `${v} 1` },
+	scaleY: { property: "scale", unit: "", identity: 1, alone: (v) => `1 ${v}` },
+	rotate: {
+		property: "rotate",
+		unit: "deg",
+		identity: 0,
+		alone: (v) => `${v}`,
+	},
+};
+
+const UNITLESS = new Set([
+	"opacity",
+	"zIndex",
+	"fontWeight",
+	"lineHeight",
+	"flexGrow",
+	"flexShrink",
+	"order",
+	"fillOpacity",
+	"strokeOpacity",
+	"strokeMiterlimit",
+	"aspectRatio",
+	"pathLength",
+]);
+
+/** A keyframe as CSS: numbers take the property's unit. */
+export function withUnit(key: string, value: KeyframeValue): string {
+	if (typeof value === "string") return value;
+	const unit =
+		TRANSFORMS[key]?.unit ??
+		(UNITLESS.has(key) || key.startsWith("--") ? "" : "px");
+	return `${value}${unit}`;
+}
+
+/** Committed transform values per element, the ones no animation is driving. */
+const committed = new WeakMap<Element, Map<string, KeyframeValue>>();
+const animating = new WeakMap<Element, Set<string>>();
+
+function entries<T>(
+	map: WeakMap<Element, T>,
+	element: Element,
+	fresh: () => T,
+) {
+	const existing = map.get(element);
+	if (existing) return existing;
+	const created = fresh();
+	map.set(element, created);
+	return created;
+}
+
+export function committedTransform(element: Element, key: string): number {
+	const value = committed.get(element)?.get(key);
+	return typeof value === "number"
+		? value
+		: Number.parseFloat(value ?? "") || (TRANSFORMS[key]?.identity ?? 0);
+}
+
+function channel(element: Element, key: string): string {
+	const channelDef = TRANSFORMS[key] as TransformChannel;
+	if (animating.get(element)?.has(key))
+		return `${channelDef.identity}${channelDef.unit}`;
+	return withUnit(key, committed.get(element)?.get(key) ?? channelDef.identity);
+}
+
+/** Writes the committed transforms inline, with every animating channel at its identity. */
+export function writeTransforms(element: Element) {
+	const style = (element as HTMLElement).style;
+	const at = (key: string) => channel(element, key);
+	style.translate = `${at("x")} ${at("y")} ${at("z")}`;
+	const uniform = Number.parseFloat(at("scale"));
+	style.scale = `${uniform * Number.parseFloat(at("scaleX"))} ${uniform * Number.parseFloat(at("scaleY"))}`;
+	style.rotate = at("rotate");
+}
+
+export function beginTransform(element: Element, key: string) {
+	entries(animating, element, () => new Set()).add(key);
+	writeTransforms(element);
+}
+
+export function commitTransform(
+	element: Element,
+	key: string,
+	value: KeyframeValue,
+) {
+	entries(committed, element, () => new Map()).set(key, value);
+	animating.get(element)?.delete(key);
+	writeTransforms(element);
+}
+
+export function cssName(key: string): string {
+	return key.startsWith("--")
+		? key
+		: key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+
+/** Moves things on screen, as opposed to fading or tinting them: what reduced motion turns off. */
+export function isMovement(key: string): boolean {
+	return !/opacity|color|fill|stroke$|filter/i.test(key);
+}

package/src/animate/types.ts

@@ -0,0 +1,69 @@
+import type { ReducedMotionPolicy } from "#/accessibility/reduced-motion.ts";
+import type { EasingDefinition } from "#/easing/types.ts";
+import type { SpringOptions } from "#/generators/types.ts";
+
+export type Delay = number | ((index: number, total: number) => number);
+
+export interface AnimationOptions extends SpringOptions {
+	/**
+	 * "spring" by default for two numeric keyframes, "tween" otherwise. A tween
+	 * lasts `duration` seconds (0.3 by default); a spring's `duration` is its
+	 * perceived duration.
+	 */
+	readonly type?: "spring" | "tween";
+	readonly delay?: Delay;
+	readonly ease?: EasingDefinition | readonly EasingDefinition[];
+	/** Where each keyframe sits, 0 to 1, for a tween over several keyframes. */
+	readonly times?: readonly number[];
+	readonly repeat?: number;
+	readonly repeatType?: "loop" | "reverse";
+	/** Units per second, for a spring. Defaults to the velocity the value already has. */
+	readonly velocity?: number;
+	/** Overrides the global policy for this animation. */
+	readonly reducedMotion?: ReducedMotionPolicy;
+}
+
+export interface ValueAnimationOptions<T> extends AnimationOptions {
+	readonly onUpdate?: (value: T) => void;
+	readonly onComplete?: () => void;
+}
+
+export type AnimationState = "running" | "paused" | "finished";
+
+/**
+ * What every `animate` call returns, whatever drives it. Awaitable: it
+ * resolves when the animation finishes, is stopped or is cancelled.
+ */
+export interface AnimationControls extends PromiseLike<void> {
+	readonly finished: Promise<void>;
+	/** Seconds since the start, delay included. Settable to scrub. */
+	time: number;
+	speed: number;
+	/** Seconds from the start to the end, delay included. */
+	readonly duration: number;
+	readonly state: AnimationState;
+	play(): void;
+	pause(): void;
+	/** Stops where it is: the value stays as painted. */
+	stop(): void;
+	/** Stops and goes back to where it started. */
+	cancel(): void;
+	/** Jumps to the end. */
+	complete(): void;
+	/** Lets a native scroll or view timeline drive it; false when part of it runs in JavaScript. */
+	attachTimeline(timeline: AnimationTimeline): boolean;
+}
+
+export type KeyframeValue = number | string;
+export type Keyframes<T = KeyframeValue> = T | readonly T[];
+
+/**
+ * DOM keyframes: any CSS property (camelCase), a CSS variable (`--name`),
+ * the independent transforms (`x`, `y`, `z`, `scale`, `scaleX`, `scaleY`,
+ * `rotate`), or an SVG attribute. A single value animates from the current
+ * one; an array lists every keyframe. Numbers take the property's unit (px,
+ * deg) when it has one.
+ */
+export type DOMKeyframes = Readonly<Record<string, Keyframes>>;
+
+export type ElementTarget = Element | string | ArrayLike<Element>;