@voila.dev/motion 0.0.0-stage → 5.0.113

package/src/interpolate/path/parse.ts

@@ -0,0 +1,162 @@
+/**
+ * A path in four commands, all absolute: H and V become L, S and T their full
+ * curves with the reflected control point, so the flattening downstream only
+ * ever meets lines, curves, arcs and closes.
+ */
+export type PathCommand =
+	| { readonly type: "M" | "L"; readonly values: readonly [number, number] }
+	| { readonly type: "C"; readonly values: readonly number[] }
+	| { readonly type: "Q"; readonly values: readonly number[] }
+	| { readonly type: "A"; readonly values: readonly number[] }
+	| { readonly type: "Z"; readonly values: readonly [] };
+
+interface State {
+	x: number;
+	y: number;
+	startX: number;
+	startY: number;
+	/** The last curve's second control point, for S and T to reflect. */
+	controlX: number;
+	controlY: number;
+	previous: string;
+}
+
+type Handler = (args: number[], state: State) => PathCommand;
+
+const ARGUMENTS: Readonly<Record<string, number>> = {
+	M: 2,
+	L: 2,
+	H: 1,
+	V: 1,
+	C: 6,
+	S: 4,
+	Q: 4,
+	T: 2,
+	A: 7,
+	Z: 0,
+};
+const NUMBER = /\s*,?\s*(-?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?)/iy;
+const FLAG = /\s*,?\s*([01])/y;
+const COMMAND = /\s*,?\s*([MLHVCSQTAZ])/iy;
+
+function reflect(state: State, curve: string): [number, number] {
+	return state.previous === curve
+		? [2 * state.x - state.controlX, 2 * state.y - state.controlY]
+		: [state.x, state.y];
+}
+
+function moveTo(state: State, x: number, y: number) {
+	state.x = x;
+	state.y = y;
+}
+
+const HANDLERS: Readonly<Record<string, Handler>> = {
+	M: ([x, y], state) => {
+		moveTo(state, x as number, y as number);
+		state.startX = state.x;
+		state.startY = state.y;
+		return { type: "M", values: [state.x, state.y] };
+	},
+	L: ([x, y], state) => {
+		moveTo(state, x as number, y as number);
+		return { type: "L", values: [state.x, state.y] };
+	},
+	H: ([x], state) => HANDLERS.L?.([x as number, state.y], state) as PathCommand,
+	V: ([y], state) => HANDLERS.L?.([state.x, y as number], state) as PathCommand,
+	C: (args, state) => {
+		[state.controlX, state.controlY] = [args[2] as number, args[3] as number];
+		moveTo(state, args[4] as number, args[5] as number);
+		return { type: "C", values: args };
+	},
+	S: (args, state) =>
+		HANDLERS.C?.([...reflect(state, "C"), ...args], state) as PathCommand,
+	Q: (args, state) => {
+		[state.controlX, state.controlY] = [args[0] as number, args[1] as number];
+		moveTo(state, args[2] as number, args[3] as number);
+		return { type: "Q", values: args };
+	},
+	T: (args, state) =>
+		HANDLERS.Q?.([...reflect(state, "Q"), ...args], state) as PathCommand,
+	A: (args, state) => {
+		moveTo(state, args[5] as number, args[6] as number);
+		return { type: "A", values: args };
+	},
+	Z: (_args, state) => {
+		moveTo(state, state.startX, state.startY);
+		return { type: "Z", values: [] };
+	},
+};
+
+/** Each argument's axis when relative: 0 adds x, 1 adds y, -1 is not a coordinate. */
+const AXES: Readonly<Record<string, readonly number[]>> = {
+	M: [0, 1],
+	L: [0, 1],
+	H: [0],
+	V: [1],
+	C: [0, 1, 0, 1, 0, 1],
+	S: [0, 1, 0, 1],
+	Q: [0, 1, 0, 1],
+	T: [0, 1],
+	A: [-1, -1, -1, -1, -1, 0, 1],
+	Z: [],
+};
+const CURVE_FAMILY: Readonly<Record<string, string>> = { S: "C", T: "Q" };
+
+function absolute(type: string, args: number[], state: State): number[] {
+	const axes = AXES[type] as readonly number[];
+	return args.map((value, index) => {
+		const axis = axes[index];
+		return axis === -1 ? value : value + (axis === 0 ? state.x : state.y);
+	});
+}
+
+function read(pattern: RegExp, text: string, at: number) {
+	pattern.lastIndex = at;
+	const match = pattern.exec(text);
+	return match === null
+		? undefined
+		: { value: match[1] as string, end: pattern.lastIndex };
+}
+
+/** Parses `d` to absolute commands; `undefined` when it is not a valid path. */
+export function parsePath(d: string): PathCommand[] | undefined {
+	const state: State = {
+		x: 0,
+		y: 0,
+		startX: 0,
+		startY: 0,
+		controlX: 0,
+		controlY: 0,
+		previous: "",
+	};
+	const commands: PathCommand[] = [];
+	let at = 0;
+	let command = read(COMMAND, d, at);
+	if (command === undefined || command.value.toUpperCase() !== "M") {
+		return undefined;
+	}
+	while (command !== undefined) {
+		at = command.end;
+		let letter = command.value;
+		do {
+			const type = letter.toUpperCase();
+			const args: number[] = [];
+			for (let index = 0; index < (ARGUMENTS[type] as number); index += 1) {
+				const flag = type === "A" && (index === 3 || index === 4);
+				const token = read(flag ? FLAG : NUMBER, d, at);
+				if (token === undefined) {
+					return undefined;
+				}
+				args.push(Number(token.value));
+				at = token.end;
+			}
+			const values = letter === type ? args : absolute(type, args, state);
+			commands.push((HANDLERS[type] as Handler)(values, state));
+			state.previous = CURVE_FAMILY[type] ?? type;
+			// After a moveto, further pairs are implicit linetos.
+			letter = type === "M" ? (letter === "M" ? "L" : "l") : letter;
+		} while (letter.toUpperCase() !== "Z" && read(NUMBER, d, at) !== undefined);
+		command = read(COMMAND, d, at);
+	}
+	return /^\s*$/.test(d.slice(at)) ? commands : undefined;
+}

package/src/interpolate/path/rings.ts

@@ -0,0 +1,151 @@
+import type { Point, Ring } from "#/interpolate/path/flatten.ts";
+
+function distance(a: Point, b: Point): number {
+	return Math.hypot(a[0] - b[0], a[1] - b[1]);
+}
+
+/** `count` points evenly spaced by arc length; a closed ring includes its closing edge. */
+export function resample(ring: Ring, count: number): Point[] {
+	const points = ring.closed
+		? [...ring.points, ring.points[0] as Point]
+		: ring.points;
+	const lengths = [0];
+	for (let index = 1; index < points.length; index += 1) {
+		lengths.push(
+			(lengths[index - 1] as number) +
+				distance(points[index - 1] as Point, points[index] as Point),
+		);
+	}
+	const total = lengths[lengths.length - 1] as number;
+	if (points.length < 2 || total === 0) {
+		return Array.from({ length: count }, () => points[0] as Point);
+	}
+	const step = total / (ring.closed ? count : Math.max(1, count - 1));
+	const result: Point[] = [];
+	let segment = 1;
+	for (let index = 0; index < count; index += 1) {
+		const along = Math.min(total, index * step);
+		while (
+			segment < points.length - 1 &&
+			(lengths[segment] as number) < along
+		) {
+			segment += 1;
+		}
+		const [a, b] = [points[segment - 1] as Point, points[segment] as Point];
+		const span =
+			(lengths[segment] as number) - (lengths[segment - 1] as number);
+		const t =
+			span === 0 ? 0 : (along - (lengths[segment - 1] as number)) / span;
+		result.push([a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t]);
+	}
+	return result;
+}
+
+export function area(points: readonly Point[]): number {
+	let sum = 0;
+	points.forEach((point, index) => {
+		const next = points[(index + 1) % points.length] as Point;
+		sum += point[0] * next[1] - next[0] * point[1];
+	});
+	return sum / 2;
+}
+
+export function centroid(points: readonly Point[]): Point {
+	const sum = points.reduce<[number, number]>(
+		(total, [x, y]) => [total[0] + x, total[1] + y],
+		[0, 0],
+	);
+	return [sum[0] / points.length, sum[1] / points.length];
+}
+
+function cost(
+	a: readonly Point[],
+	b: readonly Point[],
+	offset: number,
+): number {
+	let sum = 0;
+	for (let index = 0; index < a.length; index += 1) {
+		const other = b[(index + offset) % b.length] as Point;
+		const point = a[index] as Point;
+		sum += (point[0] - other[0]) ** 2 + (point[1] - other[1]) ** 2;
+	}
+	return sum;
+}
+
+/**
+ * `to` rearranged so each point travels as little as it can to its partner
+ * in `from`: a closed ring may start anywhere and run either way round, an
+ * open one may only run backwards. Both have the same length.
+ */
+export function alignRing(
+	from: readonly Point[],
+	to: readonly Point[],
+	closed: boolean,
+): Point[] {
+	const candidates = [to, [...to].reverse()];
+	let best = {
+		points: to as readonly Point[],
+		offset: 0,
+		cost: Number.POSITIVE_INFINITY,
+	};
+	for (const points of candidates) {
+		const offsets = closed ? points.length : 1;
+		for (let offset = 0; offset < offsets; offset += 1) {
+			const value = cost(from, points, offset);
+			if (value < best.cost) {
+				best = { points, offset, cost: value };
+			}
+		}
+	}
+	return best.points.map(
+		(_point, index) =>
+			best.points[(index + best.offset) % best.points.length] as Point,
+	);
+}
+
+/**
+ * Pairs each ring of one shape with a ring of the other, nearest centroids and
+ * closest areas first. A ring left over pairs with `undefined`: it grows from,
+ * or shrinks to, its own centroid.
+ */
+function describe(ring: Ring) {
+	return { centre: centroid(ring.points), size: Math.abs(area(ring.points)) };
+}
+
+export function matchRings(
+	from: readonly Ring[],
+	to: readonly Ring[],
+): [Ring | undefined, Ring | undefined][] {
+	const starts = from.map(describe);
+	const ends = to.map(describe);
+	const pairs = starts.flatMap((start, i) =>
+		ends.map((end, j) => {
+			const scale = Math.sqrt(Math.max(start.size, end.size, 1));
+			return {
+				i,
+				j,
+				score:
+					distance(start.centre, end.centre) / scale +
+					Math.abs(Math.log((start.size + 1) / (end.size + 1))),
+			};
+		}),
+	);
+	pairs.sort((a, b) => a.score - b.score);
+	const usedFrom = new Set<number>();
+	const usedTo = new Set<number>();
+	const result: [Ring | undefined, Ring | undefined][] = [];
+	for (const { i, j } of pairs) {
+		if (!usedFrom.has(i) && !usedTo.has(j)) {
+			usedFrom.add(i);
+			usedTo.add(j);
+			result.push([from[i], to[j]]);
+		}
+	}
+	for (const [i, ring] of from.entries()) {
+		if (!usedFrom.has(i)) result.push([ring, undefined]);
+	}
+	for (const [j, ring] of to.entries()) {
+		if (!usedTo.has(j)) result.push([undefined, ring]);
+	}
+	return result;
+}

package/src/react/index.ts

@@ -0,0 +1,11 @@
+export {
+	type Exit,
+	Presence,
+	type PresenceProps,
+	usePresence,
+} from "#/react/presence.tsx";
+export { type AnimationScope, useAnimate } from "#/react/use-animate.ts";
+export { useMotionValue } from "#/react/use-motion-value.ts";
+export { useReducedMotion } from "#/react/use-reduced-motion.ts";
+export { useSpring } from "#/react/use-spring.ts";
+export { useTransform } from "#/react/use-transform.ts";

package/src/react/presence.tsx

@@ -0,0 +1,194 @@
+import * as React from "react";
+
+/** Plays a child's way out; Presence removes it once the returned promise settles. */
+export type Exit = (element: Element) => PromiseLike<unknown> | undefined;
+
+declare module "react" {
+	interface Attributes {
+		/** Inside a `<Presence>`: plays this child's way out before it unmounts. */
+		exit?: Exit;
+	}
+}
+
+interface PresenceState {
+	readonly isPresent: boolean;
+	/** For a child that animates its own exit: tells Presence it may go. */
+	readonly safeToRemove: () => void;
+	/** Called by `usePresence`: Presence then waits for `safeToRemove`. */
+	readonly register: () => () => void;
+}
+
+const PresenceContext = React.createContext<PresenceState | null>(null);
+
+/**
+ * Whether this component is still wanted, and the function that lets it go
+ * once its own exit has played. Outside a Presence it is always present.
+ */
+export function usePresence(): readonly [boolean, () => void] {
+	const state = React.useContext(PresenceContext);
+	const register = state?.register;
+	React.useLayoutEffect(() => register?.(), [register]);
+	return [state?.isPresent ?? true, state?.safeToRemove ?? noop];
+}
+
+function noop() {}
+
+type Keyed = React.ReactElement<{ exit?: Exit; ref?: React.Ref<Element> }>;
+
+function keyedChildren(children: React.ReactNode): Keyed[] {
+	return React.Children.toArray(children).filter((child): child is Keyed =>
+		React.isValidElement(child),
+	);
+}
+
+/** The new children, with the ones that left kept where they were. */
+function merge(previous: readonly Keyed[], current: readonly Keyed[]): Keyed[] {
+	const keys = new Set(current.map((child) => child.key));
+	const merged = [...current];
+	for (const [index, child] of previous.entries()) {
+		if (keys.has(child.key)) continue;
+		const before = previous[index - 1]?.key;
+		const at = merged.findIndex((other) => other.key === before);
+		merged.splice(at + 1, 0, child);
+	}
+	return merged;
+}
+
+interface Slot {
+	ownRef: React.Ref<Element> | undefined;
+	readonly ref: (element: Element | null) => void;
+	readonly present: PresenceState;
+	readonly absent: PresenceState;
+}
+
+export interface PresenceProps {
+	readonly children?: React.ReactNode;
+	/** Called each time the last exiting child is gone. */
+	readonly onExitComplete?: () => void;
+}
+
+/**
+ * Keeps a removed child on screen until its exit has played: the `exit`
+ * prop it carries (given the child's element, through its ref), or the
+ * child's own `usePresence`. Children need a stable `key`. An exiting child
+ * is inert: it can't take focus or clicks on its way out.
+ */
+export function Presence({ children, onExitComplete }: PresenceProps) {
+	const current = keyedChildren(children);
+	const rendered = React.useRef<Keyed[]>(current);
+	const gone = React.useRef(new Set<string | null>());
+	const elements = React.useRef(new Map<string | null, Element>());
+	const registered = React.useRef(new Map<string | null, number>());
+	const [, rerender] = React.useReducer((count: number) => count + 1, 0);
+
+	const currentKeys = new Set(current.map((child) => child.key));
+	const present = React.useRef(currentKeys);
+	present.current = currentKeys;
+	/** Exits under way, so a later exit doesn't restart them, and a return can undo them. */
+	const leaving = React.useRef(
+		new Map<string | null, PromiseLike<unknown> | undefined>(),
+	);
+	const shown = merge(
+		rendered.current.filter((child) => !gone.current.has(child.key)),
+		current,
+	);
+	for (const key of currentKeys) gone.current.delete(key);
+	rendered.current = shown;
+	const exiting = shown.filter((child) => !currentKeys.has(child.key));
+
+	const remove = React.useCallback(
+		(key: string | null) => {
+			// Gone already, or back before its exit finished.
+			if (gone.current.has(key) || present.current.has(key)) return;
+			gone.current.add(key);
+			leaving.current.delete(key);
+			rerender();
+			const left = rendered.current.some(
+				(child) =>
+					!gone.current.has(child.key) && !present.current.has(child.key),
+			);
+			if (!left) onExitComplete?.();
+		},
+		[onExitComplete],
+	);
+
+	const exitingKeys = exiting.map((child) => child.key).join("\u0000");
+	// biome-ignore lint/correctness/useExhaustiveDependencies: keyed on the set of exiting children.
+	React.useLayoutEffect(() => {
+		for (const [key, played] of leaving.current) {
+			if (!present.current.has(key)) continue;
+			leaving.current.delete(key);
+			elements.current.get(key)?.removeAttribute("inert");
+			(played as { cancel?: () => void } | undefined)?.cancel?.();
+		}
+		for (const child of exiting) {
+			if (leaving.current.has(child.key)) continue;
+			const element = elements.current.get(child.key);
+			element?.setAttribute("inert", "");
+			const played = element && child.props.exit?.(element);
+			leaving.current.set(child.key, played);
+			if (played) {
+				Promise.resolve(played).then(
+					() => remove(child.key),
+					() => remove(child.key),
+				);
+			} else if (!registered.current.get(child.key)) {
+				remove(child.key);
+			}
+		}
+	}, [exitingKeys]);
+
+	const removeRef = React.useRef(remove);
+	removeRef.current = remove;
+	const slots = React.useRef(new Map<string | null, Slot>());
+
+	/**
+	 * Stable per key: the ref React sees and the context values never change
+	 * identity between renders, so a child's own callback ref isn't detached
+	 * and reattached each time, and `usePresence` consumers only re-render
+	 * when their presence flips.
+	 */
+	function slotFor(key: string | null): Slot {
+		const existing = slots.current.get(key);
+		if (existing) return existing;
+		function register() {
+			registered.current.set(key, (registered.current.get(key) ?? 0) + 1);
+			return () => {
+				registered.current.set(key, (registered.current.get(key) ?? 1) - 1);
+			};
+		}
+		function safeToRemove() {
+			removeRef.current(key);
+		}
+		const slot: Slot = {
+			ownRef: undefined,
+			ref(element) {
+				if (element) elements.current.set(key, element);
+				else elements.current.delete(key);
+				const ownRef = slot.ownRef;
+				if (typeof ownRef === "function") ownRef(element);
+				else if (ownRef)
+					(ownRef as React.RefObject<Element | null>).current = element;
+			},
+			present: { isPresent: true, safeToRemove, register },
+			absent: { isPresent: false, safeToRemove, register },
+		};
+		slots.current.set(key, slot);
+		return slot;
+	}
+
+	return shown.map((child) => {
+		const key = child.key;
+		const { exit: _exit, ref: ownRef, ...props } = child.props;
+		const slot = slotFor(key);
+		slot.ownRef = ownRef;
+		return (
+			<PresenceContext.Provider
+				key={key}
+				value={currentKeys.has(key) ? slot.present : slot.absent}
+			>
+				{React.createElement(child.type, { ...props, ref: slot.ref })}
+			</PresenceContext.Provider>
+		);
+	});
+}

package/src/react/use-animate.ts

@@ -0,0 +1,46 @@
+import * as React from "react";
+import { type Animate, createAnimate } from "#/animate/animate.ts";
+import type { AnimationControls } from "#/animate/types.ts";
+
+export interface AnimationScope<T extends Element = Element> {
+	current: T | null;
+	/** The animations started through this scope and still running. */
+	readonly animations: AnimationControls[];
+}
+
+/**
+ * A ref to put on an element, and an `animate` whose selectors only match
+ * inside it. Every animation started through it stops on unmount, so a
+ * component never animates a node React already removed.
+ */
+export function useAnimate<T extends Element = HTMLElement>(): readonly [
+	AnimationScope<T>,
+	Animate,
+] {
+	const [scope] = React.useState<AnimationScope<T>>(() => ({
+		current: null,
+		animations: [],
+	}));
+	const [scoped] = React.useState(() => {
+		const base = createAnimate(() => scope.current);
+		function tracked(...args: Parameters<typeof base>): AnimationControls {
+			const controls = (base as (...a: unknown[]) => AnimationControls)(
+				...args,
+			);
+			scope.animations.push(controls);
+			controls.finished.then(() => {
+				const index = scope.animations.indexOf(controls);
+				if (index !== -1) scope.animations.splice(index, 1);
+			});
+			return controls;
+		}
+		return tracked as Animate;
+	});
+	React.useEffect(
+		() => () => {
+			for (const controls of scope.animations.splice(0)) controls.stop();
+		},
+		[scope],
+	);
+	return [scope, scoped] as const;
+}

package/src/react/use-motion-value.ts

@@ -0,0 +1,9 @@
+import * as React from "react";
+import { type MotionValue, motionValue } from "#/value/motion-value.ts";
+
+/** A motion value that lives as long as the component, created once. */
+export function useMotionValue<T>(initial: T): MotionValue<T> {
+	const [value] = React.useState(() => motionValue(initial));
+	React.useEffect(() => () => value.stop(), [value]);
+	return value;
+}

package/src/react/use-reduced-motion.ts

@@ -0,0 +1,22 @@
+import * as React from "react";
+import {
+	onReducedMotionChange,
+	shouldReduceMotion,
+} from "#/accessibility/reduced-motion.ts";
+
+function serverSnapshot(): boolean {
+	return false;
+}
+
+/**
+ * Whether motion should be reduced, following the global policy and the
+ * reader's setting as either changes. False on the server: the first client
+ * render matches, then corrects itself.
+ */
+export function useReducedMotion(): boolean {
+	return React.useSyncExternalStore(
+		onReducedMotionChange,
+		() => shouldReduceMotion(),
+		serverSnapshot,
+	);
+}

package/src/react/use-spring.ts

@@ -0,0 +1,35 @@
+import * as React from "react";
+import { animate } from "#/animate/animate.ts";
+import type { AnimationOptions } from "#/animate/types.ts";
+import { useMotionValue } from "#/react/use-motion-value.ts";
+import { isMotionValue, type MotionValue } from "#/value/motion-value.ts";
+
+/**
+ * A value that springs towards `target` whenever it changes: a number from
+ * props, or another motion value it follows. A new target mid-flight keeps
+ * the speed the value has.
+ */
+export function useSpring(
+	target: number | MotionValue<number>,
+	options: AnimationOptions = {},
+): MotionValue<number> {
+	const value = useMotionValue(
+		isMotionValue(target) ? (target as MotionValue<number>).get() : target,
+	);
+	const optionsRef = React.useRef(options);
+	optionsRef.current = options;
+
+	React.useEffect(() => {
+		function follow(next: number) {
+			animate(value, next, { ...optionsRef.current, type: "spring" });
+		}
+		if (!isMotionValue(target)) {
+			if (value.get() !== target) follow(target);
+			return;
+		}
+		const source = target as MotionValue<number>;
+		return source.on("change", follow);
+	}, [target, value]);
+
+	return value;
+}