@voila.dev/chart 4.0.0

package/src/core/marks/rule.ts

@@ -0,0 +1,104 @@
+import { isPlaceable, readChannel } from "#/core/channel.ts";
+import { markId, paint, valueOn } from "#/core/marks/shared.ts";
+import type {
+	ChartAccessor,
+	ChartMark,
+	ChartValue,
+	SceneNode,
+} from "#/core/types.ts";
+
+export interface RuleOptions<TDatum> {
+	readonly id?: string;
+	/** The value of each rule. Defaults to the datum itself, so `ruleY([0])` works. */
+	readonly value?: ChartAccessor<TDatum, ChartValue>;
+	readonly stroke?: string;
+	readonly strokeWidth?: number;
+	readonly strokeDasharray?: string;
+	readonly opacity?: number;
+	/** Text written at the end of the rule: "Objectif", "Moyenne". */
+	readonly label?: string;
+}
+
+const LABEL_GAP = 4;
+
+function ruleMark<TDatum>(
+	kind: "ruleY" | "ruleX",
+	data: ReadonlyArray<TDatum>,
+	options: RuleOptions<TDatum>,
+): ChartMark {
+	const horizontal = kind === "ruleY";
+	const values = readChannel(
+		data,
+		options.value ?? ((datum: TDatum) => datum as unknown as ChartValue),
+	);
+	const channel = { values: values.filter(isPlaceable) };
+	return {
+		id: options.id,
+		coordinate: "cartesian",
+		channels: horizontal ? { y: channel } : { x: channel },
+		render(context) {
+			const id = markId(options.id, kind, context);
+			const scale = horizontal ? context.scales.y : context.scales.x;
+			if (scale === undefined) {
+				return { nodes: [] };
+			}
+			const { plot, theme } = context;
+			const stroke = options.stroke ?? theme.foreground;
+			const nodes: SceneNode[] = [];
+			for (const [index, raw] of values.entries()) {
+				const value = valueOn(scale, raw);
+				if (value === undefined) {
+					continue;
+				}
+				const at = scale.center(value);
+				nodes.push({
+					kind: "line",
+					key: `${id}:${index}`,
+					role: "rule",
+					...(horizontal
+						? { x1: plot.x, y1: at, x2: plot.x + plot.width, y2: at }
+						: { x1: at, y1: plot.y, x2: at, y2: plot.y + plot.height }),
+					paint: paint({
+						stroke,
+						strokeWidth: options.strokeWidth ?? 1,
+						strokeDasharray: options.strokeDasharray,
+						opacity: options.opacity,
+					}),
+				});
+				if (options.label !== undefined) {
+					nodes.push({
+						kind: "text",
+						key: `${id}:label:${index}`,
+						role: "label",
+						x: horizontal ? plot.x + plot.width : at + LABEL_GAP,
+						y: horizontal ? at - LABEL_GAP : plot.y,
+						text: options.label,
+						paint: {
+							fill: stroke,
+							fontSize: theme.fontSize,
+							textAnchor: horizontal ? "end" : "start",
+							baseline: horizontal ? "bottom" : "top",
+						},
+					});
+				}
+			}
+			return { nodes };
+		},
+	};
+}
+
+/** Horizontal rules at y values: a baseline, a target, an average. */
+export function ruleY<TDatum>(
+	data: ReadonlyArray<TDatum>,
+	options: RuleOptions<TDatum> = {},
+): ChartMark {
+	return ruleMark("ruleY", data, options);
+}
+
+/** Vertical rules at x values: a date, a threshold. */
+export function ruleX<TDatum>(
+	data: ReadonlyArray<TDatum>,
+	options: RuleOptions<TDatum> = {},
+): ChartMark {
+	return ruleMark("ruleX", data, options);
+}

package/src/core/marks/shared.ts

@@ -0,0 +1,134 @@
+import {
+	channelLabel,
+	isPlaceable,
+	numericValue,
+	readChannel,
+} from "#/core/channel.ts";
+import { categoryKey } from "#/core/scales/discrete.ts";
+import type {
+	ChartAccessor,
+	ChartChannel,
+	ChartMarkContext,
+	ChartPaint,
+	ChartPositionScale,
+	ChartValue,
+} from "#/core/types.ts";
+
+/** Options every mark takes. */
+export interface ChartMarkOptions<TDatum> {
+	/** Stable identity, so focus and legend state survive a data update. */
+	readonly id?: string;
+	/** The series' name when the mark has no color channel: legend, tooltip, table. */
+	readonly label?: string;
+	/** A field or function whose distinct values split the mark into coloured series. */
+	readonly color?: ChartAccessor<TDatum, ChartValue>;
+	/** `false` keeps the mark out of focus, tooltips and the data table. */
+	readonly tip?: boolean;
+	readonly opacity?: number;
+}
+
+export function markId(
+	id: string | undefined,
+	kind: string,
+	context: ChartMarkContext,
+): string {
+	return id ?? `${kind}-${context.markIndex}`;
+}
+
+/** A datum's series: its color value when there is a color channel, the mark otherwise. */
+export interface SeriesInfo {
+	readonly key: string;
+	readonly label: string | undefined;
+	readonly color: string;
+}
+
+export function seriesResolver<TDatum>(
+	colors: ReadonlyArray<ChartValue | undefined>,
+	options: ChartMarkOptions<TDatum> & { readonly fixedColor?: string },
+	id: string,
+	context: ChartMarkContext,
+): (index: number) => SeriesInfo {
+	const fallback =
+		options.fixedColor ?? context.paletteColor(context.markIndex);
+	const single: SeriesInfo = { key: id, label: options.label, color: fallback };
+	if (options.color === undefined) {
+		return () => single;
+	}
+	return (index) => {
+		const value = colors[index];
+		if (value === undefined) {
+			return single;
+		}
+		return {
+			key: categoryKey(value),
+			label: context.seriesLabel(value),
+			color: options.fixedColor ?? context.colorOf(value),
+		};
+	};
+}
+
+export function colorChannel<TDatum>(
+	data: ReadonlyArray<TDatum>,
+	options: ChartMarkOptions<TDatum>,
+): {
+	readonly values: ReadonlyArray<ChartValue | undefined>;
+	readonly channel: ChartChannel | undefined;
+} {
+	const values = readChannel(data, options.color);
+	return {
+		values,
+		channel:
+			options.color === undefined
+				? undefined
+				: {
+						values: values.filter(isPlaceable),
+						label: channelLabel(options.color),
+					},
+	};
+}
+
+/** Keeps only the defined paint keys, so a scene snapshot shows what was asked for. */
+export function paint<TPaint extends ChartPaint>(values: TPaint): TPaint {
+	return Object.fromEntries(
+		Object.entries(values).filter(([, value]) => value !== undefined),
+	) as TPaint;
+}
+
+/** Indices of `data` grouped by series, each group in data order. */
+export function groupBySeries(
+	count: number,
+	seriesOf: (index: number) => SeriesInfo,
+): ReadonlyMap<
+	string,
+	{ readonly series: SeriesInfo; readonly indices: number[] }
+> {
+	const groups = new Map<string, { series: SeriesInfo; indices: number[] }>();
+	for (let index = 0; index < count; index += 1) {
+		const series = seriesOf(index);
+		const group = groups.get(series.key);
+		if (group === undefined) {
+			groups.set(series.key, { series, indices: [index] });
+		} else {
+			group.indices.push(index);
+		}
+	}
+	return groups;
+}
+
+/**
+ * A raw channel value as the scale can place it, or `undefined` for a gap. A
+ * continuous scale reads numeric strings as numbers; a discrete one takes any
+ * category as is.
+ */
+export function valueOn(
+	scale: ChartPositionScale,
+	raw: unknown,
+): ChartValue | undefined {
+	if (scale.kind === "band" || scale.kind === "point") {
+		return isPlaceable(raw) ? raw : undefined;
+	}
+	if (raw instanceof Date) {
+		return Number.isNaN(raw.getTime()) ? undefined : raw;
+	}
+	return numericValue(raw);
+}

package/src/core/marks/stack.ts

@@ -0,0 +1,42 @@
+/**
+ * Stacking: each value sits on the running total of the values before it at
+ * the same position. Positives grow away from zero upwards and negatives
+ * downwards, separately, so a stack of mixed signs never overlaps itself.
+ */
+
+export interface StackSegment {
+	readonly low: number;
+	readonly high: number;
+	/** The outermost segment of its side of the stack: the one whose far end gets rounded. */
+	readonly outer: boolean;
+}
+
+export function stackSegments(
+	positions: ReadonlyArray<string | undefined>,
+	values: ReadonlyArray<number | undefined>,
+): ReadonlyArray<StackSegment | undefined> {
+	const above = new Map<string, number>();
+	const below = new Map<string, number>();
+	const lastAbove = new Map<string, number>();
+	const lastBelow = new Map<string, number>();
+	const segments: Array<
+		{ low: number; high: number; outer: boolean } | undefined
+	> = positions.map((position, index) => {
+		const value = values[index];
+		if (position === undefined || value === undefined) {
+			return undefined;
+		}
+		const totals = value >= 0 ? above : below;
+		const base = totals.get(position) ?? 0;
+		totals.set(position, base + value);
+		(value >= 0 ? lastAbove : lastBelow).set(position, index);
+		return { low: base, high: base + value, outer: false };
+	});
+	for (const index of [...lastAbove.values(), ...lastBelow.values()]) {
+		const segment = segments[index];
+		if (segment !== undefined) {
+			segment.outer = true;
+		}
+	}
+	return segments;
+}

package/src/core/marks/stats/difference.ts

@@ -0,0 +1,205 @@
+import {
+	channelLabel,
+	isPlaceable,
+	numericValue,
+	readChannel,
+} from "#/core/channel.ts";
+import { markId, paint, valueOn } from "#/core/marks/shared.ts";
+import { areaPath, type ChartXY, linePath } from "#/core/paths.ts";
+import type {
+	ChartAccessor,
+	ChartMark,
+	ChartPoint,
+	ChartValue,
+	SceneNode,
+} from "#/core/types.ts";
+
+export interface DifferenceOptions<TDatum> {
+	readonly id?: string;
+	readonly x: ChartAccessor<TDatum, ChartValue>;
+	/** The series read against the other: the fill says when it is above. */
+	readonly y1: ChartAccessor<TDatum, ChartValue>;
+	readonly y2: ChartAccessor<TDatum, ChartValue>;
+	/** Names of the two series, for the tooltip, the table and the legend. */
+	readonly labels?: readonly [string, string];
+	/** Fill where `y1` is above `y2`, and below. */
+	readonly positiveFill?: string;
+	readonly negativeFill?: string;
+	readonly fillOpacity?: number;
+}
+
+interface Sample {
+	readonly x: number;
+	readonly top: number;
+	readonly bottom: number;
+}
+
+/** Splits the band between two lines into runs of one sign, cut where they cross. */
+function signRuns(
+	samples: ReadonlyArray<Sample>,
+): Array<{ positive: boolean; samples: Sample[] }> {
+	const runs: Array<{ positive: boolean; samples: Sample[] }> = [];
+	for (const [index, sample] of samples.entries()) {
+		// Pixels: a smaller y is higher, so y1 above y2 means top < bottom.
+		const positive = sample.top <= sample.bottom;
+		const current = runs[runs.length - 1];
+		if (current === undefined) {
+			runs.push({ positive, samples: [sample] });
+			continue;
+		}
+		if (current.positive === positive) {
+			current.samples.push(sample);
+			continue;
+		}
+		const previous = samples[index - 1];
+		const before = previous.top - previous.bottom;
+		const after = sample.top - sample.bottom;
+		const share = before / (before - after);
+		const crossX = previous.x + (sample.x - previous.x) * share;
+		const crossY = previous.top + (sample.top - previous.top) * share;
+		const cross = { x: crossX, top: crossY, bottom: crossY };
+		current.samples.push(cross);
+		runs.push({ positive, samples: [cross, sample] });
+	}
+	return runs;
+}
+
+/**
+ * Two series and the band between them, filled by which one is ahead:
+ * revenue against costs, this year against last.
+ */
+export function differenceY<TDatum>(
+	data: ReadonlyArray<TDatum>,
+	options: DifferenceOptions<TDatum>,
+): ChartMark {
+	const xs = readChannel(data, options.x);
+	const first = readChannel(data, options.y1).map(numericValue);
+	const second = readChannel(data, options.y2).map(numericValue);
+	const [firstLabel, secondLabel] = options.labels ?? [
+		channelLabel(options.y1) ?? "y1",
+		channelLabel(options.y2) ?? "y2",
+	];
+	return {
+		id: options.id,
+		coordinate: "cartesian",
+		focusOrder: "x",
+		channels: {
+			x: { values: xs.filter(isPlaceable), label: channelLabel(options.x) },
+			y: {
+				values: [...first, ...second].filter(
+					(value): value is number => value !== undefined,
+				),
+			},
+		},
+		render(context) {
+			const id = markId(options.id, "differenceY", context);
+			const { x: xScale, y: yScale } = context.scales;
+			if (xScale === undefined || yScale === undefined) {
+				return { nodes: [] };
+			}
+			const positive = options.positiveFill ?? context.paletteColor(1);
+			const negative = options.negativeFill ?? context.paletteColor(0);
+			const samples: Sample[] = [];
+			const points: ChartPoint[] = [];
+			for (const [index, raw] of xs.entries()) {
+				const x = valueOn(xScale, raw);
+				const a = first[index];
+				const b = second[index];
+				if (x === undefined || a === undefined || b === undefined) continue;
+				const sample = {
+					x: xScale.center(x),
+					top: yScale.map(a),
+					bottom: yScale.map(b),
+				};
+				samples.push(sample);
+				for (const [series, value, pixel, label] of [
+					["y1", a, sample.top, firstLabel],
+					["y2", b, sample.bottom, secondLabel],
+				] as const) {
+					points.push({
+						key: `${id}:${series}:${index}`,
+						markId: id,
+						index,
+						datum: data[index],
+						x: sample.x,
+						y: pixel,
+						xValue: x,
+						yValue: value,
+						series: `${id}:${series}`,
+						seriesLabel: label,
+						color:
+							series === "y1" ? context.theme.foreground : context.theme.muted,
+						title: context.formatX(x),
+						value: context.formatY(value),
+					});
+				}
+			}
+			const nodes: SceneNode[] = signRuns(samples).map((run, index) => ({
+				kind: "path",
+				key: `${id}:band:${index}`,
+				role: "mark",
+				d: areaPath(
+					run.samples.map(
+						(sample): ChartXY => ({ x: sample.x, y: sample.top }),
+					),
+					run.samples.map(
+						(sample): ChartXY => ({ x: sample.x, y: sample.bottom }),
+					),
+				),
+				paint: paint({
+					fill: run.positive ? positive : negative,
+					fillOpacity: options.fillOpacity ?? 0.35,
+				}),
+			}));
+			nodes.push(
+				{
+					kind: "path",
+					key: `${id}:line:y1`,
+					series: `${id}:y1`,
+					role: "mark",
+					d: linePath(
+						samples.map((sample) => ({ x: sample.x, y: sample.top })),
+					),
+					paint: {
+						fill: "none",
+						stroke: context.theme.foreground,
+						strokeWidth: 1.5,
+					},
+				},
+				{
+					kind: "path",
+					key: `${id}:line:y2`,
+					series: `${id}:y2`,
+					role: "mark",
+					d: linePath(
+						samples.map((sample) => ({ x: sample.x, y: sample.bottom })),
+					),
+					paint: {
+						fill: "none",
+						stroke: context.theme.muted,
+						strokeWidth: 1.5,
+						strokeDasharray: "4 3",
+					},
+				},
+			);
+			return {
+				nodes,
+				points,
+				legend: [
+					{
+						key: `${id}:y1`,
+						label: firstLabel,
+						color: context.theme.foreground,
+						shape: "line",
+					},
+					{
+						key: `${id}:y2`,
+						label: secondLabel,
+						color: context.theme.muted,
+						shape: "dashed",
+					},
+				],
+			};
+		},
+	};
+}