@voila.dev/motion 0.0.0-stage → 5.0.0

package/src/frame/frame.ts

@@ -0,0 +1,102 @@
+import { frameDriver, onFrameDriverChange } from "#/frame/driver.ts";
+
+export interface FrameData {
+	/** Milliseconds since the previous frame, clamped so a backgrounded tab does not teleport. */
+	readonly delta: number;
+	readonly timestamp: number;
+}
+
+export type FrameCallback = (data: FrameData) => void;
+
+type Schedule = (callback: FrameCallback, keepAlive?: boolean) => FrameCallback;
+
+const PHASES = ["read", "update", "render"] as const;
+const IDEAL_DELTA = 1000 / 60;
+const MAX_DELTA = 40;
+
+let pending = PHASES.map(() => new Set<FrameCallback>());
+let running: Set<FrameCallback> | undefined;
+let keepAlive = new Set<FrameCallback>();
+let scheduled = false;
+let inFrame = false;
+let data: FrameData = { delta: IDEAL_DELTA, timestamp: 0 };
+let lastTimestamp: number | undefined;
+
+function request(): void {
+	if (scheduled) return;
+	scheduled = true;
+	frameDriver().request(tick);
+}
+
+function tick(timestamp: number): void {
+	scheduled = false;
+	const delta =
+		lastTimestamp === undefined
+			? IDEAL_DELTA
+			: Math.max(1, Math.min(timestamp - lastTimestamp, MAX_DELTA));
+	data = { delta, timestamp };
+	inFrame = true;
+	// Swapping each phase's set as it starts is what makes the scheduling rule
+	// hold: a later phase's set is still the one that will run, an earlier or
+	// the current phase's set is already the next frame's.
+	pending.forEach((_, index) => {
+		running = pending[index];
+		pending[index] = new Set();
+		for (const callback of running) {
+			callback(data);
+			if (keepAlive.has(callback)) pending[index].add(callback);
+		}
+	});
+	running = undefined;
+	inFrame = false;
+	const idle = pending.every((set) => set.size === 0);
+	lastTimestamp = idle ? undefined : timestamp;
+	if (!idle) request();
+}
+
+function schedule(phase: number): Schedule {
+	return (callback, alive = false) => {
+		if (alive) keepAlive.add(callback);
+		pending[phase].add(callback);
+		request();
+		return callback;
+	};
+}
+
+export const frame: {
+	readonly read: Schedule;
+	readonly update: Schedule;
+	readonly render: Schedule;
+} = { read: schedule(0), update: schedule(1), render: schedule(2) };
+
+export function cancelFrame(callback: FrameCallback): void {
+	keepAlive.delete(callback);
+	running?.delete(callback);
+	for (const set of pending) set.delete(callback);
+}
+
+export function frameData(): FrameData {
+	return data;
+}
+
+/** Milliseconds; inside a frame, that frame's timestamp, so every value read in it agrees. */
+export function now(): number {
+	return inFrame ? data.timestamp : frameDriver().now();
+}
+
+/** For tests: forget every callback and the frame clock. */
+export function resetFrameLoop(): void {
+	if (scheduled) frameDriver().cancel();
+	pending = PHASES.map(() => new Set<FrameCallback>());
+	keepAlive = new Set();
+	scheduled = false;
+	lastTimestamp = undefined;
+	data = { delta: IDEAL_DELTA, timestamp: 0 };
+}
+
+onFrameDriverChange((previous) => {
+	if (!scheduled) return;
+	previous.cancel();
+	scheduled = false;
+	request();
+});

package/src/generators/inertia.ts

@@ -0,0 +1,88 @@
+import { spring } from "#/generators/spring.ts";
+import type { Generator, GeneratorState } from "#/generators/types.ts";
+
+export interface InertiaOptions {
+	readonly from: number;
+	/** Units per second, typically a gesture's release velocity. */
+	readonly velocity: number;
+	/** How far the throw carries: target = from + power × velocity. */
+	readonly power?: number;
+	/** Seconds; higher glides longer. */
+	readonly timeConstant?: number;
+	readonly min?: number;
+	readonly max?: number;
+	readonly bounceStiffness?: number;
+	readonly bounceDamping?: number;
+	readonly restDelta?: number;
+	/** Snap the natural resting point, e.g. to a grid. */
+	readonly modifyTarget?: (target: number) => number;
+}
+
+/** The bound the value is past or heading past, if any. */
+function boundBeyond(value: number, min?: number, max?: number) {
+	if (min !== undefined && value < min) {
+		return min;
+	}
+	if (max !== undefined && value > max) {
+		return max;
+	}
+	return undefined;
+}
+
+/** A throw decaying exponentially, handing over to a spring when it hits `min` or `max`. */
+export function inertia(options: InertiaOptions): Generator {
+	const { from, velocity, min, max } = options;
+	const timeConstant = options.timeConstant ?? 0.325;
+	const restDelta = options.restDelta ?? 0.5;
+	function bounce(start: number, startVelocity: number, bound: number) {
+		return spring({
+			from: start,
+			to: bound,
+			velocity: startVelocity,
+			stiffness: options.bounceStiffness ?? 500,
+			damping: options.bounceDamping ?? 10,
+			restDelta,
+		});
+	}
+
+	const outside = boundBeyond(from, min, max);
+	if (outside !== undefined) {
+		return bounce(from, velocity, outside);
+	}
+
+	const ideal = from + (options.power ?? 0.8) * velocity;
+	const target = options.modifyTarget?.(ideal) ?? ideal;
+	const amplitude = target - from;
+	function decay(t: number): GeneratorState {
+		const remaining = amplitude * Math.exp(-t / timeConstant);
+		return {
+			value: target - remaining,
+			velocity: remaining / timeConstant,
+			done: false,
+		};
+	}
+	const settle =
+		Math.abs(amplitude) > restDelta
+			? timeConstant * Math.log(Math.abs(amplitude) / restDelta)
+			: 0;
+
+	const bound = boundBeyond(target, min, max);
+	if (bound === undefined) {
+		return {
+			duration: settle,
+			at: (elapsed) =>
+				elapsed >= settle
+					? { value: target, velocity: 0, done: true }
+					: decay(Math.max(0, elapsed)),
+		};
+	}
+
+	const hit = -timeConstant * Math.log((target - bound) / amplitude);
+	const atHit = decay(hit);
+	const handover = bounce(bound, atHit.velocity, bound);
+	return {
+		duration: hit + handover.duration,
+		at: (elapsed) =>
+			elapsed < hit ? decay(Math.max(0, elapsed)) : handover.at(elapsed - hit),
+	};
+}

package/src/generators/spring.ts

@@ -0,0 +1,117 @@
+import type {
+	Generator,
+	GeneratorState,
+	SpringOptions,
+} from "#/generators/types.ts";
+
+export interface SpringPhysics {
+	readonly stiffness: number;
+	readonly damping: number;
+	readonly mass: number;
+}
+
+/** A spring that never settles would animate forever: stop looking after this. */
+const MAX_DURATION = 20;
+const SETTLE_STEP = 0.005;
+
+/**
+ * Duration and bounce to physics, SwiftUI's mapping: the undamped period is
+ * the perceived duration, and the damping ratio is `1 - bounce`.
+ */
+export function springPhysics(options: SpringOptions = {}): SpringPhysics {
+	const { stiffness, damping, mass } = options;
+	if (stiffness !== undefined || damping !== undefined || mass !== undefined) {
+		return {
+			stiffness: stiffness ?? 100,
+			damping: damping ?? 10,
+			mass: mass ?? 1,
+		};
+	}
+	const duration = Math.max(options.duration ?? 0.3, 0.001);
+	const bounce = Math.min(Math.max(options.bounce ?? 0, 0), 0.95);
+	return {
+		stiffness: ((2 * Math.PI) / duration) ** 2,
+		damping: (4 * Math.PI * (1 - bounce)) / duration,
+		mass: 1,
+	};
+}
+
+type Displacement = (t: number) => readonly [number, number];
+
+/** The damped oscillator's closed form: displacement from the target and its velocity at `t`. */
+function oscillator(
+	physics: SpringPhysics,
+	x0: number,
+	v0: number,
+): Displacement {
+	const omega = Math.sqrt(physics.stiffness / physics.mass);
+	const zeta =
+		physics.damping / (2 * Math.sqrt(physics.stiffness * physics.mass));
+	if (Math.abs(zeta - 1) < 1e-6) {
+		const c = v0 + omega * x0;
+		return (t) => {
+			const decay = Math.exp(-omega * t);
+			return [decay * (x0 + c * t), decay * (c - omega * (x0 + c * t))];
+		};
+	}
+	if (zeta < 1) {
+		const omegaD = omega * Math.sqrt(1 - zeta * zeta);
+		const b = (v0 + zeta * omega * x0) / omegaD;
+		return (t) => {
+			const decay = Math.exp(-zeta * omega * t);
+			const cos = Math.cos(omegaD * t);
+			const sin = Math.sin(omegaD * t);
+			const x = x0 * cos + b * sin;
+			return [
+				decay * x,
+				decay * (-zeta * omega * x + omegaD * (b * cos - x0 * sin)),
+			];
+		};
+	}
+	const root = omega * Math.sqrt(zeta * zeta - 1);
+	const r1 = -zeta * omega + root;
+	const r2 = -zeta * omega - root;
+	const c2 = (v0 - r1 * x0) / (r2 - r1);
+	const c1 = x0 - c2;
+	return (t) => {
+		const e1 = c1 * Math.exp(r1 * t);
+		const e2 = c2 * Math.exp(r2 * t);
+		return [e1 + e2, r1 * e1 + r2 * e2];
+	};
+}
+
+/** Rest thresholds scale with the motion, so 0→1 and 0→1000 both settle to the eye. */
+function restThresholds(options: SpringOptions, span: number) {
+	const restDelta = options.restDelta ?? Math.max(span, 1) * 0.001;
+	return { restDelta, restSpeed: options.restSpeed ?? restDelta * 10 };
+}
+
+export function spring(
+	options: SpringOptions & { from: number; to: number; velocity?: number },
+): Generator {
+	const { from, to } = options;
+	const velocity = options.velocity ?? 0;
+	const displacement = oscillator(springPhysics(options), from - to, velocity);
+	const { restDelta, restSpeed } = restThresholds(options, Math.abs(to - from));
+
+	function atRest(t: number): boolean {
+		const [x, v] = displacement(t);
+		return Math.abs(x) <= restDelta && Math.abs(v) <= restSpeed;
+	}
+
+	let duration = 0;
+	while (duration < MAX_DURATION && !atRest(duration)) {
+		duration += SETTLE_STEP;
+	}
+
+	return {
+		duration,
+		at(elapsed): GeneratorState {
+			if (elapsed >= duration) {
+				return { value: to, velocity: 0, done: true };
+			}
+			const [x, v] = displacement(Math.max(0, elapsed));
+			return { value: to + x, velocity: v, done: false };
+		},
+	};
+}

package/src/generators/tween.ts

@@ -0,0 +1,74 @@
+import { easeOut, resolveEasing } from "#/easing/named.ts";
+import type { EasingDefinition } from "#/easing/types.ts";
+import type { Generator, GeneratorState } from "#/generators/types.ts";
+
+export interface TweenOptions {
+	readonly keyframes: readonly number[];
+	/** Seconds, default 0.3. */
+	readonly duration?: number;
+	/** One easing for every segment, or one per segment. */
+	readonly ease?: EasingDefinition | readonly EasingDefinition[];
+	/** Each keyframe's offset in 0..1, default evenly spaced. */
+	readonly times?: readonly number[];
+	/** A tween's shape is fixed by its easing; accepted so options pass through unchanged. */
+	readonly velocity?: number;
+}
+
+/** Window for the finite difference that reports velocity. */
+const VELOCITY_WINDOW = 0.005;
+
+function isEasingList(
+	ease: TweenOptions["ease"],
+): ease is readonly EasingDefinition[] {
+	return Array.isArray(ease) && typeof ease[0] !== "number";
+}
+
+export function tween(options: TweenOptions): Generator {
+	const { keyframes } = options;
+	const duration = Math.max(0, options.duration ?? 0.3);
+	const last = keyframes.length - 1;
+	const times =
+		options.times ??
+		keyframes.map((_unused, index) => (last === 0 ? 0 : index / last));
+	const eases = Array.from({ length: Math.max(last, 1) }, (_unused, index) => {
+		const ease = options.ease;
+		if (ease === undefined) {
+			return easeOut;
+		}
+		return resolveEasing(
+			isEasingList(ease)
+				? (ease[index] ?? ease[ease.length - 1] ?? "easeOut")
+				: ease,
+		);
+	});
+
+	function valueAt(elapsed: number): number {
+		const progress =
+			duration === 0 ? 1 : Math.min(1, Math.max(0, elapsed / duration));
+		let segment = 0;
+		while (segment < last - 1 && progress > (times[segment + 1] ?? 1)) {
+			segment += 1;
+		}
+		const start = times[segment] ?? 0;
+		const end = times[segment + 1] ?? 1;
+		const from = keyframes[segment] ?? 0;
+		const to = keyframes[segment + 1] ?? from;
+		const local = end === start ? 1 : (progress - start) / (end - start);
+		const eased = (eases[segment] ?? easeOut)(Math.min(1, Math.max(0, local)));
+		return from + (to - from) * eased;
+	}
+
+	return {
+		duration,
+		at(elapsed): GeneratorState {
+			if (elapsed >= duration) {
+				return { value: keyframes[last] ?? 0, velocity: 0, done: true };
+			}
+			const value = valueAt(elapsed);
+			const before = Math.max(0, elapsed - VELOCITY_WINDOW);
+			const after = before === elapsed ? elapsed + VELOCITY_WINDOW : elapsed;
+			const velocity = (valueAt(after) - valueAt(before)) / (after - before);
+			return { value, velocity, done: false };
+		},
+	};
+}

package/src/generators/types.ts

@@ -0,0 +1,31 @@
+export interface GeneratorState {
+	readonly value: number;
+	/** Units per second. */
+	readonly velocity: number;
+	readonly done: boolean;
+}
+
+/** One number moving over time: a spring, a tween or a decay. */
+export interface Generator {
+	/** Seconds until it settles. */
+	readonly duration: number;
+	/** The state `elapsed` seconds after the start. */
+	at(elapsed: number): GeneratorState;
+}
+
+export interface SpringOptions {
+	/**
+	 * Perceived duration in seconds, SwiftUI's model: how long the motion
+	 * looks like it takes, not when the last sub-pixel wobble ends. Ignored
+	 * when `stiffness`, `damping` or `mass` is given.
+	 */
+	readonly duration?: number;
+	/** 0 never overshoots; towards 1, springier. */
+	readonly bounce?: number;
+	readonly stiffness?: number;
+	readonly damping?: number;
+	readonly mass?: number;
+	/** Below this speed (units per second) and `restDelta`, the spring is done. */
+	readonly restSpeed?: number;
+	readonly restDelta?: number;
+}

package/src/index.ts

@@ -0,0 +1,91 @@
+export {
+	onReducedMotionChange,
+	prefersReducedMotion,
+	type ReducedMotionPolicy,
+	reducedMotionPolicy,
+	setReducedMotion,
+	shouldReduceMotion,
+} from "#/accessibility/reduced-motion.ts";
+export { type Animate, animate, createAnimate } from "#/animate/animate.ts";
+export type {
+	AnimationControls,
+	AnimationOptions,
+	AnimationState,
+	DOMKeyframes,
+	ElementTarget,
+	Keyframes,
+	ValueAnimationOptions,
+} from "#/animate/types.ts";
+export { cubicBezier } from "#/easing/cubic-bezier.ts";
+export { linearEasing } from "#/easing/linear-css.ts";
+export {
+	anticipate,
+	backIn,
+	backInOut,
+	backOut,
+	circIn,
+	circInOut,
+	circOut,
+	easeIn,
+	easeInOut,
+	easeOut,
+	linear,
+	resolveEasing,
+} from "#/easing/named.ts";
+export { type SpringEasing, springEasing } from "#/easing/spring.ts";
+export { steps } from "#/easing/steps.ts";
+export type {
+	CubicBezier,
+	Easing,
+	EasingDefinition,
+	EasingName,
+} from "#/easing/types.ts";
+export {
+	cancelFrame,
+	type FrameCallback,
+	type FrameData,
+	frame,
+	frameData,
+} from "#/frame/frame.ts";
+export { type InertiaOptions, inertia } from "#/generators/inertia.ts";
+export { spring, springPhysics } from "#/generators/spring.ts";
+export { type TweenOptions, tween } from "#/generators/tween.ts";
+export type {
+	Generator,
+	GeneratorState,
+	SpringOptions,
+} from "#/generators/types.ts";
+export { mixColor } from "#/interpolate/color.ts";
+export {
+	type InterpolateOptions,
+	interpolate,
+} from "#/interpolate/interpolate.ts";
+export { type Mixer, mix } from "#/interpolate/mix.ts";
+export { mixPath } from "#/interpolate/path/morph.ts";
+export type {
+	Segment,
+	SegmentOptions,
+	SequenceAt,
+} from "#/sequence/sequence.ts";
+export { type StaggerOptions, stagger } from "#/stagger/stagger.ts";
+export {
+	isMotionValue,
+	type MotionValue,
+	type MotionValueEvent,
+	motionValue,
+} from "#/value/motion-value.ts";
+export { transformValue } from "#/value/transform.ts";
+export {
+	type InViewOptions,
+	inView,
+	type OnViewEnd,
+	type OnViewStart,
+} from "#/view/in-view.ts";
+export { resize, type Size } from "#/view/resize.ts";
+export {
+	type OnScroll,
+	type ScrollDrivable,
+	type ScrollInfo,
+	type ScrollOptions,
+	scroll,
+} from "#/view/scroll.ts";

package/src/interpolate/array.ts

@@ -0,0 +1,13 @@
+import { mix } from "#/interpolate/mix.ts";
+
+/** Element by element; arrays of different lengths have no midpoint, so they step. */
+export function mixArray<T>(
+	from: readonly T[],
+	to: readonly T[],
+): ((progress: number) => T[]) | undefined {
+	if (from.length !== to.length) {
+		return undefined;
+	}
+	const mixers = from.map((value, index) => mix(value, to[index] as T));
+	return (progress) => mixers.map((mixer) => mixer(progress));
+}

package/src/interpolate/color-parse.ts

@@ -0,0 +1,136 @@
+/** A colour in sRGB, every channel 0–1. */
+export interface Rgba {
+	readonly r: number;
+	readonly g: number;
+	readonly b: number;
+	readonly alpha: number;
+}
+
+type Channels = readonly [number, number, number, number];
+type Parser = (args: readonly string[]) => Rgba | undefined;
+
+const FUNCTION = /^(rgba?|hsla?|oklch|oklab)\(\s*([^()]*)\)$/i;
+const HUE_UNITS: Readonly<Record<string, number>> = {
+	deg: 1,
+	grad: 0.9,
+	rad: 180 / Math.PI,
+	turn: 360,
+};
+
+/** A number, a percentage of `percentScale`, or `none`. */
+function channel(text: string | undefined, percentScale: number): number {
+	if (text === undefined || text === "none") {
+		return 0;
+	}
+	return text.endsWith("%")
+		? (Number.parseFloat(text) / 100) * percentScale
+		: Number.parseFloat(text);
+}
+
+function hue(text: string | undefined): number {
+	const unit = text?.match(/[a-z]+$/i)?.[0].toLowerCase() ?? "deg";
+	return channel(text, 1) * (HUE_UNITS[unit] ?? 1);
+}
+
+function alphaOf(args: readonly string[]): number {
+	return args[3] === undefined ? 1 : channel(args[3], 1);
+}
+
+function linearToSrgb(value: number): number {
+	return value <= 0.0031308
+		? 12.92 * value
+		: 1.055 * value ** (1 / 2.4) - 0.055;
+}
+
+/** Oklab is mixed in, and also a syntax a page can write colours in. */
+export function oklabToRgba([l, a, b, alpha]: Channels): Rgba {
+	const lms = [
+		(l + 0.3963377774 * a + 0.2158037573 * b) ** 3,
+		(l - 0.1055613458 * a - 0.0638541728 * b) ** 3,
+		(l - 0.0894841775 * a - 1.291485548 * b) ** 3,
+	] as const;
+	const [x, y, z] = lms;
+	return {
+		r: linearToSrgb(4.0767416621 * x - 3.3077115913 * y + 0.2309699292 * z),
+		g: linearToSrgb(-1.2684380046 * x + 2.6097574011 * y - 0.3413193965 * z),
+		b: linearToSrgb(-0.0041960863 * x - 0.7034186147 * y + 1.707614701 * z),
+		alpha,
+	};
+}
+
+function hslToRgba(h: number, s: number, l: number, alpha: number): Rgba {
+	const amount = s * Math.min(l, 1 - l);
+	function f(n: number) {
+		const k = (n + h / 30) % 12;
+		return l - amount * Math.max(-1, Math.min(k - 3, 9 - k, 1));
+	}
+	return { r: f(0), g: f(8), b: f(4), alpha };
+}
+
+const PARSERS: Readonly<Record<string, Parser>> = {
+	rgb: (args) => ({
+		r: channel(args[0], 255) / 255,
+		g: channel(args[1], 255) / 255,
+		b: channel(args[2], 255) / 255,
+		alpha: alphaOf(args),
+	}),
+	hsl: (args) =>
+		hslToRgba(
+			((hue(args[0]) % 360) + 360) % 360,
+			channel(args[1], 100) / 100,
+			channel(args[2], 100) / 100,
+			alphaOf(args),
+		),
+	oklab: (args) =>
+		oklabToRgba([
+			channel(args[0], 1),
+			channel(args[1], 0.4),
+			channel(args[2], 0.4),
+			alphaOf(args),
+		]),
+	oklch: (args) => {
+		const chroma = channel(args[1], 0.4);
+		const angle = (hue(args[2]) * Math.PI) / 180;
+		return oklabToRgba([
+			channel(args[0], 1),
+			chroma * Math.cos(angle),
+			chroma * Math.sin(angle),
+			alphaOf(args),
+		]);
+	},
+};
+
+function parseHex(hex: string): Rgba | undefined {
+	const digits =
+		hex.length <= 4 ? [...hex].map((digit) => digit + digit).join("") : hex;
+	if (!/^[0-9a-f]{6}(?:[0-9a-f]{2})?$/i.test(digits)) {
+		return undefined;
+	}
+	function byte(index: number) {
+		return Number.parseInt(digits.slice(index, index + 2), 16) / 255;
+	}
+	return {
+		r: byte(0),
+		g: byte(2),
+		b: byte(4),
+		alpha: digits.length === 8 ? byte(6) : 1,
+	};
+}
+
+/** A colour written out in full; `undefined` for what only the page can resolve (`var()`, names). */
+export function parseColor(text: string): Rgba | undefined {
+	const trimmed = text.trim();
+	if (trimmed.toLowerCase() === "transparent") {
+		return { r: 0, g: 0, b: 0, alpha: 0 };
+	}
+	if (trimmed.startsWith("#")) {
+		return parseHex(trimmed.slice(1));
+	}
+	const match = FUNCTION.exec(trimmed);
+	if (match === null) {
+		return undefined;
+	}
+	const name = (match[1] as string).toLowerCase().replace(/a$/, "");
+	const args = (match[2] as string).split(/[\s,/]+/).filter(Boolean);
+	return PARSERS[name]?.(args);
+}