@voila.dev/chart 4.0.0

package/src/core/marks/dot.ts

@@ -0,0 +1,157 @@
+import {
+	channelLabel,
+	isPlaceable,
+	numericValue,
+	readChannel,
+} from "#/core/channel.ts";
+import {
+	type ChartMarkOptions,
+	colorChannel,
+	markId,
+	paint,
+	seriesResolver,
+	valueOn,
+} from "#/core/marks/shared.ts";
+import type {
+	ChartAccessor,
+	ChartMark,
+	ChartPoint,
+	ChartValue,
+	SceneNode,
+} from "#/core/types.ts";
+
+export interface DotOptions<TDatum> extends ChartMarkOptions<TDatum> {
+	readonly x?: ChartAccessor<TDatum, ChartValue>;
+	readonly y?: ChartAccessor<TDatum, ChartValue>;
+	/** A radius in pixels, or a field whose values set the area of each dot. */
+	readonly r?: number | ChartAccessor<TDatum, ChartValue>;
+	/** The largest radius a sized dot reaches. */
+	readonly maxRadius?: number;
+	readonly fill?: string;
+	readonly fillOpacity?: number;
+	readonly stroke?: string;
+	readonly strokeWidth?: number;
+}
+
+const DEFAULT_RADIUS = 4;
+const DEFAULT_MAX_RADIUS = 16;
+
+/** A dot per datum: a scatter plot, or a bubble chart when `r` is a field. */
+export function dot<TDatum>(
+	data: ReadonlyArray<TDatum>,
+	options: DotOptions<TDatum> = {},
+): ChartMark {
+	const xs = readChannel(
+		data,
+		options.x ?? ((_datum: TDatum, index: number) => index),
+	);
+	const ys = readChannel(
+		data,
+		options.y ?? ((datum: TDatum) => datum as unknown as ChartValue),
+	);
+	const colors = colorChannel(data, options);
+	const sized = options.r !== undefined && typeof options.r !== "number";
+	const sizes = sized
+		? readChannel(data, options.r as ChartAccessor<TDatum, ChartValue>).map(
+				numericValue,
+			)
+		: [];
+	const largest = Math.max(0, ...sizes.map((size) => Math.abs(size ?? 0)));
+	const reach =
+		typeof options.r === "number"
+			? options.r
+			: sized
+				? (options.maxRadius ?? DEFAULT_MAX_RADIUS)
+				: DEFAULT_RADIUS;
+
+	return {
+		id: options.id,
+		coordinate: "cartesian",
+		focusOrder: "point",
+		channels: {
+			x: {
+				values: xs.filter(isPlaceable),
+				label: channelLabel(options.x),
+				inset: reach,
+			},
+			y: {
+				values: ys.filter(isPlaceable),
+				label: channelLabel(options.y) ?? options.label,
+				inset: reach,
+			},
+			color: colors.channel,
+		},
+		render(context) {
+			const id = markId(options.id, "dot", context);
+			const { x: xScale, y: yScale } = context.scales;
+			if (xScale === undefined || yScale === undefined) {
+				return { nodes: [] };
+			}
+			const seriesOf = seriesResolver(
+				colors.values,
+				{ ...options, fixedColor: options.fill },
+				id,
+				context,
+			);
+			const maxRadius = options.maxRadius ?? DEFAULT_MAX_RADIUS;
+			// Area, not radius, carries the value: a dot twice the value looks twice as big.
+			function radiusOf(index: number): number {
+				if (typeof options.r === "number") return options.r;
+				if (!sized) return DEFAULT_RADIUS;
+				const size = Math.abs(sizes[index] ?? 0);
+				return largest === 0 ? 0 : Math.sqrt(size / largest) * maxRadius;
+			}
+			const nodes: SceneNode[] = [];
+			const points: ChartPoint[] = [];
+			for (const [index, datum] of data.entries()) {
+				const xValue = valueOn(xScale, xs[index]);
+				const yValue = valueOn(yScale, ys[index]);
+				if (xValue === undefined || yValue === undefined) {
+					continue;
+				}
+				const series = seriesOf(index);
+				const cx = xScale.center(xValue);
+				const cy = yScale.center(yValue);
+				const r = radiusOf(index);
+				nodes.push({
+					kind: "circle",
+					key: `${id}:${index}`,
+					series: series.key,
+					role: "mark",
+					cx,
+					cy,
+					r,
+					paint: paint({
+						fill: series.color,
+						fillOpacity: options.fillOpacity,
+						stroke: options.stroke,
+						strokeWidth: options.strokeWidth,
+						opacity: options.opacity,
+					}),
+				});
+				if (options.tip !== false) {
+					points.push({
+						key: `${id}:${index}`,
+						markId: id,
+						index,
+						datum,
+						x: cx,
+						y: cy,
+						xValue,
+						yValue,
+						series: series.key,
+						seriesLabel: series.label,
+						color: series.color,
+						title: context.formatX(xValue),
+						value: context.formatY(yValue),
+						hit: {
+							kind: "rect",
+							rect: { x: cx - r, y: cy - r, width: r * 2, height: r * 2 },
+						},
+					});
+				}
+			}
+			return { nodes, points };
+		},
+	};
+}

package/src/core/marks/funnel-layout.ts

@@ -0,0 +1,113 @@
+/**
+ * Funnel geometry, worked out away from React so it can be asserted on
+ * directly. One slice per step: a horizontal band whose left edge is as tall
+ * as the step's value and whose right edge slopes down to the next step's
+ * value, so the drop between two steps is visible as the flank itself.
+ */
+
+export interface FunnelSlice {
+	/** Index of the datum, i.e. of the category slot. */
+	readonly index: number;
+	readonly value: number;
+	/** Left edge of the band, in plot coordinates. */
+	readonly x: number;
+	readonly width: number;
+	/** Height of the left flank, proportional to the step's value. */
+	readonly leftHeight: number;
+	/** Height of the right flank — the next step's value, or its own on the last step. */
+	readonly rightHeight: number;
+	/** The trapezoid, vertically centred on the band. `""` when there is nothing to draw. */
+	readonly path: string;
+	/** Conversion into the next step. `null` on the last step or when this one is empty. */
+	readonly ratioToNext: number | null;
+}
+
+export interface FunnelLayoutOptions {
+	readonly values: ReadonlyArray<number>;
+	readonly innerWidth: number;
+	readonly innerHeight: number;
+	/** Pixels of blank between two bands. */
+	readonly gap?: number;
+	/** Vertical centre line of the funnel. Defaults to half the inner height. */
+	readonly centerY?: number;
+	/** Height the largest value maps to. Defaults to the inner height. */
+	readonly maxHeight?: number;
+	/** Left edge of the first band. */
+	readonly originX?: number;
+}
+
+const DEFAULT_GAP = 4;
+const PATH_PRECISION = 2;
+
+function round(value: number): number {
+	const factor = 10 ** PATH_PRECISION;
+	return Math.round(value * factor) / factor;
+}
+
+function point(x: number, y: number): string {
+	return `${round(x)},${round(y)}`;
+}
+
+function trapezoidPath(
+	x: number,
+	width: number,
+	centerY: number,
+	leftHeight: number,
+	rightHeight: number,
+): string {
+	if (width <= 0 || (leftHeight <= 0 && rightHeight <= 0)) {
+		return "";
+	}
+	const right = x + width;
+	return [
+		`M${point(x, centerY - leftHeight / 2)}`,
+		`L${point(right, centerY - rightHeight / 2)}`,
+		`L${point(right, centerY + rightHeight / 2)}`,
+		`L${point(x, centerY + leftHeight / 2)}`,
+		"Z",
+	].join("");
+}
+
+export function funnelSlices(
+	options: FunnelLayoutOptions,
+): ReadonlyArray<FunnelSlice> {
+	const {
+		values,
+		innerWidth,
+		innerHeight,
+		gap = DEFAULT_GAP,
+		centerY = innerHeight / 2,
+		maxHeight = innerHeight,
+		originX = 0,
+	} = options;
+
+	const count = values.length;
+	if (count === 0 || innerWidth <= 0 || maxHeight <= 0) {
+		return [];
+	}
+
+	const clamped = values.map((value) => Math.max(0, value));
+	const peak = Math.max(...clamped);
+	const heightFor = (value: number): number =>
+		peak <= 0 ? 0 : (value / peak) * maxHeight;
+
+	const bandWidth = Math.max(0, (innerWidth - gap * (count - 1)) / count);
+
+	return clamped.map((value, index) => {
+		const next = clamped[index + 1];
+		const leftHeight = heightFor(value);
+		// The last band has no next step to taper into, so it stays a rectangle.
+		const rightHeight = next === undefined ? leftHeight : heightFor(next);
+		const x = originX + index * (bandWidth + gap);
+		return {
+			index,
+			value: values[index],
+			x,
+			width: bandWidth,
+			leftHeight,
+			rightHeight,
+			path: trapezoidPath(x, bandWidth, centerY, leftHeight, rightHeight),
+			ratioToNext: next === undefined || value <= 0 ? null : next / value,
+		};
+	});
+}

package/src/core/marks/funnel.ts

@@ -0,0 +1,172 @@
+import {
+	channelLabel,
+	isPlaceable,
+	numericValue,
+	readChannel,
+} from "#/core/channel.ts";
+import { formatPercentage } from "#/core/format.ts";
+import { funnelSlices } from "#/core/marks/funnel-layout.ts";
+import {
+	type ChartMarkOptions,
+	markId,
+	paint,
+	seriesResolver,
+} from "#/core/marks/shared.ts";
+import { categoryKey } from "#/core/scales/discrete.ts";
+import type {
+	ChartAccessor,
+	ChartMark,
+	ChartPoint,
+	ChartValue,
+	SceneNode,
+} from "#/core/types.ts";
+
+export interface FunnelOptions<TDatum> extends ChartMarkOptions<TDatum> {
+	/** The step: "Visites", "Inscriptions", "Missions". */
+	readonly category: ChartAccessor<TDatum, ChartValue>;
+	readonly value: ChartAccessor<TDatum, ChartValue>;
+	/** Pixels of blank between two steps. */
+	readonly gap?: number;
+	readonly fill?: string;
+	/** `false` drops the step name and value written above each step. */
+	readonly labels?: boolean;
+}
+
+/** Room kept above the shape for each step's name and value. */
+const LABEL_ZONE = 36;
+
+/**
+ * Steps left to right, each as tall as its value, each sloping down to the
+ * next: the drop between two stages is the shape itself. The tooltip gives
+ * the conversion from the step before.
+ */
+export function funnel<TDatum>(
+	data: ReadonlyArray<TDatum>,
+	options: FunnelOptions<TDatum>,
+): ChartMark {
+	const categories = readChannel(data, options.category);
+	const values = readChannel(data, options.value).map(
+		(value) => numericValue(value) ?? 0,
+	);
+	const colorAccessor = options.color ?? options.category;
+	const colors = readChannel(data, colorAccessor);
+	return {
+		id: options.id,
+		coordinate: "frame",
+		focusOrder: "point",
+		colorLegend: options.labels === false,
+		titles: {
+			category: channelLabel(options.category),
+			value: channelLabel(options.value) ?? options.label,
+		},
+		channels: {
+			color: {
+				values: colors.filter(isPlaceable),
+				label: channelLabel(colorAccessor),
+			},
+		},
+		render(context) {
+			const id = markId(options.id, "funnel", context);
+			const { plot, theme } = context;
+			const labelled = options.labels !== false;
+			const top = plot.y + (labelled ? LABEL_ZONE : 0);
+			const height = Math.max(0, plot.height - (labelled ? LABEL_ZONE : 0));
+			const slices = funnelSlices({
+				values,
+				innerWidth: plot.width,
+				innerHeight: height,
+				centerY: top + height / 2,
+				originX: plot.x,
+				gap: options.gap,
+			});
+			const seriesOf = seriesResolver(
+				colors,
+				{ ...options, color: colorAccessor, fixedColor: options.fill },
+				id,
+				context,
+			);
+			const nodes: SceneNode[] = [];
+			const points: ChartPoint[] = [];
+			for (const slice of slices) {
+				const category = categories[slice.index];
+				if (!isPlaceable(category) || slice.path === "") {
+					continue;
+				}
+				const series = seriesOf(slice.index);
+				const key = categoryKey(category);
+				nodes.push({
+					kind: "path",
+					key: `${id}:${key}`,
+					series: series.key,
+					role: "mark",
+					d: slice.path,
+					paint: paint({ fill: series.color, opacity: options.opacity }),
+				});
+				if (labelled) {
+					nodes.push(
+						{
+							kind: "text",
+							key: `${id}:name:${key}`,
+							role: "label",
+							x: slice.x,
+							y: plot.y,
+							text: series.label ?? context.formatX(category),
+							paint: {
+								fill: theme.muted,
+								fontSize: theme.fontSize,
+								baseline: "top",
+							},
+						},
+						{
+							kind: "text",
+							key: `${id}:value:${key}`,
+							role: "label",
+							x: slice.x,
+							y: plot.y + theme.fontSize + 4,
+							text: context.formatY(slice.value),
+							paint: {
+								fill: theme.foreground,
+								fontSize: theme.fontSize + 2,
+								fontWeight: 600,
+								baseline: "top",
+							},
+						},
+					);
+				}
+				if (options.tip === false) {
+					continue;
+				}
+				const previous = slice.index > 0 ? values[slice.index - 1] : undefined;
+				const conversion =
+					previous !== undefined && previous > 0
+						? ` (${formatPercentage(slice.value / previous, context.locale)})`
+						: "";
+				const centerY = top + height / 2;
+				points.push({
+					key: `${id}:${key}`,
+					markId: id,
+					index: slice.index,
+					datum: data[slice.index],
+					x: slice.x + slice.width / 2,
+					y: centerY,
+					xValue: category,
+					yValue: slice.value,
+					series: series.key,
+					color: series.color,
+					title: series.label ?? context.formatX(category),
+					value: `${context.formatY(slice.value)}${conversion}`,
+					hit: {
+						kind: "rect",
+						rect: {
+							x: slice.x,
+							y: centerY - slice.leftHeight / 2,
+							width: slice.width,
+							height: slice.leftHeight,
+						},
+					},
+				});
+			}
+			return { nodes, points };
+		},
+	};
+}

package/src/core/marks/line.ts

@@ -0,0 +1,206 @@
+import { channelLabel, isPlaceable, readChannel } from "#/core/channel.ts";
+import {
+	type ChartMarkOptions,
+	colorChannel,
+	groupBySeries,
+	markId,
+	paint,
+	seriesResolver,
+	valueOn,
+} from "#/core/marks/shared.ts";
+import { type ChartXY, linePath } from "#/core/paths.ts";
+import type {
+	ChartAccessor,
+	ChartCurve,
+	ChartMark,
+	ChartPoint,
+	ChartValue,
+	SceneNode,
+} from "#/core/types.ts";
+
+export interface LineOptions<TDatum> extends ChartMarkOptions<TDatum> {
+	readonly x?: ChartAccessor<TDatum, ChartValue>;
+	readonly y?: ChartAccessor<TDatum, ChartValue>;
+	readonly stroke?: string;
+	readonly strokeWidth?: number;
+	readonly strokeDasharray?: string;
+	readonly curve?: ChartCurve;
+	/** A dot on every point, not only on the focused one. */
+	readonly dots?: boolean;
+}
+
+const DEFAULT_STROKE_WIDTH = 2;
+const DOT_RADIUS = 3;
+
+/** With no accessor, a line of plain numbers plots each against its index. */
+function positionAccessor<TDatum>(
+	accessor: ChartAccessor<TDatum, ChartValue> | undefined,
+	fallback: "index" | "identity",
+): ChartAccessor<TDatum, ChartValue> {
+	if (accessor !== undefined) {
+		return accessor;
+	}
+	return fallback === "index"
+		? (_datum, index) => index
+		: (datum) => datum as unknown as ChartValue;
+}
+
+function lineMark<TDatum>(
+	kind: "lineY" | "lineX",
+	data: ReadonlyArray<TDatum>,
+	options: LineOptions<TDatum>,
+): ChartMark {
+	// lineY: the value runs up the y axis; lineX: along x, positions down y.
+	const vertical = kind === "lineY";
+	const positionKey = vertical ? options.x : options.y;
+	const valueKey = vertical ? options.y : options.x;
+	const positions = readChannel(data, positionAccessor(positionKey, "index"));
+	const values = readChannel(data, positionAccessor(valueKey, "identity"));
+	const colors = colorChannel(data, options);
+	const positionChannel = {
+		values: positions.filter(isPlaceable),
+		label: channelLabel(positionKey),
+	};
+	const valueChannel = {
+		values: values.filter(isPlaceable),
+		label: channelLabel(valueKey) ?? options.label,
+	};
+
+	return {
+		id: options.id,
+		coordinate: "cartesian",
+		focusOrder: vertical ? "x" : "y",
+		channels: {
+			x: vertical ? positionChannel : valueChannel,
+			y: vertical ? valueChannel : positionChannel,
+			color: colors.channel,
+		},
+		render(context) {
+			const id = markId(options.id, kind, context);
+			const positionScale = vertical ? context.scales.x : context.scales.y;
+			const valueScale = vertical ? context.scales.y : context.scales.x;
+			if (positionScale === undefined || valueScale === undefined) {
+				return { nodes: [] };
+			}
+			const seriesOf = seriesResolver(
+				colors.values,
+				{ ...options, fixedColor: options.stroke },
+				id,
+				context,
+			);
+			const lines: SceneNode[] = [];
+			const dots: SceneNode[] = [];
+			const points: ChartPoint[] = [];
+
+			for (const { series, indices } of groupBySeries(
+				data.length,
+				seriesOf,
+			).values()) {
+				// A gap in the data is a gap in the line, not a dive to zero.
+				const runs: ChartXY[][] = [[]];
+				for (const index of indices) {
+					const position = positions[index];
+					const value = valueOn(valueScale, values[index]);
+					if (!isPlaceable(position) || value === undefined) {
+						runs.push([]);
+						continue;
+					}
+					const along = positionScale.center(position);
+					const across = valueScale.center(value);
+					const xy = vertical
+						? { x: along, y: across }
+						: { x: across, y: along };
+					runs[runs.length - 1].push(xy);
+					if (options.tip !== false) {
+						points.push({
+							key: `${id}:${index}`,
+							markId: id,
+							index,
+							datum: data[index],
+							x: xy.x,
+							y: xy.y,
+							xValue: vertical ? position : value,
+							yValue: vertical ? value : position,
+							series: series.key,
+							seriesLabel: series.label,
+							color: series.color,
+							title: vertical
+								? context.formatX(position)
+								: context.formatY(position),
+							value: vertical ? context.formatY(value) : context.formatX(value),
+						});
+					}
+					if (options.dots) {
+						dots.push({
+							kind: "circle",
+							key: `${id}:dot:${index}`,
+							series: series.key,
+							role: "mark",
+							cx: xy.x,
+							cy: xy.y,
+							r: DOT_RADIUS,
+							paint: paint({
+								fill: series.color,
+								stroke: context.theme.background,
+								strokeWidth: 1.5,
+								opacity: options.opacity,
+							}),
+						});
+					}
+				}
+				const d = runs
+					.map((run) => linePath(run, options.curve))
+					.filter((part) => part !== "")
+					.join("");
+				lines.push({
+					kind: "path",
+					key: `${id}:line:${series.key}`,
+					series: series.key,
+					role: "mark",
+					d,
+					paint: paint({
+						stroke: series.color,
+						strokeWidth: options.strokeWidth ?? DEFAULT_STROKE_WIDTH,
+						strokeDasharray: options.strokeDasharray,
+						strokeLinecap: "round",
+						strokeLinejoin: "round",
+						fill: "none",
+						opacity: options.opacity,
+					}),
+				});
+			}
+
+			const legend =
+				options.color === undefined && options.label !== undefined
+					? [
+							{
+								key: id,
+								label: options.label,
+								color:
+									options.stroke ?? context.paletteColor(context.markIndex),
+								shape: options.strokeDasharray
+									? ("dashed" as const)
+									: ("line" as const),
+							},
+						]
+					: [];
+			return { nodes: [...lines, ...dots], points, legend };
+		},
+	};
+}
+
+/** A line whose value runs up the y axis, over x positions: a time series. */
+export function lineY<TDatum>(
+	data: ReadonlyArray<TDatum>,
+	options: LineOptions<TDatum> = {},
+): ChartMark {
+	return lineMark("lineY", data, options);
+}
+
+/** A line whose value runs along x, over y positions. */
+export function lineX<TDatum>(
+	data: ReadonlyArray<TDatum>,
+	options: LineOptions<TDatum> = {},
+): ChartMark {
+	return lineMark("lineX", data, options);
+}