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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.1.0-alpha.20260925064136",
+	"version": "0.1.0-alpha.20260925064741",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -39,6 +39,7 @@
 		"./badge": "./src/components/badge/index.ts",
 		"./bottom-sheet": "./src/components/bottom-sheet/index.ts",
 		"./button": "./src/components/button/index.ts",
+		"./card": "./src/components/card/index.ts",
 		"./chart": "./src/components/chart/index.ts",
 		"./checkbox": "./src/components/checkbox/index.ts",
 		"./chip": "./src/components/chip/index.ts",
@@ -47,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",
@@ -95,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.20260925064136",
+		"@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/card/AGENTS.md

@@ -0,0 +1,88 @@
+# Card
+
+A content surface with a header, a body and a footer, built on
+[`Surface`](../surface/AGENTS.md). Compound root plus six parts: `Header`,
+`Title`, `Description`, `Action`, `Content`, `Footer`.
+
+`import { Card } from "@delacour/react-native-ui/card";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/card` |
+| `card.tsx` | Root + the `Object.assign` compound surface |
+| `card-header.tsx` | `Card.Header`, and the bare-text wrap it owns |
+| `card-title.tsx` | `Card.Title` |
+| `card-description.tsx` | `Card.Description` |
+| `card-action.tsx` | `Card.Action` |
+| `card-content.tsx` | `Card.Content` |
+| `card-footer.tsx` | `Card.Footer` |
+| `card.context.tsx` | `CardProvider`, `useCard()`, `useCardContext()`, `useCardPart()` |
+| `card.types.ts` | Prop types shared by two or more parts |
+| `card.variants.ts` | The slotted `tv()`, `resolveCardFooterFill`, `splitCardHeaderChildren` — no RN imports |
+| `card.variants.test.ts` | |
+
+## Design
+
+- **The surface is `Surface`'s; the card adds only the rhythm between its
+  parts.** Fill, hairline, corner and clip all come from `Surface` at
+  `padding="none"`, so `variant` is `Surface`'s four fills with the same
+  nesting rule — a card that names none is the hairlined `default` on a screen
+  and steps to the next fill inside another surface. A card is not a second
+  definition of what a card-shaped surface looks like.
+- **The root resolves the fill itself as well as passing it down.** The parts
+  need the plane the card landed on — the title's colour and a band footer's
+  fill key off it — and `Surface` does not publish a prop it was never given.
+  So `Card` runs the same two pure resolvers and hands `Surface` the explicit
+  result; the two cannot disagree, because it is one function called twice.
+- **Padding lives on the parts, not the root.** The root carries `pt`/`pb`
+  and a `gap` of the same step; `Header`, `Content` and `Footer` carry that step as
+  `px`. An image written straight into the card therefore reaches both side
+  edges with nothing to undo, and `className="pt-0"` on the card bleeds it to
+  the top. Content that must not be clipped does not belong in a card: the root
+  is `padding="none"`, which is `Surface`'s one clipping step.
+- **The root's vertical padding is `pt`/`pb`, never `py`.** The root is the
+  surface's view, which carries `p-0` at `padding="none"`, and Uniwind resolves
+  that shorthand over a `py-*` on the same view — the first build on a device
+  drew the title flush against the top hairline. The longhands win, and a test
+  forbids `py-` on the root so it cannot come back.
+- **Sizes**: `sm`, `md`, `lg` — insets of 3, 4 and 6, which are `Surface`'s own
+  padding steps, so a card and a surface side by side at one size hold their
+  content at one distance from the edge. Size is one axis for five numbers —
+  vertical padding, gap, horizontal inset, title scale, description scale —
+  and the test pins the three insets to each other rather than to numbers.
+- **The title is on its plane's foreground token.** `text-card-foreground` on
+  the card fill, `text-secondary-foreground` on a secondary card, and
+  `text-foreground` for a transparent card on the page. Written out per plane
+  in the `tv()`, because Tailwind's scanner cannot see a class built at
+  runtime. The description is `muted-foreground` everywhere.
+- **`Card.Title` is announced as a header**, so a screen reader's rotor can
+  step card to card through a list of them.
+- **`Card.Action` is lifted out of the header's text column, wherever it is
+  written.** React Native has no grid to place a child by type, so the header
+  walks its children with `splitCardHeaderChildren` and renders the text column
+  as `flex-1` with the actions after it. The title wraps in the width an action
+  leaves instead of pushing it off the edge. The helper takes its predicate as
+  an argument so it stays in `card.variants.ts`, free of the part and of React
+  Native, and reachable from `bun test`.
+- **Bare text in a header is its title.** A raw string inside a `View` is a
+  red box, and a header's text is its heading — the same wrap, for the same
+  reason, as [`ListGroup.Item`](../list-group/AGENTS.md).
+- **Footer variants**: `default`, a wrapping row of actions; `band`, a strip
+  set into the card — `border-t`, the next fill down, and the card's bottom
+  corners. The band pulls itself down over the root's bottom padding with a
+  `-mb-*` of exactly that step and restates it as `py-*`, so it meets the edge
+  and the root's clip gives it the corners. That only works as the last child,
+  which the doc comment says.
+- **A band's fill is a step on the ladder, not a colour.**
+  `resolveCardFooterFill` is `resolveSurfaceVariant` for the card's plane — the
+  same step a surface nested in the card would take — so a band never matches
+  the card it sits in, at any depth. A transparent card on the page has no
+  plane, and its band takes the card fill.
+- **No interaction on the card.** A card is layout. A card that selects or
+  navigates is a `Pressable` around it — `<Pressable asChild>` or a wrapper —
+  which keeps `feedback`, `haptic` and the accessibility role at the call site
+  that knows what the press means. The playground's plan picker is the example.
+- **No text treatment on the root, header, content or footer** (rule 1). The
+  tests assert it across every combination.

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

@@ -0,0 +1,16 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { useCardPart } from "./card.context";
+import type { CardSlotProps } from "./card.types";
+import { cardVariants } from "./card.variants";
+
+/**
+ * A control pinned to the header's top-right corner — a menu button, a badge, a
+ * link. `Card.Header` lifts it out of the text column wherever it is written, so
+ * the title and description keep the width it leaves.
+ */
+export function CardAction({ className, ...props }: CardSlotProps): ReactElement {
+	const { size } = useCardPart("Card.Action");
+	return <View className={cardVariants({ size }).action({ className })} {...props} />;
+}
+CardAction.displayName = "DelacourUI.Card.Action";

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

@@ -0,0 +1,12 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { useCardPart } from "./card.context";
+import type { CardSlotProps } from "./card.types";
+import { cardVariants } from "./card.variants";
+
+/** The card's body, inset to line up with the header and footer and spaced by the card's size. */
+export function CardContent({ className, ...props }: CardSlotProps): ReactElement {
+	const { size } = useCardPart("Card.Content");
+	return <View className={cardVariants({ size }).content({ className })} {...props} />;
+}
+CardContent.displayName = "DelacourUI.Card.Content";

package/src/components/card/card-description.tsx

@@ -0,0 +1,12 @@
+import type { ReactElement } from "react";
+import { Text } from "../text";
+import { useCardPart } from "./card.context";
+import type { CardTextProps } from "./card.types";
+import { cardVariants } from "./card.variants";
+
+/** The muted supporting line under the title, a step down the type scale from it. */
+export function CardDescription({ className, ...props }: CardTextProps): ReactElement {
+	const { size } = useCardPart("Card.Description");
+	return <Text className={cardVariants({ size }).description({ className })} {...props} />;
+}
+CardDescription.displayName = "DelacourUI.Card.Description";

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

@@ -0,0 +1,30 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { useCardPart } from "./card.context";
+import type { CardSlotProps } from "./card.types";
+import { type CardFooterVariant, cardVariants, resolveCardFooterFill } from "./card.variants";
+
+export type CardFooterProps = CardSlotProps & {
+	/**
+	 * `default` is a row of actions under the content. `band` sets it into the
+	 * card as a strip of its own — a rule across the top, the next fill down, and
+	 * the card's bottom corners — for a footer that is what someone does with the
+	 * card rather than more of what it says.
+	 */
+	variant?: CardFooterVariant;
+};
+
+/**
+ * The card's last row — its actions, or a status line.
+ *
+ * A `band` footer steps its fill from the card's own plane rather than naming a
+ * colour, so it stays a step apart from the card however deep it is nested.
+ * It should be the card's last child: it pulls itself down over the card's
+ * bottom padding to meet the edge.
+ */
+export function CardFooter({ variant = "default", className, ...props }: CardFooterProps): ReactElement {
+	const { size, plane } = useCardPart("Card.Footer");
+	const slots = cardVariants({ footer: variant, footerFill: resolveCardFooterFill(plane), size });
+	return <View className={slots.footer({ className })} {...props} />;
+}
+CardFooter.displayName = "DelacourUI.Card.Footer";

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

@@ -0,0 +1,45 @@
+import { isValidElement, type ReactElement, type ReactNode } from "react";
+import { View } from "react-native";
+import { useCardPart } from "./card.context";
+import type { CardSlotProps } from "./card.types";
+import { cardVariants, splitCardHeaderChildren } from "./card.variants";
+import { CardAction } from "./card-action";
+import { CardTitle } from "./card-title";
+
+function isCardAction(node: ReactNode): boolean {
+	return isValidElement(node) && node.type === CardAction;
+}
+
+/**
+ * Wraps a bare string or number in a `Card.Title`. A raw string inside a `View`
+ * is a red box in React Native, and a header's bare text is its title.
+ */
+function wrapBareText(node: ReactNode, index: number): ReactNode {
+	return typeof node === "string" || typeof node === "number" ? (
+		<CardTitle key={`title-${index}`}>{node}</CardTitle>
+	) : (
+		node
+	);
+}
+
+/**
+ * The card's opening block: a title and description stacked on the left, and
+ * any `Card.Action` pinned to the top right.
+ *
+ * The header lifts every action out of the column wherever it is written, so
+ * the order of children does not matter and the text wraps in the width the
+ * action leaves. Bare text becomes a title.
+ */
+export function CardHeader({ className, children, ...props }: CardSlotProps): ReactElement {
+	const { size } = useCardPart("Card.Header");
+	const slots = cardVariants({ size });
+	const { text, actions } = splitCardHeaderChildren(children, isCardAction);
+
+	return (
+		<View className={slots.header({ className })} {...props}>
+			<View className={slots.headerText()}>{text.map(wrapBareText)}</View>
+			{actions}
+		</View>
+	);
+}
+CardHeader.displayName = "DelacourUI.Card.Header";

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

@@ -0,0 +1,25 @@
+import type { ReactElement } from "react";
+import { Text } from "../text";
+import { useCardPart } from "./card.context";
+import type { CardTextProps } from "./card.types";
+import { cardVariants } from "./card.variants";
+
+/**
+ * The card's heading.
+ *
+ * Carries its own colour — the foreground token of the plane the card resolved
+ * to — and its own step on the type scale, read from the card's context: a
+ * React Native `View` does not cascade colour to a `Text` descendant. Announced
+ * as a header, so a screen reader's rotor stops on each card in a list.
+ */
+export function CardTitle({ className, ...props }: CardTextProps): ReactElement {
+	const { size, plane } = useCardPart("Card.Title");
+	return (
+		<Text
+			accessibilityRole="header"
+			className={cardVariants({ plane: plane ?? "none", size }).title({ className })}
+			{...props}
+		/>
+	);
+}
+CardTitle.displayName = "DelacourUI.Card.Title";

package/src/components/card/card.context.tsx

@@ -0,0 +1,64 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { SurfacePlane, SurfaceVariant } from "../surface/surface.variants";
+import type { CardSize } from "./card.variants";
+
+export type CardContextValue = {
+	/** Size of the card — the padding, the gaps and the title and description scale. */
+	size: CardSize;
+	/** The fill the card resolved to — explicit, or stepped from the surface it sits in. */
+	variant: SurfaceVariant;
+	/**
+	 * The fill the card's content sits on. The same as `variant` unless that is
+	 * `transparent`, which passes the plane beneath it through — `null` on the page.
+	 */
+	plane: SurfacePlane | null;
+};
+
+const CardContext = createContext<CardContextValue | null>(null);
+
+/**
+ * Supplies the enclosing card's size and fill to its subtree.
+ *
+ * Lives in its own module, importing nothing but types, so a part the card
+ * renders can read it without importing `./card` and closing a cycle through
+ * `card.tsx`. See AGENTS.md rule 3.
+ */
+export function CardProvider({ value, children }: { value: CardContextValue; children: ReactNode }): ReactElement {
+	return <CardContext value={value}>{children}</CardContext>;
+}
+CardProvider.displayName = "DelacourUI.Card.Provider";
+
+/** The enclosing card's context, or null outside a `<Card>`. */
+export function useCardContext(): CardContextValue | null {
+	return use(CardContext);
+}
+
+/**
+ * Reads the enclosing card's size and fill.
+ *
+ * Lets a custom part match the card — the same inset, a colour that reads on
+ * its plane — without the card passing props down. Throws outside a `<Card>`;
+ * use {@link useCardContext} where the enclosing card is optional.
+ */
+export function useCard(): CardContextValue {
+	const context = useCardContext();
+	if (!context) {
+		throw new Error("useCard must be called inside a <Card>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing card's context, for a compound part that cannot work without one.
+ *
+ * Internal: deliberately not re-exported from `index.ts`. A caller outside the
+ * library wants {@link useCard}, whose error message names the hook rather than
+ * a part.
+ */
+export function useCardPart(component: string): CardContextValue {
+	const context = useCardContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <Card>.`);
+	}
+	return context;
+}

package/src/components/card/card.tsx

@@ -0,0 +1,94 @@
+import { type ReactElement, useMemo } from "react";
+import { Surface, type SurfaceProps, useSurfaceContext } from "../surface";
+import { resolveSurfacePlane, resolveSurfaceVariant } from "../surface/surface.variants";
+import { type CardContextValue, CardProvider } from "./card.context";
+import { type CardSize, cardVariants } from "./card.variants";
+import { CardAction } from "./card-action";
+import { CardContent } from "./card-content";
+import { CardDescription } from "./card-description";
+import { CardFooter } from "./card-footer";
+import { CardHeader } from "./card-header";
+import { CardTitle } from "./card-title";
+
+export type CardProps = Omit<SurfaceProps, "padding"> & {
+	/** The inset, the gaps between the parts, and the title and description scale. */
+	size?: CardSize;
+};
+
+function CardRoot({ variant, size = "md", className, children, ...props }: CardProps): ReactElement {
+	const parentPlane = useSurfaceContext()?.plane ?? null;
+
+	// Resolved here as well as inside `Surface`, because the parts need the plane
+	// the card landed on — the title's colour and a band footer's fill key off it.
+	const resolved = resolveSurfaceVariant({ parentPlane, variant });
+	const plane = resolveSurfacePlane({ parentPlane, variant: resolved });
+
+	const context = useMemo<CardContextValue>(() => ({ plane, size, variant: resolved }), [plane, size, resolved]);
+
+	return (
+		<CardProvider value={context}>
+			<Surface className={cardVariants({ size }).root({ className })} padding="none" variant={resolved} {...props}>
+				{children}
+			</Surface>
+		</CardProvider>
+	);
+}
+
+/**
+ * A content surface with a header, a body and a footer.
+ *
+ * Built on `Surface`, so it takes the same four fills and steps the same way:
+ * a card that names no variant is the hairlined `default` at the top of a
+ * screen and the next fill down inside another surface. The root is
+ * `padding="none"`, which clips — the padding lives on the parts, so an image
+ * placed straight in the card reaches its side edges, and `className="pt-0"`
+ * bleeds it to the top.
+ *
+ * `size` reaches every part through context, so the header, the body and the
+ * footer line up on one inset and the title picks its own scale and colour —
+ * a React Native `View` cannot cascade either to a `Text`.
+ *
+ * @example
+ * <Card>
+ *   <Card.Header>
+ *     <Card.Title>Monthly report</Card.Title>
+ *     <Card.Description>Revenue and retention for October.</Card.Description>
+ *     <Card.Action>
+ *       <Badge>New</Badge>
+ *     </Card.Action>
+ *   </Card.Header>
+ *   <Card.Content>
+ *     <Text.Title>$48,120</Text.Title>
+ *   </Card.Content>
+ *   <Card.Footer>
+ *     <Button size="sm" variant="outline">Export</Button>
+ *     <Button size="sm">Open</Button>
+ *   </Card.Footer>
+ * </Card>
+ *
+ * @example
+ * <Card className="pt-0">
+ *   <Image className="h-40 w-full" source={cover} />
+ *   <Card.Header>
+ *     <Card.Title>Lake Tekapo</Card.Title>
+ *   </Card.Header>
+ *   <Card.Footer variant="band">
+ *     <Button size="sm">Book</Button>
+ *   </Card.Footer>
+ * </Card>
+ */
+export const Card = Object.assign(CardRoot, {
+	/** The opening block. Stacks a title and description, and pins any `Card.Action` to the top right. */
+	Header: CardHeader,
+	/** The card's heading, on its plane's foreground token. Announced as a header. */
+	Title: CardTitle,
+	/** The muted supporting line under the title. */
+	Description: CardDescription,
+	/** A control pinned to the header's top-right corner, wherever in the header it is written. */
+	Action: CardAction,
+	/** The card's body, inset to line up with the header and footer. */
+	Content: CardContent,
+	/** The last row — a row of actions, or with `variant="band"` a strip set into the card. */
+	Footer: CardFooter,
+	displayName: "DelacourUI.Card",
+});

package/src/components/card/card.types.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from "react";
+import type { ViewProps } from "react-native";
+import type { TextPresetProps } from "../text";
+
+/**
+ * The shape of a card's layout parts — `Header`, `Action` and `Content`, and
+ * extended by `Footer` — so it lives in a leaf rather than in one of them
+ * arbitrarily.
+ */
+export type CardSlotProps = ViewProps & { className?: string; children?: ReactNode };
+
+/** The shape of a card's two text parts, `Title` and `Description`. */
+export type CardTextProps = TextPresetProps;