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

package/src/gesture/AGENTS.md

@@ -0,0 +1,84 @@
+# gesture
+
+The scrub: shared values, the pan that writes them, and the touch surface.
+
+## The contract
+
+Every field a consumer reads holds a **`number` or a `boolean`**. Never an
+`SkPath`, never an object, never a function.
+
+That is what keeps a themed tooltip free of any Skia import and readable from a
+plain `useAnimatedStyle` on an ordinary React Native view. A shared value
+carrying a Skia host object also has a long history of crashing, which is the
+second reason and would be sufficient on its own.
+
+## Two y values per series
+
+`y` is the position **on the drawn curve** at the touched x, solved by
+`getYForX` against the same cubics the renderer drew. A dot bound to it glides
+continuously along the line.
+
+`snappedY` is the position of the nearest datum. A dot bound to it lands on
+real measurements.
+
+Both come out of one binary search, so offering both costs nothing and the
+consumer picks. Victory-native only does the second; react-native-graph only
+does the first.
+
+For a stacked key the root builds `ys` and the curve from the stacked segment
+tops, so the dot sits on the segment that is visible, while `values` stay the
+raw series so the readout prints what was measured.
+
+## A point per series, either way round
+
+Each series also carries `snappedX` and `x`: with `snappedY` and `y` they are
+the nearest datum's canvas point on that series, and the gliding equivalent,
+**whichever way the chart is oriented**. A cursor dot reads the pair and
+never asks. On a horizontal chart the touch **y** is what matters — clamped,
+inverted against the category scale and matched to a row — and there is no
+curve to glide along, so the glide values equal the snapped ones.
+
+The root's fields say where the category is: `snappedX` on a vertical chart,
+`snappedY` on a horizontal one, `NaN` on the other. A band highlight is
+`xStep.px` wide centred on whichever is finite. `xValue` is the category value
+under the touch on either.
+
+## Files
+
+| Path | What |
+| --- | --- |
+| `gesture.types.ts` | The shared-value contract and the scrub's input model |
+| `use-chart-scrub.ts` | Allocates the shared values |
+| `use-scrub-gesture.ts` | The pan, and everything it does on the UI thread |
+| `gesture-overlay.tsx` | An absolute-fill view holding the gesture detector |
+
+## Design
+
+- **`makeMutable` in one `useMemo`, not `useSharedValue` in a loop.** The
+  series list is data. Calling a hook per series breaks the rules of hooks the
+  moment a series is added, and the memo is keyed on the joined key signature
+  so a fresh array of the same keys does not reallocate — which would strand
+  the gesture writing to values nothing renders any more.
+
+- **`onFinalize`, never `onEnd`.** A gesture that fails after activating never
+  fires `onEnd`, and the dot is stranded on screen until the next touch. This
+  is the bug `react-native-graph` fixed and left a comment about.
+
+- **`shouldCancelWhenOutside(false)`.** A finger dragged above or below the
+  plot keeps scrubbing. Cancelling there strands the gesture for anyone whose
+  thumb drifts off the chart, which is most people.
+
+- **`hold` is the default, not `claim`.** A chart usually lives in a scrolling
+  feed, and a scrub that activates on a plain drag steals the scroll. Holding
+  first is deliberate on the user's part, so nothing is taken by accident. A
+  chart that owns its width should be given `claim` explicitly.
+
+- **The handlers are built inside the `useMemo`, and that is why they may call
+  `getYForX`.** They are hook-scope worklets, captured by ordinary closure. The
+  flat-worklet rule in the package `AGENTS.md` constrains module-scope worklets
+  only, which is why the solver can be composed here rather than duplicated.
+
+- **Touches land on a React Native view, not on the canvas.** A Skia canvas is
+  one view however much is drawn on it, so there is nothing to hit-test
+  against. An absolute-fill sibling keeps the hit area exactly the chart's
+  bounds and keeps gesture composition ordinary.

package/src/gesture/gesture-overlay.tsx

@@ -0,0 +1,21 @@
+import type { ReactElement } from "react";
+import { StyleSheet, View } from "react-native";
+import { GestureDetector, type GestureType } from "react-native-gesture-handler";
+
+/**
+ * The touch surface, laid over the canvas.
+ *
+ * Gestures are handled by an ordinary React Native view rather than by the
+ * Skia canvas, because a canvas has no touch targets to speak of — it is one
+ * view however much is drawn on it. An absolute-fill sibling keeps the hit
+ * area exactly the chart's bounds and keeps gesture composition ordinary.
+ */
+export function ChartGestureOverlay({ gesture }: { readonly gesture: GestureType }): ReactElement {
+	return (
+		<GestureDetector gesture={gesture}>
+			<View style={StyleSheet.absoluteFill} />
+		</GestureDetector>
+	);
+}
+
+ChartGestureOverlay.displayName = "DelacourCharts.GestureOverlay";

package/src/gesture/gesture.types.ts

@@ -0,0 +1,143 @@
+import type { SharedValue } from "react-native-reanimated";
+import type { CurvePath } from "../core/interaction/path-segments";
+import type { ScaleDescriptor } from "../core/scale/scale.types";
+
+/**
+ * What a scrub knows about one series.
+ *
+ * `snappedX`/`snappedY` are the canvas point of the nearest datum **on this
+ * series**, whichever way the chart is oriented — a dot drawn at them sits on
+ * the datum on a vertical chart and at the end of the bar on a horizontal
+ * one. `x`/`y` are the gliding equivalent. A consumer that reads the pair
+ * never has to know the orientation.
+ */
+export type ChartScrubSeriesState = {
+	/**
+	 * Canvas x of the glide point. On a vertical chart the touch x; on a
+	 * horizontal one the same as `snappedX`, because the glide is disabled
+	 * there — a bar has no curve to slide along.
+	 */
+	readonly x: SharedValue<number>;
+	/**
+	 * Canvas y **on the drawn curve** at the touched x.
+	 *
+	 * A dot bound to this glides continuously along the line. `NaN` inside a
+	 * gap, where the series has no value. On a horizontal chart, the category's
+	 * y — the same as `snappedY`.
+	 */
+	readonly y: SharedValue<number>;
+	/** Canvas x of the nearest datum: the category's x when vertical, the value's x when horizontal. */
+	readonly snappedX: SharedValue<number>;
+	/** Canvas y of the nearest datum: the value's y when vertical, the category's y when horizontal. */
+	readonly snappedY: SharedValue<number>;
+	/** The nearest datum's value in domain units, which is what a label prints. */
+	readonly value: SharedValue<number>;
+};
+
+/**
+ * The scrub, as shared values.
+ *
+ * Every field holds a `number` or a `boolean` — never an `SkPath`, never an
+ * object. That is deliberate: it keeps a consumer's tooltip free of any Skia
+ * import and readable from a plain `useAnimatedStyle` on an ordinary React
+ * Native view.
+ */
+export type ChartScrubState = {
+	readonly isActive: SharedValue<boolean>;
+	/** Touch x in canvas points, clamped to the plot rect. */
+	readonly x: SharedValue<number>;
+	/** Touch y in canvas points, clamped to the plot rect. */
+	readonly y: SharedValue<number>;
+	/**
+	 * Canvas x of the nearest datum's category, on a vertical chart. `NaN` on
+	 * a horizontal one, where the category has no x.
+	 *
+	 * What a crosshair should sit at whenever the readout beside it names a
+	 * datum: a vertical line tracking the raw touch while the label snaps says
+	 * two different things about one gesture.
+	 */
+	readonly snappedX: SharedValue<number>;
+	/**
+	 * Canvas y of the nearest datum's category, on a horizontal chart — where
+	 * a band highlight `xStep.px` tall is centred. `NaN` on a vertical one.
+	 */
+	readonly snappedY: SharedValue<number>;
+	/** The category value under the touch, whichever axis the categories lie on. */
+	readonly xValue: SharedValue<number>;
+	/** Nearest datum index. `-1` before the first touch. */
+	readonly index: SharedValue<number>;
+	readonly series: Readonly<Record<string, ChartScrubSeriesState>>;
+};
+
+/**
+ * One series, as the scrub worklet needs it: plain numbers, nothing to call.
+ *
+ * `ys` are the canvas positions of each datum's value along the value axis —
+ * a y when vertical, an x when horizontal. A stacked key's are its segment
+ * tops, so the dot sits on the visible segment; `values` are always the raw
+ * series, which is what a readout prints.
+ */
+export type ScrubSeries = {
+	readonly key: string;
+	readonly path: CurvePath;
+	readonly ys: readonly (number | null)[];
+	readonly values: readonly (number | null)[];
+};
+
+/**
+ * Everything the scrub worklet reads, in one shared value.
+ *
+ * `axis` is the canvas axis the categories lie on, and `positions` and
+ * `scale` describe them there. `xPositions` and `xScale` are the same two
+ * under their older names, kept for a consumer that built against them.
+ */
+export type ScrubModel = {
+	/** The canvas axis the categories lie on: `x` when vertical, `y` when horizontal. */
+	readonly axis: "x" | "y";
+	readonly left: number;
+	readonly right: number;
+	readonly top: number;
+	readonly bottom: number;
+	/** Canvas position of each row's category along `axis`, ascending. */
+	readonly positions: readonly number[];
+	/** The category scale, for inverting a touch to a category value. */
+	readonly scale: ScaleDescriptor;
+	/** Same as `positions`. */
+	readonly xPositions: readonly number[];
+	/** Same as `scale`. */
+	readonly xScale: ScaleDescriptor;
+	readonly series: readonly ScrubSeries[];
+};
+
+export const EMPTY_SCRUB_MODEL: ScrubModel = {
+	axis: "x",
+	left: 0,
+	right: 0,
+	top: 0,
+	bottom: 0,
+	positions: [],
+	scale: { kind: "linear", domain: [0, 1], range: [0, 1] },
+	xPositions: [],
+	xScale: { kind: "linear", domain: [0, 1], range: [0, 1] },
+	series: [],
+};
+
+/**
+ * How the scrub coexists with a scrolling parent.
+ *
+ * - `hold` activates after a long press, so a list keeps both axes until the
+ *   user deliberately holds. The right default for a chart inside a feed.
+ * - `claim` gives horizontal drags to the scrub and vertical ones to the
+ *   scroll. For a chart that owns its width.
+ * - `block` wins outright, and needs the scrollable's gesture to block.
+ */
+export type ScrubBehaviour = "hold" | "claim" | "block";
+
+export type ScrubConfig = {
+	readonly enabled?: boolean;
+	readonly behaviour?: ScrubBehaviour;
+	/** Milliseconds to hold before `hold` activates. */
+	readonly holdDuration?: number;
+	/** How far a drag must travel before `claim` decides it is horizontal. */
+	readonly activationDistance?: number;
+};

package/src/gesture/index.ts

@@ -0,0 +1,12 @@
+export {
+	type ChartScrubSeriesState,
+	type ChartScrubState,
+	EMPTY_SCRUB_MODEL,
+	type ScrubBehaviour,
+	type ScrubConfig,
+	type ScrubModel,
+	type ScrubSeries,
+} from "./gesture.types";
+export { ChartGestureOverlay } from "./gesture-overlay";
+export { useChartScrub } from "./use-chart-scrub";
+export { type UseScrubGestureOptions, useScrubGesture } from "./use-scrub-gesture";

package/src/gesture/use-chart-scrub.ts

@@ -0,0 +1,44 @@
+import { useMemo } from "react";
+import { makeMutable } from "react-native-reanimated";
+import type { ChartScrubSeriesState, ChartScrubState } from "./gesture.types";
+
+/**
+ * Allocates the shared values a scrub writes to.
+ *
+ * `makeMutable` inside one `useMemo`, rather than a `useSharedValue` per
+ * series: the series list is data, and calling a hook in a loop over it breaks
+ * the rules of hooks the moment a series is added or removed.
+ *
+ * Hold the result and pass it to a chart. It stays stable for the life of the
+ * component unless the set of keys changes.
+ */
+export function useChartScrub(keys: readonly string[]): ChartScrubState {
+	const signature = keys.join(" ");
+
+	// Keyed on the joined signature: a fresh array of the same keys must not
+	// reallocate every shared value, which would strand the gesture writing to
+	// values nothing renders any more.
+	return useMemo<ChartScrubState>(() => {
+		const series: Record<string, ChartScrubSeriesState> = {};
+		for (const key of signature === "" ? [] : signature.split(" ")) {
+			series[key] = {
+				x: makeMutable(Number.NaN),
+				y: makeMutable(Number.NaN),
+				snappedX: makeMutable(Number.NaN),
+				snappedY: makeMutable(Number.NaN),
+				value: makeMutable(Number.NaN),
+			};
+		}
+
+		return {
+			isActive: makeMutable(false),
+			x: makeMutable(0),
+			y: makeMutable(0),
+			snappedX: makeMutable(Number.NaN),
+			snappedY: makeMutable(Number.NaN),
+			xValue: makeMutable(Number.NaN),
+			index: makeMutable(-1),
+			series,
+		};
+	}, [signature]);
+}

package/src/gesture/use-scrub-gesture.ts

@@ -0,0 +1,162 @@
+import { useMemo } from "react";
+import { Gesture, type GestureType } from "react-native-gesture-handler";
+import type { SharedValue } from "react-native-reanimated";
+import { closestIndex } from "../core/interaction/closest-index";
+import { getYForX } from "../core/interaction/y-for-x";
+import { invertValue } from "../core/scale/scale";
+import { clamp } from "../core/util/clamp";
+import { readAt } from "../core/util/read-at";
+import type { ChartScrubState, ScrubConfig, ScrubModel, ScrubSeries } from "./gesture.types";
+
+const DEFAULT_HOLD_MS = 250;
+const DEFAULT_ACTIVATION_DISTANCE = 8;
+
+export type UseScrubGestureOptions = {
+	readonly state: ChartScrubState | undefined;
+	readonly model: SharedValue<ScrubModel>;
+	readonly config?: ScrubConfig;
+	/** The scrollable's gesture to out-prioritise, for `behaviour: "block"`. */
+	readonly blocks?: GestureType;
+};
+
+/**
+ * The pan that drives a scrub.
+ *
+ * Everything happens on the UI thread. The touch x is clamped to the plot
+ * rect, inverted through the scale descriptor to a domain value, matched to
+ * the nearest datum, and solved against the drawn curve — with no hop to
+ * JavaScript, which is what lets the dot keep up with a fast drag.
+ *
+ * On a horizontal chart the touch **y** is the one that matters: it is
+ * clamped, inverted against the category scale and matched to a row, and the
+ * series' value positions come back as canvas x. The glide is off there —
+ * a bar has no curve to slide along — so every series reports its snapped
+ * point twice.
+ *
+ * The handlers are built inside this `useMemo`, so they close over
+ * `closestIndex`, `getYForX`, `invertValue` and `clamp` in the ordinary way.
+ * See the package AGENTS.md: that is legal precisely because these are not
+ * module-scope worklets.
+ */
+export function useScrubGesture(options: UseScrubGestureOptions): GestureType | null {
+	const { state, model, config, blocks } = options;
+	const enabled = (config?.enabled ?? true) && state !== undefined;
+	const behaviour = config?.behaviour ?? "hold";
+	const holdDuration = config?.holdDuration ?? DEFAULT_HOLD_MS;
+	const activationDistance = config?.activationDistance ?? DEFAULT_ACTIVATION_DISTANCE;
+
+	const apply = useScrubApply(state, model);
+
+	return useMemo(() => {
+		if (state === undefined || apply === null) return null;
+
+		const finish = (): void => {
+			"worklet";
+			state.isActive.value = false;
+		};
+
+		let pan = Gesture.Pan()
+			.enabled(enabled)
+			.averageTouches(true)
+			// A finger dragged above or below the plot keeps scrubbing. Cancelling
+			// there strands the dot mid-gesture for anyone whose thumb drifts.
+			.shouldCancelWhenOutside(false)
+			.onStart((event) => {
+				"worklet";
+				state.isActive.value = true;
+				apply(event.x, event.y);
+			})
+			.onUpdate((event) => {
+				"worklet";
+				apply(event.x, event.y);
+			})
+			// onFinalize, never onEnd: a gesture that fails after activating never
+			// fires onEnd, and the dot is stranded on screen until the next touch.
+			.onFinalize(finish);
+
+		if (behaviour === "hold") pan = pan.activateAfterLongPress(holdDuration);
+		if (behaviour === "claim") {
+			pan = pan
+				.activeOffsetX([-activationDistance, activationDistance])
+				.failOffsetY([-activationDistance, activationDistance]);
+		}
+		if (behaviour === "block" && blocks !== undefined) pan = pan.blocksExternalGesture(blocks);
+
+		return pan;
+	}, [state, apply, enabled, behaviour, holdDuration, activationDistance, blocks]);
+}
+
+type ScrubApply = (touchX: number, touchY: number) => void;
+
+/**
+ * The worklet that turns a touch into every scrub value.
+ *
+ * Built in its own `useMemo` so it closes over `closestIndex`, `getYForX`,
+ * `invertValue` and `clamp` in the ordinary way — a hook-scope worklet, which
+ * the flat-worklet rule permits — and so the pan above stays small enough to
+ * read.
+ */
+function useScrubApply(state: ChartScrubState | undefined, model: SharedValue<ScrubModel>): ScrubApply | null {
+	const applySeries = useApplySeries(state);
+	return useMemo(() => {
+		if (state === undefined || applySeries === null) return null;
+
+		return (touchX: number, touchY: number): void => {
+			"worklet";
+			const current = model.value;
+			// A collapsed plot has nothing to scrub, and would clamp into a NaN.
+			if (Math.min(current.right - current.left, current.bottom - current.top) <= 0) return;
+
+			const x = clamp(touchX, current.left, current.right);
+			const y = clamp(touchY, current.top, current.bottom);
+			state.x.value = x;
+			state.y.value = y;
+
+			const horizontal = current.axis === "y";
+			const along = horizontal ? y : x;
+			state.xValue.value = invertValue(current.scale, along);
+
+			const index = closestIndex(current.positions, along);
+			state.index.value = index;
+			const category = readAt(current.positions, index);
+			state.snappedX.value = horizontal ? Number.NaN : category;
+			state.snappedY.value = horizontal ? category : Number.NaN;
+
+			for (const series of current.series) applySeries(series, index, category, x, horizontal);
+		};
+	}, [state, model, applySeries]);
+}
+
+type ApplySeries = (series: ScrubSeries, index: number, category: number, x: number, horizontal: boolean) => void;
+
+/** The per-series half of the scrub, as a hook-scope worklet of its own. */
+function useApplySeries(state: ChartScrubState | undefined): ApplySeries | null {
+	return useMemo(() => {
+		if (state === undefined) return null;
+
+		// No glide on a horizontal chart — a bar has no curve to slide along —
+		// so the snapped point is reported twice there.
+		return (series: ScrubSeries, index: number, category: number, x: number, horizontal: boolean): void => {
+			"worklet";
+			const target = state.series[series.key];
+			if (target === undefined) return;
+
+			const snapped = readAt(series.ys, index);
+			target.value.value = readAt(series.values, index);
+			if (horizontal) {
+				target.snappedX.value = snapped;
+				target.snappedY.value = category;
+				target.x.value = snapped;
+				target.y.value = category;
+				return;
+			}
+			target.snappedX.value = category;
+			target.snappedY.value = snapped;
+			target.x.value = x;
+			// Inside a gap the curve has no y, so the dot falls back to the nearest
+			// datum rather than vanishing to NaN mid-drag.
+			const onCurve = getYForX(series.path, x);
+			target.y.value = Number.isFinite(onCurve) ? onCurve : snapped;
+		};
+	}, [state]);
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./animation";
+export * from "./cartesian";
+export * from "./core";
+export * from "./gesture";
+export * from "./polar";
+export * from "./skia";

package/src/no-classname.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test";
+import { read, relative, SRC, sourceFiles } from "./source-tree.test";
+
+/**
+ * This package emits no `className`.
+ *
+ * That is the promise the whole two-package split rests on: colours, fonts and
+ * sizes arrive as values, and `@delacour/react-native-ui` is the only place tokens
+ * exist. It also has a concrete consequence in the playground — Tailwind's
+ * scanner needs no `@source` line pointing here, because there is nothing to
+ * scan. A stray `className` would make that missing line a silent bug where a
+ * class compiles in development and vanishes from a release build.
+ *
+ * So the promise is checked rather than hoped for.
+ */
+describe("no className", () => {
+	const files = sourceFiles(SRC, { skipTests: true });
+
+	test("finds the source, so a broken walker cannot pass silently", () => {
+		expect(files.length).toBeGreaterThan(20);
+	});
+
+	test("no module names className", () => {
+		const offenders = files.filter((file) => read(file).includes("className")).map((file) => relative(file));
+		expect(offenders).toEqual([]);
+	});
+});

package/src/polar/AGENTS.md

@@ -0,0 +1,55 @@
+# polar
+
+The pie and donut root, its context, and the marks drawn inside it.
+
+Mounted the way `cartesian/` is — a measuring `View`, a `Canvas`, the provider
+**inside** the canvas, an overlay for touch — for the reasons that folder's
+`AGENTS.md` gives. Only the differences are recorded here.
+
+## Files
+
+| Path | What |
+| --- | --- |
+| `polar-chart.tsx` | The root: measure, model, canvas, provider, and the tap overlay |
+| `polar-chart.context.tsx` | The context, its hook, and the optional variant |
+| `polar-chart.types.ts` | Props, render args, and the key-narrowing helpers |
+| `hooks/use-polar-model.ts` | Layout and slices, memoised — one pass, nothing measured |
+| `marks/pie-slice.tsx` | One filled slice, growing out of the centre on mount |
+| `marks/pie-slices.tsx` | Every slice, with a cycled palette and selection dimming |
+| `marks/pie-label.tsx` | Skia text on each slice wide enough to hold it |
+| `marks/pie-inset.tsx` | A stroked hairline on each edge between slices |
+
+## Design
+
+- **Angles are degrees, 0° at 12 o'clock, clockwise.** The convention every
+  pie library shares and the one a designer's "start at the top" maps to
+  with no arithmetic. `core/polar/polar-point.ts` does the one conversion to
+  trigonometric radians; nothing above it repeats it.
+
+- **A slice path is always eleven verbs.** `M C C C C L C C C C Z`, whatever
+  the sweep and whether there is a hole — see `core/polar/build-slice-path.ts`.
+  That is what lets a data change morph rather than snap, and it is why the
+  mount animation is free: the entrance path is the same slice at radius zero.
+
+- **Colours are mark props, never a data field.** The root reads a value and a
+  label from each row and nothing else. A colour column would be a token in
+  disguise, and this package has none.
+
+- **The tap runs on the JavaScript thread.** `Gesture.Tap().runOnJS(true)`
+  calls `sliceIndexAt` and hands the index to React state. A scrub reads a
+  shared value every frame of a drag and has to stay on the UI thread; a tap
+  fires once and nothing on the UI side wants its result. `sliceIndexAt` is
+  still written as a flat worklet so a scrub over a pie could reuse it.
+
+- **The overlay mounts only with `onSlicePress`.** A pie in a scrolling feed
+  with no tap handler should take no touches at all, and a gesture detector
+  with nothing to do still claims them.
+
+- **`selectedIndex` is the caller's, not the chart's.** The root carries it
+  into context and the marks read it; the root never changes it. Holding
+  selection state here would put a second copy of it beside the one a themed
+  wrapper already keeps, and the two would drift.
+
+- **`PieInset` draws edges, not outlines.** Stroking each slice would outline
+  its arcs too, and a stroked arc under a fill of the same colour reads as a
+  slice slightly too big. One `M L` per edge is exactly the hairline wanted.

package/src/polar/hooks/use-polar-model.ts

@@ -0,0 +1,88 @@
+import type { SkFont } from "@shopify/react-native-skia";
+import { useMemo } from "react";
+import type { ChartAnimation } from "../../animation/animation.types";
+import { DEFAULT_CHART_ANIMATION } from "../../animation/animation.types";
+import type { ChartRow, ChartSize } from "../../core/chart.types";
+import { collectPieInput } from "../../core/polar/pie-input";
+import type { InnerRadius } from "../../core/polar/polar.types";
+import { resolvePolarLayout } from "../../core/polar/resolve-layout";
+import { resolveSlices } from "../../core/polar/resolve-slices";
+import type { SidedNumber } from "../../core/util/sided-number";
+import { fontMetrics } from "../../skia/font";
+import type { PolarContextValue } from "../polar-chart.types";
+
+export type UsePolarModelOptions = {
+	readonly data: readonly ChartRow[];
+	readonly valueKey: string;
+	readonly labelKey?: string;
+	readonly canvas: ChartSize;
+	readonly padding?: SidedNumber;
+	readonly size?: number;
+	readonly innerRadius?: InnerRadius;
+	readonly startAngle?: number;
+	readonly circleSweepDegrees?: number;
+	readonly animation?: ChartAnimation;
+	readonly font?: SkFont | null;
+	readonly selectedIndex?: number | null;
+};
+
+/**
+ * The whole pie, resolved: the circle's place on the canvas and every slice.
+ *
+ * Nothing here is measured, so unlike the cartesian model there is a single
+ * pass. The hook exists to memoise it — every mark below reads `slices`, and a
+ * fresh array on each render would rebuild every slice path and restart every
+ * morph while nothing had changed.
+ */
+export function usePolarModel(options: UsePolarModelOptions): PolarContextValue {
+	const {
+		data,
+		valueKey,
+		labelKey,
+		canvas,
+		padding,
+		size,
+		innerRadius,
+		startAngle = 0,
+		circleSweepDegrees = 360,
+		animation = DEFAULT_CHART_ANIMATION,
+		font = null,
+		selectedIndex = null,
+	} = options;
+
+	return useMemo<PolarContextValue>(() => {
+		const layout = resolvePolarLayout({ canvas, padding, size, innerRadius });
+		const { values, labels } = collectPieInput(data, valueKey, labelKey);
+		const slices = resolveSlices({ values, labels, layout, startAngle, circleSweepDegrees });
+		const metrics = fontMetrics(font);
+
+		return {
+			slices,
+			center: layout.center,
+			radius: layout.radius,
+			innerRadius: layout.innerRadius,
+			startAngle,
+			circleSweepDegrees,
+			canvas,
+			font,
+			lineHeight: metrics.ascent + metrics.descent,
+			fontMetrics: metrics,
+			animation,
+			selectedIndex,
+			ready: layout.radius > 0 && data.length > 0,
+		};
+	}, [
+		data,
+		valueKey,
+		labelKey,
+		canvas,
+		padding,
+		size,
+		innerRadius,
+		startAngle,
+		circleSweepDegrees,
+		animation,
+		font,
+		selectedIndex,
+	]);
+}

package/src/polar/index.ts

@@ -0,0 +1,14 @@
+export { type UsePolarModelOptions, usePolarModel } from "./hooks/use-polar-model";
+export { PieInset, type PieInsetProps } from "./marks/pie-inset";
+export { PieLabel, type PieLabelProps } from "./marks/pie-label";
+export { PieSlice, type PieSliceProps } from "./marks/pie-slice";
+export { PieSlices, type PieSlicesProps } from "./marks/pie-slices";
+export { PolarChart } from "./polar-chart";
+export { PolarChartContext, useOptionalPolarContext, usePolarContext } from "./polar-chart.context";
+export type {
+	LabelKeyOf,
+	PolarChartProps,
+	PolarContextValue,
+	PolarRenderArgs,
+	ValueKeyOf,
+} from "./polar-chart.types";