@voila.dev/motion 0.0.0-stage → 5.0.113

package/src/interpolate/color.ts

@@ -0,0 +1,97 @@
+import {
+	oklabToRgba,
+	parseColor,
+	type Rgba,
+} from "#/interpolate/color-parse.ts";
+import { mixNumber } from "#/interpolate/number.ts";
+
+export { parseColor, type Rgba } from "#/interpolate/color-parse.ts";
+
+type Oklab = readonly [number, number, number, number];
+
+const VARIABLE = /^var\(/i;
+const IDENTIFIER = /^[a-z]+$/i;
+
+function srgbToLinear(value: number): number {
+	return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+}
+
+function toOklab({ r, g, b, alpha }: Rgba): Oklab {
+	const [lr, lg, lb] = [srgbToLinear(r), srgbToLinear(g), srgbToLinear(b)];
+	const l = Math.cbrt(
+		0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb,
+	);
+	const m = Math.cbrt(
+		0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb,
+	);
+	const s = Math.cbrt(
+		0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb,
+	);
+	return [
+		0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+		1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+		0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+		alpha,
+	];
+}
+
+function byte(value: number): number {
+	return Math.round(Math.min(1, Math.max(0, value)) * 255);
+}
+
+function format({ r, g, b, alpha }: Rgba): string {
+	const a = Math.round(Math.min(1, Math.max(0, alpha)) * 1000) / 1000;
+	return `rgba(${byte(r)}, ${byte(g)}, ${byte(b)}, ${a})`;
+}
+
+/** A string the page resolves to a colour: written out, a `var()`, a name, `currentColor`. */
+export function isColorLike(text: string): boolean {
+	const trimmed = text.trim();
+	return (
+		parseColor(trimmed) !== undefined ||
+		VARIABLE.test(trimmed) ||
+		IDENTIFIER.test(trimmed)
+	);
+}
+
+/**
+ * Two written-out colours mix in oklab here, premultiplied so a fade from
+ * `transparent` does not pass through grey. A `var()` or a name is only known
+ * to the page, so it mixes there: `color-mix()` with the share quantised to
+ * 2 %, which caps the strings a long animation mints at 51.
+ */
+export function mixColor(
+	from: string,
+	to: string,
+): (progress: number) => string {
+	const start = parseColor(from);
+	const end = parseColor(to);
+	if (start === undefined || end === undefined) {
+		return (progress) => {
+			const share = Math.round(progress * 50) * 2;
+			if (share <= 0) {
+				return from;
+			}
+			return share >= 100
+				? to
+				: `color-mix(in oklab, ${to} ${share}%, ${from})`;
+		};
+	}
+	const a = toOklab(start);
+	const b = toOklab(end);
+	return (progress) => {
+		if (progress === 0) {
+			return from;
+		}
+		if (progress === 1) {
+			return to;
+		}
+		const alpha = mixNumber(a[3], b[3], progress);
+		function channel(index: 0 | 1 | 2) {
+			return alpha === 0
+				? 0
+				: mixNumber(a[index] * a[3], b[index] * b[3], progress) / alpha;
+		}
+		return format(oklabToRgba([channel(0), channel(1), channel(2), alpha]));
+	};
+}

package/src/interpolate/complex.ts

@@ -0,0 +1,80 @@
+import { mixColor } from "#/interpolate/color.ts";
+import { mixNumber } from "#/interpolate/number.ts";
+
+type Token =
+	| { readonly kind: "number"; readonly value: number }
+	| { readonly kind: "color"; readonly value: string };
+
+interface Parsed {
+	readonly skeleton: readonly string[];
+	readonly tokens: readonly Token[];
+}
+
+/** Colours first, so a hex or an `rgb()` is one token rather than its digits. */
+const TOKEN =
+	/(#[0-9a-f]{3,8}\b|(?:rgba?|hsla?|oklch|oklab)\([^()]*\))|(-?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?)/gi;
+
+function parse(text: string): Parsed {
+	const skeleton: string[] = [];
+	const tokens: Token[] = [];
+	let last = 0;
+	for (const match of text.matchAll(TOKEN)) {
+		skeleton.push(text.slice(last, match.index));
+		tokens.push(
+			match[1] === undefined
+				? { kind: "number", value: Number(match[2]) }
+				: { kind: "color", value: match[1] },
+		);
+		last = match.index + match[0].length;
+	}
+	skeleton.push(text.slice(last));
+	return { skeleton, tokens };
+}
+
+function round(value: number): number {
+	return Math.round(value * 1000) / 1000;
+}
+
+/**
+ * Strings that differ only in their numbers and colours: `10px 20px`, a
+ * transform list, two paths with the same commands. Anything else has no
+ * midpoint here, and `undefined` says so.
+ */
+export function mixComplex(
+	from: string,
+	to: string,
+): ((progress: number) => string) | undefined {
+	const start = parse(from);
+	const end = parse(to);
+	const sameShape =
+		start.tokens.length === end.tokens.length &&
+		start.skeleton.every((part, index) => part === end.skeleton[index]) &&
+		start.tokens.every(
+			(token, index) => token.kind === end.tokens[index]?.kind,
+		);
+	if (!sameShape || (start.tokens.length === 0 && from !== to)) {
+		return undefined;
+	}
+	const mixers = start.tokens.map((token, index) => {
+		const target = end.tokens[index] as Token;
+		if (token.kind === "color") {
+			return mixColor(token.value, target.value as string);
+		}
+		const a = token.value;
+		const b = target.value as number;
+		return (progress: number) => String(round(mixNumber(a, b, progress)));
+	});
+	return (progress) => {
+		if (progress === 0) {
+			return from;
+		}
+		if (progress === 1) {
+			return to;
+		}
+		let text = start.skeleton[0] as string;
+		mixers.forEach((mixer, index) => {
+			text += mixer(progress) + (start.skeleton[index + 1] as string);
+		});
+		return text;
+	};
+}

package/src/interpolate/interpolate.ts

@@ -0,0 +1,60 @@
+import { resolveEasing } from "#/easing/named.ts";
+import type { EasingDefinition } from "#/easing/types.ts";
+import { type Mixer, mix } from "#/interpolate/mix.ts";
+
+export interface InterpolateOptions<T> {
+	/** Hold the output at its ends outside the input range. Default true. */
+	readonly clamp?: boolean;
+	/** One easing for every segment, or one per segment. */
+	readonly ease?: EasingDefinition | readonly EasingDefinition[];
+	readonly mixer?: (from: T, to: T) => Mixer<T>;
+}
+
+/**
+ * Maps a number through a piecewise range: `interpolate([0, 100], [1, 0])`
+ * turns a scroll offset into an opacity, `[0, 50, 100]` with three colours a
+ * progress into a gradient. The input may run either way.
+ */
+export function interpolate<T>(
+	input: readonly number[],
+	output: readonly T[],
+	options: InterpolateOptions<T> = {},
+): (value: number) => T {
+	if (input.length !== output.length || input.length === 0) {
+		throw new RangeError(
+			"interpolate: input and output need the same, non-zero length",
+		);
+	}
+	if (input.length === 1) {
+		return () => output[0] as T;
+	}
+	const direction =
+		(input[0] as number) > (input[input.length - 1] as number) ? -1 : 1;
+	const makeMixer = options.mixer ?? mix;
+	const mixers = output
+		.slice(1)
+		.map((value, index) => makeMixer(output[index] as T, value));
+	const eases = mixers.map((_mixer, index) => {
+		const ease = options.ease;
+		const definition = Array.isArray(ease) ? ease[index] : ease;
+		return resolveEasing((definition ?? "linear") as EasingDefinition);
+	});
+	const clamp = options.clamp ?? true;
+	const low = Math.min(input[0] as number, input[input.length - 1] as number);
+	const high = Math.max(input[0] as number, input[input.length - 1] as number);
+	return (value) => {
+		const at = clamp ? Math.min(high, Math.max(low, value)) : value;
+		let segment = 0;
+		while (
+			segment < mixers.length - 1 &&
+			(at - (input[segment + 1] as number)) * direction > 0
+		) {
+			segment += 1;
+		}
+		const start = input[segment] as number;
+		const span = (input[segment + 1] as number) - start;
+		const progress = span === 0 ? 1 : (at - start) / span;
+		const eased = (eases[segment] as (progress: number) => number)(progress);
+		return (mixers[segment] as Mixer<T>)(eased);
+	};
+}

package/src/interpolate/mix.ts

@@ -0,0 +1,74 @@
+import { mixArray } from "#/interpolate/array.ts";
+import { isColorLike, mixColor, parseColor } from "#/interpolate/color.ts";
+import { mixComplex } from "#/interpolate/complex.ts";
+import { mixNumber } from "#/interpolate/number.ts";
+import { mixObject } from "#/interpolate/object.ts";
+import { mixPath } from "#/interpolate/path/morph.ts";
+
+export type Mixer<T> = (progress: number) => T;
+
+type Strategy = (from: unknown, to: unknown) => Mixer<unknown> | undefined;
+
+const PATH = /^\s*[Mm]/;
+
+function bothStrings(from: unknown, to: unknown): [string, string] | undefined {
+	return typeof from === "string" && typeof to === "string"
+		? [from, to]
+		: undefined;
+}
+
+/**
+ * A colour pair needs one side written out, or both to be variables: two bare
+ * words are as likely `auto` and `none` as `red` and `blue`.
+ */
+function colors(from: string, to: string): boolean {
+	const resolved =
+		parseColor(from) !== undefined || parseColor(to) !== undefined;
+	const variables = /^\s*var\(/i.test(from) && /^\s*var\(/i.test(to);
+	return isColorLike(from) && isColorLike(to) && (resolved || variables);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Tried in order; the first that knows the pair mixes it. */
+const STRATEGIES: readonly Strategy[] = [
+	(from, to) =>
+		typeof from === "number" && typeof to === "number"
+			? (progress) => mixNumber(from, to, progress)
+			: undefined,
+	(from, to) => {
+		const pair = bothStrings(from, to);
+		return pair && PATH.test(pair[0]) && PATH.test(pair[1])
+			? mixPath(...pair)
+			: undefined;
+	},
+	(from, to) => {
+		const pair = bothStrings(from, to);
+		return pair && colors(...pair) ? mixColor(...pair) : undefined;
+	},
+	(from, to) => {
+		const pair = bothStrings(from, to);
+		return pair && mixComplex(...pair);
+	},
+	(from, to) =>
+		Array.isArray(from) && Array.isArray(to) ? mixArray(from, to) : undefined,
+	(from, to) =>
+		isRecord(from) && isRecord(to) ? mixObject(from, to) : undefined,
+];
+
+/**
+ * The value `progress` of the way from `from` to `to`, whatever they are:
+ * numbers, colours (in oklab), paths (morphed), strings of numbers, arrays,
+ * objects. What has no midpoint switches halfway.
+ */
+export function mix<T>(from: T, to: T): Mixer<T> {
+	for (const strategy of STRATEGIES) {
+		const mixer = strategy(from, to);
+		if (mixer !== undefined) {
+			return mixer as Mixer<T>;
+		}
+	}
+	return (progress) => (progress < 0.5 ? from : to);
+}

package/src/interpolate/number.ts

@@ -0,0 +1,3 @@
+export function mixNumber(from: number, to: number, progress: number): number {
+	return from + (to - from) * progress;
+}

package/src/interpolate/object.ts

@@ -0,0 +1,20 @@
+import { mix } from "#/interpolate/mix.ts";
+
+type Record_ = Readonly<Record<string, unknown>>;
+
+/** Key by key over the target's keys; a key the start lacks starts at its target. */
+export function mixObject<T extends Record_>(
+	from: T,
+	to: T,
+): (progress: number) => T {
+	const mixers = Object.keys(to).map(
+		(key) => [key, mix(key in from ? from[key] : to[key], to[key])] as const,
+	);
+	return (progress) => {
+		const result: Record<string, unknown> = {};
+		for (const [key, mixer] of mixers) {
+			result[key] = mixer(progress);
+		}
+		return result as T;
+	};
+}

package/src/interpolate/path/flatten.ts

@@ -0,0 +1,185 @@
+import type { PathCommand } from "#/interpolate/path/parse.ts";
+
+export type Point = readonly [number, number];
+
+/** One subpath as a polyline. */
+export interface Ring {
+	readonly points: readonly Point[];
+	readonly closed: boolean;
+}
+
+const MAX_SEGMENTS = 256;
+
+/** Enough segments that no chord strays more than `tolerance` from its curve. */
+function segmentsFor(bend: number, tolerance: number): number {
+	return Math.min(
+		MAX_SEGMENTS,
+		Math.max(1, Math.ceil(Math.sqrt((0.75 * bend) / tolerance))),
+	);
+}
+
+function cubic(
+	from: Point,
+	values: readonly number[],
+	tolerance: number,
+): Point[] {
+	const [x1, y1, x2, y2, x, y] = values as [
+		number,
+		number,
+		number,
+		number,
+		number,
+		number,
+	];
+	const [x0, y0] = from;
+	const bend = Math.max(
+		Math.hypot(x0 - 2 * x1 + x2, y0 - 2 * y1 + y2),
+		Math.hypot(x1 - 2 * x2 + x, y1 - 2 * y2 + y),
+	);
+	const count = segmentsFor(bend, tolerance);
+	return Array.from({ length: count }, (_unused, index) => {
+		const t = (index + 1) / count;
+		const u = 1 - t;
+		const [a, b, c, d] = [u * u * u, 3 * u * u * t, 3 * u * t * t, t * t * t];
+		return [a * x0 + b * x1 + c * x2 + d * x, a * y0 + b * y1 + c * y2 + d * y];
+	});
+}
+
+function quadratic(
+	from: Point,
+	values: readonly number[],
+	tolerance: number,
+): Point[] {
+	const [x1, y1, x, y] = values as [number, number, number, number];
+	const [x0, y0] = from;
+	const count = segmentsFor(
+		Math.hypot(x0 - 2 * x1 + x, y0 - 2 * y1 + y) / 3,
+		tolerance,
+	);
+	return Array.from({ length: count }, (_unused, index) => {
+		const t = (index + 1) / count;
+		const u = 1 - t;
+		return [
+			u * u * x0 + 2 * u * t * x1 + t * t * x,
+			u * u * y0 + 2 * u * t * y1 + t * t * y,
+		];
+	});
+}
+
+function angleBetween(ux: number, uy: number, vx: number, vy: number): number {
+	return Math.atan2(ux * vy - uy * vx, ux * vx + uy * vy);
+}
+
+/** SVG's endpoint arc, converted to its centre form (SVG 1.1, appendix F.6.5). */
+function arc(
+	from: Point,
+	values: readonly number[],
+	tolerance: number,
+): Point[] {
+	const [rxIn, ryIn, degrees, large, sweep, x2, y2] = values as [
+		number,
+		number,
+		number,
+		number,
+		number,
+		number,
+		number,
+	];
+	const [x1, y1] = from;
+	if (rxIn === 0 || ryIn === 0) {
+		return [[x2, y2]];
+	}
+	const phi = (degrees * Math.PI) / 180;
+	const [cos, sin] = [Math.cos(phi), Math.sin(phi)];
+	const dx = (x1 - x2) / 2;
+	const dy = (y1 - y2) / 2;
+	const x1p = cos * dx + sin * dy;
+	const y1p = -sin * dx + cos * dy;
+	const scale = Math.max(
+		1,
+		Math.sqrt((x1p * x1p) / (rxIn * rxIn) + (y1p * y1p) / (ryIn * ryIn)),
+	);
+	const rx = Math.abs(rxIn) * scale;
+	const ry = Math.abs(ryIn) * scale;
+	const numerator =
+		rx * rx * ry * ry - rx * rx * y1p * y1p - ry * ry * x1p * x1p;
+	const denominator = rx * rx * y1p * y1p + ry * ry * x1p * x1p;
+	const coefficient =
+		(large === sweep ? -1 : 1) *
+		Math.sqrt(Math.max(0, numerator / (denominator || 1)));
+	const cxp = (coefficient * rx * y1p) / ry;
+	const cyp = (-coefficient * ry * x1p) / rx;
+	const cx = cos * cxp - sin * cyp + (x1 + x2) / 2;
+	const cy = sin * cxp + cos * cyp + (y1 + y2) / 2;
+	const start = angleBetween(1, 0, (x1p - cxp) / rx, (y1p - cyp) / ry);
+	let delta = angleBetween(
+		(x1p - cxp) / rx,
+		(y1p - cyp) / ry,
+		(-x1p - cxp) / rx,
+		(-y1p - cyp) / ry,
+	);
+	if (sweep === 0 && delta > 0) {
+		delta -= 2 * Math.PI;
+	}
+	if (sweep === 1 && delta < 0) {
+		delta += 2 * Math.PI;
+	}
+	const radius = Math.max(rx, ry);
+	const step = 2 * Math.acos(Math.max(-1, 1 - tolerance / radius));
+	const count = Math.min(
+		MAX_SEGMENTS,
+		Math.max(1, Math.ceil(Math.abs(delta) / step)),
+	);
+	return Array.from({ length: count }, (_unused, index): Point => {
+		if (index === count - 1) {
+			return [x2, y2];
+		}
+		const theta = start + (delta * (index + 1)) / count;
+		const [c, s] = [Math.cos(theta), Math.sin(theta)];
+		return [cx + rx * c * cos - ry * s * sin, cy + rx * c * sin + ry * s * cos];
+	});
+}
+
+const CURVES = { C: cubic, Q: quadratic, A: arc } as const;
+
+/** Every subpath of a parsed path as a polyline; `tolerance` in path units. */
+export function flattenPath(
+	commands: readonly PathCommand[],
+	tolerance = 0.25,
+): Ring[] {
+	const rings: { points: Point[]; closed: boolean }[] = [];
+	let current: { points: Point[]; closed: boolean } = {
+		points: [],
+		closed: false,
+	};
+	let start: Point = [0, 0];
+	for (const command of commands) {
+		if (command.type === "M" || current.closed) {
+			start = command.type === "M" ? command.values : start;
+			current = { points: [start], closed: false };
+			rings.push(current);
+		}
+		const last = current.points[current.points.length - 1] as Point;
+		switch (command.type) {
+			case "M":
+				break;
+			case "L":
+				current.points.push(command.values);
+				break;
+			case "Z":
+				current.closed = true;
+				break;
+			default:
+				current.points.push(
+					...CURVES[command.type](last, command.values, tolerance),
+				);
+		}
+	}
+	return rings.map(({ points, closed }) => {
+		const first = points[0] as Point;
+		const end = points[points.length - 1] as Point;
+		const repeats =
+			closed && points.length > 1 && first[0] === end[0] && first[1] === end[1];
+		return { points: repeats ? points.slice(0, -1) : points, closed };
+	});
+}

package/src/interpolate/path/morph.ts

@@ -0,0 +1,100 @@
+import { mixComplex } from "#/interpolate/complex.ts";
+import {
+	flattenPath,
+	type Point,
+	type Ring,
+} from "#/interpolate/path/flatten.ts";
+import { parsePath } from "#/interpolate/path/parse.ts";
+import {
+	alignRing,
+	centroid,
+	matchRings,
+	resample,
+} from "#/interpolate/path/rings.ts";
+
+const MIN_POINTS = 16;
+const MAX_POINTS = 512;
+
+interface Track {
+	readonly from: readonly Point[];
+	readonly to: readonly Point[];
+	readonly closedFrom: boolean;
+	readonly closedTo: boolean;
+}
+
+function round(value: number): number {
+	return Math.round(value * 100) / 100;
+}
+
+/** A ring that does not exist on one side is that side's centroid, repeated. */
+function collapsed(ring: Ring, count: number): Point[] {
+	return Array.from({ length: count }, () => centroid(ring.points));
+}
+
+function track(from: Ring | undefined, to: Ring | undefined): Track {
+	const reference = (from ?? to) as Ring;
+	const count = Math.min(
+		MAX_POINTS,
+		Math.max(MIN_POINTS, from?.points.length ?? 0, to?.points.length ?? 0),
+	);
+	const start =
+		from === undefined ? collapsed(reference, count) : resample(from, count);
+	const end =
+		to === undefined ? collapsed(reference, count) : resample(to, count);
+	const closed = (from?.closed ?? true) && (to?.closed ?? true);
+	return {
+		from: start,
+		to: alignRing(start, end, closed),
+		closedFrom: from?.closed ?? reference.closed,
+		closedTo: to?.closed ?? reference.closed,
+	};
+}
+
+function draw(tracks: readonly Track[], progress: number): string {
+	return tracks
+		.map(({ from, to, closedFrom, closedTo }) => {
+			const points = from.map((point, index) => {
+				const other = to[index] as Point;
+				const x = round(point[0] + (other[0] - point[0]) * progress);
+				const y = round(point[1] + (other[1] - point[1]) * progress);
+				return `${x},${y}`;
+			});
+			const closed = progress < 0.5 ? closedFrom : closedTo;
+			return `M${points.join("L")}${closed ? "Z" : ""}`;
+		})
+		.join("");
+}
+
+/**
+ * A path between two paths. Same commands: the numbers mix, exactly. Any
+ * other pair is flattened to polylines, each subpath resampled to a shared
+ * point count by arc length, paired with its nearest counterpart and turned
+ * to line up with it, so every frame is a valid path that moves as little as
+ * it can. The ends are the input strings themselves.
+ */
+export function mixPath(
+	from: string,
+	to: string,
+): (progress: number) => string {
+	// Arc flags are 0 or 1: mixed as numbers, they would pass through 0.5.
+	const hasArcs = /a/i.test(from) || /a/i.test(to);
+	const same =
+		from === to ? () => from : hasArcs ? undefined : mixComplex(from, to);
+	if (same !== undefined) {
+		return same;
+	}
+	const start = parsePath(from);
+	const end = parsePath(to);
+	if (start === undefined || end === undefined) {
+		return (progress) => (progress < 0.5 ? from : to);
+	}
+	const tracks = matchRings(flattenPath(start), flattenPath(end)).map(
+		([a, b]) => track(a, b),
+	);
+	return (progress) => {
+		if (progress === 0) {
+			return from;
+		}
+		return progress === 1 ? to : draw(tracks, progress);
+	};
+}