@voila.dev/chart 5.0.114 → 5.0.118

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

@@ -0,0 +1,190 @@
+import { areaPath, linePath, polygonPath } from "#/core/paths.ts";
+import type {
+	GeometryMotion,
+	GeometryPlan,
+	GeometryPoint,
+	SceneGeometry,
+	ScenePath,
+} from "#/core/types.ts";
+
+type Points = Extract<SceneGeometry, { kind: "points" }>;
+
+const POINT_FIELDS = ["x", "y", "x0", "y0"] as const;
+
+/** A line, an area or a radar outline through its points. */
+export function pointsPath(geometry: SceneGeometry): string {
+	if (geometry.kind !== "points") return "";
+	const { runs, shape, curve } = geometry;
+	if (shape === "polygon") return polygonPath(runs[0] ?? []);
+	return runs
+		.map((run) =>
+			shape === "area"
+				? areaPath(
+						run,
+						run.map((point) => ({
+							x: point.x0 ?? point.x,
+							y: point.y0 ?? point.y,
+						})),
+						curve,
+					)
+				: linePath(run, curve),
+		)
+		.join("");
+}
+
+function channel(key: string, field: string): string {
+	return `${key}\u0001${field}`;
+}
+
+function fields(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);
+	}
+}
+
+/** `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[],
+	index: number,
+	has: ReadonlyMap<string, GeometryPoint>,
+): GeometryPoint | undefined {
+	for (let at = index - 1; at >= 0; at -= 1) {
+		const found = has.get(order[at] as string);
+		if (found) return found;
+	}
+	for (let at = index + 1; at < order.length; at += 1) {
+		const found = has.get(order[at] as string);
+		if (found) return found;
+	}
+	return undefined;
+}
+
+/** The new keys, with the ones that left kept after the old point before them. */
+function mergeOrder(
+	before: readonly string[],
+	after: readonly string[],
+): string[] {
+	const merged = [...after];
+	const known = new Set(after);
+	for (const [index, key] of before.entries()) {
+		if (known.has(key)) continue;
+		const previous = before[index - 1];
+		merged.splice(
+			previous === undefined ? 0 : merged.indexOf(previous) + 1,
+			0,
+			key,
+		);
+		known.add(key);
+	}
+	return merged;
+}
+
+/**
+ * Points keyed by x. A point that appears enters from its nearest old
+ * neighbour (a month added on the right slides out of the last one); a
+ * point that leaves folds into its nearest new neighbour. Undefined when the
+ * runs don't line up: the caller falls back to tweening the path.
+ */
+function pointsPlan(from: Points, to: Points): GeometryPlan | undefined {
+	if (from.runs.length !== to.runs.length || from.shape !== to.shape)
+		return undefined;
+	const starts = new Map<string, number>();
+	const targets = new Map<string, number>();
+	const orders = to.runs.map((run, index): string[] | undefined => {
+		const old = new Map(
+			(from.runs[index] ?? []).map((point) => [point.key, point]),
+		);
+		const next = new Map(run.map((point) => [point.key, point]));
+		// Two points under one key can't be told apart: tween the path instead.
+		if (
+			old.size !== (from.runs[index]?.length ?? 0) ||
+			next.size !== run.length
+		) {
+			return undefined;
+		}
+		const order = mergeOrder([...old.keys()], [...next.keys()]);
+		for (const [at, key] of order.entries()) {
+			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);
+		}
+		return order;
+	});
+	if (orders.some((order) => order === undefined)) return undefined;
+	return {
+		starts,
+		targets,
+		build(value) {
+			const area = to.runs.some((run) => run[0]?.y0 !== undefined);
+			return {
+				...to,
+				runs: (orders as string[][]).map((order) =>
+					order.map((key) => ({
+						key,
+						x: value(channel(key, "x")),
+						y: value(channel(key, "y")),
+						...(area
+							? { x0: value(channel(key, "x0")), y0: value(channel(key, "y0")) }
+							: {}),
+					})),
+				),
+			};
+		},
+	};
+}
+
+/** A line's length along its points: what Canvas dashes against to trace it in. */
+function pointsLength(geometry: SceneGeometry): number {
+	if (geometry.kind !== "points") return 0;
+	let length = 0;
+	for (const run of geometry.runs) {
+		for (let index = 1; index < run.length; index += 1) {
+			const a = run[index - 1] as GeometryPoint;
+			const b = run[index] as GeometryPoint;
+			length += Math.hypot(b.x - a.x, b.y - a.y);
+		}
+	}
+	// A curve runs a little longer than its chords; the dash must cover it all.
+	return length * 1.1;
+}
+
+/** An area, or the line over it, grows from its lower edge. */
+function collapsed(node: ScenePath): ScenePath | undefined {
+	const geometry = node.geometry;
+	// A line over an area carries the area's lower edge too, so the two grow as one.
+	if (geometry?.kind !== "points" || geometry.runs[0]?.[0]?.y0 === undefined) {
+		return undefined;
+	}
+	return {
+		...node,
+		geometry: {
+			...geometry,
+			runs: geometry.runs.map((run) =>
+				run.map((point) => ({
+					...point,
+					x: point.x0 ?? point.x,
+					y: point.y0 ?? point.y,
+				})),
+			),
+		},
+	};
+}
+
+/** Lines, areas and radar outlines: points keyed by x (or by axis). */
+export const POINTS_MOTION: GeometryMotion = {
+	plan: (from, to) =>
+		from.kind === "points" && to.kind === "points"
+			? pointsPlan(from, to)
+			: undefined,
+	draw: pointsPath,
+	length: pointsLength,
+	enter: (node) => (node.enter === "grow" ? collapsed(node) : undefined),
+};

package/src/core/motion/strings.ts

@@ -0,0 +1,68 @@
+import { tweenPath } from "#/core/motion/tween.ts";
+import type { SceneNode } from "#/core/types.ts";
+
+/** The channels that move as a string mixed by progress, not as a number. */
+export const STRING_CHANNELS = ["d", "fill", "stroke"] as const;
+
+export type StringChannel = (typeof STRING_CHANNELS)[number];
+
+/** 2 % steps: at most 51 colours per pair, so the Canvas resolver's cache stays small. */
+const COLOUR_STEPS = 50;
+
+/**
+ * A colour part of the way to another, as CSS: `color-mix()` reads the
+ * chart's `var(--chart-1)` tokens as they are, so nothing parses colours,
+ * and the Canvas resolver computes the mix against the page like any
+ * other colour.
+ */
+export function colourBetween(
+	from: string,
+	to: string,
+	progress: number,
+): string {
+	const step = Math.round(Math.min(1, Math.max(0, progress)) * COLOUR_STEPS);
+	if (step === 0) return from;
+	if (step === COLOUR_STEPS) return to;
+	return `color-mix(in oklab, ${to} ${(step * 100) / COLOUR_STEPS}%, ${from})`;
+}
+
+/** What a string channel of `node` reads now. */
+export function stringOf(
+	node: SceneNode | undefined,
+	channel: StringChannel,
+): string | undefined {
+	if (node === undefined || node.kind === "group") return undefined;
+	return channel === "d"
+		? node.kind === "path"
+			? node.d
+			: undefined
+		: node.paint[channel];
+}
+
+/** The mix from what was painted to what `node` asks for. */
+export function stringMixer(
+	node: SceneNode,
+	channel: StringChannel,
+	from: string,
+	to: string,
+): (progress: number) => string {
+	if (channel !== "d") {
+		return (progress) => colourBetween(from, to, progress);
+	}
+	const morph = node.kind === "path" ? node.morph : undefined;
+	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);
+}

package/src/core/types.ts

@@ -92,6 +92,12 @@ export interface ChartPaint {
 	readonly strokeOpacity?: number;
 	/** Fill with diagonal hatching in the fill colour: a value pencilled in, not yet true. */
 	readonly hatch?: boolean;
+	/**
+	 * Only the first `fraction` of the stroke is drawn: a line tracing itself
+	 * in. `length` is the path's length in pixels, which Canvas needs for its
+	 * dash and SVG doesn't (it measures with `pathLength`).
+	 */
+	readonly drawn?: { readonly fraction: number; readonly length: number };
 }
 
 export interface ChartTextPaint extends ChartPaint {
@@ -108,8 +114,17 @@ interface SceneNodeBase {
 	readonly series?: string;
 	/** A role for styling and tests: "mark", "axis", "grid", "label"… */
 	readonly role?: string;
+	/** How the node appears when an update adds it: see `ChartEnter`. Fades by default. */
+	readonly enter?: ChartEnter;
 }
 
+/**
+ * How a data mark appears. "grow" rises from its baseline (bars, areas) or
+ * opens from its neighbour (slices); "draw" traces a line in on the first
+ * render; "fade" fades in; "none" is there at once.
+ */
+export type ChartEnter = "grow" | "draw" | "fade" | "none";
+
 export interface SceneGroup extends SceneNodeBase {
 	readonly kind: "group";
 	/** Shifts the children: a facet's cell drawn at its place in the grid. Clips are in the shifted space. */
@@ -125,6 +140,8 @@ export interface SceneRect extends SceneNodeBase {
 	readonly width: number;
 	readonly height: number;
 	readonly corners?: ChartCorners;
+	/** The edge a bar grows from and shrinks back to: `y` for a column, `x` for a bar, in pixels. */
+	readonly baseline?: { readonly axis: "x" | "y"; readonly at: number };
 	readonly paint: ChartPaint;
 }
 
@@ -132,9 +149,90 @@ export interface SceneRect extends SceneNodeBase {
 export interface ScenePath extends SceneNodeBase {
 	readonly kind: "path";
 	readonly d: string;
+	/** What the shape means, when it has a simple meaning: motion moves that, then redraws `d`. */
+	readonly geometry?: SceneGeometry;
+	/**
+	 * How that geometry moves, brought by the mark that drew it (like
+	 * `morph`), so a chart only loads the motion of the shapes it has.
+	 */
+	readonly motion?: GeometryMotion;
 	readonly paint: ChartPaint;
+	/**
+	 * How an update moves this outline into a new one whose commands differ:
+	 * a country, a contour, a cell. Set by the marks whose shapes have no
+	 * simpler meaning, so the morph only loads with them; without it, paths
+	 * whose commands differ swap at the end.
+	 */
+	readonly morph?: PathMorpher;
+}
+
+/** A point of a line, an area or a radar, keyed by its position so an update can slide it. */
+export interface GeometryPoint {
+	readonly key: string;
+	readonly x: number;
+	readonly y: number;
+	/** The area's lower edge under this point. */
+	readonly x0?: number;
+	readonly y0?: number;
+}
+
+export type SceneGeometry =
+	| {
+			readonly kind: "points";
+			/** One run per unbroken stretch: a gap in the data splits the line. */
+			readonly runs: ReadonlyArray<ReadonlyArray<GeometryPoint>>;
+			readonly shape: "line" | "area" | "polygon";
+			readonly curve?: ChartCurve;
+	  }
+	| {
+			readonly kind: "arc";
+			readonly cx: number;
+			readonly cy: number;
+			readonly innerRadius: number;
+			readonly outerRadius: number;
+			readonly startAngle: number;
+			readonly endAngle: number;
+	  };
+
+/**
+ * A geometry in motion: every number it has, by channel name, where each
+ * starts and where it goes, and how to rebuild the shape from the numbers of
+ * one frame. The store springs the numbers; the plan only knows shapes.
+ */
+export interface GeometryPlan {
+	readonly starts: ReadonlyMap<string, number>;
+	readonly targets: ReadonlyMap<string, number>;
+	build(value: (channel: string) => number): SceneGeometry;
 }
 
+/** What the motion store asks of a kind of geometry. */
+export interface GeometryMotion {
+	/** How `from` (what is painted) becomes `to`; undefined to tween the path instead. */
+	plan(from: SceneGeometry, to: SceneGeometry): GeometryPlan | undefined;
+	/** The path data of one frame, through the mark's own builder, so every frame is a valid shape. */
+	draw(geometry: SceneGeometry): string;
+	/** Its length in pixels: what Canvas dashes against to trace a line in. */
+	length?(geometry: SceneGeometry): number;
+	/** The shape a node an update adds grows from; `siblings` is its new list, `known` the old scene. */
+	enter?(
+		node: ScenePath,
+		siblings: readonly SceneNode[],
+		known: ReadonlyMap<string, SceneNode>,
+	): ScenePath | undefined;
+	/** The shape a node an update removes collapses to; `siblings` is its old list, `known` the new scene. */
+	exit?(
+		node: ScenePath,
+		siblings: readonly SceneNode[],
+		known: ReadonlyMap<string, SceneNode>,
+	): ScenePath | undefined;
+}
+
+/** The outlines between two paths, 0 at `from` and 1 at `to`. */
+export type PathMorpher = (
+	from: string,
+	to: string,
+) => (progress: number) => string;
+
 export interface SceneCircle extends SceneNodeBase {
 	readonly kind: "circle";
 	readonly cx: number;

package/src/geo/geo.ts

@@ -1,3 +1,4 @@
+import { mixPath } from "@voila.dev/motion";
 import {
 	type GeoPermissibleObjects,
 	type GeoProjection,
@@ -202,6 +203,7 @@ export function geoShape<TFeature extends Feature>(
 					key: `${id}:${name}`,
 					role: "mark",
 					d,
+					morph: mixPath,
 					paint: paint({
 						fill,
 						stroke: options.stroke ?? context.theme.background,

package/src/react/chart.tsx

@@ -172,9 +172,12 @@ export function Chart({
 		moved: boolean;
 	} | null>(null);
 	const stops = React.useMemo(() => focusStops(scene), [scene]);
+	// A step zoom from the keyboard moves like a data update; the wheel and a
+	// drag are direct manipulation, so they snap.
+	const [keyboardZooms, setKeyboardZooms] = React.useState(0);
 	const animationTrigger = React.useMemo(
-		() => [definition, hidden],
-		[definition, hidden],
+		() => [definition, hidden, keyboardZooms],
+		[definition, hidden, keyboardZooms],
 	);
 	// An inline `animate={{ … }}` object is read by value, not identity.
 	const animateKey = JSON.stringify(animate);
@@ -283,16 +286,19 @@ export function Chart({
 			if (event.key === "+" || event.key === "=") {
 				event.preventDefault();
 				viewport.zoomAround(center, ZOOM_STEP);
+				setKeyboardZooms((count) => count + 1);
 				return;
 			}
 			if (event.key === "-" || event.key === "_") {
 				event.preventDefault();
 				viewport.zoomAround(center, 1 / ZOOM_STEP);
+				setKeyboardZooms((count) => count + 1);
 				return;
 			}
 			if (event.key === "0") {
 				event.preventDefault();
 				viewport.reset();
+				setKeyboardZooms((count) => count + 1);
 				return;
 			}
 			if (

package/src/react/svg-scene.tsx

@@ -53,7 +53,11 @@ function paintProps(
 				: (paint.fill ?? "none"),
 		stroke: paint.stroke,
 		strokeWidth: paint.strokeWidth,
-		strokeDasharray: paint.strokeDasharray,
+		strokeDasharray: paint.drawn ? "1 1" : paint.strokeDasharray,
+		// Measured in path lengths: the dash shows the first `fraction` of the line.
+		...(paint.drawn
+			? { pathLength: 1, strokeDashoffset: 1 - paint.drawn.fraction }
+			: {}),
 		strokeLinecap: paint.strokeLinecap,
 		strokeLinejoin: paint.strokeLinejoin,
 		opacity: paint.opacity,

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

@@ -21,6 +21,9 @@ export function useAnimatedScene(
 ): ChartScene {
 	const [shown, setShown] = React.useState(scene);
 	const triggerRef = React.useRef(trigger);
+	// The first render may play once: lines that `enter: "draw"` trace themselves in.
+	const introduced = React.useRef(false);
+	const introStart = React.useRef<number | null>(null);
 	const storeRef = React.useRef<{
 		store: MotionStore;
 		timing: ChartTiming;
@@ -33,15 +36,28 @@ export function useAnimatedScene(
 			storeRef.current = { store: createMotionStore(scene, timing), timing };
 		}
 		const store = storeRef.current?.store;
-		if (!changed || !timing || !store || shouldReduceMotion()) {
+		const still = !timing || !store || shouldReduceMotion();
+		let intro = false;
+		if (!still && !changed && !introduced.current) {
+			const start = introStart.current ?? performance.now();
+			// A re-render mid-intro (the width measured after mount, fonts loaded): the
+			// new geometry, drawn from where the intro already is, never from scratch.
+			if (introStart.current !== null) store.snap(scene);
+			intro = store.introduce(start);
+			if (intro) introStart.current = start;
+		}
+		if (still || (!changed && !intro)) {
+			introduced.current = true;
 			store?.snap(scene);
 			setShown(scene);
 			return;
 		}
-		store.retarget(scene, performance.now());
+		if (changed) store.retarget(scene, performance.now());
 		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;

package/src/voronoi/voronoi.ts

@@ -1,3 +1,4 @@
+import { mixPath } from "@voila.dev/motion";
 import { Delaunay } from "d3-delaunay";
 import { isPlaceable, readChannel } from "#/core/channel.ts";
 import { markId, valueOn } from "#/core/marks/shared.ts";
@@ -66,6 +67,7 @@ export function voronoi<TDatum>(
 				key: `${id}:${dataIndex}`,
 				role: "mark",
 				d: diagram.renderCell(cell) ?? "",
+				morph: mixPath,
 				paint: options.fill
 					? {
 							fill: options.fill(data[dataIndex], dataIndex),