@voila.dev/chart 4.0.0

package/src/core/motion/tween.ts

@@ -0,0 +1,131 @@
+import type { ChartPaint, ChartScene, SceneNode } from "#/core/types.ts";
+
+/**
+ * A scene part of the way from one scene to the next, keyed by node: what an
+ * animated update draws on each frame. It lives in the core so the SVG and
+ * Canvas renderers animate identically, and never feeds hit-testing or
+ * focus: those always read the scene being animated towards.
+ *
+ * A node present on both sides moves; a new one fades in; one that left is
+ * gone at once (fading out a bar the data no longer has would show a value
+ * that is not true any more). A path tweens point by point when both shapes
+ * share their commands, and swaps at the end when they do not.
+ */
+
+const NUMBER = /-?\d*\.?\d+(?:e[-+]?\d+)?/gi;
+
+function mix(from: number, to: number, t: number): number {
+	return from + (to - from) * t;
+}
+
+/** Two paths can tween when only their numbers differ. */
+function tweenPath(from: string, to: string, t: number): string {
+	const fromNumbers = from.match(NUMBER);
+	const toNumbers = to.match(NUMBER);
+	if (
+		fromNumbers === null ||
+		toNumbers === null ||
+		fromNumbers.length !== toNumbers.length ||
+		from.replace(NUMBER, "#") !== to.replace(NUMBER, "#")
+	) {
+		return t < 1 ? from : to;
+	}
+	let index = 0;
+	return to.replace(NUMBER, () => {
+		const value = mix(Number(fromNumbers[index]), Number(toNumbers[index]), t);
+		index += 1;
+		return String(Math.round(value * 100) / 100);
+	});
+}
+
+function fadeIn<TPaint extends ChartPaint>(paint: TPaint, t: number): TPaint {
+	return { ...paint, opacity: (paint.opacity ?? 1) * t };
+}
+
+function tweenNode(
+	from: SceneNode | undefined,
+	to: SceneNode,
+	t: number,
+): SceneNode {
+	if (from === undefined || from.kind !== to.kind) {
+		return to.kind === "group"
+			? {
+					...to,
+					children: to.children.map((child) => tweenNode(undefined, child, t)),
+				}
+			: { ...to, paint: fadeIn(to.paint, t) };
+	}
+	switch (to.kind) {
+		case "group": {
+			const before = new Map(
+				(from as typeof to).children.map((child) => [child.key, child]),
+			);
+			return {
+				...to,
+				children: to.children.map((child) =>
+					tweenNode(before.get(child.key), child, t),
+				),
+			};
+		}
+		case "rect": {
+			const previous = from as typeof to;
+			return {
+				...to,
+				x: mix(previous.x, to.x, t),
+				y: mix(previous.y, to.y, t),
+				width: mix(previous.width, to.width, t),
+				height: mix(previous.height, to.height, t),
+			};
+		}
+		case "circle": {
+			const previous = from as typeof to;
+			return {
+				...to,
+				cx: mix(previous.cx, to.cx, t),
+				cy: mix(previous.cy, to.cy, t),
+				r: mix(previous.r, to.r, t),
+			};
+		}
+		case "line": {
+			const previous = from as typeof to;
+			return {
+				...to,
+				x1: mix(previous.x1, to.x1, t),
+				y1: mix(previous.y1, to.y1, t),
+				x2: mix(previous.x2, to.x2, t),
+				y2: mix(previous.y2, to.y2, t),
+			};
+		}
+		case "text": {
+			const previous = from as typeof to;
+			return {
+				...to,
+				x: mix(previous.x, to.x, t),
+				y: mix(previous.y, to.y, t),
+			};
+		}
+		case "path":
+			return { ...to, d: tweenPath((from as typeof to).d, to.d, t) };
+	}
+}
+
+/** `to`, `t` of the way from `from` (0 is `from`, 1 is `to`). */
+export function tweenScene(
+	from: ChartScene,
+	to: ChartScene,
+	t: number,
+): ChartScene {
+	if (t >= 1) {
+		return to;
+	}
+	const before = new Map(from.nodes.map((node) => [node.key, node]));
+	return {
+		...to,
+		nodes: to.nodes.map((node) => tweenNode(before.get(node.key), node, t)),
+	};
+}
+
+/** Fast out, slow in: the motion settles rather than stops. */
+export function easeOutCubic(t: number): number {
+	return 1 - (1 - t) ** 3;
+}

package/src/core/nearest.ts

@@ -0,0 +1,223 @@
+import { categoryKey } from "#/core/scales/discrete.ts";
+import type {
+	ChartFocusOrder,
+	ChartHitShape,
+	ChartPoint,
+	ChartScene,
+	ChartValue,
+} from "#/core/types.ts";
+
+/**
+ * Focus and hit-testing, on the scene only, so SVG and Canvas behave the same.
+ * A stop is what one arrow-key press moves to: one point, or every point that
+ * shares a position (the column of a multi-series chart).
+ */
+export interface ChartFocusStop {
+	readonly key: string;
+	readonly points: ReadonlyArray<ChartPoint>;
+	/** Where the stop sits along its axis, in chart pixels. */
+	readonly at: number;
+}
+
+/** How far from a dot the pointer may be and still hover it, in pixels. */
+const POINT_REACH = 24;
+
+function positionOf(
+	point: ChartPoint,
+	order: ChartFocusOrder,
+): ChartValue | undefined {
+	return order === "y" ? point.yValue : point.xValue;
+}
+
+export function focusStops(scene: ChartScene): ReadonlyArray<ChartFocusStop> {
+	const order = scene.focusOrder;
+	if (order === "point") {
+		return scene.points.map((point) => ({
+			key: point.key,
+			points: [point],
+			at: point.x,
+		}));
+	}
+	const stops = new Map<
+		string,
+		{ key: string; points: ChartPoint[]; at: number }
+	>();
+	for (const point of scene.points) {
+		const position = positionOf(point, order);
+		// On a faceted chart a column is a column of one cell, never across cells.
+		const within = point.facet === undefined ? "" : `${point.facet}|`;
+		const key = `${within}${
+			position === undefined
+				? `px:${Math.round(order === "y" ? point.y : point.x)}`
+				: categoryKey(position)
+		}`;
+		const stop = stops.get(key);
+		if (stop === undefined) {
+			stops.set(key, {
+				key,
+				points: [point],
+				at: order === "y" ? point.y : point.x,
+			});
+		} else {
+			stop.points.push(point);
+		}
+	}
+	const cellOrder = new Map(
+		(scene.cells ?? []).map((cell, index) => [cell.key, index]),
+	);
+	const cellOf = (stop: { points: ChartPoint[] }) =>
+		cellOrder.get(stop.points[0].facet ?? "") ?? 0;
+	return [...stops.values()].sort(
+		(left, right) => cellOf(left) - cellOf(right) || left.at - right.at,
+	);
+}
+
+/** Degrees clockwise from twelve o'clock, in `[0, 360)`. */
+function bearing(dx: number, dy: number): number {
+	const degrees = (Math.atan2(dx, -dy) * 180) / Math.PI;
+	return degrees < 0 ? degrees + 360 : degrees;
+}
+
+export function contains(hit: ChartHitShape, x: number, y: number): boolean {
+	if (hit.kind === "rect") {
+		const { rect } = hit;
+		return (
+			x >= rect.x &&
+			x <= rect.x + rect.width &&
+			y >= rect.y &&
+			y <= rect.y + rect.height
+		);
+	}
+	const dx = x - hit.cx;
+	const dy = y - hit.cy;
+	const radius = Math.hypot(dx, dy);
+	if (radius < hit.innerRadius || radius > hit.outerRadius) {
+		return false;
+	}
+	const angle = bearing(dx, dy);
+	const start = ((hit.startAngle % 360) + 360) % 360;
+	const sweep = hit.endAngle - hit.startAngle;
+	const offset = (angle - start + 360) % 360;
+	return sweep >= 360 || offset <= sweep;
+}
+
+function hitArea(hit: ChartHitShape): number {
+	if (hit.kind === "rect") {
+		return hit.rect.width * hit.rect.height;
+	}
+	const sweep = Math.min(360, hit.endAngle - hit.startAngle) / 360;
+	return Math.PI * (hit.outerRadius ** 2 - hit.innerRadius ** 2) * sweep;
+}
+
+export interface ChartHit {
+	readonly stop: number;
+	readonly point: number;
+}
+
+function pickInStop(
+	stop: ChartFocusStop,
+	x: number,
+	y: number,
+	order: ChartFocusOrder,
+): number {
+	const inside = stop.points.findIndex(
+		(point) => point.hit !== undefined && contains(point.hit, x, y),
+	);
+	if (inside !== -1) {
+		return inside;
+	}
+	let best = 0;
+	let bestDistance = Number.POSITIVE_INFINITY;
+	for (const [index, point] of stop.points.entries()) {
+		const distance =
+			order === "y" ? Math.abs(point.x - x) : Math.abs(point.y - y);
+		if (distance < bestDistance) {
+			best = index;
+			bestDistance = distance;
+		}
+	}
+	return best;
+}
+
+/**
+ * The stop and point under the pointer. Along a position axis the nearest
+ * column wins wherever the pointer is in the plot, the way a reader scrubs a
+ * time series; a scatter, pie or map needs the pointer on or near the shape.
+ */
+export function findNearest(
+	scene: ChartScene,
+	stops: ReadonlyArray<ChartFocusStop>,
+	x: number,
+	y: number,
+): ChartHit | null {
+	if (stops.length === 0) {
+		return null;
+	}
+	const order = scene.focusOrder;
+	if (order === "point") {
+		// Shapes can overlap (a dot over a region, regions' bounding boxes):
+		// the smallest one under the pointer is the one meant.
+		let inside = -1;
+		let insideArea = Number.POSITIVE_INFINITY;
+		for (const [index, stop] of stops.entries()) {
+			const hit = stop.points[0].hit;
+			if (hit !== undefined && contains(hit, x, y)) {
+				const area = hitArea(hit);
+				if (area < insideArea) {
+					inside = index;
+					insideArea = area;
+				}
+			}
+		}
+		if (inside !== -1) {
+			return { stop: inside, point: 0 };
+		}
+		let best = -1;
+		let bestDistance = POINT_REACH;
+		for (const [index, stop] of stops.entries()) {
+			const point = stop.points[0];
+			if (point.hit?.kind === "arc") {
+				continue;
+			}
+			const distance = Math.hypot(point.x - x, point.y - y);
+			if (distance < bestDistance) {
+				best = index;
+				bestDistance = distance;
+			}
+		}
+		return best === -1 ? null : { stop: best, point: 0 };
+	}
+	const cell = scene.cells?.find(
+		(candidate) =>
+			x >= candidate.plot.x &&
+			x <= candidate.plot.x + candidate.plot.width &&
+			y >= candidate.plot.y &&
+			y <= candidate.plot.y + candidate.plot.height,
+	);
+	if (scene.cells !== undefined && cell === undefined) {
+		return null;
+	}
+	const plot = cell?.plot ?? scene.plot;
+	if (
+		x < plot.x ||
+		x > plot.x + plot.width ||
+		y < plot.y ||
+		y > plot.y + plot.height
+	) {
+		return null;
+	}
+	const along = order === "y" ? y : x;
+	let best = 0;
+	let bestDistance = Number.POSITIVE_INFINITY;
+	for (const [index, stop] of stops.entries()) {
+		if (cell !== undefined && stop.points[0].facet !== cell.key) {
+			continue;
+		}
+		const distance = Math.abs(stop.at - along);
+		if (distance < bestDistance) {
+			best = index;
+			bestDistance = distance;
+		}
+	}
+	return { stop: best, point: pickInStop(stops[best], x, y, order) };
+}

package/src/core/paths.ts

@@ -0,0 +1,323 @@
+import type { ChartCorners, ChartCurve } from "#/core/types.ts";
+
+/** A point in chart pixels. */
+export interface ChartXY {
+	readonly x: number;
+	readonly y: number;
+}
+
+/**
+ * Path builders. Everything is SVG path data, which both renderers read: SVG
+ * sets it as `d`, Canvas hands it to `Path2D`. Everything It is rounded to `PATH_PRECISION` decimals so the
+ * emitted `d` attributes stay short, stable across runs and pleasant to assert
+ * on in tests.
+ */
+
+const PATH_PRECISION = 2;
+/** Fritsch-Carlson clamps the tangent when the slope ratio exceeds this. */
+const MONOTONE_SLOPE_LIMIT = 9;
+
+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)}`;
+}
+
+/**
+ * Per-point tangents for a monotone cubic spline (Fritsch-Carlson): the curve
+ * bends through the data without the overshoot a plain cubic gives you, so a
+ * series that never goes negative never dips below the axis.
+ */
+function monotoneTangents(points: ReadonlyArray<ChartXY>): number[] {
+	const count = points.length;
+	const secants: number[] = [];
+	for (let index = 0; index < count - 1; index += 1) {
+		const run = points[index + 1].x - points[index].x;
+		secants.push(run === 0 ? 0 : (points[index + 1].y - points[index].y) / run);
+	}
+
+	const tangents: number[] = [secants[0] ?? 0];
+	for (let index = 1; index < count - 1; index += 1) {
+		tangents.push((secants[index - 1] + secants[index]) / 2);
+	}
+	tangents.push(secants[count - 2] ?? 0);
+
+	for (let index = 0; index < secants.length; index += 1) {
+		const secant = secants[index];
+		if (secant === 0) {
+			tangents[index] = 0;
+			tangents[index + 1] = 0;
+			continue;
+		}
+		const before = tangents[index] / secant;
+		const after = tangents[index + 1] / secant;
+		const magnitude = before * before + after * after;
+		if (magnitude > MONOTONE_SLOPE_LIMIT) {
+			const scale = 3 / Math.sqrt(magnitude);
+			tangents[index] = scale * before * secant;
+			tangents[index + 1] = scale * after * secant;
+		}
+	}
+	return tangents;
+}
+
+function monotoneSegments(points: ReadonlyArray<ChartXY>): string {
+	const tangents = monotoneTangents(points);
+	const segments: string[] = [];
+	for (let index = 0; index < points.length - 1; index += 1) {
+		const from = points[index];
+		const to = points[index + 1];
+		const third = (to.x - from.x) / 3;
+		segments.push(
+			`C${point(from.x + third, from.y + tangents[index] * third)} ${point(
+				to.x - third,
+				to.y - tangents[index + 1] * third,
+			)} ${point(to.x, to.y)}`,
+		);
+	}
+	return segments.join("");
+}
+
+/** Midpoint step: hold the value, jump halfway between the two categories. */
+function stepSegments(points: ReadonlyArray<ChartXY>): string {
+	const segments: string[] = [];
+	for (let index = 0; index < points.length - 1; index += 1) {
+		const from = points[index];
+		const to = points[index + 1];
+		const middle = (from.x + to.x) / 2;
+		segments.push(
+			`L${point(middle, from.y)}L${point(middle, to.y)}L${point(to.x, to.y)}`,
+		);
+	}
+	return segments.join("");
+}
+
+function linearSegments(points: ReadonlyArray<ChartXY>): string {
+	return points
+		.slice(1)
+		.map((current) => `L${point(current.x, current.y)}`)
+		.join("");
+}
+
+const segmentBuilders: Record<
+	ChartCurve,
+	(points: ReadonlyArray<ChartXY>) => string
+> = {
+	linear: linearSegments,
+	monotone: monotoneSegments,
+	step: stepSegments,
+};
+
+/**
+ * An open path through `points`. Returns `""` for fewer than two points, which
+ * renders as nothing rather than as a stray dot.
+ */
+export function linePath(
+	points: ReadonlyArray<ChartXY>,
+	curve: ChartCurve = "linear",
+): string {
+	if (points.length < 2) {
+		return "";
+	}
+	return `M${point(points[0].x, points[0].y)}${segmentBuilders[curve](points)}`;
+}
+
+/**
+ * A closed band between a top edge and a bottom edge, both drawn with the same
+ * curve, so an area and its outline never disagree. The bottom edge runs under
+ * the same x positions as the top: a flat baseline, or the series below it in
+ * a stack.
+ */
+export function areaPath(
+	top: ReadonlyArray<ChartXY>,
+	bottom: ReadonlyArray<ChartXY>,
+	curve: ChartCurve = "linear",
+): string {
+	const upper = linePath(top, curve);
+	if (upper === "" || bottom.length === 0) {
+		return "";
+	}
+	const lower = [...bottom].reverse();
+	return `${upper}L${point(lower[0].x, lower[0].y)}${segmentBuilders[curve](lower)}Z`;
+}
+
+/** A closed polygon — the radar mark's outline. */
+export function polygonPath(points: ReadonlyArray<ChartXY>): string {
+	if (points.length === 0) {
+		return "";
+	}
+	const [head, ...rest] = points;
+	const tail = rest
+		.map((current) => `L${point(current.x, current.y)}`)
+		.join("");
+	return `M${point(head.x, head.y)}${tail}Z`;
+}
+
+function cornerRadii(
+	radius: number | ChartCorners,
+	width: number,
+	height: number,
+): readonly [number, number, number, number] {
+	const raw: readonly [number, number, number, number] =
+		typeof radius === "number" ? [radius, radius, radius, radius] : radius;
+	const limit = Math.min(Math.abs(width), Math.abs(height)) / 2;
+	return [
+		Math.max(0, Math.min(raw[0], limit)),
+		Math.max(0, Math.min(raw[1], limit)),
+		Math.max(0, Math.min(raw[2], limit)),
+		Math.max(0, Math.min(raw[3], limit)),
+	];
+}
+
+export interface RoundedBarOptions {
+	readonly x: number;
+	readonly y: number;
+	readonly width: number;
+	readonly height: number;
+	/** One radius, or `[topLeft, topRight, bottomRight, bottomLeft]`. */
+	readonly radius?: number | ChartCorners;
+}
+
+/**
+ * A rectangle with independently rounded corners — stacked bars round only the
+ * outer end of the stack, so the inner joins stay square.
+ */
+export function roundedBarPath(options: RoundedBarOptions): string {
+	const { x, y, width, height, radius = 0 } = options;
+	if (width <= 0 || height <= 0) {
+		return "";
+	}
+	const [topLeft, topRight, bottomRight, bottomLeft] = cornerRadii(
+		radius,
+		width,
+		height,
+	);
+	const right = x + width;
+	const bottom = y + height;
+	return [
+		`M${point(x + topLeft, y)}`,
+		`H${round(right - topRight)}`,
+		topRight > 0
+			? `A${round(topRight)},${round(topRight)} 0 0 1 ${point(right, y + topRight)}`
+			: "",
+		`V${round(bottom - bottomRight)}`,
+		bottomRight > 0
+			? `A${round(bottomRight)},${round(bottomRight)} 0 0 1 ${point(right - bottomRight, bottom)}`
+			: "",
+		`H${round(x + bottomLeft)}`,
+		bottomLeft > 0
+			? `A${round(bottomLeft)},${round(bottomLeft)} 0 0 1 ${point(x, bottom - bottomLeft)}`
+			: "",
+		`V${round(y + topLeft)}`,
+		topLeft > 0
+			? `A${round(topLeft)},${round(topLeft)} 0 0 1 ${point(x + topLeft, y)}`
+			: "",
+		"Z",
+	].join("");
+}
+
+const DEGREES_TO_RADIANS = Math.PI / 180;
+
+/**
+ * Angles are degrees, clockwise, zero at twelve o'clock: the way a pie chart
+ * is described out loud.
+ */
+export function polarToCartesian(
+	cx: number,
+	cy: number,
+	radius: number,
+	angle: number,
+): ChartXY {
+	const radians = angle * DEGREES_TO_RADIANS;
+	return {
+		x: cx + radius * Math.sin(radians),
+		y: cy - radius * Math.cos(radians),
+	};
+}
+
+export interface ArcOptions {
+	/** Centre of the circle the arc is cut from, in plot coordinates. */
+	readonly cx: number;
+	/** Centre of the circle the arc is cut from, in plot coordinates. */
+	readonly cy: number;
+	/** Inner edge. `0` makes the arc a pie wedge rather than a donut segment. */
+	readonly innerRadius: number;
+	/** Outer edge, in pixels from the centre. */
+	readonly outerRadius: number;
+	/** Degrees clockwise from twelve o'clock. */
+	readonly startAngle: number;
+	/** Degrees clockwise from twelve o'clock. A 360-degree sweep draws a full ring. */
+	readonly endAngle: number;
+}
+
+/**
+ * A pie wedge (`innerRadius` 0) or a donut segment. A sweep of 360 degrees or
+ * more is drawn as two half arcs, because a single arc back to its own start
+ * point renders as nothing at all.
+ */
+export function arcPath(options: ArcOptions): string {
+	const { cx, cy, innerRadius, outerRadius, startAngle, endAngle } = options;
+	const sweep = endAngle - startAngle;
+	if (sweep <= 0 || outerRadius <= 0) {
+		return "";
+	}
+	if (sweep >= 360) {
+		const half = startAngle + 180;
+		return `${arcPath({ ...options, endAngle: half })}${arcPath({
+			...options,
+			startAngle: half,
+			endAngle: startAngle + 359.99,
+		})}`;
+	}
+
+	const largeArc = sweep > 180 ? 1 : 0;
+	const outerStart = polarToCartesian(cx, cy, outerRadius, startAngle);
+	const outerEnd = polarToCartesian(cx, cy, outerRadius, endAngle);
+
+	if (innerRadius <= 0) {
+		return [
+			`M${point(cx, cy)}`,
+			`L${point(outerStart.x, outerStart.y)}`,
+			`A${round(outerRadius)},${round(outerRadius)} 0 ${largeArc} 1 ${point(outerEnd.x, outerEnd.y)}`,
+			"Z",
+		].join("");
+	}
+
+	const innerEnd = polarToCartesian(cx, cy, innerRadius, endAngle);
+	const innerStart = polarToCartesian(cx, cy, innerRadius, startAngle);
+	return [
+		`M${point(outerStart.x, outerStart.y)}`,
+		`A${round(outerRadius)},${round(outerRadius)} 0 ${largeArc} 1 ${point(outerEnd.x, outerEnd.y)}`,
+		`L${point(innerEnd.x, innerEnd.y)}`,
+		`A${round(innerRadius)},${round(innerRadius)} 0 ${largeArc} 0 ${point(innerStart.x, innerStart.y)}`,
+		"Z",
+	].join("");
+}
+
+/**
+ * Path data for GeoJSON polygon rings already in chart pixels (what
+ * d3-contour returns): every ring closed, holes drawn with the even-odd rule
+ * the renderers default to.
+ */
+export function multiPolygonPath(
+	polygons: ReadonlyArray<
+		ReadonlyArray<
+			ReadonlyArray<readonly [number, number] | ReadonlyArray<number>>
+		>
+	>,
+	offsetX = 0,
+	offsetY = 0,
+): string {
+	return polygons
+		.flatMap((rings) =>
+			rings.map((ring) =>
+				ring.length === 0
+					? ""
+					: `M${ring.map(([x, y]) => point(x + offsetX, y + offsetY)).join("L")}Z`,
+			),
+		)
+		.join("");
+}