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

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

@@ -0,0 +1,35 @@
+import { ChartScatter as EngineScatter } from "@delacour/react-native-charts";
+import type { ScatterShape } from "@delacour/react-native-charts/core";
+import type { ReactElement } from "react";
+import { useSeriesColor } from "./chart.context";
+
+export type ChartScatterProps = {
+	/** Which series to draw. Names a key of the chart's `config`. */
+	yKey: string;
+	/** Overrides the series' colour from the config. A literal — the canvas can resolve no token. */
+	color?: string;
+	/** Every point's radius in points. Defaults to 4. */
+	radius?: number;
+	shape?: ScatterShape;
+	opacity?: number;
+};
+
+/**
+ * One filled shape per datum, in the series' colour.
+ *
+ * The engine draws a whole series as one path, so a hundred points is one
+ * Skia node; a gap is the same shape at radius zero, which is what lets a
+ * datum come and go without the series snapping. Rings, per-point radii and
+ * the engine's other options are deliberately not surfaced — a scatter on a
+ * themed chart is a set of dots, and a chart that needs more reaches for the
+ * engine's own mark.
+ */
+export function ChartScatter({ yKey, color, radius, shape, opacity }: ChartScatterProps): ReactElement | null {
+	const resolved = useSeriesColor(yKey);
+	const paint = color ?? resolved;
+	if (paint === undefined) return null;
+
+	return <EngineScatter color={paint} opacity={opacity} radius={radius} shape={shape} yKey={yKey} />;
+}
+
+ChartScatter.displayName = "DelacourUI.Chart.Scatter";

package/src/components/chart/chart-tooltip-dot.tsx

@@ -0,0 +1,70 @@
+import { ChartCursorDot } from "@delacour/react-native-charts";
+import type { ReactElement } from "react";
+import { useChart } from "./chart.context";
+
+export type ChartTooltipDotProps = {
+	/** Which series to mark. Omit to mark every one. */
+	yKey?: string;
+	/** Overrides the series' colour. */
+	color?: string;
+	radius?: number;
+	/** The ring's width. Zero draws no ring. */
+	borderWidth?: number;
+	/**
+	 * Ride the curve continuously instead of sitting on the nearest datum.
+	 *
+	 * Off by default: the readout names a datum, so a dot that glides between
+	 * them describes a different position from the number beside it.
+	 */
+	glide?: boolean;
+	opacity?: number;
+};
+
+/**
+ * A dot on each series at the scrubbed position.
+ *
+ * A Skia mark, so it moves with the plot on the UI thread. It is named under
+ * `Chart.Tooltip` because it is part of the same readout, but it is placed as
+ * a **sibling** of it rather than a child — the tooltip is a React Native view
+ * over the canvas and this is drawn inside it, so one cannot contain the other.
+ *
+ * The ring takes the chart's background, which is what makes a dot in the
+ * series colour legible on a line of that same colour.
+ *
+ * A series drawn only as a bar gets no dot. A bar has no curve for a dot to
+ * sit on — it would float at the bar's top, over a column the tooltip's band
+ * already picks out — so the dot follows only the keys some line, area or
+ * scatter draws a point for.
+ */
+export function ChartTooltipDot({
+	yKey,
+	color,
+	radius,
+	borderWidth,
+	glide,
+	opacity,
+}: ChartTooltipDotProps): ReactElement {
+	const { series, surfaceColor, bars, pointKeys } = useChart();
+	const shown = (yKey === undefined ? series : series.filter((entry) => entry.key === yKey)).filter(
+		(entry) => !bars.keys.includes(entry.key) || pointKeys.includes(entry.key)
+	);
+
+	return (
+		<>
+			{shown.map((entry) => (
+				<ChartCursorDot
+					borderColor={borderWidth === 0 ? undefined : surfaceColor}
+					borderWidth={borderWidth}
+					color={color ?? entry.color}
+					key={entry.key}
+					opacity={opacity}
+					radius={radius}
+					snap={glide !== true}
+					yKey={entry.key}
+				/>
+			))}
+		</>
+	);
+}
+
+ChartTooltipDot.displayName = "DelacourUI.Chart.Tooltip.Dot";

package/src/components/chart/chart-tooltip-x.tsx

@@ -0,0 +1,121 @@
+import type { ChartBounds, ChartOrientation, ChartScrubState, ChartStep } from "@delacour/react-native-charts";
+import { ChartCursorLine, useChartContext as useEngineChart } from "@delacour/react-native-charts";
+import { Rect } from "@shopify/react-native-skia";
+import type { ReactElement } from "react";
+import { useDerivedValue } from "react-native-reanimated";
+import { useChart } from "./chart.context";
+
+export type ChartTooltipXProps = {
+	/** Overrides the `muted-foreground` token this paints with. */
+	color?: string;
+	width?: number;
+	/** Dash on/off lengths. Pass `null` for a solid rule. */
+	dash?: readonly [number, number] | null;
+	glide?: boolean;
+	opacity?: number;
+	/**
+	 * A translucent band one step wide instead of a rule.
+	 *
+	 * On by default when the chart holds bars or candles: a hairline through
+	 * the middle of a bar says less than a wash over the whole column. Set it
+	 * explicitly to get the band on a line chart, or the rule on a bar chart.
+	 */
+	band?: boolean;
+};
+
+/** Dashed by default, so the crosshair reads as a guide beside solid gridlines. */
+const DEFAULT_DASH = [4, 4] as const;
+
+/** A wash, not a fill — the bars under it have to stay legible. */
+const BAND_OPACITY = 0.12;
+
+/** Parked off-canvas, so a band with nothing to point at is not at the origin. */
+const OFFSCREEN = -10_000;
+
+/**
+ * A vertical rule through the scrubbed position — or, over bars, a band.
+ *
+ * Named for the axis it reads against — it tells you *where along x* you are —
+ * rather than for the direction it is drawn in. The band is the same mark in
+ * a different width: one `xStep`, centred on the snapped datum, so it picks
+ * out the column the readout names. On a horizontal chart the step runs up
+ * the category axis, so the band lies across the plot instead.
+ */
+export function ChartTooltipX({ color, width, dash, glide, opacity, band }: ChartTooltipXProps): ReactElement | null {
+	const { axisColor, bars, candlestick } = useChart();
+	const paint = color ?? axisColor;
+	if (paint === undefined) return null;
+
+	if (band ?? (bars.mode !== "none" || candlestick !== null)) {
+		return <ChartTooltipBand color={paint} opacity={opacity ?? BAND_OPACITY} />;
+	}
+
+	return (
+		<ChartCursorLine
+			axis="x"
+			color={paint}
+			dash={dash === null ? undefined : (dash ?? DEFAULT_DASH)}
+			opacity={opacity ?? 0.6}
+			snap={glide !== true}
+			width={width}
+		/>
+	);
+}
+
+ChartTooltipX.displayName = "DelacourUI.Chart.Tooltip.X";
+
+type ChartTooltipBandProps = {
+	readonly color: string;
+	readonly opacity: number;
+};
+
+/**
+ * The band. Reads the engine's context directly, because the scrub's shared
+ * values and the step live there; the outer part only decides whether to
+ * draw one. Split so a chart with no scrub never runs the derived values.
+ */
+function ChartTooltipBand(props: ChartTooltipBandProps): ReactElement | null {
+	const { scrub, bounds, xStep, orientation } = useEngineChart();
+	if (scrub === null) return null;
+	return <TooltipBand {...props} bounds={bounds} orientation={orientation} scrub={scrub} step={xStep} />;
+}
+
+ChartTooltipBand.displayName = "DelacourUI.Chart.Tooltip.X.Band";
+
+type TooltipBandProps = ChartTooltipBandProps & {
+	readonly scrub: ChartScrubState;
+	readonly bounds: ChartBounds;
+	readonly step: ChartStep;
+	readonly orientation: ChartOrientation;
+};
+
+/**
+ * One rect, `step.px` wide, riding the snapped position on the UI thread the
+ * way the engine's cursor line does. Always snapped: a band that glided
+ * between columns would highlight half of two bars. The engine reports the
+ * category's position on `snappedX` when vertical and `snappedY` when
+ * horizontal, and the other is `NaN` — which is why each axis reads its own.
+ */
+function TooltipBand({ color, opacity, scrub, bounds, step, orientation }: TooltipBandProps): ReactElement {
+	const horizontal = orientation === "horizontal";
+	const width = horizontal ? bounds.right - bounds.left : step.px;
+	const height = horizontal ? step.px : bounds.bottom - bounds.top;
+
+	const x = useDerivedValue(() => {
+		if (horizontal) return bounds.left;
+		const centre = scrub.snappedX.value;
+		return Number.isFinite(centre) ? centre - step.px / 2 : OFFSCREEN;
+	});
+
+	const y = useDerivedValue(() => {
+		if (!horizontal) return bounds.top;
+		const centre = scrub.snappedY.value;
+		return Number.isFinite(centre) ? centre - step.px / 2 : OFFSCREEN;
+	});
+
+	const alpha = useDerivedValue(() => (scrub.isActive.value ? opacity : 0));
+
+	return <Rect color={color} height={height} opacity={alpha} width={width} x={x} y={y} />;
+}
+
+TooltipBand.displayName = "DelacourUI.Chart.Tooltip.X.Band.Inner";

package/src/components/chart/chart-tooltip-y.tsx

@@ -0,0 +1,55 @@
+import { ChartCursorLine } from "@delacour/react-native-charts";
+import type { ReactElement } from "react";
+import { useChart } from "./chart.context";
+
+export type ChartTooltipYProps = {
+	/** Which series' value the rule sits at. Defaults to the first. */
+	yKey?: string;
+	/** Overrides the series' colour. */
+	color?: string;
+	width?: number;
+	/** Dash on/off lengths. Pass `null` for a solid rule. */
+	dash?: readonly [number, number] | null;
+	glide?: boolean;
+	opacity?: number;
+};
+
+const DEFAULT_DASH = [4, 4] as const;
+
+/**
+ * A horizontal rule at one series' scrubbed value.
+ *
+ * It carries the value across to the y axis, which is the same job a gridline
+ * does — so it takes the series' own colour rather than the axis', to say
+ * *which* series it is reading.
+ *
+ * One series only. Drawing a rule per series would put four horizontal lines
+ * across a four-series chart, and the reader would have to work out which
+ * belonged to which.
+ */
+export function ChartTooltipY({
+	yKey,
+	color,
+	width,
+	dash,
+	glide,
+	opacity = 0.6,
+}: ChartTooltipYProps): ReactElement | null {
+	const { series } = useChart();
+	const target = yKey === undefined ? series[0] : series.find((entry) => entry.key === yKey);
+	if (target === undefined) return null;
+
+	return (
+		<ChartCursorLine
+			axis="y"
+			color={color ?? target.color}
+			dash={dash === null ? undefined : (dash ?? DEFAULT_DASH)}
+			opacity={opacity}
+			snap={glide !== true}
+			width={width}
+			yKey={target.key}
+		/>
+	);
+}
+
+ChartTooltipY.displayName = "DelacourUI.Chart.Tooltip.Y";

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

@@ -0,0 +1,133 @@
+import { type ReactElement, useState } from "react";
+import { View } from "react-native";
+import Animated, { useAnimatedReaction, useAnimatedStyle } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { cn } from "../../lib/cn";
+import { Text } from "../text";
+import { useChart } from "./chart.context";
+import { chartTooltipOffset, resolveTooltipRows } from "./chart.variants";
+import { ChartTooltipDot } from "./chart-tooltip-dot";
+import { ChartTooltipX } from "./chart-tooltip-x";
+import { ChartTooltipY } from "./chart-tooltip-y";
+
+export type ChartTooltipProps = {
+	className?: string;
+	/**
+	 * Prints the heading from the row under the cursor.
+	 *
+	 * Defaults to the x field, formatted the way the axis formats it — a `Date`
+	 * comes out as `20 Jan`, not as `Tue Jan 20 2026 00:00:00 GMT+0000`.
+	 */
+	formatHeading?: (row: Record<string, unknown>, index: number) => string;
+	/** Prints one series' value. Defaults to the number as written. */
+	formatValue?: (value: unknown, key: string) => string;
+	/** Overrides the measured size used to keep the tooltip inside the frame. */
+	size?: { width: number; height: number };
+};
+
+/** Assumed size before layout, so the first frame is not placed off-screen. */
+const DEFAULT_SIZE = { width: 120, height: 56 };
+
+/**
+ * A floating readout that follows the scrub.
+ *
+ * **A React Native view, deliberately, even though it sits 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. Drawing it in Skia would
+ * mean re-implementing text layout and line breaking for nothing.
+ *
+ * ## Two threads, on purpose
+ *
+ * Its **position** rides the scrub's shared values through `useAnimatedStyle`,
+ * so it tracks the finger on the UI thread with no bridge hop.
+ *
+ * Its **contents** are ordinary React state, updated through `scheduleOnRN`
+ * only when the nearest datum index actually changes. That is a handful of
+ * updates per drag rather than one per frame, because the text only changes
+ * when the selected row does — and text on a shared value would mean an
+ * `AnimatedTextInput` and a `value` prop pretending to be a label.
+ *
+ * With a candlestick present the rows are open, high, low and close, each
+ * swatched in the candle's own sentiment colour — see `resolveTooltipRows`.
+ */
+function ChartTooltipRoot({ className, formatHeading, formatValue, size }: ChartTooltipProps): ReactElement {
+	const { scrub, slots, series, data, formatXValue, frame, candlestick, candleColors } = useChart();
+	const [index, setIndex] = useState(-1);
+	const measured = size ?? DEFAULT_SIZE;
+
+	useAnimatedReaction(
+		() => scrub.index.value,
+		(next, previous) => {
+			if (next === previous) return;
+			scheduleOnRN(setIndex, next);
+		}
+	);
+
+	const style = useAnimatedStyle(() => {
+		const offset = chartTooltipOffset({
+			x: scrub.x.value,
+			y: scrub.series[series[0]?.key ?? ""]?.y.value ?? frame.height / 2,
+			width: measured.width,
+			height: measured.height,
+			frameWidth: frame.width,
+			frameHeight: frame.height,
+		});
+
+		return {
+			opacity: scrub.isActive.value ? 1 : 0,
+			transform: [{ translateX: offset.x }, { translateY: offset.y }],
+		};
+	});
+
+	const row = data[index];
+	const heading = row === undefined ? "" : (formatHeading?.(row, index) ?? formatXValue(row));
+	const rows = resolveTooltipRows(
+		series,
+		candlestick === null ? null : { keys: candlestick, colors: candleColors },
+		row
+	);
+
+	return (
+		<Animated.View className={cn(slots.tooltip(), className)} pointerEvents="none" style={style}>
+			{heading === "" ? null : <Text className={slots.tooltipHeading()}>{heading}</Text>}
+			{rows.map((entry) => (
+				<View className={slots.tooltipRow()} key={entry.key}>
+					<View className={slots.tooltipSwatch()} style={{ backgroundColor: entry.color }} />
+					<Text className={slots.tooltipName()}>{entry.label}</Text>
+					<Text className={slots.tooltipValue()}>
+						{row === undefined ? "" : (formatValue?.(entry.value, entry.key) ?? String(entry.value ?? ""))}
+					</Text>
+				</View>
+			))}
+		</Animated.View>
+	);
+}
+
+/**
+ * A floating readout that follows the scrub, and the marks that point at it.
+ *
+ * The readout is a React Native view over the canvas; `Dot`, `X` and `Y` are
+ * Skia marks drawn inside it. They are named here because they are one
+ * feature, but they are **placed as siblings** — a view cannot contain a
+ * canvas node, so `<Chart.Tooltip><Chart.Tooltip.Dot /></Chart.Tooltip>` would
+ * put the dot in the wrong tree and draw nothing.
+ *
+ * @example
+ * <Chart config={config} data={rows} xKey="at">
+ *   <Chart.Line yKey="price" />
+ *   <Chart.Tooltip.X />
+ *   <Chart.Tooltip.Y />
+ *   <Chart.Tooltip.Dot />
+ *   <Chart.Tooltip />
+ * </Chart>
+ */
+export const ChartTooltip = Object.assign(ChartTooltipRoot, {
+	/** A dot on each series at the scrubbed point, ringed in the chart's background. */
+	Dot: ChartTooltipDot,
+	/** A vertical rule through the scrubbed position — where along x you are. */
+	X: ChartTooltipX,
+	/** A horizontal rule at one series' value, carrying it across to the y axis. */
+	Y: ChartTooltipY,
+	displayName: "DelacourUI.Chart.Tooltip",
+});

package/src/components/chart/chart-x-axis.tsx

@@ -0,0 +1,27 @@
+import { ChartXAxis as EngineXAxis } from "@delacour/react-native-charts";
+import type { ReactElement } from "react";
+import { useChart } from "./chart.context";
+
+export type ChartXAxisProps = {
+	/** Overrides the `muted-foreground` token this paints with. */
+	color?: string;
+	/** Space between the plot rect and the labels. */
+	tickPadding?: number;
+	opacity?: number;
+};
+
+/**
+ * Tick labels below the plot.
+ *
+ * `muted-foreground`, the colour every secondary label in this package already
+ * uses — an axis names the scale, it does not compete with the data.
+ */
+export function ChartXAxis({ color, tickPadding, opacity }: ChartXAxisProps): ReactElement | null {
+	const { axisColor } = useChart();
+	const paint = color ?? axisColor;
+	if (paint === undefined) return null;
+
+	return <EngineXAxis color={paint} opacity={opacity} tickPadding={tickPadding} />;
+}
+
+ChartXAxis.displayName = "DelacourUI.Chart.XAxis";

package/src/components/chart/chart-y-axis.tsx

@@ -0,0 +1,21 @@
+import { ChartYAxis as EngineYAxis } from "@delacour/react-native-charts";
+import type { ReactElement } from "react";
+import { useChart } from "./chart.context";
+
+export type ChartYAxisProps = {
+	color?: string;
+	tickPadding?: number;
+	side?: "left" | "right";
+	opacity?: number;
+};
+
+/** Tick labels beside the plot, right-aligned so they form a clean column. */
+export function ChartYAxis({ color, tickPadding, side, opacity }: ChartYAxisProps): ReactElement | null {
+	const { axisColor } = useChart();
+	const paint = color ?? axisColor;
+	if (paint === undefined) return null;
+
+	return <EngineYAxis color={paint} opacity={opacity} side={side} tickPadding={tickPadding} />;
+}
+
+ChartYAxis.displayName = "DelacourUI.Chart.YAxis";

package/src/components/chart/chart.context.tsx

@@ -0,0 +1,127 @@
+import type { ChartOrientation, ChartScrubState } from "@delacour/react-native-charts";
+import { createContext, type ReactNode, useContext } from "react";
+import type {
+	ChartBarLayout,
+	ChartCandleColors,
+	ChartCandlestickKeys,
+	ChartDatum,
+	ChartResolvedSeries,
+} from "./chart.types";
+import type { ChartSize, chartVariants } from "./chart.variants";
+import { PieChartContext } from "./pie-chart.context";
+
+export type ChartSlots = ReturnType<typeof chartVariants>;
+
+export type ChartContextValue = {
+	/** Series in draw order, colours already resolved to values. */
+	readonly series: readonly ChartResolvedSeries[];
+	readonly data: readonly ChartDatum[];
+	readonly xKey: string;
+	/** Prints a row's x field — a Date as a date, not as an RFC timestamp. */
+	readonly formatXValue: (row: ChartDatum) => string;
+	readonly size: ChartSize;
+	readonly slots: ChartSlots;
+	/** Resolved gridline colour, or `undefined` if the theme emits none. */
+	readonly gridColor: string | undefined;
+	/** Resolved axis-label colour. */
+	readonly axisColor: string | undefined;
+	/**
+	 * The surface the chart is drawn on.
+	 *
+	 * A cursor dot rings itself in this so it reads as a knob sitting on the
+	 * line rather than as a slight thickening of it.
+	 */
+	readonly surfaceColor: string | undefined;
+	readonly scrub: ChartScrubState;
+	/** The frame's measured size, for placing an overlay inside it. */
+	readonly frame: { readonly width: number; readonly height: number };
+	/** Every `Chart.Bar`, resolved into one arrangement. `mode: "none"` without any. */
+	readonly bars: ChartBarLayout;
+	/** A bar's corner radius in points — `--radius` × the size's multiplier. */
+	readonly barRadius: number;
+	/** The candlestick's four fields, or `null` without one. */
+	readonly candlestick: ChartCandlestickKeys | null;
+	/** The three sentiment tokens, resolved. */
+	readonly candleColors: ChartCandleColors;
+	/**
+	 * Keys some mark draws a point for — a line, an area or a scatter.
+	 *
+	 * A cursor dot skips a series that is only a bar: a bar has no curve for a
+	 * dot to sit on, and the band under the tooltip already says which column.
+	 */
+	readonly pointKeys: readonly string[];
+	readonly orientation: ChartOrientation;
+};
+
+/**
+ * The resolved chart, published twice from one value.
+ *
+ * Twice because the chart straddles a reconciler boundary. Skia's `<Canvas>`
+ * runs its own React renderer and context does not cross into it, so the root
+ * renders one provider around the React Native subtree — the legend and the
+ * tooltip — and a second one *inside* the canvas around the marks. Same object,
+ * two provider elements, no bridge and no extra dependency.
+ *
+ * The context is exported rather than hidden behind its hook because that
+ * second mounting is unusual enough to want something to copy.
+ */
+export const ChartContext = createContext<ChartContextValue | null>(null);
+
+ChartContext.displayName = "DelacourUI.ChartContext";
+
+export function ChartProvider({
+	value,
+	children,
+}: {
+	readonly value: ChartContextValue;
+	readonly children: ReactNode;
+}): ReactNode {
+	return <ChartContext.Provider value={value}>{children}</ChartContext.Provider>;
+}
+
+ChartProvider.displayName = "DelacourUI.ChartProvider";
+
+/**
+ * The chart a part belongs to.
+ *
+ * Throws outside one. A Skia mark that silently rendered nothing would leave a
+ * blank canvas with no error and no element inspector to look at, which is
+ * among the hardest things to diagnose in this package.
+ */
+export function useChart(): ChartContextValue {
+	const value = useContext(ChartContext);
+	if (value === null) {
+		throw new Error("[DelacourUI] a Chart part was used outside a <Chart>. Every part reads the chart from context.");
+	}
+	return value;
+}
+
+/** The chart, or `null` outside one. */
+export function useChartContext(): ChartContextValue | null {
+	return useContext(ChartContext);
+}
+
+/** One series' resolved colour, or `undefined` when the key names no series. */
+export function useSeriesColor(key: string | undefined): string | undefined {
+	const { series } = useChart();
+	if (key === undefined) return undefined;
+	return series.find((entry) => entry.key === key)?.color;
+}
+
+/**
+ * The series and slots of whichever chart a part is under.
+ *
+ * For a part both roots share — the legend — which reads the same two fields
+ * off a `Chart` or a `PieChart` and does not care which. Throws outside both.
+ */
+export function useChartSeries(): { series: readonly ChartResolvedSeries[]; slots: ChartSlots } {
+	const cartesian = useContext(ChartContext);
+	const pie = useContext(PieChartContext);
+	const value = cartesian ?? pie;
+	if (value === null) {
+		throw new Error(
+			"[DelacourUI] a chart part was used outside a <Chart> or a <PieChart>. Every part reads the chart from context."
+		);
+	}
+	return { series: value.series, slots: value.slots };
+}