@voila.dev/motion 0.0.0-stage → 5.0.0

package/src/animate/value.ts

@@ -0,0 +1,93 @@
+import { shouldReduceMotion } from "#/accessibility/reduced-motion.ts";
+import { finishedControls, groupControls } from "#/animate/controls.ts";
+import { jsAnimation } from "#/animate/js-animation.ts";
+import type {
+	AnimationControls,
+	AnimationOptions,
+	Keyframes,
+	ValueAnimationOptions,
+} from "#/animate/types.ts";
+import { cancelFrame, frame } from "#/frame/frame.ts";
+import type { MotionValue } from "#/value/motion-value.ts";
+
+function startDelay(options: AnimationOptions): number {
+	return typeof options.delay === "function"
+		? options.delay(0, 1)
+		: (options.delay ?? 0);
+}
+
+/**
+ * A motion value towards a target on the frame loop. Whatever the value is
+ * doing now — mid-spring, dragged — is where the new animation starts, at
+ * the same speed.
+ */
+export function animateMotionValue<T>(
+	value: MotionValue<T>,
+	target: Keyframes<T>,
+	options: ValueAnimationOptions<T> = {},
+): AnimationControls {
+	const list: readonly T[] = Array.isArray(target) ? target : [target as T];
+	const keyframes = list.length > 1 ? list : [value.get(), list[0] as T];
+	const velocity = value.getVelocity();
+	value.stop();
+	if (shouldReduceMotion(options.reducedMotion)) {
+		value.jump(keyframes.at(-1) as T);
+		options.onUpdate?.(value.get());
+		options.onComplete?.();
+		return finishedControls();
+	}
+	const animation = jsAnimation({
+		keyframes,
+		options,
+		delay: startDelay(options),
+		velocity: list.length > 1 ? 0 : velocity,
+		apply(next: T) {
+			value.set(next);
+			options.onUpdate?.(next);
+		},
+		onComplete: options.onComplete,
+	});
+	value.start(animation);
+	return animation;
+}
+
+/** Each numeric or mixable key of a plain object, written back into the object. */
+export function animateObject<T extends object>(
+	object: T,
+	keyframes: { readonly [K in keyof T]?: Keyframes<T[K]> },
+	options: ValueAnimationOptions<T> = {},
+): AnimationControls {
+	const record = object as Record<string, unknown>;
+	const reduce = shouldReduceMotion(options.reducedMotion);
+	const controls = Object.entries(keyframes).map(([key, target]) => {
+		const list: readonly unknown[] = Array.isArray(target) ? target : [target];
+		const frames = list.length > 1 ? list : [record[key], list[0]];
+		if (reduce) {
+			record[key] = frames.at(-1);
+			return finishedControls();
+		}
+		return jsAnimation({
+			keyframes: frames,
+			options,
+			delay: startDelay(options),
+			velocity: 0,
+			apply(next) {
+				record[key] = next;
+			},
+		});
+	});
+	if (reduce) options.onUpdate?.(object);
+	// One update per frame for the whole object, after every key has moved.
+	const group = groupControls(controls);
+	const notify = options.onUpdate;
+	if (notify && !reduce) {
+		const each = () => notify(object);
+		frame.render(each, true);
+		group.finished.then(() => {
+			cancelFrame(each);
+			notify(object);
+		});
+	}
+	group.finished.then(() => options.onComplete?.());
+	return group;
+}

package/src/animate/waapi.ts

@@ -0,0 +1,212 @@
+import { thenable } from "#/animate/controls.ts";
+import type { JsAnimation } from "#/animate/js-animation.ts";
+import { iterationTime, planGenerator } from "#/animate/plan.ts";
+import { cssName } from "#/animate/style.ts";
+import type {
+	AnimationOptions,
+	AnimationState,
+	KeyframeValue,
+} from "#/animate/types.ts";
+import { linearEasing, supportsLinearEasing } from "#/easing/linear-css.ts";
+import { easingToCss, resolveEasing } from "#/easing/named.ts";
+import type { EasingDefinition } from "#/easing/types.ts";
+import type { Generator } from "#/generators/types.ts";
+
+export interface WaapiConfig {
+	readonly element: Element;
+	/** The CSS property the browser animates. */
+	readonly property: string;
+	readonly keyframes: readonly KeyframeValue[];
+	/** A keyframe as the property's CSS value. */
+	format(value: KeyframeValue): string;
+	readonly options: AnimationOptions;
+	readonly delay: number;
+	readonly velocity: number;
+	readonly composite: CompositeOperation;
+	/** Writes the value that stays once the animation is gone. */
+	commit(value: KeyframeValue): void;
+	onComplete?(): void;
+}
+
+const SAMPLE_STEP = 1 / 60;
+
+function cssEasing(definition: EasingDefinition, duration: number): string {
+	return (
+		easingToCss(definition) ?? linearEasing(resolveEasing(definition), duration)
+	);
+}
+
+/**
+ * The browser keyframes and easing. Two keyframes on a spring become one
+ * `linear()` easing sampled from the spring, so the compositor plays the
+ * exact curve. Without `linear()`, or when the spring starts and ends at the
+ * same value (a flick of velocity), the spring is sampled into keyframes.
+ */
+function browserKeyframes(
+	config: WaapiConfig,
+	generator: Generator,
+	positional: boolean,
+): { keyframes: Keyframe[]; easing: string } {
+	const { keyframes, format, property, options } = config;
+	const duration = generator.duration;
+	const [from, to] = keyframes;
+	const springs =
+		options.type !== "tween" && keyframes.length === 2 && !options.ease;
+	const span =
+		typeof from === "number" && typeof to === "number" ? to - from : 1;
+	if (springs && span !== 0 && supportsLinearEasing()) {
+		const progress = (t: number) => {
+			const { value } = generator.at(t * duration);
+			return positional ? value : (value - (from as number)) / span;
+		};
+		return {
+			keyframes: keyframes.map((frame) => ({ [property]: format(frame) })),
+			easing: linearEasing(progress, duration),
+		};
+	}
+	if (springs && !positional) {
+		const count = Math.max(2, Math.ceil(duration / SAMPLE_STEP) + 1);
+		return {
+			keyframes: Array.from({ length: count }, (_unused, index) => {
+				const offset = index / (count - 1);
+				return {
+					[property]: format(generator.at(offset * duration).value),
+					offset,
+				};
+			}),
+			easing: "linear",
+		};
+	}
+	const ease = options.ease ?? "easeOut";
+	return {
+		keyframes: keyframes.map((frame, index) => ({
+			[property]: format(frame),
+			offset: options.times?.[index] ?? index / (keyframes.length - 1),
+			easing: cssEasing(
+				Array.isArray(ease) && typeof ease[0] !== "number"
+					? ((ease as readonly EasingDefinition[])[index] ?? "linear")
+					: (ease as EasingDefinition),
+				duration,
+			),
+		})),
+		easing: "linear",
+	};
+}
+
+const STATES: Record<AnimationPlayState, AnimationState> = {
+	running: "running",
+	paused: "paused",
+	finished: "finished",
+	idle: "finished",
+};
+
+/** One CSS property of one element, played by the Web Animations API. */
+export function waapiAnimation(
+	config: WaapiConfig,
+): JsAnimation<KeyframeValue> {
+	const { element, keyframes, options, delay, commit } = config;
+	const { generator, positional } = planGenerator(
+		keyframes,
+		options,
+		config.velocity,
+	);
+	const iterations = (options.repeat ?? 0) + 1;
+	const { keyframes: frames, easing } = browserKeyframes(
+		config,
+		generator,
+		positional,
+	);
+	const animation = element.animate(frames, {
+		duration: generator.duration * 1000,
+		delay: delay * 1000,
+		iterations,
+		direction: options.repeatType === "reverse" ? "alternate" : "normal",
+		easing,
+		fill: "both",
+		composite: config.composite,
+	});
+	const last = keyframes[
+		options.repeatType === "reverse" && iterations % 2 === 0
+			? 0
+			: keyframes.length - 1
+	] as KeyframeValue;
+
+	let settled = false;
+	/** What stayed on screen when it settled: where a following animation starts. */
+	let held: KeyframeValue = keyframes[0] as KeyframeValue;
+	let resolve: () => void = () => {};
+	const finished = new Promise<void>((done) => {
+		resolve = done;
+	});
+
+	function current() {
+		if (settled) return { value: held, velocity: 0 };
+		const elapsed = (Number(animation.currentTime) || 0) / 1000 - delay;
+		if (elapsed <= 0)
+			return { value: keyframes[0] as KeyframeValue, velocity: 0 };
+		const state = generator.at(
+			iterationTime(elapsed, generator.duration, options),
+		);
+		if (!positional) return state;
+		// The browser mixes colours and strings itself: ask it what it painted.
+		const painted =
+			config.composite === "replace"
+				? getComputedStyle(element).getPropertyValue(cssName(config.property))
+				: "";
+		return { value: painted || last, velocity: 0 };
+	}
+
+	function settle(value: KeyframeValue | undefined) {
+		if (settled) return;
+		settled = true;
+		if (value !== undefined) {
+			held = value;
+			commit(value);
+		}
+		animation.cancel();
+		resolve();
+	}
+
+	animation.finished.then(
+		() => {
+			if (settled) return;
+			settle(last);
+			config.onComplete?.();
+		},
+		() => settle(undefined),
+	);
+
+	return {
+		...thenable(finished),
+		get time() {
+			return (Number(animation.currentTime) || 0) / 1000;
+		},
+		set time(seconds) {
+			animation.currentTime = seconds * 1000;
+		},
+		get speed() {
+			return animation.playbackRate;
+		},
+		set speed(rate) {
+			animation.playbackRate = rate;
+		},
+		duration: delay + generator.duration * iterations,
+		get state() {
+			return settled ? "finished" : STATES[animation.playState];
+		},
+		play: () => animation.play(),
+		pause: () => animation.pause(),
+		stop: () => settle(current().value),
+		cancel: () => settle(keyframes[0]),
+		// The browser refuses to finish an endless animation: settle on its last frame instead.
+		complete: () =>
+			iterations === Number.POSITIVE_INFINITY
+				? settle(last)
+				: animation.finish(),
+		attachTimeline(timeline) {
+			animation.timeline = timeline;
+			return true;
+		},
+		current,
+	};
+}

package/src/dom.ts

@@ -0,0 +1,35 @@
+import { animateElements } from "#/animate/dom.ts";
+import type {
+	AnimationControls,
+	AnimationOptions,
+	DOMKeyframes,
+	ElementTarget,
+} from "#/animate/types.ts";
+import { resolveElements } from "#/view/resolve-elements.ts";
+
+export type {
+	AnimationControls,
+	AnimationOptions,
+	DOMKeyframes,
+	ElementTarget,
+} from "#/animate/types.ts";
+export { spring } from "#/generators/spring.ts";
+export { stagger } from "#/stagger/stagger.ts";
+
+/**
+ * `animate` for elements only, every property played by the browser: CSS
+ * properties and the independent transforms, with springs as `linear()`.
+ * What it can't hand to the browser (SVG attributes, CSS variables) jumps to
+ * its last keyframe: use the full `animate` for those.
+ */
+export function animate(
+	target: ElementTarget,
+	keyframes: DOMKeyframes,
+	options: AnimationOptions = {},
+): AnimationControls {
+	return animateElements(
+		resolveElements(target as Element | string | readonly Element[]),
+		keyframes,
+		options,
+	);
+}

package/src/easing/cubic-bezier.ts

@@ -0,0 +1,64 @@
+import type { Easing } from "#/easing/types.ts";
+
+function linear(progress: number): number {
+	return progress;
+}
+
+/** One coordinate of the curve at parameter `t`, with P0 = 0 and P3 = 1. */
+function coordinate(t: number, p1: number, p2: number): number {
+	return ((1 - 3 * p2 + 3 * p1) * t + (3 * p2 - 6 * p1)) * t * t + 3 * p1 * t;
+}
+
+function slope(t: number, p1: number, p2: number): number {
+	return 3 * (1 - 3 * p2 + 3 * p1) * t * t + 2 * (3 * p2 - 6 * p1) * t + 3 * p1;
+}
+
+/** The curve's parameter whose x is `x`: Newton first, bisection when the slope flattens. */
+function solveT(x: number, x1: number, x2: number): number {
+	let t = x;
+	for (let iteration = 0; iteration < 8; iteration += 1) {
+		const error = coordinate(t, x1, x2) - x;
+		if (Math.abs(error) < 1e-7) {
+			return t;
+		}
+		const derivative = slope(t, x1, x2);
+		if (Math.abs(derivative) < 1e-6) {
+			break;
+		}
+		t -= error / derivative;
+	}
+	let low = 0;
+	let high = 1;
+	t = x;
+	for (let iteration = 0; iteration < 24; iteration += 1) {
+		const value = coordinate(t, x1, x2);
+		if (Math.abs(value - x) < 1e-7) {
+			return t;
+		}
+		if (value < x) {
+			low = t;
+		} else {
+			high = t;
+		}
+		t = (low + high) / 2;
+	}
+	return t;
+}
+
+/** CSS `cubic-bezier(x1, y1, x2, y2)` as a function. */
+export function cubicBezier(
+	x1: number,
+	y1: number,
+	x2: number,
+	y2: number,
+): Easing {
+	if (x1 === y1 && x2 === y2) {
+		return linear;
+	}
+	return function bezier(progress) {
+		if (progress <= 0 || progress >= 1) {
+			return progress <= 0 ? 0 : 1;
+		}
+		return coordinate(solveT(progress, x1, x2), y1, y2);
+	};
+}

package/src/easing/linear-css.ts

@@ -0,0 +1,41 @@
+import type { Easing } from "#/easing/types.ts";
+
+/** Past this many points the string grows with no visible gain. */
+const MAX_POINTS = 200;
+
+function round(value: number): string {
+	return String(Math.round(value * 10_000) / 10_000);
+}
+
+/**
+ * Any easing as a CSS `linear()` string, so the browser plays a spring or a
+ * custom curve off the main thread. `duration` and `step` are in seconds:
+ * longer motions need more points to stay smooth.
+ */
+export function linearEasing(
+	sample: Easing,
+	duration: number,
+	step = 0.01,
+): string {
+	const intervals = Math.min(
+		MAX_POINTS - 1,
+		Math.max(1, Math.ceil(duration / step)),
+	);
+	const points: string[] = [];
+	for (let index = 0; index <= intervals; index += 1) {
+		points.push(round(sample(index / intervals)));
+	}
+	return `linear(${points.join(", ")})`;
+}
+
+let supported: boolean | undefined;
+
+export function supportsLinearEasing(): boolean {
+	if (supported === undefined) {
+		if (typeof CSS === "undefined" || typeof CSS.supports !== "function") {
+			return false;
+		}
+		supported = CSS.supports("animation-timing-function", "linear(0, 1)");
+	}
+	return supported;
+}

package/src/easing/named.ts

@@ -0,0 +1,88 @@
+import { cubicBezier } from "#/easing/cubic-bezier.ts";
+import type {
+	CubicBezier,
+	Easing,
+	EasingDefinition,
+	EasingName,
+} from "#/easing/types.ts";
+
+function reverse(easing: Easing): Easing {
+	return (progress) => 1 - easing(1 - progress);
+}
+
+function mirror(easing: Easing): Easing {
+	return (progress) =>
+		progress <= 0.5
+			? easing(2 * progress) / 2
+			: (2 - easing(2 * (1 - progress))) / 2;
+}
+
+/** The named easings that are plain CSS curves, so WAAPI plays them natively. */
+const BEZIERS: Partial<Record<EasingName, CubicBezier>> = {
+	easeIn: [0.42, 0, 1, 1],
+	easeOut: [0, 0, 0.58, 1],
+	easeInOut: [0.42, 0, 0.58, 1],
+	backIn: [0.31, 0.01, 0.66, -0.59],
+	backOut: [0.33, 1.53, 0.69, 0.99],
+};
+
+export const linear: Easing = (progress) => progress;
+export const easeIn = cubicBezier(0.42, 0, 1, 1);
+export const easeOut = cubicBezier(0, 0, 0.58, 1);
+export const easeInOut = cubicBezier(0.42, 0, 0.58, 1);
+export const circIn: Easing = (progress) =>
+	1 - Math.sin(Math.acos(Math.min(1, Math.max(0, progress))));
+export const circOut = reverse(circIn);
+export const circInOut = mirror(circIn);
+export const backIn = cubicBezier(0.31, 0.01, 0.66, -0.59);
+export const backOut = cubicBezier(0.33, 1.53, 0.69, 0.99);
+export const backInOut = mirror(backIn);
+export const anticipate: Easing = (progress) => {
+	const doubled = progress * 2;
+	return doubled < 1
+		? 0.5 * backIn(doubled)
+		: 0.5 * (2 - 2 ** (-10 * (doubled - 1)));
+};
+
+const NAMED: Record<EasingName, Easing> = {
+	linear,
+	easeIn,
+	easeOut,
+	easeInOut,
+	circIn,
+	circOut,
+	circInOut,
+	backIn,
+	backOut,
+	backInOut,
+	anticipate,
+};
+
+export function resolveEasing(definition: EasingDefinition): Easing {
+	if (typeof definition === "function") {
+		return definition;
+	}
+	if (typeof definition === "string") {
+		return NAMED[definition];
+	}
+	return cubicBezier(...definition);
+}
+
+function bezierCss([x1, y1, x2, y2]: CubicBezier): string {
+	return `cubic-bezier(${x1}, ${y1}, ${x2}, ${y2})`;
+}
+
+/** A CSS `<easing-function>` for the definition, or undefined when only sampling can express it. */
+export function easingToCss(definition: EasingDefinition): string | undefined {
+	if (typeof definition === "function") {
+		return undefined;
+	}
+	if (typeof definition !== "string") {
+		return bezierCss(definition);
+	}
+	if (definition === "linear") {
+		return "linear";
+	}
+	const bezier = BEZIERS[definition];
+	return bezier === undefined ? undefined : bezierCss(bezier);
+}

package/src/easing/spring.ts

@@ -0,0 +1,25 @@
+import { linearEasing } from "#/easing/linear-css.ts";
+import type { Easing } from "#/easing/types.ts";
+import { spring } from "#/generators/spring.ts";
+import type { SpringOptions } from "#/generators/types.ts";
+
+export interface SpringEasing {
+	/** Seconds until the spring settles: the WAAPI duration to play `easing` over. */
+	readonly duration: number;
+	readonly easing: string;
+	readonly at: Easing;
+}
+
+/** A spring from 0 to 1 as an easing: what WAAPI plays for a DOM spring. */
+export function springEasing(options: SpringOptions = {}): SpringEasing {
+	const generator = spring({ ...options, from: 0, to: 1 });
+	const duration = generator.duration;
+	function at(progress: number): number {
+		return generator.at(progress * duration).value;
+	}
+	return {
+		duration,
+		easing: duration > 0 ? linearEasing(at, duration) : "linear(0, 1)",
+		at,
+	};
+}

package/src/easing/steps.ts

@@ -0,0 +1,16 @@
+import type { Easing } from "#/easing/types.ts";
+
+/** CSS `steps(count, jump-start | jump-end)`. */
+export function steps(
+	count: number,
+	direction: "start" | "end" = "end",
+): Easing {
+	const jump = direction === "start" ? 1 : 0;
+	return function stepped(progress) {
+		if (progress >= 1) {
+			return 1;
+		}
+		const clamped = Math.max(0, progress);
+		return Math.min(1, (Math.floor(clamped * count) + jump) / count);
+	};
+}

package/src/easing/types.ts

@@ -0,0 +1,18 @@
+export type Easing = (progress: number) => number;
+
+export type CubicBezier = readonly [number, number, number, number];
+
+export type EasingName =
+	| "linear"
+	| "easeIn"
+	| "easeOut"
+	| "easeInOut"
+	| "circIn"
+	| "circOut"
+	| "circInOut"
+	| "backIn"
+	| "backOut"
+	| "backInOut"
+	| "anticipate";
+
+export type EasingDefinition = EasingName | CubicBezier | Easing;

package/src/frame/driver.ts

@@ -0,0 +1,56 @@
+/** What ticks the frame loop: the browser's frames by default, a test clock when injected. */
+export interface FrameDriver {
+	request(tick: (timestamp: number) => void): void;
+	cancel(): void;
+	/** Milliseconds, on the same clock as the timestamps handed to `tick`. */
+	now(): number;
+}
+
+function clock(): number {
+	return typeof performance === "undefined" ? Date.now() : performance.now();
+}
+
+/** Read lazily so importing on the server never touches the browser globals. */
+function browserDriver(): FrameDriver {
+	let handle: number | ReturnType<typeof setTimeout> | undefined;
+	const hasAnimationFrame = typeof requestAnimationFrame === "function";
+	return {
+		request(tick) {
+			handle = hasAnimationFrame
+				? requestAnimationFrame(tick)
+				: setTimeout(() => tick(clock()), 1000 / 60);
+		},
+		cancel() {
+			if (handle === undefined) return;
+			if (hasAnimationFrame) cancelAnimationFrame(handle as number);
+			else clearTimeout(handle);
+			handle = undefined;
+		},
+		now: clock,
+	};
+}
+
+let injected: FrameDriver | undefined;
+let fallback: FrameDriver | undefined;
+const driverListeners = new Set<(previous: FrameDriver) => void>();
+
+export function frameDriver(): FrameDriver {
+	if (injected) return injected;
+	fallback ??= browserDriver();
+	return fallback;
+}
+
+/** `undefined` restores the browser's frames. */
+export function setFrameDriver(driver: FrameDriver | undefined): void {
+	const previous = frameDriver();
+	injected = driver;
+	for (const listener of driverListeners) listener(previous);
+}
+
+/** The loop listens so a driver swapped mid-animation carries the pending frame over. */
+export function onFrameDriverChange(
+	listener: (previous: FrameDriver) => void,
+): () => void {
+	driverListeners.add(listener);
+	return () => driverListeners.delete(listener);
+}