@voila.dev/motion 0.0.0-stage → 5.0.113

package/src/react/use-transform.ts

@@ -0,0 +1,73 @@
+import * as React from "react";
+import {
+	type InterpolateOptions,
+	interpolate,
+} from "#/interpolate/interpolate.ts";
+import { type MotionValue, motionValue } from "#/value/motion-value.ts";
+
+/**
+ * A motion value derived from others: mapped from an input range to an
+ * output range, or computed by a function. It updates with its sources,
+ * without re-rendering the component.
+ */
+export function useTransform<T>(
+	source: MotionValue<number>,
+	input: readonly number[],
+	output: readonly T[],
+	options?: InterpolateOptions<T>,
+): MotionValue<T>;
+export function useTransform<S, T>(
+	source: MotionValue<S>,
+	compute: (value: S) => T,
+): MotionValue<T>;
+export function useTransform<V extends readonly unknown[], T>(
+	sources: { readonly [K in keyof V]: MotionValue<V[K]> },
+	compute: (...values: V) => T,
+): MotionValue<T>;
+export function useTransform(...args: unknown[]): MotionValue<unknown> {
+	const [source, second, output, options] = args;
+	const sources = (
+		Array.isArray(source) ? source : [source]
+	) as MotionValue<unknown>[];
+	// Ranges are usually inline arrays: rebuild the mapping when their contents change, not their identity.
+	const ranges =
+		typeof second === "function" ? "" : JSON.stringify([second, output]);
+	// biome-ignore lint/correctness/useExhaustiveDependencies: keyed on the ranges' contents.
+	const map = React.useMemo(
+		() =>
+			typeof second === "function"
+				? undefined
+				: interpolate(
+						second as readonly number[],
+						output as readonly unknown[],
+						options as InterpolateOptions<unknown>,
+					),
+		[ranges],
+	);
+	const compute = (map ?? second) as (...values: unknown[]) => unknown;
+	const latest = React.useRef(compute);
+	latest.current = compute;
+	function read(): unknown {
+		return latest.current(...sources.map((one) => one.get()));
+	}
+	// biome-ignore lint/correctness/useExhaustiveDependencies: rebuilt only when a source changes.
+	const derived = React.useMemo(() => motionValue(read()), sources);
+	// Rendered with new ranges or a new function: the value follows at once.
+	const computed = React.useRef(compute);
+	if (computed.current !== compute) {
+		computed.current = compute;
+		derived.set(read());
+	}
+	// Subscribed in an effect, so StrictMode's unmount and remount leave it listening.
+	// biome-ignore lint/correctness/useExhaustiveDependencies: the sources are the identity of `derived`.
+	React.useEffect(() => {
+		derived.set(read());
+		const unsubscribes = sources.map((one) =>
+			one.on("change", () => derived.set(read())),
+		);
+		return () => {
+			for (const unsubscribe of unsubscribes) unsubscribe();
+		};
+	}, [derived]);
+	return derived;
+}

package/src/sequence/sequence.ts

@@ -0,0 +1,129 @@
+import { groupControls, thenable } from "#/animate/controls.ts";
+import type {
+	AnimationControls,
+	AnimationOptions,
+	DOMKeyframes,
+	ElementTarget,
+	Keyframes,
+} from "#/animate/types.ts";
+import { now } from "#/frame/frame.ts";
+import type { MotionValue } from "#/value/motion-value.ts";
+
+/**
+ * When a segment starts: seconds from the start of the sequence, `"+0.1"` or
+ * `"-0.2"` from the end of the segment before, `"<"` with the segment before,
+ * or the name of a label.
+ */
+export type SequenceAt = number | `+${number}` | `-${number}` | "<" | string;
+
+export interface SegmentOptions extends AnimationOptions {
+	readonly at?: SequenceAt;
+}
+
+export type Segment =
+	| readonly [ElementTarget, DOMKeyframes, SegmentOptions?]
+	// biome-ignore lint/suspicious/noExplicitAny: a sequence mixes values of any type.
+	| readonly [MotionValue<any>, Keyframes<any>, SegmentOptions?]
+	| string
+	| { readonly name: string; readonly at?: SequenceAt };
+
+export type AnimateOne = (
+	target: unknown,
+	keyframes: unknown,
+	options: AnimationOptions,
+) => AnimationControls;
+
+export type ResolveTargets = (target: unknown) => readonly object[];
+
+function startOf(
+	at: SequenceAt | undefined,
+	cursor: number,
+	previousStart: number,
+	labels: ReadonlyMap<string, number>,
+): number {
+	if (at === undefined) return cursor;
+	if (typeof at === "number") return at;
+	if (at === "<") return previousStart;
+	if (/^[+-]/.test(at)) return Math.max(0, cursor + Number(at));
+	return labels.get(at) ?? cursor;
+}
+
+/**
+ * Launches every segment at once, each delayed to its place on the
+ * timeline, so the whole sequence shares one clock and can be scrubbed. A
+ * segment that animates a property an earlier segment already animates
+ * waits for that one to finish, then starts from where it left off.
+ */
+export function animateSequence(
+	segments: readonly Segment[],
+	options: AnimationOptions,
+	animateOne: AnimateOne,
+	resolveTargets: ResolveTargets,
+): AnimationControls {
+	const begun = now();
+	const labels = new Map<string, number>();
+	const busy = new Map<object, Map<string, Promise<void>>>();
+	const children: AnimationControls[] = [];
+	const waits: Promise<void>[] = [];
+	let cursor = 0;
+	let previousStart = 0;
+	for (const segment of segments) {
+		if (typeof segment === "string" || "name" in segment) {
+			const label = typeof segment === "string" ? { name: segment } : segment;
+			labels.set(label.name, startOf(label.at, cursor, previousStart, labels));
+			continue;
+		}
+		const [target, keyframes, own = {}] = segment as readonly [
+			unknown,
+			unknown,
+			SegmentOptions?,
+		];
+		const start = startOf(own.at, cursor, previousStart, labels);
+		const { delay } = own;
+		/** Launched late, a segment only waits for what is left of its delay. */
+		function optionsAt(elapsed: number): AnimationOptions {
+			const offset = start - elapsed;
+			return {
+				...options,
+				...own,
+				delay:
+					typeof delay === "function"
+						? (index, total) => Math.max(0, offset + delay(index, total))
+						: Math.max(0, offset + (delay ?? 0)),
+			};
+		}
+		const keys =
+			typeof keyframes === "object" &&
+			keyframes !== null &&
+			!Array.isArray(keyframes)
+				? Object.keys(keyframes)
+				: ["value"];
+		const targets = resolveTargets(target);
+		const before = targets.flatMap((one) =>
+			keys.flatMap((key) => busy.get(one)?.get(key) ?? []),
+		);
+		const launch = () =>
+			animateOne(target, keyframes, optionsAt((now() - begun) / 1000));
+		let finished: Promise<void>;
+		if (before.length === 0) {
+			const controls = launch();
+			children.push(controls);
+			finished = controls.finished;
+			cursor = Math.max(start, controls.duration);
+		} else {
+			finished = Promise.all(before).then(() => launch().finished);
+			waits.push(finished);
+		}
+		for (const one of targets) {
+			const byKey = busy.get(one) ?? new Map();
+			busy.set(one, byKey);
+			for (const key of keys) byKey.set(key, finished);
+		}
+		previousStart = start;
+	}
+	const group = groupControls(children);
+	const finished = Promise.all([group.finished, ...waits]).then(
+		() => undefined,
+	);
+	return Object.assign(group, thenable(finished));
+}

package/src/stagger/stagger.ts

@@ -0,0 +1,36 @@
+import { resolveEasing } from "#/easing/named.ts";
+import type { EasingDefinition } from "#/easing/types.ts";
+
+export interface StaggerOptions {
+	/** Seconds before the first one starts. */
+	readonly startDelay?: number;
+	/** Which one starts first; the others follow by their distance from it. */
+	readonly from?: "first" | "last" | "center" | number;
+	/** Spreads the delays along an easing instead of evenly. */
+	readonly ease?: EasingDefinition;
+}
+
+const ORIGINS: Record<"first" | "last" | "center", (total: number) => number> =
+	{
+		first: () => 0,
+		last: (total) => total - 1,
+		center: (total) => (total - 1) / 2,
+	};
+
+/** A `delay` for many targets: `gap` seconds between neighbours. */
+export function stagger(
+	gap = 0.1,
+	options: StaggerOptions = {},
+): (index: number, total: number) => number {
+	const { startDelay = 0, from = "first", ease } = options;
+	return (index, total) => {
+		const origin = typeof from === "number" ? from : ORIGINS[from](total);
+		const distance = Math.abs(index - origin);
+		if (ease === undefined) return startDelay + distance * gap;
+		const furthest = Math.max(origin, total - 1 - origin);
+		const spread = furthest * gap;
+		return furthest === 0
+			? startDelay
+			: startDelay + resolveEasing(ease)(distance / furthest) * spread;
+	};
+}

package/src/testing/browser-commands.d.ts

@@ -0,0 +1,11 @@
+import "vitest/browser";
+
+declare module "vitest/browser" {
+	interface BrowserCommands {
+		emulateMedia(media: {
+			readonly colorScheme?: "light" | "dark" | null;
+			readonly forcedColors?: "active" | "none" | null;
+			readonly reducedMotion?: "reduce" | "no-preference" | null;
+		}): Promise<void>;
+	}
+}

package/src/testing/manual-frames.ts

@@ -0,0 +1,49 @@
+import { setFrameDriver } from "#/frame/driver.ts";
+import { resetFrameLoop } from "#/frame/frame.ts";
+
+const FRAME = 1000 / 60;
+
+export interface ManualFrames {
+	/** Moves the clock by `ms`, running each 60 Hz frame it crosses while one is requested. */
+	advance(ms: number): void;
+	/** The clock, in milliseconds. */
+	time(): number;
+	/** Back to the browser's frames, with an empty loop. */
+	restore(): void;
+}
+
+/** Installs a clock the test steps by hand, starting at 0 with an empty loop. */
+export function manualFrames(): ManualFrames {
+	let time = 0;
+	let tick: ((timestamp: number) => void) | undefined;
+	resetFrameLoop();
+	setFrameDriver({
+		request(next) {
+			tick = next;
+		},
+		cancel() {
+			tick = undefined;
+		},
+		now: () => time,
+	});
+	return {
+		advance(ms) {
+			const end = time + ms;
+			// Frames land on the 60 Hz grid however the test slices its steps.
+			let frameAt = (Math.floor(time / FRAME + 1e-9) + 1) * FRAME;
+			while (frameAt <= end + 1e-9) {
+				time = frameAt;
+				const next = tick;
+				tick = undefined;
+				next?.(time);
+				frameAt += FRAME;
+			}
+			time = end;
+		},
+		time: () => time,
+		restore() {
+			resetFrameLoop();
+			setFrameDriver(undefined);
+		},
+	};
+}

package/src/value/motion-value.ts

@@ -0,0 +1,131 @@
+import { now } from "#/frame/frame.ts";
+
+export type MotionValueEvent =
+	| "change"
+	| "animationStart"
+	| "animationComplete"
+	| "animationCancel";
+
+/** What `animate()` hands a value it drives; `finished` lets the value announce the end. */
+export interface MotionValueAnimation {
+	stop(): void;
+	readonly finished?: PromiseLike<unknown>;
+}
+
+export interface MotionValue<T = number> {
+	get(): T;
+	/** Sets the value and tracks its velocity. */
+	set(value: T): void;
+	/** Sets the value with no velocity and stops any animation. */
+	jump(value: T): void;
+	/** Units per second; 0 for a non-number or a value left alone for 30 ms. */
+	getVelocity(): number;
+	getPrevious(): T | undefined;
+	on(event: "change", listener: (value: T) => void): () => void;
+	on(
+		event: Exclude<MotionValueEvent, "change">,
+		listener: () => void,
+	): () => void;
+	/** Stops the running animation (`animationCancel`), then `animationStart`. */
+	start(animation: MotionValueAnimation): void;
+	/** Stops the running animation, if any, with `animationCancel`. */
+	stop(): void;
+	isAnimating(): boolean;
+	destroy(): void;
+}
+
+const STALE_AFTER = 30;
+const values = new WeakSet<object>();
+
+export function isMotionValue(value: unknown): value is MotionValue<unknown> {
+	return typeof value === "object" && value !== null && values.has(value);
+}
+
+export function motionValue<T>(initial: T): MotionValue<T> {
+	let current = initial;
+	let updatedAt = now();
+	let last: T | undefined;
+	let previous: T | undefined;
+	let previousAt = updatedAt;
+	let animation: MotionValueAnimation | undefined;
+	const listeners = new Map<MotionValueEvent, Set<(value?: T) => void>>();
+
+	function emit(event: MotionValueEvent): void {
+		for (const listener of listeners.get(event) ?? []) listener(current);
+	}
+
+	function stop(): void {
+		const running = animation;
+		if (!running) return;
+		// Cleared first: the animation's own stop may call back into this value.
+		animation = undefined;
+		running.stop();
+		emit("animationCancel");
+	}
+
+	const value: MotionValue<T> = {
+		get: () => current,
+		set(next) {
+			const time = now();
+			// Two sets in one frame keep the previous frame's sample, so velocity
+			// spans real time instead of dividing by zero.
+			if (time !== updatedAt) {
+				previous = current;
+				previousAt = updatedAt;
+			}
+			last = current;
+			current = next;
+			updatedAt = time;
+			emit("change");
+		},
+		jump(next) {
+			stop();
+			last = current;
+			current = next;
+			previous = undefined;
+			updatedAt = now();
+			previousAt = updatedAt;
+			emit("change");
+		},
+		getVelocity() {
+			const elapsed = updatedAt - previousAt;
+			if (
+				typeof current !== "number" ||
+				typeof previous !== "number" ||
+				elapsed <= 0 ||
+				now() - updatedAt > STALE_AFTER
+			) {
+				return 0;
+			}
+			return ((current - previous) / elapsed) * 1000;
+		},
+		getPrevious: () => last,
+		// One implementation behind both overloads: a lifecycle listener ignores the argument.
+		on: ((event: MotionValueEvent, listener: (value?: T) => void) => {
+			const set = listeners.get(event) ?? new Set();
+			listeners.set(event, set);
+			set.add(listener);
+			return () => {
+				set.delete(listener);
+			};
+		}) as MotionValue<T>["on"],
+		start(next) {
+			stop();
+			animation = next;
+			emit("animationStart");
+			next.finished?.then(() => {
+				if (animation !== next) return;
+				animation = undefined;
+				emit("animationComplete");
+			});
+		},
+		stop,
+		isAnimating: () => animation !== undefined,
+		destroy() {
+			stop();
+			listeners.clear();
+		},
+	};
+	values.add(value);
+	return value;
+}

package/src/value/transform.ts

@@ -0,0 +1,61 @@
+import {
+	type InterpolateOptions,
+	interpolate,
+} from "#/interpolate/interpolate.ts";
+import { type MotionValue, motionValue } from "#/value/motion-value.ts";
+
+type Values<V extends readonly unknown[]> = {
+	readonly [K in keyof V]: MotionValue<V[K]>;
+};
+
+/**
+ * A value derived from others, recomputed on each of their changes:
+ * `transformValue(x, [0, 100], [1, 0])` maps through a range,
+ * `transformValue([x, y], (x, y) => Math.hypot(x, y))` combines. Its
+ * `destroy()` lets go of the sources.
+ */
+export function transformValue<T>(
+	source: MotionValue<number>,
+	input: readonly number[],
+	output: readonly T[],
+	options?: InterpolateOptions<T>,
+): MotionValue<T>;
+export function transformValue<S, T>(
+	source: MotionValue<S>,
+	compute: (value: S) => T,
+): MotionValue<T>;
+export function transformValue<V extends readonly unknown[], T>(
+	sources: Values<V>,
+	compute: (...values: V) => T,
+): MotionValue<T>;
+export function transformValue<T>(
+	sources: MotionValue<unknown> | readonly MotionValue<unknown>[],
+	inputOrCompute: readonly number[] | ((...values: never[]) => T),
+	output?: readonly T[],
+	options?: InterpolateOptions<T>,
+): MotionValue<T> {
+	const list: readonly MotionValue<unknown>[] = Array.isArray(sources)
+		? sources
+		: [sources as MotionValue<unknown>];
+	const compute =
+		typeof inputOrCompute === "function"
+			? (inputOrCompute as (...values: unknown[]) => T)
+			: mapThrough(interpolate(inputOrCompute, output ?? [], options));
+	function read(): T {
+		return compute(...list.map((source) => source.get()));
+	}
+	const derived = motionValue(read());
+	const unsubscribes = list.map((source) =>
+		source.on("change", () => derived.set(read())),
+	);
+	const destroy = derived.destroy;
+	derived.destroy = () => {
+		for (const unsubscribe of unsubscribes) unsubscribe();
+		destroy();
+	};
+	return derived;
+}
+
+function mapThrough<T>(map: (value: number) => T): (...values: unknown[]) => T {
+	return (value) => map(value as number);
+}

package/src/view/in-view.ts

@@ -0,0 +1,74 @@
+import { resolveElements } from "#/view/resolve-elements.ts";
+
+export type InViewAmount = "some" | "all" | number;
+
+export interface InViewOptions {
+	/** The scrolling ancestor to intersect with; the viewport by default. */
+	readonly root?: Element | Document;
+	/** Grows or shrinks the root's box, CSS margin syntax: "0px 0px -20% 0px". */
+	readonly margin?: string;
+	/** How much of the element must show: any pixel, all of it, or a fraction. */
+	readonly amount?: InViewAmount;
+}
+
+export type OnViewEnd = (entry: IntersectionObserverEntry) => void;
+export type OnViewStart = (
+	element: Element,
+	entry: IntersectionObserverEntry,
+) => undefined | OnViewEnd;
+
+const THRESHOLDS: Readonly<Record<"some" | "all", number>> = {
+	some: 0,
+	all: 1,
+};
+
+/**
+ * Calls `onStart` when an element comes into view. When it returns a
+ * function, that runs when the element leaves and `onStart` runs again on
+ * the next entry; otherwise the element fires once. Returns a function that
+ * stops observing.
+ */
+export function inView(
+	target: Element | string | readonly Element[],
+	onStart: OnViewStart,
+	options: InViewOptions = {},
+): () => void {
+	const elements = resolveElements(target);
+	if (elements.length === 0 || typeof IntersectionObserver === "undefined") {
+		return () => {};
+	}
+	const amount = options.amount ?? "some";
+	const threshold = typeof amount === "number" ? amount : THRESHOLDS[amount];
+	const active = new Map<Element, OnViewEnd>();
+
+	function onIntersect(entries: IntersectionObserverEntry[]) {
+		for (const entry of entries) {
+			// Chromium reports a fully visible box as 0.99… on fractional layouts.
+			const visible =
+				entry.isIntersecting && entry.intersectionRatio + 1e-3 >= threshold;
+			const onEnd = active.get(entry.target);
+			if (visible && onEnd === undefined) {
+				const next = onStart(entry.target, entry);
+				if (typeof next === "function") {
+					active.set(entry.target, next);
+				} else {
+					observer.unobserve(entry.target);
+				}
+			}
+			if (!visible && onEnd !== undefined) {
+				active.delete(entry.target);
+				onEnd(entry);
+			}
+		}
+	}
+
+	const observer = new IntersectionObserver(onIntersect, {
+		root: options.root,
+		rootMargin: options.margin,
+		threshold,
+	});
+	for (const element of elements) {
+		observer.observe(element);
+	}
+	return () => observer.disconnect();
+}

package/src/view/resize.ts

@@ -0,0 +1,101 @@
+import { resolveElements } from "#/view/resolve-elements.ts";
+
+export interface Size {
+	readonly width: number;
+	readonly height: number;
+}
+
+export type OnElementResize = (element: Element, size: Size) => void;
+export type OnWindowResize = (size: Size) => void;
+
+// One observer for every element on the page: a ResizeObserver per call
+// would multiply the browser's work by the number of animated elements.
+let observer: ResizeObserver | undefined;
+const elementListeners = new Map<Element, Set<OnElementResize>>();
+const windowListeners = new Set<OnWindowResize>();
+
+function boxSize(entry: ResizeObserverEntry): Size {
+	const box = entry.borderBoxSize?.[0];
+	return box
+		? { width: box.inlineSize, height: box.blockSize }
+		: { width: entry.contentRect.width, height: entry.contentRect.height };
+}
+
+function notifyElements(entries: ResizeObserverEntry[]) {
+	for (const entry of entries) {
+		const size = boxSize(entry);
+		for (const listener of elementListeners.get(entry.target) ?? []) {
+			listener(entry.target, size);
+		}
+	}
+}
+
+function notifyWindow() {
+	const size = { width: window.innerWidth, height: window.innerHeight };
+	for (const listener of windowListeners) {
+		listener(size);
+	}
+}
+
+function resizeWindow(onResize: OnWindowResize): () => void {
+	if (windowListeners.size === 0) {
+		window.addEventListener("resize", notifyWindow);
+	}
+	windowListeners.add(onResize);
+	return () => {
+		windowListeners.delete(onResize);
+		if (windowListeners.size === 0) {
+			window.removeEventListener("resize", notifyWindow);
+		}
+	};
+}
+
+function resizeElements(
+	target: Element | string | readonly Element[],
+	onResize: OnElementResize,
+): () => void {
+	if (typeof ResizeObserver === "undefined") {
+		return () => {};
+	}
+	observer ??= new ResizeObserver(notifyElements);
+	const elements = resolveElements(target);
+	for (const element of elements) {
+		const listeners = elementListeners.get(element) ?? new Set();
+		if (listeners.size === 0) {
+			elementListeners.set(element, listeners);
+			observer.observe(element);
+		}
+		listeners.add(onResize);
+	}
+	return () => {
+		for (const element of elements) {
+			const listeners = elementListeners.get(element);
+			listeners?.delete(onResize);
+			if (listeners?.size === 0) {
+				elementListeners.delete(element);
+				observer?.unobserve(element);
+			}
+		}
+	};
+}
+
+/**
+ * Calls back when an element's border box changes size, or when the window
+ * does. Returns a function that stops listening.
+ */
+export function resize(onResize: OnWindowResize): () => void;
+export function resize(
+	target: Element | string | readonly Element[],
+	onResize: OnElementResize,
+): () => void;
+export function resize(
+	targetOrListener: Element | string | readonly Element[] | OnWindowResize,
+	onResize?: OnElementResize,
+): () => void {
+	if (typeof targetOrListener === "function") {
+		return typeof window === "undefined"
+			? () => {}
+			: resizeWindow(targetOrListener);
+	}
+	return onResize ? resizeElements(targetOrListener, onResize) : () => {};
+}

package/src/view/resolve-elements.ts

@@ -0,0 +1,11 @@
+/** Elements named by a selector, a list or a single element. */
+export function resolveElements(
+	target: Element | string | readonly Element[],
+): readonly Element[] {
+	if (typeof target === "string") {
+		return typeof document === "undefined"
+			? []
+			: Array.from(document.querySelectorAll(target));
+	}
+	return "length" in target ? target : [target as Element];
+}