@voila.dev/chart 4.0.0

package/src/core/facet.ts

@@ -0,0 +1,189 @@
+import { channelsOf, isMark } from "#/core/compile.ts";
+import type {
+	ChartFacet,
+	ChartFacetCompileOptions,
+	ChartFacetOptions,
+	ChartSpec,
+} from "#/core/define-chart.ts";
+import { formatValue } from "#/core/format.ts";
+import { categoryKey } from "#/core/scales/discrete.ts";
+import { planScale } from "#/core/scales/resolve.ts";
+import { DEFAULT_THEME } from "#/core/theme.ts";
+import type {
+	ChartHitShape,
+	ChartLegendItem,
+	ChartMark,
+	ChartPoint,
+	ChartScene,
+	SceneNode,
+} from "#/core/types.ts";
+
+const DEFAULT_COLUMNS = 3;
+const DEFAULT_GAP = 16;
+const TITLE_GAP = 6;
+
+function shifted(
+	hit: ChartHitShape | undefined,
+	dx: number,
+	dy: number,
+): ChartHitShape | undefined {
+	if (hit === undefined) {
+		return undefined;
+	}
+	return hit.kind === "rect"
+		? {
+				kind: "rect",
+				rect: { ...hit.rect, x: hit.rect.x + dx, y: hit.rect.y + dy },
+			}
+		: { ...hit, cx: hit.cx + dx, cy: hit.cy + dy };
+}
+
+/**
+ * Small multiples. Every cell is compiled as a chart of its own, on x, y and
+ * colour domains planned over all the cells together, then moved to its
+ * place in the grid under a title. Points carry their cell, so the keyboard
+ * walks one cell's values and the tooltip names the cell.
+ */
+function compileFacets(
+	spec: ChartSpec,
+	facet: ChartFacetOptions,
+	options: ChartFacetCompileOptions,
+): ChartScene {
+	const { compileCell, ...cellOptions } = options;
+	const { width, height } = options;
+	const theme = { ...DEFAULT_THEME, ...spec.theme };
+	const values = facet.values;
+	const columns = Math.max(
+		1,
+		Math.min(facet.columns ?? DEFAULT_COLUMNS, values.length),
+	);
+	const rows = Math.max(1, Math.ceil(values.length / columns));
+	const gap = facet.gap ?? DEFAULT_GAP;
+	const title = theme.fontSize + TITLE_GAP;
+	const cellWidth = (width - gap * (columns - 1)) / columns;
+	const cellHeight = (height - gap * (rows - 1)) / rows;
+	const label = (value: (typeof values)[number]) =>
+		facet.label?.(value) ?? formatValue(value, spec.locale);
+
+	const cellMarks: ChartMark[][] = values.map((value, index) =>
+		facet.marks(value, index).filter(isMark),
+	);
+	const everyMark = cellMarks.flat();
+	const cartesian = everyMark.filter((mark) => mark.coordinate === "cartesian");
+	const sharedX = planScale(channelsOf(cartesian, "x"), spec.x, "x");
+	const sharedY = planScale(channelsOf(cartesian, "y"), spec.y, "y");
+	const colors = channelsOf(everyMark, "color").flatMap(
+		(channel) => channel.values,
+	);
+	const numericColors =
+		colors.length > 0 && colors.every((value) => typeof value === "number");
+	const colorDomain =
+		spec.color?.domain ??
+		(colors.length === 0
+			? undefined
+			: numericColors
+				? [Math.min(...(colors as number[])), Math.max(...(colors as number[]))]
+				: [
+						...new Map(
+							colors.map((value) => [categoryKey(value), value]),
+						).values(),
+					]);
+
+	const nodes: SceneNode[] = [];
+	const points: ChartPoint[] = [];
+	const legend: ChartLegendItem[] = [];
+	const cells: Array<{ key: string; label: string; plot: ChartScene["plot"] }> =
+		[];
+	let first: ChartScene | undefined;
+
+	for (const [index, value] of values.entries()) {
+		const key = categoryKey(value);
+		const x = (index % columns) * (cellWidth + gap);
+		const y = Math.floor(index / columns) * (cellHeight + gap);
+		const cell = compileCell(
+			{
+				...spec,
+				facet: undefined,
+				marks: cellMarks[index],
+				x: sharedX
+					? { ...spec.x, domain: sharedX.domain, nice: false }
+					: spec.x,
+				y: sharedY
+					? { ...spec.y, domain: sharedY.domain, nice: false }
+					: spec.y,
+				color: colorDomain
+					? { ...spec.color, domain: colorDomain }
+					: spec.color,
+			},
+			{ ...cellOptions, width: cellWidth, height: cellHeight - title },
+		);
+		first ??= cell;
+		const dy = y + title;
+		nodes.push(
+			{
+				kind: "text",
+				key: `facet-title:${key}`,
+				role: "facet-title",
+				x: x + cell.plot.x,
+				y,
+				text: label(value),
+				paint: {
+					fill: theme.foreground,
+					fontSize: theme.fontSize,
+					fontWeight: 600,
+					baseline: "top",
+				},
+			},
+			{
+				kind: "group",
+				key: `facet:${key}`,
+				translate: { x, y: dy },
+				children: cell.nodes,
+			},
+		);
+		for (const point of cell.points) {
+			points.push({
+				...point,
+				key: `${key}|${point.key}`,
+				x: point.x + x,
+				y: point.y + dy,
+				hit: shifted(point.hit, x, dy),
+				facet: key,
+				title: `${label(value)} · ${point.title}`,
+			});
+		}
+		legend.push(...cell.legend);
+		cells.push({
+			key,
+			label: label(value),
+			plot: { ...cell.plot, x: cell.plot.x + x, y: cell.plot.y + dy },
+		});
+	}
+
+	const distinctLegend = [
+		...new Map(legend.map((item) => [item.key, item])).values(),
+	];
+	return {
+		...(first ??
+			compileCell({ ...spec, facet: undefined, marks: [] }, cellOptions)),
+		width,
+		height,
+		plot: { x: 0, y: 0, width, height },
+		nodes,
+		points,
+		legend: distinctLegend,
+		cells,
+	};
+}
+
+/**
+ * Small multiples: the same chart once per value, on a grid, every cell on
+ * the same scales. Pass the result as the definition's `facet`.
+ */
+export function facet(options: ChartFacetOptions): ChartFacet {
+	return {
+		options,
+		compile: (spec, compileOptions) =>
+			compileFacets(spec, options, compileOptions),
+	};
+}

package/src/core/format.ts

@@ -0,0 +1,163 @@
+/**
+ * Number formatting for axes, labels and tooltips. The whole app writes its
+ * numbers in French, so that is the default here too — pass an explicit locale
+ * when a chart lives on a page that does not.
+ */
+
+const DEFAULT_LOCALE = "fr-FR";
+/** Above this magnitude an axis tick reads better as "12 k" than as "12 000". */
+const COMPACT_THRESHOLD = 10_000;
+
+const formatterCache = new Map<string, Intl.NumberFormat>();
+
+function formatterFor(
+	locale: string,
+	options: Intl.NumberFormatOptions,
+): Intl.NumberFormat {
+	const cacheKey = `${locale}:${JSON.stringify(options)}`;
+	const cached = formatterCache.get(cacheKey);
+	if (cached !== undefined) {
+		return cached;
+	}
+	const created = new Intl.NumberFormat(locale, options);
+	formatterCache.set(cacheKey, created);
+	return created;
+}
+
+export interface FormatNumberOptions {
+	readonly locale?: string;
+	readonly maximumFractionDigits?: number;
+	readonly minimumFractionDigits?: number;
+}
+
+export function formatNumber(
+	value: number,
+	options: FormatNumberOptions = {},
+): string {
+	const { locale = DEFAULT_LOCALE, ...digits } = options;
+	return formatterFor(locale, digits).format(value);
+}
+
+/** "12 k", "3,4 M" — for axis ticks, where width is the scarce resource. */
+export function formatCompactNumber(
+	value: number,
+	locale: string = DEFAULT_LOCALE,
+): string {
+	return formatterFor(locale, {
+		notation: "compact",
+		maximumFractionDigits: 1,
+	}).format(value);
+}
+
+export function formatPercentage(
+	fraction: number,
+	locale: string = DEFAULT_LOCALE,
+): string {
+	return formatterFor(locale, {
+		style: "percent",
+		maximumFractionDigits: 1,
+	}).format(fraction);
+}
+
+/**
+ * What a value axis uses when the caller has no opinion: plain digits until the
+ * numbers get long, compact notation after that, and at most one decimal so a
+ * tick step of 0.5 still reads correctly.
+ */
+export function formatTickValue(
+	value: number,
+	locale: string = DEFAULT_LOCALE,
+): string {
+	if (Math.abs(value) >= COMPACT_THRESHOLD) {
+		return formatCompactNumber(value, locale);
+	}
+	return formatNumber(value, { locale, maximumFractionDigits: 2 });
+}
+
+/** Renders an unknown datum field as a label without throwing on `null`. */
+export function formatLabel(value: unknown): string {
+	if (value === null || value === undefined) {
+		return "";
+	}
+	if (typeof value === "number") {
+		return formatTickValue(value);
+	}
+	return String(value);
+}
+
+/**
+ * A value as a tooltip, the live region or the data table says it: dates in
+ * full, numbers grouped, strings as they are.
+ */
+export function formatValue(
+	value: unknown,
+	locale: string = DEFAULT_LOCALE,
+): string {
+	if (value instanceof Date) {
+		return formatDate(value, locale);
+	}
+	if (typeof value === "number") {
+		return formatNumber(value, { locale, maximumFractionDigits: 2 });
+	}
+	return formatLabel(value);
+}
+
+const formatters = new Map<string, Intl.DateTimeFormat>();
+
+export function dateFormat(
+	locale: string,
+	options: Intl.DateTimeFormatOptions,
+): Intl.DateTimeFormat {
+	const key = `${locale}:${JSON.stringify(options)}`;
+	const cached = formatters.get(key);
+	if (cached !== undefined) {
+		return cached;
+	}
+	const created = new Intl.DateTimeFormat(locale, {
+		...options,
+		timeZone: "UTC",
+	});
+	formatters.set(key, created);
+	return created;
+}
+
+const MS_PER_DAY = 86_400_000;
+
+/** A date written in full, for a tooltip or a table cell: "3 mars 2026", with the time when there is one. */
+export function formatDate(value: Date, locale: string): string {
+	const time = value.getTime();
+	const hasTime = time % MS_PER_DAY !== 0;
+	return dateFormat(locale, {
+		day: "numeric",
+		month: "long",
+		year: "numeric",
+		...(hasTime ? { hour: "2-digit", minute: "2-digit" } : {}),
+	}).format(value);
+}
+
+/**
+ * How to write the dates of one channel in full, judged on all of them: a
+ * series of month buckets reads "mars 2026", of years "2026", anything finer
+ * the full date.
+ */
+export function dateValueFormatter(
+	values: ReadonlyArray<unknown>,
+	locale: string,
+): ((value: Date) => string) | undefined {
+	const dates = values.filter((value): value is Date => value instanceof Date);
+	if (dates.length === 0) {
+		return undefined;
+	}
+	const firstOfMonth = dates.every(
+		(date) => date.getTime() % MS_PER_DAY === 0 && date.getUTCDate() === 1,
+	);
+	if (firstOfMonth && dates.every((date) => date.getUTCMonth() === 0)) {
+		const year = dateFormat(locale, { year: "numeric" });
+		return (value) => year.format(value);
+	}
+	if (firstOfMonth) {
+		const month = dateFormat(locale, { month: "long", year: "numeric" });
+		return (value) => month.format(value);
+	}
+	return undefined;
+}

package/src/core/guides/axes.ts

@@ -0,0 +1,283 @@
+import type { ChartAxisOptions } from "#/core/define-chart.ts";
+import type {
+	ChartPositionScale,
+	ChartRect,
+	ChartTextMeasurer,
+	ChartTheme,
+	ChartValue,
+	SceneNode,
+} from "#/core/types.ts";
+
+/**
+ * The axes as scene nodes: grid lines behind the marks, tick labels and
+ * titles in front. They are measured before the plot exists, so the margins
+ * fit the widest label instead of a guessed constant.
+ */
+
+const TICK_GAP = 8;
+const TITLE_GAP = 6;
+const LABEL_SPACING = 8;
+const EDGE = 8;
+/** A category label on a horizontal bar chart never takes more of the width than this. */
+const MAX_CATEGORY_SHARE = 0.35;
+const ELLIPSIS = "…";
+
+export interface AxisMeasureInput {
+	readonly scale: ChartPositionScale;
+	readonly options: ChartAxisOptions | undefined;
+	readonly title: string | undefined;
+	readonly theme: ChartTheme;
+	readonly measureText: ChartTextMeasurer;
+}
+
+export function axisTicks(
+	scale: ChartPositionScale,
+	options: ChartAxisOptions | undefined,
+): ReadonlyArray<ChartValue> {
+	const ticks = options?.ticks;
+	if (Array.isArray(ticks)) {
+		return ticks;
+	}
+	return scale.ticks(typeof ticks === "number" ? ticks : undefined);
+}
+
+export function tickLabel(
+	scale: ChartPositionScale,
+	options: ChartAxisOptions | undefined,
+	value: ChartValue,
+): string {
+	return options?.tickFormat?.(value) ?? scale.format(value);
+}
+
+/** Cuts a label down to `maxWidth`, ending on an ellipsis. */
+export function truncate(
+	text: string,
+	maxWidth: number,
+	fontSize: number,
+	measureText: ChartTextMeasurer,
+): string {
+	if (measureText(text, fontSize) <= maxWidth) {
+		return text;
+	}
+	let kept = text;
+	while (kept.length > 1 && measureText(kept + ELLIPSIS, fontSize) > maxWidth) {
+		kept = kept.slice(0, -1);
+	}
+	return kept + ELLIPSIS;
+}
+
+function hidden(options: ChartAxisOptions | undefined): boolean {
+	return options?.axis === false;
+}
+
+/** Room the left axis needs: its widest tick label, the gap, and the title. */
+export function leftMargin(
+	input: AxisMeasureInput,
+	chartWidth: number,
+): number {
+	const { scale, options, title, theme, measureText } = input;
+	if (hidden(options)) {
+		return EDGE;
+	}
+	const discrete = scale.kind === "band" || scale.kind === "point";
+	const widest = Math.max(
+		0,
+		...axisTicks(scale, options).map((tick) =>
+			measureText(tickLabel(scale, options, tick), theme.fontSize),
+		),
+	);
+	const labels = discrete
+		? Math.min(widest, chartWidth * MAX_CATEGORY_SHARE)
+		: widest;
+	return EDGE + labels + TICK_GAP + (title ? theme.fontSize + TITLE_GAP : 0);
+}
+
+export function bottomMargin(input: AxisMeasureInput): number {
+	const { options, title, theme } = input;
+	if (hidden(options)) {
+		return EDGE;
+	}
+	return (
+		TICK_GAP +
+		theme.fontSize +
+		EDGE / 2 +
+		(title ? theme.fontSize + TITLE_GAP : 0)
+	);
+}
+
+/** Half the last x label hangs past the plot's right edge; leave it room. */
+export function rightMargin(input: AxisMeasureInput): number {
+	const { scale, options, theme, measureText } = input;
+	if (hidden(options) || scale.kind === "band" || scale.kind === "point") {
+		return EDGE;
+	}
+	const ticks = axisTicks(scale, options);
+	const last = ticks[ticks.length - 1];
+	if (last === undefined) {
+		return EDGE;
+	}
+	const half = measureText(tickLabel(scale, options, last), theme.fontSize) / 2;
+	const overhang = half - (scale.range[1] - scale.map(last));
+	return Math.max(EDGE, overhang + 2);
+}
+
+export interface AxisNodes {
+	readonly grid: ReadonlyArray<SceneNode>;
+	readonly labels: ReadonlyArray<SceneNode>;
+}
+
+/**
+ * Every `step`-th label, so neighbours never overlap. The step is the same
+ * across the axis: thinning by skipping single labels reads as noise.
+ */
+function thinned(
+	ticks: ReadonlyArray<ChartValue>,
+	widths: ReadonlyArray<number>,
+	positions: ReadonlyArray<number>,
+): ReadonlyArray<number> {
+	if (ticks.length < 2) {
+		return ticks.map((_tick, index) => index);
+	}
+	const spacing = Math.abs(positions[1] - positions[0]) || 1;
+	const widest = Math.max(...widths);
+	const step = Math.max(1, Math.ceil((widest + LABEL_SPACING) / spacing));
+	return ticks
+		.map((_tick, index) => index)
+		.filter((index) => index % step === 0);
+}
+
+export function bottomAxis(
+	input: AxisMeasureInput,
+	plot: ChartRect,
+	grid: boolean,
+): AxisNodes {
+	const { scale, options, title, theme, measureText } = input;
+	const ticks = axisTicks(scale, options);
+	const positions = ticks.map((tick) => scale.center(tick));
+	const gridNodes: SceneNode[] = grid
+		? ticks.map((tick, index) => ({
+				kind: "line",
+				key: `grid-x:${tickLabel(scale, options, tick)}`,
+				role: "grid",
+				x1: positions[index],
+				y1: plot.y,
+				x2: positions[index],
+				y2: plot.y + plot.height,
+				paint: { stroke: theme.grid, strokeWidth: 1 },
+			}))
+		: [];
+	if (hidden(options)) {
+		return { grid: gridNodes, labels: [] };
+	}
+	const texts = ticks.map((tick) => tickLabel(scale, options, tick));
+	const widths = texts.map((text) => measureText(text, theme.fontSize));
+	const baseline = plot.y + plot.height + TICK_GAP;
+	const labels: SceneNode[] = thinned(ticks, widths, positions).map(
+		(index) => ({
+			kind: "text",
+			key: `tick-x:${texts[index]}`,
+			role: "axis",
+			x: positions[index],
+			y: baseline,
+			text: texts[index],
+			paint: {
+				fill: theme.muted,
+				fontSize: theme.fontSize,
+				textAnchor: "middle",
+				baseline: "top",
+			},
+		}),
+	);
+	if (title) {
+		labels.push({
+			kind: "text",
+			key: "title-x",
+			role: "axis-title",
+			x: plot.x + plot.width / 2,
+			y: baseline + theme.fontSize + TITLE_GAP,
+			text: title,
+			paint: {
+				fill: theme.muted,
+				fontSize: theme.fontSize,
+				fontWeight: 500,
+				textAnchor: "middle",
+				baseline: "top",
+			},
+		});
+	}
+	return { grid: gridNodes, labels };
+}
+
+export function leftAxis(
+	input: AxisMeasureInput,
+	plot: ChartRect,
+	grid: boolean,
+	chartWidth: number,
+): AxisNodes {
+	const { scale, options, title, theme, measureText } = input;
+	const ticks = axisTicks(scale, options);
+	const positions = ticks.map((tick) => scale.center(tick));
+	const gridNodes: SceneNode[] = grid
+		? ticks.map((tick, index) => ({
+				kind: "line",
+				key: `grid-y:${tickLabel(scale, options, tick)}`,
+				role: "grid",
+				x1: plot.x,
+				y1: positions[index],
+				x2: plot.x + plot.width,
+				y2: positions[index],
+				paint: { stroke: theme.grid, strokeWidth: 1 },
+			}))
+		: [];
+	if (hidden(options)) {
+		return { grid: gridNodes, labels: [] };
+	}
+	const discrete = scale.kind === "band" || scale.kind === "point";
+	const maxWidth = discrete
+		? chartWidth * MAX_CATEGORY_SHARE
+		: Number.POSITIVE_INFINITY;
+	const texts = ticks.map((tick) =>
+		truncate(
+			tickLabel(scale, options, tick),
+			maxWidth,
+			theme.fontSize,
+			measureText,
+		),
+	);
+	const heights = texts.map(() => theme.fontSize);
+	const labels: SceneNode[] = thinned(ticks, heights, positions).map(
+		(index) => ({
+			kind: "text",
+			key: `tick-y:${texts[index]}`,
+			role: "axis",
+			x: plot.x - TICK_GAP,
+			y: positions[index],
+			text: texts[index],
+			paint: {
+				fill: theme.muted,
+				fontSize: theme.fontSize,
+				textAnchor: "end",
+				baseline: "middle",
+			},
+		}),
+	);
+	if (title) {
+		labels.push({
+			kind: "text",
+			key: "title-y",
+			role: "axis-title",
+			x: EDGE / 2 + theme.fontSize / 2,
+			y: plot.y + plot.height / 2,
+			text: title,
+			rotate: -90,
+			paint: {
+				fill: theme.muted,
+				fontSize: theme.fontSize,
+				fontWeight: 500,
+				textAnchor: "middle",
+				baseline: "middle",
+			},
+		});
+	}
+	return { grid: gridNodes, labels };
+}