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

package/src/polar/marks/pie-inset.tsx

@@ -0,0 +1,70 @@
+import { Path, type SkPath } from "@shopify/react-native-skia";
+import { type ReactElement, useMemo } from "react";
+import type { ChartAnimation } from "../../animation/animation.types";
+import { useAnimatedPath } from "../../animation/use-animated-path";
+import { buildSliceEdgePath } from "../../core/polar/build-slice-path";
+import { toSkPath } from "../../skia/build-path";
+import { usePolarContext } from "../polar-chart.context";
+
+export type PieInsetProps = {
+	readonly color: string;
+	readonly strokeWidth?: number;
+	readonly opacity?: number;
+	readonly animation?: ChartAnimation;
+};
+
+/**
+ * A hairline between neighbouring slices.
+ *
+ * One stroked `M L` per slice's start edge, plus the last slice's end edge
+ * when the slices do not close the circle. Drawn in the background colour it
+ * reads as a gap; drawn in a foreground colour it reads as a border.
+ *
+ * Nothing is drawn for fewer than two slices or for a slice that is the whole
+ * circle: there is no neighbour to separate, and a single line from the
+ * centre to 12 o'clock on a full disc is a scratch, not an inset.
+ */
+export function PieInset({ color, strokeWidth = 1, opacity, animation }: PieInsetProps): ReactElement | null {
+	const { slices, circleSweepDegrees, animation: chartAnimation } = usePolarContext();
+
+	const edges = useMemo<SkPath[]>(() => {
+		if (slices.length < 2 || slices.some((slice) => slice.sliceIsEntireCircle)) return [];
+		const paths = slices.map((slice) => toSkPath(buildSliceEdgePath(slice, "start")));
+		const last = slices[slices.length - 1];
+		if (last !== undefined && circleSweepDegrees < 360) paths.push(toSkPath(buildSliceEdgePath(last, "end")));
+		return paths;
+	}, [slices, circleSweepDegrees]);
+
+	if (edges.length === 0) return null;
+
+	return (
+		<>
+			{edges.map((edge, index) => (
+				<InsetEdge
+					animation={animation ?? chartAnimation}
+					color={color}
+					key={`${edges.length}-${index}`}
+					opacity={opacity}
+					path={edge}
+					strokeWidth={strokeWidth}
+				/>
+			))}
+		</>
+	);
+}
+
+PieInset.displayName = "DelacourCharts.PieInset";
+
+type InsetEdgeProps = {
+	readonly path: SkPath;
+	readonly color: string;
+	readonly strokeWidth: number;
+	readonly opacity: number | undefined;
+	readonly animation: ChartAnimation;
+};
+
+/** One edge, morphing with its slice. A component so each edge owns a hook. */
+function InsetEdge({ path, color, strokeWidth, opacity, animation }: InsetEdgeProps): ReactElement {
+	const animated = useAnimatedPath(path, animation);
+	return <Path color={color} opacity={opacity} path={animated} strokeWidth={strokeWidth} style="stroke" />;
+}

package/src/polar/marks/pie-label.tsx

@@ -0,0 +1,71 @@
+import { type SkFont, Text } from "@shopify/react-native-skia";
+import type { ReactElement, ReactNode } from "react";
+import { sliceLabelPosition } from "../../core/polar/label-position";
+import type { PieSliceData } from "../../core/polar/polar.types";
+import { anchorX, anchorY } from "../../core/text/label-anchor";
+import { fontMetrics, measureLabelWidth } from "../../skia/font";
+import { usePolarContext } from "../polar-chart.context";
+
+export type PieLabelProps = {
+	readonly color: string;
+	/** Overrides the chart's font. */
+	readonly font?: SkFont | null;
+	/** Across the annulus: 0 the inner edge, 1 the outer, more than 1 outside. */
+	readonly radiusOffset?: number;
+	/** The text for a slice. Defaults to its label. */
+	readonly formatLabel?: (slice: PieSliceData) => string;
+	/** Slices narrower than this, in degrees, get no label. */
+	readonly minSweep?: number;
+	readonly opacity?: number;
+	/** Skia paint children — a shader for the text. */
+	readonly children?: ReactNode;
+};
+
+/**
+ * A text label on every slice wide enough to hold one.
+ *
+ * Skia text, for the reason the axes use it: the labels move with the canvas.
+ * Draws nothing while the font is `null`, and nothing on a slice narrower than
+ * `minSweep` — a label on a two-degree slice lands on its neighbours, and
+ * three overlapping labels are less legible than none.
+ */
+export function PieLabel({
+	color,
+	font,
+	radiusOffset = 0.5,
+	formatLabel,
+	minSweep = 0,
+	opacity,
+	children,
+}: PieLabelProps): ReactElement | null {
+	const chart = usePolarContext();
+	const face = font === undefined ? chart.font : font;
+	if (face === null) return null;
+	const metrics = font === undefined ? chart.fontMetrics : fontMetrics(face);
+
+	return (
+		<>
+			{chart.slices.map((slice) => {
+				if (slice.sweepAngle <= 0 || slice.sweepAngle < minSweep) return null;
+				const text = formatLabel === undefined ? slice.label : formatLabel(slice);
+				if (text === "") return null;
+				const position = sliceLabelPosition(slice, radiusOffset);
+				return (
+					<Text
+						color={color}
+						font={face}
+						key={slice.index}
+						opacity={opacity}
+						text={text}
+						x={anchorX(position.x, measureLabelWidth(face, text), "middle")}
+						y={anchorY(position.y, metrics, "middle")}
+					>
+						{children}
+					</Text>
+				);
+			})}
+		</>
+	);
+}
+
+PieLabel.displayName = "DelacourCharts.PieLabel";

package/src/polar/marks/pie-slice.tsx

@@ -0,0 +1,82 @@
+import { Path, type SkPath } from "@shopify/react-native-skia";
+import { type ReactElement, type ReactNode, useMemo } from "react";
+import type { ChartAnimation } from "../../animation/animation.types";
+import { useAnimatedPath } from "../../animation/use-animated-path";
+import { buildSlicePath } from "../../core/polar/build-slice-path";
+import type { PieSliceData } from "../../core/polar/polar.types";
+import { toSkPath } from "../../skia/build-path";
+import { usePolarContext } from "../polar-chart.context";
+
+export type PieSliceProps = {
+	/** Which slice to draw. Read from the chart's context. */
+	readonly index?: number;
+	/** The slice to draw, when it is not coming from context. */
+	readonly slice?: PieSliceData;
+	/** A flat fill. Leave it out when a child shader supplies the paint. */
+	readonly color?: string;
+	readonly opacity?: number;
+	readonly animation?: ChartAnimation;
+	/** Skia paint children — a gradient, a shader. */
+	readonly children?: ReactNode;
+};
+
+/**
+ * One filled slice.
+ *
+ * Takes `index` or `slice`, never needing both, the way a cartesian mark takes
+ * `yKey` or `points`. Fill only: a stroke on a slice would outline its arcs as
+ * well as its edges, and the hairline between slices is `PieInset`'s job.
+ *
+ * On mount it grows out of the centre — the entrance path is the same slice
+ * at radius zero, which shares its eleven verbs and so interpolates. Without
+ * that a pie would simply be there on the first frame, and a pie that morphs
+ * on every later change but not on its first looks like the mount is broken.
+ */
+export function PieSlice({ index, slice, color, opacity, animation, children }: PieSliceProps): ReactElement | null {
+	const chart = usePolarContext();
+	const target = slice ?? (index === undefined ? undefined : chart.slices[index]);
+
+	const path = useMemo(() => (target === undefined ? null : toSkPath(buildSlicePath(target))), [target]);
+	const entrance = useMemo(
+		() => (target === undefined ? null : toSkPath(buildSlicePath({ ...target, radius: 0, innerRadius: 0 }))),
+		[target]
+	);
+
+	if (path === null || entrance === null) return null;
+
+	return (
+		<AnimatedSlice
+			animation={animation ?? chart.animation}
+			color={color}
+			entrance={entrance}
+			opacity={opacity}
+			path={path}
+		>
+			{children}
+		</AnimatedSlice>
+	);
+}
+
+PieSlice.displayName = "DelacourCharts.PieSlice";
+
+type AnimatedSliceProps = {
+	readonly path: SkPath;
+	readonly entrance: SkPath;
+	readonly animation: ChartAnimation;
+	readonly color: string | undefined;
+	readonly opacity: number | undefined;
+	readonly children: ReactNode;
+};
+
+/**
+ * Split from `PieSlice` so the hook order holds: a slice with no target
+ * returns early, and `useAnimatedPath` cannot sit after an early return.
+ */
+function AnimatedSlice({ path, entrance, animation, color, opacity, children }: AnimatedSliceProps): ReactElement {
+	const animated = useAnimatedPath(path, animation, { enterFrom: entrance });
+	return (
+		<Path color={color} opacity={opacity} path={animated} style="fill">
+			{children}
+		</Path>
+	);
+}

package/src/polar/marks/pie-slices.tsx

@@ -0,0 +1,60 @@
+import type { ReactElement, ReactNode } from "react";
+import type { ChartAnimation } from "../../animation/animation.types";
+import type { PieSliceData } from "../../core/polar/polar.types";
+import { sliceOpacity } from "../../core/polar/slice-opacity";
+import { usePolarContext } from "../polar-chart.context";
+import { PieSlice } from "./pie-slice";
+
+export type PieSlicesProps = {
+	/** One per slice, cycled when there are more slices than colours. */
+	readonly colors: readonly string[];
+	readonly opacity?: number;
+	/** Opacity of every slice but the selected one, while one is selected. */
+	readonly dimUnselected?: number;
+	readonly animation?: ChartAnimation;
+	/** Skia paint children for each slice — a gradient, a shader. */
+	readonly children?: (slice: PieSliceData, color: string) => ReactNode;
+};
+
+/**
+ * Every slice of the chart, one `PieSlice` each.
+ *
+ * Colours cycle rather than stop: a palette of five under twenty slices
+ * colours all twenty, and a slice with no colour would be an invisible wedge
+ * that still takes taps.
+ *
+ * While `selectedIndex` is set, the other slices draw at `dimUnselected`. The
+ * default dims them, because a selection that changes nothing on screen looks
+ * like a tap that missed. `1` turns it off.
+ */
+export function PieSlices({
+	colors,
+	opacity = 1,
+	dimUnselected = 0.4,
+	animation,
+	children,
+}: PieSlicesProps): ReactElement | null {
+	const { slices, selectedIndex } = usePolarContext();
+	if (colors.length === 0) return null;
+
+	return (
+		<>
+			{slices.map((slice) => {
+				const color = colors[slice.index % colors.length] as string;
+				return (
+					<PieSlice
+						animation={animation}
+						color={color}
+						key={slice.index}
+						opacity={sliceOpacity(slice.index, selectedIndex, opacity, dimUnselected)}
+						slice={slice}
+					>
+						{children?.(slice, color)}
+					</PieSlice>
+				);
+			})}
+		</>
+	);
+}
+
+PieSlices.displayName = "DelacourCharts.PieSlices";

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

@@ -0,0 +1,37 @@
+import { createContext, useContext } from "react";
+import type { PolarContextValue } from "./polar-chart.types";
+
+/**
+ * The resolved polar chart, published to its children.
+ *
+ * Rendered **inside** the Skia canvas, for the reason `CartesianChartContext`
+ * documents: context resolves by which reconciler renders the provider node,
+ * so a provider among the canvas' children is visible to the Skia marks below
+ * it and one above the canvas is not.
+ */
+export const PolarChartContext = createContext<PolarContextValue | null>(null);
+
+PolarChartContext.displayName = "DelacourCharts.PolarChartContext";
+
+/**
+ * The chart a pie mark is drawn in.
+ *
+ * Throws outside one rather than returning `null`: a mark that silently draws
+ * nothing is a blank canvas with no error, and a Skia tree has no element
+ * inspector to look at.
+ */
+export function usePolarContext(): PolarContextValue {
+	const value = useContext(PolarChartContext);
+	if (value === null) {
+		throw new Error(
+			"[@delacour/react-native-charts] a pie mark was rendered outside a <PolarChart>. " +
+				"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 useOptionalPolarContext(): PolarContextValue | null {
+	return useContext(PolarChartContext);
+}

package/src/polar/polar-chart.tsx

@@ -0,0 +1,91 @@
+import { Canvas } from "@shopify/react-native-skia";
+import { type ReactElement, useMemo, useRef } from "react";
+import { StyleSheet, View } from "react-native";
+import { Gesture, type GestureType } from "react-native-gesture-handler";
+import { useCanvasSize } from "../cartesian/hooks/use-canvas-size";
+import type { ChartRow } from "../core/chart.types";
+import { sliceIndexAt } from "../core/polar/slice-index-at";
+import { ChartGestureOverlay } from "../gesture/gesture-overlay";
+import { usePolarModel } from "./hooks/use-polar-model";
+import { PolarChartContext } from "./polar-chart.context";
+import type { LabelKeyOf, PolarChartProps, PolarContextValue, PolarRenderArgs, ValueKeyOf } from "./polar-chart.types";
+
+/**
+ * A polar chart: a circle on the canvas, cut into slices, and whatever marks
+ * you place.
+ *
+ * Mounted the way `CartesianChart` is — measuring view, canvas, the provider
+ * **inside** the canvas, an overlay for touch — and for the same reasons; see
+ * that root. The one difference is the gesture: a pie has no scrub, so the
+ * overlay appears only when `onSlicePress` is given, and it carries a tap.
+ *
+ * The tap runs its callback on the JavaScript thread (`runOnJS(true)`). A
+ * scrub reads a shared value every frame of a drag and has to stay on the UI
+ * thread; a tap fires once, its result goes straight into React state, and
+ * hopping threads to compute an index nobody reads on the UI side would be a
+ * hop for nothing.
+ */
+export function PolarChart<Row extends ChartRow, const VK extends ValueKeyOf<Row>, const LK extends LabelKeyOf<Row>>(
+	props: PolarChartProps<Row, VK, LK>
+): ReactElement {
+	const { data, valueKey, labelKey, children, onSlicePress, ...rest } = props;
+
+	const { size, onLayout } = useCanvasSize();
+
+	const model = usePolarModel({
+		...rest,
+		data: data as readonly ChartRow[],
+		valueKey,
+		labelKey,
+		canvas: size,
+	});
+
+	const gesture = useSliceTap(model, onSlicePress);
+
+	const content = typeof children === "function" ? children({ ...model, data } as PolarRenderArgs<Row>) : children;
+
+	return (
+		<View onLayout={onLayout} style={styles.root}>
+			<Canvas style={StyleSheet.absoluteFill}>
+				<PolarChartContext.Provider value={model}>{content}</PolarChartContext.Provider>
+			</Canvas>
+			{gesture === null ? null : <ChartGestureOverlay gesture={gesture} />}
+		</View>
+	);
+}
+
+PolarChart.displayName = "DelacourCharts.PolarChart";
+
+/**
+ * A tap that reports the slice under the finger, or `null` when there is none.
+ *
+ * The callback is read through a ref so an inline arrow — the usual way to
+ * pass it — does not rebuild the gesture on every render, and the gesture is
+ * keyed on the model so a data change is picked up by the next tap.
+ */
+function useSliceTap(
+	model: PolarContextValue,
+	onSlicePress: ((index: number | null) => void) | undefined
+): GestureType | null {
+	const handler = useRef(onSlicePress);
+	handler.current = onSlicePress;
+	const enabled = onSlicePress !== undefined;
+
+	return useMemo(() => {
+		if (!enabled) return null;
+		const { center, innerRadius, radius, slices } = model;
+		const starts = slices.map((slice) => slice.startAngle);
+		const sweeps = slices.map((slice) => slice.sweepAngle);
+		return Gesture.Tap()
+			.runOnJS(true)
+			.onEnd((event, success) => {
+				if (!success) return;
+				const index = sliceIndexAt(event.x, event.y, center.x, center.y, innerRadius, radius, starts, sweeps);
+				handler.current?.(index === -1 ? null : index);
+			});
+	}, [enabled, model]);
+}
+
+const styles = StyleSheet.create({
+	root: { flex: 1, overflow: "hidden" },
+});

package/src/polar/polar-chart.types.ts

@@ -0,0 +1,82 @@
+import type { SkFont } from "@shopify/react-native-skia";
+import type { ReactNode } from "react";
+import type { ChartAnimation } from "../animation/animation.types";
+import type { ChartRow, ChartSize } from "../core/chart.types";
+import type { InnerRadius, PieSliceData, PolarPoint } from "../core/polar/polar.types";
+import type { LabelMetrics } from "../core/text/label-anchor";
+import type { SidedNumber } from "../core/util/sided-number";
+
+/**
+ * Fields that can size a slice — a number, or nothing.
+ *
+ * The `string extends keyof Row` guard widens back to `string` for a row typed
+ * only as an index signature; see `XKeyOf` in the cartesian types for why a
+ * caller who has not typed their rows would otherwise be unable to name a key.
+ */
+export type ValueKeyOf<Row extends ChartRow> = string extends keyof Row
+	? string
+	: {
+			[Key in keyof Row]-?: Row[Key] extends number | null | undefined ? Key : never;
+		}[keyof Row] &
+			string;
+
+/** Fields that can name a slice. Widens the same way. */
+export type LabelKeyOf<Row extends ChartRow> = string extends keyof Row
+	? string
+	: {
+			[Key in keyof Row]-?: Row[Key] extends string | number | null | undefined ? Key : never;
+		}[keyof Row] &
+			string;
+
+/** Everything a mark or a render prop can read about the chart. */
+export type PolarContextValue = {
+	/** One per row, in data order, zero-sweep slices included. */
+	readonly slices: readonly PieSliceData[];
+	readonly center: PolarPoint;
+	readonly radius: number;
+	readonly innerRadius: number;
+	readonly startAngle: number;
+	readonly circleSweepDegrees: number;
+	/** The whole canvas, including the padding. */
+	readonly canvas: ChartSize;
+	/** `null` until the font resolves; a label mark then draws nothing. */
+	readonly font: SkFont | null;
+	readonly lineHeight: number;
+	/** The font's ascent and descent, for placing a label by its glyph box. */
+	readonly fontMetrics: LabelMetrics;
+	readonly animation: ChartAnimation;
+	/** The slice the caller has singled out, or `null`. */
+	readonly selectedIndex: number | null;
+	/** Whether there is room to draw in. */
+	readonly ready: boolean;
+};
+
+export type PolarRenderArgs<Row extends ChartRow> = PolarContextValue & {
+	readonly data: readonly Row[];
+};
+
+export type PolarChartProps<Row extends ChartRow, VK extends ValueKeyOf<Row>, LK extends LabelKeyOf<Row>> = {
+	readonly data: readonly Row[];
+	/** The field a slice's size comes from. */
+	readonly valueKey: VK;
+	/** The field a slice's label comes from. Without it, the row's index. */
+	readonly labelKey?: LK;
+	/** The donut hole — points, or a percentage of the radius. */
+	readonly innerRadius?: InnerRadius;
+	/** 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;
+	/** An explicit diameter. Otherwise the largest circle the canvas holds. */
+	readonly size?: number;
+	/** Space between the canvas edge and the circle. */
+	readonly padding?: SidedNumber;
+	readonly animation?: ChartAnimation;
+	readonly font?: SkFont | null;
+	/** The slice to single out. Marks read it; the root does nothing with it. */
+	readonly selectedIndex?: number | null;
+	/** Called with the tapped slice's index, or `null` for a tap outside every slice. */
+	readonly onSlicePress?: (index: number | null) => void;
+	/** Skia children, or a function of the resolved chart. */
+	readonly children?: ReactNode | ((args: PolarRenderArgs<Row>) => ReactNode);
+};

package/src/purity.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, test } from "bun:test";
+import { join } from "node:path";
+import { read, relative, SRC, sourceFiles } from "./source-tree.test";
+
+/**
+ * Modules `src/core` may not import a runtime value from.
+ *
+ * React Native ships Flow-typed source that Bun's transpiler cannot parse, so
+ * one of these anywhere under `core/` takes the *entire* suite down — and the
+ * error names whichever file happened to import the offender first, not the
+ * file that broke the rule. Hence this test: it fails first, and it fails by
+ * name.
+ *
+ * Type-only imports are fine. Types are erased before Bun sees them.
+ */
+const FORBIDDEN = [
+	"react",
+	"react-native",
+	"react-dom",
+	"@shopify/react-native-skia",
+	"react-native-reanimated",
+	"react-native-gesture-handler",
+	"react-native-worklets",
+];
+
+const IMPORT = /^\s*import\s+([\s\S]*?)\s*from\s*["']([^"']+)["']/gm;
+
+/** Whether an import clause brings in nothing but types. */
+function isTypeOnly(clause: string): boolean {
+	const trimmed = clause.trim();
+	if (trimmed.startsWith("type ")) return true;
+
+	const named = trimmed.match(/^\{([\s\S]*)\}$/);
+	if (!named) return false;
+
+	return (named[1] as string)
+		.split(",")
+		.map((specifier) => specifier.trim())
+		.filter((specifier) => specifier !== "")
+		.every((specifier) => specifier.startsWith("type "));
+}
+
+describe("core purity", () => {
+	const files = sourceFiles(join(SRC, "core"));
+
+	test("finds the core modules, so a broken walker cannot pass silently", () => {
+		expect(files.length).toBeGreaterThan(20);
+	});
+
+	test("no module under src/core imports a React Native runtime value", () => {
+		const offenders: string[] = [];
+
+		for (const file of files) {
+			const source = read(file);
+			IMPORT.lastIndex = 0;
+			for (let match = IMPORT.exec(source); match !== null; match = IMPORT.exec(source)) {
+				const clause = match[1] as string;
+				const specifier = match[2] as string;
+				const root = specifier.startsWith("@") ? specifier.split("/").slice(0, 2).join("/") : specifier.split("/")[0];
+				if (!FORBIDDEN.includes(root as string)) continue;
+				if (isTypeOnly(clause)) continue;
+				offenders.push(`${relative(file)} imports ${specifier}`);
+			}
+		}
+
+		expect(offenders).toEqual([]);
+	});
+
+	test("no module under src/core reaches sideways into src/skia", () => {
+		const offenders = files
+			.filter((file) => /from\s+["'][^"']*\/skia\//.test(read(file)))
+			.map((file) => relative(file));
+		expect(offenders).toEqual([]);
+	});
+});

package/src/skia/AGENTS.md

@@ -0,0 +1,39 @@
+# skia
+
+The only folder that imports Skia values. Four small translators.
+
+Everything below `core/` computes numbers; this turns them into things Skia can
+draw. Keeping the surface this narrow is deliberate — Skia 2.x renamed and
+restructured a good deal of the path API, so every future migration is these
+files and nothing else.
+
+## Files
+
+| Path | What |
+| --- | --- |
+| `build-path.ts` | An SVG path string from `core/curve` into an `SkPath` |
+| `font.ts` | A system font, label advance widths, and line height |
+
+## Design
+
+- **A path Skia cannot parse becomes an empty path, not `null`.** Every caller
+  renders the result, and an empty path draws nothing — which is a chart with a
+  missing series rather than a crash.
+
+- **No font ships with this package.** `matchFont` resolves against the
+  operating system's own families, so a chart is legible with no `expo-font`,
+  no config plugin and no Metro asset resolver in the consuming app. The trade
+  is that iOS' system font is not Android's, so the same labels measure
+  differently and the plot rect differs by a few points across platforms. That
+  is correct, but it does mean a screenshot baseline has to be per-platform.
+
+- **Label width is the sum of glyph advances, not `measureText`.**
+  `measureText` returns the *drawn* bounds, which exclude side bearings, so a
+  tick reading "10" measures narrower than the space it occupies and every
+  axis gutter comes out a point or two too tight. `getTextWidth` gives the
+  advance directly but is deprecated in Skia 2.x, so the advances are summed
+  from `getGlyphWidths`.
+
+- **Line height comes from the font's metrics, not its point size.** An axis
+  gutter has to reserve the full glyph box — ascent plus descent — and the
+  nominal size is neither.

package/src/skia/build-path.ts

@@ -0,0 +1,22 @@
+import { Skia, type SkPath } from "@shopify/react-native-skia";
+
+/** A path with nothing in it — what an empty series draws. */
+export function emptyPath(): SkPath {
+	return Skia.Path.Make();
+}
+
+/**
+ * An SVG path string as a Skia path.
+ *
+ * The string comes from `d3-shape` in `core/curve`, which is the one place
+ * this package pays for taking d3: the geometry is serialised to text and
+ * parsed straight back. It happens once per data change, not per frame.
+ *
+ * A string Skia cannot parse yields an empty path rather than `null`. Every
+ * caller renders it, and an empty path draws nothing — which is a chart with a
+ * missing series, not a crash.
+ */
+export function toSkPath(svg: string): SkPath {
+	if (svg === "") return Skia.Path.Make();
+	return Skia.Path.MakeFromSVGString(svg) ?? Skia.Path.Make();
+}