@voila.dev/ui-chart 1.1.9

package/src/core/geometry.ts

@@ -0,0 +1,271 @@
+import { polarToCartesian } from "#/core/polar.ts";
+import type {
+	ChartCornerRadius,
+	ChartCurve,
+	ChartPoint,
+} from "#/core/types.ts";
+
+/**
+ * SVG path builders. Everything 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<ChartPoint>): 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<ChartPoint>): 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<ChartPoint>): 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<ChartPoint>): string {
+	return points
+		.slice(1)
+		.map((current) => `L${point(current.x, current.y)}`)
+		.join("");
+}
+
+const segmentBuilders: Record<
+	ChartCurve,
+	(points: ReadonlyArray<ChartPoint>) => 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<ChartPoint>,
+	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 `points` and a flat `baseline` y. Built from the same
+ * curve as `linePath`, so an area and its outline never disagree.
+ */
+export function areaPath(
+	points: ReadonlyArray<ChartPoint>,
+	baseline: number,
+	curve: ChartCurve = "linear",
+): string {
+	const top = linePath(points, curve);
+	if (top === "") {
+		return "";
+	}
+	const last = points[points.length - 1];
+	const first = points[0];
+	return `${top}L${point(last.x, baseline)}L${point(first.x, baseline)}Z`;
+}
+
+/** A closed polygon — the radar mark's outline. */
+export function polygonPath(points: ReadonlyArray<ChartPoint>): 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: ChartCornerRadius,
+	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?: ChartCornerRadius;
+}
+
+/**
+ * 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("");
+}
+
+export interface ArcOptions {
+	readonly cx: number;
+	readonly cy: number;
+	readonly innerRadius: number;
+	readonly outerRadius: number;
+	/** Degrees clockwise from twelve o'clock. */
+	readonly startAngle: number;
+	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("");
+}

package/src/core/polar.ts

@@ -0,0 +1,138 @@
+import type { ChartPoint } from "#/core/types.ts";
+
+/**
+ * Polar helpers. Angles are **degrees, clockwise, zero at twelve o'clock** —
+ * the way a pie chart is described out loud — rather than the mathematical
+ * convention, so nothing in the components has to apply a mental offset.
+ */
+
+const FULL_TURN = 360;
+const DEGREES_TO_RADIANS = Math.PI / 180;
+
+export function polarToCartesian(
+	cx: number,
+	cy: number,
+	radius: number,
+	angle: number,
+): ChartPoint {
+	const radians = angle * DEGREES_TO_RADIANS;
+	return {
+		x: cx + radius * Math.sin(radians),
+		y: cy - radius * Math.cos(radians),
+	};
+}
+
+export interface PolarFrame {
+	readonly cx: number;
+	readonly cy: number;
+	readonly radius: number;
+}
+
+/**
+ * Where a round chart sits inside the root: centred in the plotting area, and
+ * never wider than it. That is what makes the root's `margin` mean something
+ * on a round chart — reserve space at the bottom for a legend and the circle
+ * shrinks to leave it, rather than being drawn over it.
+ */
+export function polarFrame(options: {
+	readonly innerWidth: number;
+	readonly innerHeight: number;
+	/** Pixels kept clear inside the plotting area, around the outer edge. */
+	readonly inset?: number;
+}): PolarFrame {
+	const { innerWidth, innerHeight, inset = 0 } = options;
+	return {
+		cx: innerWidth / 2,
+		cy: innerHeight / 2,
+		radius: Math.max(0, Math.min(innerWidth, innerHeight) / 2 - inset),
+	};
+}
+
+export interface ChartSliceAngle {
+	readonly index: number;
+	readonly value: number;
+	/** Share of the total, in `[0, 1]`. Zero when every value is zero. */
+	readonly fraction: number;
+	readonly startAngle: number;
+	readonly endAngle: number;
+}
+
+export interface SliceAngleOptions {
+	readonly startAngle?: number;
+	readonly endAngle?: number;
+	/** Degrees of blank left between two neighbouring slices. */
+	readonly padAngle?: number;
+}
+
+/**
+ * Splits an angular span between values, proportionally. Negative values are
+ * treated as zero: a pie of signed numbers has no honest reading, and silently
+ * flipping a slice inside-out would be worse than showing nothing.
+ */
+export function sliceAngles(
+	values: ReadonlyArray<number>,
+	options: SliceAngleOptions = {},
+): ReadonlyArray<ChartSliceAngle> {
+	const { startAngle = 0, endAngle = FULL_TURN, padAngle = 0 } = options;
+	const positives = values.map((value) =>
+		Number.isFinite(value) && value > 0 ? value : 0,
+	);
+	const total = positives.reduce((sum, value) => sum + value, 0);
+	const span = endAngle - startAngle;
+	const available = Math.max(0, span - padAngle * positives.length);
+
+	let cursor = startAngle;
+	return positives.map((value, index) => {
+		const fraction = total === 0 ? 0 : value / total;
+		const sweep = available * fraction;
+		const slice: ChartSliceAngle = {
+			index,
+			value: values[index],
+			fraction,
+			startAngle: cursor + padAngle / 2,
+			endAngle: cursor + padAngle / 2 + sweep,
+		};
+		cursor += sweep + padAngle;
+		return slice;
+	});
+}
+
+/** The angle of the `index`-th of `count` axes, spread over a full turn. */
+export function axisAngle(
+	index: number,
+	count: number,
+	startAngle = 0,
+): number {
+	return count === 0 ? startAngle : startAngle + (FULL_TURN * index) / count;
+}
+
+/**
+ * The vertices of one radar ring: `count` equally spaced points at `radius`.
+ * Also used for the polar grid, whose rings are polygons rather than circles so
+ * they line up with the data they frame.
+ */
+export function ringPoints(
+	cx: number,
+	cy: number,
+	radius: number,
+	count: number,
+	startAngle = 0,
+): ReadonlyArray<ChartPoint> {
+	return Array.from({ length: count }, (_unused, index) =>
+		polarToCartesian(cx, cy, radius, axisAngle(index, count, startAngle)),
+	);
+}
+
+/**
+ * Radii for `count` evenly spaced grid rings inside `radius`, outermost first.
+ * The centre is never emitted — a ring of radius zero is a dot, not a ring.
+ */
+export function ringRadii(
+	radius: number,
+	count: number,
+): ReadonlyArray<number> {
+	return Array.from(
+		{ length: Math.max(0, count) },
+		(_unused, index) => (radius * (count - index)) / count,
+	);
+}

package/src/core/scales.ts

@@ -0,0 +1,167 @@
+import { niceTicks } from "#/core/ticks.ts";
+import type {
+	ChartDiscreteScale,
+	ChartInterval,
+	ChartLinearScale,
+} from "#/core/types.ts";
+
+/**
+ * The three scales a cartesian chart needs, written out rather than pulled in.
+ * Each one is a plain object of closures: no state, no mutation, safe to build
+ * during render and cheap enough to build on every render.
+ */
+
+const DEFAULT_BAND_PADDING_INNER = 0.2;
+const DEFAULT_BAND_PADDING_OUTER = 0.1;
+
+function clamp(value: number, low: number, high: number): number {
+	return Math.min(Math.max(value, low), high);
+}
+
+export interface LinearScaleOptions {
+	readonly domain: ChartInterval;
+	readonly range: ChartInterval;
+}
+
+/**
+ * Maps a numeric domain onto a pixel range, linearly. A zero-width domain
+ * collapses to the middle of the range, so a flat series draws a centred line
+ * instead of dividing by zero.
+ */
+export function linearScale(options: LinearScaleOptions): ChartLinearScale {
+	const [domainStart, domainEnd] = options.domain;
+	const [rangeStart, rangeEnd] = options.range;
+	const domainSpan = domainEnd - domainStart;
+	const rangeSpan = rangeEnd - rangeStart;
+
+	const scale = (value: number): number =>
+		domainSpan === 0
+			? rangeStart + rangeSpan / 2
+			: rangeStart + ((value - domainStart) / domainSpan) * rangeSpan;
+
+	const invert = (pixel: number): number =>
+		rangeSpan === 0
+			? domainStart
+			: domainStart + ((pixel - rangeStart) / rangeSpan) * domainSpan;
+
+	return {
+		kind: "linear",
+		domain: options.domain,
+		range: options.range,
+		bandwidth: 0,
+		scale,
+		invert,
+		ticks: (count) =>
+			niceTicks(
+				Math.min(domainStart, domainEnd),
+				Math.max(domainStart, domainEnd),
+				count,
+			),
+	};
+}
+
+export interface BandScaleOptions {
+	readonly domain: ReadonlyArray<string>;
+	readonly range: ChartInterval;
+	/** Share of a step left empty between two bands. 0 = touching bars. */
+	readonly paddingInner?: number;
+	/** Share of a step left empty before the first and after the last band. */
+	readonly paddingOuter?: number;
+}
+
+/**
+ * Maps categories onto equal slots of `bandwidth` pixels — the scale bars sit
+ * on. Categories are looked up by value, so duplicate category labels collapse
+ * onto the first slot (which is what a duplicated x value means anyway).
+ */
+export function bandScale(options: BandScaleOptions): ChartDiscreteScale {
+	const {
+		domain,
+		range,
+		paddingInner = DEFAULT_BAND_PADDING_INNER,
+		paddingOuter = DEFAULT_BAND_PADDING_OUTER,
+	} = options;
+	const [rangeStart, rangeEnd] = range;
+	const count = domain.length;
+	const step =
+		(rangeEnd - rangeStart) /
+		Math.max(1, count - paddingInner + paddingOuter * 2);
+	const bandwidth = step * (1 - paddingInner);
+	const origin = rangeStart + step * paddingOuter;
+	const indexByValue = new Map<string, number>();
+	for (const [index, value] of domain.entries()) {
+		if (!indexByValue.has(value)) {
+			indexByValue.set(value, index);
+		}
+	}
+
+	const scale = (value: string): number =>
+		origin + step * (indexByValue.get(value) ?? 0);
+
+	return {
+		kind: "band",
+		domain,
+		range,
+		bandwidth,
+		step,
+		scale,
+		center: (value) => scale(value) + bandwidth / 2,
+		invert: (pixel) =>
+			count === 0
+				? 0
+				: clamp(Math.floor((pixel - origin) / step), 0, count - 1),
+		ticks: () => domain,
+	};
+}
+
+export interface PointScaleOptions {
+	readonly domain: ReadonlyArray<string>;
+	readonly range: ChartInterval;
+	/** Share of a step left empty at each end. 0 pins the ends to the edges. */
+	readonly padding?: number;
+}
+
+/**
+ * Maps categories onto evenly spaced positions with no width — the scale lines
+ * and areas sit on, where the first and last points touch the plot edges.
+ */
+export function pointScale(options: PointScaleOptions): ChartDiscreteScale {
+	const { domain, range, padding = 0 } = options;
+	const [rangeStart, rangeEnd] = range;
+	const count = domain.length;
+	const step = (rangeEnd - rangeStart) / Math.max(1, count - 1 + padding * 2);
+	const origin = rangeStart + step * padding;
+	const indexByValue = new Map<string, number>();
+	for (const [index, value] of domain.entries()) {
+		if (!indexByValue.has(value)) {
+			indexByValue.set(value, index);
+		}
+	}
+
+	const scale = (value: string): number =>
+		count <= 1
+			? rangeStart + (rangeEnd - rangeStart) / 2
+			: origin + step * (indexByValue.get(value) ?? 0);
+
+	return {
+		kind: "point",
+		domain,
+		range,
+		bandwidth: 0,
+		step,
+		scale,
+		center: scale,
+		invert: (pixel) =>
+			count === 0
+				? 0
+				: clamp(Math.round((pixel - origin) / step), 0, count - 1),
+		ticks: () => domain,
+	};
+}
+
+/** Type guard so marks can branch on "is this axis continuous?". */
+export function isLinearScale(
+	scale: ChartLinearScale | ChartDiscreteScale,
+): scale is ChartLinearScale {
+	return scale.kind === "linear";
+}

package/src/core/series.ts

@@ -0,0 +1,70 @@
+import { readNumber } from "#/core/chart-model.ts";
+import type {
+	ChartDatum,
+	ChartDiscreteScale,
+	ChartLinearScale,
+	ChartOrientation,
+	ChartPoint,
+} from "#/core/types.ts";
+
+/**
+ * Point geometry shared by the line, area and scatter marks: one place that
+ * knows a category runs along x when the chart is upright and along y when it
+ * is on its side.
+ */
+
+export interface SeriesPointsOptions {
+	readonly data: ReadonlyArray<ChartDatum>;
+	readonly categories: ReadonlyArray<string>;
+	readonly categoryScale: ChartDiscreteScale;
+	readonly valueScale: ChartLinearScale;
+	readonly orientation: ChartOrientation;
+	readonly key: string;
+	/**
+	 * Value each point sits on top of, per datum — the running total under a
+	 * stacked series. Defaults to zero, i.e. straight off the baseline.
+	 */
+	readonly base?: ReadonlyArray<number>;
+}
+
+export function seriesPoints(
+	options: SeriesPointsOptions,
+): ReadonlyArray<ChartPoint> {
+	const {
+		data,
+		categories,
+		categoryScale,
+		valueScale,
+		orientation,
+		key,
+		base,
+	} = options;
+
+	return data.map((datum, index) => {
+		const along = categoryScale.center(categories[index] ?? String(index));
+		const value = readNumber(datum, key) + (base?.[index] ?? 0);
+		const across = valueScale.scale(value);
+		return orientation === "vertical"
+			? { x: along, y: across }
+			: { x: across, y: along };
+	});
+}
+
+/**
+ * Running totals under each series of a stack, in draw order. `stackTops[key]`
+ * is what the next series up should sit on.
+ */
+export function stackBases(
+	data: ReadonlyArray<ChartDatum>,
+	keys: ReadonlyArray<string>,
+): ReadonlyMap<string, ReadonlyArray<number>> {
+	const bases = new Map<string, ReadonlyArray<number>>();
+	const running = data.map(() => 0);
+	for (const key of keys) {
+		bases.set(key, [...running]);
+		for (const [index, datum] of data.entries()) {
+			running[index] += readNumber(datum, key);
+		}
+	}
+	return bases;
+}