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

package/src/components/calendar/calendar.variants.ts

@@ -0,0 +1,426 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+import {
+	type CalendarCell,
+	type CalendarDate,
+	type CalendarDateRange,
+	type CalendarSelectionState,
+	compareDates,
+	isBetween,
+	isSameDay,
+	startOfMonth,
+} from "./calendar.date";
+
+export const CALENDAR_VARIANTS = ["primary", "secondary"] as const;
+export const CALENDAR_SIZES = ["sm", "md", "lg"] as const;
+
+/** How a day is painted: unselected, a filled selection, or the soft band between a range's ends. */
+export const CALENDAR_DAY_TONES = ["plain", "selected", "band"] as const;
+
+/** Where a day sits in a range. `none` is outside it — `tv` cannot key a variant on `null`. */
+export const CALENDAR_RANGE_ROLES = ["none", "start", "middle", "end", "only"] as const;
+
+export type CalendarVariant = (typeof CALENDAR_VARIANTS)[number];
+export type CalendarSize = (typeof CALENDAR_SIZES)[number];
+export type CalendarDayTone = (typeof CALENDAR_DAY_TONES)[number];
+export type CalendarRangeRole = Exclude<(typeof CALENDAR_RANGE_ROLES)[number], "none">;
+
+/** The view the calendar's body shows: the month grid, or one of the two jump views. */
+export type CalendarView = "days" | "months" | "years";
+
+export const CALENDAR_DEFAULT_VARIANT: CalendarVariant = "primary";
+export const CALENDAR_DEFAULT_SIZE: CalendarSize = "md";
+
+/**
+ * How far a swipe must travel, as a fraction of the grid's width, to page.
+ *
+ * A quarter rather than a half because a thumb sweeping across a phone rarely covers half the
+ * screen, and a fast flick pages regardless — see {@link CALENDAR_PAGE_VELOCITY}.
+ */
+export const CALENDAR_PAGE_THRESHOLD = 0.25;
+
+/** A release faster than this, in points per second, pages however short the swipe was. */
+export const CALENDAR_PAGE_VELOCITY = 500;
+
+/**
+ * Styling for every part of a calendar.
+ *
+ * One slotted `tv()` because eight part files read the same `size` and `variant`, and none of them
+ * can import the root without closing a cycle (AGENTS.md rule 3).
+ *
+ * **A day is three layers.** `cell` is the flex-1 column share and the touch target's height;
+ * `band` is drawn behind, edge to edge, for a day inside a range; `dayBase` is the circle that
+ * fills for a selection and rings for today, and `dayLabel` is the number. The band spans the
+ * whole cell so neighbouring days join into one continuous strip — a gap between columns would
+ * break it into beads.
+ *
+ * **The band ends under the circle, never beside it.** Start runs from its cell's centre to the
+ * right edge, end from the left edge to its centre, and every day between spans the whole cell
+ * square — including at a week's edge, where the strip simply stops and picks up again on the
+ * next row. A cell is wider than its circle, so a band rounded across the whole end cell poked a
+ * crescent out beside the circle; stopping at the centre lets the circle itself be the cap. A
+ * one-day range draws no band at all.
+ *
+ * **The cell steps on the input scale** — `h-input-*` and `text-input-*` — so a calendar inline
+ * beside a field shares its density, and a retune of the field retunes the calendar.
+ *
+ * **Colour is on the text slots, never their parent** (rule 1): `dayLabel`, `weekdayLabel`,
+ * `captionText` and `pickerItemLabel` carry it; every `View` slot carries a fill at most.
+ *
+ * Free of React Native imports so it stays unit-testable. See AGENTS.md.
+ */
+export const calendarVariants = tv({
+	slots: {
+		/** The column holding the header, the weekday row and the grid. */
+		root: "w-full gap-1",
+		/** Previous arrow, caption, next arrow. */
+		header: "flex-row items-center justify-between gap-1",
+		/** The caption's touch target — a capsule when it opens the jump view. */
+		caption: "min-h-11 flex-row items-center justify-center gap-1 rounded-full px-3",
+		/** The month and year. */
+		captionText: "font-sans font-semibold text-foreground",
+		/** The row of weekday names. */
+		weekdays: "flex-row",
+		/** One weekday name's column. */
+		weekday: "flex-1 items-center justify-center py-1",
+		/** A weekday name. */
+		weekdayLabel: "font-medium font-sans text-muted-foreground text-xs",
+		/** The six weeks, clipped so a page sliding in or out never draws past the edge. */
+		grid: "overflow-hidden",
+		/** One week. */
+		week: "flex-row",
+		/** One day's column share, and the height of its touch target. */
+		cell: "flex-1 items-center justify-center",
+		/** The strip behind a day inside a range. */
+		band: "absolute inset-y-0",
+		/** The circle a selection fills and today rings. */
+		dayBase: "items-center justify-center rounded-full border border-transparent",
+		/** The day's number. */
+		dayLabel: "font-sans tabular-nums",
+		/** The months or years jump view. */
+		pickerGrid: "flex-row flex-wrap",
+		/** One month or year. */
+		pickerItem: "basis-1/3 items-center justify-center rounded-full",
+		/** A month or year's name. */
+		pickerItemLabel: "font-sans",
+	},
+	variants: {
+		variant: {
+			primary: {},
+			secondary: {},
+		},
+		size: {
+			sm: {
+				captionText: "text-input-sm",
+				cell: "h-input-sm",
+				dayBase: "size-input-sm",
+				dayLabel: "text-input-sm",
+				pickerItem: "h-input-sm",
+				pickerItemLabel: "text-input-sm",
+			},
+			md: {
+				captionText: "text-input-md",
+				cell: "h-input-md",
+				dayBase: "size-input-md",
+				dayLabel: "text-input-md",
+				pickerItem: "h-input-md",
+				pickerItemLabel: "text-input-md",
+			},
+			lg: {
+				captionText: "text-input-lg",
+				cell: "h-input-lg",
+				dayBase: "size-input-lg",
+				dayLabel: "text-input-lg",
+				pickerItem: "h-input-lg",
+				pickerItemLabel: "text-input-lg",
+			},
+		},
+		tone: {
+			plain: { dayLabel: "text-foreground", pickerItemLabel: "text-foreground" },
+			selected: { dayLabel: "font-semibold", pickerItemLabel: "font-semibold" },
+			band: { dayBase: "bg-transparent" },
+		},
+		rangeRole: {
+			none: { band: "hidden" },
+			start: { band: "left-1/2 right-0" },
+			middle: { band: "inset-x-0" },
+			end: { band: "left-0 right-1/2" },
+			only: { band: "hidden" },
+		},
+		isToday: { true: {}, false: {} },
+		isOutside: { true: {}, false: {} },
+		isInvalid: { true: {}, false: {} },
+		isDisabled: {
+			true: { root: "opacity-50", dayBase: "opacity-40" },
+			false: {},
+		},
+	},
+	compoundVariants: [
+		{ variant: "primary", tone: "selected", class: { dayBase: "bg-primary", dayLabel: "text-primary-foreground" } },
+		{
+			variant: "primary",
+			tone: "selected",
+			class: { pickerItem: "bg-primary", pickerItemLabel: "text-primary-foreground" },
+		},
+		{ variant: "primary", class: { band: "bg-primary/15" } },
+		{ variant: "primary", tone: "band", class: { dayLabel: "text-foreground" } },
+		{
+			variant: "secondary",
+			tone: "selected",
+			class: {
+				dayBase: "bg-primary/25",
+				dayLabel: "text-foreground",
+				pickerItem: "bg-primary/25",
+				pickerItemLabel: "text-foreground",
+			},
+		},
+		{ variant: "secondary", class: { band: "bg-primary/10" } },
+		{ variant: "secondary", tone: "band", class: { dayLabel: "text-foreground" } },
+		{
+			isInvalid: true,
+			tone: "selected",
+			class: {
+				dayBase: "bg-destructive",
+				dayLabel: "text-destructive-foreground",
+				pickerItem: "bg-destructive",
+				pickerItemLabel: "text-destructive-foreground",
+			},
+		},
+		{ isInvalid: true, class: { band: "bg-destructive-soft" } },
+		{ isInvalid: true, tone: "band", class: { dayLabel: "text-destructive-soft-foreground" } },
+		{ isToday: true, tone: "plain", class: { dayBase: "border-ring", dayLabel: "font-semibold text-primary" } },
+		{ isOutside: true, tone: "plain", class: { dayLabel: "text-muted-foreground" } },
+	],
+	defaultVariants: {
+		variant: CALENDAR_DEFAULT_VARIANT,
+		size: CALENDAR_DEFAULT_SIZE,
+		tone: "plain",
+		rangeRole: "none",
+		isToday: false,
+		isOutside: false,
+		isInvalid: false,
+		isDisabled: false,
+	},
+});
+
+export type CalendarVariantProps = VariantProps<typeof calendarVariants>;
+
+// ── Resolvers ───────────────────────────────────────────────────────────────
+
+/**
+ * Where `date` sits in `range`, or `null` outside it.
+ *
+ * A started range's one day is `only`, the same as a complete one-day range: both are a single
+ * filled circle with nothing joining it to a neighbour.
+ */
+export function resolveRangeRole(range: CalendarDateRange, date: CalendarDate): CalendarRangeRole | null {
+	const { start, end } = range;
+	if (!start) return null;
+	if (!end || isSameDay(start, end)) return isSameDay(start, date) ? "only" : null;
+	if (isSameDay(start, date)) return "start";
+	if (isSameDay(end, date)) return "end";
+	return isBetween(date, start, end) ? "middle" : null;
+}
+
+/** How a day is painted, from whether it is selected and where it sits in a range. */
+export function resolveDayTone({
+	isSelected,
+	rangeRole,
+}: {
+	isSelected: boolean;
+	rangeRole: CalendarRangeRole | null;
+}): CalendarDayTone {
+	if (rangeRole === "middle") return "band";
+	return isSelected || rangeRole !== null ? "selected" : "plain";
+}
+
+/** Whether a day is part of the selection, in whichever mode it is. */
+export function isDateSelected(selection: CalendarSelectionState, date: CalendarDate): boolean {
+	switch (selection.mode) {
+		case "single":
+			return isSameDay(selection.value, date);
+		case "multiple":
+			return selection.value.some((item) => isSameDay(item, date));
+		case "range":
+			return resolveRangeRole(selection.value, date) !== null;
+	}
+}
+
+/** Everything a `Calendar.Day` needs to know to draw itself and decide whether it takes a tap. */
+export type CalendarDayState = {
+	isSelected: boolean;
+	rangeRole: CalendarRangeRole | null;
+	tone: CalendarDayTone;
+	isToday: boolean;
+	isOutside: boolean;
+	/** Dimmed and announced as disabled: out of bounds, or matched. */
+	isDisabled: boolean;
+	/** Drawn as an empty cell — an outside day with `showOutsideDays` off. */
+	isHidden: boolean;
+	/** Takes a tap. */
+	isPressable: boolean;
+};
+
+/**
+ * One day's state, from its cell and the calendar around it.
+ *
+ * **An outside day shows no selection unless outside days are selectable.** It is a preview of
+ * the next month, and a range drawn into it would read as a second copy of the range's end.
+ * **`isReadOnly` stops the tap but not the paint**, while a disabled day or a disabled calendar
+ * stops both — a read-only calendar is showing an answer, not offering a dead control.
+ */
+export function resolveDayState({
+	cell,
+	selection,
+	today,
+	isDisabled,
+	showOutsideDays,
+	selectOutsideDays,
+	isCalendarDisabled,
+	isReadOnly,
+}: {
+	cell: CalendarCell;
+	selection: CalendarSelectionState;
+	today: CalendarDate;
+	isDisabled: (date: CalendarDate) => boolean;
+	showOutsideDays: boolean;
+	selectOutsideDays: boolean;
+	isCalendarDisabled: boolean;
+	isReadOnly: boolean;
+}): CalendarDayState {
+	const { date, isOutside } = cell;
+	const isHidden = isOutside && !showOutsideDays;
+	const showsSelection = !isOutside || selectOutsideDays;
+	const isSelected = showsSelection && isDateSelected(selection, date);
+	const rangeRole = showsSelection && selection.mode === "range" ? resolveRangeRole(selection.value, date) : null;
+	const dayDisabled = isDisabled(date);
+
+	return {
+		isSelected,
+		rangeRole,
+		tone: resolveDayTone({ isSelected, rangeRole }),
+		isToday: isSameDay(date, today),
+		isOutside,
+		isDisabled: dayDisabled,
+		isHidden,
+		isPressable: !isHidden && !dayDisabled && !isCalendarDisabled && !isReadOnly && (!isOutside || selectOutsideDays),
+	};
+}
+
+/**
+ * The first and last months the arrows and the swipe can reach.
+ *
+ * `startMonth`/`endMonth` when the caller names them, otherwise the months `minDate`/`maxDate`
+ * fall in — paging to a month in which nothing can be picked is a dead end. Either may be `null`,
+ * which is unbounded.
+ */
+export function resolveMonthBounds({
+	startMonth,
+	endMonth,
+	minDate,
+	maxDate,
+}: {
+	startMonth?: CalendarDate | null;
+	endMonth?: CalendarDate | null;
+	minDate?: CalendarDate | null;
+	maxDate?: CalendarDate | null;
+}): { first: CalendarDate | null; last: CalendarDate | null } {
+	const first = startMonth ?? minDate;
+	const last = endMonth ?? maxDate;
+	return { first: first ? startOfMonth(first) : null, last: last ? startOfMonth(last) : null };
+}
+
+/** Whether `month` lies inside the bounds {@link resolveMonthBounds} returns, by month alone. */
+export function isMonthInBounds(
+	month: CalendarDate,
+	{ first, last }: { first: CalendarDate | null; last: CalendarDate | null }
+): boolean {
+	const start = startOfMonth(month);
+	if (first && compareDates(start, first) < 0) return false;
+	if (last && compareDates(start, last) > 0) return false;
+	return true;
+}
+
+/**
+ * Which way a released swipe pages: `1` forward, `-1` back, `0` settle where it was.
+ *
+ * A swipe pages when it travelled past {@link CALENDAR_PAGE_THRESHOLD} of the width, or was
+ * released faster than {@link CALENDAR_PAGE_VELOCITY} — unless the flick goes against the drag,
+ * which is someone changing their mind. It never pages past a bound, and an unmeasured grid
+ * never pages at all.
+ */
+export function resolvePageDirection({
+	translationX,
+	velocityX,
+	width,
+	canGoPrev,
+	canGoNext,
+}: {
+	translationX: number;
+	velocityX: number;
+	width: number;
+	canGoPrev: boolean;
+	canGoNext: boolean;
+}): -1 | 0 | 1 {
+	"worklet";
+	if (width <= 0 || translationX === 0) return 0;
+	const direction = translationX < 0 ? 1 : -1;
+	const against =
+		(direction === 1 && velocityX > CALENDAR_PAGE_VELOCITY) ||
+		(direction === -1 && velocityX < -CALENDAR_PAGE_VELOCITY);
+	if (against) return 0;
+	const far = Math.abs(translationX) >= width * CALENDAR_PAGE_THRESHOLD;
+	const fast = Math.abs(velocityX) >= CALENDAR_PAGE_VELOCITY;
+	if (!far && !fast) return 0;
+	if (direction === 1 && !canGoNext) return 0;
+	if (direction === -1 && !canGoPrev) return 0;
+	return direction;
+}
+
+/** What a calendar was given at its own call site. */
+export type CalendarOwnAxes = {
+	variant?: CalendarVariant;
+	size?: CalendarSize;
+	isDisabled?: boolean;
+	isInvalid?: boolean;
+	isReadOnly?: boolean;
+};
+
+/** What an enclosing `Field` publishes, or null outside one. */
+export type CalendarFieldAxes = { isDisabled?: boolean; isInvalid?: boolean };
+
+export type CalendarAxes = Required<CalendarOwnAxes>;
+
+/**
+ * Settles a calendar's axes: its own props, then an enclosing `Field`, then the defaults — `??`
+ * throughout, so an explicit `false` is a value. A field reaches the two state axes only;
+ * `isReadOnly` is the calendar's own.
+ */
+export function resolveCalendarAxes({
+	own,
+	field,
+}: {
+	own?: CalendarOwnAxes;
+	field?: CalendarFieldAxes | null;
+}): CalendarAxes {
+	return {
+		variant: own?.variant ?? CALENDAR_DEFAULT_VARIANT,
+		size: own?.size ?? CALENDAR_DEFAULT_SIZE,
+		isDisabled: own?.isDisabled ?? field?.isDisabled ?? false,
+		isInvalid: own?.isInvalid ?? field?.isInvalid ?? false,
+		isReadOnly: own?.isReadOnly ?? false,
+	};
+}
+
+/**
+ * A part's `testID`, derived from the calendar's own: `booking` names its days `booking-day-2026-10-05`,
+ * its arrows `booking-prev` and `booking-next`, its caption `booking-caption` and the jump views'
+ * items `booking-month-10` and `booking-year-2026`.
+ *
+ * Derived rather than taken per part because the default anatomy renders forty-odd parts no caller
+ * writes, and an end-to-end test or a recorded flow has to reach a particular day all the same.
+ * A calendar with no `testID` gives its parts none.
+ */
+export function resolvePartTestID(root: string | undefined, part: string): string | undefined {
+	return root === undefined ? undefined : `${root}-${part}`;
+}

package/src/components/calendar/index.ts

@@ -0,0 +1,96 @@
+export { Calendar } from "./calendar";
+export {
+	type CalendarContextValue,
+	CalendarProvider,
+	useCalendar,
+	useCalendarContext,
+} from "./calendar.context";
+export {
+	addDays,
+	addMonths,
+	addYears,
+	applyRangeTap,
+	applySingleTap,
+	CALENDAR_WEEKS,
+	CALENDAR_YEAR_REACH,
+	type CalendarCell,
+	type CalendarDate,
+	type CalendarDateBounds,
+	type CalendarDateFormatOptions,
+	type CalendarDateRange,
+	type CalendarDateStyle,
+	type CalendarSelectionState,
+	clampDate,
+	compareDates,
+	compareMonths,
+	type DateMatcher,
+	DEFAULT_WEEK_START,
+	daysInMonth,
+	formatDate,
+	formatDateRange,
+	formatMonthYear,
+	formatYear,
+	fromDate,
+	isBetween,
+	isDateDisabled,
+	isLeapYear,
+	isSameDay,
+	isSameMonth,
+	isValidDate,
+	matchesDisabled,
+	monthGrid,
+	monthNames,
+	nextSelection,
+	normaliseRange,
+	parseDate,
+	rangeContainsDisabled,
+	resolveWeekStart,
+	resolveYearSpan,
+	serialiseDate,
+	startOfMonth,
+	toDate,
+	today,
+	toggleMultiple,
+	type Weekday,
+	weekdayLabels,
+	weekdayOf,
+	weekStartFromRegion,
+} from "./calendar.date";
+export type { CalendarCaptionLayout, CalendarProps, CalendarSelection } from "./calendar.types";
+export {
+	CALENDAR_DAY_TONES,
+	CALENDAR_DEFAULT_SIZE,
+	CALENDAR_DEFAULT_VARIANT,
+	CALENDAR_PAGE_THRESHOLD,
+	CALENDAR_PAGE_VELOCITY,
+	CALENDAR_RANGE_ROLES,
+	CALENDAR_SIZES,
+	CALENDAR_VARIANTS,
+	type CalendarAxes,
+	type CalendarDayState,
+	type CalendarDayTone,
+	type CalendarFieldAxes,
+	type CalendarOwnAxes,
+	type CalendarRangeRole,
+	type CalendarSize,
+	type CalendarVariant,
+	type CalendarVariantProps,
+	type CalendarView,
+	calendarVariants,
+	isDateSelected,
+	isMonthInBounds,
+	resolveCalendarAxes,
+	resolveDayState,
+	resolveDayTone,
+	resolveMonthBounds,
+	resolvePageDirection,
+	resolvePartTestID,
+	resolveRangeRole,
+} from "./calendar.variants";
+export type { CalendarCaptionProps } from "./calendar-caption";
+export type { CalendarDayProps, CalendarDayRenderProps } from "./calendar-day";
+export type { CalendarGridProps } from "./calendar-grid";
+export type { CalendarHeaderProps } from "./calendar-header";
+export type { CalendarNavProps } from "./calendar-nav";
+export type { CalendarPickerProps } from "./calendar-picker";
+export type { CalendarWeekdaysProps } from "./calendar-weekdays";

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