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

package/src/core/polar/resolve-layout.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import type { InnerRadius } from "./polar.types";
+import { resolveInnerRadius, resolvePolarLayout } from "./resolve-layout";
+
+describe("resolvePolarLayout", () => {
+	test("fits the largest circle the canvas holds, centred", () => {
+		const layout = resolvePolarLayout({ canvas: { width: 300, height: 200 } });
+		expect(layout.center).toEqual({ x: 150, y: 100 });
+		expect(layout.radius).toBe(100);
+		expect(layout.innerRadius).toBe(0);
+	});
+
+	test("padding shrinks the circle and moves the centre", () => {
+		const layout = resolvePolarLayout({ canvas: { width: 300, height: 200 }, padding: { left: 100 } });
+		expect(layout.center).toEqual({ x: 200, y: 100 });
+		expect(layout.radius).toBe(100);
+	});
+
+	test("an explicit size caps the diameter but never exceeds the canvas", () => {
+		expect(resolvePolarLayout({ canvas: { width: 300, height: 200 }, size: 100 }).radius).toBe(50);
+		expect(resolvePolarLayout({ canvas: { width: 300, height: 200 }, size: 1000 }).radius).toBe(100);
+	});
+
+	test("resolves the inner radius against the outer one", () => {
+		expect(resolvePolarLayout({ canvas: { width: 200, height: 200 }, innerRadius: "50%" }).innerRadius).toBe(50);
+		expect(resolvePolarLayout({ canvas: { width: 200, height: 200 }, innerRadius: 30 }).innerRadius).toBe(30);
+	});
+
+	test("a zero or over-padded canvas yields a zero radius rather than a negative one", () => {
+		expect(resolvePolarLayout({ canvas: { width: 0, height: 0 } }).radius).toBe(0);
+		expect(resolvePolarLayout({ canvas: { width: 50, height: 50 }, padding: 40 }).radius).toBe(0);
+	});
+});
+
+describe("resolveInnerRadius", () => {
+	test("a number is taken as points", () => {
+		expect(resolveInnerRadius(40, 100)).toBe(40);
+	});
+
+	test("a percentage is of the outer radius", () => {
+		expect(resolveInnerRadius("60%", 100)).toBe(60);
+	});
+
+	test("clamps into [0, radius)", () => {
+		expect(resolveInnerRadius(-5, 100)).toBe(0);
+		expect(resolveInnerRadius(150, 100)).toBeLessThan(100);
+		expect(resolveInnerRadius(150, 100)).toBeGreaterThanOrEqual(0);
+		expect(resolveInnerRadius("120%", 100)).toBeLessThan(100);
+	});
+
+	test("an unreadable percentage is 0", () => {
+		expect(resolveInnerRadius("abc%" as unknown as InnerRadius, 100)).toBe(0);
+		expect(resolveInnerRadius(Number.NaN, 100)).toBe(0);
+	});
+
+	test("undefined is 0, which is a pie rather than a donut", () => {
+		expect(resolveInnerRadius(undefined, 100)).toBe(0);
+	});
+
+	test("a zero outer radius gives a zero inner one", () => {
+		expect(resolveInnerRadius("50%", 0)).toBe(0);
+	});
+});

package/src/core/polar/resolve-layout.ts

@@ -0,0 +1,55 @@
+import type { ChartSize } from "../chart.types";
+import { type SidedNumber, sidesOf } from "../util/sided-number";
+import type { InnerRadius, PolarLayout } from "./polar.types";
+
+export type ResolvePolarLayoutOptions = {
+	readonly canvas: ChartSize;
+	/** Space between the canvas edge and the circle. */
+	readonly padding?: SidedNumber;
+	/** An explicit diameter, in points. Never larger than the padded canvas. */
+	readonly size?: number;
+	readonly innerRadius?: InnerRadius;
+};
+
+/**
+ * The largest circle the padded canvas holds, centred in it.
+ *
+ * The radius is never negative: a canvas smaller than its padding — the first
+ * layout pass, before anything has been measured — gives a zero radius, and a
+ * zero radius draws nothing rather than an inverted slice.
+ */
+export function resolvePolarLayout(options: ResolvePolarLayoutOptions): PolarLayout {
+	const { canvas, padding, size, innerRadius } = options;
+	const sides = sidesOf(padding);
+	const width = Math.max(0, canvas.width - sides.left - sides.right);
+	const height = Math.max(0, canvas.height - sides.top - sides.bottom);
+	const fit = Math.min(width, height) / 2;
+	const radius = size !== undefined && Number.isFinite(size) ? Math.max(0, Math.min(fit, size / 2)) : fit;
+	return {
+		center: { x: sides.left + width / 2, y: sides.top + height / 2 },
+		radius,
+		innerRadius: resolveInnerRadius(innerRadius, radius),
+	};
+}
+
+/**
+ * The hole's radius in points, held inside `[0, radius)`.
+ *
+ * A hole as large as the circle would leave a ring of zero width, which draws
+ * nothing and cannot be tapped, so the clamp stops one point short of it. An
+ * unreadable value — `"abc%"`, `NaN` — is no hole, because a pie is the more
+ * reasonable thing to draw than nothing.
+ */
+export function resolveInnerRadius(spec: InnerRadius | undefined, radius: number): number {
+	if (radius <= 0) return 0;
+	const requested = typeof spec === "number" ? spec : parsePercent(spec) * radius;
+	if (!Number.isFinite(requested) || requested <= 0) return 0;
+	return Math.min(requested, Math.max(0, radius - 1));
+}
+
+/** `"60%"` as `0.6`; `0` for anything that is not a percentage. */
+function parsePercent(spec: `${number}%` | undefined): number {
+	if (spec === undefined) return 0;
+	const parsed = Number(spec.slice(0, -1));
+	return Number.isFinite(parsed) ? parsed / 100 : 0;
+}

package/src/core/polar/resolve-slices.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import type { PolarLayout } from "./polar.types";
+import { resolveSlices } from "./resolve-slices";
+
+const layout: PolarLayout = { center: { x: 100, y: 100 }, radius: 80, innerRadius: 20 };
+
+function sweeps(values: readonly number[], options: { startAngle?: number; circleSweepDegrees?: number } = {}) {
+	return resolveSlices({ values, labels: values.map(String), layout, ...options }).map((slice) => slice.sweepAngle);
+}
+
+describe("resolveSlices", () => {
+	test("splits the circle in proportion, starting at 0°", () => {
+		const slices = resolveSlices({ values: [1, 1, 2], labels: ["a", "b", "c"], layout });
+		expect(slices.map((slice) => slice.fraction)).toEqual([0.25, 0.25, 0.5]);
+		expect(slices.map((slice) => slice.startAngle)).toEqual([0, 90, 180]);
+		expect(slices.map((slice) => slice.endAngle)).toEqual([90, 180, 360]);
+	});
+
+	test("carries the layout, label, value and index on every slice", () => {
+		const [slice] = resolveSlices({ values: [3], labels: ["only"], layout });
+		expect(slice).toMatchObject({
+			index: 0,
+			label: "only",
+			value: 3,
+			center: layout.center,
+			radius: 80,
+			innerRadius: 20,
+		});
+	});
+
+	test("a negative or non-finite value gets a zero sweep but keeps its index", () => {
+		const slices = resolveSlices({ values: [1, -1, Number.NaN, 1], labels: ["a", "b", "c", "d"], layout });
+		expect(slices.map((slice) => slice.index)).toEqual([0, 1, 2, 3]);
+		expect(slices.map((slice) => slice.sweepAngle)).toEqual([180, 0, 0, 180]);
+		expect(slices[1]?.startAngle).toBe(180);
+		expect(slices[2]?.startAngle).toBe(180);
+	});
+
+	test("a zero total gives every slice a zero sweep and no NaN", () => {
+		const slices = resolveSlices({ values: [0, 0], labels: ["a", "b"], layout });
+		for (const slice of slices) {
+			expect(slice.sweepAngle).toBe(0);
+			expect(slice.fraction).toBe(0);
+			expect(Number.isFinite(slice.startAngle)).toBe(true);
+		}
+	});
+
+	test("sweeps sum to the circle exactly, with the last slice absorbing drift", () => {
+		const values = [1, 1, 1, 1, 1, 1, 1];
+		const total = sweeps(values).reduce((sum, sweep) => sum + sweep, 0);
+		expect(total).toBe(360);
+	});
+
+	test("a trailing zero slice stays zero when drift is absorbed", () => {
+		const result = sweeps([1, 1, 1, 0]);
+		expect(result[3]).toBe(0);
+		expect(result.reduce((sum, sweep) => sum + sweep, 0)).toBe(360);
+	});
+
+	test("honours a start angle and a partial circle", () => {
+		const slices = resolveSlices({
+			values: [1, 1],
+			labels: ["a", "b"],
+			layout,
+			startAngle: -90,
+			circleSweepDegrees: 180,
+		});
+		expect(slices.map((slice) => slice.startAngle)).toEqual([-90, 0]);
+		expect(slices.map((slice) => slice.sweepAngle)).toEqual([90, 90]);
+	});
+
+	test("flags the one slice that is the whole circle", () => {
+		const [whole] = resolveSlices({ values: [5, 0], labels: ["a", "b"], layout });
+		expect(whole?.sliceIsEntireCircle).toBe(true);
+		const [half] = resolveSlices({ values: [5], labels: ["a"], layout, circleSweepDegrees: 180 });
+		expect(half?.sliceIsEntireCircle).toBe(false);
+		const [part] = resolveSlices({ values: [5, 5], labels: ["a", "b"], layout });
+		expect(part?.sliceIsEntireCircle).toBe(false);
+	});
+
+	test("a missing label falls back to the index", () => {
+		const [slice] = resolveSlices({ values: [1], labels: [], layout });
+		expect(slice?.label).toBe("0");
+	});
+
+	test("no values gives no slices", () => {
+		expect(resolveSlices({ values: [], labels: [], layout })).toEqual([]);
+	});
+});

package/src/core/polar/resolve-slices.ts

@@ -0,0 +1,58 @@
+import type { PieSliceData, PolarLayout } from "./polar.types";
+
+export type ResolveSlicesOptions = {
+	readonly values: readonly number[];
+	readonly labels: readonly string[];
+	readonly layout: PolarLayout;
+	/** Where the first slice begins. Degrees clockwise from 12 o'clock. */
+	readonly startAngle?: number;
+	/** How much of the circle the slices fill. 180 is a half-pie gauge. */
+	readonly circleSweepDegrees?: number;
+};
+
+/**
+ * Every value as a slice of the circle.
+ *
+ * A negative or unreadable value gets a **zero sweep and keeps its index**.
+ * Dropping it would move every later slice one place, and a legend built from
+ * the same rows would then colour the wrong slice.
+ *
+ * The sweeps sum to the circle exactly: the last slice with any sweep absorbs
+ * the floating-point drift of the others. Without that, seven equal slices end
+ * a hair short of 360° and a hairline of background shows through at the seam.
+ */
+export function resolveSlices(options: ResolveSlicesOptions): PieSliceData[] {
+	const { values, labels, layout, startAngle = 0, circleSweepDegrees = 360 } = options;
+	const clean = values.map((value) => (Number.isFinite(value) && value > 0 ? value : 0));
+	const total = clean.reduce((sum, value) => sum + value, 0);
+	const circle = Number.isFinite(circleSweepDegrees) ? circleSweepDegrees : 360;
+	const origin = Number.isFinite(startAngle) ? startAngle : 0;
+
+	const sweeps = clean.map((value) => (total > 0 ? (value / total) * circle : 0));
+	const last = clean.reduce((found, value, index) => (value > 0 ? index : found), -1);
+	if (last >= 0) {
+		const others = sweeps.reduce((sum, sweep, index) => (index === last ? sum : sum + sweep), 0);
+		sweeps[last] = circle - others;
+	}
+
+	let cursor = origin;
+	return clean.map((value, index) => {
+		const sweepAngle = sweeps[index] as number;
+		const start = cursor;
+		cursor += sweepAngle;
+		const fraction = total > 0 ? value / total : 0;
+		return {
+			index,
+			label: labels[index] ?? String(index),
+			value,
+			fraction,
+			startAngle: start,
+			endAngle: start + sweepAngle,
+			sweepAngle,
+			center: layout.center,
+			radius: layout.radius,
+			innerRadius: layout.innerRadius,
+			sliceIsEntireCircle: circle === 360 && fraction === 1,
+		};
+	});
+}

package/src/core/polar/slice-index-at.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from "bun:test";
+import { sliceIndexAt } from "./slice-index-at";
+
+// Three quarters and a zero-sweep slice: 0–90, 90–180, 180–180, 180–360.
+const starts = [0, 90, 180, 180];
+const sweeps = [90, 90, 0, 180];
+
+function hit(x: number, y: number, innerRadius = 0): number {
+	return sliceIndexAt(x, y, 100, 100, innerRadius, 80, starts, sweeps);
+}
+
+describe("sliceIndexAt", () => {
+	test("finds the slice under a point", () => {
+		expect(hit(130, 70)).toBe(0);
+		expect(hit(130, 130)).toBe(1);
+		expect(hit(70, 130)).toBe(3);
+		expect(hit(70, 70)).toBe(3);
+	});
+
+	test("outside the radius is nothing", () => {
+		expect(hit(200, 100)).toBe(-1);
+	});
+
+	test("inside the hole is nothing", () => {
+		expect(hit(110, 100, 40)).toBe(-1);
+		expect(hit(150, 100, 40)).toBe(1);
+	});
+
+	test("a zero-sweep slice is never hit", () => {
+		expect(hit(100, 150)).toBe(3);
+	});
+
+	test("wraps a slice that crosses 360°", () => {
+		// One slice from 300° through 0° to 60°.
+		expect(sliceIndexAt(100, 50, 100, 100, 0, 80, [300], [120])).toBe(0);
+		expect(sliceIndexAt(150, 100, 100, 100, 0, 80, [300], [120])).toBe(-1);
+	});
+
+	test("accepts start angles outside [0, 360)", () => {
+		expect(sliceIndexAt(130, 70, 100, 100, 0, 80, [-360], [90])).toBe(0);
+		expect(sliceIndexAt(130, 70, 100, 100, 0, 80, [720], [90])).toBe(0);
+	});
+
+	test("a full-circle slice takes every point", () => {
+		expect(sliceIndexAt(100, 50, 100, 100, 0, 80, [0], [360])).toBe(0);
+		expect(sliceIndexAt(60, 140, 100, 100, 0, 80, [0], [360])).toBe(0);
+	});
+
+	test("no slices is nothing", () => {
+		expect(sliceIndexAt(100, 100, 100, 100, 0, 80, [], [])).toBe(-1);
+	});
+});

package/src/core/polar/slice-index-at.ts

@@ -0,0 +1,42 @@
+/**
+ * Which slice is under a canvas point, or `-1`.
+ *
+ * Flat worklet: it calls nothing, so it may run on the UI thread from a gesture
+ * callback. The angle maths is inlined rather than shared with
+ * `polar-point.ts` for that reason — see the package AGENTS.md on why a
+ * module-scope worklet must not call another function.
+ *
+ * A slice owns its start angle and not its end, so a point exactly on a
+ * boundary belongs to the later slice. A slice with no sweep owns nothing.
+ */
+export function sliceIndexAt(
+	x: number,
+	y: number,
+	centerX: number,
+	centerY: number,
+	innerRadius: number,
+	radius: number,
+	startAngles: readonly number[],
+	sweepAngles: readonly number[]
+): number {
+	"worklet";
+	const dx = x - centerX;
+	const dy = y - centerY;
+	const distance = Math.sqrt(dx * dx + dy * dy);
+	if (distance > radius || distance < innerRadius) return -1;
+
+	// Degrees clockwise from 12 o'clock — the same convention the slices use.
+	let angle = (Math.atan2(dx, -dy) * 180) / Math.PI;
+	angle = ((angle % 360) + 360) % 360;
+
+	for (let index = 0; index < startAngles.length; index += 1) {
+		const sweep = sweepAngles[index] ?? 0;
+		if (!(sweep > 0)) continue;
+		const start = (((startAngles[index] ?? 0) % 360) + 360) % 360;
+		let relative = angle - start;
+		if (relative < 0) relative += 360;
+		if (relative < sweep) return index;
+	}
+
+	return -1;
+}

package/src/core/polar/slice-opacity.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, test } from "bun:test";
+import { sliceOpacity } from "./slice-opacity";
+
+describe("sliceOpacity", () => {
+	test("every slice is at full opacity with nothing selected", () => {
+		expect(sliceOpacity(0, null, 1, 0.4)).toBe(1);
+		expect(sliceOpacity(3, null, 0.8, 0.4)).toBe(0.8);
+	});
+
+	test("the selected slice keeps its opacity", () => {
+		expect(sliceOpacity(0, 0, 1, 0.4)).toBe(1);
+		expect(sliceOpacity(2, 2, 0.5, 0.4)).toBe(0.5);
+	});
+
+	test("every other slice dims by the factor", () => {
+		expect(sliceOpacity(1, 0, 1, 0.4)).toBeCloseTo(0.4);
+		expect(sliceOpacity(0, 1, 0.5, 0.4)).toBeCloseTo(0.2);
+	});
+
+	test("a dim of one leaves the others alone", () => {
+		expect(sliceOpacity(1, 0, 1, 1)).toBe(1);
+	});
+
+	// Index zero is a real slice, not a falsy "nothing selected".
+	test("selecting the first slice dims the rest, not the first", () => {
+		expect(sliceOpacity(0, 0, 1, 0.4)).toBe(1);
+		expect(sliceOpacity(1, 0, 1, 0.4)).toBeCloseTo(0.4);
+	});
+});

package/src/core/polar/slice-opacity.ts

@@ -0,0 +1,12 @@
+/**
+ * The opacity one slice draws at, given which slice is selected.
+ *
+ * With no selection every slice draws at `opacity`. With one, the selected
+ * slice keeps `opacity` and every other slice draws at `opacity × dim` — a
+ * selection that changed nothing on screen would look like a tap that missed.
+ * `dim` of `1` turns the effect off without needing a second code path.
+ */
+export function sliceOpacity(index: number, selectedIndex: number | null, opacity: number, dim: number): number {
+	if (selectedIndex === null || selectedIndex === index) return opacity;
+	return opacity * dim;
+}

package/src/core/scale/make-scale.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from "bun:test";
+import { makeScale } from "./make-scale";
+import { scaleValue } from "./scale";
+
+describe("makeScale", () => {
+	test("keeps the domain it was given when nicing is off", () => {
+		const scale = makeScale({ kind: "linear", domain: [3, 97], range: [0, 300] });
+		expect(scale.domain).toEqual([3, 97]);
+		expect(scale.range).toEqual([0, 300]);
+	});
+
+	test("rounds the domain out to tick values when nicing is on", () => {
+		const scale = makeScale({ kind: "linear", domain: [3, 97], range: [0, 300], nice: true });
+		expect(scale.domain[0]).toBeLessThanOrEqual(3);
+		expect(scale.domain[1]).toBeGreaterThanOrEqual(97);
+		expect(scale.domain).toEqual([0, 100]);
+	});
+
+	test("honours a requested tick count when nicing", () => {
+		const scale = makeScale({ kind: "linear", domain: [0.7, 9.3], range: [0, 300], nice: 2 });
+		expect(scale.domain[0]).toBeLessThanOrEqual(0.7);
+		expect(scale.domain[1]).toBeGreaterThanOrEqual(9.3);
+	});
+
+	test("returns a descriptor holding numbers only, so a worklet can read it", () => {
+		const scale = makeScale({ kind: "time", domain: [0, 86_400_000], range: [0, 240] });
+		expect(JSON.parse(JSON.stringify(scale))).toEqual(scale as unknown as Record<string, unknown>);
+		for (const bound of [...scale.domain, ...scale.range]) expect(typeof bound).toBe("number");
+	});
+
+	test("nices a time domain onto a calendar boundary", () => {
+		const start = Date.UTC(2026, 0, 1, 4, 37);
+		const end = Date.UTC(2026, 0, 3, 19, 12);
+		const scale = makeScale({ kind: "time", domain: [start, end], range: [0, 300], nice: true });
+		expect(scale.domain[0]).toBeLessThanOrEqual(start);
+		expect(scale.domain[1]).toBeGreaterThanOrEqual(end);
+	});
+
+	test("carries the log base through", () => {
+		const scale = makeScale({ kind: "log", domain: [1, 1024], range: [0, 300], base: 2 });
+		expect(scale.kind === "log" && scale.base).toBe(2);
+	});
+
+	test("floors a log domain above zero rather than emitting -Infinity", () => {
+		const scale = makeScale({ kind: "log", domain: [0, 100], range: [0, 300] });
+		expect(scale.domain[0]).toBeGreaterThan(0);
+		expect(Number.isFinite(scaleValue(scale, 50))).toBe(true);
+	});
+
+	test("substitutes zero for a non-finite bound rather than poisoning every point", () => {
+		const scale = makeScale({ kind: "linear", domain: [Number.NaN, 100], range: [0, 300] });
+		expect(Number.isFinite(scale.domain[0])).toBe(true);
+		expect(Number.isFinite(scaleValue(scale, 50))).toBe(true);
+	});
+});

package/src/core/scale/make-scale.ts

@@ -0,0 +1,78 @@
+import { scaleLinear, scaleLog, scaleTime } from "d3-scale";
+import type { DomainTuple, RangeTuple, ScaleDescriptor, ScaleType } from "./scale.types";
+
+/** The smallest domain a log scale can take; d3 produces garbage at or below zero. */
+const LOG_FLOOR = 1e-9;
+
+export type MakeScaleOptions = {
+	readonly kind: ScaleType;
+	readonly domain: DomainTuple;
+	readonly range: RangeTuple;
+	/**
+	 * Round the domain out to values a tick would land on. `true` uses the
+	 * default tick count; a number asks for that many.
+	 */
+	readonly nice?: boolean | number;
+	/** Log base. Ignored by every other kind. */
+	readonly base?: number;
+};
+
+/**
+ * Builds a scale and returns only its descriptor.
+ *
+ * d3 does the work that is genuinely hard — `.nice()` rounding a domain out to
+ * human numbers, and `scaleTime` understanding that a DST day is 23 hours —
+ * and then we throw the closure away and keep the numbers. Nothing downstream
+ * ever holds a d3 scale, which is what keeps the UI thread able to read one.
+ */
+export function makeScale(options: MakeScaleOptions): ScaleDescriptor {
+	const { kind, range } = options;
+	const domain = normaliseDomain(options.domain, kind);
+
+	const nice = options.nice;
+
+	switch (kind) {
+		case "linear": {
+			const scale = scaleLinear().domain([domain[0], domain[1]]).range([range[0], range[1]]);
+			applyNice(scale, nice);
+			const nicened = scale.domain();
+			return { kind: "linear", domain: [nicened[0] as number, nicened[1] as number], range };
+		}
+		case "time": {
+			const scale = scaleTime()
+				.domain([new Date(domain[0]), new Date(domain[1])])
+				.range([range[0], range[1]]);
+			applyNice(scale, nice);
+			const nicened = scale.domain();
+			return { kind: "time", domain: [nicened[0].getTime(), nicened[1].getTime()], range };
+		}
+		case "log": {
+			const base = options.base ?? 10;
+			const scale = scaleLog().base(base).domain([domain[0], domain[1]]).range([range[0], range[1]]);
+			applyNice(scale, nice);
+			const nicened = scale.domain();
+			return { kind: "log", domain: [nicened[0] as number, nicened[1] as number], range, base };
+		}
+	}
+}
+
+/** Rounds a scale's domain out in place, when the caller asked for it. */
+function applyNice(scale: { nice: (count?: number) => unknown }, nice: boolean | number | undefined): void {
+	if (nice === undefined || nice === false) return;
+	scale.nice(nice === true ? undefined : nice);
+}
+
+/**
+ * A domain d3 will not choke on.
+ *
+ * Two guards. A non-finite bound becomes zero, because a `NaN` domain produces
+ * a `NaN` position for every point and an empty canvas with nothing logged. A
+ * log domain is floored above zero, because `scaleLog` with a zero or negative
+ * bound returns `-Infinity` for the whole range.
+ */
+function normaliseDomain(domain: DomainTuple, kind: ScaleType): DomainTuple {
+	const lo = Number.isFinite(domain[0]) ? domain[0] : 0;
+	const hi = Number.isFinite(domain[1]) ? domain[1] : 0;
+	if (kind !== "log") return [lo, hi];
+	return [Math.max(lo, LOG_FLOOR), Math.max(hi, LOG_FLOOR * 10)];
+}

package/src/core/scale/scale.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from "bun:test";
+import { invertValue, scaleValue } from "./scale";
+import type { ScaleDescriptor } from "./scale.types";
+
+const linear: ScaleDescriptor = { kind: "linear", domain: [0, 100], range: [0, 300] };
+const flipped: ScaleDescriptor = { kind: "linear", domain: [0, 100], range: [300, 0] };
+const log: ScaleDescriptor = { kind: "log", domain: [1, 1000], range: [0, 300], base: 10 };
+
+describe("scaleValue", () => {
+	test("maps the domain onto the range", () => {
+		expect(scaleValue(linear, 0)).toBe(0);
+		expect(scaleValue(linear, 50)).toBe(150);
+		expect(scaleValue(linear, 100)).toBe(300);
+	});
+
+	test("handles an inverted range, which is what a y axis is", () => {
+		expect(scaleValue(flipped, 0)).toBe(300);
+		expect(scaleValue(flipped, 100)).toBe(0);
+	});
+
+	test("extrapolates outside the domain rather than clamping", () => {
+		// Clamping here would silently flatten an out-of-viewport point onto the
+		// axis. Clipping is the renderer's job, not the scale's.
+		expect(scaleValue(linear, 150)).toBe(450);
+		expect(scaleValue(linear, -50)).toBe(-150);
+	});
+
+	test("returns the range midpoint for a zero-width domain", () => {
+		const point: ScaleDescriptor = { kind: "linear", domain: [7, 7], range: [0, 300] };
+		expect(scaleValue(point, 7)).toBe(150);
+		expect(scaleValue(point, 999)).toBe(150);
+	});
+
+	test("places log decades evenly", () => {
+		expect(scaleValue(log, 1)).toBeCloseTo(0, 9);
+		expect(scaleValue(log, 10)).toBeCloseTo(100, 9);
+		expect(scaleValue(log, 100)).toBeCloseTo(200, 9);
+		expect(scaleValue(log, 1000)).toBeCloseTo(300, 9);
+	});
+
+	test("never returns NaN for a non-positive value on a log scale", () => {
+		expect(Number.isFinite(scaleValue(log, 0))).toBe(true);
+		expect(Number.isFinite(scaleValue(log, -5))).toBe(true);
+	});
+
+	test("returns the midpoint for a log scale whose domain reaches zero", () => {
+		const broken: ScaleDescriptor = { kind: "log", domain: [0, 100], range: [0, 300], base: 10 };
+		expect(scaleValue(broken, 10)).toBe(150);
+	});
+
+	test("reads a time domain as epoch milliseconds", () => {
+		const day = 86_400_000;
+		const time: ScaleDescriptor = { kind: "time", domain: [0, day], range: [0, 240] };
+		expect(scaleValue(time, day / 2)).toBe(120);
+	});
+});
+
+describe("invertValue", () => {
+	test("round-trips every kind", () => {
+		for (const scale of [linear, flipped, log]) {
+			for (const value of [1, 2, 17, 99]) {
+				expect(invertValue(scale, scaleValue(scale, value))).toBeCloseTo(value, 6);
+			}
+		}
+	});
+
+	test("returns the domain start for a zero-width range", () => {
+		const collapsed: ScaleDescriptor = { kind: "linear", domain: [4, 9], range: [12, 12] };
+		expect(invertValue(collapsed, 12)).toBe(4);
+	});
+
+	test("stays finite on a log scale whose domain reaches zero", () => {
+		const broken: ScaleDescriptor = { kind: "log", domain: [0, 100], range: [0, 300], base: 10 };
+		expect(Number.isFinite(invertValue(broken, 150))).toBe(true);
+	});
+});

package/src/core/scale/scale.ts

@@ -0,0 +1,65 @@
+import type { ScaleDescriptor } from "./scale.types";
+
+/**
+ * A domain value's position along the range.
+ *
+ * Flat worklet: it calls nothing and closes over nothing, so a gesture
+ * callback can reference it directly. See the package AGENTS.md.
+ *
+ * A zero-width domain returns the range midpoint rather than dividing by zero.
+ * That case is real — a single datum, or a series that is one repeated value —
+ * and one `NaN` written into a shared value freezes a chart permanently.
+ */
+export function scaleValue(scale: ScaleDescriptor, value: number): number {
+	"worklet";
+	const d0 = scale.domain[0];
+	const d1 = scale.domain[1];
+	const r0 = scale.range[0];
+	const r1 = scale.range[1];
+
+	switch (scale.kind) {
+		case "linear":
+		case "time": {
+			if (d0 === d1) return (r0 + r1) / 2;
+			return r0 + ((value - d0) / (d1 - d0)) * (r1 - r0);
+		}
+		case "log": {
+			if (d0 <= 0 || d1 <= 0 || d0 === d1) return (r0 + r1) / 2;
+			const l0 = Math.log(d0);
+			const l1 = Math.log(d1);
+			const lv = Math.log(value > 0 ? value : Number.MIN_VALUE);
+			return r0 + ((lv - l0) / (l1 - l0)) * (r1 - r0);
+		}
+	}
+}
+
+/**
+ * The domain value at a position along the range — `scaleValue` inverted.
+ *
+ * This is the one piece of scale maths that runs on the UI thread every frame
+ * of a scrub, which is the whole reason the descriptor is plain data.
+ *
+ * Flat worklet: calls nothing, closes over nothing.
+ */
+export function invertValue(scale: ScaleDescriptor, position: number): number {
+	"worklet";
+	const d0 = scale.domain[0];
+	const d1 = scale.domain[1];
+	const r0 = scale.range[0];
+	const r1 = scale.range[1];
+
+	if (r0 === r1) return d0;
+	const t = (position - r0) / (r1 - r0);
+
+	switch (scale.kind) {
+		case "linear":
+		case "time":
+			return d0 + t * (d1 - d0);
+		case "log": {
+			if (d0 <= 0 || d1 <= 0) return d0;
+			const l0 = Math.log(d0);
+			const l1 = Math.log(d1);
+			return Math.exp(l0 + t * (l1 - l0));
+		}
+	}
+}