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

package/README.md

@@ -0,0 +1,98 @@
+# @delacour/react-native-charts
+
+Headless charting primitives for React Native — Skia for drawing, Reanimated
+for animation, Gesture Handler for touch.
+
+No tokens, no `className`, no theme. Every colour, font and size is a value you
+pass in. If you want charts already wearing a design system, use
+[`@delacour/react-native-ui/chart`](https://ui.delacour.co.nz/docs/native/components/chart),
+which is this engine with the tokens attached.
+
+> **Alpha.** Both this package and `@delacour/react-native-ui` publish to npm's
+> `alpha` tag, and every alpha is also `latest`.
+
+Docs: [ui.delacour.co.nz/docs/charts](https://ui.delacour.co.nz/docs/charts).
+
+## Install
+
+```bash
+bun add @delacour/react-native-charts
+bunx expo install @shopify/react-native-skia react-native-gesture-handler react-native-reanimated react-native-worklets
+```
+
+Peers: `@shopify/react-native-skia`, `react-native-reanimated`,
+`react-native-gesture-handler`, `react-native-worklets`, `react`,
+`react-native`. The native four go through `expo install`, so the SDK picks
+versions it can build; `react` and `react-native` are already in any app.
+
+Your app needs a `GestureHandlerRootView` at its root. This package does not
+render one — a nested root is dead weight, and every React Native app that
+handles touch already has one.
+
+## Use
+
+```tsx
+import { CartesianChart, ChartArea, ChartLine } from "@delacour/react-native-charts";
+
+<CartesianChart data={rows} xKey="day" yKeys={["revenue"]}>
+  {({ points, bounds }) => (
+    <>
+      <ChartArea baseline={bounds.bottom} color="#0A84FF22" curve="monotone" points={points.revenue} />
+      <ChartLine color="#0A84FF" curve="monotone" points={points.revenue} strokeWidth={2} />
+    </>
+  )}
+</CartesianChart>
+```
+
+Marks also read the chart context, so they can be placed rather than called:
+
+```tsx
+<CartesianChart data={rows} xKey="day" yKeys={["revenue"]}>
+  <ChartLine color="#0A84FF" yKey="revenue" />
+</CartesianChart>
+```
+
+Bars stand on zero and need half a step of x padding so the outermost ones sit
+inside the plot. Sibling series stack when the root is told which keys to
+stack, because only the root can size the y axis for the totals:
+
+```tsx
+import { CartesianChart, ChartBar, ChartBarStack } from "@delacour/react-native-charts";
+
+<CartesianChart data={rows} domainPadding={{ x: 0.5 }} includeZero xKey="month" yKeys={["revenue"]}>
+  <ChartBar color="#0A84FF" roundedCorners={{ topLeft: 4, topRight: 4 }} yKey="revenue" />
+</CartesianChart>
+
+<CartesianChart data={rows} domainPadding={{ x: 0.5 }} stackKeys={["web", "ios", "android"]} xKey="month" yKeys={["web", "ios", "android"]}>
+  <ChartBarStack colors={["#0A84FF", "#30D158", "#FF9F0A"]} yKeys={["web", "ios", "android"]} />
+</CartesianChart>
+```
+
+Add `orientation="horizontal"` to the root and the categories run down the
+left with the bars growing rightward; nothing else changes.
+
+A pie is its own root. Slices, labels and the hairline between them are marks,
+and a tap reports the slice under the finger:
+
+```tsx
+import { PieInset, PieLabel, PieSlices, PolarChart } from "@delacour/react-native-charts";
+
+<PolarChart data={rows} innerRadius="60%" labelKey="browser" onSlicePress={setSelected} selectedIndex={selected} valueKey="share">
+  <PieSlices colors={["#0A84FF", "#30D158", "#FF9F0A", "#FF375F"]} />
+  <PieInset color="#FFFFFF" strokeWidth={2} />
+  <PieLabel color="#FFFFFF" font={font} formatLabel={(slice) => `${Math.round(slice.fraction * 100)}%`} minSweep={12} />
+</PolarChart>
+```
+
+## The maths on its own
+
+`@delacour/react-native-charts/core` is every scale, tick, curve and solver in the package,
+importable with no Skia in the module graph:
+
+```ts
+import { closestIndex, invertValue, makeScale } from "@delacour/react-native-charts/core";
+```
+
+## Licence
+
+MIT

package/package.json

@@ -0,0 +1,61 @@
+{
+	"name": "@delacour/react-native-charts",
+	"version": "0.1.0-alpha.20260925053522",
+	"description": "Headless Skia charting primitives for React Native \u2014 no tokens, no className",
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/delacournz/delacour-ui.git",
+		"directory": "packages/react-native-charts"
+	},
+	"keywords": [
+		"react-native",
+		"skia",
+		"charts",
+		"reanimated",
+		"gesture-handler",
+		"expo"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"README.md"
+	],
+	"sideEffects": false,
+	"exports": {
+		".": "./src/index.ts",
+		"./core": "./src/core/index.ts"
+	},
+	"scripts": {
+		"fmt": "biome format --write ./src",
+		"lint": "biome lint --write ./src",
+		"check": "biome check ./src",
+		"typecheck": "tsc --noEmit",
+		"test": "bun test"
+	},
+	"dependencies": {
+		"@types/d3-scale": "^4.0.9",
+		"@types/d3-shape": "^3.1.7",
+		"d3-scale": "^4.0.2",
+		"d3-shape": "^3.2.0"
+	},
+	"peerDependencies": {
+		"@shopify/react-native-skia": ">=2.6",
+		"react": ">=19",
+		"react-native": ">=0.81",
+		"react-native-gesture-handler": ">=2.28",
+		"react-native-reanimated": ">=4",
+		"react-native-worklets": ">=0.5"
+	},
+	"devDependencies": {
+		"@delacour/biome-config": "workspace:*",
+		"@delacour/tsconfig": "workspace:*",
+		"@shopify/react-native-skia": "catalog:",
+		"@types/bun": "^1.3.8",
+		"@types/react": "catalog:",
+		"typescript": "^5.9.3"
+	}
+}

package/src/animation/AGENTS.md

@@ -0,0 +1,40 @@
+# animation
+
+Path morphing, and the configuration that drives it.
+
+## Files
+
+| Path | What |
+| --- | --- |
+| `animation.types.ts` | `ChartAnimation` — timing, spring, or none |
+| `use-animated-path.ts` | A path that morphs whenever it changes |
+
+## Design
+
+- **Interpolation is Skia's own `usePathInterpolation`.** One native
+  `Path.Interpolate` per frame, with no path allocated on the JavaScript side.
+  The alternative — constructing a path inside a `useDerivedValue` — is the
+  shape behind a long-standing crash with Skia host objects in shared values.
+
+- **It never falls back to snapping, and says so when it does.** Point counts
+  are matched in data space before either path is built, so two paths always
+  share a verb sequence and `isInterpolatable` always holds. The
+  development-only warning exists to make a regression loud: if it fires,
+  `chooseMorphStrategy` or `matchPointCounts` has a bug, and silently snapping
+  is exactly how that bug would survive a release.
+
+- **`none` is not a zero duration.** It skips the interpolation entirely, which
+  is what a chart re-rendering off a live feed needs — there is nothing to
+  animate towards when the target moves every frame, and starting an animation
+  you immediately abandon costs a frame each time.
+
+- **The animation config is read through a ref inside the effect.** An inline
+  `{ type: "timing" }` prop is a new object every render; in the dependency
+  list it would restart the animation on every render, which reads as a line
+  that never settles.
+
+- **`enterFrom` is read on mount and never again.** It seeds the first morph
+  — a pie slice hands over itself at radius zero and grows out of the centre —
+  and is then forgotten, so an inline path built on every render cannot restart
+  the entrance. Omitted, the hook behaves exactly as it did before the option
+  existed: the range starts at the target and nothing is animated on mount.

package/src/animation/animation.types.ts

@@ -0,0 +1,16 @@
+import type { WithSpringConfig, WithTimingConfig } from "react-native-reanimated";
+
+/**
+ * How a mark moves when its data changes.
+ *
+ * `none` is not the same as a zero duration: it skips the interpolation
+ * entirely, which is what a chart re-rendering sixty times a second off a live
+ * feed wants — there is nothing to animate towards when the target moves every
+ * frame.
+ */
+export type ChartAnimation =
+	| { readonly type: "none" }
+	| ({ readonly type: "timing" } & WithTimingConfig)
+	| ({ readonly type: "spring" } & WithSpringConfig);
+
+export const DEFAULT_CHART_ANIMATION: ChartAnimation = { type: "timing", duration: 300 };

package/src/animation/index.ts

@@ -0,0 +1,2 @@
+export { type ChartAnimation, DEFAULT_CHART_ANIMATION } from "./animation.types";
+export { type AnimatedPathOptions, useAnimatedPath } from "./use-animated-path";

package/src/animation/use-animated-path.ts

@@ -0,0 +1,74 @@
+import { type SkPath, usePathInterpolation } from "@shopify/react-native-skia";
+import { useEffect, useRef, useState } from "react";
+import { type SharedValue, useSharedValue, withSpring, withTiming } from "react-native-reanimated";
+import { type ChartAnimation, DEFAULT_CHART_ANIMATION } from "./animation.types";
+
+export type AnimatedPathOptions = {
+	/**
+	 * The path the very first animation starts from. Read on mount only.
+	 *
+	 * Without it a mark appears fully drawn, because there is no earlier path
+	 * to morph from. A pie slice hands over the same slice at radius zero and
+	 * scales out of the centre; a bar could hand over itself at the baseline.
+	 * It must share the target's verb sequence, or the mount snaps like any
+	 * other non-interpolatable change.
+	 */
+	readonly enterFrom?: SkPath;
+};
+
+/**
+ * A path that morphs to `path` whenever it changes.
+ *
+ * Interpolation is Skia's own `usePathInterpolation` — one native
+ * `Path.Interpolate` per frame, with no path allocated on the JS side. The
+ * alternative, building a path inside a `useDerivedValue`, is the shape behind
+ * a long-standing crash with Skia host objects in shared values.
+ *
+ * It never has to fall back to snapping, because point counts are matched in
+ * data space before either path is built — see `core/animation`. The
+ * development-only warning below exists to say so: if it ever fires, the morph
+ * strategy has a bug, and silently snapping is how that bug would survive a
+ * release.
+ */
+export function useAnimatedPath(
+	path: SkPath,
+	animation: ChartAnimation = DEFAULT_CHART_ANIMATION,
+	options?: AnimatedPathOptions
+): SharedValue<SkPath> {
+	// `enterFrom` is consulted by the initialisers alone, so a later change to
+	// it does nothing: the entrance has already happened. Seeding the range and
+	// the progress with it, rather than only the ref, is what stops the first
+	// frame showing the finished path before the effect below starts the morph.
+	const entrance = options?.enterFrom ?? path;
+	const progress = useSharedValue(entrance === path ? 1 : 0);
+	const previous = useRef<SkPath>(entrance);
+	const config = useRef<ChartAnimation>(animation);
+	config.current = animation;
+
+	const [range, setRange] = useState<SkPath[]>(() => [entrance, path]);
+
+	useEffect(() => {
+		const from = previous.current;
+		previous.current = path;
+
+		const current = config.current;
+		if (current.type === "none" || !from.isInterpolatable(path)) {
+			if (__DEV__ && current.type !== "none" && !from.isInterpolatable(path)) {
+				console.warn(
+					"[@delacour/react-native-charts] two paths were not interpolatable, so the change snapped. " +
+						"Point counts are supposed to be matched in data space before the paths are built — " +
+						"this means chooseMorphStrategy or matchPointCounts got it wrong."
+				);
+			}
+			setRange([path, path]);
+			progress.value = 1;
+			return;
+		}
+
+		setRange([from, path]);
+		progress.value = 0;
+		progress.value = current.type === "spring" ? withSpring(1, current) : withTiming(1, current);
+	}, [path, progress]);
+
+	return usePathInterpolation(progress, [0, 1], range);
+}

package/src/cartesian/AGENTS.md

@@ -0,0 +1,110 @@
+# cartesian
+
+The chart root, its context, and the marks and axes drawn inside it.
+
+## Where things are mounted, and why
+
+```
+View        onLayout, and the only thing that knows the chart's size
+  Canvas    the Skia reconciler starts here
+    Provider  ← rendered INSIDE the canvas, so marks below can read it
+      children
+  Overlay   an ordinary RN view; the canvas has no touch targets
+```
+
+The provider's position is the whole design. `<Canvas>` mounts a **second React
+reconciler**, and context does not cross a reconciler boundary — but it
+resolves by which reconciler renders the *provider node*, not by where the
+context object was created. Placing the provider among the canvas' children
+puts it in the Skia tree, and every mark below resolves it normally. No
+`its-fine`, no context bridge, no `FiberProvider` wrapping the host app.
+
+**The consequence for anything that skins this package:** every hook that reads
+a theme — `useThemeColor`, anything backed by a CSS variable — has to be called
+*above* the canvas and its result passed down as a plain value. There is
+nowhere inside to call one. That is not a limitation to work around; it is what
+keeps the re-render boundary visible in a diff.
+
+## Files
+
+| Path | What |
+| --- | --- |
+| `cartesian-chart.tsx` | The root: measure, model, canvas, provider, gesture overlay |
+| `cartesian-chart.context.tsx` | The context, its hook, and the optional variant |
+| `cartesian-chart.types.ts` | Props, render args, and the key-narrowing helpers |
+| `hooks/use-canvas-size.ts` | `onLayout` on the wrapping view |
+| `hooks/use-chart-model.ts` | The two passes, with the measuring between them; the axis roles, the x step, the stacks |
+| `marks/chart-line.tsx` | A stroked series |
+| `marks/chart-area.tsx` | The region between a series and a baseline |
+| `marks/chart-bar.tsx` | One bar per datum, on zero, with optional value labels |
+| `marks/chart-bar-group.tsx` | Several series side by side within each step, one path per series |
+| `marks/chart-bar-stack.tsx` | Several series stacked, read from the root's `stacked`, one path per series |
+| `marks/chart-scatter.tsx` | A circle, square or star per datum, all in one path |
+| `marks/chart-candlestick.tsx` | Open-high-low-close candles: six paths, wicks under bodies |
+| `marks/chart-grid.tsx` | One path holding every rule |
+| `axes/chart-x-axis.tsx` | Tick labels below the plot |
+| `axes/chart-y-axis.tsx` | Tick labels beside the plot |
+
+## Design
+
+- **A mark takes `yKey` or `points`, never needing both.** Given a key it reads
+  the context; given points it draws exactly those. That is what lets one
+  implementation serve the declarative call site and the render-prop one, so
+  the two can never drift apart or grow different bugs.
+
+- **The model is a hook, and everything it computes is not.** `useChartModel`
+  measures labels with the font and does nothing else of consequence — the
+  planning either side of the measurement lives in `core/geometry/chart-layout.ts`
+  and is unit-tested. `bun test` cannot render a `.tsx`, so logic left in one
+  is logic nothing checks.
+
+- **Skia text for axis labels; React Native text for legends and tooltips.**
+  The distinction is whether it moves *with* the canvas. Under a pan the marks
+  move on the UI thread, and an overlaid RN label would move on the JavaScript
+  thread and lag by a frame — the most visible bug a chart can have. A legend
+  sits beside the canvas and is static relative to it, so it belongs in a view
+  where it can have a type scale and a colour token.
+
+- **The grid is one path, not one node per rule.** Two axes at eight ticks each
+  is sixteen Skia nodes for what is a single stroke, and node count is what a
+  Skia tree costs.
+
+- **A bar's width comes from the chart, not from a band scale.** The root
+  measures `xStep` — the smallest gap between x values — and publishes the x
+  positions; `resolveBand` turns those into a step and a bandwidth on the
+  canvas. The root also has to pad the x domain by half a step
+  (`domainPadding={{ x: 0.5 }}`) or the outermost bars straddle the plot's
+  edge; `ChartBar` warns in development when it does not.
+
+- **The root stacks; the stack mark only draws.** `stackKeys` names the series
+  to stack, the model stacks them in data space so the y domain covers the
+  totals, and `ChartBarStack` reads `chart.stacked`. A mark that stacked for
+  itself would draw past the top of the plot. `points[key]` stays the raw
+  series, which is what a tooltip prints.
+
+- **A group and a stack are one path per series, not one per bar.** Node count
+  is what a Skia tree costs, and a series' bars morph together anyway. The
+  price is that per-datum colour and opacity are not offered — `barOptions` on
+  a stack gives per-segment corners, which a path can carry, and nothing else.
+
+- **`ChartBarGroup` takes `yKeys`, not child marks.** The group has to know how
+  many series there are before any of them can know its offset, and reading
+  that off children is the same information arriving later. A Skia tree gains
+  nothing from identity matching.
+
+- **`orientation` is resolved once, in the model.** The hook plans the
+  category axis and the value axis by role, and `placeAxisRoles` puts them on
+  the canvas — categories down y, top first, when horizontal. Every mark then
+  reads `chart.orientation` and hands it to its shape builder; none of them
+  swaps a coordinate itself. `xScale` and `yScale` on the context are always
+  the canvas axes, so a mark that wants the value scale asks by role.
+
+- **`useChartContext` throws outside a chart.** A mark that silently rendered
+  nothing would leave a blank canvas with no error, and a Skia tree has no
+  element inspector to look at.
+
+- **The scrub model is rebuilt on the JavaScript thread and read on the UI
+  one.** The root packs bounds, x positions, the scale descriptor and each
+  series' cubic runs into a single shared value whenever the data changes. The
+  pan then reads plain numbers every frame, with no bridge hop — which is what
+  lets the dot keep up with a fast drag.

package/src/cartesian/axes/chart-x-axis.tsx

@@ -0,0 +1,52 @@
+import { Text } from "@shopify/react-native-skia";
+import type { ReactElement } from "react";
+import { anchorX, anchorY } from "../../core/text/label-anchor";
+import { measureLabelWidth } from "../../skia/font";
+import { useChartContext } from "../cartesian-chart.context";
+
+export type ChartXAxisProps = {
+	readonly color: string;
+	/** Space between the plot rect and the labels. */
+	readonly tickPadding?: number;
+	readonly opacity?: number;
+};
+
+/**
+ * Tick labels below the plot rect.
+ *
+ * Skia text, not React Native text. Under a pan or a zoom the marks move on
+ * the UI thread; overlaid RN labels would move on the JavaScript thread and
+ * lag them by a frame, which is the most visible bug a chart can have. Labels
+ * that sit *beside* the canvas rather than moving with it — a legend, a
+ * tooltip — are the opposite case and belong in RN views.
+ *
+ * Draws nothing while `font` is `null`. `matchFont` resolves synchronously in
+ * practice, but a chart that renders before it would otherwise crash rather
+ * than come up a frame late.
+ */
+export function ChartXAxis({ color, tickPadding = 6, opacity }: ChartXAxisProps): ReactElement | null {
+	const { xTicks, xLabels, bounds, font, fontMetrics } = useChartContext();
+	if (font === null || xLabels.length === 0) return null;
+
+	return (
+		<>
+			{xTicks.map((tick, index) => {
+				const label = xLabels[index];
+				if (label === undefined || label === "" || !Number.isFinite(tick.position)) return null;
+				return (
+					<Text
+						color={color}
+						font={font}
+						key={`${tick.value}-${label}`}
+						opacity={opacity}
+						text={label}
+						x={anchorX(tick.position, measureLabelWidth(font, label), "middle")}
+						y={anchorY(bounds.bottom, fontMetrics, "below", tickPadding)}
+					/>
+				);
+			})}
+		</>
+	);
+}
+
+ChartXAxis.displayName = "DelacourCharts.ChartXAxis";

package/src/cartesian/axes/chart-y-axis.tsx

@@ -0,0 +1,56 @@
+import { Text } from "@shopify/react-native-skia";
+import type { ReactElement } from "react";
+import { anchorX, anchorY } from "../../core/text/label-anchor";
+import { measureLabelWidth } from "../../skia/font";
+import { useChartContext } from "../cartesian-chart.context";
+
+export type ChartYAxisProps = {
+	readonly color: string;
+	/** Space between the labels and the plot rect. */
+	readonly tickPadding?: number;
+	readonly side?: "left" | "right";
+	readonly opacity?: number;
+};
+
+/**
+ * Tick labels beside the plot rect.
+ *
+ * Right-aligned against the plot's left edge, so the labels form a clean
+ * column whatever their widths — a left-aligned y axis puts "5" and "1000"
+ * on different vertical lines and reads as ragged.
+ *
+ * Vertically the glyph box is centred on the tick rather than the baseline;
+ * `anchorY`'s `middle` is what handles that, and skipping it puts every label
+ * a third of a line-height below its own gridline.
+ */
+export function ChartYAxis({ color, tickPadding = 6, side = "left", opacity }: ChartYAxisProps): ReactElement | null {
+	const { yTicks, yLabels, bounds, font, fontMetrics } = useChartContext();
+	if (font === null || yLabels.length === 0) return null;
+
+	return (
+		<>
+			{yTicks.map((tick, index) => {
+				const label = yLabels[index];
+				if (label === undefined || label === "" || !Number.isFinite(tick.position)) return null;
+				const width = measureLabelWidth(font, label);
+				return (
+					<Text
+						color={color}
+						font={font}
+						key={`${tick.value}-${label}`}
+						opacity={opacity}
+						text={label}
+						x={
+							side === "left"
+								? anchorX(bounds.left - tickPadding, width, "end")
+								: anchorX(bounds.right + tickPadding, width, "start")
+						}
+						y={anchorY(tick.position, fontMetrics, "middle")}
+					/>
+				);
+			})}
+		</>
+	);
+}
+
+ChartYAxis.displayName = "DelacourCharts.ChartYAxis";

package/src/cartesian/cartesian-chart.context.tsx

@@ -0,0 +1,43 @@
+import { createContext, useContext } from "react";
+import type { ChartContextValue } from "./cartesian-chart.types";
+
+/**
+ * The resolved chart, published to its children.
+ *
+ * The provider is rendered **inside** the Skia canvas. That is what makes this
+ * work at all: `<Canvas>` mounts a second React reconciler, so a provider
+ * placed above it is invisible to Skia children below it. Context resolves by
+ * which reconciler renders the *provider node*, not by where the context
+ * object was created — so mounting the provider as a child of the canvas puts
+ * it in the Skia tree and consumers below resolve it normally.
+ *
+ * It is exported rather than hidden behind its hook because a consumer that
+ * wants its own context inside the canvas needs to do exactly the same thing,
+ * and needs something to copy.
+ */
+export const CartesianChartContext = createContext<ChartContextValue | null>(null);
+
+CartesianChartContext.displayName = "DelacourCharts.CartesianChartContext";
+
+/**
+ * The chart a mark is drawn in.
+ *
+ * Throws outside a chart rather than returning `null`. A mark that silently
+ * renders nothing is a blank canvas with no error, which is among the hardest
+ * things to diagnose in a Skia tree — there is no element inspector to look at.
+ */
+export function useChartContext(): ChartContextValue {
+	const value = useContext(CartesianChartContext);
+	if (value === null) {
+		throw new Error(
+			"[@delacour/react-native-charts] a chart mark was rendered outside a <CartesianChart>. " +
+				"Marks read the chart from context, so they have to be its children."
+		);
+	}
+	return value;
+}
+
+/** The chart, or `null` outside one. For a part that is legitimately optional. */
+export function useOptionalChartContext(): ChartContextValue | null {
+	return useContext(CartesianChartContext);
+}