@voila.dev/chart 4.0.0

package/src/hierarchy/hierarchy.ts

@@ -0,0 +1,377 @@
+import {
+	type HierarchyNode,
+	type HierarchyRectangularNode,
+	hierarchy,
+	partition,
+	tree,
+	treemap,
+} from "d3-hierarchy";
+import { truncate } from "#/core/guides/axes.ts";
+import { markId } from "#/core/marks/shared.ts";
+import { arcPath, polarToCartesian } from "#/core/paths.ts";
+import type {
+	ChartMark,
+	ChartMarkContext,
+	ChartPoint,
+	SceneNode,
+} from "#/core/types.ts";
+
+/**
+ * Nested data: a treemap, a sunburst, a tree. Each takes one root and reads
+ * its children, value and name through accessors, so any nested shape works.
+ * Colours follow the root's direct children (the branches the legend lists);
+ * deeper levels keep their branch's colour.
+ */
+
+export interface HierarchyOptions<TNode> {
+	readonly id?: string;
+	readonly children?: (node: TNode) => ReadonlyArray<TNode> | undefined;
+	/** A leaf's size. Branches sum their leaves. */
+	readonly value?: (node: TNode) => number;
+	readonly name: (node: TNode) => string;
+	/** What the values are, for the table heading. */
+	readonly label?: string;
+	readonly tip?: boolean;
+}
+
+function rooted<TNode>(
+	root: TNode,
+	options: HierarchyOptions<TNode>,
+): HierarchyNode<TNode> {
+	const node = hierarchy(
+		root,
+		(datum) =>
+			(options.children?.(datum) as TNode[] | undefined) ??
+			(datum as { children?: TNode[] }).children,
+	);
+	return node
+		.sum((datum) => (options.value ? Math.max(0, options.value(datum)) : 0))
+		.sort((left, right) => (right.value ?? 0) - (left.value ?? 0));
+}
+
+function branchOf<TNode>(node: HierarchyNode<TNode>): HierarchyNode<TNode> {
+	let current = node;
+	while (current.parent?.parent) {
+		current = current.parent;
+	}
+	return current;
+}
+
+function pathName<TNode>(
+	node: HierarchyNode<TNode>,
+	options: HierarchyOptions<TNode>,
+): string {
+	return node
+		.ancestors()
+		.reverse()
+		.slice(1)
+		.map((ancestor) => options.name(ancestor.data))
+		.join(" › ");
+}
+
+function branchNames<TNode>(
+	root: TNode,
+	options: HierarchyOptions<TNode>,
+): string[] {
+	return (rooted(root, options).children ?? []).map((child) =>
+		options.name(child.data),
+	);
+}
+
+function nodeKey<TNode>(
+	node: HierarchyNode<TNode>,
+	options: HierarchyOptions<TNode>,
+): string {
+	return node
+		.ancestors()
+		.map((ancestor) => options.name(ancestor.data))
+		.reverse()
+		.join("/");
+}
+
+function colorFor<TNode>(
+	node: HierarchyNode<TNode>,
+	options: HierarchyOptions<TNode>,
+	context: ChartMarkContext,
+): string {
+	return node.depth === 0
+		? context.theme.muted
+		: context.colorOf(options.name(branchOf(node).data));
+}
+
+function pointFor<TNode>(
+	id: string,
+	node: HierarchyNode<TNode>,
+	options: HierarchyOptions<TNode>,
+	context: ChartMarkContext,
+	index: number,
+	at: { x: number; y: number },
+	hit?: ChartPoint["hit"],
+): ChartPoint {
+	return {
+		key: `${id}:${nodeKey(node, options)}`,
+		markId: id,
+		index,
+		datum: node.data,
+		x: at.x,
+		y: at.y,
+		xValue: options.name(node.data),
+		yValue: node.value ?? 0,
+		series: options.name(branchOf(node).data),
+		seriesLabel: options.label,
+		color: colorFor(node, options, context),
+		title: pathName(node, options) || options.name(node.data),
+		value: context.formatY(node.value ?? 0),
+		hit,
+	};
+}
+
+const LABEL_PADDING = 4;
+const MIN_LABEL_HEIGHT = 16;
+
+/** Rectangles nested inside rectangles, each leaf as large as its value. */
+export function treemapMark<TNode>(
+	root: TNode,
+	options: HierarchyOptions<TNode>,
+): ChartMark {
+	return {
+		id: options.id,
+		coordinate: "frame",
+		focusOrder: "point",
+		titles: { value: options.label },
+		channels: { color: { values: branchNames(root, options) } },
+		render(context) {
+			const id = markId(options.id, "treemap", context);
+			const { plot, theme } = context;
+			const laid = treemap<TNode>()
+				.size([plot.width, plot.height])
+				.paddingInner(2)
+				.round(true)(rooted(root, options));
+			const nodes: SceneNode[] = [];
+			const points: ChartPoint[] = [];
+			for (const [index, leaf] of laid.leaves().entries()) {
+				const rect = {
+					x: plot.x + leaf.x0,
+					y: plot.y + leaf.y0,
+					width: Math.max(0, leaf.x1 - leaf.x0),
+					height: Math.max(0, leaf.y1 - leaf.y0),
+				};
+				const key = nodeKey(leaf, options);
+				const series = options.name(branchOf(leaf).data);
+				nodes.push({
+					kind: "rect",
+					key: `${id}:${key}`,
+					series,
+					role: "mark",
+					...rect,
+					corners: [3, 3, 3, 3],
+					paint: {
+						fill: colorFor(leaf, options, context),
+						fillOpacity: 0.55 + 0.45 / leaf.depth,
+					},
+				});
+				if (
+					rect.height >= MIN_LABEL_HEIGHT &&
+					rect.width > theme.fontSize * 2
+				) {
+					nodes.push({
+						kind: "text",
+						key: `${id}:label:${key}`,
+						series,
+						role: "label",
+						x: rect.x + LABEL_PADDING,
+						y: rect.y + LABEL_PADDING,
+						text: truncate(
+							options.name(leaf.data),
+							rect.width - LABEL_PADDING * 2,
+							theme.fontSize,
+							context.measureText,
+						),
+						paint: {
+							fill: theme.background,
+							fontSize: theme.fontSize,
+							fontWeight: 600,
+							baseline: "top",
+						},
+					});
+				}
+				if (options.tip !== false) {
+					points.push(
+						pointFor(
+							id,
+							leaf,
+							options,
+							context,
+							index,
+							{ x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 },
+							{ kind: "rect", rect },
+						),
+					);
+				}
+			}
+			return { nodes, points };
+		},
+	};
+}
+
+/** Rings of arcs: the root's children on the first ring, theirs on the next. */
+export function sunburstMark<TNode>(
+	root: TNode,
+	options: HierarchyOptions<TNode>,
+): ChartMark {
+	return {
+		id: options.id,
+		coordinate: "frame",
+		focusOrder: "point",
+		titles: { value: options.label },
+		channels: { color: { values: branchNames(root, options) } },
+		render(context) {
+			const id = markId(options.id, "sunburst", context);
+			const { plot } = context;
+			const radius = Math.max(0, Math.min(plot.width, plot.height) / 2 - 4);
+			const cx = plot.x + plot.width / 2;
+			const cy = plot.y + plot.height / 2;
+			const laid = partition<TNode>().size([360, radius])(
+				rooted(root, options),
+			);
+			// The root's ring would be a disc in the middle: leave it empty.
+			const ringWidth = radius / (laid.height + 1);
+			const nodes: SceneNode[] = [];
+			const points: ChartPoint[] = [];
+			const descendants = laid
+				.descendants()
+				.filter((node) => node.depth > 0 && node.x1 - node.x0 > 0.2);
+			for (const [index, node] of descendants.entries()) {
+				const shape = {
+					cx,
+					cy,
+					innerRadius: node.depth * ringWidth,
+					outerRadius: (node.depth + 1) * ringWidth - 1,
+					startAngle: node.x0 + 0.25,
+					endAngle: node.x1 - 0.25,
+				};
+				const series = options.name(branchOf(node).data);
+				nodes.push({
+					kind: "path",
+					key: `${id}:${nodeKey(node, options)}`,
+					series,
+					role: "mark",
+					d: arcPath(shape),
+					paint: {
+						fill: colorFor(node, options, context),
+						fillOpacity: 1 - (node.depth - 1) * 0.18,
+					},
+				});
+				if (options.tip !== false) {
+					const anchor = polarToCartesian(
+						cx,
+						cy,
+						(shape.innerRadius + shape.outerRadius) / 2,
+						(shape.startAngle + shape.endAngle) / 2,
+					);
+					points.push(
+						pointFor(id, node, options, context, index, anchor, {
+							kind: "arc",
+							...shape,
+						}),
+					);
+				}
+			}
+			return { nodes, points };
+		},
+	};
+}
+
+const NODE_RADIUS = 4;
+const LABEL_GAP = 6;
+
+/** A node-link tree, root on the left, leaves on the right, every node named. */
+export function treeMark<TNode>(
+	root: TNode,
+	options: HierarchyOptions<TNode>,
+): ChartMark {
+	return {
+		id: options.id,
+		coordinate: "frame",
+		focusOrder: "point",
+		titles: { value: options.label },
+		channels: {},
+		render(context) {
+			const id = markId(options.id, "tree", context);
+			const { plot, theme, measureText } = context;
+			const rootNode = rooted(root, options);
+			const leafLabel = Math.max(
+				0,
+				...rootNode
+					.leaves()
+					.map((leaf) => measureText(options.name(leaf.data), theme.fontSize)),
+			);
+			const width = Math.max(
+				0,
+				plot.width - leafLabel - LABEL_GAP - NODE_RADIUS * 2,
+			);
+			const laid = tree<TNode>().size([plot.height, width])(
+				rootNode,
+			) as HierarchyRectangularNode<TNode> & HierarchyNode<TNode>;
+			const position = (
+				node: HierarchyNode<TNode> & { x?: number; y?: number },
+			) => ({
+				x: plot.x + NODE_RADIUS + (node.y ?? 0),
+				y: plot.y + (node.x ?? 0),
+			});
+			const nodes: SceneNode[] = [];
+			const points: ChartPoint[] = [];
+			for (const link of laid.links()) {
+				const from = position(link.source);
+				const to = position(link.target);
+				const middle = (from.x + to.x) / 2;
+				nodes.push({
+					kind: "path",
+					key: `${id}:link:${nodeKey(link.target, options)}`,
+					role: "grid",
+					d: `M${from.x},${from.y}C${middle},${from.y} ${middle},${to.y} ${to.x},${to.y}`,
+					paint: { fill: "none", stroke: theme.grid, strokeWidth: 1.5 },
+				});
+			}
+			for (const [index, node] of laid.descendants().entries()) {
+				const at = position(node);
+				const leaf = node.children === undefined;
+				nodes.push(
+					{
+						kind: "circle",
+						key: `${id}:${nodeKey(node, options)}`,
+						role: "mark",
+						cx: at.x,
+						cy: at.y,
+						r: NODE_RADIUS,
+						paint: {
+							fill: leaf ? theme.background : colorFor(node, options, context),
+							stroke: colorFor(node, options, context),
+							strokeWidth: 1.5,
+						},
+					},
+					{
+						kind: "text",
+						key: `${id}:label:${nodeKey(node, options)}`,
+						role: "label",
+						x:
+							at.x +
+							(leaf ? LABEL_GAP + NODE_RADIUS : -(LABEL_GAP + NODE_RADIUS)),
+						y: at.y,
+						text: options.name(node.data),
+						paint: {
+							fill: theme.foreground,
+							fontSize: theme.fontSize,
+							textAnchor: leaf ? "start" : "end",
+							baseline: "middle",
+						},
+					},
+				);
+				if (options.tip !== false) {
+					points.push(pointFor(id, node, options, context, index, at));
+				}
+			}
+			return { nodes, points };
+		},
+	};
+}

package/src/hierarchy/index.ts

@@ -0,0 +1,6 @@
+export {
+	type HierarchyOptions,
+	sunburstMark as sunburst,
+	treeMark as tree,
+	treemapMark as treemap,
+} from "#/hierarchy/hierarchy.ts";

package/src/index.ts

@@ -0,0 +1,70 @@
+export { type CompileOptions, compileChart } from "#/core/compile.ts";
+export {
+	type ChartAxisOptions,
+	type ChartBuildContext,
+	type ChartColorOptions,
+	type ChartDefinition,
+	type ChartFacet,
+	type ChartFacetOptions,
+	type ChartPositionScaleOptions,
+	type ChartSpec,
+	defineChart,
+} from "#/core/define-chart.ts";
+export { facet } from "#/core/facet.ts";
+export { formatDate, formatNumber, formatValue } from "#/core/format.ts";
+export { type AreaOptions, areaX, areaY } from "#/core/marks/area.ts";
+export { type BarOptions, barX, barY } from "#/core/marks/bar.ts";
+export { type CellOptions, cell } from "#/core/marks/cell.ts";
+export { type DotOptions, dot } from "#/core/marks/dot.ts";
+export { type FunnelOptions, funnel } from "#/core/marks/funnel.ts";
+export { type LineOptions, lineX, lineY } from "#/core/marks/line.ts";
+export {
+	type ArcOptions,
+	arc,
+	donut,
+	type RadarOptions,
+	type RadialBarOptions,
+	radar,
+	radialBar,
+} from "#/core/marks/polar.ts";
+export { type RectOptions, rectY } from "#/core/marks/rect.ts";
+export { type RuleOptions, ruleX, ruleY } from "#/core/marks/rule.ts";
+export type { ChartMarkOptions } from "#/core/marks/shared.ts";
+export {
+	type DifferenceOptions,
+	differenceY,
+} from "#/core/marks/stats/difference.ts";
+export {
+	type BoxOptions,
+	boxY,
+	type RidgelineOptions,
+	ridgeline,
+	violinY,
+} from "#/core/marks/stats/distribution.ts";
+export { type DodgeOptions, dodgeY } from "#/core/marks/stats/dodge.ts";
+export { type HexbinOptions, hexbin } from "#/core/marks/stats/hexbin.ts";
+export {
+	type HistogramOptions,
+	histogram,
+} from "#/core/marks/stats/histogram.ts";
+export {
+	type RegressionOptions,
+	regressionY,
+} from "#/core/marks/stats/regression.ts";
+export {
+	boxSummary,
+	kernelDensity,
+	linearFit,
+	quantile,
+} from "#/core/marks/stats/statistics.ts";
+export { type WaffleOptions, waffleY } from "#/core/marks/stats/waffle.ts";
+export { type TextOptions, text } from "#/core/marks/text.ts";
+export { easeOutCubic, tweenScene } from "#/core/motion/tween.ts";
+export {
+	type ChartFocusStop,
+	findNearest,
+	focusStops,
+} from "#/core/nearest.ts";
+export { estimateTextWidth } from "#/core/text.ts";
+export { DEFAULT_THEME } from "#/core/theme.ts";
+export type * from "#/core/types.ts";

package/src/react/brush-contract.ts

@@ -0,0 +1,35 @@
+import type * as React from "react";
+import type {
+	ChartPositionScale,
+	ChartRect,
+	ChartValue,
+} from "#/core/types.ts";
+import type { ChartMessages } from "#/react/messages.ts";
+
+export type ChartBrushRange = readonly [ChartValue, ChartValue];
+
+export interface ChartBrushLayerProps {
+	readonly scale: ChartPositionScale;
+	readonly plot: ChartRect;
+	readonly range: ChartBrushRange | null;
+	readonly messages: ChartMessages;
+	readonly onChange: (range: ChartBrushRange | null) => void;
+}
+
+/**
+ * What `brushX(…)` from `@voila.dev/chart/brush` returns. The chart only
+ * knows this shape, so the brush's selection layer and sliders ship only
+ * with the charts that use them.
+ */
+export interface ChartBrush {
+	readonly onBrush: (range: ChartBrushRange | null) => void;
+	readonly Layer: React.ComponentType<ChartBrushLayerProps>;
+}
+
+/** The two ends in the scale's own order. */
+export function ordered(
+	scale: ChartPositionScale,
+	[a, b]: ChartBrushRange,
+): ChartBrushRange {
+	return scale.map(a) <= scale.map(b) ? [a, b] : [b, a];
+}

package/src/react/chart-data-table.tsx

@@ -0,0 +1,98 @@
+import type { ChartFocusStop } from "#/core/nearest.ts";
+import type { ChartScene } from "#/core/types.ts";
+import { SR_ONLY } from "#/react/sr-only.ts";
+
+/**
+ * The chart's content as a table, for anyone who cannot read the picture: a
+ * screen reader gets the actual numbers, not a one-line summary of them. One
+ * row per focus stop, one column per series, the same values the tooltip
+ * shows.
+ *
+ * The hiding goes on a wrapper: a table box ignores `width: 1px` and lays out
+ * at its content width, which widened the page on a phone.
+ */
+export function ChartDataTable({
+	scene,
+	stops,
+	caption,
+	seriesHeading,
+}: {
+	scene: ChartScene;
+	stops: ReadonlyArray<ChartFocusStop>;
+	caption: string;
+	seriesHeading: string;
+}) {
+	if (stops.length === 0) {
+		return null;
+	}
+	const series = new Map<string, string>();
+	for (const point of scene.points) {
+		const key = point.series ?? point.markId;
+		if (!series.has(key)) {
+			series.set(key, point.seriesLabel ?? scene.yLabel);
+		}
+	}
+	// A pie or a scatter: one row per point, the series only when it says
+	// something the row heading does not.
+	if (scene.focusOrder === "point") {
+		const named = scene.points.some(
+			(point) =>
+				point.seriesLabel !== undefined && point.seriesLabel !== point.title,
+		);
+		return (
+			<div style={SR_ONLY}>
+				<table data-slot="chart-data-table">
+					<caption>{caption}</caption>
+					<thead>
+						<tr>
+							<th scope="col">{scene.xLabel}</th>
+							{named ? <th scope="col">{seriesHeading}</th> : null}
+							<th scope="col">{scene.yLabel}</th>
+						</tr>
+					</thead>
+					<tbody>
+						{scene.points.map((point) => (
+							<tr key={point.key}>
+								<th scope="row">{point.title}</th>
+								{named ? <td>{point.seriesLabel}</td> : null}
+								<td>{point.value}</td>
+							</tr>
+						))}
+					</tbody>
+				</table>
+			</div>
+		);
+	}
+	const columns = [...series.entries()];
+	return (
+		<div style={SR_ONLY}>
+			<table data-slot="chart-data-table">
+				<caption>{caption}</caption>
+				<thead>
+					<tr>
+						<th scope="col">{scene.xLabel}</th>
+						{columns.map(([key, label]) => (
+							<th key={key} scope="col">
+								{label}
+							</th>
+						))}
+					</tr>
+				</thead>
+				<tbody>
+					{stops.map((stop) => (
+						<tr key={stop.key}>
+							<th scope="row">{stop.points[0].title}</th>
+							{columns.map(([key]) => (
+								<td key={key}>
+									{stop.points.find(
+										(point) => (point.series ?? point.markId) === key,
+									)?.value ?? ""}
+								</td>
+							))}
+						</tr>
+					))}
+				</tbody>
+			</table>
+		</div>
+	);
+}

package/src/react/chart-legend.tsx

@@ -0,0 +1,130 @@
+import type { ChartLegendItem, ChartScene } from "#/core/types.ts";
+
+function Swatch({ item }: { item: ChartLegendItem }) {
+	const base = { flex: "none" as const, display: "inline-block" };
+	if (item.shape === "line" || item.shape === "dashed") {
+		return (
+			<span
+				aria-hidden="true"
+				style={{
+					...base,
+					width: 14,
+					height: 0,
+					borderTop: `2px ${item.shape === "dashed" ? "dashed" : "solid"} ${item.color}`,
+				}}
+			/>
+		);
+	}
+	return (
+		<span
+			aria-hidden="true"
+			style={{
+				...base,
+				width: 10,
+				height: 10,
+				borderRadius: item.shape === "dot" ? "50%" : 2,
+				background: item.color,
+			}}
+		/>
+	);
+}
+
+/**
+ * One toggle button per series. Turning a series off redraws without it but
+ * keeps the axes where they were, so the other series do not jump.
+ */
+export function ChartLegend({
+	items,
+	hidden,
+	label,
+	onToggle,
+}: {
+	items: ReadonlyArray<ChartLegendItem>;
+	hidden: ReadonlySet<string>;
+	label: string;
+	onToggle: (key: string) => void;
+}) {
+	return (
+		<ul
+			aria-label={label}
+			data-slot="chart-legend"
+			style={{
+				display: "flex",
+				flexWrap: "wrap",
+				justifyContent: "center",
+				gap: 4,
+				margin: 0,
+				padding: 0,
+				listStyle: "none",
+				fontSize: 12,
+			}}
+		>
+			{items.map((item) => {
+				const visible = !hidden.has(item.key);
+				return (
+					<li key={item.key}>
+						<button
+							type="button"
+							aria-pressed={visible}
+							onClick={() => onToggle(item.key)}
+							style={{
+								display: "inline-flex",
+								alignItems: "center",
+								gap: 6,
+								minHeight: 24,
+								padding: "2px 8px",
+								border: 0,
+								borderRadius: 6,
+								background: "transparent",
+								color: "inherit",
+								font: "inherit",
+								cursor: "pointer",
+								opacity: visible ? 1 : 0.45,
+								textDecoration: visible ? undefined : "line-through",
+							}}
+						>
+							<Swatch item={item} />
+							{item.label}
+						</button>
+					</li>
+				);
+			})}
+		</ul>
+	);
+}
+
+/** The ramp of a sequential colour scale: a gradient bar between its two ends. */
+export function ChartColorRamp({
+	ramp,
+	label,
+}: {
+	ramp: NonNullable<ChartScene["colorRamp"]>;
+	label: string;
+}) {
+	return (
+		<div
+			role="img"
+			aria-label={`${label} : ${ramp.low} – ${ramp.high}`}
+			data-slot="chart-color-ramp"
+			style={{
+				display: "flex",
+				alignItems: "center",
+				justifyContent: "center",
+				gap: 8,
+				fontSize: 12,
+			}}
+		>
+			<span>{ramp.low}</span>
+			<span
+				aria-hidden="true"
+				style={{
+					width: 120,
+					height: 8,
+					borderRadius: 4,
+					background: `linear-gradient(to right, ${ramp.stops.join(", ")})`,
+				}}
+			/>
+			<span>{ramp.high}</span>
+		</div>
+	);
+}