@voila.dev/chart 4.0.0

package/src/core/theme.ts

@@ -0,0 +1,26 @@
+import type { ChartTheme } from "#/core/types.ts";
+
+/** What the palette falls back to on a page without the kit's `--chart-N` tokens. */
+const FALLBACK_PALETTE = [
+	"oklch(0.646 0.222 41.116)",
+	"oklch(0.6 0.118 184.704)",
+	"oklch(0.398 0.07 227.392)",
+	"oklch(0.828 0.189 84.429)",
+	"oklch(0.769 0.188 70.08)",
+];
+
+/**
+ * Every colour is a CSS variable with a fallback, so a chart picks up the
+ * kit's tokens (`--chart-1`…, `--muted-foreground`, `--border`) when the page
+ * has them and still draws legibly when it does not.
+ */
+export const DEFAULT_THEME: ChartTheme = {
+	palette: FALLBACK_PALETTE.map(
+		(fallback, index) => `var(--chart-${index + 1}, ${fallback})`,
+	),
+	foreground: "var(--foreground, currentColor)",
+	muted: "var(--muted-foreground, currentColor)",
+	grid: "var(--border, color-mix(in oklab, currentColor 15%, transparent))",
+	background: "var(--background, Canvas)",
+	fontSize: 12,
+};

package/src/core/ticks.ts

@@ -0,0 +1,118 @@
+/**
+ * Round tick values for a continuous axis. The step is always 1, 2, 5 or 10
+ * times a power of ten, which is what makes an axis readable: 0/25/50/75/100
+ * rather than 0/23.4/46.8.
+ */
+
+/** Steps the eye reads as round, in units of the current power of ten. */
+const NICE_FACTORS = [
+	{ threshold: Math.SQRT2, factor: 1 },
+	{ threshold: Math.sqrt(10), factor: 2 },
+	{ threshold: Math.sqrt(50), factor: 5 },
+] as const;
+
+const DEFAULT_TICK_COUNT = 5;
+/** Beyond this many decimals the rounding helper stops fighting IEEE noise. */
+const MAX_TICK_PRECISION = 12;
+
+/**
+ * Drops the floating-point dust `i * step` leaves behind (0.30000000000000004)
+ * by rounding to the number of decimals the step itself carries.
+ */
+function roundToStep(value: number, step: number): number {
+	if (step === 0 || !Number.isFinite(step)) {
+		return value;
+	}
+	const decimals = Math.max(0, -Math.floor(Math.log10(Math.abs(step))));
+	return Number(value.toFixed(Math.min(decimals, MAX_TICK_PRECISION)));
+}
+
+/**
+ * The round step closest to covering `[min, max]` in about `count` intervals.
+ * Returns `0` for a degenerate span, which callers read as "no ticks".
+ */
+export function tickStep(
+	min: number,
+	max: number,
+	count: number = DEFAULT_TICK_COUNT,
+): number {
+	const span = max - min;
+	if (!Number.isFinite(span) || span <= 0 || count <= 0) {
+		return 0;
+	}
+	const rough = span / count;
+	const power = Math.floor(Math.log10(rough));
+	const error = rough / 10 ** power;
+	const match = NICE_FACTORS.find((candidate) => error < candidate.threshold);
+	return (match?.factor ?? 10) * 10 ** power;
+}
+
+/**
+ * Round values strictly inside `[min, max]`. An axis that has been through
+ * `niceDomain` first gets ticks on both bounds; a raw domain does not, on
+ * purpose — a tick outside the data would be a lie.
+ */
+export function niceTicks(
+	min: number,
+	max: number,
+	count: number = DEFAULT_TICK_COUNT,
+): ReadonlyArray<number> {
+	if (min === max) {
+		return [min];
+	}
+	const step = tickStep(min, max, count);
+	if (step === 0) {
+		return [];
+	}
+	const first = Math.ceil(min / step);
+	const last = Math.floor(max / step);
+	const ticks: number[] = [];
+	for (let index = first; index <= last; index += 1) {
+		ticks.push(roundToStep(index * step, step));
+	}
+	return ticks;
+}
+
+/**
+ * Widens `[min, max]` outwards to the nearest round step, so the axis starts
+ * and ends on a tick instead of mid-air.
+ */
+export function niceDomain(
+	min: number,
+	max: number,
+	count: number = DEFAULT_TICK_COUNT,
+): readonly [number, number] {
+	if (!Number.isFinite(min) || !Number.isFinite(max)) {
+		return [0, 1];
+	}
+	if (min === max) {
+		return min === 0 ? [0, 1] : [Math.min(0, min), Math.max(0, max)];
+	}
+	const step = tickStep(min, max, count);
+	if (step === 0) {
+		return [min, max];
+	}
+	return [
+		roundToStep(Math.floor(min / step) * step, step),
+		roundToStep(Math.ceil(max / step) * step, step),
+	];
+}
+
+/**
+ * The `[min, max]` of a set of values, always including zero so bars are
+ * measured from a real baseline rather than from an arbitrary floor.
+ */
+export function extentFromZero(
+	values: ReadonlyArray<number>,
+): readonly [number, number] {
+	let min = 0;
+	let max = 0;
+	for (const value of values) {
+		if (!Number.isFinite(value)) {
+			continue;
+		}
+		min = Math.min(min, value);
+		max = Math.max(max, value);
+	}
+	return [min, max];
+}

package/src/core/types.ts

@@ -0,0 +1,358 @@
+/**
+ * The vocabulary of the chart pipeline. A definition lists marks; compiling it
+ * resolves scales from the marks' channels, lays out the guides, and asks each
+ * mark for its scene. The scene is plain data with stable keys: the SVG and
+ * Canvas renderers draw the same scene, and hit-testing, focus, tooltips and
+ * the data table all read it, never the DOM.
+ */
+
+/** A value a channel can carry onto a scale. */
+export type ChartValue = number | string | Date;
+
+/** A field of the datum, or a function of it. */
+export type ChartAccessor<TDatum, TValue> =
+	| (keyof TDatum & string)
+	| ((datum: TDatum, index: number) => TValue);
+
+export interface ChartRect {
+	readonly x: number;
+	readonly y: number;
+	readonly width: number;
+	readonly height: number;
+}
+
+export interface ChartMargin {
+	readonly top: number;
+	readonly right: number;
+	readonly bottom: number;
+	readonly left: number;
+}
+
+/** `[topLeft, topRight, bottomRight, bottomLeft]`, clockwise. */
+export type ChartCorners = readonly [number, number, number, number];
+
+/** How a line or area joins its points. */
+export type ChartCurve = "linear" | "monotone" | "step";
+
+// ---------------------------------------------------------------------------
+// Scales
+// ---------------------------------------------------------------------------
+
+export type ChartPositionScaleKind =
+	| "linear"
+	| "log"
+	| "time"
+	| "band"
+	| "point";
+
+/**
+ * One positional scale. Every kind answers the same questions, so a mark never
+ * branches on the kind: `map` places the start of a value's slot, `center` its
+ * middle (they differ only on a band scale), and `invert` reads a pixel back.
+ */
+export interface ChartPositionScale {
+	readonly kind: ChartPositionScaleKind;
+	/** `[min, max]` for continuous kinds, every category for discrete ones. */
+	readonly domain: ReadonlyArray<ChartValue>;
+	readonly range: readonly [number, number];
+	readonly map: (value: ChartValue) => number;
+	readonly center: (value: ChartValue) => number;
+	readonly invert: (pixel: number) => ChartValue;
+	/** Slot width on a band scale, `0` everywhere else. */
+	readonly bandwidth: number;
+	readonly ticks: (count?: number) => ReadonlyArray<ChartValue>;
+	readonly format: (value: ChartValue) => string;
+}
+
+export interface ChartColorScale {
+	readonly kind: "ordinal" | "sequential";
+	readonly domain: ReadonlyArray<ChartValue>;
+	readonly map: (value: ChartValue) => string;
+}
+
+export interface ChartScales {
+	readonly x?: ChartPositionScale;
+	readonly y?: ChartPositionScale;
+	readonly color?: ChartColorScale;
+}
+
+// ---------------------------------------------------------------------------
+// Scene
+// ---------------------------------------------------------------------------
+
+export interface ChartPaint {
+	readonly fill?: string;
+	readonly stroke?: string;
+	readonly strokeWidth?: number;
+	readonly strokeDasharray?: string;
+	readonly strokeLinecap?: "butt" | "round" | "square";
+	readonly strokeLinejoin?: "miter" | "round" | "bevel";
+	readonly opacity?: number;
+	readonly fillOpacity?: number;
+	readonly strokeOpacity?: number;
+}
+
+export interface ChartTextPaint extends ChartPaint {
+	readonly fontSize?: number;
+	readonly fontWeight?: number;
+	readonly textAnchor?: "start" | "middle" | "end";
+	readonly baseline?: "top" | "middle" | "bottom" | "alphabetic";
+}
+
+interface SceneNodeBase {
+	/** Stable across renders of the same data: what renderers reconcile on. */
+	readonly key: string;
+	/** The series the node draws, so a legend toggle can hide it. */
+	readonly series?: string;
+	/** A role for styling and tests: "mark", "axis", "grid", "label"… */
+	readonly role?: string;
+}
+
+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. */
+	readonly translate?: { readonly x: number; readonly y: number };
+	readonly clip?: ChartRect;
+	readonly children: ReadonlyArray<SceneNode>;
+}
+
+export interface SceneRect extends SceneNodeBase {
+	readonly kind: "rect";
+	readonly x: number;
+	readonly y: number;
+	readonly width: number;
+	readonly height: number;
+	readonly corners?: ChartCorners;
+	readonly paint: ChartPaint;
+}
+
+/** Any outline: a line, an area, a wedge, a country. `d` is SVG path data, which `Path2D` reads as well. */
+export interface ScenePath extends SceneNodeBase {
+	readonly kind: "path";
+	readonly d: string;
+	readonly paint: ChartPaint;
+}
+
+export interface SceneCircle extends SceneNodeBase {
+	readonly kind: "circle";
+	readonly cx: number;
+	readonly cy: number;
+	readonly r: number;
+	readonly paint: ChartPaint;
+}
+
+export interface SceneLine extends SceneNodeBase {
+	readonly kind: "line";
+	readonly x1: number;
+	readonly y1: number;
+	readonly x2: number;
+	readonly y2: number;
+	readonly paint: ChartPaint;
+}
+
+export interface SceneText extends SceneNodeBase {
+	readonly kind: "text";
+	readonly x: number;
+	readonly y: number;
+	readonly text: string;
+	/** Degrees, clockwise, around `(x, y)`. */
+	readonly rotate?: number;
+	readonly paint: ChartTextPaint;
+}
+
+export type SceneNode =
+	| SceneGroup
+	| SceneRect
+	| ScenePath
+	| SceneCircle
+	| SceneLine
+	| SceneText;
+
+/** The area a pointer has to land in to hit a point, beyond plain proximity. */
+export type ChartHitShape =
+	| { readonly kind: "rect"; readonly rect: ChartRect }
+	| {
+			readonly kind: "arc";
+			readonly cx: number;
+			readonly cy: number;
+			readonly innerRadius: number;
+			readonly outerRadius: number;
+			/** Degrees clockwise from twelve o'clock. */
+			readonly startAngle: number;
+			readonly endAngle: number;
+	  };
+
+/**
+ * One datum as the reader meets it: what the keyboard steps through, what the
+ * tooltip and the live region describe, what the data table lists.
+ */
+export interface ChartPoint<TDatum = unknown> {
+	readonly key: string;
+	readonly markId: string;
+	readonly index: number;
+	readonly datum: TDatum;
+	/** Anchor in chart pixels: where the focus ring and the tooltip go. */
+	readonly x: number;
+	readonly y: number;
+	readonly xValue?: ChartValue;
+	readonly yValue?: ChartValue;
+	readonly series?: string;
+	readonly seriesLabel?: string;
+	readonly color: string;
+	/** What the point reads as, without its series: "March 2026", "Paris". */
+	readonly title: string;
+	/** Its value, formatted: "1 240". */
+	readonly value: string;
+	readonly hit?: ChartHitShape;
+	/** The facet cell the point belongs to, on a faceted chart. */
+	readonly facet?: string;
+}
+
+export interface ChartLegendItem {
+	readonly key: string;
+	readonly label: string;
+	readonly color: string;
+	readonly shape: "square" | "line" | "dashed" | "dot";
+}
+
+/**
+ * How the keyboard walks the points. `x` groups every point that shares an x
+ * value into one stop (a column of a multi-series chart), `y` does the same
+ * along y for horizontal bars, `point` visits each point on its own.
+ */
+export type ChartFocusOrder = "x" | "y" | "point";
+
+export interface ChartScene {
+	readonly width: number;
+	readonly height: number;
+	readonly plot: ChartRect;
+	readonly nodes: ReadonlyArray<SceneNode>;
+	readonly points: ReadonlyArray<ChartPoint>;
+	readonly legend: ReadonlyArray<ChartLegendItem>;
+	readonly focusOrder: ChartFocusOrder;
+	readonly scales: ChartScales;
+	/** Column headings of the data table and tooltip: the axis labels. */
+	readonly xLabel: string;
+	readonly yLabel: string;
+	readonly theme: ChartTheme;
+	readonly locale: string;
+	/** A faceted chart's cells, each with its own plot, in reading order. */
+	readonly cells?: ReadonlyArray<{
+		readonly key: string;
+		readonly label: string;
+		readonly plot: ChartRect;
+	}>;
+	/** The sequential colour scale's ramp, for its legend: the colours and the ends' labels. */
+	readonly colorRamp?: {
+		readonly stops: ReadonlyArray<string>;
+		readonly low: string;
+		readonly high: string;
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Marks
+// ---------------------------------------------------------------------------
+
+/** The values a mark puts on a scale, so the scale's domain can cover them. */
+export interface ChartChannel {
+	readonly values: ReadonlyArray<ChartValue>;
+	/** Bars need a band; the first mark that asks for one gets it. */
+	readonly discrete?: "band" | "point";
+	/** A bar or an area measures from zero, so zero must be on the scale. */
+	readonly includeZero?: boolean;
+	/** The field the values come from: the axis title when none is given. */
+	readonly label?: string;
+	/** Pixels the mark reaches past its value (a dot's radius), kept inside the plot. */
+	readonly inset?: number;
+	/** Band padding the mark draws best with: cells touch, bars breathe. */
+	readonly padding?: number;
+	/** Outer band padding, when it differs: room for a ridge rising past its row. */
+	readonly paddingOuter?: number;
+}
+
+/**
+ * A map projection, described without naming the library that implements it
+ * (`@voila.dev/chart/geo` does, with d3-geo). Declared once on the
+ * definition and fitted to the plot, so every map mark draws on the same one.
+ */
+export interface ChartProjection {
+	readonly fit: (plot: ChartRect) => ChartFittedProjection;
+}
+
+export interface ChartFittedProjection {
+	/** Longitude and latitude to chart pixels; `undefined` when clipped away. */
+	readonly project: (
+		longitude: number,
+		latitude: number,
+	) => { x: number; y: number } | undefined;
+	/** Path data for a GeoJSON object. */
+	readonly path: (geometry: unknown) => string;
+	readonly centroid: (geometry: unknown) => { x: number; y: number };
+	readonly bounds: (geometry: unknown) => ChartRect;
+}
+
+export type ChartTextMeasurer = (
+	text: string,
+	fontSize: number,
+	fontWeight?: number,
+) => number;
+
+export interface ChartTheme {
+	readonly palette: ReadonlyArray<string>;
+	readonly foreground: string;
+	readonly muted: string;
+	readonly grid: string;
+	readonly background: string;
+	readonly fontSize: number;
+}
+
+export interface ChartMarkContext {
+	readonly scales: ChartScales;
+	readonly plot: ChartRect;
+	readonly theme: ChartTheme;
+	readonly measureText: ChartTextMeasurer;
+	readonly locale: string;
+	/** A colour for a mark with no color channel: its place in the palette. */
+	readonly paletteColor: (index: number) => string;
+	/** The colour of one value of the color channel. */
+	readonly colorOf: (value: ChartValue) => string;
+	/** The display name of one value of the color channel. */
+	readonly seriesLabel: (value: ChartValue) => string;
+	readonly formatX: (value: ChartValue) => string;
+	readonly formatY: (value: ChartValue) => string;
+	readonly markIndex: number;
+	/** The definition's projection, fitted to the plot. Map marks need it. */
+	readonly projection?: ChartFittedProjection;
+}
+
+export interface ChartMarkScene {
+	readonly nodes: ReadonlyArray<SceneNode>;
+	readonly points?: ReadonlyArray<ChartPoint>;
+	readonly legend?: ReadonlyArray<ChartLegendItem>;
+}
+
+/**
+ * What every mark factory returns. A cartesian mark declares channels so the
+ * scales cover it; a `frame` mark (pie, treemap, map) owns the whole plot and
+ * ignores the x and y scales.
+ */
+export interface ChartMark {
+	readonly id?: string;
+	readonly coordinate: "cartesian" | "frame";
+	readonly channels: {
+		readonly x?: ChartChannel;
+		readonly y?: ChartChannel;
+		readonly color?: ChartChannel;
+	};
+	/** The keyboard order this mark reads best in. */
+	readonly focusOrder?: ChartFocusOrder;
+	/** `false` when the mark already names its colours itself (a labelled funnel). */
+	readonly colorLegend?: boolean;
+	/** What a frame mark's categories and values are called, for the table and the tooltip. */
+	readonly titles?: {
+		readonly category?: string;
+		readonly value?: string;
+	};
+	readonly render: (context: ChartMarkContext) => ChartMarkScene;
+}

package/src/force/force.ts

@@ -0,0 +1,200 @@
+import {
+	forceCenter,
+	forceCollide,
+	forceLink,
+	forceManyBody,
+	forceSimulation,
+	forceX,
+	forceY,
+	type SimulationLinkDatum,
+	type SimulationNodeDatum,
+} from "d3-force";
+import { markId } from "#/core/marks/shared.ts";
+import type { ChartMark, ChartPoint, SceneNode } from "#/core/types.ts";
+
+export interface ForceNode {
+	readonly id: string;
+	readonly label?: string;
+	/** Colour group. */
+	readonly group?: string;
+}
+
+export interface ForceLink {
+	readonly source: string;
+	readonly target: string;
+}
+
+export interface ForceOptions {
+	readonly id?: string;
+	readonly radius?: number;
+	/** Settling steps. More is tidier and slower. */
+	readonly ticks?: number;
+	readonly labels?: boolean;
+	readonly tip?: boolean;
+}
+
+interface SimulatedNode extends SimulationNodeDatum, ForceNode {}
+
+const DEFAULT_RADIUS = 5;
+const DEFAULT_TICKS = 300;
+
+/** A fixed-seed random stream: the same graph settles the same way on the server and in the browser. */
+function seeded(seed: number): () => number {
+	let state = seed;
+	return () => {
+		state = (state * 1664525 + 1013904223) % 4294967296;
+		return state / 4294967296;
+	};
+}
+
+/**
+ * A network laid out by forces: linked nodes pull together, all nodes push
+ * apart. The simulation runs to rest before drawing, with a fixed seed, so
+ * the picture is the same every time; a reader moves through the nodes with
+ * the keyboard, each announced with how many links it has.
+ */
+export function forceGraph(
+	data: {
+		readonly nodes: ReadonlyArray<ForceNode>;
+		readonly links: ReadonlyArray<ForceLink>;
+	},
+	options: ForceOptions = {},
+): ChartMark {
+	const groups = data.nodes.map((node) => node.group ?? "");
+	return {
+		id: options.id,
+		coordinate: "frame",
+		focusOrder: "point",
+		channels: groups.some((group) => group !== "")
+			? { color: { values: groups.filter((group) => group !== "") } }
+			: {},
+		render(context) {
+			const id = markId(options.id, "force", context);
+			const { plot, theme } = context;
+			const radius = options.radius ?? DEFAULT_RADIUS;
+			const simulated: SimulatedNode[] = data.nodes.map((node) => ({
+				...node,
+			}));
+			const links = data.links.map((link) => ({
+				...link,
+			})) as SimulationLinkDatum<SimulatedNode>[];
+			const simulation = forceSimulation(simulated)
+				.randomSource(seeded(1))
+				.force(
+					"link",
+					forceLink<SimulatedNode, SimulationLinkDatum<SimulatedNode>>(links)
+						.id((node) => node.id)
+						.distance(radius * 10),
+				)
+				.force("charge", forceManyBody().strength(-radius * 20))
+				.force("collide", forceCollide(radius * 3))
+				.force("center", forceCenter(0, 0))
+				// A gentle pull to the middle keeps separate groups on one picture.
+				.force("x", forceX(0).strength(0.08))
+				.force("y", forceY(0).strength(0.08))
+				.stop();
+			simulation.tick(options.ticks ?? DEFAULT_TICKS);
+			const xs = simulated.map((node) => node.x ?? 0);
+			const ys = simulated.map((node) => node.y ?? 0);
+			const [minX, maxX, minY, maxY] = [
+				Math.min(...xs),
+				Math.max(...xs),
+				Math.min(...ys),
+				Math.max(...ys),
+			];
+			const pad = radius * 2;
+			const scale = Math.min(
+				(plot.width - pad * 2) / Math.max(1, maxX - minX),
+				(plot.height - pad * 2) / Math.max(1, maxY - minY),
+				1.5,
+			);
+			const place = (node: SimulatedNode) => ({
+				x:
+					plot.x + plot.width / 2 + ((node.x ?? 0) - (minX + maxX) / 2) * scale,
+				y:
+					plot.y +
+					plot.height / 2 +
+					((node.y ?? 0) - (minY + maxY) / 2) * scale,
+			});
+			const degree = new Map<string, number>();
+			const nodes: SceneNode[] = [];
+			for (const link of links) {
+				const source = link.source as SimulatedNode;
+				const target = link.target as SimulatedNode;
+				degree.set(source.id, (degree.get(source.id) ?? 0) + 1);
+				degree.set(target.id, (degree.get(target.id) ?? 0) + 1);
+				const from = place(source);
+				const to = place(target);
+				nodes.push({
+					kind: "line",
+					key: `${id}:link:${source.id}:${target.id}`,
+					role: "grid",
+					x1: from.x,
+					y1: from.y,
+					x2: to.x,
+					y2: to.y,
+					paint: { stroke: theme.grid, strokeWidth: 1.5 },
+				});
+			}
+			const points: ChartPoint[] = [];
+			for (const [index, node] of simulated.entries()) {
+				const at = place(node);
+				const color = node.group
+					? context.colorOf(node.group)
+					: context.paletteColor(0);
+				nodes.push({
+					kind: "circle",
+					key: `${id}:${node.id}`,
+					series: node.group,
+					role: "mark",
+					cx: at.x,
+					cy: at.y,
+					r: radius,
+					paint: { fill: color, stroke: theme.background, strokeWidth: 1.5 },
+				});
+				if (options.labels) {
+					nodes.push({
+						kind: "text",
+						key: `${id}:label:${node.id}`,
+						role: "label",
+						x: at.x + radius + 3,
+						y: at.y,
+						text: node.label ?? node.id,
+						paint: {
+							fill: theme.foreground,
+							fontSize: theme.fontSize - 1,
+							baseline: "middle",
+						},
+					});
+				}
+				if (options.tip !== false) {
+					points.push({
+						key: `${id}:${node.id}`,
+						markId: id,
+						index,
+						datum: node,
+						x: at.x,
+						y: at.y,
+						xValue: node.label ?? node.id,
+						yValue: degree.get(node.id) ?? 0,
+						series: node.group,
+						seriesLabel: node.group,
+						color,
+						title: node.label ?? node.id,
+						value: context.formatY(degree.get(node.id) ?? 0),
+						hit: {
+							kind: "rect",
+							rect: {
+								x: at.x - radius - 2,
+								y: at.y - radius - 2,
+								width: radius * 2 + 4,
+								height: radius * 2 + 4,
+							},
+						},
+					});
+				}
+			}
+			return { nodes, points };
+		},
+	};
+}

package/src/force/index.ts

@@ -0,0 +1,6 @@
+export {
+	type ForceLink,
+	type ForceNode,
+	type ForceOptions,
+	forceGraph,
+} from "#/force/force.ts";