@delacour/react-native-ui 0.1.0-alpha.3

package/src/components/chart/AGENTS.md

@@ -0,0 +1,210 @@
+# Chart
+
+Skia charts wearing the theme's five-colour series ramp — the skin over
+[`@delacour/react-native-charts`](../../../../charts/AGENTS.md), which does the drawing and
+knows nothing about tokens.
+
+`import { Chart, PieChart } from "@delacour/react-native-ui/chart";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/chart` |
+| `chart.tsx` | The root, the child partition, and the single `Object.assign` |
+| `chart.context.tsx` | The context, mounted twice — see below |
+| `chart.types.ts` | `ChartConfig`, `ChartSeriesConfig`, `ChartResolvedSeries` |
+| `chart.variants.ts` | The slotted `tv()`, the ramp, and every pure resolver |
+| `chart.variants.test.ts` | Including the assertion that the ramp tokens exist |
+| `use-chart-font.ts` | `--font-sans` into an `SkFont` |
+| `use-chart-palette.ts` | The eight fixed `useThemeColor` slots a series list resolves through |
+| `chart-grid.tsx`, `chart-line.tsx`, `chart-area.tsx` | Skia marks; `Chart.Area` takes a `stackId` |
+| `chart-bar.tsx` | `Chart.Bar` — a spec the root collects, and a lone engine bar when reached unrouted |
+| `chart-bars.tsx` | Internal `ChartBars`: every `Chart.Bar` drawn as one bar, group or stack, spliced in by the root |
+| `chart-scatter.tsx`, `chart-candlestick.tsx` | Skia marks — dots per datum, and O/H/L/C candles in the sentiment tokens |
+| `chart-x-axis.tsx`, `chart-y-axis.tsx` | Skia axis labels |
+| `chart-legend.tsx`, `chart-tooltip.tsx` | React Native, around and over the canvas |
+| `chart-tooltip-dot.tsx`, `chart-tooltip-x.tsx`, `chart-tooltip-y.tsx` | Skia cursor marks, named under the tooltip; `.X` is a band over bars |
+| `pie-chart.tsx` | The second root: `PieChart`, its child partition, and its `Object.assign` |
+| `pie-chart.context.tsx` | The pie's context, mounted twice the same way; `useChartSeries` in `chart.context.tsx` reads either |
+| `pie-chart-slice.tsx`, `pie-chart-label.tsx` | Skia marks — the wedges with a hairline between them, and a label per wedge |
+| `pie-chart-center.tsx`, `pie-chart-tooltip.tsx` | React Native, over the canvas — the donut hole's content and the tap readout |
+
+## Design
+
+- **Skia's `<Canvas>` is a second React reconciler, so every theme lookup
+  happens in the root, above it.** A hook called inside the canvas has no
+  Uniwind provider above it and resolves nothing. `ChartRoot` calls
+  `useThemeColor` for the series ramp, the grid and the axis labels, and the
+  marks receive resolved strings as plain props. This is the single most
+  important thing to know before editing anything in this folder.
+
+- **The context is mounted twice, from one value.** Once around the React
+  Native subtree — legend and tooltip — and once *inside* the canvas around the
+  marks. Context resolves by which reconciler renders the provider node, so a
+  provider placed among the canvas' children lands in the Skia tree and marks
+  below it read it normally. That is why no context bridge and no `its-fine`
+  dependency is needed.
+
+- **A Skia mark takes values, never a `className`.** There is nothing for
+  `cn()` to merge on a canvas node and nothing Uniwind could compile. Only the
+  root, the legend and the tooltip accept one. Rule 7's `withUniwind` carve-out
+  is already spent on `icon.tsx`, and this component does not need a second: it
+  sizes the canvas by sizing the `View` around it.
+
+- **The `config` is the chart.** It names each series, sets the draw order, and
+  assigns the ramp by position, so a call site writes `yKey="desktop"` and
+  never a colour. The shape is shadcn's deliberately — rule 11's principle,
+  that a theme written for a web app moves across as a copy rather than a
+  translation, extends past token names to the component's own API.
+
+- **The ramp stops at five, and cycles.** `--chart-1` … `--chart-5` are what
+  shadcn's palette declares. A sixth token would not survive a pasted theme: a
+  designer copying a tweakcn palette supplies five, so a six-series chart would
+  draw five themed lines and one stranger — and one wrong-coloured line reads
+  as a bug in a way a slightly-off surface does not.
+
+- **At most eight *distinct* tokens per render, and it throws past that.**
+  `useThemeColor` is a hook and cannot run in a loop over a list whose length
+  changes, so `useChartPalette` resolves a fixed eight slots and
+  `partitionChartColors` dedupes the tokens and pads to reach them. The ramp
+  dedupes, so a pie of twenty ramp slices needs five. Literal colours bypass
+  the hook entirely, so a chart of twenty literal-coloured series is fine.
+  Eight is an opinion — a categorical legend stops being readable well before
+  it — not a limit of the technique.
+
+- **No new colour token.** The grid is `border`, which is what `Separator`
+  already paints a rule between regions with; axis labels are
+  `muted-foreground`, the colour every secondary label here uses; the tooltip
+  is `popover` on `border`. Rule 11 would require a `--chart-grid` to be
+  derived from a shadcn token anyway, and every borrowed palette would leave it
+  on this package's default.
+
+- **One new size token trio**, `--spacing-chart-sm/md/lg`. A canvas has no
+  intrinsic height, and without a token every chart on a dashboard would be a
+  different one. A height rather than `aspect-video` because two charts at
+  different widths must still line up — and registering the names with
+  tailwind-merge is what lets a caller's `className="aspect-video h-auto"`
+  cleanly win when they want that instead.
+
+- **The tooltip is a React Native view even though it floats over the canvas.**
+  It wants `popover`, `border`, the radius scale and the type scale, none of
+  which exist in Skia, and it is the part a caller most wants to restyle —
+  which a className cannot do to a Skia rounded rect. Axis labels are the
+  opposite call and stay in Skia: they move with the plot under a scrub, and an
+  overlaid React Native label would lag them by a frame.
+
+- **The tooltip's position rides the UI thread; its text does not.**
+  `useAnimatedStyle` follows the finger with no bridge hop, while the contents
+  update through `scheduleOnRN` only when the nearest datum index changes —
+  which is a few times per drag, not once per frame. Text on a shared value
+  would mean an animated `TextInput` with a `value` prop pretending to be a
+  label.
+
+- **The cursor marks are named under `Chart.Tooltip` but placed beside it.**
+  `Chart.Tooltip.Dot`, `.X` and `.Y` are one feature with the readout, so they
+  share its namespace — but the readout is a React Native view over the canvas
+  and the marks are drawn inside it. Nesting them
+  (`<Chart.Tooltip><Chart.Tooltip.Dot /></Chart.Tooltip>`) would put a canvas
+  node in a view's tree and draw nothing, with no error. They are siblings, and
+  `partitionChildren` routes them to opposite sides of the boundary.
+
+- **The marks snap to the datum, because the readout names one.** A rule
+  tracking the raw touch while the label beside it snaps says two different
+  things about one gesture. `snappedX` exists on the scrub for exactly this —
+  the crosshair, the dot and the number all read the same row. `glide` opts
+  into the continuous curve position, and the doc says what it costs.
+
+- **A dot rings itself in the chart's background.** A dot in the series colour
+  sitting on a line of that same colour is a slight thickening and nothing
+  more; the ring is what makes it a knob. That is why `surfaceColor` is
+  resolved in the root and carried on the context.
+
+- **Bars group by being siblings, and stack by sharing a `stackId`.** That
+  is shadcn's surface, and it is the reason `Chart.Bar` does not draw itself:
+  a bar's width depends on how many share its step, and its base on what is
+  stacked under it, so the root collects every `Chart.Bar`, resolves them with
+  `resolveBarLayout`, and mounts one internal `ChartBars` where the first bar
+  stood. A `Chart.Bar` wrapped in a caller's own component never reaches that
+  pass — it renders a single engine bar in its own colour, so it degrades to
+  "not grouped" rather than to nothing, but it cannot group or stack.
+
+- **One stack per chart.** Two `stackId`s, a stack beside a loose bar, or an
+  area stack beside a bar stack all throw by name. The engine's `stackKeys` is
+  one ordered list because the y domain has to cover one set of running
+  totals; a second stack would need a group of stacks, which nothing here
+  draws yet. Throwing beats drawing something that looks stacked and is not.
+
+- **Bar corners follow `--radius`.** `--radius` × a per-size multiplier, the
+  way `Checkbox`'s fill does, so a theme that squares its buttons squares its
+  bars. Only `--radius` survives to runtime — the scale is `@theme inline` —
+  so `BAR_RADIUS_MULTIPLIER` restates the steps and a test pins it against
+  `tokens.css`. A stack rounds only its outermost segment, so a column reads
+  as one bar rather than a pile of pills. `rounded={false}` is square.
+
+- **Candle sentiment is the top of the ramp.** A rising candle is `chart-1`
+  and a falling one `chart-2`, so a candlestick is painted from the same five
+  colours as every other chart and a pasted palette recolours it with them.
+  `success` and `destructive` were tried first and made the one chart on a
+  dashboard that ignored the ramp; a flat candle is `muted-foreground`. The root
+  resolves the three with three fixed hook calls, which is why the part takes
+  only literal overrides — a token given to a mark inside the canvas has
+  nothing to resolve it. The config names the close field alone, so the
+  legend says one price; the tooltip prints O/H/L/C, swatched by sentiment.
+
+- **The band is `Chart.Tooltip.X`, not a new part.** Over bars or candles the
+  rule becomes a wash one `xStep` wide, snapped to the datum, at a twelfth of
+  the axis colour. It is the same question — where along x are you — with an
+  answer sized to the mark: a hairline through the middle of a bar says less
+  than the whole column lit. `band` flips it either way. A cursor dot skips a
+  series that is only a bar, because a bar has no curve to sit on and the band
+  already picks out its column.
+
+- **Parts must be direct children of `<Chart>`.** The root partitions them by
+  component identity to decide what goes inside the canvas, what floats over
+  it and what sits under it — the technique `Spinner` uses on its own children.
+  An array from `.map()` is fine, since `Children.toArray` flattens it; a mark
+  wrapped in a caller's own component is not, because there is nothing to match
+  until it renders.
+
+- **Pie is a second root, not a part.** A pie shares nothing with a cartesian
+  plot on screen — no axes, no grid, no scrub, no x — and only the palette,
+  the legend and the font underneath, so `<Chart><Chart.Pie /></Chart>` would
+  be a root whose every other part throws under it. `PieChart` reuses
+  `chartVariants` for its frame heights, `useChartPalette` for its colours and
+  `ChartLegend` verbatim, through `useChartSeries`, which reads whichever
+  context is above it. Its categories are its **rows**: the ramp walks the
+  data, and the `config` is an optional override keyed by a row's name.
+
+- **A pie's colours dedupe before the hook.** Twenty slices walk the
+  five-token ramp, and `partitionChartColors` collects *distinct* tokens, so
+  that costs five of the eight slots rather than throwing at the ninth slice.
+  Rows are dropped for a negative or unreadable value **before** the engine
+  sees them, so the series, the values, the engine's slices and the legend all
+  agree on an index — a selection reports a position in the drawn order.
+
+- **`PieChart.Center` is a React Native view because it wants the type
+  scale.** What sits in a donut's hole is a headline number and a caption,
+  which want `text-2xl`, `foreground`, `muted-foreground` and a className —
+  none of which a Skia `<Text>` has. It centres over the frame, which is the
+  circle's centre because the root gives the engine no padding. It is named
+  `Center` rather than `Inset` because the engine's `PieInset` is the hairline
+  between slices, and the two would otherwise share a name for two things.
+
+- **The pie tooltip is selection-driven, not scrub-driven.** There is no x to
+  scrub along, so a tap selects a slice, the others dim, and the readout sits
+  just outside that slice's outer edge on its bisector — the position a
+  callout would point at. It needs no shared values: the selection changes a
+  few times a session, not once a frame. The slice geometry it reads is
+  resolved a second time in the root, with the engine's own pure functions on
+  the same frame, because the engine's context stops at the canvas boundary
+  and the tooltip lives outside it. A tap selects only when something would
+  show it — a `PieChart.Tooltip`, an `onSelect`, or a controlled
+  `selectedIndex` — so a pie with none of those takes no gesture at all.
+
+- **`@delacour/react-native-charts` is an optional peer, not a dependency.** A dependency
+  may be nested, and two copies of the engine mean two chart contexts — so a
+  correctly-nested `<Chart.Line>` would throw "must be used inside a `<Chart>`"
+  from inside a `<Chart>`. It also peer-depends on Skia, so a dependency would
+  install a native module for someone who only ever imported
+  `@delacour/react-native-ui/button`.

package/src/components/chart/chart-area.tsx

@@ -0,0 +1,93 @@
+import { ChartArea as EngineArea, useChartContext as useEngineChart } from "@delacour/react-native-charts";
+import type { CurveType } from "@delacour/react-native-charts/core";
+import type { ReactElement } from "react";
+import { useSeriesColor } from "./chart.context";
+import { resolveAreaFill } from "./chart.variants";
+
+export type ChartAreaProps = {
+	yKey: string;
+	/**
+	 * Stack this area on every sibling area that names the same id.
+	 *
+	 * A stacked area is a band from the top of the series below it to its
+	 * own running total, so the topmost edge reads as the sum. One stack per
+	 * chart, shared with the bars: a second id, or an area stack beside a bar
+	 * stack, throws by name.
+	 */
+	stackId?: string;
+	color?: string;
+	curve?: CurveType;
+	connectMissingData?: boolean;
+	/**
+	 * Fade the fill out towards the baseline instead of painting it flat.
+	 *
+	 * On by default for a lone area: a flat fill at any readable opacity
+	 * competes with the line it sits under. Off by default for a stacked band,
+	 * which has to read as a distinct region — see `resolveAreaFill`.
+	 */
+	gradient?: boolean;
+	/** Opacity of the fill — at its top when it fades, throughout when flat. */
+	opacity?: number;
+};
+
+/**
+ * The region under a series, in that series' colour.
+ *
+ * The fade is built from the resolved colour rather than from an opacity prop
+ * on the whole mark, so the top of the fill keeps the series' hue at reduced
+ * strength and the bottom reaches genuine transparency. Fading the node instead
+ * would leave a visible flat edge along the baseline.
+ *
+ * A stacked area reads its segments from the engine's context — the root
+ * stacked them in data space so the y domain covers the totals — and draws
+ * the band between each segment's base and its top. It is placed inside the
+ * canvas, which is why the engine's own context is in reach here. A band is
+ * painted flat: three fades over the full plot height blur into one wash,
+ * and nothing then says where one series ends and the next begins.
+ */
+export function ChartArea({
+	yKey,
+	stackId,
+	color,
+	curve,
+	connectMissingData,
+	gradient: gradientProp,
+	opacity: opacityProp,
+}: ChartAreaProps): ReactElement | null {
+	const resolved = useSeriesColor(yKey);
+	const { stacked } = useEngineChart();
+	const paint = color ?? resolved;
+	if (paint === undefined) return null;
+	const segments = stackId === undefined ? undefined : stacked[yKey];
+	const { gradient, opacity } = resolveAreaFill({
+		stacked: stackId !== undefined,
+		gradient: gradientProp,
+		opacity: opacityProp,
+	});
+
+	if (!gradient) {
+		return (
+			<EngineArea
+				color={paint}
+				connectMissingData={connectMissingData}
+				curve={curve}
+				opacity={opacity}
+				segments={segments}
+				yKey={yKey}
+			/>
+		);
+	}
+
+	return (
+		<EngineArea
+			connectMissingData={connectMissingData}
+			curve={curve}
+			gradient={[paint, "transparent"]}
+			opacity={opacity}
+			segments={segments}
+			yKey={yKey}
+		/>
+	);
+}
+
+ChartArea.displayName = "DelacourUI.Chart.Area";

package/src/components/chart/chart-bar.tsx

@@ -0,0 +1,103 @@
+import { type ChartBarLabels, ChartBar as EngineBar } from "@delacour/react-native-charts";
+import type { ChartPoint, CornerRadii } from "@delacour/react-native-charts/core";
+import type { ReactElement } from "react";
+import { useChart, useSeriesColor } from "./chart.context";
+import type { ChartDatum } from "./chart.types";
+
+export type ChartBarProps = {
+	/** Which series to draw. Names a key of the chart's `config`. */
+	yKey: string;
+	/**
+	 * Stack this bar on every sibling that names the same id.
+	 *
+	 * Sibling bars without one sit side by side within each step. One stack
+	 * per chart: a second id, or a stack beside a loose bar, throws by name.
+	 */
+	stackId?: string;
+	/** Overrides the series' colour from the config. A literal — the canvas can resolve no token. */
+	color?: string;
+	/**
+	 * Round the value end. On by default, following `--radius` at the chart's
+	 * size; `false` is square and a number is an exact radius in points.
+	 */
+	rounded?: boolean | number;
+	/**
+	 * Print each value against its bar.
+	 *
+	 * `true` prints the value as written; a function receives the value and
+	 * its row and returns the text, `""` to skip that bar. Drawn in the axis
+	 * colour with the axis font. A grouped or stacked chart draws no labels —
+	 * there is no room between the bars for them to read.
+	 */
+	labels?: boolean | ((value: number, row: ChartDatum) => string);
+	opacity?: number;
+};
+
+/**
+ * One bar per datum for one series, standing on zero.
+ *
+ * Placed as a direct child of `<Chart>`, it never renders itself: the root
+ * collects every `Chart.Bar`, lays them out together — grouped by being
+ * siblings, stacked by `stackId` — and draws them through one internal
+ * `Chart.Bars` in the first bar's place. That is what lets two bars know
+ * they share a step before either has rendered.
+ *
+ * Reached any other way — wrapped in a caller's own component, say — it
+ * draws a single engine bar in its series' colour. It degrades to "not
+ * grouped" rather than to nothing, but it cannot know its siblings, so a
+ * wrapped bar never groups or stacks. See AGENTS.md.
+ */
+export function ChartBar({ yKey, color, rounded, labels, opacity }: ChartBarProps): ReactElement | null {
+	const { barRadius, axisColor, data } = useChart();
+	const resolved = useSeriesColor(yKey);
+	const paint = color ?? resolved;
+	if (paint === undefined) return null;
+
+	return (
+		<EngineBar
+			color={paint}
+			labels={resolveBarLabels(labels, axisColor, data)}
+			opacity={opacity}
+			roundedCorners={barCorners(barRadiusFor(rounded, barRadius))}
+			yKey={yKey}
+		/>
+	);
+}
+
+ChartBar.displayName = "DelacourUI.Chart.Bar";
+
+/** The value end's two corners at one radius. The base stays square. */
+export function barCorners(radius: number): CornerRadii {
+	return { topLeft: radius, topRight: radius };
+}
+
+/**
+ * A bar's own `rounded` against the chart's resolved radius.
+ *
+ * The context already holds `--radius` × the size multiplier, so this only
+ * has to honour `false` and a number. `resolveBarRadius` does the same in
+ * the root, where `--radius` is readable; this runs where a part is not.
+ */
+export function barRadiusFor(rounded: boolean | number | undefined, barRadius: number): number {
+	if (rounded === false) return 0;
+	if (typeof rounded === "number") return Number.isFinite(rounded) ? Math.max(0, rounded) : 0;
+	return barRadius;
+}
+
+/** The engine's label options for a `labels` prop, or nothing. */
+export function resolveBarLabels(
+	labels: ChartBarProps["labels"],
+	color: string | undefined,
+	data: readonly ChartDatum[]
+): ChartBarLabels | undefined {
+	if (labels === undefined || labels === false || color === undefined) return undefined;
+	if (labels === true) return { color };
+	const format = labels;
+	return {
+		color,
+		formatLabel: (point: ChartPoint, index: number): string => {
+			const row = data[index];
+			return point.yValue === null || row === undefined ? "" : format(point.yValue, row);
+		},
+	};
+}

package/src/components/chart/chart-bars.tsx

@@ -0,0 +1,75 @@
+import {
+	type ChartBarStackSegmentInfo,
+	type ChartBarStackSegmentOptions,
+	ChartBar as EngineBar,
+	ChartBarGroup as EngineBarGroup,
+	ChartBarStack as EngineBarStack,
+} from "@delacour/react-native-charts";
+import { type ReactElement, useCallback, useMemo } from "react";
+import { useChart } from "./chart.context";
+import { barCorners, barRadiusFor, type ChartBarProps, resolveBarLabels } from "./chart-bar";
+
+export type ChartBarsProps = {
+	/** Every `Chart.Bar`'s props, in placement order. */
+	readonly bars: readonly ChartBarProps[];
+};
+
+/**
+ * Every `Chart.Bar` of the chart, drawn as one arrangement.
+ *
+ * Internal. The root collects the `Chart.Bar` children, resolves them with
+ * `resolveBarLayout`, and mounts one of these where the first bar stood —
+ * a single engine bar, a group or a stack, depending on what it found. A
+ * bar cannot draw itself because it cannot see its siblings, and the width
+ * of every bar depends on how many share a step.
+ *
+ * Colours come from each bar's series; `rounded` and `opacity` are read
+ * from the first bar that sets them, because a group is one path per series
+ * but one radius for all — corners that differed across a group would read
+ * as a mistake. A stack rounds only its outermost segment, so the column
+ * reads as one bar; every inner segment is square where it meets the next.
+ */
+export function ChartBars({ bars }: ChartBarsProps): ReactElement | null {
+	const { bars: layout, series, barRadius, axisColor, data } = useChart();
+
+	const radius = barRadiusFor(bars.find((bar) => bar.rounded !== undefined)?.rounded, barRadius);
+	const corners = useMemo(() => barCorners(radius), [radius]);
+	const opacity = bars.find((bar) => bar.opacity !== undefined)?.opacity;
+
+	const colors = useMemo(
+		() =>
+			layout.keys.map((key) => {
+				const bar = bars.find((entry) => entry.yKey === key);
+				return bar?.color ?? series.find((entry) => entry.key === key)?.color ?? "transparent";
+			}),
+		[layout.keys, bars, series]
+	);
+
+	const barOptions = useCallback(
+		(info: ChartBarStackSegmentInfo): ChartBarStackSegmentOptions => (info.isTop ? { roundedCorners: corners } : {}),
+		[corners]
+	);
+
+	const first = bars[0];
+	if (first === undefined || layout.mode === "none") return null;
+
+	if (layout.mode === "single") {
+		return (
+			<EngineBar
+				color={colors[0]}
+				labels={resolveBarLabels(first.labels, axisColor, data)}
+				opacity={opacity}
+				roundedCorners={corners}
+				yKey={first.yKey}
+			/>
+		);
+	}
+
+	if (layout.mode === "grouped") {
+		return <EngineBarGroup colors={colors} opacity={opacity} roundedCorners={corners} yKeys={layout.keys} />;
+	}
+
+	return <EngineBarStack barOptions={barOptions} colors={colors} opacity={opacity} yKeys={layout.keys} />;
+}
+
+ChartBars.displayName = "DelacourUI.Chart.Bars";

package/src/components/chart/chart-candlestick.tsx

@@ -0,0 +1,60 @@
+import { ChartCandlestick as EngineCandlestick } from "@delacour/react-native-charts";
+import type { ReactElement } from "react";
+import { useChart } from "./chart.context";
+import type { ChartCandleColors, ChartCandlestickKeys } from "./chart.types";
+
+export type ChartCandlestickProps = {
+	/** The row field holding each price. Default to the conventional names. */
+	open?: string;
+	high?: string;
+	low?: string;
+	close?: string;
+	/**
+	 * Overrides the sentiment colours. Literals only.
+	 *
+	 * The defaults are `chart-1`, `chart-2` and `muted-foreground`,
+	 * resolved in the root; a token here would reach the canvas unresolved.
+	 */
+	colors?: Partial<ChartCandleColors>;
+	/** The fraction of each step a body fills. Defaults to 0.6. */
+	bodyWidth?: number;
+	/** The wick's stroke width in points. Defaults to 1. */
+	wickWidth?: number;
+	opacity?: number;
+};
+
+/**
+ * Open-high-low-close candles, coloured by whether each closed up or down.
+ *
+ * The chart's `config` names the close field alone, so the legend and the
+ * tooltip name one price rather than four; the root reads the other three
+ * fields off this part and plots them for the engine. A rising candle is
+ * `chart-1` and a falling one `chart-2` — the top of the same ramp every
+ * other chart wears — and a flat candle is `muted-foreground`.
+ */
+export function ChartCandlestick(props: ChartCandlestickProps): ReactElement {
+	const { candleColors } = useChart();
+	const { colors, bodyWidth, wickWidth, opacity } = props;
+
+	return (
+		<EngineCandlestick
+			candleColors={{ ...candleColors, ...colors }}
+			candleRatio={bodyWidth}
+			keys={candlestickKeysOf(props)}
+			opacity={opacity}
+			wickStrokeWidth={wickWidth}
+		/>
+	);
+}
+
+ChartCandlestick.displayName = "DelacourUI.Chart.Candlestick";
+
+/** The four field names, with the conventional defaults filled in. */
+export function candlestickKeysOf(props: ChartCandlestickProps): ChartCandlestickKeys {
+	return {
+		open: props.open ?? "open",
+		high: props.high ?? "high",
+		low: props.low ?? "low",
+		close: props.close ?? "close",
+	};
+}

package/src/components/chart/chart-grid.tsx

@@ -0,0 +1,33 @@
+import { ChartGrid as EngineGrid } from "@delacour/react-native-charts";
+import type { GridAxis } from "@delacour/react-native-charts/core";
+import type { ReactElement } from "react";
+import { useChart } from "./chart.context";
+
+export type ChartGridProps = {
+	/** Which ticks get a rule. Defaults to the y ticks alone. */
+	axis?: GridAxis;
+	/** Overrides the `border` token this paints with. */
+	color?: string;
+	lineWidth?: number;
+	opacity?: number;
+	/** Dash on/off lengths, in points. */
+	dash?: readonly [number, number];
+};
+
+/**
+ * A hairline rule at each tick.
+ *
+ * Painted with `border`, not a chart token of its own. A gridline is a rule
+ * between regions, which is what `Separator` already uses `border` for — and
+ * inventing a `--chart-grid` would be a token no pasted shadcn theme supplies,
+ * so every borrowed palette would leave the grid on this package's default.
+ */
+export function ChartGrid({ axis, color, lineWidth, opacity, dash }: ChartGridProps): ReactElement | null {
+	const { gridColor } = useChart();
+	const paint = color ?? gridColor;
+	if (paint === undefined) return null;
+
+	return <EngineGrid axis={axis} color={paint} dash={dash} lineWidth={lineWidth} opacity={opacity} />;
+}
+
+ChartGrid.displayName = "DelacourUI.Chart.Grid";

package/src/components/chart/chart-legend.tsx

@@ -0,0 +1,41 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { cn } from "../../lib/cn";
+import { Text } from "../text";
+import { useChartSeries } from "./chart.context";
+
+export type ChartLegendProps = {
+	className?: string;
+	/** Show only these series, in this order. Defaults to all of them. */
+	keys?: readonly string[];
+};
+
+/**
+ * A swatch and a label per series, under the chart.
+ *
+ * Shared by `Chart` and `PieChart`: it reads whichever context is above it,
+ * since a legend row is a colour and a name under either root.
+ *
+ * A React Native view, not a Skia node, and the distinction is whether it
+ * moves *with* the canvas. A legend sits beside the plot and is static
+ * relative to it, so it can have the type scale, a colour token and a
+ * className — none of which exist on a canvas. Axis labels are the opposite
+ * case: they move under a pan and belong in Skia.
+ */
+export function ChartLegend({ className, keys }: ChartLegendProps): ReactElement {
+	const { series, slots } = useChartSeries();
+	const shown = keys === undefined ? series : keys.flatMap((key) => series.filter((entry) => entry.key === key));
+
+	return (
+		<View className={cn(slots.legend(), className)}>
+			{shown.map((entry) => (
+				<View className={slots.legendItem()} key={entry.key}>
+					<View className={slots.legendSwatch()} style={{ backgroundColor: entry.color }} />
+					<Text className={slots.legendLabel()}>{entry.label}</Text>
+				</View>
+			))}
+		</View>
+	);
+}
+
+ChartLegend.displayName = "DelacourUI.Chart.Legend";

package/src/components/chart/chart-line.tsx

@@ -0,0 +1,50 @@
+import { ChartLine as EngineLine } from "@delacour/react-native-charts";
+import type { CurveType } from "@delacour/react-native-charts/core";
+import type { ReactElement } from "react";
+import { useSeriesColor } from "./chart.context";
+
+export type ChartLineProps = {
+	/** Which series to draw. Names a key of the chart's `config`. */
+	yKey: string;
+	/** Overrides the series' colour from the config. A token or a literal. */
+	color?: string;
+	strokeWidth?: number;
+	curve?: CurveType;
+	/** Draw straight through a gap instead of breaking the line. */
+	connectMissingData?: boolean;
+	opacity?: number;
+};
+
+/**
+ * A stroked line through one series, in that series' colour.
+ *
+ * A Skia mark, so it takes values and not classNames — there is nothing for
+ * `cn()` to merge on a canvas node and nothing Uniwind could compile. The
+ * colour comes from the chart's `config` by key, so a call site names the data
+ * and never the paint.
+ */
+export function ChartLine({
+	yKey,
+	color,
+	strokeWidth = 2,
+	curve,
+	connectMissingData,
+	opacity,
+}: ChartLineProps): ReactElement | null {
+	const resolved = useSeriesColor(yKey);
+	const paint = color ?? resolved;
+	if (paint === undefined) return null;
+
+	return (
+		<EngineLine
+			color={paint}
+			connectMissingData={connectMissingData}
+			curve={curve}
+			opacity={opacity}
+			strokeWidth={strokeWidth}
+			yKey={yKey}
+		/>
+	);
+}
+
+ChartLine.displayName = "DelacourUI.Chart.Line";