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

package/src/components/item/item.variants.test.ts

@@ -0,0 +1,263 @@
+import { describe, expect, test } from "bun:test";
+import { ICON_SIZE_TOKENS } from "../../styles/tokens";
+import { LIST_GROUP_SIZES, listGroupVariants } from "../list-group/list-group.variants";
+import {
+	ITEM_MEDIA_VARIANTS,
+	ITEM_ORIENTATIONS,
+	ITEM_SIZES,
+	ITEM_VARIANTS,
+	itemVariants,
+	resolveItemFeedback,
+	resolveItemRender,
+	resolveItemSize,
+	resolveItemSurface,
+} from "./item.variants";
+
+/** Pulls the horizontal padding step out of a class string — `px-4` yields 4. */
+function paddingStep(cls: string): string | undefined {
+	return cls.match(/\bpx-(\d+(?:\.\d+)?)\b/)?.[1];
+}
+
+/** Position of a class string's `size-icon-*` token on the shared icon scale. */
+function iconStep(cls: string): number {
+	const token = cls.match(/\bsize-(icon-[\w-]+)\b/)?.[1];
+	return ICON_SIZE_TOKENS.indexOf(token as (typeof ICON_SIZE_TOKENS)[number]);
+}
+
+describe("resolveItemSurface", () => {
+	test("a standalone item keeps its own variant", () => {
+		for (const variant of ITEM_VARIANTS) {
+			expect(resolveItemSurface(variant, false)).toBe(variant);
+		}
+	});
+
+	// The group owns the surface: a border or a fill on each row would draw a
+	// card inside a card.
+	test("an item inside a ListGroup is always grouped, whatever its variant", () => {
+		for (const variant of ITEM_VARIANTS) {
+			expect(resolveItemSurface(variant, true)).toBe("grouped");
+		}
+	});
+});
+
+describe("resolveItemSize", () => {
+	test("an explicit size wins over the group's", () => {
+		expect(resolveItemSize("lg", "sm")).toBe("lg");
+	});
+
+	test("inherits the enclosing group's size when unset", () => {
+		for (const size of LIST_GROUP_SIZES) {
+			expect(resolveItemSize(undefined, size)).toBe(size);
+		}
+	});
+
+	test("falls back to md outside a group", () => {
+		expect(resolveItemSize(undefined, undefined)).toBe("md");
+	});
+});
+
+describe("resolveItemFeedback", () => {
+	test("a caller's feedback always wins", () => {
+		expect(resolveItemFeedback("none", true)).toBe("none");
+		expect(resolveItemFeedback("scale-fade", false)).toBe("scale-fade");
+	});
+
+	// A full-bleed row that scales reads as the whole card flexing.
+	test("fades inside a group and scales standalone", () => {
+		expect(resolveItemFeedback(undefined, true)).toBe("fade");
+		expect(resolveItemFeedback(undefined, false)).toBe("scale");
+	});
+});
+
+describe("resolveItemRender", () => {
+	const noop = () => {};
+
+	test("is static without a press handler, disabled or not", () => {
+		expect(resolveItemRender({ isDisabled: false })).toBe("static");
+		expect(resolveItemRender({ isDisabled: true })).toBe("static");
+	});
+
+	test("is a pressable with a handler", () => {
+		expect(resolveItemRender({ isDisabled: false, onPress: noop })).toBe("pressable");
+		expect(resolveItemRender({ isDisabled: false, onLongPress: noop })).toBe("pressable");
+	});
+
+	// Pressable composes its resting opacity with the press animation, so a
+	// disabled Pressable dims through `opacity-50` like any other row.
+	test("stays a pressable when disabled", () => {
+		expect(resolveItemRender({ isDisabled: true, onPress: noop })).toBe("pressable");
+		expect(resolveItemRender({ isDisabled: true, onLongPress: noop })).toBe("pressable");
+	});
+});
+
+describe("itemVariants root slot", () => {
+	test("gives every surface a distinct class string", () => {
+		const surfaces = [...ITEM_VARIANTS, "grouped"] as const;
+		const seen = new Set(surfaces.map((surface) => itemVariants({ surface }).root()));
+		expect(seen.size).toBe(surfaces.length);
+	});
+
+	test("maps each surface", () => {
+		expect(itemVariants({ surface: "default" }).root()).toContain("bg-transparent");
+		expect(itemVariants({ surface: "outline" }).root()).toContain("border-border");
+		expect(itemVariants({ surface: "muted" }).root()).toContain("bg-muted");
+	});
+
+	test("a standalone surface is rounded; a grouped one is not", () => {
+		for (const surface of ITEM_VARIANTS) {
+			expect(itemVariants({ surface }).root()).toMatch(/\brounded-/);
+		}
+		expect(itemVariants({ surface: "grouped" }).root()).not.toMatch(/\brounded-/);
+		expect(itemVariants({ surface: "grouped" }).root()).not.toContain("border-border");
+	});
+
+	// Without it a short row leaves the press feedback ending mid-card.
+	test("a grouped row spans the group", () => {
+		expect(itemVariants({ surface: "grouped" }).root()).toContain("w-full");
+	});
+
+	test("holds no text colour — a View cannot cascade one", () => {
+		for (const surface of [...ITEM_VARIANTS, "grouped"] as const) {
+			expect(itemVariants({ surface }).root()).not.toMatch(/\btext-/);
+		}
+	});
+
+	test("orientation picks the main axis", () => {
+		expect(itemVariants({ orientation: "horizontal" }).root()).toContain("flex-row");
+		expect(itemVariants({ orientation: "vertical" }).root()).toContain("flex-col");
+		expect(itemVariants({ orientation: "vertical" }).root()).not.toContain("flex-row");
+	});
+
+	test("disabled dims the row", () => {
+		expect(itemVariants({ isDisabled: true }).root()).toContain("opacity-50");
+		expect(itemVariants({ isDisabled: false }).root()).not.toContain("opacity-50");
+	});
+
+	test("selected lays the accent over every surface, the muted fill included", () => {
+		for (const surface of [...ITEM_VARIANTS, "grouped"] as const) {
+			const cls = itemVariants({ isSelected: true, surface }).root();
+			expect(cls).toContain("bg-accent");
+			expect(cls).not.toContain("bg-muted");
+			expect(cls).not.toContain("bg-transparent");
+		}
+	});
+});
+
+describe("itemVariants sizes", () => {
+	// This is what makes an Item drop into a ListGroup: the group insets its
+	// dividers by its own row padding, so the item's padding has to match it.
+	test("row padding matches ListGroup's divider inset at every size", () => {
+		for (const size of ITEM_SIZES) {
+			const itemPadding = paddingStep(itemVariants({ size }).root());
+			const dividerInset = listGroupVariants({ size })
+				.divider()
+				.match(/\bmx-(\d+(?:\.\d+)?)\b/)?.[1];
+			expect(itemPadding).toBeDefined();
+			expect(itemPadding).toBe(dividerInset);
+		}
+	});
+
+	test("row metrics match a ListGroup row at every size", () => {
+		for (const size of ITEM_SIZES) {
+			const item = itemVariants({ size }).root();
+			for (const cls of listGroupVariants({ size }).item().split(" ")) {
+				if (/^(min-h|gap|px|py)-/.test(cls)) expect(item).toContain(cls);
+			}
+		}
+	});
+
+	test("title and description step up with size", () => {
+		expect(itemVariants({ size: "sm" }).title()).toContain("text-sm");
+		expect(itemVariants({ size: "md" }).title()).toContain("text-base");
+		expect(itemVariants({ size: "lg" }).title()).toContain("text-lg");
+		expect(itemVariants({ size: "sm" }).description()).toContain("text-xs");
+		expect(itemVariants({ size: "md" }).description()).toContain("text-sm");
+		expect(itemVariants({ size: "lg" }).description()).toContain("text-base");
+	});
+
+	test("text carries its own colour tokens", () => {
+		expect(itemVariants().title()).toContain("text-foreground");
+		expect(itemVariants().description()).toContain("text-muted-foreground");
+	});
+
+	test("every media icon names an ascending step on the shared icon scale", () => {
+		for (const mediaVariant of ITEM_MEDIA_VARIANTS) {
+			if (mediaVariant === "image") continue;
+			const steps = ITEM_SIZES.map((size) => iconStep(itemVariants({ mediaVariant, size }).mediaIcon()));
+			for (const step of steps) expect(step).toBeGreaterThanOrEqual(0);
+			expect([...steps].sort((a, b) => a - b)).toEqual(steps);
+			expect(new Set(steps).size).toBe(steps.length);
+		}
+	});
+
+	test("a bare media icon matches ListGroup's prefix icon", () => {
+		for (const size of ITEM_SIZES) {
+			expect(itemVariants({ mediaVariant: "default", size }).mediaIcon()).toBe(
+				listGroupVariants({ size }).prefixIcon()
+			);
+		}
+	});
+});
+
+describe("itemVariants media slot", () => {
+	test("the icon tile has a fill and a corner", () => {
+		const cls = itemVariants({ mediaVariant: "icon" }).media();
+		expect(cls).toContain("bg-muted");
+		expect(cls).toMatch(/\brounded-/);
+	});
+
+	test("an image clips its child to the corner", () => {
+		expect(itemVariants({ mediaVariant: "image" }).media()).toContain("overflow-hidden");
+	});
+
+	test("the icon tile and image are fixed squares that grow with size", () => {
+		for (const mediaVariant of ["icon", "image"] as const) {
+			const edges = ITEM_SIZES.map((size) => {
+				const edge = itemVariants({ mediaVariant, size })
+					.media()
+					.match(/\bsize-(\d+)\b/)?.[1];
+				return Number(edge);
+			});
+			for (const edge of edges) expect(edge).toBeGreaterThan(0);
+			expect([...edges].sort((a, b) => a - b)).toEqual(edges);
+		}
+	});
+
+	test("a tile stays visible on the muted and the selected surface", () => {
+		for (const mediaVariant of ["icon", "image"] as const) {
+			for (const cls of [
+				itemVariants({ mediaVariant, surface: "muted" }).media(),
+				itemVariants({ isSelected: true, mediaVariant }).media(),
+			]) {
+				expect(cls).toContain("bg-background");
+				expect(cls).not.toContain("bg-muted");
+			}
+		}
+	});
+
+	test("a bare media slot draws nothing of its own", () => {
+		const cls = itemVariants({ mediaVariant: "default" }).media();
+		expect(cls).not.toMatch(/\bbg-/);
+		expect(cls).not.toMatch(/\bsize-\d/);
+	});
+});
+
+describe("itemVariants orientation", () => {
+	// A `flex-1` column in an auto-height parent collapses to nothing in Yoga.
+	test("content only flexes along a row", () => {
+		expect(itemVariants({ orientation: "horizontal" }).content()).toContain("flex-1");
+		expect(itemVariants({ orientation: "vertical" }).content()).not.toContain("flex-1");
+	});
+
+	test("header and footer are full-width strips on both axes", () => {
+		for (const orientation of ITEM_ORIENTATIONS) {
+			expect(itemVariants({ orientation }).header()).toContain("w-full");
+			expect(itemVariants({ orientation }).footer()).toContain("w-full");
+		}
+	});
+
+	test("a group runs down by default and across when horizontal", () => {
+		expect(itemVariants({ groupOrientation: "vertical" }).group()).toContain("flex-col");
+		expect(itemVariants({ groupOrientation: "horizontal" }).group()).toContain("flex-row");
+	});
+});

package/src/components/item/item.variants.ts

@@ -0,0 +1,200 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+import type { PressableFeedback } from "../pressable/pressable.variants";
+
+export const ITEM_VARIANTS = ["default", "outline", "muted"] as const;
+
+export const ITEM_SIZES = ["sm", "md", "lg"] as const;
+
+export const ITEM_ORIENTATIONS = ["horizontal", "vertical"] as const;
+
+export const ITEM_MEDIA_VARIANTS = ["default", "icon", "image"] as const;
+
+export type ItemVariant = (typeof ITEM_VARIANTS)[number];
+export type ItemSize = (typeof ITEM_SIZES)[number];
+export type ItemOrientation = (typeof ITEM_ORIENTATIONS)[number];
+export type ItemMediaVariant = (typeof ITEM_MEDIA_VARIANTS)[number];
+
+/**
+ * The surface a row actually draws.
+ *
+ * One of the three variants a caller picks, or `grouped` — the surface an item
+ * takes inside a `ListGroup`, where the group already draws the card and the
+ * row must draw nothing but itself.
+ */
+export type ItemSurface = ItemVariant | "grouped";
+
+/** Theme token an icon in `Item.Media` inherits. */
+export const ITEM_MEDIA_ICON_TOKEN = "foreground";
+
+/** Theme token an icon in `Item.Actions` inherits — a trailing hint, not the row's subject. */
+export const ITEM_ACTIONS_ICON_TOKEN = "muted-foreground";
+
+/**
+ * The surface an item draws, given its variant and whether a `ListGroup`
+ * encloses it.
+ *
+ * Inside a group the variant is ignored: the group owns the border, the fill
+ * and the corner, and a row repeating any of them would draw a card inside a
+ * card.
+ */
+export function resolveItemSurface(variant: ItemVariant, isInGroup: boolean): ItemSurface {
+	return isInGroup ? "grouped" : variant;
+}
+
+/**
+ * An item's size: its own when set, else the enclosing `ListGroup`'s, else
+ * `md`.
+ *
+ * The two share one scale on purpose, so an item dropped into a `sm` group
+ * comes out `sm` with nothing said at the call site.
+ */
+export function resolveItemSize(size: ItemSize | undefined, groupSize: ItemSize | undefined): ItemSize {
+	return size ?? groupSize ?? "md";
+}
+
+/**
+ * The press feedback for an item, when the caller has not named one.
+ *
+ * A full-bleed row inside a group fades, because a row that scales reads as
+ * the whole card flexing. A standalone item is its own card, so it scales the
+ * way a card does.
+ */
+export function resolveItemFeedback(feedback: PressableFeedback | undefined, isInGroup: boolean): PressableFeedback {
+	return feedback ?? (isInGroup ? "fade" : "scale");
+}
+
+/**
+ * What an item renders as.
+ *
+ * - `pressable` — it has a handler: a `Pressable`, announced as a button. A
+ *   disabled one keeps the role, reports `disabled`, and dims through
+ *   `opacity-50`, which `Pressable` composes with its press animation.
+ * - `static` — no handler: a plain view with no role. A static row announcing
+ *   itself as a button is a lie VoiceOver tells on every swipe.
+ */
+export type ItemRender = "pressable" | "static";
+
+export function resolveItemRender(options: {
+	onPress?: () => void;
+	onLongPress?: () => void;
+	isDisabled: boolean;
+}): ItemRender {
+	const hasHandler = options.onPress !== undefined || options.onLongPress !== undefined;
+	return hasHandler ? "pressable" : "static";
+}
+
+/**
+ * Styling for every part of an item.
+ *
+ * Row metrics are the same numbers a `ListGroup` row uses, per size — asserted
+ * as a pair in the tests — because a group insets its dividers by its own row
+ * padding. An item whose padding drifted from that would sit in a group with
+ * its text and its divider out of line.
+ *
+ * `surface` rather than `variant` is the axis here, because inside a group the
+ * variant a caller passed does not decide what is drawn. `resolveItemSurface`
+ * is where that decision lives.
+ *
+ * The horizontal root wraps, and `header` and `footer` are `w-full`: a strip
+ * then takes a line of its own above or below the media, text and actions, on
+ * either orientation, with no extra prop. `content` only flexes along a row — a
+ * `flex-1` column in an auto-height parent collapses to nothing in Yoga.
+ *
+ * No slot but the two text slots holds a `text-*` colour — a React Native
+ * `View` does not cascade one to a `Text`.
+ *
+ * Free of React Native imports so it stays unit-testable — `bun test` cannot
+ * parse React Native's Flow-typed source. See AGENTS.md.
+ */
+export const itemVariants = tv({
+	slots: {
+		root: "",
+		media: "items-center justify-center",
+		/** Edge length an `Icon` in the media slot inherits. */
+		mediaIcon: "",
+		content: "justify-center gap-0.5",
+		title: "font-medium text-foreground",
+		description: "text-muted-foreground",
+		actions: "flex-row items-center gap-2",
+		/** Edge length an `Icon` in the actions slot inherits. */
+		actionsIcon: "",
+		header: "w-full flex-row items-center justify-between gap-2",
+		footer: "w-full flex-row items-center justify-between gap-2",
+		group: "",
+	},
+	variants: {
+		surface: {
+			default: { root: "rounded-lg border border-transparent bg-transparent" },
+			outline: { root: "rounded-lg border border-border bg-transparent" },
+			muted: { root: "rounded-lg border border-transparent bg-muted" },
+			grouped: { root: "w-full bg-transparent" },
+		},
+		size: {
+			sm: {
+				root: "min-h-12 gap-2.5 px-3 py-2",
+				title: "text-sm",
+				description: "text-xs",
+				actionsIcon: "size-icon-xs",
+			},
+			md: {
+				root: "min-h-14 gap-3 px-4 py-3",
+				title: "text-base",
+				description: "text-sm",
+				actionsIcon: "size-icon-sm",
+			},
+			lg: {
+				root: "min-h-16 gap-3.5 px-5 py-4",
+				title: "text-lg",
+				description: "text-base",
+				actionsIcon: "size-icon-md",
+			},
+		},
+		orientation: {
+			horizontal: { root: "flex-row flex-wrap items-center", content: "flex-1" },
+			vertical: { root: "flex-col items-start", content: "self-stretch" },
+		},
+		mediaVariant: {
+			default: {},
+			icon: { media: "rounded-md bg-muted" },
+			image: { media: "overflow-hidden rounded-md bg-muted" },
+		},
+		groupOrientation: {
+			vertical: { group: "flex-col gap-2" },
+			horizontal: { group: "flex-row gap-3" },
+		},
+		// The empty `false` branches type the props as `boolean` rather than
+		// `true`. See the note in button.variants.ts.
+		isDisabled: { true: { root: "opacity-50" }, false: {} },
+		isSelected: { true: { root: "bg-accent" }, false: {} },
+	},
+	compoundVariants: [
+		// A card-shaped surface is `rounded-lg`, stepping down to `rounded-md` at
+		// `sm` — the same one step `ListGroup` and `Accordion` take.
+		{ size: "sm", surface: ["default", "outline", "muted"], class: { root: "rounded-md" } },
+		{ mediaVariant: "default", size: "sm", class: { mediaIcon: "size-icon-md" } },
+		{ mediaVariant: "default", size: "md", class: { mediaIcon: "size-icon-lg" } },
+		{ mediaVariant: "default", size: "lg", class: { mediaIcon: "size-icon-xl" } },
+		{ mediaVariant: "icon", size: "sm", class: { media: "size-8", mediaIcon: "size-icon-sm" } },
+		{ mediaVariant: "icon", size: "md", class: { media: "size-10", mediaIcon: "size-icon-md" } },
+		{ mediaVariant: "icon", size: "lg", class: { media: "size-12", mediaIcon: "size-icon-lg" } },
+		{ mediaVariant: "image", size: "sm", class: { media: "size-10" } },
+		{ mediaVariant: "image", size: "md", class: { media: "size-12" } },
+		{ mediaVariant: "image", size: "lg", class: { media: "size-14" } },
+		// A tile is `bg-muted`, so on a muted or selected surface it would vanish
+		// into the row.
+		{ mediaVariant: ["icon", "image"], surface: "muted", class: { media: "bg-background" } },
+		{ mediaVariant: ["icon", "image"], isSelected: true, class: { media: "bg-background" } },
+	],
+	defaultVariants: {
+		surface: "default",
+		size: "md",
+		orientation: "horizontal",
+		mediaVariant: "default",
+		groupOrientation: "vertical",
+		isDisabled: false,
+		isSelected: false,
+	},
+});
+
+export type ItemVariantProps = VariantProps<typeof itemVariants>;

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";