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

package/src/core/shape/build-candles.ts

@@ -0,0 +1,153 @@
+import type { ChartOrientation, ChartPoint } from "../chart.types";
+import { rectPath } from "./rect-path";
+
+/** Which way a candle went: close above open, below it, or unchanged. */
+export type Sentiment = "positive" | "negative" | "neutral";
+
+export const SENTIMENTS: readonly Sentiment[] = ["positive", "negative", "neutral"];
+
+/**
+ * One candle, in canvas positions and domain values.
+ *
+ * `x` is the category's position and the four `…Y` fields are positions
+ * along the value axis. On a horizontal chart those axes swap — `x` is then
+ * a canvas y and `openY` a canvas x — and the names keep the vertical case,
+ * like `xValue` and `yValue` do.
+ */
+export type Candle = {
+	readonly index: number;
+	readonly x: number;
+	readonly openY: number;
+	readonly highY: number;
+	readonly lowY: number;
+	readonly closeY: number;
+	readonly openValue: number | null;
+	readonly highValue: number | null;
+	readonly lowValue: number | null;
+	readonly closeValue: number | null;
+	readonly sentiment: Sentiment;
+	/** Any of the four values missing. The canvas fields are then `NaN`. */
+	readonly gap: boolean;
+};
+
+/** Close above open is positive. Equal, or anything unreadable, is neutral. */
+export function candleSentiment(openValue: number | null, closeValue: number | null): Sentiment {
+	if (openValue === null || closeValue === null || !Number.isFinite(openValue) || !Number.isFinite(closeValue)) {
+		return "neutral";
+	}
+	if (closeValue > openValue) return "positive";
+	if (closeValue < openValue) return "negative";
+	return "neutral";
+}
+
+/**
+ * Four series zipped into candles by index.
+ *
+ * A row missing any of the four is a gap candle, kept in its place, so the
+ * candle count — and therefore the verb count of every path — matches the
+ * row count.
+ */
+export function candlePoints(
+	open: readonly ChartPoint[],
+	high: readonly ChartPoint[],
+	low: readonly ChartPoint[],
+	close: readonly ChartPoint[],
+	orientation: ChartOrientation = "vertical"
+): Candle[] {
+	const length = Math.min(open.length, high.length, low.length, close.length);
+	const horizontal = orientation === "horizontal";
+	const valueAt = (point: ChartPoint): number | null => (horizontal ? point.x : point.y);
+	const candles: Candle[] = [];
+
+	for (let index = 0; index < length; index += 1) {
+		const o = open[index] as ChartPoint;
+		const h = high[index] as ChartPoint;
+		const l = low[index] as ChartPoint;
+		const c = close[index] as ChartPoint;
+		const gap = [o, h, l, c].some((point) => {
+			const value = valueAt(point);
+			return value === null || !Number.isFinite(value) || point.yValue === null;
+		});
+		candles.push({
+			index,
+			x: (horizontal ? o.y : o.x) ?? Number.NaN,
+			openY: gap ? Number.NaN : (valueAt(o) as number),
+			highY: gap ? Number.NaN : (valueAt(h) as number),
+			lowY: gap ? Number.NaN : (valueAt(l) as number),
+			closeY: gap ? Number.NaN : (valueAt(c) as number),
+			openValue: o.yValue,
+			highValue: h.yValue,
+			lowValue: l.yValue,
+			closeValue: c.yValue,
+			sentiment: gap ? "neutral" : candleSentiment(o.yValue, c.yValue),
+			gap,
+		});
+	}
+
+	return candles;
+}
+
+export type CandlePathOptions = {
+	readonly bandwidth: number;
+	/** A body thinner than this is expanded about its midpoint, so a flat candle is still visible. Defaults to 1. */
+	readonly minBodyHeight?: number;
+	/** Canvas position along the value axis a gap candle collapses to. Defaults to 0. */
+	readonly baseline?: number;
+	/** Bodies span open to close along y (the default) or along x. */
+	readonly orientation?: ChartOrientation;
+};
+
+export type CandlePaths = {
+	readonly bodies: string;
+	readonly wicks: string;
+};
+
+/**
+ * Bodies and wicks, one pair of paths per sentiment.
+ *
+ * **Every candle appears in all three sentiment paths.** In the two whose
+ * sentiment it does not have it is a zero-size rect and a zero-length wick at
+ * its own midpoint. Six paths of N shapes each, always, so a candle whose
+ * close crosses its open morphs from one colour's path into the other rather
+ * than vanishing from one and appearing in the next — and so the paths stay
+ * interpolatable across the change at all.
+ *
+ * A gap candle is degenerate in all six, at the baseline. Wicks are drawn
+ * with butt caps by the mark, which is what makes a zero-length wick draw
+ * nothing rather than a dot.
+ */
+export function buildCandlePaths(
+	candles: readonly Candle[],
+	options: CandlePathOptions
+): Record<Sentiment, CandlePaths> {
+	const { bandwidth, minBodyHeight = 1, baseline = 0, orientation = "vertical" } = options;
+	const horizontal = orientation === "horizontal";
+	const half = bandwidth / 2;
+	// A rect stated as (category from, value from, category to, value to).
+	const rect = (c0: number, v0: number, c1: number, v1: number): string =>
+		horizontal ? rectPath(v0, c0, v1, c1, {}) : rectPath(c0, v0, c1, v1, {});
+	const line = (c: number, v0: number, v1: number): string =>
+		horizontal ? `M${v0},${c}L${v1},${c}` : `M${c},${v0}L${c},${v1}`;
+	const bodies: Record<Sentiment, string> = { positive: "", negative: "", neutral: "" };
+	const wicks: Record<Sentiment, string> = { positive: "", negative: "", neutral: "" };
+
+	for (const candle of candles) {
+		const mid = candle.gap ? baseline : (candle.openY + candle.closeY) / 2;
+		for (const sentiment of SENTIMENTS) {
+			if (candle.gap || sentiment !== candle.sentiment) {
+				bodies[sentiment] += rect(candle.x, mid, candle.x, mid);
+				wicks[sentiment] += line(candle.x, mid, mid);
+				continue;
+			}
+			const height = Math.max(Math.abs(candle.closeY - candle.openY), minBodyHeight);
+			bodies[sentiment] += rect(candle.x - half, mid - height / 2, candle.x + half, mid + height / 2);
+			wicks[sentiment] += line(candle.x, candle.highY, candle.lowY);
+		}
+	}
+
+	return {
+		positive: { bodies: bodies.positive, wicks: wicks.positive },
+		negative: { bodies: bodies.negative, wicks: wicks.negative },
+		neutral: { bodies: bodies.neutral, wicks: wicks.neutral },
+	};
+}

package/src/core/shape/build-scatter.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "bun:test";
+import type { ChartPoint } from "../chart.types";
+import { buildScatterPath } from "./build-scatter";
+
+const at = (x: number, y: number | null): ChartPoint => ({ x, y, xValue: x, yValue: y });
+
+function commands(path: string): string {
+	return (path.match(/[A-Za-z]/g) ?? []).join("");
+}
+
+function numbers(path: string): number[] {
+	return (path.match(/-?\d+(?:\.\d+)?(?:e[-+]?\d+)?/g) ?? []).map(Number);
+}
+
+describe("buildScatterPath", () => {
+	test("a circle is a move and four cubics, closed", () => {
+		expect(commands(buildScatterPath([at(10, 10)], { radius: 4, baseline: 100 }))).toBe("MCCCCZ");
+	});
+
+	test("a square is a move and three lines, closed", () => {
+		expect(commands(buildScatterPath([at(10, 10)], { radius: 4, shape: "square", baseline: 100 }))).toBe("MLLLZ");
+	});
+
+	test("a star is a move and nine lines, closed", () => {
+		expect(commands(buildScatterPath([at(10, 10)], { radius: 4, shape: "star", baseline: 100 }))).toBe("MLLLLLLLLLZ");
+	});
+
+	test("one shape's worth of verbs per point", () => {
+		const points = [at(10, 10), at(20, 20), at(30, 30)];
+		expect(commands(buildScatterPath(points, { radius: 4, baseline: 100 }))).toBe("MCCCCZ".repeat(3));
+		expect(commands(buildScatterPath(points, { radius: 4, shape: "square", baseline: 100 }))).toBe("MLLLZ".repeat(3));
+	});
+
+	test("a square's corners are a radius from the centre on each axis", () => {
+		const path = buildScatterPath([at(10, 20)], { radius: 4, shape: "square", baseline: 100 });
+		expect(numbers(path)).toEqual([6, 16, 14, 16, 14, 24, 6, 24]);
+	});
+
+	test("a circle's cubics start at the top and pass through the four compass points", () => {
+		const path = buildScatterPath([at(10, 20)], { radius: 4, baseline: 100 });
+		expect(path.startsWith("M10,16")).toBe(true);
+		const values = numbers(path);
+		// Each cubic's end point is every sixth pair after the move.
+		expect([values[6], values[7]]).toEqual([14, 20]);
+		expect([values[12], values[13]]).toEqual([10, 24]);
+		expect([values[18], values[19]]).toEqual([6, 20]);
+	});
+
+	test("a star alternates outer and inner vertices, the inner at 0.382 of the radius", () => {
+		const values = numbers(buildScatterPath([at(0, 0)], { radius: 10, shape: "star", baseline: 100 }));
+		const distances: number[] = [];
+		for (let index = 0; index < values.length; index += 2) {
+			distances.push(Math.hypot(values[index] as number, values[index + 1] as number));
+		}
+		expect(distances).toHaveLength(10);
+		for (let index = 0; index < distances.length; index += 1) {
+			expect(distances[index]).toBeCloseTo(index % 2 === 0 ? 10 : 3.82, 5);
+		}
+		// The first vertex points straight up.
+		expect(values[0]).toBeCloseTo(0, 10);
+		expect(values[1]).toBeCloseTo(-10, 10);
+	});
+
+	test("a radius function receives the point and its index", () => {
+		const seen: [number, number][] = [];
+		buildScatterPath([at(1, 1), at(2, 2)], {
+			radius: (point, index) => {
+				seen.push([point.x, index]);
+				return 3;
+			},
+			baseline: 100,
+		});
+		expect(seen).toEqual([
+			[1, 0],
+			[2, 1],
+		]);
+	});
+
+	test("a gap keeps its verbs as a zero-radius shape at the baseline", () => {
+		// The animation invariant again: a datum that gains a value morphs out
+		// of the baseline rather than the whole series snapping.
+		const path = buildScatterPath([at(10, 10), at(20, null), at(30, 30)], { radius: 4, baseline: 100 });
+		expect(commands(path)).toBe("MCCCCZ".repeat(3));
+		expect(path).toContain("M20,100");
+	});
+
+	test("a non-finite radius collapses the shape at its own point", () => {
+		const path = buildScatterPath([at(10, 10)], { radius: () => Number.NaN, baseline: 100 });
+		expect(commands(path)).toBe("MCCCCZ");
+		expect(path.startsWith("M10,10")).toBe(true);
+	});
+
+	test("is empty for no points", () => {
+		expect(buildScatterPath([], { radius: 4, baseline: 100 })).toBe("");
+	});
+
+	test("a horizontal gap collapses at the baseline x, keeping its category y", () => {
+		const gap: ChartPoint = { x: Number.NaN, y: 40, xValue: 1, yValue: null };
+		const path = buildScatterPath([gap], { radius: 4, baseline: 7, orientation: "horizontal" });
+		expect(commands(path)).toBe("MCCCCZ");
+		expect(path.startsWith("M7,40")).toBe(true);
+	});
+});

package/src/core/shape/build-scatter.ts

@@ -0,0 +1,81 @@
+import type { ChartOrientation, ChartPoint } from "../chart.types";
+import { KAPPA } from "./rect-path";
+
+export type ScatterShape = "circle" | "square" | "star";
+
+/** A star's inner vertices sit at this fraction of the radius — the golden-ratio pentagram. */
+const STAR_INNER = 0.382;
+
+export type ScatterPathOptions = {
+	/** One radius for every point, or one per point. */
+	readonly radius: number | ((point: ChartPoint, index: number) => number);
+	readonly shape?: ScatterShape;
+	/** Canvas position along the value axis a gap's collapsed shape sits at, so it grows out of the axis when it gains a value. */
+	readonly baseline: number;
+	/** Whether the value axis is y (the default) or x. */
+	readonly orientation?: ChartOrientation;
+};
+
+/**
+ * One shape per point, all in one path.
+ *
+ * Each shape has a fixed verb sequence — a circle is four cubics, a square
+ * three lines, a star nine — and a gap or an unreadable radius emits the same
+ * shape at radius zero rather than nothing. That keeps two series of equal
+ * length interpolatable whatever their values, which is what lets a scatter
+ * animate a data change instead of snapping.
+ */
+export function buildScatterPath(points: readonly ChartPoint[], options: ScatterPathOptions): string {
+	const { radius, shape = "circle", baseline, orientation = "vertical" } = options;
+	const horizontal = orientation === "horizontal";
+	let path = "";
+
+	for (let index = 0; index < points.length; index += 1) {
+		const point = points[index] as ChartPoint;
+		const gap = point.y === null || !Number.isFinite(point.y) || !Number.isFinite(point.x);
+		const requested = typeof radius === "function" ? radius(point, index) : radius;
+		const r = gap || !Number.isFinite(requested) || requested < 0 ? 0 : requested;
+		const x = gap && horizontal ? baseline : point.x;
+		const y = gap && !horizontal ? baseline : (point.y as number);
+		path += shapePath(shape, x, y, r);
+	}
+
+	return path;
+}
+
+function shapePath(shape: ScatterShape, cx: number, cy: number, r: number): string {
+	switch (shape) {
+		case "circle":
+			return circlePath(cx, cy, r);
+		case "square":
+			return `M${cx - r},${cy - r}L${cx + r},${cy - r}L${cx + r},${cy + r}L${cx - r},${cy + r}Z`;
+		case "star":
+			return starPath(cx, cy, r);
+	}
+}
+
+/** A circle as four cubics, starting at the top and running clockwise. */
+function circlePath(cx: number, cy: number, r: number): string {
+	const k = r * KAPPA;
+	return (
+		`M${cx},${cy - r}` +
+		`C${cx + k},${cy - r},${cx + r},${cy - k},${cx + r},${cy}` +
+		`C${cx + r},${cy + k},${cx + k},${cy + r},${cx},${cy + r}` +
+		`C${cx - k},${cy + r},${cx - r},${cy + k},${cx - r},${cy}` +
+		`C${cx - r},${cy - k},${cx - k},${cy - r},${cx},${cy - r}` +
+		"Z"
+	);
+}
+
+/** A five-pointed star, first vertex straight up, alternating outer and inner radii. */
+function starPath(cx: number, cy: number, r: number): string {
+	let path = "";
+	for (let vertex = 0; vertex < 10; vertex += 1) {
+		const distance = vertex % 2 === 0 ? r : r * STAR_INNER;
+		const angle = -Math.PI / 2 + (vertex * Math.PI) / 5;
+		const x = cx + Math.cos(angle) * distance;
+		const y = cy + Math.sin(angle) * distance;
+		path += `${vertex === 0 ? "M" : "L"}${x},${y}`;
+	}
+	return `${path}Z`;
+}

package/src/core/shape/rect-path.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import { KAPPA, rectPath } from "./rect-path";
+
+/** The command letters of a path, which is what `isInterpolatable` compares. */
+function commands(path: string): string {
+	return (path.match(/[A-Za-z]/g) ?? []).join("");
+}
+
+/** Every number in a path, in order. */
+function numbers(path: string): number[] {
+	return (path.match(/-?\d+(?:\.\d+)?(?:e[-+]?\d+)?/g) ?? []).map(Number);
+}
+
+describe("rectPath", () => {
+	test("is always a move, four cubic corners and three lines, closed", () => {
+		// The animation invariant: a bar that rounds its corners when the data
+		// changes must keep the same verbs, or Skia snaps instead of morphing.
+		expect(commands(rectPath(0, 0, 10, 20, {}))).toBe("MCLCLCLCZ");
+		expect(commands(rectPath(0, 0, 10, 20, { topLeft: 4, topRight: 4 }))).toBe("MCLCLCLCZ");
+		expect(commands(rectPath(0, 0, 10, 20, { topLeft: 100, bottomRight: 100 }))).toBe("MCLCLCLCZ");
+	});
+
+	test("with square corners every point sits on the rect's edge", () => {
+		for (const value of numbers(rectPath(2, 3, 12, 23, {}))) {
+			expect([2, 3, 12, 23]).toContain(value);
+		}
+	});
+
+	test("starts on the left edge, one radius below the top", () => {
+		expect(rectPath(0, 0, 10, 20, { topLeft: 4 }).startsWith("M0,4")).toBe(true);
+		expect(rectPath(0, 0, 10, 20, {}).startsWith("M0,0")).toBe(true);
+	});
+
+	test("a rounded corner's cubic reaches the tangent points, not the corner", () => {
+		const path = rectPath(0, 0, 10, 20, { topLeft: 4 });
+		// M0,4 then C toward (4,0): the cubic's end point is the tangent point.
+		expect(path.startsWith(`M0,4C0,${4 - 4 * KAPPA},${4 - 4 * KAPPA},0,4,0`)).toBe(true);
+	});
+
+	test("clamps a radius to half the shorter side", () => {
+		// A 10×20 rect can round by at most 5; more would fold the path over.
+		const path = rectPath(0, 0, 10, 20, { topLeft: 100, topRight: 100 });
+		expect(path.startsWith("M0,5")).toBe(true);
+		expect(path).toContain("L5,0");
+	});
+
+	test("normalises a rect given upside down or back to front", () => {
+		expect(rectPath(10, 20, 0, 0, {})).toBe(rectPath(0, 0, 10, 20, {}));
+	});
+
+	test("a zero-height rect still has all nine verbs", () => {
+		// A gap in a bar series is a zero-height bar at the baseline, so its
+		// path must match the bar it may animate into.
+		expect(commands(rectPath(0, 5, 10, 5, { topLeft: 4 }))).toBe("MCLCLCLCZ");
+	});
+
+	test("treats a negative or unreadable radius as square", () => {
+		expect(rectPath(0, 0, 10, 20, { topLeft: -4 })).toBe(rectPath(0, 0, 10, 20, {}));
+		expect(rectPath(0, 0, 10, 20, { topLeft: Number.NaN })).toBe(rectPath(0, 0, 10, 20, {}));
+	});
+});

package/src/core/shape/rect-path.ts

@@ -0,0 +1,69 @@
+/** A radius per corner. A missing corner is square. */
+export type CornerRadii = {
+	readonly topLeft?: number;
+	readonly topRight?: number;
+	readonly bottomRight?: number;
+	readonly bottomLeft?: number;
+};
+
+/**
+ * The control-point distance, as a fraction of the radius, at which a cubic
+ * best approximates a quarter circle. Standard value: `4(√2 − 1) / 3`.
+ */
+export const KAPPA = 0.5522847498;
+
+/**
+ * A rectangle as an SVG path whose every corner is a cubic.
+ *
+ * Always `M C L C L C L C Z` — nine verbs — whether a corner is rounded or
+ * not. A square corner is a cubic whose four points coincide. That is the
+ * animation invariant: Skia interpolates two paths only when their verbs
+ * match, so a bar that goes from square to rounded, or from a value to a gap,
+ * has to keep the same verb sequence or it snaps instead of morphing.
+ *
+ * Radii are clamped to half the shorter side so a tall thin bar rounds into a
+ * capsule rather than folding the path over itself.
+ */
+export function rectPath(left: number, top: number, right: number, bottom: number, radii: CornerRadii): string {
+	const x0 = Math.min(left, right);
+	const x1 = Math.max(left, right);
+	const y0 = Math.min(top, bottom);
+	const y1 = Math.max(top, bottom);
+	const limit = Math.min((x1 - x0) / 2, (y1 - y0) / 2);
+
+	const tl = clampRadius(radii.topLeft, limit);
+	const tr = clampRadius(radii.topRight, limit);
+	const br = clampRadius(radii.bottomRight, limit);
+	const bl = clampRadius(radii.bottomLeft, limit);
+
+	return (
+		`M${x0},${y0 + tl}` +
+		corner(x0, y0 + tl, x0, y0, x0 + tl, y0) +
+		`L${x1 - tr},${y0}` +
+		corner(x1 - tr, y0, x1, y0, x1, y0 + tr) +
+		`L${x1},${y1 - br}` +
+		corner(x1, y1 - br, x1, y1, x1 - br, y1) +
+		`L${x0 + bl},${y1}` +
+		corner(x0 + bl, y1, x0, y1, x0, y1 - bl) +
+		"Z"
+	);
+}
+
+/** A radius that is finite, non-negative and no more than `limit`. */
+function clampRadius(radius: number | undefined, limit: number): number {
+	if (radius === undefined || !Number.isFinite(radius) || radius <= 0) return 0;
+	return Math.min(radius, Math.max(limit, 0));
+}
+
+/**
+ * A cubic from `(ax, ay)` to `(bx, by)` bowing toward the corner `(cx, cy)`.
+ * With the corner on both points it is a cubic of zero length, which is what
+ * keeps the verb count fixed.
+ */
+function corner(ax: number, ay: number, cx: number, cy: number, bx: number, by: number): string {
+	const c1x = ax + (cx - ax) * KAPPA;
+	const c1y = ay + (cy - ay) * KAPPA;
+	const c2x = bx + (cx - bx) * KAPPA;
+	const c2y = by + (cy - by) * KAPPA;
+	return `C${c1x},${c1y},${c2x},${c2y},${bx},${by}`;
+}

package/src/core/text/axis-gutters.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test";
+import { resolveAxisGutters } from "./axis-gutters";
+
+const base = { yLabelWidths: [10, 24, 18], xLabelWidths: [30, 30, 30], fontHeight: 12 };
+
+describe("resolveAxisGutters", () => {
+	test("reserves the widest y label plus the tick padding", () => {
+		expect(resolveAxisGutters({ ...base, tickPadding: 6 }).left).toBe(30);
+	});
+
+	test("reserves one line height under the plot for the x labels", () => {
+		expect(resolveAxisGutters({ ...base, tickPadding: 6 }).bottom).toBe(18);
+	});
+
+	test("moves the gutter to the other side when the axis does", () => {
+		const right = resolveAxisGutters({ ...base, yAxisSide: "right" });
+		expect(right.left).toBeLessThan(right.right);
+		const top = resolveAxisGutters({ ...base, xAxisSide: "top" });
+		// The bottom keeps the y labels' half-line overhang, but loses the x
+		// gutter entirely — 6 rather than 18.
+		expect(top.bottom).toBe(6);
+		expect(top.top).toBeGreaterThan(base.fontHeight);
+	});
+
+	test("carries the first and last x label's overhang", () => {
+		// Without it the leftmost label is clipped in half by the canvas edge,
+		// which reads as a rendering bug rather than a layout one.
+		const gutters = resolveAxisGutters({ ...base, yLabelWidths: [], xLabelWidths: [80, 30, 80] });
+		expect(gutters.left).toBe(40);
+		expect(gutters.right).toBe(40);
+	});
+
+	test("takes the wider of the y gutter and the label overhang, not their sum", () => {
+		const gutters = resolveAxisGutters({ ...base, yLabelWidths: [100], xLabelWidths: [20, 20], tickPadding: 6 });
+		expect(gutters.left).toBe(106);
+	});
+
+	test("reserves half a line above and below for the outermost y labels", () => {
+		// A y label is centred on its tick and the outermost ticks sit on the
+		// plot rect's edges, so half a line escapes at each end. Without this the
+		// top label is sliced by the canvas — the vertical twin of the x labels'
+		// horizontal overhang.
+		const gutters = resolveAxisGutters({ ...base, xLabelWidths: [], fontHeight: 12 });
+		expect(gutters.top).toBe(6);
+		expect(gutters.bottom).toBe(6);
+	});
+
+	test("takes the wider of the x gutter and the y overhang, not their sum", () => {
+		const gutters = resolveAxisGutters({ ...base, tickPadding: 6 });
+		expect(gutters.bottom).toBe(18);
+	});
+
+	test("reserves no vertical overhang when the y axis draws no labels", () => {
+		expect(resolveAxisGutters({ ...base, yLabelWidths: [], xLabelWidths: [] }).top).toBe(0);
+	});
+
+	test("reserves nothing for an axis that is not drawn", () => {
+		const gutters = resolveAxisGutters({ ...base, showXAxis: false, showYAxis: false });
+		expect(gutters).toEqual({ left: 0, right: 0, top: 0, bottom: 0 });
+	});
+
+	test("reserves nothing when there are no labels to draw", () => {
+		expect(resolveAxisGutters({ yLabelWidths: [], xLabelWidths: [], fontHeight: 12 })).toEqual({
+			left: 0,
+			right: 0,
+			top: 0,
+			bottom: 0,
+		});
+	});
+});

package/src/core/text/axis-gutters.ts

@@ -0,0 +1,70 @@
+import type { ChartGutters } from "../geometry/chart-bounds";
+
+export type AxisGutterInput = {
+	/** Measured widths of the y-axis labels, in points. */
+	readonly yLabelWidths: readonly number[];
+	/** Measured widths of the x-axis labels, in points. */
+	readonly xLabelWidths: readonly number[];
+	/** Line height of the axis font. */
+	readonly fontHeight: number;
+	/** Space between a label and the plot rect. */
+	readonly tickPadding?: number;
+	readonly showXAxis?: boolean;
+	readonly showYAxis?: boolean;
+	readonly yAxisSide?: "left" | "right";
+	readonly xAxisSide?: "top" | "bottom";
+};
+
+const DEFAULT_TICK_PADDING = 6;
+
+/**
+ * How much room the axes need outside the plot rect.
+ *
+ * This is the second half of a two-pass layout, and the reason it is only two
+ * passes. Label width sets the gutter, the gutter sets the plot rect, and the
+ * plot rect sets how many ticks fit — a cycle. It is broken by computing the
+ * tick *values* against the whole canvas first, measuring those, and then
+ * moving only the scale's range. The values never change, so the layout is a
+ * pure function of the measurements and never oscillates.
+ *
+ * The horizontal gutters also carry the first and last x label's overhang.
+ * Without it a "Jan 2026" under the leftmost tick is clipped in half by the
+ * canvas edge, which reads as a rendering bug rather than a layout one.
+ */
+export function resolveAxisGutters(input: AxisGutterInput): ChartGutters {
+	const padding = input.tickPadding ?? DEFAULT_TICK_PADDING;
+	const showY = input.showYAxis ?? true;
+	const showX = input.showXAxis ?? true;
+	const labels = showX ? input.xLabelWidths : [];
+
+	const widestY = showY ? widest(input.yLabelWidths) : 0;
+	const yGutter = widestY === 0 ? 0 : widestY + padding;
+	const xGutter = labels.length === 0 ? 0 : input.fontHeight + padding;
+
+	const overhangLeft = (labels[0] ?? 0) / 2;
+	const overhangRight = (labels[labels.length - 1] ?? 0) / 2;
+
+	const yOnLeft = (input.yAxisSide ?? "left") === "left";
+	const xOnBottom = (input.xAxisSide ?? "bottom") === "bottom";
+
+	// A y label is centred on its tick, and the outermost ticks sit exactly on
+	// the plot rect's edges — so half a line escapes at the top and half at the
+	// bottom. Without this the first and last labels are sliced by the canvas,
+	// which is the vertical twin of the x labels' horizontal overhang.
+	const yOverhang = yGutter === 0 ? 0 : input.fontHeight / 2;
+
+	return {
+		left: Math.max(yOnLeft ? yGutter : 0, overhangLeft),
+		right: Math.max(yOnLeft ? 0 : yGutter, overhangRight),
+		top: Math.max(xOnBottom ? 0 : xGutter, yOverhang),
+		bottom: Math.max(xOnBottom ? xGutter : 0, yOverhang),
+	};
+}
+
+function widest(widths: readonly number[]): number {
+	let max = 0;
+	for (const width of widths) {
+		if (Number.isFinite(width) && width > max) max = width;
+	}
+	return max;
+}