@voila.dev/chart 5.0.113 → 5.0.117

package/src/core/motion/timing.ts

@@ -0,0 +1,63 @@
+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;
+	  };
+
+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;
+}
+
+const DEFAULT_DURATION = 300;
+const MAX_STAGGER_TOTAL = 0.3;
+
+/** The timing an `animate` prop means, or `null` to snap. */
+export function chartTiming(
+	animate: boolean | number | ChartAnimation,
+): ChartTiming | null {
+	if (animate === false || animate === 0) return null;
+	const options: ChartAnimation =
+		typeof animate === "object"
+			? animate
+			: { duration: animate === true ? DEFAULT_DURATION : animate };
+	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,
+	};
+}
+
+/** The delay of the `index`-th of `count` marks: the gap shrinks so the last one never waits more than 300 ms. */
+export function staggerDelay(
+	timing: ChartTiming,
+	index: number,
+	count: number,
+): number {
+	if (timing.stagger === 0 || count < 2) return 0;
+	return index * Math.min(timing.stagger, MAX_STAGGER_TOTAL / (count - 1));
+}

package/src/core/motion/tween.ts

@@ -19,7 +19,7 @@ function mix(from: number, to: number, t: number): number {
 }
 
 /** Two paths can tween when only their numbers differ. */
-function tweenPath(from: string, to: string, t: number): string {
+export function tweenPath(from: string, to: string, t: number): string {
 	const fromNumbers = from.match(NUMBER);
 	const toNumbers = to.match(NUMBER);
 	if (

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/index.ts

@@ -60,6 +60,15 @@ export {
 export { type WaffleOptions, waffleY } from "#/core/marks/stats/waffle.ts";
 export { type TextOptions, text } from "#/core/marks/text.ts";
 export { type TickOptions, tickX, tickY } from "#/core/marks/tick.ts";
+export {
+	createMotionStore,
+	type MotionStore,
+} from "#/core/motion/motion-store.ts";
+export {
+	type ChartAnimation,
+	type ChartTiming,
+	chartTiming,
+} from "#/core/motion/timing.ts";
 export { easeOutCubic, tweenScene } from "#/core/motion/tween.ts";
 export {
 	type ChartFocusStop,

package/src/react/chart.tsx

@@ -1,6 +1,7 @@
 import * as React from "react";
 import { compileChart } from "#/core/compile.ts";
 import type { ChartDefinition } from "#/core/define-chart.ts";
+import { type ChartAnimation, chartTiming } from "#/core/motion/timing.ts";
 import { findNearest, focusStops } from "#/core/nearest.ts";
 import { toNumber } from "#/core/scales/continuous.ts";
 import type { ChartPoint } from "#/core/types.ts";
@@ -29,7 +30,6 @@ import { useTextMeasurer } from "#/react/use-text-measurer.ts";
 
 const DEFAULT_HEIGHT = 300;
 const DEFAULT_INITIAL_WIDTH = 640;
-const DEFAULT_DURATION = 300;
 
 /** Focus ring, forced colours and reduced motion: what inline styles cannot say. */
 const CHART_CSS = `
@@ -69,8 +69,12 @@ interface Props
 	readonly legend?: boolean;
 	/** The visually hidden table of the values. On by default; turn it off only when the page shows the same table. */
 	readonly dataTable?: boolean;
-	/** Tween a data update, in milliseconds; `false` snaps. Reduced motion always snaps. */
-	readonly animate?: boolean | number;
+	/**
+	 * 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.
+	 */
+	readonly animate?: boolean | number | ChartAnimation;
 	/**
 	 * Zoom a continuous x: the wheel while the chart has focus, + and −,
 	 * Shift and the arrows to pan, a drag to pan when zoomed, 0 to reset.
@@ -168,15 +172,20 @@ 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],
 	);
-	const shown = useAnimatedScene(
-		scene,
-		animationTrigger,
-		animate === false ? 0 : animate === true ? DEFAULT_DURATION : animate,
+	// An inline `animate={{ … }}` object is read by value, not identity.
+	const animateKey = JSON.stringify(animate);
+	const timing = React.useMemo(
+		() => chartTiming(JSON.parse(animateKey)),
+		[animateKey],
 	);
+	const shown = useAnimatedScene(scene, animationTrigger, timing);
 	const messages = messagesFor(scene.locale);
 	const { active, handlers } = useChartFocus({
 		stops,
@@ -277,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

@@ -1,57 +1,73 @@
+import { cancelFrame, frame, shouldReduceMotion } from "@voila.dev/motion";
 import * as React from "react";
-import { easeOutCubic, tweenScene } from "#/core/motion/tween.ts";
+import {
+	createMotionStore,
+	type MotionStore,
+} from "#/core/motion/motion-store.ts";
+import type { ChartTiming } from "#/core/motion/timing.ts";
 import type { ChartScene } from "#/core/types.ts";
 
-function prefersReducedMotion(): boolean {
-	return (
-		typeof window !== "undefined" &&
-		window.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true
-	);
-}
-
 /**
  * The scene to draw this frame. A data change (`trigger` changed: a new
- * definition, a series toggled) tweens from what is on screen to the new
- * scene; a resize snaps, since watching bars slide while a window is dragged
- * helps no one. Reduced motion always snaps. An update that lands mid-tween
- * starts from the frame already painted, so nothing jumps.
+ * definition, a series toggled) moves from what is on screen to the new
+ * scene on springs; one landing mid-flight keeps every node's speed. A
+ * resize snaps, since watching bars slide while a window is dragged helps no
+ * one. Reduced motion always snaps.
  */
 export function useAnimatedScene(
 	scene: ChartScene,
 	trigger: unknown,
-	duration: number,
+	timing: ChartTiming | null,
 ): ChartScene {
 	const [shown, setShown] = React.useState(scene);
-	const shownRef = React.useRef(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;
+	} | null>(null);
 
 	React.useLayoutEffect(() => {
 		const changed = triggerRef.current !== trigger;
 		triggerRef.current = trigger;
-		if (!changed || duration <= 0 || prefersReducedMotion()) {
-			shownRef.current = scene;
+		if (timing && storeRef.current?.timing !== timing) {
+			storeRef.current = { store: createMotionStore(scene, timing), timing };
+		}
+		const store = storeRef.current?.store;
+		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;
 		}
-		const from = shownRef.current;
-		// Frame zero now, before paint: nodes that left are gone at once.
-		const first = tweenScene(from, scene, 0);
-		shownRef.current = first;
-		setShown(first);
-		const start = performance.now();
-		let frame = 0;
-		function step(now: number) {
-			const t = Math.min(1, (now - start) / duration);
-			const next = tweenScene(from, scene, easeOutCubic(t));
-			shownRef.current = next;
-			setShown(next);
-			if (t < 1) {
-				frame = requestAnimationFrame(step);
+		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;
 			}
+			setShown(store?.frame(now) ?? scene);
 		}
-		frame = requestAnimationFrame(step);
-		return () => cancelAnimationFrame(frame);
-	}, [scene, trigger, duration]);
+		tick();
+		frame.update(tick, true);
+		return () => cancelFrame(tick);
+	}, [scene, trigger, timing]);
 
 	return shown;
 }

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),