@voila.dev/chart 5.0.113 → 5.0.117

package/src/core/marks/polar.ts

@@ -12,6 +12,8 @@ import {
 	seriesResolver,
 	tips,
 } from "#/core/marks/shared.ts";
+import { ARC_MOTION } from "#/core/motion/arc-motion.ts";
+import { POINTS_MOTION } from "#/core/motion/points-motion.ts";
 import {
 	arcPath,
 	type ChartXY,
@@ -181,6 +183,9 @@ export function arc<TDatum>(
 					series: series.key,
 					role: "mark",
 					d: arcPath(shape),
+					geometry: { kind: "arc", ...shape },
+					motion: ARC_MOTION,
+					enter: options.enter ?? "grow",
 					paint: paint({
 						fill: series.color,
 						stroke: options.stroke ?? context.theme.background,
@@ -306,6 +311,9 @@ export function radialBar<TDatum>(
 					series: series.key,
 					role: "mark",
 					d: arcPath(shape),
+					geometry: { kind: "arc", ...shape },
+					motion: ARC_MOTION,
+					enter: options.enter ?? "grow",
 					paint: paint({ fill: series.color, opacity: options.opacity }),
 				});
 				if (!tips(options.tip, data[index], index)) {
@@ -532,16 +540,25 @@ export function radar<TDatum>(
 				}
 			}
 			for (const [key, polygon] of polygons) {
+				const geometry = {
+					kind: "points" as const,
+					shape: "polygon" as const,
+					runs: [
+						polygon.vertices.map((vertex, spoke) => ({
+							key: categoryKey(axes[spoke] as ChartValue),
+							...(vertex ?? { x: frame.cx, y: frame.cy }),
+						})),
+					],
+				};
 				nodes.push({
 					kind: "path",
 					key: `${id}:shape:${key}`,
 					series: key,
 					role: "mark",
-					d: polygonPath(
-						polygon.vertices.map(
-							(vertex) => vertex ?? { x: frame.cx, y: frame.cy },
-						),
-					),
+					d: polygonPath(geometry.runs[0]),
+					geometry,
+					motion: POINTS_MOTION,
+					enter: options.enter,
 					paint: paint({
 						fill: polygon.color,
 						fillOpacity: options.fillOpacity ?? 0.2,

package/src/core/marks/shared.ts

@@ -8,6 +8,7 @@ import { categoryKey } from "#/core/scales/discrete.ts";
 import type {
 	ChartAccessor,
 	ChartChannel,
+	ChartEnter,
 	ChartMarkContext,
 	ChartPaint,
 	ChartPositionScale,
@@ -29,6 +30,13 @@ export interface ChartMarkOptions<TDatum> {
 	 */
 	readonly tip?: boolean | ((datum: TDatum, index: number) => boolean);
 	readonly opacity?: number;
+	/**
+	 * How the mark appears when an update adds it: "grow" from its baseline
+	 * or neighbour (the default for bars, areas and slices), "fade" (the
+	 * default otherwise), "none". A line can also "draw": trace itself in on
+	 * the first render.
+	 */
+	readonly enter?: ChartEnter;
 }
 
 export function markId(

package/src/core/marks/stats/difference.ts

@@ -5,12 +5,16 @@ import {
 	readChannel,
 } from "#/core/channel.ts";
 import { markId, paint, valueOn } from "#/core/marks/shared.ts";
-import { areaPath, type ChartXY, linePath } from "#/core/paths.ts";
+import { POINTS_MOTION, pointsPath } from "#/core/motion/points-motion.ts";
+import { areaPath, type ChartXY } from "#/core/paths.ts";
+import { categoryKey } from "#/core/scales/discrete.ts";
 import type {
 	ChartAccessor,
 	ChartMark,
 	ChartPoint,
 	ChartValue,
+	GeometryMotion,
+	SceneGeometry,
 	SceneNode,
 } from "#/core/types.ts";
 
@@ -34,6 +38,25 @@ interface Sample {
 	readonly bottom: number;
 }
 
+/** One of the two lines, keyed by x so an update slides it like any line. */
+function keyedLine(
+	samples: readonly (Sample & { readonly key: string })[],
+	edge: "top" | "bottom",
+): { d: string; geometry: SceneGeometry; motion: GeometryMotion } {
+	const geometry: SceneGeometry = {
+		kind: "points",
+		shape: "line",
+		runs: [
+			samples.map((sample) => ({
+				key: sample.key,
+				x: sample.x,
+				y: sample[edge],
+			})),
+		],
+	};
+	return { d: pointsPath(geometry), geometry, motion: POINTS_MOTION };
+}
+
 /** Splits the band between two lines into runs of one sign, cut where they cross. */
 function signRuns(
 	samples: ReadonlyArray<Sample>,
@@ -99,7 +122,7 @@ export function differenceY<TDatum>(
 			}
 			const positive = options.positiveFill ?? context.paletteColor(1);
 			const negative = options.negativeFill ?? context.paletteColor(0);
-			const samples: Sample[] = [];
+			const samples: Array<Sample & { readonly key: string }> = [];
 			const points: ChartPoint[] = [];
 			for (const [index, raw] of xs.entries()) {
 				const x = valueOn(xScale, raw);
@@ -107,6 +130,7 @@ export function differenceY<TDatum>(
 				const b = second[index];
 				if (x === undefined || a === undefined || b === undefined) continue;
 				const sample = {
+					key: categoryKey(x),
 					x: xScale.center(x),
 					top: yScale.map(a),
 					bottom: yScale.map(b),
@@ -157,9 +181,7 @@ export function differenceY<TDatum>(
 					key: `${id}:line:y1`,
 					series: `${id}:y1`,
 					role: "mark",
-					d: linePath(
-						samples.map((sample) => ({ x: sample.x, y: sample.top })),
-					),
+					...keyedLine(samples, "top"),
 					paint: {
 						fill: "none",
 						stroke: context.theme.foreground,
@@ -171,9 +193,7 @@ export function differenceY<TDatum>(
 					key: `${id}:line:y2`,
 					series: `${id}:y2`,
 					role: "mark",
-					d: linePath(
-						samples.map((sample) => ({ x: sample.x, y: sample.bottom })),
-					),
+					...keyedLine(samples, "bottom"),
 					paint: {
 						fill: "none",
 						stroke: context.theme.muted,

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

@@ -0,0 +1,113 @@
+import { arcPath } from "#/core/paths.ts";
+import type {
+	GeometryMotion,
+	GeometryPlan,
+	SceneGeometry,
+	SceneNode,
+	ScenePath,
+} from "#/core/types.ts";
+
+type Arc = Extract<SceneGeometry, { kind: "arc" }>;
+
+const ARC_FIELDS = [
+	"cx",
+	"cy",
+	"innerRadius",
+	"outerRadius",
+	"startAngle",
+	"endAngle",
+] as const;
+
+function arcOf(node: SceneNode | undefined): Arc | undefined {
+	return node?.kind === "path" && node.geometry?.kind === "arc"
+		? node.geometry
+		: undefined;
+}
+
+/** Slices of one ring tile it: those are the neighbours a slice opens from and closes onto. */
+function sameRing(a: Arc, b: Arc): boolean {
+	return (
+		a.cx === b.cx &&
+		a.cy === b.cy &&
+		a.innerRadius === b.innerRadius &&
+		a.outerRadius === b.outerRadius
+	);
+}
+
+function withAngle(node: ScenePath, arc: Arc, angle: number): ScenePath {
+	return { ...node, geometry: { ...arc, startAngle: angle, endAngle: angle } };
+}
+
+/**
+ * The boundary angle next to `node` among the slices of its ring in `order`,
+ * read from `known`: the end of the nearest one before it, or the start of the
+ * nearest one after it, whichever side `afterFirst` looks at first.
+ */
+function boundary(
+	node: SceneNode,
+	order: readonly SceneNode[],
+	known: ReadonlyMap<string, SceneNode>,
+	arc: Arc,
+	afterFirst: boolean,
+): number {
+	const index = order.findIndex((other) => other.key === node.key);
+	function scan(step: -1 | 1): number | undefined {
+		for (let at = index + step; at >= 0 && at < order.length; at += step) {
+			const other = arcOf(known.get((order[at] as SceneNode).key));
+			if (other && sameRing(other, arc)) {
+				return step === 1 ? other.startAngle : other.endAngle;
+			}
+		}
+		return undefined;
+	}
+	const [first, second] = afterFirst ? ([1, -1] as const) : ([-1, 1] as const);
+	return scan(first) ?? scan(second) ?? arc.startAngle;
+}
+
+function arcPlan(from: Arc, to: Arc): GeometryPlan {
+	function record(arc: Arc) {
+		return new Map<string, number>(
+			ARC_FIELDS.map((field) => [field, arc[field]]),
+		);
+	}
+	return {
+		starts: record(from),
+		targets: record(to),
+		build(value) {
+			const arc = { kind: "arc" } as Record<string, unknown>;
+			for (const field of ARC_FIELDS) arc[field] = value(field);
+			return arc as Arc;
+		},
+	};
+}
+
+/**
+ * Slices and radial bars: their angles and radii move, and the arc is
+ * rebuilt each frame, so its large-arc flag is never wrong. A new slice opens
+ * from the boundary where it will sit; a removed one closes onto the slice
+ * after it.
+ */
+export const ARC_MOTION: GeometryMotion = {
+	plan: (from, to) =>
+		from.kind === "arc" && to.kind === "arc" ? arcPlan(from, to) : undefined,
+	draw: (geometry) =>
+		geometry.kind === "arc"
+			? arcPath({
+					...geometry,
+					endAngle: Math.max(geometry.startAngle, geometry.endAngle),
+				})
+			: "",
+	enter(node, siblings, before) {
+		const arc = arcOf(node);
+		return node.enter === "grow" && arc
+			? withAngle(node, arc, boundary(node, siblings, before, arc, false))
+			: undefined;
+	},
+	exit(node, siblings, after) {
+		const arc = arcOf(node);
+		// A slice closes onto the one after it, so it takes that one's new start.
+		return node.enter === "grow" && arc
+			? withAngle(node, arc, boundary(node, siblings, after, arc, true))
+			: undefined;
+	},
+};

package/src/core/motion/enter-exit.ts

@@ -0,0 +1,44 @@
+import type { SceneNode, SceneRect } from "#/core/types.ts";
+
+/**
+ * The shape a data mark grows from when an update adds it, and collapses to
+ * when an update removes it. Always a node of the same kind, so the store
+ * springs it like any other change. Undefined when the mark has no such
+ * shape: it fades in, and is gone at once when it leaves. A bar has its
+ * baseline; a path asks the motion its mark brought (a slice opens from its
+ * neighbour, an area grows from its lower edge).
+ */
+
+function collapsedBar(node: SceneRect): SceneRect | undefined {
+	const { baseline } = node;
+	if (!baseline) return undefined;
+	return baseline.axis === "y"
+		? { ...node, y: baseline.at, height: 0 }
+		: { ...node, x: baseline.at, width: 0 };
+}
+
+/** Where a node an update adds starts from. `siblings` is the list it sits in, `before` the old scene. */
+export function enterFrom(
+	node: SceneNode,
+	siblings: readonly SceneNode[],
+	before: ReadonlyMap<string, SceneNode>,
+): SceneNode | undefined {
+	if (node.enter !== "grow") return undefined;
+	if (node.kind === "rect") return collapsedBar(node);
+	return node.kind === "path"
+		? node.motion?.enter?.(node, siblings, before)
+		: undefined;
+}
+
+/** Where a node an update removes collapses to. `siblings` is the old list it sat in, `after` the new scene. */
+export function exitTo(
+	node: SceneNode,
+	siblings: readonly SceneNode[],
+	after: ReadonlyMap<string, SceneNode>,
+): SceneNode | undefined {
+	if (node.enter !== "grow") return undefined;
+	if (node.kind === "rect") return collapsedBar(node);
+	return node.kind === "path"
+		? node.motion?.exit?.(node, siblings, after)
+		: undefined;
+}

package/src/core/motion/leaving.ts

@@ -0,0 +1,55 @@
+import type { SceneNode } from "#/core/types.ts";
+
+/**
+ * Guides that left the scene still fade out where they stood: a tick label
+ * or a grid line vanishing at once reads as a glitch. Data marks never
+ * linger — a bar the data no longer has would show a value that isn't true.
+ */
+const GUIDE_ROLES = new Set(["grid", "axis"]);
+
+export interface LeavingGuide {
+	readonly node: SceneNode;
+	/** The group it sat in, or null at the root. */
+	readonly parent: string | null;
+	readonly index: number;
+}
+
+/** The guides of `nodes` whose keys `stays` no longer has. */
+export function leavingGuides(
+	nodes: readonly SceneNode[],
+	stays: (key: string) => boolean,
+	parent: string | null = null,
+	into: LeavingGuide[] = [],
+): LeavingGuide[] {
+	for (const [index, node] of nodes.entries()) {
+		if (node.kind === "group") {
+			leavingGuides(node.children, stays, node.key, into);
+			continue;
+		}
+		if (!stays(node.key) && GUIDE_ROLES.has(node.role ?? "")) {
+			into.push({ node, parent, index });
+		}
+	}
+	return into;
+}
+
+/** `children` with the leaving guides of `parent` back at their places, faded to `opacity`. */
+export function withLeaving(
+	children: readonly SceneNode[],
+	parent: string | null,
+	leaving: ReadonlyArray<readonly [LeavingGuide, number]>,
+): SceneNode[] {
+	const placed = [...children];
+	for (const [guide, opacity] of leaving) {
+		if (guide.parent !== parent || guide.node.kind === "group") continue;
+		const faded = {
+			...guide.node,
+			paint: {
+				...guide.node.paint,
+				opacity: (guide.node.paint.opacity ?? 1) * opacity,
+			},
+		} as SceneNode;
+		placed.splice(Math.min(guide.index, placed.length), 0, faded);
+	}
+	return placed;
+}