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

package/src/components/drawer/drawer.variants.ts

@@ -0,0 +1,244 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+
+/** The logical sides a drawer opens from. `start` and `end` follow the layout direction. */
+export const DRAWER_SIDES = ["start", "end", "top", "bottom"] as const;
+export type DrawerSide = (typeof DRAWER_SIDES)[number];
+
+/** The physical screen edges a side resolves to — what the motion and the pan are measured against. */
+export const DRAWER_EDGES = ["left", "right", "top", "bottom"] as const;
+export type DrawerEdge = (typeof DRAWER_EDGES)[number];
+
+/** The panel's extents, narrowest first. */
+export const DRAWER_SIZES = ["sm", "md", "lg", "full"] as const;
+export type DrawerSize = (typeof DRAWER_SIZES)[number];
+
+/** What a released swipe does. */
+export type DrawerRelease = "dismiss" | "restore";
+
+/**
+ * Each size as a fraction of the window along the panel's axis, capped.
+ *
+ * A fraction so a phone always keeps a strip of the app in view to tap away
+ * on; a cap so a tablet's drawer stays a drawer and not a second screen.
+ * `full` keeps a 6% strip and has no cap.
+ */
+export const DRAWER_SIZE_EXTENT = {
+	sm: { fraction: 0.62, max: 280 },
+	md: { fraction: 0.78, max: 320 },
+	lg: { fraction: 0.88, max: 400 },
+	full: { fraction: 0.94, max: Number.POSITIVE_INFINITY },
+} as const satisfies Record<DrawerSize, { fraction: number; max: number }>;
+
+/** A release past this fraction of the extent toward the edge dismisses. */
+export const DRAWER_DISMISS_FRACTION = 0.4;
+
+/** A release faster than this toward the edge dismisses from any distance, pt/s. */
+export const DRAWER_FLING_VELOCITY = 800;
+
+/** The asymptote a drag away from the edge approaches, in points. */
+export const DRAWER_RUBBER_BAND = 40;
+
+/**
+ * Travel along the panel's axis before the pan claims the touch, in points.
+ * Travel across it first fails the pan, so a vertical scroll in a start
+ * drawer's body never moves the drawer.
+ */
+export const DRAWER_PAN_ACTIVE_OFFSET = 10;
+
+/** The bounds on a release animation, ms — finite so an E2E settle wait ends. */
+export const DRAWER_RELEASE_MS = { min: 80, max: 220 } as const;
+
+/** The scrim's token — the foundation's, named here so the test can pin it. */
+export const DRAWER_SCRIM_TOKEN = "overlay";
+
+/** Slop around the header ✕ — a bare glyph has no capsule to bring it toward 44pt. */
+export const DRAWER_CLOSE_HIT_SLOP = 8;
+
+export const drawerVariants = tv({
+	slots: {
+		/** The foundation's scrim token. The fade is `Overlay.Scrim`'s own. */
+		scrim: "bg-overlay",
+		/**
+		 * A window-sized frame the panel is positioned in, laid out left to
+		 * right whatever the app's direction, so the panel's classes and its
+		 * safe-area padding are physical — the same terms its motion and its pan
+		 * are measured in. `inner` restores the app's direction for the content.
+		 */
+		positioner: "absolute inset-0",
+		/**
+		 * The panel. Docked flush to its edge with square corners there, and the
+		 * card corner on the two corners facing the app. `popover` because a
+		 * drawer is a layer over the app, as `Dialog` and `BottomSheet` are.
+		 */
+		content: "absolute overflow-hidden bg-popover",
+		/** The column inside the safe-area padding, laid out in the app's direction. */
+		inner: "flex-1",
+		/** Title block and ✕ in a row; the ✕ sits at the trailing edge. */
+		header: "flex-row items-start gap-3 px-5 pt-5 pb-3",
+		/** The title and description column, taking the row's slack. */
+		heading: "flex-1 gap-1",
+		body: "flex-1",
+		/** The body's padding, on the scroll content so it scrolls with it. */
+		bodyContent: "gap-3 px-5 pb-5",
+		/** `mt-auto` so it sits at the panel's end even when no body takes the slack. */
+		footer: "mt-auto flex-row items-center justify-end gap-2 border-border border-t px-5 py-4",
+		close: "shrink-0",
+	},
+	variants: {
+		edge: {
+			left: { content: "inset-y-0 left-0 rounded-r-lg" },
+			right: { content: "inset-y-0 right-0 rounded-l-lg" },
+			top: { content: "inset-x-0 top-0 rounded-b-lg" },
+			bottom: { content: "inset-x-0 bottom-0 rounded-t-lg" },
+		},
+	},
+	defaultVariants: {
+		edge: "left",
+	},
+});
+
+/**
+ * There is no `title` or `description` slot. Both *are* text presets with no
+ * layout of their own — the ✕ sits in the flow, so the title needs no
+ * clearance — and `tv` emits `undefined` for an empty class string. The parts
+ * merge a caller's `className` with `cn()` instead, as `Dialog`'s description does.
+ */
+export type DrawerVariantProps = VariantProps<typeof drawerVariants>;
+
+/**
+ * The physical edge a side docks to. `start` is the left edge in a
+ * left-to-right layout and the right edge in a right-to-left one.
+ */
+export function resolveDrawerEdge(side: DrawerSide, isRTL: boolean): DrawerEdge {
+	if (side === "start") return isRTL ? "right" : "left";
+	if (side === "end") return isRTL ? "left" : "right";
+	return side;
+}
+
+/**
+ * The panel's width (a left or right edge) or height (top or bottom), from the
+ * window's extent along the same axis. Whole points, never negative.
+ */
+export function resolveDrawerExtent(size: DrawerSize, windowExtent: number): number {
+	if (windowExtent <= 0) return 0;
+	const { fraction, max } = DRAWER_SIZE_EXTENT[size];
+	return Math.round(Math.min(windowExtent * fraction, max));
+}
+
+/**
+ * The translate that puts the panel `progress` of the way in: 0 is the whole
+ * extent off its edge, 1 is docked.
+ *
+ * A worklet, read in the panel's animated style. Flat on purpose — a
+ * module-scope worklet never calls another function.
+ */
+export function resolveDrawerOffset(
+	edge: DrawerEdge,
+	extent: number,
+	progress: number
+): { translateX: number; translateY: number } {
+	"worklet";
+	const hidden = extent * (1 - progress);
+	if (edge === "left") return { translateX: -hidden, translateY: 0 };
+	if (edge === "right") return { translateX: hidden, translateY: 0 };
+	if (edge === "top") return { translateX: 0, translateY: -hidden };
+	return { translateX: 0, translateY: hidden };
+}
+
+/**
+ * Where the panel sits for a finger's travel along its axis.
+ *
+ * Toward the docked edge — the way it would leave — the panel follows the
+ * finger one to one. Away from it, into the app, it rubber-bands toward
+ * `DRAWER_RUBBER_BAND` and never reaches it, so the panel gives a little and
+ * says it goes no further. The result has the translation's sign.
+ */
+export function resolveDrawerDrag(edge: DrawerEdge, translation: number): number {
+	"worklet";
+	const sign = edge === "left" || edge === "top" ? -1 : 1;
+	const toward = translation * sign;
+	if (toward >= 0) return translation;
+	const away = -toward;
+	return -sign * (away / (1 + away / DRAWER_RUBBER_BAND));
+}
+
+/** How much of the extent a drag has carried the panel toward its edge, 0 to 1. */
+export function resolveDrawerDragFraction(edge: DrawerEdge, translation: number, extent: number): number {
+	"worklet";
+	if (extent <= 0) return 0;
+	const sign = edge === "left" || edge === "top" ? -1 : 1;
+	return Math.min(1, Math.max(0, (translation * sign) / extent));
+}
+
+export type DrawerReleaseInput = {
+	edge: DrawerEdge;
+	/** The finger's travel along the panel's axis, physical sign. */
+	translation: number;
+	/** The release velocity along the same axis, pt/s, physical sign. */
+	velocity: number;
+	extent: number;
+};
+
+/**
+ * Whether a released swipe dismisses the drawer or puts it back.
+ *
+ * A fling away from the edge always restores — the user changed their mind
+ * mid-swipe. Otherwise a fling toward the edge faster than
+ * `DRAWER_FLING_VELOCITY`, or a drag past `DRAWER_DISMISS_FRACTION` of the
+ * extent, dismisses.
+ */
+export function resolveDrawerRelease({ edge, translation, velocity, extent }: DrawerReleaseInput): DrawerRelease {
+	"worklet";
+	if (extent <= 0) return "restore";
+	const sign = edge === "left" || edge === "top" ? -1 : 1;
+	const toward = velocity * sign;
+	if (toward < -DRAWER_FLING_VELOCITY) return "restore";
+	if (toward > DRAWER_FLING_VELOCITY) return "dismiss";
+	return (translation * sign) / extent > DRAWER_DISMISS_FRACTION ? "dismiss" : "restore";
+}
+
+/**
+ * How long the panel takes to cover the rest of its way out after a dismissing
+ * release: the remaining distance at the release speed, held inside
+ * `DRAWER_RELEASE_MS` so a flick does not snap and a slow release does not drift.
+ */
+export function resolveDrawerExitDuration({ remaining, velocity }: { remaining: number; velocity: number }): number {
+	"worklet";
+	const speed = Math.abs(velocity);
+	if (remaining <= 0) return DRAWER_RELEASE_MS.min;
+	if (speed === 0) return DRAWER_RELEASE_MS.max;
+	return Math.min(DRAWER_RELEASE_MS.max, Math.max(DRAWER_RELEASE_MS.min, (remaining / speed) * 1000));
+}
+
+export type DrawerInsets = { top: number; right: number; bottom: number; left: number };
+
+/**
+ * The safe-area padding a panel docked to `edge` takes.
+ *
+ * Every side that meets a screen edge pads its inset — the docked side and the
+ * two beside it — so a start drawer clears the status bar and the home
+ * indicator. The side facing the app sits nowhere near a screen edge, and pads
+ * nothing.
+ */
+export function resolveDrawerInsets(edge: DrawerEdge, insets: DrawerInsets): DrawerInsets {
+	return {
+		top: edge === "bottom" ? 0 : insets.top,
+		right: edge === "left" ? 0 : insets.right,
+		bottom: edge === "top" ? 0 : insets.bottom,
+		left: edge === "right" ? 0 : insets.left,
+	};
+}
+
+/**
+ * The panel's full width or height: the size's extent plus the inset on the
+ * docked edge.
+ *
+ * The size measures the content, not the safe-area band it sits under — a
+ * top drawer at `sm` would otherwise hand a third of its 280pt to the status
+ * bar and clip its rows. The motion uses this, so the panel starts fully off
+ * screen.
+ */
+export function resolveDrawerFrameExtent(edge: DrawerEdge, extent: number, insets: DrawerInsets): number {
+	return extent + insets[edge];
+}

package/src/components/drawer/index.ts

@@ -0,0 +1,41 @@
+export { Drawer, type DrawerProps } from "./drawer";
+export { type DrawerContextValue, useDrawer, useDrawerContext } from "./drawer.context";
+export {
+	DRAWER_CLOSE_HIT_SLOP,
+	DRAWER_DISMISS_FRACTION,
+	DRAWER_EDGES,
+	DRAWER_FLING_VELOCITY,
+	DRAWER_PAN_ACTIVE_OFFSET,
+	DRAWER_RELEASE_MS,
+	DRAWER_RUBBER_BAND,
+	DRAWER_SCRIM_TOKEN,
+	DRAWER_SIDES,
+	DRAWER_SIZE_EXTENT,
+	DRAWER_SIZES,
+	type DrawerEdge,
+	type DrawerInsets,
+	type DrawerRelease,
+	type DrawerReleaseInput,
+	type DrawerSide,
+	type DrawerSize,
+	type DrawerVariantProps,
+	drawerVariants,
+	resolveDrawerDrag,
+	resolveDrawerDragFraction,
+	resolveDrawerEdge,
+	resolveDrawerExitDuration,
+	resolveDrawerExtent,
+	resolveDrawerFrameExtent,
+	resolveDrawerInsets,
+	resolveDrawerOffset,
+	resolveDrawerRelease,
+} from "./drawer.variants";
+export type { DrawerBodyProps } from "./drawer-body";
+export type { DrawerCloseProps } from "./drawer-close";
+export type { DrawerContentProps } from "./drawer-content";
+export type { DrawerDescriptionProps } from "./drawer-description";
+export type { DrawerFooterProps } from "./drawer-footer";
+export type { DrawerHeaderProps } from "./drawer-header";
+export type { DrawerTitleProps } from "./drawer-title";
+export type { DrawerTriggerProps } from "./drawer-trigger";
+export type { UseDrawerPanOptions } from "./use-drawer-pan";

package/src/components/drawer/use-drawer-pan.ts

@@ -0,0 +1,108 @@
+import { useMemo } from "react";
+import { Gesture, type PanGesture } from "react-native-gesture-handler";
+import { cancelAnimation, Easing, type SharedValue, useSharedValue, withTiming } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { OVERLAY_MOTION } from "../overlay/overlay.variants";
+import { playHaptic } from "../pressable";
+import {
+	DRAWER_DISMISS_FRACTION,
+	DRAWER_PAN_ACTIVE_OFFSET,
+	type DrawerEdge,
+	resolveDrawerDrag,
+	resolveDrawerDragFraction,
+	resolveDrawerExitDuration,
+	resolveDrawerRelease,
+} from "./drawer.variants";
+
+export type UseDrawerPanOptions = {
+	edge: DrawerEdge;
+	/** The panel's width or height along its axis. */
+	extent: number;
+	isEnabled: boolean;
+	/** The panel's displacement along its axis, physical sign — written by the pan, read by the panel's style. */
+	drag: SharedValue<number>;
+	/** Called once a dismissing release has carried the panel off its edge. */
+	onDismiss: () => void;
+};
+
+const RESTORE_EASING = Easing.out(Easing.cubic);
+const PAN_RANGE: [number, number] = [-DRAWER_PAN_ACTIVE_OFFSET, DRAWER_PAN_ACTIVE_OFFSET];
+
+/**
+ * The panel's swipe-to-dismiss.
+ *
+ * The pan claims the touch only after `DRAWER_PAN_ACTIVE_OFFSET` of travel
+ * along the panel's axis and fails on the same travel across it, so a tap
+ * reaches the row under it and a vertical scroll in a start or end drawer's
+ * body never moves the drawer.
+ *
+ * While it runs the panel follows the finger toward its edge and rubber-bands
+ * away from it (`resolveDrawerDrag`), and a `selection` haptic marks each
+ * crossing of the dismiss threshold — the moment letting go changes what
+ * happens. On release `resolveDrawerRelease` decides: a dismiss **continues
+ * from where the finger left the panel**, at the release speed, and closes the
+ * drawer when it lands; a restore eases back to docked.
+ *
+ * The handlers are built in this hook, so they may call the module-scope
+ * worklets in `drawer.variants` — those, being module-scope, call nothing.
+ * Per-gesture memory lives in shared values: each worklet gets its own copy of
+ * a captured `let`.
+ */
+export function useDrawerPan({ edge, extent, isEnabled, drag, onDismiss }: UseDrawerPanOptions): PanGesture {
+	const isDragging = useSharedValue(false);
+	const isPastThreshold = useSharedValue(false);
+
+	return useMemo(() => {
+		const isHorizontal = edge === "left" || edge === "right";
+		const sign = edge === "left" || edge === "top" ? -1 : 1;
+		const pan = Gesture.Pan().enabled(isEnabled).shouldCancelWhenOutside(false);
+		if (isHorizontal) {
+			pan.activeOffsetX(PAN_RANGE).failOffsetY(PAN_RANGE);
+		} else {
+			pan.activeOffsetY(PAN_RANGE).failOffsetX(PAN_RANGE);
+		}
+
+		return pan
+			.onStart(() => {
+				"worklet";
+				cancelAnimation(drag);
+				isDragging.value = true;
+				isPastThreshold.value = false;
+			})
+			.onUpdate((event) => {
+				"worklet";
+				const translation = isHorizontal ? event.translationX : event.translationY;
+				drag.value = resolveDrawerDrag(edge, translation);
+
+				const isPast = resolveDrawerDragFraction(edge, translation, extent) > DRAWER_DISMISS_FRACTION;
+				if (isPast !== isPastThreshold.value) {
+					isPastThreshold.value = isPast;
+					playHaptic("selection");
+				}
+			})
+			.onFinalize((event) => {
+				"worklet";
+				// A touch that never activated — a tap, a scroll across the axis —
+				// must not touch `drag`: a dismiss may still be animating it.
+				if (!isDragging.value) return;
+				isDragging.value = false;
+
+				const translation = isHorizontal ? event.translationX : event.translationY;
+				const velocity = isHorizontal ? event.velocityX : event.velocityY;
+				const release = resolveDrawerRelease({ edge, extent, translation, velocity });
+
+				if (release === "dismiss") {
+					const duration = resolveDrawerExitDuration({
+						remaining: Math.max(0, extent - Math.abs(drag.value)),
+						velocity,
+					});
+					drag.value = withTiming(sign * extent, { duration, easing: Easing.linear }, (finished) => {
+						if (finished) scheduleOnRN(onDismiss);
+					});
+					return;
+				}
+
+				drag.value = withTiming(0, { duration: OVERLAY_MOTION.enterMs, easing: RESTORE_EASING });
+			});
+	}, [drag, edge, extent, isDragging, isEnabled, isPastThreshold, onDismiss]);
+}

package/src/components/empty-state/AGENTS.md

@@ -0,0 +1,90 @@
+# EmptyState
+
+A placeholder for a list or a screen with nothing in it yet. Compound root plus
+five parts: `Header`, `Media`, `Title`, `Description`, `Content`.
+
+`import { EmptyState } from "@delacour/react-native-ui/empty-state";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/empty-state` |
+| `empty-state.tsx` | Root + the `Object.assign` compound surface |
+| `empty-state-header.tsx` | `EmptyState.Header` |
+| `empty-state-media.tsx` | `EmptyState.Media`, and the icon cascade it owns |
+| `empty-state-title.tsx` | `EmptyState.Title` |
+| `empty-state-description.tsx` | `EmptyState.Description` |
+| `empty-state-content.tsx` | `EmptyState.Content` |
+| `empty-state.context.tsx` | `EmptyStateProvider`, `useEmptyState()`, `useEmptyStateContext()`, `useEmptyStatePart()` |
+| `empty-state.types.ts` | Prop types shared by two or more parts |
+| `empty-state.variants.ts` | Pure `tv()` slots and the media colour map, no RN imports |
+| `empty-state.variants.test.ts` | |
+
+## Anatomy
+
+```tsx
+<EmptyState>
+  <EmptyState.Header>
+    <EmptyState.Media variant="icon">
+      <Icon icon={IconInbox} />
+    </EmptyState.Media>
+    <EmptyState.Title>No messages</EmptyState.Title>
+    <EmptyState.Description>New conversations will show up here.</EmptyState.Description>
+  </EmptyState.Header>
+  <EmptyState.Content>
+    <Button onPress={compose}>New message</Button>
+  </EmptyState.Content>
+</EmptyState>
+```
+
+## Design
+
+- **Variants**: `default`, `card`. **Sizes**: `sm`, `md`, `lg`. **Media
+  variants**: `default`, `icon`. Size drives the padding, both gaps, the media
+  box, the glyph inside it and both type scales — one axis rather than seven
+  numbers that drift apart. The tests assert every one of them ascends.
+- **`default` grows; it never uses `flex-1`.** `flex-1` is a zero flex basis, so
+  inside a `ScrollView`'s content container, which has no height to grow into,
+  the block collapsed to nothing. `grow` keeps the content height as a floor and
+  fills whatever spare height a bounded parent has — which is what "fills its
+  container" has to mean in both places. A test holds the class.
+- **`card` is dashed.** A dashed outline is the conventional mark of a slot
+  waiting for content, and it stops an embedded empty state reading as one
+  more populated card beside real ones. The corner is the card step,
+  `rounded-lg`, stepping to `rounded-md` at `sm` like `ListGroup` and
+  `Accordion`. The border is reserved on both variants (`border-transparent` on
+  `default`), so switching variant changes a colour and never the layout.
+- **A size is padding, never a height.** The description respects OS font
+  scaling; a fixed height would clip it at a large accessibility step.
+- **Icons are composed, never passed as props.** `Media` wraps its subtree in an
+  `IconDefaultsProvider` carrying the `mediaIcon` slot — a step on the shared
+  `--spacing-icon-*` scale — and `EMPTY_STATE_MEDIA_FOREGROUND_TOKEN[variant]`.
+  A bare glyph is `muted-foreground`, because the picture is decoration and must
+  not outweigh the title. Inside the tinted `icon` box it takes `foreground`:
+  `muted-foreground` on `bg-muted` is two greys a step apart.
+- **The glyph uses the same three steps inside the box and out of it.** The
+  icon scale tops out at `icon-2xl`, so a bare glyph one step larger than the
+  boxed one would have left `md` and `lg` identical.
+- **The media sits further from the title than the title from its
+  description.** The header's `gap` spaces the two lines; the media adds a
+  bottom margin on top of it, so text reads as one unit and the picture as
+  something above it.
+- **`Media` is hidden from assistive technology by default.** The title already
+  says what the picture shows, and a screen reader saying "image" first only
+  delays it. Media that carries meaning of its own opts back in with
+  `accessibilityElementsHidden={false}` and `importantForAccessibility="auto"` —
+  both are spread after the defaults.
+- **`Title` is announced as a header.** An empty screen's title is what the
+  screen *is*, and the heading rotor should land on it.
+- **Actions are a wrapping row, not a column.** Two actions sit side by side and
+  fall to a second line only when they must. `className="flex-col"` stacks them.
+  Button size is the caller's choice — `Content` sets nothing on its children, so
+  a `Button` keeps every prop it already has.
+- **Header and content cap at `max-w-sm`.** On a tablet or in landscape a
+  description stretched edge to edge is a line too long to read.
+- **Colour goes on the text parts.** No `View` slot carries a `text-*` utility;
+  a React Native `View` cannot cascade colour to a `Text`. The tests assert it.
+- **No state of its own.** An empty state is a presentation of *someone else's*
+  state — a list's length, a query's result. Loading and disabled belong to the
+  `Button`s inside it, which already have them.

package/src/components/empty-state/empty-state-content.tsx

@@ -0,0 +1,17 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { useEmptyStatePart } from "./empty-state.context";
+import type { EmptyStateSlotProps } from "./empty-state.types";
+import { emptyStateVariants } from "./empty-state.variants";
+
+/**
+ * The action slot under the header — usually one or two `Button`s.
+ *
+ * A centred row that wraps, so two actions sit side by side and fall onto a
+ * second line only when they have to. Pass `className="flex-col"` to stack them.
+ */
+export function EmptyStateContent({ className, ...props }: EmptyStateSlotProps): ReactElement {
+	const { size } = useEmptyStatePart("EmptyState.Content");
+	return <View className={emptyStateVariants({ size }).content({ className })} {...props} />;
+}
+EmptyStateContent.displayName = "DelacourUI.EmptyState.Content";

package/src/components/empty-state/empty-state-description.tsx

@@ -0,0 +1,12 @@
+import type { ReactElement } from "react";
+import { Text } from "../text";
+import { useEmptyStatePart } from "./empty-state.context";
+import type { EmptyStateTextProps } from "./empty-state.types";
+import { emptyStateVariants } from "./empty-state.variants";
+
+/** The supporting line under the title — a step down in scale, on the muted token. */
+export function EmptyStateDescription({ className, ...props }: EmptyStateTextProps): ReactElement {
+	const { size } = useEmptyStatePart("EmptyState.Description");
+	return <Text className={emptyStateVariants({ size }).description({ className })} {...props} />;
+}
+EmptyStateDescription.displayName = "DelacourUI.EmptyState.Description";

package/src/components/empty-state/empty-state-header.tsx

@@ -0,0 +1,17 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { useEmptyStatePart } from "./empty-state.context";
+import type { EmptyStateSlotProps } from "./empty-state.types";
+import { emptyStateVariants } from "./empty-state.variants";
+
+/**
+ * The centred column holding the media, the title and the description.
+ *
+ * Its own gap spaces the title from the description; the media adds a margin
+ * of its own on top, so the picture sits apart from the two lines of text.
+ */
+export function EmptyStateHeader({ className, ...props }: EmptyStateSlotProps): ReactElement {
+	const { size } = useEmptyStatePart("EmptyState.Header");
+	return <View className={emptyStateVariants({ size }).header({ className })} {...props} />;
+}
+EmptyStateHeader.displayName = "DelacourUI.EmptyState.Header";

package/src/components/empty-state/empty-state-media.tsx

@@ -0,0 +1,56 @@
+import { type ReactElement, useMemo } from "react";
+import { View } from "react-native";
+import { IconDefaultsProvider } from "../icon";
+import { useEmptyStatePart } from "./empty-state.context";
+import type { EmptyStateSlotProps } from "./empty-state.types";
+import {
+	EMPTY_STATE_MEDIA_FOREGROUND_TOKEN,
+	type EmptyStateMediaVariant,
+	emptyStateVariants,
+} from "./empty-state.variants";
+
+export type EmptyStateMediaProps = EmptyStateSlotProps & {
+	/**
+	 * `icon` draws a tinted, rounded box sized for a glyph. `default` draws
+	 * nothing behind its content, for an illustration or an image that sizes
+	 * itself.
+	 */
+	variant?: EmptyStateMediaVariant;
+};
+
+/**
+ * The picture above the title.
+ *
+ * Its subtree inherits an icon size on the shared scale and a colour token, so a
+ * bare `<Icon icon={IconInbox} />` comes out right with nothing said at the call
+ * site — the same cascade a `Button` gives its icons.
+ *
+ * Hidden from assistive technology by default: the title already says what the
+ * picture shows, and a screen reader announcing "image" first only delays it.
+ * Pass `accessibilityElementsHidden={false}` and
+ * `importantForAccessibility="auto"` for media that carries meaning of its own.
+ */
+export function EmptyStateMedia({
+	variant = "default",
+	className,
+	children,
+	...props
+}: EmptyStateMediaProps): ReactElement {
+	const { size } = useEmptyStatePart("EmptyState.Media");
+	const slots = emptyStateVariants({ size, media: variant });
+	const iconClassName = slots.mediaIcon();
+	const color = EMPTY_STATE_MEDIA_FOREGROUND_TOKEN[variant];
+	const iconDefaults = useMemo(() => ({ className: iconClassName, color }), [iconClassName, color]);
+
+	return (
+		<View
+			accessibilityElementsHidden
+			className={slots.media({ className })}
+			importantForAccessibility="no-hide-descendants"
+			{...props}
+		>
+			<IconDefaultsProvider value={iconDefaults}>{children}</IconDefaultsProvider>
+		</View>
+	);
+}
+EmptyStateMedia.displayName = "DelacourUI.EmptyState.Media";

package/src/components/empty-state/empty-state-title.tsx

@@ -0,0 +1,18 @@
+import type { ReactElement } from "react";
+import { Text } from "../text";
+import { useEmptyStatePart } from "./empty-state.context";
+import type { EmptyStateTextProps } from "./empty-state.types";
+import { emptyStateVariants } from "./empty-state.variants";
+
+/**
+ * The empty state's heading.
+ *
+ * Announced as a header, so a screen reader's heading rotor lands on it — the
+ * title is what an empty screen *is*. Carries its own colour and type scale
+ * from context: a React Native `View` does not cascade colour to a `Text`.
+ */
+export function EmptyStateTitle({ className, ...props }: EmptyStateTextProps): ReactElement {
+	const { size } = useEmptyStatePart("EmptyState.Title");
+	return <Text accessibilityRole="header" className={emptyStateVariants({ size }).title({ className })} {...props} />;
+}
+EmptyStateTitle.displayName = "DelacourUI.EmptyState.Title";

package/src/components/empty-state/empty-state.context.tsx

@@ -0,0 +1,65 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { EmptyStateSize, EmptyStateVariant } from "./empty-state.variants";
+
+export type EmptyStateContextValue = {
+	/** Size of the empty state. */
+	size: EmptyStateSize;
+	/** How the empty state sits on the screen. */
+	variant: EmptyStateVariant;
+};
+
+const EmptyStateContext = createContext<EmptyStateContextValue | null>(null);
+
+/**
+ * Supplies the enclosing empty state's size and variant to its subtree.
+ *
+ * Lives in its own module, importing nothing but `empty-state.variants`, so a
+ * part can read it without importing `./empty-state` and closing a cycle
+ * through the root. See the package AGENTS.md, rule 3.
+ */
+export function EmptyStateProvider({
+	value,
+	children,
+}: {
+	value: EmptyStateContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <EmptyStateContext value={value}>{children}</EmptyStateContext>;
+}
+EmptyStateProvider.displayName = "DelacourUI.EmptyState.Provider";
+
+/** The enclosing empty state's context, or null outside an `<EmptyState>`. */
+export function useEmptyStateContext(): EmptyStateContextValue | null {
+	return use(EmptyStateContext);
+}
+
+/**
+ * Reads the enclosing empty state's size and variant.
+ *
+ * Lets a custom part — an illustration, a link row — scale with the block
+ * without the root passing props down. Throws outside an `<EmptyState>`; use
+ * {@link useEmptyStateContext} where the enclosing empty state is optional.
+ */
+export function useEmptyState(): EmptyStateContextValue {
+	const context = useEmptyStateContext();
+	if (!context) {
+		throw new Error("useEmptyState must be called inside an <EmptyState>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing empty state'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 useEmptyState}, whose error names the hook rather than a
+ * part.
+ */
+export function useEmptyStatePart(component: string): EmptyStateContextValue {
+	const context = useEmptyStateContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside an <EmptyState>.`);
+	}
+	return context;
+}