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

package/src/core/geometry/transform-input-data.ts

@@ -0,0 +1,88 @@
+import type { ChartOrientation, ChartPoint, ChartRow } from "../chart.types";
+import { scaleValue } from "../scale/scale";
+import type { ScaleDescriptor } from "../scale/scale.types";
+import { asNumber } from "../util/as-number";
+
+export type TransformInputOptions = {
+	readonly data: readonly ChartRow[];
+	readonly yKeys: readonly string[];
+	/** x in domain units, already resolved — see `resolveXValues`. */
+	readonly xValues: readonly number[];
+	/** The scale on the canvas' x axis — categories when vertical, values when horizontal. */
+	readonly xScale: ScaleDescriptor;
+	/** The scale on the canvas' y axis. */
+	readonly yScale: ScaleDescriptor;
+	/** Defaults to `vertical`. */
+	readonly orientation?: ChartOrientation;
+};
+
+export type TransformedData = {
+	/** One array per y key, in the order the keys were given. */
+	readonly points: Readonly<Record<string, readonly ChartPoint[]>>;
+	/**
+	 * Canvas position of each row's category, shared by every series — the
+	 * scrub's search space. An x on a vertical chart, a y on a horizontal one;
+	 * the name is the vertical case, like `xValue`.
+	 */
+	readonly xPositions: readonly number[];
+};
+
+/**
+ * Rows into plotted points, one series per y key.
+ *
+ * A row whose y field is missing, `null` or unparseable becomes a point with
+ * `y: null` rather than being dropped. Dropping it would shift every later
+ * point one place left against the x positions, and the line would silently
+ * draw the wrong shape.
+ */
+export function transformInputData(options: TransformInputOptions): TransformedData {
+	const { data, yKeys, xValues, xScale, yScale, orientation = "vertical" } = options;
+	const horizontal = orientation === "horizontal";
+	const categoryScale = horizontal ? yScale : xScale;
+	const valueScale = horizontal ? xScale : yScale;
+
+	const xPositions = xValues.map((value) => scaleValue(categoryScale, value));
+	const points: Record<string, ChartPoint[]> = {};
+
+	for (const key of yKeys) {
+		const series: ChartPoint[] = new Array(data.length);
+		for (let index = 0; index < data.length; index += 1) {
+			const yValue = asNumber((data[index] as ChartRow)[key]);
+			const plottable = Number.isFinite(yValue);
+			series[index] = plotPoint(
+				horizontal,
+				xPositions[index] as number,
+				xValues[index] as number,
+				plottable ? yValue : null,
+				plottable ? scaleValue(valueScale, yValue) : null
+			);
+		}
+		points[key] = series;
+	}
+
+	return { points, xPositions };
+}
+
+/** One point, its category and value positions on whichever canvas axes the orientation says. */
+function plotPoint(
+	horizontal: boolean,
+	category: number,
+	xValue: number,
+	yValue: number | null,
+	valuePosition: number | null
+): ChartPoint {
+	if (horizontal) return { x: valuePosition ?? Number.NaN, y: category, xValue, yValue };
+	return { x: category, y: valuePosition, xValue, yValue };
+}
+
+/** Every y value across every series, for measuring one shared domain. */
+export function collectYValues(data: readonly ChartRow[], yKeys: readonly string[]): number[] {
+	const values: number[] = [];
+	for (const row of data) {
+		for (const key of yKeys) {
+			const value = asNumber(row[key]);
+			if (Number.isFinite(value)) values.push(value);
+		}
+	}
+	return values;
+}

package/src/core/geometry/x-values.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { resolveXValues } from "./x-values";
+
+describe("resolveXValues", () => {
+	test("reads a numeric field as itself", () => {
+		const resolved = resolveXValues([{ t: 10 }, { t: 20 }], "t");
+		expect(resolved.values).toEqual([10, 20]);
+		expect(resolved.isCategorical).toBe(false);
+	});
+
+	test("reads a Date field as epoch milliseconds", () => {
+		const resolved = resolveXValues([{ t: new Date(1000) }, { t: new Date(2000) }], "t");
+		expect(resolved.values).toEqual([1000, 2000]);
+		expect(resolved.isCategorical).toBe(false);
+	});
+
+	test("substitutes indices for a label field", () => {
+		const resolved = resolveXValues([{ m: "Jan" }, { m: "Feb" }, { m: "Mar" }], "m");
+		expect(resolved.values).toEqual([0, 1, 2]);
+		expect(resolved.isCategorical).toBe(true);
+		expect(resolved.raw).toEqual(["Jan", "Feb", "Mar"]);
+	});
+
+	test("falls back for the whole series when a single row is unreadable", () => {
+		// Mixing measured values with indices breaks the ascending order every
+		// binary search here assumes, and a scrub lands on the wrong datum.
+		const resolved = resolveXValues([{ t: 10 }, { t: "n/a" }, { t: 30 }], "t");
+		expect(resolved.values).toEqual([0, 1, 2]);
+		expect(resolved.isCategorical).toBe(true);
+	});
+
+	test("handles an empty dataset", () => {
+		const resolved = resolveXValues([], "t");
+		expect(resolved.values).toEqual([]);
+		expect(resolved.isCategorical).toBe(false);
+	});
+});

package/src/core/geometry/x-values.ts

@@ -0,0 +1,36 @@
+import type { ChartRow } from "../chart.types";
+import { asNumber } from "../util/as-number";
+
+export type ResolvedXValues = {
+	readonly values: readonly number[];
+	/**
+	 * Whether the values are positions rather than measurements.
+	 *
+	 * True when the field held labels and the index stood in for it. An axis
+	 * should then print the original label, never the number.
+	 */
+	readonly isCategorical: boolean;
+	/** The original field values, for a label formatter. */
+	readonly raw: readonly unknown[];
+};
+
+/**
+ * The x values a scale can be built from.
+ *
+ * A chart's x field is often a month name or a category. When *any* row fails
+ * to read as a number the whole series falls back to indices — all of it, not
+ * just the bad rows. Mixing the two would break the ascending order every
+ * binary search in this package assumes, and a scrub would land on the wrong
+ * datum in a way that looks like a rendering bug.
+ */
+export function resolveXValues(data: readonly ChartRow[], xKey: string): ResolvedXValues {
+	const raw = data.map((row) => row[xKey]);
+	const numeric = raw.map(asNumber);
+	const isCategorical = numeric.some((value) => !Number.isFinite(value));
+
+	return {
+		values: isCategorical ? raw.map((_, index) => index) : numeric,
+		isCategorical,
+		raw,
+	};
+}

package/src/core/index.ts

@@ -0,0 +1,109 @@
+export { chooseMorphStrategy, type MorphStrategy } from "./animation/morph-strategy";
+export { matchPointCounts, resamplePoints } from "./animation/resample-points";
+export type { ChartBounds, ChartOrientation, ChartPoint, ChartRow, ChartSegment, ChartSize } from "./chart.types";
+export { type AreaPathOptions, buildAreaPath } from "./curve/build-area";
+export { buildLinePath, isDrawable, type LinePathOptions } from "./curve/build-line";
+export { APPROXIMATING_CURVES, CURVE_TYPES, CURVES, type CurveType } from "./curve/curves";
+export {
+	type Band,
+	type GroupLayout,
+	type GroupLayoutOptions,
+	groupLayout,
+	type ResolveBandOptions,
+	resolveBand,
+} from "./geometry/band";
+export { categoryDomainCovers } from "./geometry/category-domain";
+export { type ChartGutters, getChartBounds, hasArea, NO_GUTTERS } from "./geometry/chart-bounds";
+export {
+	type AxisPlan,
+	axisRanges,
+	type ChartFrame,
+	type ChartPlan,
+	type PlanAxisOptions,
+	pickAxisRoles,
+	placeAxisRoles,
+	planAxis,
+	type ResolveChartFrameOptions,
+	resolveChartFrame,
+} from "./geometry/chart-layout";
+export {
+	type DomainPadding,
+	EMPTY_DOMAIN,
+	type ResolveDomainOptions,
+	resolveDomain,
+	resolveDomainPadding,
+} from "./geometry/domain";
+export { type GridAxis, type GridSegment, type GridSegmentOptions, gridSegments } from "./geometry/grid-lines";
+export { collectStackedYValues, type StackSeriesOptions, stackSeries } from "./geometry/stack";
+export { resolveStep } from "./geometry/step";
+export {
+	collectYValues,
+	type TransformedData,
+	type TransformInputOptions,
+	transformInputData,
+} from "./geometry/transform-input-data";
+export { type ResolvedXValues, resolveXValues } from "./geometry/x-values";
+export { closestIndex } from "./interaction/closest-index";
+export { type CurvePath, type CurveRun, RUN_STRIDE, runSegmentCount, toCurvePath } from "./interaction/path-segments";
+export { getYForX } from "./interaction/y-for-x";
+// polar — pie and donut geometry
+export { ARC_SEGMENTS, buildSliceEdgePath, buildSlicePath } from "./polar/build-slice-path";
+export { sliceLabelPosition } from "./polar/label-position";
+export { collectPieInput, type PieInput } from "./polar/pie-input";
+export type { InnerRadius, PieSliceData, PolarLayout, PolarPoint } from "./polar/polar.types";
+export { normalizeDegrees, polarToCartesian } from "./polar/polar-point";
+export { type ResolvePolarLayoutOptions, resolveInnerRadius, resolvePolarLayout } from "./polar/resolve-layout";
+export { type ResolveSlicesOptions, resolveSlices } from "./polar/resolve-slices";
+export { sliceIndexAt } from "./polar/slice-index-at";
+export { sliceOpacity } from "./polar/slice-opacity";
+export { type MakeScaleOptions, makeScale } from "./scale/make-scale";
+export { invertValue, scaleValue } from "./scale/scale";
+export type { DomainTuple, RangeTuple, ScaleDescriptor, ScaleType } from "./scale/scale.types";
+// shape — bars, scatter and candles, each on a fixed verb sequence
+export {
+	type BarPoint,
+	type BarRect,
+	type BarRectOptions,
+	barRects,
+	barsPathFromRects,
+	buildBarsPath,
+	resolveBaseline,
+} from "./shape/build-bars";
+export {
+	buildCandlePaths,
+	type Candle,
+	type CandlePathOptions,
+	type CandlePaths,
+	candlePoints,
+	candleSentiment,
+	SENTIMENTS,
+	type Sentiment,
+} from "./shape/build-candles";
+export { buildScatterPath, type ScatterPathOptions, type ScatterShape } from "./shape/build-scatter";
+export { type CornerRadii, KAPPA, rectPath } from "./shape/rect-path";
+export { type AxisGutterInput, resolveAxisGutters } from "./text/axis-gutters";
+export { type BarLabelAnchorOptions, type BarLabelPosition, barLabelAnchor } from "./text/bar-label";
+export {
+	categoricalTickFormat,
+	defaultTickFormat,
+	formatDateTick,
+	formatNumberTick,
+} from "./text/format-tick";
+export {
+	anchorX,
+	anchorY,
+	type LabelAlignment,
+	type LabelMetrics,
+	type LabelPosition,
+	labelHeight,
+} from "./text/label-anchor";
+export { type BuildTicksOptions, buildTicks } from "./ticks/build-ticks";
+export { linearTicks, logTicks } from "./ticks/linear-ticks";
+export type { ChartTick } from "./ticks/tick.types";
+export { DEFAULT_TICK_COUNT, downsampleTicks, normalizeTickCount } from "./ticks/tick-count";
+export { timeTicks } from "./ticks/time-ticks";
+export { asNumber, isPlottable } from "./util/as-number";
+export { clamp } from "./util/clamp";
+export { extent, unionExtents } from "./util/extent";
+export { readAt } from "./util/read-at";
+export { type Side, type SidedNumber, sidesOf, valueFromSidedNumber } from "./util/sided-number";

package/src/core/interaction/closest-index.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { closestIndex } from "./closest-index";
+
+const xs = [0, 10, 20, 30, 40];
+
+describe("closestIndex", () => {
+	test("finds an exact hit", () => {
+		expect(closestIndex(xs, 20)).toBe(2);
+	});
+
+	test("picks the nearer neighbour", () => {
+		expect(closestIndex(xs, 21)).toBe(2);
+		expect(closestIndex(xs, 29)).toBe(3);
+	});
+
+	test("clamps outside the range", () => {
+		expect(closestIndex(xs, -100)).toBe(0);
+		expect(closestIndex(xs, 1000)).toBe(4);
+	});
+
+	test("degenerates safely", () => {
+		expect(closestIndex([], 5)).toBe(-1);
+		expect(closestIndex([7], 1000)).toBe(0);
+	});
+
+	test("agrees with a linear scan over a large series", () => {
+		const many = Array.from({ length: 500 }, (_, index) => index * 3);
+		for (const probe of [0, 1, 2, 700, 748, 749.9, 1497]) {
+			let best = 0;
+			for (let index = 1; index < many.length; index += 1) {
+				if (Math.abs((many[index] as number) - probe) < Math.abs((many[best] as number) - probe)) best = index;
+			}
+			expect(closestIndex(many, probe)).toBe(best);
+		}
+	});
+});

package/src/core/interaction/closest-index.ts

@@ -0,0 +1,27 @@
+/**
+ * Index of the value in `xs` nearest to `x`.
+ *
+ * `xs` must ascend — a chart's x values do, because the scales are built from
+ * their extent and the data is plotted in order.
+ *
+ * Flat worklet: calls nothing, closes over nothing. It runs on every frame of
+ * a scrub, which is the reason it is a binary search and not a linear scan.
+ */
+export function closestIndex(xs: readonly number[], x: number): number {
+	"worklet";
+	const count = xs.length;
+	if (count === 0) return -1;
+	if (count === 1) return 0;
+
+	let lo = 0;
+	let hi = count - 1;
+	while (hi - lo > 1) {
+		const mid = (lo + hi) >> 1;
+		if ((xs[mid] as number) <= x) lo = mid;
+		else hi = mid;
+	}
+
+	const loDistance = Math.abs((xs[lo] as number) - x);
+	const hiDistance = Math.abs((xs[hi] as number) - x);
+	return hiDistance < loDistance ? hi : lo;
+}

package/src/core/interaction/path-segments.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+import type { ChartPoint } from "../chart.types";
+import { buildLinePath } from "../curve/build-line";
+import { RUN_STRIDE, runSegmentCount, toCurvePath } from "./path-segments";
+
+const at = (x: number, y: number | null): ChartPoint => ({ x, y, xValue: x, yValue: y });
+
+describe("toCurvePath", () => {
+	test("returns nothing for an empty path", () => {
+		expect(toCurvePath("")).toEqual([]);
+	});
+
+	test("normalises a straight line into a cubic on the same line", () => {
+		const path = toCurvePath("M0,0L30,30");
+		expect(path).toHaveLength(1);
+		// Control points at the third and two-third marks: still a straight line.
+		expect(path[0]).toEqual([0, 0, 10, 10, 20, 20, 30, 30]);
+	});
+
+	test("keeps a cubic's own control points", () => {
+		expect(toCurvePath("M0,0C1,2,3,4,5,6")[0]).toEqual([0, 0, 1, 2, 3, 4, 5, 6]);
+	});
+
+	test("gives every segment the same stride whatever the curve was", () => {
+		// The reason the solver needs no branch on verb.
+		const points = [at(0, 5), at(10, 8), at(20, 3), at(30, 9)];
+		for (const curve of ["linear", "monotone", "step", "natural"] as const) {
+			for (const run of toCurvePath(buildLinePath(points, { curve }))) {
+				expect((run.length - 2) % RUN_STRIDE).toBe(0);
+				expect(runSegmentCount(run)).toBeGreaterThan(0);
+			}
+		}
+	});
+
+	test("splits a gapped series into one run per unbroken stretch", () => {
+		const path = toCurvePath(buildLinePath([at(0, 1), at(10, 2), at(20, null), at(30, 4), at(40, 5)]));
+		expect(path).toHaveLength(2);
+		expect(path[0]?.[0]).toBe(0);
+		expect(path[1]?.[0]).toBe(30);
+	});
+
+	test("drops a single-point subpath, which has no segment to solve", () => {
+		expect(toCurvePath("M5,5Z")).toEqual([]);
+	});
+
+	test("handles implicit repeated coordinates after one command", () => {
+		expect(toCurvePath("M0,0L10,10L20,20")).toHaveLength(1);
+		expect(runSegmentCount(toCurvePath("M0,0L10,10L20,20")[0] as number[])).toBe(2);
+	});
+
+	test("reads scientific notation and negative numbers", () => {
+		const path = toCurvePath("M-1e1,-5L10,5");
+		expect(path[0]?.[0]).toBe(-10);
+		expect(path[0]?.[1]).toBe(-5);
+	});
+
+	test("ignores a verb it does not know rather than throwing", () => {
+		expect(() => toCurvePath("M0,0Q5,5,10,10L20,20")).not.toThrow();
+	});
+});

package/src/core/interaction/path-segments.ts

@@ -0,0 +1,155 @@
+/**
+ * One contiguous run of cubic segments.
+ *
+ * Flat numbers, `[x0,y0, c1x,c1y,c2x,c2y,x1,y1, c1x,c1y,c2x,c2y,x2,y2, …]` —
+ * two for the start point, then six per segment. Segment `i` starts where
+ * segment `i-1` ended, so the array is `2 + 6n` long.
+ *
+ * Flat because it crosses into a shared value and is read every frame of a
+ * scrub. Two hundred `{x, y}` objects is two hundred serialisations where a
+ * number array is one.
+ */
+export type CurveRun = readonly number[];
+
+/** A whole path: one run per subpath. A series with gaps has more than one. */
+export type CurvePath = readonly CurveRun[];
+
+/** Numbers per segment after the leading start point. */
+export const RUN_STRIDE = 6;
+
+/** How many cubic segments a run holds. */
+export function runSegmentCount(run: CurveRun): number {
+	return run.length < 2 + RUN_STRIDE ? 0 : (run.length - 2) / RUN_STRIDE;
+}
+
+/** Path verbs, their operands, and the pen position between them. */
+type Builder = {
+	readonly runs: number[][];
+	run: number[] | null;
+	x: number;
+	y: number;
+};
+
+const TOKEN = /([MLCZmlczHhVv])|(-?\d*\.?\d+(?:[eE][-+]?\d+)?)/g;
+const THIRD = 1 / 3;
+
+/** Appends a cubic, opening a run if the pen has just moved. */
+function cubicTo(builder: Builder, c1x: number, c1y: number, c2x: number, c2y: number, x: number, y: number): void {
+	if (builder.run === null) {
+		builder.run = [builder.x, builder.y];
+		builder.runs.push(builder.run);
+	}
+	builder.run.push(c1x, c1y, c2x, c2y, x, y);
+	builder.x = x;
+	builder.y = y;
+}
+
+/**
+ * Appends a straight segment **as a cubic**, control points at the third and
+ * two-third marks — the same line, in the one shape the solver understands.
+ */
+function lineTo(builder: Builder, x: number, y: number): void {
+	const dx = x - builder.x;
+	const dy = y - builder.y;
+	cubicTo(
+		builder,
+		builder.x + dx * THIRD,
+		builder.y + dy * THIRD,
+		builder.x + dx * 2 * THIRD,
+		builder.y + dy * 2 * THIRD,
+		x,
+		y
+	);
+}
+
+function moveTo(builder: Builder, values: readonly number[]): void {
+	if (values.length < 2) return;
+	builder.x = values[0] as number;
+	builder.y = values[1] as number;
+	builder.run = null;
+	for (let index = 2; index + 1 < values.length; index += 2) {
+		lineTo(builder, values[index] as number, values[index + 1] as number);
+	}
+}
+
+function curveTo(builder: Builder, values: readonly number[]): void {
+	for (let index = 0; index + 5 < values.length; index += RUN_STRIDE) {
+		cubicTo(
+			builder,
+			values[index] as number,
+			values[index + 1] as number,
+			values[index + 2] as number,
+			values[index + 3] as number,
+			values[index + 4] as number,
+			values[index + 5] as number
+		);
+	}
+}
+
+function applyVerb(builder: Builder, verb: string, values: readonly number[]): void {
+	switch (verb) {
+		case "M":
+			moveTo(builder, values);
+			return;
+		case "C":
+			curveTo(builder, values);
+			return;
+		case "L":
+			for (let index = 0; index + 1 < values.length; index += 2) {
+				lineTo(builder, values[index] as number, values[index + 1] as number);
+			}
+			return;
+		case "H":
+			for (const value of values) lineTo(builder, value, builder.y);
+			return;
+		case "V":
+			for (const value of values) lineTo(builder, builder.x, value);
+			return;
+		default:
+			return;
+	}
+}
+
+/**
+ * Re-encodes an SVG path string as runs of cubics.
+ *
+ * Two jobs, and the second is the interesting one.
+ *
+ * It **normalises every segment to a cubic**, so the scrub solver has exactly
+ * one segment kind to handle however the curve was drawn — no branch on verb,
+ * no second code path to get wrong. d3 emits `L` for a linear curve and `C`
+ * for a monotone one; downstream, they are indistinguishable.
+ *
+ * And it **splits on subpath**, so a series broken by a gap yields one run per
+ * unbroken stretch and the solver reports no value inside the gap rather than
+ * interpolating a line nobody measured.
+ *
+ * Only the verbs d3's `line` and `area` emit are handled — `M`, `L`, `C`, `Z`,
+ * plus `H`/`V` defensively. Anything else is ignored rather than throwing: a
+ * path this cannot fully read should cost a scrub, not the whole chart.
+ */
+export function toCurvePath(path: string): CurvePath {
+	if (path === "") return [];
+
+	const builder: Builder = { runs: [], run: null, x: 0, y: 0 };
+	let verb = "";
+	let operands: number[] = [];
+
+	TOKEN.lastIndex = 0;
+	for (let match = TOKEN.exec(path); match !== null; match = TOKEN.exec(path)) {
+		if (match[1] === undefined) {
+			operands.push(Number(match[2]));
+			continue;
+		}
+		if (verb !== "") applyVerb(builder, verb, operands);
+		operands = [];
+		verb = match[1].toUpperCase();
+		if (verb === "Z") {
+			verb = "";
+			builder.run = null;
+		}
+	}
+	if (verb !== "") applyVerb(builder, verb, operands);
+
+	return builder.runs.filter((run) => run.length >= 2 + RUN_STRIDE);
+}

package/src/core/interaction/y-for-x.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, test } from "bun:test";
+import type { ChartPoint } from "../chart.types";
+import { buildLinePath } from "../curve/build-line";
+import { toCurvePath } from "./path-segments";
+import { getYForX } from "./y-for-x";
+
+const at = (x: number, y: number | null): ChartPoint => ({ x, y, xValue: x, yValue: y });
+
+/**
+ * The analytic cubic root, as an oracle.
+ *
+ * This is the implementation `getYForX` deliberately does not ship — it is
+ * three functions calling each other, which the flat-worklet rule forbids. It
+ * lives here so bisection has something exact to be checked against.
+ */
+function cuberoot(x: number): number {
+	const y = Math.abs(x) ** (1 / 3);
+	return x < 0 ? -y : y;
+}
+
+function solveCubic(a: number, b: number, c: number, d: number): number[] {
+	if (Math.abs(a) < 1e-8) {
+		if (Math.abs(b) < 1e-8) return Math.abs(c) < 1e-8 ? [] : [-d / c];
+		const disc = c * c - 4 * b * d;
+		if (disc < 0) return [];
+		return [(-c + Math.sqrt(disc)) / (2 * b), (-c - Math.sqrt(disc)) / (2 * b)];
+	}
+	const p = (3 * a * c - b * b) / (3 * a * a);
+	const q = (2 * b * b * b - 9 * a * b * c + 27 * a * a * d) / (27 * a * a * a);
+	let roots: number[];
+	if (Math.abs(p) < 1e-12) roots = [cuberoot(-q)];
+	else if (Math.abs(q) < 1e-12) roots = p < 0 ? [0, Math.sqrt(-p), -Math.sqrt(-p)] : [0];
+	else {
+		const disc = (q * q) / 4 + (p * p * p) / 27;
+		if (Math.abs(disc) < 1e-12) roots = [(-1.5 * q) / p, (3 * q) / p];
+		else if (disc > 0) {
+			const u = cuberoot(-q / 2 - Math.sqrt(disc));
+			roots = [u - p / (3 * u)];
+		} else {
+			const u = 2 * Math.sqrt(-p / 3);
+			const t = Math.acos(((3 * q) / p / u) * 1) / 3;
+			const k = (2 * Math.PI) / 3;
+			roots = [u * Math.cos(t), u * Math.cos(t - k), u * Math.cos(t - 2 * k)];
+		}
+	}
+	return roots.map((root) => root - b / (3 * a));
+}
+
+function bezier(p0: number, c1: number, c2: number, p1: number, t: number): number {
+	const mt = 1 - t;
+	return mt * mt * mt * p0 + 3 * mt * mt * t * c1 + 3 * mt * t * t * c2 + t * t * t * p1;
+}
+
+/** `y` at `x` on one cubic, solved exactly. */
+function oracleY(run: readonly number[], x: number): number {
+	const [p0x, p0y, c1x, c1y, c2x, c2y, p1x, p1y] = run as number[];
+	const a = -(p0x as number) + 3 * (c1x as number) - 3 * (c2x as number) + (p1x as number);
+	const b = 3 * (p0x as number) - 6 * (c1x as number) + 3 * (c2x as number);
+	const c = -3 * (p0x as number) + 3 * (c1x as number);
+	const d = (p0x as number) - x;
+	for (const root of solveCubic(a, b, c, d)) {
+		if (root >= -1e-9 && root <= 1 + 1e-9) {
+			return bezier(p0y as number, c1y as number, c2y as number, p1y as number, Math.min(1, Math.max(0, root)));
+		}
+	}
+	return Number.NaN;
+}
+
+describe("getYForX", () => {
+	test("rides a straight line exactly", () => {
+		const path = toCurvePath(buildLinePath([at(0, 0), at(100, 100)]));
+		expect(getYForX(path, 25)).toBeCloseTo(25, 6);
+		expect(getYForX(path, 73.5)).toBeCloseTo(73.5, 6);
+	});
+
+	test("passes through every data point on an interpolating curve", () => {
+		const points = [at(0, 40), at(50, 10), at(100, 90), at(150, 30)];
+		const path = toCurvePath(buildLinePath(points, { curve: "monotone" }));
+		for (const point of points) {
+			expect(getYForX(path, point.x)).toBeCloseTo(point.y as number, 6);
+		}
+	});
+
+	test("clamps to the ends outside the path", () => {
+		const path = toCurvePath(buildLinePath([at(10, 5), at(90, 45)]));
+		expect(getYForX(path, -50)).toBe(5);
+		expect(getYForX(path, 500)).toBe(45);
+	});
+
+	test("returns NaN inside a gap so the caller can fall back to a datum", () => {
+		const path = toCurvePath(buildLinePath([at(0, 1), at(10, 2), at(20, null), at(30, 4), at(40, 5)]));
+		expect(getYForX(path, 20)).toBeNaN();
+		expect(Number.isFinite(getYForX(path, 5))).toBe(true);
+		expect(Number.isFinite(getYForX(path, 35))).toBe(true);
+	});
+
+	test("degenerates safely", () => {
+		expect(getYForX([], 5)).toBeNaN();
+		expect(getYForX(toCurvePath(buildLinePath([at(0, 1)])), 0)).toBeNaN();
+		expect(getYForX(toCurvePath(buildLinePath([at(0, 0), at(10, 10)])), Number.NaN)).toBeNaN();
+	});
+
+	test("resolves a vertical step segment to the value after the step", () => {
+		const path = toCurvePath(buildLinePath([at(0, 0), at(10, 100)], { curve: "stepBefore" }));
+		expect(Number.isFinite(getYForX(path, 0))).toBe(true);
+		expect(getYForX(path, 10)).toBeCloseTo(100, 6);
+	});
+
+	test("agrees with the analytic solver across a thousand random curves", () => {
+		let checked = 0;
+		let seed = 20260902;
+		const random = (): number => {
+			seed = (seed * 1103515245 + 12345) % 2147483648;
+			return seed / 2147483648;
+		};
+
+		for (let trial = 0; trial < 1000; trial += 1) {
+			const points = Array.from({ length: 5 }, (_, index) => at(index * 40, random() * 200));
+			const path = toCurvePath(buildLinePath(points, { curve: "monotone" }));
+			const x = random() * 160;
+			const actual = getYForX(path, x);
+			if (!Number.isFinite(actual)) continue;
+
+			const run = path[0] as readonly number[];
+			const segment = Math.min(Math.floor(x / 40), (run.length - 2) / 6 - 1);
+			const expected = oracleY(run.slice(segment * 6, segment * 6 + 8), x);
+			if (!Number.isFinite(expected)) continue;
+
+			expect(actual).toBeCloseTo(expected, 6);
+			checked += 1;
+		}
+
+		expect(checked).toBeGreaterThan(800);
+	});
+});