@voila.dev/chart 5.0.118 → 6.0.120

package/src/core/motion/motion-store.ts

@@ -1,4 +1,4 @@
-import { type Generator, spring, tween } from "@voila.dev/motion";
+import type { Generator } from "@voila.dev/motion";
 import { enterFrom, exitTo } from "#/core/motion/enter-exit.ts";
 import {
 	type LeavingGuide,
@@ -10,7 +10,7 @@ import {
 	type StringChannel,
 	stringMixer,
 	stringOf,
-	withStrings,
+	withString,
 } from "#/core/motion/strings.ts";
 import { type ChartTiming, staggerDelay } from "#/core/motion/timing.ts";
 import type {
@@ -43,16 +43,8 @@ interface Motion {
 	readonly generator: Generator;
 	/** Milliseconds, the delay included. */
 	readonly start: number;
-}
-
-/** A path or a colour: a progress from 0 to 1, and the mix it reads. */
-interface StringMotion extends Motion {
-	readonly mix: (progress: number) => string;
-}
-
-/** A guide fading out where it stood. */
-interface GuideMotion extends Motion {
-	readonly guide: LeavingGuide;
+	/** A path or a colour: the generator runs a progress from 0 to 1, and this reads it. */
+	readonly mix?: (progress: number) => string;
 }
 
 /** A data mark collapsing on its way out: drawn after its old sibling until its springs settle. */
@@ -105,6 +97,10 @@ function elapsed(motion: Motion, now: number): number {
 	return Math.max(0, (now - motion.start) / 1000);
 }
 
+function sample(motion: Motion, now: number) {
+	return motion.generator.at(elapsed(motion, now));
+}
+
 function done(motion: Motion, now: number): boolean {
 	return elapsed(motion, now) >= motion.generator.duration;
 }
@@ -118,34 +114,18 @@ export function createMotionStore(
 	timing: ChartTiming,
 ): MotionStore {
 	let target = initial;
-	const numbers = new Map<string, Motion>();
-	const strings = new Map<string, StringMotion>();
-	const guides = new Map<string, GuideMotion>();
+	const channels = new Map<string, Motion>();
+	/** Fading out on their opacity channel. */
+	const guides = new Map<string, LeavingGuide>();
 	const shapes = new Map<
 		string,
 		{ readonly plan: GeometryPlan; readonly motion: GeometryMotion }
 	>();
 	const leaving = new Map<string, Leaving>();
 
-	function generator(from: number, to: number, velocity: number): Generator {
-		return timing.type === "spring"
-			? spring({
-					from,
-					to,
-					velocity,
-					duration: timing.duration,
-					bounce: timing.bounce,
-				})
-			: tween({
-					keyframes: [from, to],
-					duration: timing.duration,
-					ease: timing.easing,
-				});
-	}
-
 	function value(node: string, channel: string, fallback: number, now: number) {
-		const motion = numbers.get(channelKey(node, channel));
-		return motion ? motion.generator.at(elapsed(motion, now)).value : fallback;
+		const motion = channels.get(channelKey(node, channel));
+		return motion ? sample(motion, now).value : fallback;
 	}
 
 	/** Springs one channel from `from` to `to`, at the speed it already has. */
@@ -158,13 +138,11 @@ export function createMotionStore(
 		now: number,
 	) {
 		const key = channelKey(node, channel);
-		const running = numbers.get(key);
-		const velocity = running
-			? running.generator.at(elapsed(running, now)).velocity
-			: 0;
-		numbers.delete(key);
+		const running = channels.get(key);
+		const velocity = running ? sample(running, now).velocity : 0;
+		channels.delete(key);
 		if (from === to && velocity === 0) return;
-		numbers.set(key, { generator: generator(from, to, velocity), start });
+		channels.set(key, { generator: timing.motion(from, to, velocity), start });
 	}
 
 	/** Mixes one string channel from what is painted to what `to` asks for. */
@@ -175,22 +153,20 @@ export function createMotionStore(
 		start: number,
 	) {
 		const key = channelKey(to.key, channel);
-		strings.delete(key);
+		channels.delete(key);
 		const was = stringOf(from, channel);
 		const goal = stringOf(to, channel);
 		if (was === undefined || goal === undefined || was === goal) return;
-		strings.set(key, {
-			generator: generator(0, 1, 0),
+		channels.set(key, {
+			generator: timing.motion(0, 1, 0),
 			start,
 			mix: stringMixer(to, channel, was, goal),
 		});
 	}
 
 	function drop(node: string) {
-		for (const motions of [numbers, strings]) {
-			for (const key of motions.keys()) {
-				if (key.startsWith(node + SEPARATOR)) motions.delete(key);
-			}
+		for (const key of channels.keys()) {
+			if (key.startsWith(node + SEPARATOR)) channels.delete(key);
 		}
 		shapes.delete(node);
 		leaving.delete(node);
@@ -215,7 +191,7 @@ export function createMotionStore(
 		if (to.kind !== "path" || from.kind !== "path") return;
 		const previous = shapes.get(key);
 		shapes.delete(key);
-		strings.delete(channelKey(key, "d"));
+		channels.delete(channelKey(key, "d"));
 		const motion = to.motion;
 		const plan =
 			motion && from.geometry && to.geometry
@@ -228,7 +204,7 @@ export function createMotionStore(
 		}
 		for (const channel of previous?.plan.targets.keys() ?? []) {
 			if (!plan.targets.has(channel)) {
-				numbers.delete(channelKey(key, `g${channel}`));
+				channels.delete(channelKey(key, `g${channel}`));
 			}
 		}
 		for (const [channel, goal] of plan.targets) {
@@ -260,35 +236,28 @@ export function createMotionStore(
 			);
 			next = { ...next, geometry, d: shape.motion.draw(geometry) };
 		}
-		const mixed: Partial<Record<StringChannel, string>> = {};
 		for (const channel of STRING_CHANNELS) {
-			const motion = strings.get(channelKey(key, channel));
-			if (motion) {
-				mixed[channel] = motion.mix(
-					motion.generator.at(elapsed(motion, now)).value,
-				);
+			const motion = channels.get(channelKey(key, channel));
+			if (motion?.mix) {
+				next = withString(next, channel, motion.mix(sample(motion, now).value));
 			}
 		}
-		next = withStrings(next, mixed) as typeof next;
 		const opacity = value(key, OPACITY, 1, now);
 		const drawn = value(key, DRAWN, 1, now);
 		if (opacity === 1 && drawn === 1) return next;
-		const geometry = next.kind === "path" ? next.geometry : undefined;
-		const length =
-			geometry && next.kind === "path" ? next.motion?.length?.(geometry) : 0;
 		return {
 			...next,
 			paint: {
 				...next.paint,
 				opacity: (next.paint.opacity ?? 1) * clamp(opacity),
-				...(drawn < 1 && geometry
-					? {
-							drawn: {
-								fraction: clamp(drawn),
-								length: length ?? 0,
-							},
-						}
-					: {}),
+				...(drawn < 1 &&
+					next.kind === "path" &&
+					next.geometry && {
+						drawn: {
+							fraction: clamp(drawn),
+							length: next.motion?.length?.(next.geometry) ?? 0,
+						},
+					}),
 			},
 		} as SceneNode;
 	}
@@ -316,32 +285,22 @@ export function createMotionStore(
 			place(node.key);
 		}
 		if (guides.size === 0) return out;
-		const fading = [...guides.values()].map(
-			(motion) =>
-				[
-					motion.guide,
-					Math.max(0, motion.generator.at(elapsed(motion, now)).value),
-				] as const,
+		return withLeaving(out, parent, guides.values(), (node) =>
+			paintNode(node, now),
 		);
-		return withLeaving(out, parent, fading);
 	}
 
 	function prune(now: number) {
-		for (const motions of [numbers, strings, guides]) {
-			for (const [key, motion] of motions) {
-				if (done(motion, now)) motions.delete(key);
-			}
+		for (const [key, motion] of channels) {
+			if (done(motion, now)) channels.delete(key);
 		}
 		const moving = new Set(
-			[...numbers.keys(), ...strings.keys()].map(
-				(key) => key.split(SEPARATOR)[0],
-			),
+			[...channels.keys()].map((key) => key.split(SEPARATOR)[0]),
 		);
-		for (const key of shapes.keys()) {
-			if (!moving.has(key)) shapes.delete(key);
-		}
-		for (const key of leaving.keys()) {
-			if (!moving.has(key)) leaving.delete(key);
+		for (const byNode of [shapes, leaving, guides]) {
+			for (const key of byNode.keys()) {
+				if (!moving.has(key)) byNode.delete(key);
+			}
 		}
 	}
 
@@ -353,19 +312,15 @@ export function createMotionStore(
 				const node =
 					before.byKey.get(key) ??
 					leaving.get(key)?.node ??
-					guides.get(key)?.guide.node;
+					guides.get(key)?.node;
 				return node && paintNode(node, now);
 			}
 			// Read before the exits below drop what the guides were showing.
-			for (const guide of leavingGuides(target.nodes, (key) =>
+			const fadingGuides = leavingGuides(target.nodes, (key) =>
 				after.byKey.has(key),
-			)) {
-				guides.set(guide.node.key, {
-					generator: generator(value(guide.node.key, OPACITY, 1, now), 0, 0),
-					start: now,
-					guide,
-				});
-			}
+			).map(
+				(guide) => [guide, value(guide.node.key, OPACITY, 1, now)] as const,
+			);
 			for (const key of new Set([...before.byKey.keys(), ...leaving.keys()])) {
 				if (after.byKey.has(key)) continue;
 				const base = (before.byKey.get(key) ??
@@ -386,6 +341,13 @@ export function createMotionStore(
 					siblings,
 				});
 			}
+			for (const [guide, shown] of fadingGuides) {
+				guides.set(guide.node.key, guide);
+				channels.set(channelKey(guide.node.key, OPACITY), {
+					generator: timing.motion(shown, 0, 0),
+					start: now,
+				});
+			}
 			const marks = [...after.byKey.values()].filter(
 				(node) => node.role === "mark",
 			);
@@ -401,14 +363,12 @@ export function createMotionStore(
 					old ??
 					enterFrom(node, after.siblings.get(node.key) ?? [], before.byKey);
 				if (from) move(from, node, start, now);
-				const fading = numbers.get(channelKey(node.key, OPACITY));
-				const returning = guides.get(node.key);
-				if ((!from && node.enter !== "none") || fading || returning) {
-					const shown = returning
-						? Math.max(0, returning.generator.at(elapsed(returning, now)).value)
-						: fading
-							? value(node.key, OPACITY, 1, now)
-							: 0;
+				const fading = channels.get(channelKey(node.key, OPACITY));
+				if ((!from && node.enter !== "none") || fading) {
+					const shown = fading ? Math.max(0, sample(fading, now).value) : 0;
+					// A guide coming back starts from rest: its fade-out speed points the wrong way.
+					if (guides.has(node.key))
+						channels.delete(channelKey(node.key, OPACITY));
 					spring1(node.key, OPACITY, shown, 1, start, now);
 				}
 			}
@@ -428,22 +388,18 @@ export function createMotionStore(
 			return any;
 		},
 		snap(scene) {
-			for (const motions of [numbers, strings, guides, shapes, leaving]) {
+			for (const motions of [channels, guides, shapes, leaving]) {
 				motions.clear();
 			}
 			target = scene;
 		},
 		frame(now) {
 			prune(now);
-			if (numbers.size + strings.size + guides.size === 0) return target;
+			if (channels.size === 0) return target;
 			return { ...target, nodes: paintList(target.nodes, null, now) };
 		},
 		settled(now) {
-			return [
-				...numbers.values(),
-				...strings.values(),
-				...guides.values(),
-			].every((motion) => done(motion, now));
+			return [...channels.values()].every((motion) => done(motion, now));
 		},
 	};
 }

package/src/core/motion/points-motion.ts

@@ -11,6 +11,11 @@ type Points = Extract<SceneGeometry, { kind: "points" }>;
 
 const POINT_FIELDS = ["x", "y", "x0", "y0"] as const;
 
+/** Where `point` sits on its area's lower edge. */
+function lowerEdge(point: GeometryPoint): GeometryPoint {
+	return { ...point, x: point.x0 ?? point.x, y: point.y0 ?? point.y };
+}
+
 /** A line, an area or a radar outline through its points. */
 export function pointsPath(geometry: SceneGeometry): string {
 	if (geometry.kind !== "points") return "";
@@ -19,14 +24,7 @@ export function pointsPath(geometry: SceneGeometry): string {
 	return runs
 		.map((run) =>
 			shape === "area"
-				? areaPath(
-						run,
-						run.map((point) => ({
-							x: point.x0 ?? point.x,
-							y: point.y0 ?? point.y,
-						})),
-						curve,
-					)
+				? areaPath(run, run.map(lowerEdge), curve)
 				: linePath(run, curve),
 		)
 		.join("");
@@ -36,18 +34,14 @@ function channel(key: string, field: string): string {
 	return `${key}\u0001${field}`;
 }
 
-function fields(point: GeometryPoint, into: Map<string, number>) {
+/** `point`'s numbers under `key`'s channel names: `point` may be a neighbour that `key` enters from or folds into. */
+function fields(key: string, point: GeometryPoint, into: Map<string, number>) {
 	for (const field of POINT_FIELDS) {
 		const value = point[field];
-		if (value !== undefined) into.set(channel(point.key, field), value);
+		if (value !== undefined) into.set(channel(key, field), value);
 	}
 }
 
-/** `point`'s numbers under `key`'s channel names: a point entering from, or folding into, a neighbour. */
-function as(key: string, point: GeometryPoint): GeometryPoint {
-	return { ...point, key };
-}
-
 /** The nearest of `order` around `index` that `has` knows: looking back first, then ahead. */
 function neighbour(
 	order: readonly string[],
@@ -113,8 +107,8 @@ function pointsPlan(from: Points, to: Points): GeometryPlan | undefined {
 			const target = next.get(key) ?? neighbour(order, at, next);
 			const start = old.get(key) ?? neighbour(order, at, old) ?? target;
 			if (target === undefined || start === undefined) continue;
-			fields(as(key, start), starts);
-			fields(as(key, target), targets);
+			fields(key, start, starts);
+			fields(key, target, targets);
 		}
 		return order;
 	});
@@ -167,13 +161,7 @@ function collapsed(node: ScenePath): ScenePath | undefined {
 		...node,
 		geometry: {
 			...geometry,
-			runs: geometry.runs.map((run) =>
-				run.map((point) => ({
-					...point,
-					x: point.x0 ?? point.x,
-					y: point.y0 ?? point.y,
-				})),
-			),
+			runs: geometry.runs.map((run) => run.map(lowerEdge)),
 		},
 	};
 }

package/src/core/motion/strings.ts

@@ -53,16 +53,13 @@ export function stringMixer(
 	return morph ? morph(from, to) : (progress) => tweenPath(from, to, progress);
 }
 
-/** `node` with each string channel set to its moving value. */
-export function withStrings(
-	node: SceneNode,
-	values: Partial<Record<StringChannel, string>>,
-): SceneNode {
-	if (node.kind === "group") return node;
-	const { d, ...colours } = values;
-	const shaped =
-		d === undefined || node.kind !== "path" ? node : { ...node, d };
-	return Object.keys(colours).length === 0
-		? shaped
-		: ({ ...shaped, paint: { ...shaped.paint, ...colours } } as SceneNode);
+/** `node` with one string channel set to its moving value. */
+export function withString<Node extends Exclude<SceneNode, { kind: "group" }>>(
+	node: Node,
+	channel: StringChannel,
+	value: string,
+): Node {
+	if (channel !== "d")
+		return { ...node, paint: { ...node.paint, [channel]: value } };
+	return node.kind === "path" ? { ...node, d: value } : node;
 }

package/src/core/motion/timing.ts

@@ -1,34 +1,30 @@
-import type { EasingName } from "@voila.dev/motion";
-
-/** How a data update moves: what `<Chart animate>` accepts beyond `true`, `false` and a duration. */
-export type ChartAnimation =
-	| {
-			readonly type?: "spring";
-			/** Perceived duration, in milliseconds. */
-			readonly duration?: number;
-			/** 0 never overshoots (the default: a bar past its value shows a number the data doesn't have); up to 0.5. */
-			readonly bounce?: number;
-			/** Milliseconds between marks in focus order, capped at 300 ms in all. */
-			readonly stagger?: number;
-	  }
-	| {
-			readonly type: "tween";
-			readonly duration?: number;
-			readonly easing?: EasingName;
-			readonly stagger?: number;
-	  };
+import { type Generator, spring } from "@voila.dev/motion";
 
+/**
+ * How every channel of a chart moves on an update. The store only asks it
+ * for one channel's motion, so a chart that never tweens never loads the
+ * tween: `tween()` builds one, the default is a spring.
+ */
 export interface ChartTiming {
-	readonly type: "spring" | "tween";
-	/** Seconds, as the motion package counts them. */
-	readonly duration: number;
-	readonly bounce: number;
-	readonly easing: EasingName;
 	/** Seconds between neighbours. */
 	readonly stagger: number;
+	/** One channel from `from` to `to`, leaving at `velocity` (units per second). */
+	motion(from: number, to: number, velocity: number): Generator;
+}
+
+/** The spring `<Chart animate>` takes beyond `true`, `false` and a duration. */
+export interface ChartSpring {
+	/** Perceived duration, in milliseconds. */
+	readonly duration?: number;
+	/** 0 never overshoots (the default: a bar past its value shows a number the data doesn't have); up to 0.5. */
+	readonly bounce?: number;
+	/** Milliseconds between marks in focus order, capped at 300 ms in all. */
+	readonly stagger?: number;
 }
 
-const DEFAULT_DURATION = 300;
+export type ChartAnimation = ChartSpring | ChartTiming;
+
+export const DEFAULT_DURATION = 300;
 const MAX_STAGGER_TOTAL = 0.3;
 
 /** The timing an `animate` prop means, or `null` to snap. */
@@ -36,19 +32,18 @@ export function chartTiming(
 	animate: boolean | number | ChartAnimation,
 ): ChartTiming | null {
 	if (animate === false || animate === 0) return null;
-	const options: ChartAnimation =
+	if (typeof animate === "object" && "motion" in animate) return animate;
+	const options: ChartSpring =
 		typeof animate === "object"
 			? animate
 			: { duration: animate === true ? DEFAULT_DURATION : animate };
+	const duration = (options.duration ?? DEFAULT_DURATION) / 1000;
+	const bounce = Math.min(Math.max(options.bounce ?? 0, 0), 0.5);
 	return {
-		type: options.type ?? "spring",
-		duration: (options.duration ?? DEFAULT_DURATION) / 1000,
-		bounce: Math.min(
-			Math.max("bounce" in options ? (options.bounce ?? 0) : 0, 0),
-			0.5,
-		),
-		easing: ("easing" in options ? options.easing : undefined) ?? "easeOut",
 		stagger: (options.stagger ?? 0) / 1000,
+		motion(from, to, velocity) {
+			return spring({ from, to, velocity, duration, bounce });
+		},
 	};
 }
 

package/src/core/motion/tween-timing.ts

@@ -0,0 +1,35 @@
+import { type EasingName, tween as tweenGenerator } from "@voila.dev/motion";
+import { type ChartTiming, DEFAULT_DURATION } from "#/core/motion/timing.ts";
+
+export interface ChartTweenOptions {
+	/** Milliseconds. */
+	readonly duration?: number;
+	readonly easing?: EasingName;
+	/** Milliseconds between marks in focus order, capped at 300 ms in all. */
+	readonly stagger?: number;
+}
+
+/**
+ * A fixed curve instead of the spring, for `<Chart animate={tween()} />`.
+ * Its own import, so the easings only load in a chart that asks for them.
+ * The options stay on the timing as plain fields: `<Chart>` reads an inline
+ * `animate` by value, and a function alone would not tell two tweens apart.
+ */
+export function tween(
+	options: ChartTweenOptions = {},
+): ChartTiming & ChartTweenOptions {
+	const duration = options.duration ?? DEFAULT_DURATION;
+	const easing = options.easing ?? "easeOut";
+	return {
+		duration,
+		easing,
+		stagger: (options.stagger ?? 0) / 1000,
+		motion(from, to) {
+			return tweenGenerator({
+				keyframes: [from, to],
+				duration: duration / 1000,
+				ease: easing,
+			});
+		},
+	};
+}

package/src/index.ts

@@ -66,10 +66,12 @@ export {
 } from "#/core/motion/motion-store.ts";
 export {
 	type ChartAnimation,
+	type ChartSpring,
 	type ChartTiming,
 	chartTiming,
 } from "#/core/motion/timing.ts";
 export { easeOutCubic, tweenScene } from "#/core/motion/tween.ts";
+export { type ChartTweenOptions, tween } from "#/core/motion/tween-timing.ts";
 export {
 	type ChartFocusStop,
 	findNearest,

package/src/react/chart.tsx

@@ -71,8 +71,9 @@ interface Props
 	readonly dataTable?: boolean;
 	/**
 	 * How a data update moves: `true` (a spring with no bounce), a perceived
-	 * duration in milliseconds, or `{ duration, bounce, stagger }` and
-	 * `{ type: "tween", easing }`. `false` snaps; reduced motion always does.
+	 * duration in milliseconds, `{ duration, bounce, stagger }`, or
+	 * `tween({ duration, easing, stagger })`. `false` snaps; reduced motion
+	 * always does.
 	 */
 	readonly animate?: boolean | number | ChartAnimation;
 	/**
@@ -179,10 +180,14 @@ export function Chart({
 		() => [definition, hidden, keyboardZooms],
 		[definition, hidden, keyboardZooms],
 	);
-	// An inline `animate={{ … }}` object is read by value, not identity.
+	// An inline `animate={{ … }}` or `tween({ … })` is read by value, not
+	// identity: a new object each render must not restart the motion.
+	const latestAnimate = React.useRef(animate);
+	latestAnimate.current = animate;
 	const animateKey = JSON.stringify(animate);
+	// biome-ignore lint/correctness/useExhaustiveDependencies: keyed on the value of `animate`.
 	const timing = React.useMemo(
-		() => chartTiming(JSON.parse(animateKey)),
+		() => chartTiming(latestAnimate.current),
 		[animateKey],
 	);
 	const shown = useAnimatedScene(scene, animationTrigger, timing);

package/src/react/use-animated-scene.ts

@@ -1,4 +1,4 @@
-import { cancelFrame, frame, shouldReduceMotion } from "@voila.dev/motion";
+import { shouldReduceMotion } from "@voila.dev/motion";
 import * as React from "react";
 import {
 	createMotionStore,
@@ -53,20 +53,22 @@ export function useAnimatedScene(
 			return;
 		}
 		if (changed) store.retarget(scene, performance.now());
+		// One chart needs one callback a frame: a plain requestAnimationFrame
+		// keeps motion's shared frame loop out of every chart bundle.
+		let request = 0;
 		function tick() {
 			const now = performance.now();
 			if (store?.settled(now)) {
 				// Only once it has played: StrictMode's rerun of the effect starts it again.
 				introduced.current = true;
-				cancelFrame(tick);
 				setShown(scene);
 				return;
 			}
 			setShown(store?.frame(now) ?? scene);
+			request = requestAnimationFrame(tick);
 		}
 		tick();
-		frame.update(tick, true);
-		return () => cancelFrame(tick);
+		return () => cancelAnimationFrame(request);
 	}, [scene, trigger, timing]);
 
 	return shown;