@delacour/react-native-ui 0.1.0-alpha.20260925064429 → 0.1.0-alpha.20260925064741

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.1.0-alpha.20260925064429",
+	"version": "0.1.0-alpha.20260925064741",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -48,6 +48,7 @@
 		"./field": "./src/components/field/index.ts",
 		"./icon": "./src/components/icon/index.ts",
 		"./input": "./src/components/input/index.ts",
+		"./kpi": "./src/components/kpi/index.ts",
 		"./label": "./src/components/label/index.ts",
 		"./list-group": "./src/components/list-group/index.ts",
 		"./meter": "./src/components/meter/index.ts",
@@ -96,7 +97,7 @@
 	},
 	"peerDependencies": {
 		"@central-icons-react-native/round-outlined-radius-1-stroke-1.5": "^1.1",
-		"@delacour/react-native-charts": "0.1.0-alpha.20260925064429",
+		"@delacour/react-native-charts": "0.1.0-alpha.20260925064741",
 		"@gorhom/bottom-sheet": "^5.2.8",
 		"@legendapp/list": ">=3.3",
 		"expo-linear-gradient": ">=15",

package/src/components/chart/AGENTS.md

@@ -87,6 +87,14 @@ knows nothing about tokens.
   tailwind-merge is what lets a caller's `className="aspect-video h-auto"`
   cleanly win when they want that instead.
 
+- **`frameClassName` resizes the frame, not the root.** The canvas fills the
+  frame, and the frame carries the size's height, so a `className` on the root
+  cannot shorten the plot — the frame would overflow it. `frameClassName` is
+  merged after the size's `h-chart-*`, and the tokens are registered with
+  tailwind-merge, so `h-16` cleanly replaces it. `Kpi.Sparkline` is the reason
+  it exists: a sparkline is a chart with no axes a third the height of the
+  smallest one.
+
 - **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 —

package/src/components/chart/chart.tsx

@@ -72,6 +72,12 @@ export type ChartProps = {
 	/** How the scrub coexists with a scrolling parent. Defaults to holding. */
 	scrubConfig?: ScrubConfig;
 	className?: string;
+	/**
+	 * Merged onto the frame — the view the canvas fills — after the size's
+	 * height. `frameClassName="h-16"` is a sparkline; the three `size` heights
+	 * are for a chart someone reads with axes.
+	 */
+	frameClassName?: string;
 	/** Named on the frame, so a capture flow or a test can find the plot. */
 	testID?: string;
 	children?: ReactNode;
@@ -106,6 +112,7 @@ function ChartRoot({
 	orientation = "vertical",
 	scrubConfig,
 	className,
+	frameClassName,
 	testID,
 	children,
 }: ChartProps): ReactElement {
@@ -231,7 +238,7 @@ function ChartRoot({
 	return (
 		<ChartProvider value={value}>
 			<View className={slots.root({ className })}>
-				<View className={slots.frame()} onLayout={onLayout} testID={testID}>
+				<View className={slots.frame({ className: frameClassName })} onLayout={onLayout} testID={testID}>
 					<CartesianChart
 						curve={curve}
 						data={data}

package/src/components/kpi/AGENTS.md

@@ -0,0 +1,125 @@
+# Kpi
+
+One number, what it is doing, and the shape it made getting there — a
+[`Card`](../card/AGENTS.md) with a vocabulary for a metric, whose sparkline is a
+[`Chart`](../chart/AGENTS.md) line. Compound root plus eleven parts: `Header`,
+`Icon`, `Title`, `Action`, `Content`, `Stat`, `Value`, `Trend`, `Sparkline`,
+`Footer`, `Group`.
+
+`import { Kpi } from "@delacour/react-native-ui/kpi";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/kpi` |
+| `kpi.tsx` | Root + the `Object.assign` compound surface |
+| `kpi-header.tsx` | `Kpi.Header`, on the card header's inset |
+| `kpi-icon.tsx` | `Kpi.Icon`, and the icon defaults it publishes |
+| `kpi-title.tsx` | `Kpi.Title` |
+| `kpi-action.tsx` | `Kpi.Action` |
+| `kpi-content.tsx` | `Kpi.Content`, and the layout it publishes |
+| `kpi-stat.tsx` | `Kpi.Stat` |
+| `kpi-value.tsx` | `Kpi.Value`, and its loading placeholder |
+| `kpi-trend.tsx` | `Kpi.Trend` — text or badge |
+| `kpi-sparkline.tsx` | `Kpi.Sparkline`, and the internal scrub reader |
+| `kpi-footer.tsx` | `Kpi.Footer`, over `Card.Footer` |
+| `kpi-group.tsx` | `Kpi.Group` |
+| `kpi.context.tsx` | `KpiProvider`, `useKpi()`, `useKpiContext()`, `useKpiPart()`, the layout and group contexts |
+| `kpi.types.ts` | Prop types shared by two or more parts |
+| `kpi.variants.ts` | The slotted `tv()`, the axes, and every pure resolver — no RN imports |
+| `kpi.variants.test.ts` | |
+
+## Design
+
+- **A KPI is a card, not a second definition of one.** The root renders `Card`
+  with the caller's `variant` and `size`, so it takes the four fills, steps
+  when nested, and has no scale of its own — `KPI_SIZES` *is* `CARD_SIZES`.
+  `Kpi.Header` and `Kpi.Content` compose their classes onto `cardVariants`'
+  own `header` and `content` slots, and the test asserts the card's inset
+  survives the merge, so the number, the title and the footer sit on one line
+  and a retune of the card moves all three.
+- **The trend is coloured by what the movement means, never by its sign.**
+  `resolveKpiTrend` turns a signed percentage and a `goodDirection` into a
+  `direction` and a `tone`. A fall in churn is `down` and `good`, drawn in
+  `success-soft-foreground`. `goodDirection` is said once on the card and every
+  trend follows it unless it overrides it; `none` keeps the direction and drops
+  the judgement. A value that is not finite — a change against a zero baseline
+  — is flat and neutral rather than news of either kind.
+- **There is no direction prop.** The sign is the direction. A separate prop
+  would be a second statement of one fact that the call site has to keep in
+  step, and the first time it did not the card would paint a fall green.
+- **The trend is printed with a typographic minus.** `−4.2%` rather than
+  `-4.2%`: a hyphen is narrower than a plus, so a column of changes would not
+  line up on the sign. A value that rounds to zero is unsigned — `−0.0%` would
+  claim a fall nothing shows.
+- **Colour is never the only signal.** The sign carries the direction in text,
+  the badge adds an arrow, and the trend is one accessible string — "Up 7.8
+  percent, vs last month" — rather than a number, an arrow and a caption read
+  as three stops.
+- **The badge is `Badge`, soft.** `KPI_TONE_BADGE_COLOR` maps the tone onto
+  `success`, `destructive` and `default`, so a trend badge is the same object as
+  any other status badge on the screen.
+- **The value is formatted by the caller.** Separators, currency and units are
+  locale decisions a component would get wrong in a way that is hard to notice
+  and impossible to override. It is one line, shrinking to fit — a number that
+  wraps is no longer read as one — and it takes the foreground token of the
+  plane the card landed on, the way `Card.Title` does.
+- **The title never grows.** A growing child of a column absorbs the column's
+  spare height, which in a row of cards lands every number at a different
+  height. The header pushes `Kpi.Action` to the end with `ml-auto` instead, and
+  a test forbids `flex-1` on the title.
+- **`Kpi.Stat` exists because the value and its change are one fact.** The
+  card's gap is for the space between facts; written straight into the content
+  the two drift apart and stop reading as a unit. Beside an `inline` sparkline
+  the stat takes the row's width.
+- **The sparkline is `Chart`, with nothing but the line.** No grid, no axes, no
+  tooltip readout — `Chart` reserves an axis gutter only for an axis that is
+  placed, so the plot is the whole frame. The frame is sized through `Chart`'s
+  `frameClassName`, which exists for this: the chart's three `size` heights are
+  for a chart someone reads with axes. Rows or a bare list of numbers both work;
+  `resolveSparklineSeries` indexes a list.
+- **The y bounds are the data's own, padded a tenth.** With no padding a line
+  drawn to its exact extent puts the peak and trough on the frame's edge, half
+  the stroke off the canvas. `resolveSparklineDomain` pads the span and gives a
+  flat series a unit either side so it sits centred.
+- **Inline is a fixed 128pt column; below is the full width.** A stack of cards
+  has labels of every length, and a chart taking whatever the text left would
+  be a different width on every card. Fixed, the shapes line up down the
+  right-hand edge, which is the reason to put them there. Below, the chart is
+  filled; inline it is not, where a fill would make it a second block competing
+  with the number — `resolveSparklineFilled`, overridable.
+- **`colorIndex` is on the card, not the chart.** The icon and the sparkline
+  share it, and a row of cards gets five series colours by setting one prop on
+  each. The trend ignores it: a series colour has nothing to say about whether
+  the number went the right way. The icon square is the series colour at 15%,
+  written out per index because Tailwind's scanner cannot see a class built at
+  runtime.
+- **Holding the sparkline scrubs it, and the scrub is state.** A
+  `Chart.Tooltip.Dot` rides the line, and an internal `KpiSparklineScrub` —
+  a child of `<Chart>` that is not a mark, so the chart mounts it beside the
+  canvas with the scrub's shared values in reach — reports the index to the
+  root through `scheduleOnRN` only when it changes, and `null` when the finger
+  lifts. The root holds it with `useControllableState`: `activeIndex` and
+  `onActiveIndexChange` control it, `defaultActiveIndex` seeds it, and
+  `useKpi()` reads it, so a part of the caller's own prints the scrubbed
+  point's value in place of the latest. A controlled index moves what the
+  caller prints; it draws no dot, because the dot is the finger's.
+- **Loading is a placeholder the size of what it stands for.** `isLoading`
+  swaps the value, the trend and the sparkline for muted blocks — the value's
+  is the height of its line at each size, which a test pins — and marks the
+  card busy, so nothing jumps when the data lands. They are
+  `muted-foreground` at 15%, not `bg-muted`: `muted` is the secondary fill, and
+  the first build's placeholders vanished on a secondary card. A translucent
+  foreground reads on every plane, and a test forbids a fill token there.
+- **No interaction on the card.** Like `Card`, a KPI that selects or navigates
+  is a `Pressable` around it, which keeps the role, the haptic and the pressed
+  state at the call site that knows what the press means. The playground's
+  metric picker is the example.
+- **`Kpi.Group` arranges; it does not restyle.** A row gives each metric an
+  equal share of the width. `separated` sets them on one `Surface` with a
+  `Separator` between each — hidden from assistive technology, so a rule is not
+  an unlabelled stop between two numbers — and each metric drops its own fill
+  to `transparent` unless it names one.
+- **No text treatment on a view slot** (rule 1). The tests assert it across
+  every combination.

package/src/components/kpi/index.ts

@@ -0,0 +1,45 @@
+export { Kpi, type KpiProps } from "./kpi";
+export {
+	type KpiContextValue,
+	type KpiGroupContextValue,
+	KpiProvider,
+	useKpi,
+	useKpiContext,
+	useKpiLayout,
+} from "./kpi.context";
+export type { KpiSlotProps, KpiTextProps } from "./kpi.types";
+export {
+	formatKpiTrend,
+	KPI_COLOR_INDEXES,
+	KPI_DIRECTIONS,
+	KPI_GOOD_DIRECTIONS,
+	KPI_GROUP_ORIENTATIONS,
+	KPI_LAYOUTS,
+	KPI_SIZES,
+	KPI_TONE_BADGE_COLOR,
+	KPI_TONES,
+	KPI_TREND_VARIANTS,
+	type KpiColorIndex,
+	type KpiDirection,
+	type KpiGoodDirection,
+	type KpiGroupOrientation,
+	type KpiLayout,
+	type KpiSize,
+	type KpiSparklineData,
+	type KpiSparklineSeries,
+	type KpiTone,
+	type KpiTrendVariant,
+	type KpiVariantProps,
+	kpiSparklineAccessibilityLabel,
+	kpiTrendAccessibilityLabel,
+	kpiVariants,
+	resolveKpiTrend,
+	resolveSparklineDomain,
+	resolveSparklineFilled,
+	resolveSparklineSeries,
+} from "./kpi.variants";
+export type { KpiContentProps } from "./kpi-content";
+export type { KpiFooterProps } from "./kpi-footer";
+export type { KpiGroupProps } from "./kpi-group";
+export type { KpiSparklineProps } from "./kpi-sparkline";
+export type { KpiTrendProps } from "./kpi-trend";

package/src/components/kpi/kpi-action.tsx

@@ -0,0 +1,12 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { useKpiPart } from "./kpi.context";
+import type { KpiSlotProps } from "./kpi.types";
+import { kpiVariants } from "./kpi.variants";
+
+/** The header's trailing end — a menu button, a period filter, a link — pushed to the right edge. */
+export function KpiAction({ className, ...props }: KpiSlotProps): ReactElement {
+	const { size } = useKpiPart("Kpi.Action");
+	return <View className={kpiVariants({ size }).action({ className })} {...props} />;
+}
+KpiAction.displayName = "DelacourUI.Kpi.Action";

package/src/components/kpi/kpi-content.tsx

@@ -0,0 +1,35 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { cn } from "../../lib/cn";
+import { cardVariants } from "../card/card.variants";
+import { KpiLayoutProvider, useKpiPart } from "./kpi.context";
+import type { KpiSlotProps } from "./kpi.types";
+import { type KpiLayout, kpiVariants } from "./kpi.variants";
+
+export type KpiContentProps = KpiSlotProps & {
+	/**
+	 * `below` stacks the stat over a full-width sparkline. `inline` sets the
+	 * sparkline in a fixed column beside the number, for a stack of cards whose
+	 * shapes should line up down the right-hand edge.
+	 */
+	layout?: KpiLayout;
+};
+
+/**
+ * The body: the stat and the sparkline. Sits on the card content's own inset,
+ * and tells the stat and the sparkline inside it which layout they are in.
+ */
+export function KpiContent({ layout = "below", className, ...props }: KpiContentProps): ReactElement {
+	const { size } = useKpiPart("Kpi.Content");
+	return (
+		<KpiLayoutProvider value={layout}>
+			<View
+				className={cardVariants({ size }).content({
+					className: cn(kpiVariants({ layout, size }).content(), className),
+				})}
+				{...props}
+			/>
+		</KpiLayoutProvider>
+	);
+}
+KpiContent.displayName = "DelacourUI.Kpi.Content";

package/src/components/kpi/kpi-footer.tsx

@@ -0,0 +1,52 @@
+import { Children, type ReactElement, type ReactNode } from "react";
+import type { CardFooterProps } from "../card";
+import { Card } from "../card";
+import { Text } from "../text";
+import { useKpiPart } from "./kpi.context";
+import { kpiVariants } from "./kpi.variants";
+
+export type KpiFooterProps = CardFooterProps;
+
+/**
+ * Wraps each run of bare strings and numbers in one muted caption. A raw string
+ * inside a `View` is a red box in React Native, and the run is joined rather
+ * than wrapped piece by piece: `last {days} days` is three children, and three
+ * `Text`s in the footer's row would sit apart by its gap.
+ */
+function wrapBareText(children: ReactNode, className: string): ReactNode[] {
+	const output: ReactNode[] = [];
+	let run: string[] = [];
+	const flush = (): void => {
+		if (run.length === 0) return;
+		output.push(
+			<Text className={className} key={`text-${output.length}`}>
+				{run.join("")}
+			</Text>
+		);
+		run = [];
+	};
+
+	for (const child of Children.toArray(children)) {
+		if (typeof child === "string" || typeof child === "number") {
+			run.push(String(child));
+		} else {
+			flush();
+			output.push(child);
+		}
+	}
+	flush();
+	return output;
+}
+
+/**
+ * The bottom strip — a comparison period, a caveat, a link.
+ *
+ * `Card.Footer`, so `variant="band"` sets it into the card on the next fill
+ * down, and it must be the last child for the same reason. Bare text becomes a
+ * muted caption at the card's scale.
+ */
+export function KpiFooter({ children, ...props }: KpiFooterProps): ReactElement {
+	const { size } = useKpiPart("Kpi.Footer");
+	return <Card.Footer {...props}>{wrapBareText(children, kpiVariants({ size }).trendCaption())}</Card.Footer>;
+}
+KpiFooter.displayName = "DelacourUI.Kpi.Footer";

package/src/components/kpi/kpi-group.tsx

@@ -0,0 +1,70 @@
+import { Children, type ReactElement, type ReactNode, useMemo } from "react";
+import { View } from "react-native";
+import { Separator } from "../separator";
+import { Surface } from "../surface";
+import { type KpiGroupContextValue, KpiGroupProvider } from "./kpi.context";
+import type { KpiSlotProps } from "./kpi.types";
+import { type KpiGroupOrientation, kpiVariants } from "./kpi.variants";
+
+export type KpiGroupProps = KpiSlotProps & {
+	/** `horizontal` splits the row between the metrics; `vertical` stacks them. */
+	orientation?: KpiGroupOrientation;
+	/**
+	 * Set the metrics on one surface with a rule between them, rather than as
+	 * separate cards spaced apart. Several metrics divided by a rule read as one
+	 * panel; several spaced apart read as several panels that happen to be
+	 * adjacent.
+	 */
+	separated?: boolean;
+};
+
+/** Puts a rule between adjacent children. `Separator` is hidden from assistive technology. */
+function withRules(children: ReactNode, orientation: KpiGroupOrientation): ReactNode[] {
+	const output: ReactNode[] = [];
+	for (const [index, child] of Children.toArray(children).entries()) {
+		if (index > 0) {
+			output.push(
+				<Separator key={`rule-${index}`} orientation={orientation === "horizontal" ? "vertical" : "horizontal"} />
+			);
+		}
+		output.push(child);
+	}
+	return output;
+}
+
+/**
+ * Several metrics as one arrangement, in a row or a column.
+ *
+ * Each `Kpi` inside reads the group: in a row it takes an equal share of the
+ * width, and in a `separated` group it drops its own fill and hairline so the
+ * group's one surface holds them all, a rule between each.
+ */
+export function KpiGroup({
+	orientation = "vertical",
+	separated = false,
+	className,
+	children,
+	...props
+}: KpiGroupProps): ReactElement {
+	const context = useMemo<KpiGroupContextValue>(() => ({ orientation, separated }), [orientation, separated]);
+	const slots = kpiVariants({ orientation, separated });
+
+	if (separated) {
+		return (
+			<KpiGroupProvider value={context}>
+				<Surface className={slots.group({ className })} padding="none" {...props}>
+					{withRules(children, orientation)}
+				</Surface>
+			</KpiGroupProvider>
+		);
+	}
+
+	return (
+		<KpiGroupProvider value={context}>
+			<View className={slots.group({ className })} {...props}>
+				{children}
+			</View>
+		</KpiGroupProvider>
+	);
+}
+KpiGroup.displayName = "DelacourUI.Kpi.Group";

package/src/components/kpi/kpi-header.tsx

@@ -0,0 +1,25 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { cn } from "../../lib/cn";
+import { cardVariants } from "../card/card.variants";
+import { useKpiPart } from "./kpi.context";
+import type { KpiSlotProps } from "./kpi.types";
+import { kpiVariants } from "./kpi.variants";
+
+/**
+ * The top row: a tinted icon, the metric's name, and anything acting on it.
+ *
+ * Sits on the card header's own inset — the classes are the card's, with the
+ * row centred rather than top-aligned — so the title lines up with the number
+ * and the footer below it at every size.
+ */
+export function KpiHeader({ className, ...props }: KpiSlotProps): ReactElement {
+	const { size } = useKpiPart("Kpi.Header");
+	return (
+		<View
+			className={cardVariants({ size }).header({ className: cn(kpiVariants({ size }).header(), className) })}
+			{...props}
+		/>
+	);
+}
+KpiHeader.displayName = "DelacourUI.Kpi.Header";

package/src/components/kpi/kpi-icon.tsx

@@ -0,0 +1,28 @@
+import { type ReactElement, useMemo } from "react";
+import { View } from "react-native";
+import { IconDefaultsProvider } from "../icon";
+import { useKpiPart } from "./kpi.context";
+import type { KpiSlotProps } from "./kpi.types";
+import { kpiVariants } from "./kpi.variants";
+
+/**
+ * A tinted square for a glyph.
+ *
+ * It takes the element rather than drawing one — a metric's icon is the app's
+ * choice — and hands an unstyled `Icon` inside it the card's series colour and
+ * a step of the icon scale sized to the square. The square is that colour at
+ * 15%, so a row of cards given five colour indexes reads as five series.
+ */
+export function KpiIcon({ className, children, ...props }: KpiSlotProps): ReactElement {
+	const { size, colorIndex } = useKpiPart("Kpi.Icon");
+	const slots = kpiVariants({ colorIndex, size });
+	const glyph = slots.iconGlyph();
+	const defaults = useMemo(() => ({ className: glyph, color: `chart-${colorIndex}` }), [glyph, colorIndex]);
+
+	return (
+		<View className={slots.icon({ className })} {...props}>
+			<IconDefaultsProvider value={defaults}>{children}</IconDefaultsProvider>
+		</View>
+	);
+}
+KpiIcon.displayName = "DelacourUI.Kpi.Icon";

package/src/components/kpi/kpi-sparkline.tsx

@@ -0,0 +1,145 @@
+import type { CurveType } from "@delacour/react-native-charts/core";
+import { type ReactElement, useMemo } from "react";
+import { View } from "react-native";
+import { useAnimatedReaction } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { Chart, type ChartConfig } from "../chart";
+import { useChart } from "../chart/chart.context";
+import { useKpiLayout, useKpiPart } from "./kpi.context";
+import {
+	type KpiColorIndex,
+	type KpiSparklineData,
+	kpiSparklineAccessibilityLabel,
+	kpiVariants,
+	resolveSparklineDomain,
+	resolveSparklineFilled,
+	resolveSparklineSeries,
+} from "./kpi.variants";
+
+export type KpiSparklineProps = KpiSparklineData & {
+	/** Overrides the KPI's `colorIndex` for this chart. */
+	colorIndex?: KpiColorIndex;
+	/** A theme token or a literal, over the series colour entirely. */
+	color?: string;
+	/**
+	 * Fill under the line. Defaults on under the card and off beside the
+	 * number, where a fill would make the chart a second block competing with
+	 * the value.
+	 */
+	filled?: boolean;
+	strokeWidth?: number;
+	curve?: CurveType;
+	/**
+	 * Hold and drag to scrub a point: a dot rides the line and the KPI's
+	 * `activeIndex` follows it, so a custom part can print that point's value.
+	 * On by default. The scrub starts on a hold, so a sparkline in a scrolling
+	 * list does not steal the scroll.
+	 */
+	interactive?: boolean;
+	/** Formats the first and last point for the screen-reader summary. */
+	formatValue?: (value: number) => string;
+	/** Replaces the screen-reader summary — "Trend over 30 points, from 120 to 184". */
+	accessibilityLabel?: string;
+	className?: string;
+	testID?: string;
+};
+
+/**
+ * Reports the scrubbed index to the KPI, as `null` once the finger lifts.
+ *
+ * A child of `<Chart>` that is not a mark, so the chart mounts it beside the
+ * canvas where its context — and the scrub's shared values — are in reach. It
+ * crosses to the JS thread only when the index changes, which is a few times
+ * per drag rather than once a frame.
+ */
+function KpiSparklineScrub({ onChange }: { onChange: (index: number | null) => void }): null {
+	const { scrub } = useChart();
+
+	useAnimatedReaction(
+		() => (scrub.isActive.value ? scrub.index.value : -1),
+		(next, previous) => {
+			if (next === previous) return;
+			scheduleOnRN(onChange, next < 0 ? null : next);
+		}
+	);
+
+	return null;
+}
+KpiSparklineScrub.displayName = "DelacourUI.Kpi.Sparkline.Scrub";
+
+/**
+ * The shape the number made getting there — a `Chart` line with no grid, no
+ * axes and no padding, in the KPI's series colour.
+ *
+ * Takes a bare list of numbers, or rows with an `xKey` and a `yKey`. Under the
+ * card it is full width and filled; beside the number (`Kpi.Content
+ * layout="inline"`) it is a fixed 128pt column, unfilled, so a stack of cards
+ * lines its shapes up down the right-hand edge whatever their labels. The y
+ * bounds are the data's own, padded a tenth each way, so the peak and trough
+ * are not drawn half off the canvas.
+ *
+ * Announced as one image — how many points and where they started and ended.
+ * While the KPI loads it is a muted block of its own size.
+ */
+export function KpiSparkline(props: KpiSparklineProps): ReactElement {
+	const {
+		data,
+		xKey,
+		yKey,
+		colorIndex: colorIndexProp,
+		color,
+		filled: filledProp,
+		strokeWidth = 2,
+		curve,
+		interactive = true,
+		formatValue,
+		accessibilityLabel,
+		className,
+		testID,
+	} = props;
+	const context = useKpiPart("Kpi.Sparkline");
+	const layout = useKpiLayout();
+	const slots = kpiVariants({ layout, size: context.size });
+	const colorIndex = colorIndexProp ?? context.colorIndex;
+
+	// Keyed on the three fields the series reads rather than on the props
+	// object, which is new every render and would re-plot the chart with it.
+	// biome-ignore lint/correctness/useExhaustiveDependencies: see above
+	const series = useMemo(() => resolveSparklineSeries(props), [data, xKey, yKey]);
+	const domain = useMemo(() => ({ y: resolveSparklineDomain(series.values) }), [series]);
+	const config = useMemo<ChartConfig>(
+		() => ({ [series.yKey]: { label: series.yKey, color: color ?? `chart-${colorIndex}` } }),
+		[series.yKey, color, colorIndex]
+	);
+
+	if (context.isLoading) {
+		return <View className={slots.sparklinePlaceholder({ className: slots.sparkline({ className }) })} />;
+	}
+
+	const filled = resolveSparklineFilled({ filled: filledProp, layout });
+
+	return (
+		<View
+			accessibilityLabel={accessibilityLabel ?? kpiSparklineAccessibilityLabel(series.values, formatValue)}
+			accessibilityRole="image"
+			accessible
+			className={slots.sparkline({ className })}
+		>
+			<Chart
+				config={config}
+				curve={curve}
+				data={series.rows}
+				domain={domain}
+				frameClassName={slots.sparklineFrame()}
+				testID={testID}
+				xKey={series.xKey}
+			>
+				{filled ? <Chart.Area yKey={series.yKey} /> : null}
+				<Chart.Line strokeWidth={strokeWidth} yKey={series.yKey} />
+				{interactive ? <Chart.Tooltip.Dot yKey={series.yKey} /> : null}
+				{interactive ? <KpiSparklineScrub onChange={context.setActiveIndex} /> : null}
+			</Chart>
+		</View>
+	);
+}
+KpiSparkline.displayName = "DelacourUI.Kpi.Sparkline";

package/src/components/kpi/kpi-stat.tsx

@@ -0,0 +1,20 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { useKpiLayout, useKpiPart } from "./kpi.context";
+import type { KpiSlotProps } from "./kpi.types";
+import { kpiVariants } from "./kpi.variants";
+
+/**
+ * The value and its change, stacked tight.
+ *
+ * Its own container rather than loose children of the content, because the
+ * number and its change are one fact in two lines and the card's spacing is
+ * for the gaps *between* facts. Beside an `inline` sparkline it takes the
+ * row's width, leaving the chart its column on the end.
+ */
+export function KpiStat({ className, ...props }: KpiSlotProps): ReactElement {
+	const { size } = useKpiPart("Kpi.Stat");
+	const layout = useKpiLayout();
+	return <View className={kpiVariants({ layout, size }).stat({ className })} {...props} />;
+}
+KpiStat.displayName = "DelacourUI.Kpi.Stat";

package/src/components/kpi/kpi-title.tsx

@@ -0,0 +1,19 @@
+import type { ReactElement } from "react";
+import { Text } from "../text";
+import { useKpiPart } from "./kpi.context";
+import type { KpiTextProps } from "./kpi.types";
+import { kpiVariants } from "./kpi.variants";
+
+/**
+ * The metric's name. Quiet on purpose — `muted-foreground`, a step down the
+ * type scale — because the value is the thing being read.
+ *
+ * It never grows to fill its row: in a column that would absorb the spare
+ * height and land a row of cards' numbers at different heights. The header
+ * pushes its action to the end instead.
+ */
+export function KpiTitle({ className, ...props }: KpiTextProps): ReactElement {
+	const { size } = useKpiPart("Kpi.Title");
+	return <Text className={kpiVariants({ size }).title({ className })} numberOfLines={1} {...props} />;
+}
+KpiTitle.displayName = "DelacourUI.Kpi.Title";