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

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

@@ -0,0 +1,106 @@
+import type { CurvePath } from "./path-segments";
+
+/**
+ * Bisection steps.
+ *
+ * 32 resolves `t` to 2⁻³² of a segment, which on a 1000-point-wide canvas is
+ * about 2e-7 points of `y` — seven orders of magnitude below anything a screen
+ * can show. Each step is a handful of multiplies, so the whole solve is well
+ * under a microsecond and the extra headroom over the ~1e-6 that 24 steps give
+ * costs nothing worth measuring.
+ */
+const BISECTIONS = 32;
+
+/** Below this the segment is vertical and `x` does not select a single `y`. */
+const VERTICAL_EPSILON = 1e-9;
+
+/**
+ * The `y` on the drawn curve at canvas `x`, or `NaN` where the path has none.
+ *
+ * This is what makes a scrub dot glide along the line rather than hop between
+ * data points. It reads the same cubics the renderer drew, so the dot cannot
+ * drift off the stroke however the curve was interpolated.
+ *
+ * **Bisection, not the analytic cubic root.** The closed-form solve is three
+ * functions calling each other — `solveCubic` calling `cuberoot` — and a
+ * module-scope worklet that calls another module-scope worklet binds at import
+ * time in source order, so the UI thread gets `undefined is not a function`.
+ * Since `x` is monotone along every segment a chart draws, bisection converges
+ * provably and fits in one flat function. The exact solver lives in this
+ * module's test as an oracle, which is the right place for a second
+ * implementation.
+ *
+ * Outside the path it clamps to the nearer end. Inside a gap it returns `NaN`,
+ * and the caller falls back to the nearest datum.
+ *
+ * Flat worklet: calls nothing, closes over nothing but the two constants above.
+ *
+ * It is one long function for that reason and not by preference. The obvious
+ * refactor — a run scan, a segment search and a bisection as three helpers —
+ * is four module-scope functions calling each other, which binds at import
+ * time in source order and hands the UI thread `undefined is not a function`
+ * the moment a finger lands. The complexity rule is suppressed below because
+ * satisfying it here would break the code on a device.
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the flat-worklet rule forbids extracting helpers; see the doc comment above.
+export function getYForX(path: CurvePath, x: number): number {
+	"worklet";
+	if (path.length === 0 || !Number.isFinite(x)) return Number.NaN;
+
+	const firstRun = path[0] as readonly number[];
+	if (x <= (firstRun[0] as number)) return firstRun[1] as number;
+
+	const lastRun = path[path.length - 1] as readonly number[];
+	if (x >= (lastRun[lastRun.length - 2] as number)) return lastRun[lastRun.length - 1] as number;
+
+	for (let runIndex = 0; runIndex < path.length; runIndex += 1) {
+		const run = path[runIndex] as readonly number[];
+		const count = (run.length - 2) / 6;
+		if (count < 1) continue;
+		if (x < (run[0] as number) || x > (run[run.length - 2] as number)) continue;
+
+		let lo = 0;
+		let hi = count - 1;
+		let index = -1;
+		while (lo <= hi) {
+			const mid = (lo + hi) >> 1;
+			const startX = run[mid * 6] as number;
+			const endX = run[mid * 6 + 6] as number;
+			if (x < startX) hi = mid - 1;
+			else if (x > endX) lo = mid + 1;
+			else {
+				index = mid;
+				break;
+			}
+		}
+		if (index === -1) continue;
+
+		const base = index * 6;
+		const p0x = run[base] as number;
+		const p0y = run[base + 1] as number;
+		const c1x = run[base + 2] as number;
+		const c1y = run[base + 3] as number;
+		const c2x = run[base + 4] as number;
+		const c2y = run[base + 5] as number;
+		const p1x = run[base + 6] as number;
+		const p1y = run[base + 7] as number;
+
+		if (Math.abs(p1x - p0x) < VERTICAL_EPSILON) return p1y;
+
+		let t0 = 0;
+		let t1 = 1;
+		let t = 0.5;
+		for (let step = 0; step < BISECTIONS; step += 1) {
+			t = (t0 + t1) / 2;
+			const mt = 1 - t;
+			const bx = mt * mt * mt * p0x + 3 * mt * mt * t * c1x + 3 * mt * t * t * c2x + t * t * t * p1x;
+			if (bx < x) t0 = t;
+			else t1 = t;
+		}
+
+		const mt = 1 - t;
+		return mt * mt * mt * p0y + 3 * mt * mt * t * c1y + 3 * mt * t * t * c2y + t * t * t * p1y;
+	}
+
+	return Number.NaN;
+}

package/src/core/polar/build-slice-path.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, test } from "bun:test";
+import { ARC_SEGMENTS, buildSliceEdgePath, buildSlicePath } from "./build-slice-path";
+import type { PieSliceData, PolarPoint } from "./polar.types";
+import { polarToCartesian } from "./polar-point";
+
+const center: PolarPoint = { x: 100, y: 100 };
+
+function slice(sweep: number, innerRadius = 0, startAngle = 0, radius = 80): PieSliceData {
+	return {
+		index: 0,
+		label: "",
+		value: sweep,
+		fraction: sweep / 360,
+		startAngle,
+		endAngle: startAngle + sweep,
+		sweepAngle: sweep,
+		center,
+		radius,
+		innerRadius,
+		sliceIsEntireCircle: sweep === 360,
+	};
+}
+
+/** 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);
+}
+
+/** The cubic segments of a path as `[p0, c1, c2, p1]` tuples, walking the current point. */
+function cubics(path: string): PolarPoint[][] {
+	const found: PolarPoint[][] = [];
+	let current: PolarPoint = { x: 0, y: 0 };
+	const tokens = path.match(/[A-Za-z][^A-Za-z]*/g) ?? [];
+	for (const token of tokens) {
+		const verb = token[0];
+		const values = numbers(token.slice(1));
+		if (verb === "M" || verb === "L") {
+			current = { x: values[0] as number, y: values[1] as number };
+		} else if (verb === "C") {
+			const c1 = { x: values[0] as number, y: values[1] as number };
+			const c2 = { x: values[2] as number, y: values[3] as number };
+			const p1 = { x: values[4] as number, y: values[5] as number };
+			found.push([current, c1, c2, p1]);
+			current = p1;
+		}
+	}
+	return found;
+}
+
+/** A point on a cubic Bézier at parameter `t` — the oracle. */
+function bezierAt([p0, c1, c2, p1]: PolarPoint[], t: number): PolarPoint {
+	const u = 1 - t;
+	const a = u * u * u;
+	const b = 3 * u * u * t;
+	const c = 3 * u * t * t;
+	const d = t * t * t;
+	return {
+		x: a * (p0 as PolarPoint).x + b * (c1 as PolarPoint).x + c * (c2 as PolarPoint).x + d * (p1 as PolarPoint).x,
+		y: a * (p0 as PolarPoint).y + b * (c1 as PolarPoint).y + c * (c2 as PolarPoint).y + d * (p1 as PolarPoint).y,
+	};
+}
+
+function distance(a: PolarPoint, b: PolarPoint): number {
+	return Math.hypot(a.x - b.x, a.y - b.y);
+}
+
+describe("buildSlicePath", () => {
+	test("emits four cubics per arc", () => {
+		expect(ARC_SEGMENTS).toBe(4);
+	});
+
+	test("always has the same eleven verbs, whatever the sweep or the hole", () => {
+		for (const sweep of [0, 1, 90, 180, 270, 360]) {
+			for (const inner of [0, 40]) {
+				expect(commands(buildSlicePath(slice(sweep, inner)))).toBe("MCCCCLCCCCZ");
+			}
+		}
+	});
+
+	test("starts at the outer start point and lines to the inner end point", () => {
+		const path = buildSlicePath(slice(90, 40));
+		const values = numbers(path);
+		const outerStart = polarToCartesian(center, 80, 0);
+		expect(values[0]).toBeCloseTo(outerStart.x, 2);
+		expect(values[1]).toBeCloseTo(outerStart.y, 2);
+
+		const segments = cubics(path);
+		const outerEnd = polarToCartesian(center, 80, 90);
+		expect(segments[3]?.[3]?.x).toBeCloseTo(outerEnd.x, 2);
+		expect(segments[3]?.[3]?.y).toBeCloseTo(outerEnd.y, 2);
+
+		const innerEnd = polarToCartesian(center, 40, 90);
+		expect(segments[4]?.[0]?.x).toBeCloseTo(innerEnd.x, 2);
+		expect(segments[4]?.[0]?.y).toBeCloseTo(innerEnd.y, 2);
+
+		const innerStart = polarToCartesian(center, 40, 0);
+		expect(segments[7]?.[3]?.x).toBeCloseTo(innerStart.x, 2);
+		expect(segments[7]?.[3]?.y).toBeCloseTo(innerStart.y, 2);
+	});
+
+	test("stays within 0.05% of the radius along every arc", () => {
+		for (const sweep of [30, 90, 180, 270, 360]) {
+			const segments = cubics(buildSlicePath(slice(sweep, 40, 15)));
+			segments.forEach((segment, index) => {
+				const radius = index < ARC_SEGMENTS ? 80 : 40;
+				for (let step = 0; step <= 10; step += 1) {
+					const point = bezierAt(segment, step / 10);
+					expect(Math.abs(distance(point, center) - radius) / radius).toBeLessThan(0.0005);
+				}
+			});
+		}
+	});
+
+	test("a full circle with a hole closes into a ring, not a disc", () => {
+		// Outer arc clockwise, inner arc counter-clockwise: opposite winding is
+		// what leaves the hole empty under nonzero winding.
+		const segments = cubics(buildSlicePath(slice(360, 40)));
+		const outerFirst = segments[0] as PolarPoint[];
+		const innerFirst = segments[4] as PolarPoint[];
+		const outerEnd = bezierAt(outerFirst, 1);
+		const innerEnd = bezierAt(innerFirst, 1);
+		// Both arcs start at 12 o'clock. Clockwise moves right; counter-clockwise moves left.
+		expect(outerEnd.x).toBeGreaterThan(center.x);
+		expect(innerEnd.x).toBeLessThan(center.x);
+		// And both come back to where they began.
+		const lastOuter = bezierAt(segments[3] as PolarPoint[], 1);
+		expect(lastOuter.x).toBeCloseTo(center.x, 2);
+		expect(lastOuter.y).toBeCloseTo(center.y - 80, 2);
+	});
+
+	test("a slice at radius 0 collapses to the centre and keeps its verbs", () => {
+		const path = buildSlicePath(slice(90, 0, 0, 0));
+		expect(commands(path)).toBe("MCCCCLCCCCZ");
+		for (const value of numbers(path)) expect(value).toBe(100);
+	});
+
+	test("emits no NaN for any degenerate input", () => {
+		for (const path of [
+			buildSlicePath(slice(0, 0)),
+			buildSlicePath(slice(0, 40)),
+			buildSlicePath(slice(Number.NaN, 0)),
+			buildSlicePath({ ...slice(90), startAngle: Number.NaN }),
+		]) {
+			expect(path).not.toContain("NaN");
+			expect(commands(path)).toBe("MCCCCLCCCCZ");
+		}
+	});
+});
+
+describe("buildSliceEdgePath", () => {
+	test("is a single line from the inner edge to the outer edge", () => {
+		const path = buildSliceEdgePath(slice(90, 40), "start");
+		expect(commands(path)).toBe("ML");
+		const values = numbers(path);
+		expect(values[0]).toBeCloseTo(100, 2);
+		expect(values[1]).toBeCloseTo(60, 2);
+		expect(values[2]).toBeCloseTo(100, 2);
+		expect(values[3]).toBeCloseTo(20, 2);
+	});
+
+	test("the end edge sits at the end angle", () => {
+		const values = numbers(buildSliceEdgePath(slice(90, 0), "end"));
+		expect(values[0]).toBeCloseTo(100, 2);
+		expect(values[1]).toBeCloseTo(100, 2);
+		expect(values[2]).toBeCloseTo(180, 2);
+		expect(values[3]).toBeCloseTo(100, 2);
+	});
+});

package/src/core/polar/build-slice-path.ts

@@ -0,0 +1,98 @@
+import type { PieSliceData, PolarPoint } from "./polar.types";
+import { polarToCartesian } from "./polar-point";
+
+/** Cubics per arc. Four keeps a quarter turn each, where the error is 0.03%. */
+export const ARC_SEGMENTS = 4;
+
+/**
+ * A slice as an SVG path: outer arc, a line inward, inner arc, close.
+ *
+ * The verb sequence is **always** `M C C C C L C C C C Z` — eleven verbs,
+ * whatever the sweep and whether there is a hole. A zero sweep emits four
+ * cubics with every control point on one ray; a pie with no hole emits an
+ * inner arc of radius zero sitting on the centre. That constancy is what lets
+ * Skia interpolate one slice into another when the data changes, and it is
+ * why a slice never uses an `A` arc verb: an arc's parameters are not
+ * pointwise-interpolatable and Skia would snap instead of morphing.
+ *
+ * The inner arc runs **counter-clockwise**. Under the nonzero winding rule the
+ * opposite direction is what leaves the hole of a 360° donut empty — with the
+ * arcs wound the same way, a single-slice donut fills into a disc.
+ */
+export function buildSlicePath(slice: PieSliceData): string {
+	const { center } = slice;
+	const radius = finite(slice.radius);
+	const inner = finite(slice.innerRadius);
+	const start = finite(slice.startAngle);
+	const sweep = finite(slice.sweepAngle);
+	const end = start + sweep;
+
+	const outerStart = polarToCartesian(center, radius, start);
+	const innerEnd = polarToCartesian(center, inner, end);
+
+	return [
+		`M${point(outerStart)}`,
+		...arcCubics(center, radius, start, sweep),
+		`L${point(innerEnd)}`,
+		...arcCubics(center, inner, end, -sweep),
+		"Z",
+	].join("");
+}
+
+/**
+ * One edge of a slice, from the inner radius to the outer, as `M L`.
+ *
+ * What a hairline between slices is drawn with: stroking the slice itself
+ * would also outline the arcs, and a stroked arc under a fill of the same
+ * colour reads as a slice that is slightly too big.
+ */
+export function buildSliceEdgePath(slice: PieSliceData, edge: "start" | "end"): string {
+	const angle = finite(edge === "start" ? slice.startAngle : slice.endAngle);
+	const from = polarToCartesian(slice.center, finite(slice.innerRadius), angle);
+	const to = polarToCartesian(slice.center, finite(slice.radius), angle);
+	return `M${point(from)}L${point(to)}`;
+}
+
+/**
+ * An arc of `sweep` degrees from `start`, as `ARC_SEGMENTS` cubic Béziers.
+ *
+ * Each cubic covers an equal share of the sweep; its control points sit on the
+ * tangents at either end, `4/3 · tan(θ/4)` of the radius along them, which is
+ * the standard circular approximation. A negative sweep walks the other way
+ * round, and the same formula holds because `tan` is odd.
+ */
+function arcCubics(center: PolarPoint, radius: number, start: number, sweep: number): string[] {
+	const segments: string[] = [];
+	const step = sweep / ARC_SEGMENTS;
+	const theta = (step * Math.PI) / 180;
+	const handle = (4 / 3) * Math.tan(theta / 4) * radius;
+
+	for (let index = 0; index < ARC_SEGMENTS; index += 1) {
+		const from = start + step * index;
+		const to = from + step;
+		const fromRadians = (from * Math.PI) / 180;
+		const toRadians = (to * Math.PI) / 180;
+		const p0 = polarToCartesian(center, radius, from);
+		const p1 = polarToCartesian(center, radius, to);
+		// The tangent at angle a, clockwise from 12 o'clock, is (cos a, sin a).
+		const c1 = { x: p0.x + handle * Math.cos(fromRadians), y: p0.y + handle * Math.sin(fromRadians) };
+		const c2 = { x: p1.x - handle * Math.cos(toRadians), y: p1.y - handle * Math.sin(toRadians) };
+		segments.push(`C${point(c1)} ${point(c2)} ${point(p1)}`);
+	}
+
+	return segments;
+}
+
+function point({ x, y }: PolarPoint): string {
+	return `${round(x)},${round(y)}`;
+}
+
+/** Three decimals — sub-pixel, and short enough that a path string stays small. */
+function round(value: number): number {
+	const rounded = Math.round(value * 1000) / 1000;
+	return rounded === 0 ? 0 : rounded;
+}
+
+function finite(value: number): number {
+	return Number.isFinite(value) ? value : 0;
+}

package/src/core/polar/label-position.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "bun:test";
+import { sliceLabelPosition } from "./label-position";
+import type { PieSliceData } from "./polar.types";
+
+const slice: PieSliceData = {
+	index: 0,
+	label: "a",
+	value: 1,
+	fraction: 0.25,
+	startAngle: 0,
+	endAngle: 90,
+	sweepAngle: 90,
+	center: { x: 100, y: 100 },
+	radius: 80,
+	innerRadius: 40,
+	sliceIsEntireCircle: false,
+};
+
+describe("sliceLabelPosition", () => {
+	test("sits on the slice's bisector, halfway across the annulus by default", () => {
+		const point = sliceLabelPosition(slice);
+		// 45°, at radius 60.
+		expect(point.x).toBeCloseTo(100 + 60 * Math.SQRT1_2);
+		expect(point.y).toBeCloseTo(100 - 60 * Math.SQRT1_2);
+	});
+
+	test("0 is the inner edge and 1 the outer", () => {
+		expect(Math.hypot(sliceLabelPosition(slice, 0).x - 100, sliceLabelPosition(slice, 0).y - 100)).toBeCloseTo(40);
+		expect(Math.hypot(sliceLabelPosition(slice, 1).x - 100, sliceLabelPosition(slice, 1).y - 100)).toBeCloseTo(80);
+	});
+
+	test("more than 1 sits outside the circle", () => {
+		const point = sliceLabelPosition(slice, 1.25);
+		expect(Math.hypot(point.x - 100, point.y - 100)).toBeCloseTo(90);
+	});
+
+	test("a pie with no hole measures from the centre", () => {
+		const point = sliceLabelPosition({ ...slice, innerRadius: 0 }, 0.5);
+		expect(Math.hypot(point.x - 100, point.y - 100)).toBeCloseTo(40);
+	});
+});

package/src/core/polar/label-position.ts

@@ -0,0 +1,18 @@
+import type { PieSliceData, PolarPoint } from "./polar.types";
+import { polarToCartesian } from "./polar-point";
+
+/**
+ * Where a slice's label sits: on the bisector, `radiusOffset` of the way
+ * across the annulus.
+ *
+ * The offset is a fraction of the **annulus** — `0` is the inner edge, `1` the
+ * outer, more than `1` outside the circle — rather than of the radius. A donut
+ * with a 60% hole and a label at half the radius would put the label in the
+ * hole; measuring from the inner edge keeps the same offset meaningful for a
+ * pie and a donut alike.
+ */
+export function sliceLabelPosition(slice: PieSliceData, radiusOffset = 0.5): PolarPoint {
+	const midAngle = slice.startAngle + slice.sweepAngle / 2;
+	const radius = slice.innerRadius + (slice.radius - slice.innerRadius) * radiusOffset;
+	return polarToCartesian(slice.center, radius, midAngle);
+}

package/src/core/polar/pie-input.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { collectPieInput } from "./pie-input";
+
+describe("collectPieInput", () => {
+	const rows = [
+		{ name: "chrome", share: 64 },
+		{ name: "safari", share: "19" },
+		{ name: "other", share: null },
+	];
+
+	test("reads values through asNumber, so a numeric string counts", () => {
+		expect(collectPieInput(rows, "share").values).toEqual([64, 19, Number.NaN]);
+	});
+
+	test("labels come from the label key as strings", () => {
+		expect(collectPieInput(rows, "share", "name").labels).toEqual(["chrome", "safari", "other"]);
+	});
+
+	test("labels fall back to the row's index when no key is given", () => {
+		expect(collectPieInput(rows, "share").labels).toEqual(["0", "1", "2"]);
+	});
+
+	test("a missing label reads as an empty string, not the word undefined", () => {
+		expect(collectPieInput([{ share: 1 }], "share", "name").labels).toEqual([""]);
+	});
+
+	test("keeps one entry per row, so indices line up with the data", () => {
+		const input = collectPieInput(rows, "share", "name");
+		expect(input.values.length).toBe(rows.length);
+		expect(input.labels.length).toBe(rows.length);
+	});
+
+	test("an empty table gives empty arrays", () => {
+		expect(collectPieInput([], "share")).toEqual({ values: [], labels: [] });
+	});
+});

package/src/core/polar/pie-input.ts

@@ -0,0 +1,32 @@
+import type { ChartRow } from "../chart.types";
+import { asNumber } from "../util/as-number";
+
+export type PieInput = {
+	/** One per row, `NaN` where the field could not be read. */
+	readonly values: readonly number[];
+	/** One per row, the index when there is no label field. */
+	readonly labels: readonly string[];
+};
+
+/**
+ * The value and label of every row, by key.
+ *
+ * Nothing is dropped here. A row that cannot be read stays in place as `NaN`
+ * so that indices still line up with the caller's data — `resolveSlices` turns
+ * it into a zero-sweep slice, and a tap readout reporting index 3 means the
+ * fourth row and not the fourth *readable* row.
+ */
+export function collectPieInput(rows: readonly ChartRow[], valueKey: string, labelKey?: string): PieInput {
+	const values: number[] = [];
+	const labels: string[] = [];
+	rows.forEach((row, index) => {
+		values.push(asNumber(row[valueKey]));
+		if (labelKey === undefined) {
+			labels.push(String(index));
+			return;
+		}
+		const label = row[labelKey];
+		labels.push(label === null || label === undefined ? "" : String(label));
+	});
+	return { values, labels };
+}

package/src/core/polar/polar-point.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from "bun:test";
+import { normalizeDegrees, polarToCartesian } from "./polar-point";
+
+const center = { x: 100, y: 100 };
+
+describe("polarToCartesian", () => {
+	test("0° is straight up", () => {
+		const point = polarToCartesian(center, 50, 0);
+		expect(point.x).toBeCloseTo(100);
+		expect(point.y).toBeCloseTo(50);
+	});
+
+	test("90° is to the right, so angles run clockwise", () => {
+		const point = polarToCartesian(center, 50, 90);
+		expect(point.x).toBeCloseTo(150);
+		expect(point.y).toBeCloseTo(100);
+	});
+
+	test("180° is straight down and 270° is to the left", () => {
+		expect(polarToCartesian(center, 50, 180).y).toBeCloseTo(150);
+		expect(polarToCartesian(center, 50, 270).x).toBeCloseTo(50);
+	});
+
+	test("a full turn lands where it started", () => {
+		const start = polarToCartesian(center, 50, 30);
+		const end = polarToCartesian(center, 50, 390);
+		expect(end.x).toBeCloseTo(start.x);
+		expect(end.y).toBeCloseTo(start.y);
+	});
+
+	test("radius zero is the centre at any angle", () => {
+		expect(polarToCartesian(center, 0, 123)).toEqual(center);
+	});
+});
+
+describe("normalizeDegrees", () => {
+	test("keeps a value already in range", () => {
+		expect(normalizeDegrees(45)).toBe(45);
+	});
+
+	test("wraps past a full turn, in both directions", () => {
+		expect(normalizeDegrees(370)).toBe(10);
+		expect(normalizeDegrees(-10)).toBe(350);
+		expect(normalizeDegrees(720)).toBe(0);
+	});
+
+	test("never returns 360", () => {
+		expect(normalizeDegrees(360)).toBe(0);
+	});
+
+	test("turns a non-finite angle into 0 rather than NaN", () => {
+		expect(normalizeDegrees(Number.NaN)).toBe(0);
+		expect(normalizeDegrees(Number.POSITIVE_INFINITY)).toBe(0);
+	});
+});

package/src/core/polar/polar-point.ts

@@ -0,0 +1,29 @@
+import type { PolarPoint } from "./polar.types";
+
+/**
+ * A canvas point at `radius` from `center`, `degrees` clockwise from 12 o'clock.
+ *
+ * The trigonometric convention has 0° at 3 o'clock and runs counter-clockwise;
+ * a pie chart's has 0° at the top and runs clockwise. The swap is done here,
+ * once, so every angle elsewhere in the package can be stated the way a chart
+ * reads and no mark has to remember which axis is `sin`.
+ */
+export function polarToCartesian(center: PolarPoint, radius: number, degrees: number): PolarPoint {
+	const radians = (degrees * Math.PI) / 180;
+	return {
+		x: center.x + radius * Math.sin(radians),
+		y: center.y - radius * Math.cos(radians),
+	};
+}
+
+/**
+ * `degrees` folded into `[0, 360)`.
+ *
+ * A non-finite angle becomes `0` rather than `NaN` — a `NaN` here would put a
+ * slice nowhere and the whole chart would go blank with nothing logged.
+ */
+export function normalizeDegrees(degrees: number): number {
+	if (!Number.isFinite(degrees)) return 0;
+	const folded = ((degrees % 360) + 360) % 360;
+	return folded === 360 ? 0 : folded;
+}

package/src/core/polar/polar.types.ts

@@ -0,0 +1,47 @@
+/** A point on the canvas, in points. */
+export type PolarPoint = {
+	readonly x: number;
+	readonly y: number;
+};
+
+/**
+ * The hole in a donut — points, or a percentage of the outer radius.
+ *
+ * A percentage is the form a themed wrapper wants, because it reads the same
+ * at every chart size; points are what a caller who has measured wants.
+ */
+export type InnerRadius = number | `${number}%`;
+
+/** Where the circle sits on the canvas, and how big it is. */
+export type PolarLayout = {
+	readonly center: PolarPoint;
+	readonly radius: number;
+	readonly innerRadius: number;
+};
+
+/**
+ * One slice, resolved: its share of the circle and where it is drawn.
+ *
+ * Angles are **degrees, 0° at 12 o'clock, clockwise** — the convention every
+ * pie chart library on every platform shares, and the one a designer's
+ * "start the first slice at the top" maps to without arithmetic. The layout
+ * is carried on every slice so a mark can be handed one slice and draw it
+ * with nothing else in scope.
+ */
+export type PieSliceData = {
+	/** Position in the data, kept even for a slice with no sweep. */
+	readonly index: number;
+	readonly label: string;
+	/** The datum's value; `0` for anything that could not be read. */
+	readonly value: number;
+	/** Share of the total, in `[0, 1]`. `0` when the total is zero. */
+	readonly fraction: number;
+	readonly startAngle: number;
+	readonly endAngle: number;
+	readonly sweepAngle: number;
+	readonly center: PolarPoint;
+	readonly radius: number;
+	readonly innerRadius: number;
+	/** The slice is the whole 360°, which makes its two edges coincide. */
+	readonly sliceIsEntireCircle: boolean;
+};