@voila.dev/chart 4.0.0

package/src/react/use-chart-focus.ts

@@ -0,0 +1,245 @@
+import * as React from "react";
+import type { ChartFocusStop, findNearest } from "#/core/nearest.ts";
+import type { ChartFocusOrder, ChartPoint } from "#/core/types.ts";
+
+/**
+ * Which point the reader is on, by the pointer or the keyboard. Focus is held
+ * by key, not index, so it stays on the same datum when the data updates
+ * around it, and drops cleanly when that datum goes away.
+ */
+interface FocusState {
+	readonly stopKey: string;
+	readonly pointKey: string;
+	readonly source: "pointer" | "keyboard";
+	readonly pinned: boolean;
+}
+
+export interface ActiveFocus {
+	readonly stop: ChartFocusStop;
+	readonly point: ChartPoint;
+	readonly source: "pointer" | "keyboard";
+	readonly pinned: boolean;
+}
+
+interface Options {
+	readonly stops: ReadonlyArray<ChartFocusStop>;
+	readonly order: ChartFocusOrder;
+	readonly hitTest: (x: number, y: number) => ReturnType<typeof findNearest>;
+	readonly onFocusChange?: (point: ChartPoint | null) => void;
+	readonly onSelect?: (point: ChartPoint | null) => void;
+}
+
+/** Points of a stop in screen order across the stop: top to bottom, or left to right. */
+function across(
+	stop: ChartFocusStop,
+	order: ChartFocusOrder,
+): ReadonlyArray<ChartPoint> {
+	return [...stop.points].sort((left, right) =>
+		order === "y" ? left.x - right.x : left.y - right.y,
+	);
+}
+
+const ALONG_KEYS: Record<
+	ChartFocusOrder,
+	{ next: string[]; previous: string[] }
+> = {
+	x: { next: ["ArrowRight"], previous: ["ArrowLeft"] },
+	y: { next: ["ArrowDown"], previous: ["ArrowUp"] },
+	point: {
+		next: ["ArrowRight", "ArrowDown"],
+		previous: ["ArrowLeft", "ArrowUp"],
+	},
+};
+
+const ACROSS_KEYS: Record<
+	ChartFocusOrder,
+	{ next: string[]; previous: string[] }
+> = {
+	x: { next: ["ArrowDown"], previous: ["ArrowUp"] },
+	y: { next: ["ArrowRight"], previous: ["ArrowLeft"] },
+	point: { next: [], previous: [] },
+};
+
+export function useChartFocus({
+	stops,
+	order,
+	hitTest,
+	onFocusChange,
+	onSelect,
+}: Options) {
+	const [state, setState] = React.useState<FocusState | null>(null);
+
+	const active = React.useMemo<ActiveFocus | null>(() => {
+		if (state === null) {
+			return null;
+		}
+		const stop = stops.find((candidate) => candidate.key === state.stopKey);
+		const point = stop?.points.find(
+			(candidate) => candidate.key === state.pointKey,
+		);
+		return stop && point
+			? { stop, point, source: state.source, pinned: state.pinned }
+			: null;
+	}, [state, stops]);
+
+	const activeKey = active?.point.key;
+	const onFocusChangeRef = React.useRef(onFocusChange);
+	onFocusChangeRef.current = onFocusChange;
+	// biome-ignore lint/correctness/useExhaustiveDependencies: fires on a change of point, not on every render
+	React.useEffect(() => {
+		onFocusChangeRef.current?.(active?.point ?? null);
+	}, [activeKey]);
+
+	function focusStop(
+		index: number,
+		source: FocusState["source"],
+		pointIndex = 0,
+	) {
+		const stop = stops[index];
+		if (stop === undefined) {
+			return;
+		}
+		const points = across(stop, order);
+		const point = points[Math.min(pointIndex, points.length - 1)];
+		setState({ stopKey: stop.key, pointKey: point.key, source, pinned: false });
+	}
+
+	function onKeyDown(event: React.KeyboardEvent<HTMLElement>) {
+		if (stops.length === 0) {
+			return;
+		}
+		const stopIndex = active ? stops.indexOf(active.stop) : -1;
+		const along = ALONG_KEYS[order];
+		const crossing = ACROSS_KEYS[order];
+		const { key } = event;
+		let handled = true;
+		if (along.next.includes(key)) {
+			focusStop(
+				stopIndex === -1 ? 0 : Math.min(stops.length - 1, stopIndex + 1),
+				"keyboard",
+			);
+		} else if (along.previous.includes(key)) {
+			focusStop(stopIndex === -1 ? 0 : Math.max(0, stopIndex - 1), "keyboard");
+		} else if (key === "Home") {
+			focusStop(0, "keyboard");
+		} else if (key === "End") {
+			focusStop(stops.length - 1, "keyboard");
+		} else if (
+			active &&
+			(crossing.next.includes(key) || crossing.previous.includes(key))
+		) {
+			const points = across(active.stop, order);
+			const current = points.indexOf(active.point);
+			const step = crossing.next.includes(key) ? 1 : -1;
+			const next =
+				points[Math.min(points.length - 1, Math.max(0, current + step))];
+			setState({
+				stopKey: active.stop.key,
+				pointKey: next.key,
+				source: "keyboard",
+				pinned: false,
+			});
+		} else if ((key === "Enter" || key === " ") && active) {
+			setState({
+				stopKey: active.stop.key,
+				pointKey: active.point.key,
+				source: "keyboard",
+				pinned: !active.pinned,
+			});
+			onSelect?.(active.pinned ? null : active.point);
+		} else if (key === "Escape" && active) {
+			setState(
+				active.pinned
+					? {
+							stopKey: active.stop.key,
+							pointKey: active.point.key,
+							source: "keyboard",
+							pinned: false,
+						}
+					: null,
+			);
+		} else {
+			handled = false;
+		}
+		if (handled) {
+			event.preventDefault();
+		}
+	}
+
+	function localPoint(
+		event: React.PointerEvent<HTMLElement> | React.MouseEvent<HTMLElement>,
+	) {
+		const box = event.currentTarget.getBoundingClientRect();
+		return { x: event.clientX - box.left, y: event.clientY - box.top };
+	}
+
+	function onPointerMove(event: React.PointerEvent<HTMLElement>) {
+		if (active?.pinned) {
+			return;
+		}
+		const { x, y } = localPoint(event);
+		const hit = hitTest(x, y);
+		if (hit === null) {
+			setState(null);
+			return;
+		}
+		const stop = stops[hit.stop];
+		const point = stop.points[hit.point];
+		if (stop.key !== state?.stopKey || point.key !== state?.pointKey) {
+			setState({
+				stopKey: stop.key,
+				pointKey: point.key,
+				source: "pointer",
+				pinned: false,
+			});
+		}
+	}
+
+	function onPointerLeave() {
+		if (!active?.pinned) {
+			setState(null);
+		}
+	}
+
+	function onClick(event: React.MouseEvent<HTMLElement>) {
+		const { x, y } = localPoint(event);
+		const hit = hitTest(x, y);
+		if (hit === null) {
+			setState(null);
+			onSelect?.(null);
+			return;
+		}
+		const stop = stops[hit.stop];
+		const point = stop.points[hit.point];
+		const unpin = active?.pinned === true && active.point.key === point.key;
+		setState({
+			stopKey: stop.key,
+			pointKey: point.key,
+			source: "pointer",
+			pinned: !unpin,
+		});
+		onSelect?.(unpin ? null : point);
+	}
+
+	function onFocus(event: React.FocusEvent<HTMLElement>) {
+		if (state === null && event.currentTarget.matches(":focus-visible")) {
+			focusStop(0, "keyboard");
+		}
+	}
+
+	function onBlur() {
+		setState(null);
+	}
+
+	return {
+		active,
+		handlers: {
+			onKeyDown,
+			onPointerMove,
+			onPointerLeave,
+			onClick,
+			onFocus,
+			onBlur,
+		},
+	};
+}

package/src/react/use-chart-width.ts

@@ -0,0 +1,27 @@
+import * as React from "react";
+
+/**
+ * The container's width. The server and the first client render use
+ * `initialWidth`, so the hydrated markup matches; the real width arrives on
+ * the first observer callback.
+ */
+export function useChartWidth(initialWidth: number) {
+	const [node, setNode] = React.useState<HTMLDivElement | null>(null);
+	const [width, setWidth] = React.useState(initialWidth);
+
+	React.useEffect(() => {
+		if (node === null || typeof ResizeObserver === "undefined") {
+			return;
+		}
+		const observer = new ResizeObserver((entries) => {
+			const measured = entries[0]?.contentRect.width;
+			if (measured !== undefined && measured > 0) {
+				setWidth(Math.round(measured));
+			}
+		});
+		observer.observe(node);
+		return () => observer.disconnect();
+	}, [node]);
+
+	return { ref: setNode, width, node };
+}

package/src/react/use-chart-zoom.ts

@@ -0,0 +1,67 @@
+import * as React from "react";
+
+/** The narrowest view: a hundredth of the data. */
+const MAX_ZOOM = 100;
+
+function clampDomain(
+	[from, to]: readonly [number, number],
+	[low, high]: readonly [number, number],
+): readonly [number, number] {
+	const span = Math.min(
+		high - low,
+		Math.max((high - low) / MAX_ZOOM, to - from),
+	);
+	const start = Math.min(Math.max(from, low), high - span);
+	return [start, start + span];
+}
+
+/**
+ * The part of a continuous x axis on show. `null` is the whole of it. Zooming
+ * keeps the value under the pointer (or the focused value) where it is on
+ * screen; panning never leaves the data.
+ */
+export function useChartZoom(
+	full: readonly [number, number] | undefined,
+	resetKey: unknown,
+) {
+	const [domain, setDomain] = React.useState<readonly [number, number] | null>(
+		null,
+	);
+	const keyRef = React.useRef(resetKey);
+	if (keyRef.current !== resetKey) {
+		keyRef.current = resetKey;
+		if (domain !== null) {
+			setDomain(null);
+		}
+	}
+
+	function apply(next: readonly [number, number]) {
+		if (full === undefined) return;
+		const clamped = clampDomain(next, full);
+		setDomain(clamped[0] <= full[0] && clamped[1] >= full[1] ? null : clamped);
+	}
+
+	function zoomAround(center: number, factor: number) {
+		if (full === undefined) return;
+		const [from, to] = domain ?? full;
+		const share = to === from ? 0.5 : (center - from) / (to - from);
+		const span = (to - from) * factor;
+		apply([center - span * share, center - span * share + span]);
+	}
+
+	function pan(delta: number) {
+		if (full === undefined || domain === null) return;
+		apply([domain[0] + delta, domain[1] + delta]);
+	}
+
+	return {
+		domain,
+		zoomAround,
+		pan,
+		reset: () => setDomain(null),
+		span: () => {
+			const [from, to] = domain ?? full ?? [0, 1];
+			return to - from;
+		},
+	};
+}

package/src/react/use-text-measurer.ts

@@ -0,0 +1,49 @@
+import * as React from "react";
+import { estimateTextWidth } from "#/core/text.ts";
+import type { ChartTextMeasurer } from "#/core/types.ts";
+
+/**
+ * Real text metrics once mounted. Until then, and on the server, the estimate
+ * — the same on both sides, so hydration never sees a different layout. A web
+ * font that finishes loading later triggers one more measure.
+ */
+export function useTextMeasurer(node: HTMLElement | null): ChartTextMeasurer {
+	const [measurer, setMeasurer] = React.useState<ChartTextMeasurer>(
+		() => estimateTextWidth,
+	);
+
+	React.useEffect(() => {
+		if (node === null || typeof document === "undefined") {
+			return;
+		}
+		const context = document.createElement("canvas").getContext("2d");
+		if (context === null) {
+			return;
+		}
+		function install() {
+			if (node === null || context === null) {
+				return;
+			}
+			const family = getComputedStyle(node).fontFamily || "sans-serif";
+			const cache = new Map<string, number>();
+			const measure: ChartTextMeasurer = (text, fontSize, fontWeight = 400) => {
+				const key = `${fontWeight}:${fontSize}:${text}`;
+				const cached = cache.get(key);
+				if (cached !== undefined) {
+					return cached;
+				}
+				context.font = `${fontWeight} ${fontSize}px ${family}`;
+				const width = context.measureText(text).width;
+				cache.set(key, width);
+				return width;
+			};
+			setMeasurer(() => measure);
+		}
+		install();
+		const fonts = document.fonts;
+		fonts?.addEventListener?.("loadingdone", install);
+		return () => fonts?.removeEventListener?.("loadingdone", install);
+	}, [node]);
+
+	return measurer;
+}

package/src/sankey/index.ts

@@ -0,0 +1,6 @@
+export {
+	type SankeyLink,
+	type SankeyNode,
+	type SankeyOptions,
+	sankey,
+} from "#/sankey/sankey.ts";

package/src/sankey/sankey.ts

@@ -0,0 +1,179 @@
+import { sankey as sankeyLayout, sankeyLinkHorizontal } from "d3-sankey";
+import { markId } from "#/core/marks/shared.ts";
+import type { ChartMark, ChartPoint, SceneNode } from "#/core/types.ts";
+
+export interface SankeyNode {
+	readonly id: string;
+	/** Display name. Defaults to the id. */
+	readonly label?: string;
+}
+
+export interface SankeyLink {
+	readonly source: string;
+	readonly target: string;
+	readonly value: number;
+}
+
+export interface SankeyOptions {
+	readonly id?: string;
+	readonly nodeWidth?: number;
+	readonly nodePadding?: number;
+	/** What the flows are, for the table heading. */
+	readonly label?: string;
+	readonly tip?: boolean;
+}
+
+interface LaidNode extends SankeyNode {
+	x0?: number;
+	x1?: number;
+	y0?: number;
+	y1?: number;
+	value?: number;
+}
+
+interface LaidLink {
+	source: LaidNode;
+	target: LaidNode;
+	value: number;
+	width?: number;
+	y0?: number;
+	y1?: number;
+}
+
+const LABEL_GAP = 6;
+
+/**
+ * Flows between stages: each node as tall as what passes through it, each
+ * link as wide as its flow. Nodes and links are both focusable, so the
+ * keyboard reaches "Inscriptions → Missions: 240" as well as each stage.
+ */
+export function sankey(
+	data: {
+		readonly nodes: ReadonlyArray<SankeyNode>;
+		readonly links: ReadonlyArray<SankeyLink>;
+	},
+	options: SankeyOptions = {},
+): ChartMark {
+	const names = new Map(
+		data.nodes.map((node) => [node.id, node.label ?? node.id]),
+	);
+	return {
+		id: options.id,
+		coordinate: "frame",
+		focusOrder: "point",
+		titles: { value: options.label },
+		channels: {
+			color: { values: data.nodes.map((node) => node.label ?? node.id) },
+		},
+		colorLegend: false,
+		render(context) {
+			const id = markId(options.id, "sankey", context);
+			const { plot, theme, measureText } = context;
+			const widest = Math.max(
+				0,
+				...[...names.values()].map((name) => measureText(name, theme.fontSize)),
+			);
+			const layout = sankeyLayout<LaidNode, LaidLink>()
+				.nodeId((node) => node.id)
+				.nodeWidth(options.nodeWidth ?? 12)
+				.nodePadding(options.nodePadding ?? 12)
+				.extent([
+					[plot.x, plot.y],
+					[plot.x + plot.width - widest - LABEL_GAP, plot.y + plot.height],
+				]);
+			const graph = layout({
+				nodes: data.nodes.map((node) => ({ ...node })),
+				links: data.links.map((link) => ({ ...link })) as unknown as LaidLink[],
+			});
+			const path = sankeyLinkHorizontal<LaidNode, LaidLink>();
+			const nodes: SceneNode[] = [];
+			const points: ChartPoint[] = [];
+			for (const [index, link] of graph.links.entries()) {
+				const from = names.get(link.source.id) ?? link.source.id;
+				const to = names.get(link.target.id) ?? link.target.id;
+				nodes.push({
+					kind: "path",
+					key: `${id}:link:${link.source.id}:${link.target.id}`,
+					series: from,
+					role: "mark",
+					d: path(link as never) ?? "",
+					paint: {
+						fill: "none",
+						stroke: context.colorOf(from),
+						strokeOpacity: 0.35,
+						strokeWidth: Math.max(1, link.width ?? 1),
+					},
+				});
+				if (options.tip !== false) {
+					points.push({
+						key: `${id}:link:${link.source.id}:${link.target.id}`,
+						markId: id,
+						index,
+						datum: link,
+						x: ((link.source.x1 ?? 0) + (link.target.x0 ?? 0)) / 2,
+						y: ((link.y0 ?? 0) + (link.y1 ?? 0)) / 2,
+						xValue: `${from} → ${to}`,
+						yValue: link.value,
+						seriesLabel: options.label,
+						color: context.colorOf(from),
+						title: `${from} → ${to}`,
+						value: context.formatY(link.value),
+					});
+				}
+			}
+			for (const [index, node] of graph.nodes.entries()) {
+				const name = names.get(node.id) ?? node.id;
+				const rect = {
+					x: node.x0 ?? 0,
+					y: node.y0 ?? 0,
+					width: (node.x1 ?? 0) - (node.x0 ?? 0),
+					height: Math.max(1, (node.y1 ?? 0) - (node.y0 ?? 0)),
+				};
+				nodes.push(
+					{
+						kind: "rect",
+						key: `${id}:node:${node.id}`,
+						series: name,
+						role: "mark",
+						...rect,
+						paint: { fill: context.colorOf(name) },
+					},
+					{
+						kind: "text",
+						key: `${id}:label:${node.id}`,
+						role: "label",
+						x: rect.x + rect.width + LABEL_GAP,
+						y: rect.y + rect.height / 2,
+						text: name,
+						paint: {
+							fill: theme.foreground,
+							fontSize: theme.fontSize,
+							baseline: "middle",
+						},
+					},
+				);
+				if (options.tip !== false) {
+					points.push({
+						key: `${id}:node:${node.id}`,
+						markId: id,
+						index: graph.links.length + index,
+						datum: node,
+						x: rect.x + rect.width / 2,
+						y: rect.y + rect.height / 2,
+						xValue: name,
+						yValue: node.value ?? 0,
+						seriesLabel: options.label,
+						color: context.colorOf(name),
+						title: name,
+						value: context.formatY(node.value ?? 0),
+						hit: {
+							kind: "rect",
+							rect: { ...rect, x: rect.x - 4, width: rect.width + 8 },
+						},
+					});
+				}
+			}
+			return { nodes, points };
+		},
+	};
+}

package/src/voronoi/index.ts

@@ -0,0 +1 @@
+export { type VoronoiOptions, voronoi } from "#/voronoi/voronoi.ts";

package/src/voronoi/voronoi.ts

@@ -0,0 +1,84 @@
+import { Delaunay } from "d3-delaunay";
+import { isPlaceable, readChannel } from "#/core/channel.ts";
+import { markId, valueOn } from "#/core/marks/shared.ts";
+import type {
+	ChartAccessor,
+	ChartMark,
+	ChartValue,
+	SceneNode,
+} from "#/core/types.ts";
+
+export interface VoronoiOptions<TDatum> {
+	readonly id?: string;
+	readonly x: ChartAccessor<TDatum, ChartValue>;
+	readonly y: ChartAccessor<TDatum, ChartValue>;
+	readonly stroke?: string;
+	/** Fill each cell, by its own colour, instead of drawing the borders only. */
+	readonly fill?: (datum: TDatum, index: number) => string;
+}
+
+/**
+ * Each point's cell: the area closer to it than to any other. Clipped to the
+ * plot. The borders alone read as a mesh over a scatter; filled, the cells
+ * become territories.
+ */
+export function voronoi<TDatum>(
+	data: ReadonlyArray<TDatum>,
+	options: VoronoiOptions<TDatum>,
+): ChartMark {
+	const xs = readChannel(data, options.x);
+	const ys = readChannel(data, options.y);
+	return {
+		id: options.id,
+		coordinate: "cartesian",
+		channels: {
+			x: { values: xs.filter(isPlaceable) },
+			y: { values: ys.filter(isPlaceable) },
+		},
+		render(context) {
+			const id = markId(options.id, "voronoi", context);
+			const { x: xScale, y: yScale } = context.scales;
+			if (xScale === undefined || yScale === undefined) {
+				return { nodes: [] };
+			}
+			const { plot } = context;
+			const indices: number[] = [];
+			const pixels: Array<[number, number]> = [];
+			for (const [index, raw] of xs.entries()) {
+				const x = valueOn(xScale, raw);
+				const y = valueOn(yScale, ys[index]);
+				if (x !== undefined && y !== undefined) {
+					indices.push(index);
+					pixels.push([xScale.center(x), yScale.center(y)]);
+				}
+			}
+			if (pixels.length === 0) {
+				return { nodes: [] };
+			}
+			const diagram = Delaunay.from(pixels).voronoi([
+				plot.x,
+				plot.y,
+				plot.x + plot.width,
+				plot.y + plot.height,
+			]);
+			const nodes: SceneNode[] = indices.map((dataIndex, cell) => ({
+				kind: "path",
+				key: `${id}:${dataIndex}`,
+				role: "mark",
+				d: diagram.renderCell(cell) ?? "",
+				paint: options.fill
+					? {
+							fill: options.fill(data[dataIndex], dataIndex),
+							stroke: context.theme.background,
+							strokeWidth: 1,
+						}
+					: {
+							fill: "none",
+							stroke: options.stroke ?? context.theme.grid,
+							strokeWidth: 1,
+						},
+			}));
+			return { nodes };
+		},
+	};
+}