@delacour/react-native-charts 0.1.0-alpha.20260925053522

package/src/core/animation/resample-points.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+import type { ChartPoint } from "../chart.types";
+import { matchPointCounts, resamplePoints } from "./resample-points";
+
+const at = (x: number, y: number | null): ChartPoint => ({ x, y, xValue: x, yValue: y });
+
+describe("resamplePoints", () => {
+	test("keeps both ends and interpolates between", () => {
+		const resampled = resamplePoints([at(0, 0), at(10, 10)], 3);
+		expect(resampled).toHaveLength(3);
+		expect(resampled[0]).toEqual(at(0, 0));
+		expect(resampled[1]).toEqual(at(5, 5));
+		expect(resampled[2]).toEqual(at(10, 10));
+	});
+
+	test("keeps a gap a gap rather than averaging across it", () => {
+		expect(resamplePoints([at(0, 0), at(10, null)], 3)[1]?.y).toBeNull();
+	});
+
+	test("degenerates safely", () => {
+		expect(resamplePoints([], 4)).toEqual([]);
+		expect(resamplePoints([at(1, 1)], 3)).toHaveLength(3);
+		expect(resamplePoints([at(1, 1), at(2, 2)], 0)).toEqual([]);
+		expect(resamplePoints([at(1, 1), at(2, 2)], 1)).toHaveLength(1);
+	});
+});
+
+describe("matchPointCounts", () => {
+	const previous = [at(0, 1), at(10, 2), at(20, 3)];
+
+	test("always returns two arrays of equal length", () => {
+		const next = [at(0, 5), at(10, 6), at(20, 7), at(30, 8), at(40, 9)];
+		for (const strategy of ["none", "pad-end", "pad-start", "resample"] as const) {
+			const [a, b] = matchPointCounts(previous, next, strategy);
+			expect(a).toHaveLength(b.length);
+		}
+	});
+
+	test("passes equal-length series through untouched", () => {
+		const next = [at(0, 5), at(10, 6), at(20, 7)];
+		const [a, b] = matchPointCounts(previous, next, "none");
+		expect(a).toBe(previous);
+		expect(b).toBe(next);
+	});
+
+	test("grows the tail out of where the line stopped", () => {
+		const next = [at(0, 1), at(10, 2), at(20, 3), at(30, 4), at(40, 5)];
+		const [a] = matchPointCounts(previous, next, "pad-end");
+		expect(a).toHaveLength(5);
+		expect(a[3]).toEqual(at(20, 3));
+		expect(a[4]).toEqual(at(20, 3));
+	});
+
+	test("collapses the departing head into the first survivor", () => {
+		const next = [at(20, 3)];
+		const [, b] = matchPointCounts(previous, next, "pad-start");
+		expect(b).toHaveLength(3);
+		expect(b[0]).toEqual(at(20, 3));
+		expect(b[2]).toEqual(at(20, 3));
+	});
+
+	test("resamples an unrelated series to the longer length", () => {
+		const next = [at(100, 9), at(200, 9), at(300, 9), at(400, 9), at(500, 9)];
+		const [a, b] = matchPointCounts(previous, next, "resample");
+		expect(a).toHaveLength(5);
+		expect(b).toHaveLength(5);
+	});
+});

package/src/core/animation/resample-points.ts

@@ -0,0 +1,64 @@
+import type { ChartPoint } from "../chart.types";
+import type { MorphStrategy } from "./morph-strategy";
+
+/** One point between two, at fraction `t`. A gap at either end stays a gap. */
+function lerpPoint(from: ChartPoint, to: ChartPoint, t: number): ChartPoint {
+	const bothPlotted = from.y !== null && to.y !== null;
+	return {
+		x: from.x + (to.x - from.x) * t,
+		y: bothPlotted ? (from.y as number) + ((to.y as number) - (from.y as number)) * t : null,
+		xValue: from.xValue + (to.xValue - from.xValue) * t,
+		yValue: from.yValue !== null && to.yValue !== null ? from.yValue + (to.yValue - from.yValue) * t : null,
+	};
+}
+
+/** `points` re-spread over exactly `length` places, evenly by index. */
+export function resamplePoints(points: readonly ChartPoint[], length: number): readonly ChartPoint[] {
+	if (length <= 0 || points.length === 0) return [];
+	if (points.length === 1 || length === 1) return new Array(length).fill(points[0] as ChartPoint);
+
+	const last = points.length - 1;
+	return Array.from({ length }, (_, index) => {
+		const source = (index / (length - 1)) * last;
+		const lower = Math.floor(source);
+		const upper = Math.min(last, lower + 1);
+		return lerpPoint(points[lower] as ChartPoint, points[upper] as ChartPoint, source - lower);
+	});
+}
+
+/** `points` grown to `length` by repeating an end. */
+function padPoints(points: readonly ChartPoint[], length: number, end: "start" | "end"): readonly ChartPoint[] {
+	if (points.length >= length || points.length === 0) return points;
+	const filler = new Array(length - points.length).fill(
+		end === "end" ? (points[points.length - 1] as ChartPoint) : (points[0] as ChartPoint)
+	);
+	return end === "end" ? [...points, ...filler] : [...filler, ...points];
+}
+
+/**
+ * Two series at one length, ready to build two interpolatable paths.
+ *
+ * Matching happens here, in data space, and not on the finished paths. That is
+ * the only place it is geometrically meaningful, and it is why
+ * `useAnimatedPath` never has to fall back to snapping: two point arrays of
+ * equal length through the same curve produce the same sequence of path verbs,
+ * which is exactly what Skia's interpolation requires.
+ */
+export function matchPointCounts(
+	previous: readonly ChartPoint[],
+	next: readonly ChartPoint[],
+	strategy: MorphStrategy
+): readonly [readonly ChartPoint[], readonly ChartPoint[]] {
+	if (previous.length === next.length) return [previous, next];
+
+	const length = Math.max(previous.length, next.length);
+	switch (strategy) {
+		case "pad-end":
+			return [padPoints(previous, length, "end"), padPoints(next, length, "end")];
+		case "pad-start":
+			return [padPoints(previous, length, "start"), padPoints(next, length, "start")];
+		case "none":
+		case "resample":
+			return [resamplePoints(previous, length), resamplePoints(next, length)];
+	}
+}

package/src/core/chart.types.ts

@@ -0,0 +1,62 @@
+/**
+ * Which axis the categories run along.
+ *
+ * `vertical` is the ordinary chart: categories along x, values up y.
+ * `horizontal` swaps the roles so bars grow rightward from a category axis on
+ * the left. It is decided once, at the root, because every mark, axis and the
+ * scrub have to agree on it.
+ */
+export type ChartOrientation = "vertical" | "horizontal";
+
+/**
+ * One plotted datum, in both coordinate systems at once.
+ *
+ * Marks need the canvas coordinates; a tooltip, a label and the scrub state
+ * need the domain values. Carrying both on one object is what stops a caller
+ * having to re-invert a position to find out what it meant.
+ */
+export type ChartPoint = {
+	/** Canvas x, in points. On a horizontal chart this is the value's position, `NaN` for a gap. */
+	readonly x: number;
+	/** Canvas y, in points. `null` marks a gap — the series has no value here. On a horizontal chart, the category's position. */
+	readonly y: number | null;
+	/** The datum's category in domain units — x on a vertical chart. Epoch milliseconds on a time scale. */
+	readonly xValue: number;
+	/** The datum's value in domain units — y on a vertical chart. `null` for a gap. */
+	readonly yValue: number | null;
+};
+
+/**
+ * One datum of a stacked series: a point with the edge it stands on.
+ *
+ * `y` and `yValue` are the segment's top — the running total including this
+ * series — so a `ChartSegment` reads as a `ChartPoint` wherever a mark wants
+ * only the upper edge. `y0` is where the series below it ended. Both are
+ * `null` for a gap.
+ */
+export type ChartSegment = ChartPoint & {
+	/**
+	 * Canvas position of the segment's base **along the value axis** — a y on
+	 * a vertical chart, an x on a horizontal one. Named for the vertical case,
+	 * like `yValue`; the pair `y`/`y0` is what a bar draws between either way.
+	 */
+	readonly y0: number | null;
+	/** The base in domain units. */
+	readonly y0Value: number | null;
+};
+
+/** The plot rect: the canvas minus the axis gutters and the padding. */
+export type ChartBounds = {
+	readonly left: number;
+	readonly right: number;
+	readonly top: number;
+	readonly bottom: number;
+};
+
+export type ChartSize = {
+	readonly width: number;
+	readonly height: number;
+};
+
+/** A row of the caller's data. Fields are read by key, never by position. */
+export type ChartRow = Record<string, unknown>;

package/src/core/curve/build-area.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from "bun:test";
+import type { ChartPoint } from "../chart.types";
+import { buildAreaPath } from "./build-area";
+
+const at = (x: number, y: number | null): ChartPoint => ({ x, y, xValue: x, yValue: y });
+
+describe("buildAreaPath", () => {
+	test("closes the fill against the baseline", () => {
+		expect(buildAreaPath([at(0, 0), at(10, 10)], { baseline: 100 })).toBe("M0,0L10,10L10,100L0,100Z");
+	});
+
+	test("returns an empty string for no points", () => {
+		expect(buildAreaPath([], { baseline: 100 })).toBe("");
+	});
+
+	test("follows a per-point lower edge when given one", () => {
+		expect(buildAreaPath([at(0, 0), at(10, 10)], { baseline: 100, lower: [80, 90] })).toBe("M0,0L10,10L10,90L0,80Z");
+	});
+
+	test("falls back to the baseline where the lower edge has a gap", () => {
+		expect(buildAreaPath([at(0, 0), at(10, 10)], { baseline: 100, lower: [80, null] })).toBe("M0,0L10,10L10,100L0,80Z");
+	});
+
+	test("gives the lower edge the same interpolator as the upper", () => {
+		// Closing a monotone area by hand leaves a curved top on a straight
+		// bottom, and the two disagree visibly wherever the baseline is not flat.
+		const path = buildAreaPath([at(0, 0), at(10, 10), at(20, 4)], {
+			baseline: 100,
+			lower: [90, 70, 95],
+			curve: "monotone",
+		});
+		expect((path.match(/C/g) ?? []).length).toBeGreaterThanOrEqual(4);
+	});
+
+	test("breaks at a gap by default", () => {
+		const path = buildAreaPath([at(0, 0), at(10, null), at(20, 5)], { baseline: 100 });
+		expect((path.match(/M/g) ?? []).length).toBeGreaterThan(1);
+	});
+
+	test("closes against a baseline x when horizontal", () => {
+		// Category on y, value on x: the lower edge is a vertical line at x = baseline.
+		const points = [
+			{ x: 30, y: 0, xValue: 0, yValue: 30 },
+			{ x: 50, y: 10, xValue: 1, yValue: 50 },
+		];
+		expect(buildAreaPath(points, { baseline: 0, orientation: "horizontal" })).toBe("M30,0L50,10L0,10L0,0Z");
+	});
+});

package/src/core/curve/build-area.ts

@@ -0,0 +1,58 @@
+import { area } from "d3-shape";
+import type { ChartOrientation, ChartPoint } from "../chart.types";
+import { isDrawable } from "./build-line";
+import { CURVES, type CurveType } from "./curves";
+
+export type AreaPathOptions = {
+	readonly curve?: CurveType;
+	readonly connectMissingData?: boolean;
+	/**
+	 * Canvas y the fill closes against — usually the plot rect's bottom, or the
+	 * position of zero when the series crosses it.
+	 */
+	readonly baseline: number;
+	/** Per-point lower edge, for a band rather than a fill to a baseline. */
+	readonly lower?: readonly (number | null)[];
+	/** Whether the fill closes down to a y (the default) or across to an x. */
+	readonly orientation?: ChartOrientation;
+};
+
+/**
+ * An SVG path string for the region between `points` and a baseline.
+ *
+ * Built with d3's `area` rather than by appending a closing edge to the line
+ * path, so the lower edge follows the same interpolator as the upper one. A
+ * hand-closed monotone area has a curved top and a straight bottom, and the
+ * two disagree visibly wherever the baseline is not flat.
+ */
+export function buildAreaPath(points: readonly ChartPoint[], options: AreaPathOptions): string {
+	if (points.length === 0) return "";
+	const curve = CURVES[options.curve ?? "linear"];
+	const lower = options.lower;
+
+	const edge = (index: number): number => {
+		if (!lower) return options.baseline;
+		const bound = lower[index];
+		return bound === null || bound === undefined || !Number.isFinite(bound) ? options.baseline : bound;
+	};
+
+	const generator =
+		options.orientation === "horizontal"
+			? area<ChartPoint>()
+					.y((point) => point.y ?? 0)
+					.x1((point) => point.x)
+					.x0((_point, index) => edge(index))
+					.curve(curve)
+			: area<ChartPoint>()
+					.x((point) => point.x)
+					.y1((point) => point.y ?? 0)
+					.y0((_point, index) => edge(index))
+					.curve(curve);
+
+	if (options.connectMissingData) {
+		const drawable = points.filter(isDrawable);
+		return drawable.length === 0 ? "" : (generator(drawable) ?? "");
+	}
+
+	return generator.defined(isDrawable)(points) ?? "";
+}

package/src/core/curve/build-line.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import type { ChartPoint } from "../chart.types";
+import { buildLinePath, isDrawable } from "./build-line";
+import { CURVE_TYPES } from "./curves";
+
+const at = (x: number, y: number | null): ChartPoint => ({ x, y, xValue: x, yValue: y });
+
+/** The command letters of a path, which is what `isInterpolatable` compares. */
+function commands(path: string): string {
+	return (path.match(/[A-Za-z]/g) ?? []).join("");
+}
+
+describe("buildLinePath", () => {
+	test("returns an empty string for no points", () => {
+		expect(buildLinePath([])).toBe("");
+	});
+
+	test("emits a move then lines for a linear curve", () => {
+		expect(buildLinePath([at(0, 0), at(10, 10)])).toBe("M0,0L10,10");
+	});
+
+	test("emits cubics for monotone", () => {
+		expect(commands(buildLinePath([at(0, 0), at(10, 10), at(20, 5)], { curve: "monotone" }))).toBe("MCC");
+	});
+
+	test("breaks the line at a gap rather than drawing through it", () => {
+		// Two subpaths, two moves. A line drawn across missing data asserts a
+		// trend nobody measured.
+		expect(commands(buildLinePath([at(0, 0), at(10, null), at(20, 5)]))).toContain("MZM");
+	});
+
+	test("draws through a gap when asked", () => {
+		expect(buildLinePath([at(0, 0), at(10, null), at(20, 5)], { connectMissingData: true })).toBe("M0,0L20,5");
+	});
+
+	test("treats a non-finite coordinate as a gap", () => {
+		expect(buildLinePath([at(0, 0), at(10, Number.NaN), at(20, 5)], { connectMissingData: true })).toBe("M0,0L20,5");
+	});
+
+	test("returns an empty string when every point is a gap", () => {
+		expect(buildLinePath([at(0, null), at(10, null)], { connectMissingData: true })).toBe("");
+	});
+
+	test("produces the same command sequence for equal point counts on every curve", () => {
+		// This is the animation invariant. Skia can only interpolate two paths
+		// whose verbs match, so a data change that keeps the point count must
+		// keep the command sequence — otherwise `useAnimatedPath` snaps instead
+		// of morphing and the chart jumps.
+		const before = [at(0, 5), at(10, 8), at(20, 3), at(30, 9)];
+		const after = [at(0, 2), at(10, 1), at(20, 7), at(30, 4)];
+		for (const curve of CURVE_TYPES) {
+			expect(commands(buildLinePath(after, { curve }))).toBe(commands(buildLinePath(before, { curve })));
+		}
+	});
+});
+
+describe("isDrawable", () => {
+	test("rejects gaps and non-finite coordinates", () => {
+		expect(isDrawable(at(0, 1))).toBe(true);
+		expect(isDrawable(at(0, null))).toBe(false);
+		expect(isDrawable(at(0, Number.NaN))).toBe(false);
+		expect(isDrawable(at(Number.POSITIVE_INFINITY, 1))).toBe(false);
+	});
+});

package/src/core/curve/build-line.ts

@@ -0,0 +1,53 @@
+import { line } from "d3-shape";
+import type { ChartPoint } from "../chart.types";
+import { CURVES, type CurveType } from "./curves";
+
+export type LinePathOptions = {
+	readonly curve?: CurveType;
+	/**
+	 * Draw straight through a gap instead of breaking the line.
+	 *
+	 * The default breaks it, because a line drawn across missing data asserts a
+	 * trend that was never measured.
+	 */
+	readonly connectMissingData?: boolean;
+};
+
+/** Whether a point can be drawn — both coordinates finite, and not a gap. */
+export function isDrawable(point: ChartPoint): boolean {
+	return point.y !== null && Number.isFinite(point.y) && Number.isFinite(point.x);
+}
+
+/**
+ * An SVG path string through `points`.
+ *
+ * A string rather than a Skia path because this module is pure — Skia's
+ * builder cannot be imported here without taking the whole test suite down
+ * (see the package AGENTS.md). `src/skia/build-path.ts` parses it.
+ *
+ * Gaps come out as separate subpaths via d3's `.defined()`, so a broken series
+ * is one path object with several `M` commands rather than several paths.
+ */
+export function buildLinePath(points: readonly ChartPoint[], options: LinePathOptions = {}): string {
+	if (points.length === 0) return "";
+	const curve = CURVES[options.curve ?? "linear"];
+
+	if (options.connectMissingData) {
+		const drawable = points.filter(isDrawable);
+		if (drawable.length === 0) return "";
+		return (
+			line<ChartPoint>()
+				.x((point) => point.x)
+				.y((point) => point.y as number)
+				.curve(curve)(drawable) ?? ""
+		);
+	}
+
+	return (
+		line<ChartPoint>()
+			.x((point) => point.x)
+			.y((point) => point.y ?? 0)
+			.defined(isDrawable)
+			.curve(curve)(points) ?? ""
+	);
+}

package/src/core/curve/curves.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import { APPROXIMATING_CURVES, CURVE_TYPES, CURVES } from "./curves";
+
+describe("CURVES", () => {
+	test("every listed name resolves to an interpolator", () => {
+		expect(CURVE_TYPES.length).toBeGreaterThan(0);
+		for (const name of CURVE_TYPES) expect(CURVES[name]).toBeDefined();
+	});
+
+	test("names the curves that do not touch their own data", () => {
+		// A scrub dot on an approximating curve sits off every datum. Callers
+		// need to be able to ask, rather than find out from a screenshot.
+		expect(APPROXIMATING_CURVES).toContain("basis");
+		for (const name of APPROXIMATING_CURVES) expect(CURVE_TYPES).toContain(name);
+	});
+
+	test("offers monotone, the one interpolating curve that cannot overshoot", () => {
+		expect(CURVE_TYPES).toContain("monotone");
+	});
+});

package/src/core/curve/curves.ts

@@ -0,0 +1,48 @@
+import {
+	curveBasis,
+	curveBumpX,
+	curveBumpY,
+	curveCardinal,
+	curveCatmullRom,
+	curveLinear,
+	curveMonotoneX,
+	curveNatural,
+	curveStep,
+	curveStepAfter,
+	curveStepBefore,
+} from "d3-shape";
+
+/**
+ * The curve interpolators a mark can be drawn with.
+ *
+ * `monotone` is the default worth reaching for on a value-over-time series: it
+ * is the only interpolating curve here that cannot overshoot, so a line
+ * through non-negative data never dips below zero between two points and
+ * invents a loss that never happened.
+ *
+ * `basis` is the odd one out and is kept deliberately. It approximates rather
+ * than interpolates — the drawn line does not pass through its own data — so a
+ * scrub dot placed on the curve will not coincide with any datum. Fine for a
+ * decorative sparkline, wrong for anything a reader will measure.
+ */
+export const CURVES = {
+	linear: curveLinear,
+	monotone: curveMonotoneX,
+	natural: curveNatural,
+	basis: curveBasis,
+	cardinal: curveCardinal,
+	catmullRom: curveCatmullRom,
+	bumpX: curveBumpX,
+	bumpY: curveBumpY,
+	step: curveStep,
+	stepBefore: curveStepBefore,
+	stepAfter: curveStepAfter,
+} as const;
+
+export type CurveType = keyof typeof CURVES;
+
+/** Every curve name, for a caller mapping over the set. */
+export const CURVE_TYPES = Object.keys(CURVES) as readonly CurveType[];
+
+/** Curves that do not pass through their own data points. */
+export const APPROXIMATING_CURVES: readonly CurveType[] = ["basis"];

package/src/core/geometry/band.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test";
+import { groupLayout, resolveBand } from "./band";
+
+describe("resolveBand", () => {
+	test("the step is the smallest gap between neighbouring positions", () => {
+		expect(resolveBand({ xPositions: [0, 50, 100, 150], plotWidth: 200 }).step).toBe(50);
+		expect(resolveBand({ xPositions: [0, 50, 75, 150], plotWidth: 200 }).step).toBe(25);
+	});
+
+	test("the bandwidth is the step less the inner padding", () => {
+		expect(resolveBand({ xPositions: [0, 50], plotWidth: 100 }).bandwidth).toBe(40);
+		expect(resolveBand({ xPositions: [0, 50], plotWidth: 100, innerPadding: 0.5 }).bandwidth).toBe(25);
+		expect(resolveBand({ xPositions: [0, 50], plotWidth: 100, innerPadding: 0 }).bandwidth).toBe(50);
+	});
+
+	test("a bar count divides the plot instead of measuring the positions", () => {
+		// The way to keep bars the same width across charts with different row counts.
+		expect(resolveBand({ xPositions: [0, 50], plotWidth: 100, barCount: 10 }).step).toBe(10);
+	});
+
+	test("an explicit bar width wins over the padding", () => {
+		expect(resolveBand({ xPositions: [0, 50], plotWidth: 100, barWidth: 12 }).bandwidth).toBe(12);
+	});
+
+	test("clamps the inner padding to [0, 1) so a bar never inverts or vanishes", () => {
+		expect(resolveBand({ xPositions: [0, 50], plotWidth: 100, innerPadding: 1 }).bandwidth).toBeGreaterThan(0);
+		expect(resolveBand({ xPositions: [0, 50], plotWidth: 100, innerPadding: -1 }).bandwidth).toBe(50);
+		expect(resolveBand({ xPositions: [0, 50], plotWidth: 100, innerPadding: Number.NaN }).bandwidth).toBe(40);
+	});
+
+	test("a lone bar takes the whole plot as its step", () => {
+		expect(resolveBand({ xPositions: [50], plotWidth: 100 }).step).toBe(100);
+		expect(resolveBand({ xPositions: [], plotWidth: 100 }).step).toBe(100);
+	});
+
+	test("ignores non-finite positions and duplicates", () => {
+		expect(resolveBand({ xPositions: [0, 0, Number.NaN, 50], plotWidth: 100 }).step).toBe(50);
+	});
+
+	test("a collapsed plot yields zero, never NaN", () => {
+		const band = resolveBand({ xPositions: [], plotWidth: 0 });
+		expect(band.step).toBe(0);
+		expect(band.bandwidth).toBe(0);
+	});
+});
+
+describe("groupLayout", () => {
+	test("splits the group's share of the step evenly, centred on the datum", () => {
+		const layout = groupLayout({ step: 100, seriesCount: 2, betweenGroupPadding: 0.2, withinGroupPadding: 0 });
+		// 80 for the group, 40 per slot, centres at ±20.
+		expect(layout.bandwidth).toBe(40);
+		expect(layout.offsets).toEqual([-20, 20]);
+	});
+
+	test("offsets are symmetric about zero for an odd count too", () => {
+		const layout = groupLayout({ step: 100, seriesCount: 3, betweenGroupPadding: 0.1, withinGroupPadding: 0 });
+		expect(layout.offsets).toEqual([-30, 0, 30]);
+	});
+
+	test("within-group padding narrows each bar but not its slot", () => {
+		const layout = groupLayout({ step: 100, seriesCount: 2, betweenGroupPadding: 0.2, withinGroupPadding: 0.5 });
+		expect(layout.bandwidth).toBe(20);
+		expect(layout.offsets).toEqual([-20, 20]);
+	});
+
+	test("an explicit bar width wins over the padding", () => {
+		expect(groupLayout({ step: 100, seriesCount: 2, barWidth: 7 }).bandwidth).toBe(7);
+	});
+
+	test("defaults both paddings to a fifth", () => {
+		const layout = groupLayout({ step: 100, seriesCount: 1 });
+		expect(layout.bandwidth).toBe(64);
+		expect(layout.offsets).toEqual([0]);
+	});
+
+	test("no series is no offsets and no width", () => {
+		expect(groupLayout({ step: 100, seriesCount: 0 })).toEqual({ bandwidth: 0, offsets: [] });
+	});
+});

package/src/core/geometry/band.ts

@@ -0,0 +1,111 @@
+import { clamp } from "../util/clamp";
+
+/** How much of the category axis one datum owns, and how much of that a bar fills. */
+export type Band = {
+	/** Canvas distance from one datum to the next. */
+	readonly step: number;
+	/** Canvas width of a bar. */
+	readonly bandwidth: number;
+};
+
+export type ResolveBandOptions = {
+	/** Canvas x per row — the chart's `xPositions`. */
+	readonly xPositions: readonly number[];
+	readonly plotWidth: number;
+	/** The fraction of the step left empty, split either side. Defaults to 0.2. */
+	readonly innerPadding?: number;
+	/** An exact bar width, overriding `innerPadding`. */
+	readonly barWidth?: number;
+	/** Divide the plot into this many steps instead of measuring the positions. */
+	readonly barCount?: number;
+};
+
+/**
+ * The band a bar draws in, on a scale that has no band of its own.
+ *
+ * There is no band scale in this package; a category sits at its index on a
+ * linear scale. The step is therefore *measured* — the smallest canvas gap
+ * between neighbouring positions — which on evenly spaced data is what a
+ * band scale would have computed, and on a time axis with a missing month is
+ * the honest answer: the narrower gap.
+ *
+ * `barCount` exists so several charts with different row counts can share a
+ * bar width. A lone bar, or no bar, takes the whole plot as its step; it would
+ * otherwise have no width at all.
+ */
+export function resolveBand(options: ResolveBandOptions): Band {
+	const { xPositions, plotWidth, barWidth, barCount } = options;
+	const width = Number.isFinite(plotWidth) && plotWidth > 0 ? plotWidth : 0;
+
+	let step: number;
+	if (barCount !== undefined && Number.isFinite(barCount) && barCount > 0) {
+		step = width / barCount;
+	} else {
+		step = smallestGap(xPositions);
+		if (step === 0) step = width;
+	}
+
+	const padding = paddingOrDefault(options.innerPadding, 0.2);
+	const bandwidth = barWidth !== undefined && Number.isFinite(barWidth) ? Math.max(barWidth, 0) : step * (1 - padding);
+	return { step, bandwidth };
+}
+
+export type GroupLayoutOptions = {
+	readonly step: number;
+	readonly seriesCount: number;
+	/** The fraction of the step left empty between groups. Defaults to 0.2. */
+	readonly betweenGroupPadding?: number;
+	/** The fraction of each bar's slot left empty. Defaults to 0.2. */
+	readonly withinGroupPadding?: number;
+	readonly barWidth?: number;
+};
+
+export type GroupLayout = {
+	readonly bandwidth: number;
+	/** Canvas x offset of each series' bar from the datum's x, symmetric about zero. */
+	readonly offsets: readonly number[];
+};
+
+/**
+ * Where each series' bar sits inside a grouped step.
+ *
+ * The offsets are symmetric about zero so the group is centred on the datum,
+ * which keeps the scrub's snapped x — the datum's x — in the middle of the
+ * group rather than on its first bar.
+ */
+export function groupLayout(options: GroupLayoutOptions): GroupLayout {
+	const { step, seriesCount, barWidth } = options;
+	if (!Number.isFinite(seriesCount) || seriesCount <= 0) return { bandwidth: 0, offsets: [] };
+
+	const between = paddingOrDefault(options.betweenGroupPadding, 0.2);
+	const within = paddingOrDefault(options.withinGroupPadding, 0.2);
+	const groupWidth = step * (1 - between);
+	const slot = groupWidth / seriesCount;
+	const bandwidth = barWidth !== undefined && Number.isFinite(barWidth) ? Math.max(barWidth, 0) : slot * (1 - within);
+
+	const offsets: number[] = [];
+	for (let index = 0; index < seriesCount; index += 1) {
+		offsets.push(-groupWidth / 2 + slot * (index + 0.5));
+	}
+	return { bandwidth, offsets };
+}
+
+/** The smallest positive gap between neighbouring positions, or zero when there is none. */
+function smallestGap(positions: readonly number[]): number {
+	const sorted = positions.filter((value) => Number.isFinite(value)).sort((a, b) => a - b);
+	let gap = Number.POSITIVE_INFINITY;
+	for (let index = 1; index < sorted.length; index += 1) {
+		const current = (sorted[index] as number) - (sorted[index - 1] as number);
+		if (current > 0 && current < gap) gap = current;
+	}
+	return Number.isFinite(gap) ? gap : 0;
+}
+
+/**
+ * A padding fraction held inside `[0, 1)`. At one a bar would have no width
+ * and above it a negative one, which draws inside out.
+ */
+function paddingOrDefault(value: number | undefined, fallback: number): number {
+	if (value === undefined || !Number.isFinite(value)) return fallback;
+	return clamp(value, 0, 1 - Number.EPSILON);
+}