@voila.dev/chart 4.0.0

package/src/contour/density.ts

@@ -0,0 +1,90 @@
+import { contourDensity } from "d3-contour";
+import { isPlaceable, readChannel } from "#/core/channel.ts";
+import { markId, valueOn } from "#/core/marks/shared.ts";
+import { multiPolygonPath } from "#/core/paths.ts";
+import type {
+	ChartAccessor,
+	ChartMark,
+	ChartValue,
+	SceneNode,
+} from "#/core/types.ts";
+
+export interface Density2dOptions<TDatum> {
+	readonly id?: string;
+	readonly x: ChartAccessor<TDatum, ChartValue>;
+	readonly y: ChartAccessor<TDatum, ChartValue>;
+	/** Smoothing, in pixels. */
+	readonly bandwidth?: number;
+	/** How many density levels to draw. */
+	readonly thresholds?: number;
+	readonly fill?: string;
+	/** Outline the levels instead of filling them. */
+	readonly stroke?: boolean;
+}
+
+/**
+ * Where points crowd, as nested contours: the shape of a scatter too dense
+ * to read. Decorative on its own (the levels are not values a reader can
+ * visit), so draw the points too, or give the chart a description.
+ */
+export function density2d<TDatum>(
+	data: ReadonlyArray<TDatum>,
+	options: Density2dOptions<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, "density2d", context);
+			const { x: xScale, y: yScale } = context.scales;
+			if (xScale === undefined || yScale === undefined) {
+				return { nodes: [] };
+			}
+			const { plot } = context;
+			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) {
+					pixels.push([xScale.center(x) - plot.x, yScale.center(y) - plot.y]);
+				}
+			}
+			const levels = contourDensity()
+				.x((pixel) => pixel[0])
+				.y((pixel) => pixel[1])
+				.size([
+					Math.max(1, Math.round(plot.width)),
+					Math.max(1, Math.round(plot.height)),
+				])
+				.bandwidth(options.bandwidth ?? 20)
+				.thresholds(options.thresholds ?? 8)(pixels);
+			const color = options.fill ?? context.paletteColor(context.markIndex);
+			const nodes: SceneNode[] = levels.map((level, index) => {
+				const share = levels.length <= 1 ? 1 : (index + 1) / levels.length;
+				return {
+					kind: "path",
+					key: `${id}:${index}`,
+					role: "mark",
+					d: multiPolygonPath(level.coordinates as never, plot.x, plot.y),
+					paint: options.stroke
+						? {
+								fill: "none",
+								stroke: color,
+								strokeWidth: 1,
+								strokeOpacity: 0.3 + 0.7 * share,
+							}
+						: { fill: color, fillOpacity: 0.12 },
+				};
+			});
+			return {
+				nodes: nodes.filter((node) => node.kind !== "path" || node.d !== ""),
+			};
+		},
+	};
+}

package/src/contour/index.ts

@@ -0,0 +1 @@
+export { type Density2dOptions, density2d } from "#/contour/density.ts";

package/src/core/channel.ts

@@ -0,0 +1,53 @@
+import type { ChartAccessor, ChartValue } from "#/core/types.ts";
+
+/** Reads one channel off every datum. A missing field reads as `undefined`, never a throw. */
+export function readChannel<TDatum, TValue>(
+	data: ReadonlyArray<TDatum>,
+	accessor: ChartAccessor<TDatum, TValue> | undefined,
+): ReadonlyArray<TValue | undefined> {
+	if (accessor === undefined) {
+		return data.map(() => undefined);
+	}
+	if (typeof accessor === "function") {
+		return data.map((datum, index) => accessor(datum, index));
+	}
+	return data.map(
+		(datum) => (datum as Record<string, unknown>)[accessor] as TValue,
+	);
+}
+
+/** The field name an accessor reads, for an axis or column heading. */
+export function channelLabel<TDatum, TValue>(
+	accessor: ChartAccessor<TDatum, TValue> | undefined,
+): string | undefined {
+	return typeof accessor === "string" ? accessor : undefined;
+}
+
+/** A value a scale can place: finite numbers, valid dates and strings. */
+export function isPlaceable(value: unknown): value is ChartValue {
+	if (typeof value === "number") {
+		return Number.isFinite(value);
+	}
+	if (value instanceof Date) {
+		return !Number.isNaN(value.getTime());
+	}
+	return typeof value === "string";
+}
+
+/** A number off a channel, or `undefined` for a gap. Numeric strings count. */
+export function numericValue(value: unknown): number | undefined {
+	if (typeof value === "number") {
+		return Number.isFinite(value) ? value : undefined;
+	}
+	if (typeof value === "string" && value.trim() !== "") {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : undefined;
+	}
+	return undefined;
+}
+
+export function placeableValues(
+	values: ReadonlyArray<unknown>,
+): ReadonlyArray<ChartValue> {
+	return values.filter(isPlaceable);
+}

package/src/core/compile.ts

@@ -0,0 +1,436 @@
+import type {
+	ChartDefinition,
+	ChartPositionScaleOptions,
+	ChartSpec,
+} from "#/core/define-chart.ts";
+import { dateValueFormatter, formatValue } from "#/core/format.ts";
+import {
+	type AxisMeasureInput,
+	bottomAxis,
+	bottomMargin,
+	leftAxis,
+	leftMargin,
+	rightMargin,
+} from "#/core/guides/axes.ts";
+import {
+	ordinalColorScale,
+	sequentialColorScale,
+} from "#/core/scales/color.ts";
+import { toNumber } from "#/core/scales/continuous.ts";
+import { categoryKey } from "#/core/scales/discrete.ts";
+import {
+	buildScale,
+	planScale,
+	type ScalePlan,
+} from "#/core/scales/resolve.ts";
+import { estimateTextWidth } from "#/core/text.ts";
+import { DEFAULT_THEME } from "#/core/theme.ts";
+import type {
+	ChartChannel,
+	ChartColorScale,
+	ChartFocusOrder,
+	ChartLegendItem,
+	ChartMargin,
+	ChartMark,
+	ChartPoint,
+	ChartPositionScale,
+	ChartRect,
+	ChartScene,
+	ChartTextMeasurer,
+	ChartTheme,
+	ChartValue,
+	SceneNode,
+} from "#/core/types.ts";
+
+const DEFAULT_LOCALE = "fr-FR";
+const EDGE = 8;
+/** Pixels per tick an axis aims for: about one label every 80 px across, 48 px down. */
+const X_TICK_SPACING = 80;
+const Y_TICK_SPACING = 48;
+const MIN_TICKS = 2;
+
+export interface CompileOptions {
+	readonly width: number;
+	readonly height: number;
+	readonly measureText?: ChartTextMeasurer;
+	/** Series the legend has switched off. The scales keep their domain, so the axes hold still. */
+	readonly hiddenSeries?: ReadonlySet<string>;
+	/** The part of a continuous x on show, when zoomed. */
+	readonly xDomain?: readonly [number, number];
+}
+
+function distinctBy<T>(
+	items: ReadonlyArray<T>,
+	keyOf: (item: T) => string,
+): T[] {
+	const seen = new Set<string>();
+	return items.filter((item) => {
+		const key = keyOf(item);
+		if (seen.has(key)) {
+			return false;
+		}
+		seen.add(key);
+		return true;
+	});
+}
+
+const RAMP_STOPS = 5;
+
+function rampOf(
+	color: ChartColorScale,
+	format: (value: ChartValue) => string,
+): ChartScene["colorRamp"] {
+	const [low, high] = color.domain.map(toNumber);
+	return {
+		stops: Array.from({ length: RAMP_STOPS }, (_unused, index) =>
+			color.map(low + ((high - low) * index) / (RAMP_STOPS - 1)),
+		),
+		low: format(low),
+		high: format(high),
+	};
+}
+
+export function isMark(
+	mark: ChartMark | false | null | undefined,
+): mark is ChartMark {
+	return Boolean(mark);
+}
+
+export function channelsOf(
+	marks: ReadonlyArray<ChartMark>,
+	name: "x" | "y" | "color",
+): ReadonlyArray<ChartChannel> {
+	return marks.flatMap((mark) => {
+		const channel = mark.channels[name];
+		return channel === undefined ? [] : [channel];
+	});
+}
+
+function tickCount(length: number, spacing: number): number {
+	return Math.max(MIN_TICKS, Math.floor(length / spacing));
+}
+
+function colorScaleOf(
+	spec: ChartSpec,
+	channels: ReadonlyArray<ChartChannel>,
+	theme: ChartTheme,
+): ChartColorScale | undefined {
+	if (channels.length === 0) {
+		return undefined;
+	}
+	const options = spec.color;
+	const values = channels.flatMap((channel) => channel.values);
+	const sequential =
+		options?.type === "sequential" ||
+		(options?.type === undefined &&
+			values.length > 0 &&
+			values.every((value) => typeof value === "number"));
+	if (sequential) {
+		const numbers = (options?.domain ?? values).map(toNumber);
+		const [from = theme.background, to = theme.palette[0]] = options?.range ?? [
+			`color-mix(in oklab, ${theme.palette[0]} 12%, ${theme.background})`,
+			theme.palette[0],
+		];
+		return sequentialColorScale(
+			[Math.min(...numbers), Math.max(...numbers)],
+			[from, to],
+		);
+	}
+	const domain = distinctBy(options?.domain ?? values, categoryKey);
+	return ordinalColorScale(domain, options?.range ?? theme.palette);
+}
+
+function withoutHidden(
+	nodes: ReadonlyArray<SceneNode>,
+	hidden: ReadonlySet<string>,
+): ReadonlyArray<SceneNode> {
+	if (hidden.size === 0) {
+		return nodes;
+	}
+	return nodes
+		.filter((node) => node.series === undefined || !hidden.has(node.series))
+		.map((node) =>
+			node.kind === "group"
+				? { ...node, children: withoutHidden(node.children, hidden) }
+				: node,
+		);
+}
+
+function focusOrderOf(
+	spec: ChartSpec,
+	marks: ReadonlyArray<ChartMark>,
+	x: ChartPositionScale | undefined,
+	y: ChartPositionScale | undefined,
+): ChartFocusOrder {
+	if (spec.focus !== undefined) {
+		return spec.focus;
+	}
+	if (
+		marks.some(
+			(mark) => mark.coordinate === "frame" || mark.focusOrder === "point",
+		)
+	) {
+		return "point";
+	}
+	const yDiscrete = y?.kind === "band" || y?.kind === "point";
+	const xDiscrete = x?.kind === "band" || x?.kind === "point";
+	return yDiscrete && !xDiscrete ? "y" : "x";
+}
+
+function marginFor(
+	spec: ChartSpec,
+	width: number,
+	xInput: AxisMeasureInput | undefined,
+	yInput: AxisMeasureInput | undefined,
+	fontSize: number,
+): ChartMargin {
+	const computed: ChartMargin = {
+		top: yInput === undefined ? EDGE : Math.max(EDGE, fontSize / 2 + 2),
+		right: xInput === undefined ? EDGE : rightMargin(xInput),
+		bottom: xInput === undefined ? EDGE : bottomMargin(xInput),
+		left: yInput === undefined ? EDGE : leftMargin(yInput, width),
+	};
+	return { ...computed, ...spec.margin };
+}
+
+/**
+ * Definition and size in, scene out. Pure: the same inputs give the same
+ * scene, on the server and in the browser, which is what lets the SVG render
+ * on the server hydrate without a mismatch.
+ */
+export function compileChart(
+	definition: ChartDefinition,
+	options: CompileOptions,
+): ChartScene {
+	const spec = definition.build({
+		width: options.width,
+		height: options.height,
+	});
+	return spec.facet === undefined
+		? compileSpec(spec, options)
+		: spec.facet.compile(spec, { ...options, compileCell: compileSpec });
+}
+
+/** One chart's scene from its spec: what `compileChart` does once per facet cell. */
+export function compileSpec(
+	spec: ChartSpec,
+	options: CompileOptions,
+): ChartScene {
+	const { width, height } = options;
+	const measureText = options.measureText ?? estimateTextWidth;
+	const hidden = options.hiddenSeries ?? new Set<string>();
+	const locale = spec.locale ?? DEFAULT_LOCALE;
+	const theme: ChartTheme = { ...DEFAULT_THEME, ...spec.theme };
+	const marks = (spec.marks ?? []).filter(isMark);
+	const cartesian = marks.filter((mark) => mark.coordinate === "cartesian");
+
+	const plannedX = planScale(channelsOf(cartesian, "x"), spec.x, "x");
+	// A zoomed chart shows part of a continuous x: the viewport replaces the
+	// domain, and the marks are clipped to the plot.
+	const zoomed =
+		options.xDomain !== undefined &&
+		plannedX !== undefined &&
+		plannedX.kind !== "band" &&
+		plannedX.kind !== "point";
+	const xPlan =
+		zoomed && plannedX && options.xDomain
+			? { ...plannedX, domain: options.xDomain }
+			: plannedX;
+	const yPlan = planScale(channelsOf(cartesian, "y"), spec.y, "y");
+
+	// First pass: scales over the whole chart, only to measure tick labels.
+	function provisional(
+		plan: ScalePlan | undefined,
+		axisOptions: ChartPositionScaleOptions | undefined,
+		range: readonly [number, number],
+		count: number,
+	): AxisMeasureInput | undefined {
+		if (plan === undefined) {
+			return undefined;
+		}
+		return {
+			scale: buildScale(plan, axisOptions, range, locale, count),
+			options: axisOptions,
+			title: axisOptions?.label,
+			theme,
+			measureText,
+		};
+	}
+	const yDiscrete = yPlan?.kind === "band" || yPlan?.kind === "point";
+	const yRange = (top: number, bottom: number): readonly [number, number] =>
+		yDiscrete ? [top, bottom] : [bottom, top];
+
+	const margin = marginFor(
+		spec,
+		width,
+		provisional(xPlan, spec.x, [0, width], tickCount(width, X_TICK_SPACING)),
+		provisional(
+			yPlan,
+			spec.y,
+			yRange(0, height),
+			tickCount(height, Y_TICK_SPACING),
+		),
+		theme.fontSize,
+	);
+	const plot: ChartRect = {
+		x: margin.left,
+		y: margin.top,
+		width: Math.max(0, width - margin.left - margin.right),
+		height: Math.max(0, height - margin.top - margin.bottom),
+	};
+
+	function insetOf(name: "x" | "y"): number {
+		return Math.max(
+			0,
+			...channelsOf(cartesian, name).map((channel) => channel.inset ?? 0),
+		);
+	}
+	const xInset = insetOf("x");
+	const yInset = insetOf("y");
+	const x =
+		xPlan &&
+		buildScale(
+			xPlan,
+			spec.x,
+			[plot.x + xInset, plot.x + plot.width - xInset],
+			locale,
+			tickCount(plot.width, X_TICK_SPACING),
+		);
+	const y =
+		yPlan &&
+		buildScale(
+			yPlan,
+			spec.y,
+			yRange(plot.y + yInset, plot.y + plot.height - yInset),
+			locale,
+			tickCount(plot.height, Y_TICK_SPACING),
+		);
+	const color = colorScaleOf(spec, channelsOf(marks, "color"), theme);
+	const scales = { x, y, color };
+
+	function channelFormatter(
+		channels: ReadonlyArray<ChartChannel>,
+		custom: ((value: ChartValue) => string) | undefined,
+	): (value: ChartValue) => string {
+		if (custom !== undefined) {
+			return custom;
+		}
+		const dates = dateValueFormatter(
+			channels.flatMap((channel) => channel.values),
+			locale,
+		);
+		return (value) =>
+			dates !== undefined && value instanceof Date
+				? dates(value)
+				: formatValue(value, locale);
+	}
+	const formatX = channelFormatter(channelsOf(cartesian, "x"), spec.x?.format);
+	const formatY = channelFormatter(channelsOf(cartesian, "y"), spec.y?.format);
+	const seriesLabel = (value: ChartValue) =>
+		spec.color?.labels?.[categoryKey(value)] ?? formatValue(value, locale);
+
+	const grid: SceneNode[] = [];
+	const guides: SceneNode[] = [];
+	const xContinuous =
+		x !== undefined && x.kind !== "band" && x.kind !== "point";
+	const yContinuous =
+		y !== undefined && y.kind !== "band" && y.kind !== "point";
+	if (x !== undefined) {
+		const axis = bottomAxis(
+			{ scale: x, options: spec.x, title: spec.x?.label, theme, measureText },
+			plot,
+			spec.x?.grid ?? (xContinuous && !yContinuous),
+		);
+		grid.push(...axis.grid);
+		guides.push(...axis.labels);
+	}
+	if (y !== undefined) {
+		const axis = leftAxis(
+			{ scale: y, options: spec.y, title: spec.y?.label, theme, measureText },
+			plot,
+			spec.y?.grid ?? yContinuous,
+			width,
+		);
+		grid.push(...axis.grid);
+		guides.push(...axis.labels);
+	}
+
+	const markNodes: SceneNode[] = [];
+	const points: ChartPoint[] = [];
+	const legend: ChartLegendItem[] = [];
+	const paletteColor = (index: number) =>
+		theme.palette[index % theme.palette.length];
+	const projection = spec.projection?.fit(plot);
+	for (const [markIndex, mark] of marks.entries()) {
+		const rendered = mark.render({
+			scales,
+			plot,
+			theme,
+			measureText,
+			locale,
+			paletteColor,
+			colorOf: (value) => color?.map(value) ?? paletteColor(markIndex),
+			seriesLabel,
+			formatX,
+			formatY,
+			markIndex,
+			projection,
+		});
+		markNodes.push(...rendered.nodes);
+		points.push(
+			...(rendered.points ?? []).filter(
+				(point) => point.series === undefined || !hidden.has(point.series),
+			),
+		);
+		legend.push(...(rendered.legend ?? []));
+	}
+
+	const colored = marks.filter((mark) => mark.channels.color !== undefined);
+	const legendWanted =
+		spec.color?.legend ?? colored.some((mark) => mark.colorLegend !== false);
+	if (color?.kind === "ordinal" && legendWanted) {
+		for (const value of color.domain) {
+			legend.push({
+				key: categoryKey(value),
+				label: seriesLabel(value),
+				color: color.map(value),
+				shape: "square",
+			});
+		}
+	}
+
+	return {
+		width,
+		height,
+		plot,
+		nodes: [
+			{ kind: "group", key: "grid", role: "grid", children: grid },
+			{
+				kind: "group",
+				key: "marks",
+				role: "marks",
+				clip: zoomed ? plot : undefined,
+				children: withoutHidden(markNodes, hidden),
+			},
+			{ kind: "group", key: "axes", role: "axes", children: guides },
+		],
+		points,
+		legend: distinctBy(legend, (item) => item.key),
+		focusOrder: focusOrderOf(spec, marks, x, y),
+		scales,
+		xLabel:
+			xPlan?.label ??
+			marks.find((mark) => mark.titles?.category)?.titles?.category ??
+			"x",
+		yLabel:
+			yPlan?.label ??
+			marks.find((mark) => mark.titles?.value)?.titles?.value ??
+			"y",
+		theme,
+		locale,
+		colorRamp:
+			color?.kind === "sequential" && spec.color?.legend !== false
+				? rampOf(color, (value) => formatValue(value, locale))
+				: undefined,
+	};
+}

package/src/core/define-chart.ts

@@ -0,0 +1,128 @@
+import type {
+	ChartFocusOrder,
+	ChartMargin,
+	ChartMark,
+	ChartPositionScaleKind,
+	ChartProjection,
+	ChartScene,
+	ChartTextMeasurer,
+	ChartTheme,
+	ChartValue,
+} from "#/core/types.ts";
+
+export interface ChartAxisOptions {
+	/** Axis title, data-table column heading and tooltip heading. */
+	readonly label?: string;
+	/** `false` hides the axis; the scale still places the marks. */
+	readonly axis?: boolean;
+	readonly grid?: boolean;
+	/** A tick count to aim for, or the exact values to tick. */
+	readonly ticks?: number | ReadonlyArray<ChartValue>;
+	readonly tickFormat?: (value: ChartValue) => string;
+	/** How the tooltip, live region and data table write a value of this channel. */
+	readonly format?: (value: ChartValue) => string;
+}
+
+export interface ChartPositionScaleOptions extends ChartAxisOptions {
+	readonly type?: ChartPositionScaleKind;
+	readonly domain?: ReadonlyArray<ChartValue>;
+	/** Widen a continuous domain to round ticks. On by default for y. */
+	readonly nice?: boolean;
+	/** Keep zero on a continuous domain even when no mark asks for it. */
+	readonly zero?: boolean;
+	readonly reverse?: boolean;
+	readonly paddingInner?: number;
+	readonly paddingOuter?: number;
+}
+
+export interface ChartColorOptions {
+	readonly type?: "ordinal" | "sequential";
+	readonly domain?: ReadonlyArray<ChartValue>;
+	/** Palette for an ordinal scale, `[from, to]` for a sequential one. */
+	readonly range?: ReadonlyArray<string>;
+	readonly legend?: boolean;
+	/** Display names of the series, by value. */
+	readonly labels?: Readonly<Record<string, string>>;
+}
+
+/**
+ * Small multiples: the same chart once per value, on a grid, every cell on
+ * the same scales so the cells compare at a glance.
+ */
+export interface ChartFacetOptions {
+	readonly values: ReadonlyArray<ChartValue>;
+	/** The marks of one cell. */
+	readonly marks: (
+		value: ChartValue,
+		index: number,
+	) => ReadonlyArray<ChartMark | false | null | undefined>;
+	readonly label?: (value: ChartValue) => string;
+	/** Cells per row. Defaults to three, or fewer when there are fewer values. */
+	readonly columns?: number;
+	/** Pixels between two cells. */
+	readonly gap?: number;
+}
+
+/**
+ * What `facet(…)` returns: the options, and the compiler that lays the cells
+ * out. Carried by the spec rather than imported by the core, so a chart
+ * without facets never ships the facet code.
+ */
+export interface ChartFacet {
+	readonly options: ChartFacetOptions;
+	readonly compile: (
+		spec: ChartSpec,
+		options: ChartFacetCompileOptions,
+	) => ChartScene;
+}
+
+/** The compile options a facet compiler is handed, plus the per-cell compiler. */
+export interface ChartFacetCompileOptions {
+	readonly width: number;
+	readonly height: number;
+	readonly measureText?: ChartTextMeasurer;
+	readonly hiddenSeries?: ReadonlySet<string>;
+	readonly xDomain?: readonly [number, number];
+	readonly compileCell: (
+		spec: ChartSpec,
+		options: Omit<ChartFacetCompileOptions, "compileCell">,
+	) => ChartScene;
+}
+
+export interface ChartSpec {
+	/** Falsy entries are skipped, so a mark can be switched on with `&&`. Unused with `facet`. */
+	readonly marks?: ReadonlyArray<ChartMark | false | null | undefined>;
+	readonly x?: ChartPositionScaleOptions;
+	readonly y?: ChartPositionScaleOptions;
+	readonly color?: ChartColorOptions;
+	/** Overrides the margins the axes would reserve, side by side. */
+	readonly margin?: Partial<ChartMargin>;
+	readonly focus?: ChartFocusOrder;
+	/** Small multiples, from `facet(…)`. With it, `marks` is ignored: each cell takes its own. */
+	readonly facet?: ChartFacet;
+	/** For maps: how longitude and latitude become pixels. */
+	readonly projection?: ChartProjection;
+	readonly locale?: string;
+	readonly theme?: Partial<ChartTheme>;
+}
+
+export interface ChartBuildContext {
+	readonly width: number;
+	readonly height: number;
+}
+
+export interface ChartDefinition {
+	readonly build: (context: ChartBuildContext) => ChartSpec;
+}
+
+/**
+ * A chart as data. Pass the spec when it does not depend on the size, or a
+ * builder when it does (fewer ticks on a phone, a different layout below some
+ * width). Build it in `useMemo`: the definition's identity is what tells the
+ * renderer the data changed.
+ */
+export function defineChart(
+	spec: ChartSpec | ((context: ChartBuildContext) => ChartSpec),
+): ChartDefinition {
+	return { build: typeof spec === "function" ? spec : () => spec };
+}