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

package/src/components/dialog/dialog.tsx

@@ -0,0 +1,119 @@
+import { type ReactElement, type ReactNode, useCallback, useId, useMemo, useRef } from "react";
+import { useControllableState } from "../../hooks/use-controllable-state";
+import { type DialogFocusTarget, type DialogInternalValue, DialogProvider } from "./dialog.context";
+import { DialogBody } from "./dialog-body";
+import { DialogClose } from "./dialog-close";
+import { DialogContent } from "./dialog-content";
+import { DialogDescription } from "./dialog-description";
+import { DialogFooter } from "./dialog-footer";
+import { DialogHeader } from "./dialog-header";
+import { DialogTitle } from "./dialog-title";
+import { DialogTrigger } from "./dialog-trigger";
+
+export type DialogProps = {
+	/** Whether the dialog is open. Pass it to control the dialog; omit it and the dialog holds its own state. */
+	isOpen?: boolean;
+	/** Whether an uncontrolled dialog starts open. Default false. */
+	defaultOpen?: boolean;
+	/** Called with the new value whenever the dialog opens or closes, from any path. */
+	onOpenChange?: (isOpen: boolean) => void;
+	/**
+	 * Whether a scrim tap, Android back and the iOS escape gesture close it.
+	 * `false` makes an alert dialog: only its own actions close it. Default true.
+	 */
+	isDismissible?: boolean;
+	children: ReactNode;
+};
+
+function DialogRoot({
+	isOpen,
+	defaultOpen = false,
+	onOpenChange,
+	isDismissible = true,
+	children,
+}: DialogProps): ReactElement {
+	const [open, setControllableOpen] = useControllableState({
+		defaultValue: defaultOpen,
+		onChange: onOpenChange,
+		value: isOpen,
+	});
+
+	// Every path — trigger, close, scrim, back, escape — lands here, and a
+	// second close while the first is still exiting would report twice.
+	const setOpen = useCallback(
+		(next: boolean) => {
+			if (next !== open) setControllableOpen(next);
+		},
+		[open, setControllableOpen]
+	);
+	const close = useCallback(() => setOpen(false), [setOpen]);
+
+	const titleId = useId();
+	const descriptionId = useId();
+	const triggerRef = useRef<DialogFocusTarget | null>(null);
+	const titleRef = useRef<DialogFocusTarget | null>(null);
+
+	const value = useMemo<DialogInternalValue>(
+		() => ({ close, descriptionId, isDismissible, isOpen: open, setOpen, titleId, titleRef, triggerRef }),
+		[close, descriptionId, isDismissible, open, setOpen, titleId]
+	);
+
+	return <DialogProvider value={value}>{children}</DialogProvider>;
+}
+
+/**
+ * A centred card over a dimmed app that asks for a decision or a short input
+ * before the user goes on — confirm a delete, rename a file, accept terms.
+ *
+ * It takes the whole screen. Use a `Popover` when the surrounding context must
+ * stay visible, and a `BottomSheet` when the content is long or scrolls. With
+ * `isDismissible={false}` it is an alert dialog: only its own actions close it.
+ *
+ * Draws through `Overlay.Portal`, so the app needs `OverlayProvider` mounted
+ * once at its root.
+ *
+ * @example
+ * <Dialog>
+ *   <Dialog.Trigger asChild>
+ *     <Button variant="destructive">Delete</Button>
+ *   </Dialog.Trigger>
+ *   <Dialog.Content>
+ *     <Dialog.Close />
+ *     <Dialog.Header>
+ *       <Dialog.Title>Delete project?</Dialog.Title>
+ *       <Dialog.Description>This cannot be undone.</Dialog.Description>
+ *     </Dialog.Header>
+ *     <Dialog.Footer>
+ *       <Dialog.Close asChild>
+ *         <Button variant="secondary">Cancel</Button>
+ *       </Dialog.Close>
+ *       <Button variant="destructive" onPress={remove}>Delete</Button>
+ *     </Dialog.Footer>
+ *   </Dialog.Content>
+ * </Dialog>
+ *
+ * @example
+ * // Controlled, and an alert dialog.
+ * <Dialog isOpen={isOpen} onOpenChange={setIsOpen} isDismissible={false}>
+ *   …
+ * </Dialog>
+ */
+export const Dialog = Object.assign(DialogRoot, {
+	/** The control that opens it. `asChild` donates the press to a `Button`. */
+	Trigger: DialogTrigger,
+	/** The portal, scrim and card. Renders nothing while closed. */
+	Content: DialogContent,
+	/** The ✕ in the corner, or — with `asChild` — any control that closes it. */
+	Close: DialogClose,
+	/** The column holding the title and description. */
+	Header: DialogHeader,
+	/** The heading — a `Text.Header` the card is labelled by. */
+	Title: DialogTitle,
+	/** Muted supporting copy — a `Text.Paragraph`. */
+	Description: DialogDescription,
+	/** What the dialog asks for, between the header and the footer. */
+	Body: DialogBody,
+	/** The actions — a row, or a stacked column on an `sm` card. */
+	Footer: DialogFooter,
+	displayName: "DelacourUI.Dialog",
+});

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

@@ -0,0 +1,224 @@
+import { describe, expect, test } from "bun:test";
+import { declaredTokens } from "../../styles/theme-tokens.test";
+import {
+	DIALOG_CLOSE_HIT_SLOP,
+	DIALOG_ENTER_SCALE,
+	DIALOG_ENTER_TRANSLATE_Y,
+	DIALOG_FOOTER_VARIANTS,
+	DIALOG_KEYBOARD_MARGIN,
+	DIALOG_SCRIM_TOKEN,
+	DIALOG_SIZE_CLASS,
+	DIALOG_SIZES,
+	dialogVariants,
+	resolveDialogFooterDirection,
+	resolveDialogKeyboardLift,
+	resolveDialogRole,
+} from "./dialog.variants";
+
+const LIGHT = declaredTokens("light");
+const DARK = declaredTokens("dark");
+
+/** `border-t` and friends set a width, not a colour, and name no token. */
+const STRUCTURAL_BORDER_SUFFIXES = new Set(["t", "b", "l", "r", "x", "y", "s", "e"]);
+
+/** Every theme token a class string paints with, with any `/alpha` suffix dropped. */
+function colorTokens(cls: string): string[] {
+	const tokens: string[] = [];
+
+	for (const [, utility, token] of cls.matchAll(/\b(bg|border|text)-([a-z][\w-]*)(?:\/\d+)?\b/g)) {
+		if (utility === "border" && STRUCTURAL_BORDER_SUFFIXES.has(token)) continue;
+		tokens.push(token);
+	}
+
+	return tokens;
+}
+
+/**
+ * The slots this component declares, pinned rather than derived — `tv` adds a
+ * `base` slot of its own, and a new slot has to be listed here before the
+ * token sweep can miss it.
+ */
+const SLOT_NAMES = ["scrim", "positioner", "content", "close", "header", "title", "body", "footer"] as const;
+
+describe("dialogVariants", () => {
+	test("the scrim paints the overlay token, which exists in both themes", () => {
+		expect(dialogVariants().scrim()).toContain(`bg-${DIALOG_SCRIM_TOKEN}`);
+		expect(LIGHT.has(DIALOG_SCRIM_TOKEN)).toBe(true);
+		expect(DARK.has(DIALOG_SCRIM_TOKEN)).toBe(true);
+	});
+
+	test("the positioner fills the window, centres the card and keeps the screen gutter", () => {
+		const positioner = dialogVariants().positioner();
+		expect(positioner).toContain("absolute");
+		expect(positioner).toContain("inset-0");
+		expect(positioner).toContain("items-center");
+		expect(positioner).toContain("justify-center");
+		expect(positioner).toContain("px-screen-gutter");
+	});
+
+	test("the card is a popover surface with the card corner and a hairline", () => {
+		const content = dialogVariants().content();
+		expect(content).toContain("bg-popover");
+		expect(content).toContain("rounded-lg");
+		expect(content).toContain("border");
+		expect(content).toContain("border-border");
+		expect(content).toContain("w-full");
+	});
+
+	test("each size pins its own max width", () => {
+		expect(DIALOG_SIZE_CLASS).toEqual({
+			full: "max-w-full",
+			lg: "max-w-[520px]",
+			md: "max-w-[400px]",
+			sm: "max-w-[320px]",
+		});
+		for (const size of DIALOG_SIZES) {
+			expect(dialogVariants({ size }).content()).toContain(DIALOG_SIZE_CLASS[size]);
+		}
+	});
+
+	test("defaults to md", () => {
+		expect(dialogVariants().content()).toContain(DIALOG_SIZE_CLASS.md);
+	});
+
+	test("a caller's className reaches the card and wins a conflict", () => {
+		const content = dialogVariants().content({ className: "rounded-2xl" });
+		expect(content).toContain("rounded-2xl");
+		expect(content).not.toContain("rounded-lg");
+	});
+
+	test("the title reserves clearance for the close glyph and carries no type of its own", () => {
+		const title = dialogVariants().title();
+		expect(title).toBe("pr-8");
+		expect(title).not.toMatch(/\btext-(xs|sm|base|lg|xl|\dxl)\b/);
+		expect(title).not.toMatch(/\bfont-/);
+	});
+
+	test("the close glyph sits in the card's top-right corner", () => {
+		const close = dialogVariants().close();
+		expect(close).toContain("absolute");
+		expect(close).toContain("top-");
+		expect(close).toContain("right-");
+	});
+
+	test("a plain footer is a right-aligned row inside the card padding", () => {
+		const footer = dialogVariants({ footer: "plain" }).footer();
+		expect(footer).toContain("flex-row");
+		expect(footer).toContain("justify-end");
+		expect(footer).toContain("gap-2");
+		expect(footer).not.toContain("bg-muted");
+	});
+
+	test("a panel footer bleeds to the card's edges on a muted band under a hairline", () => {
+		const footer = dialogVariants({ footer: "panel" }).footer();
+		expect(footer).toContain("bg-muted");
+		expect(footer).toContain("border-t");
+		expect(footer).toContain("border-border");
+		expect(footer).toMatch(/-mx-\d/);
+		expect(footer).toMatch(/-mb-\d/);
+		expect(footer).toContain("rounded-b-lg");
+	});
+
+	test("a column footer stacks its actions full width", () => {
+		const footer = dialogVariants({ footer: "plain", footerDirection: "column" }).footer();
+		expect(footer).toContain("flex-col");
+		expect(footer).not.toContain("flex-row");
+	});
+
+	test("the footer variants are the two the spec names", () => {
+		expect([...DIALOG_FOOTER_VARIANTS]).toEqual(["plain", "panel"]);
+	});
+});
+
+describe("every token the slots name", () => {
+	test("is declared in both variants of theme.css", () => {
+		for (const size of DIALOG_SIZES) {
+			for (const footer of DIALOG_FOOTER_VARIANTS) {
+				const slots = dialogVariants({ footer, size });
+				for (const name of SLOT_NAMES) {
+					for (const token of colorTokens(slots[name]())) {
+						expect({ inLight: LIGHT.has(token), slot: name, token }).toEqual({ inLight: true, slot: name, token });
+						expect({ inDark: DARK.has(token), slot: name, token }).toEqual({ inDark: true, slot: name, token });
+					}
+				}
+			}
+		}
+	});
+
+	test("the reader found tokens at all", () => {
+		expect(colorTokens(dialogVariants().content())).toEqual(expect.arrayContaining(["popover", "border"]));
+		expect(colorTokens(dialogVariants({ footer: "panel" }).footer())).toEqual(
+			expect.arrayContaining(["muted", "border"])
+		);
+	});
+});
+
+describe("resolveDialogFooterDirection", () => {
+	test("stacks on the narrow card only", () => {
+		expect(resolveDialogFooterDirection("sm")).toBe("column");
+		expect(resolveDialogFooterDirection("md")).toBe("row");
+		expect(resolveDialogFooterDirection("lg")).toBe("row");
+		expect(resolveDialogFooterDirection("full")).toBe("row");
+	});
+});
+
+describe("resolveDialogRole", () => {
+	test("a dismissible dialog is a dialog, a non-dismissible one an alert dialog", () => {
+		expect(resolveDialogRole(true)).toBe("dialog");
+		expect(resolveDialogRole(false)).toBe("alertdialog");
+	});
+});
+
+describe("motion constants", () => {
+	test("the card grows into place from just under full size and just below", () => {
+		expect(DIALOG_ENTER_SCALE).toBe(0.96);
+		expect(DIALOG_ENTER_TRANSLATE_Y).toBe(8);
+	});
+});
+
+describe("DIALOG_CLOSE_HIT_SLOP", () => {
+	test("brings a bare corner glyph up toward the 44pt minimum", () => {
+		expect(DIALOG_CLOSE_HIT_SLOP).toBe(8);
+	});
+});
+
+describe("resolveDialogKeyboardLift", () => {
+	const base = { cardBottom: 500, cardTop: 300, margin: DIALOG_KEYBOARD_MARGIN, topInset: 59, windowHeight: 852 };
+
+	test("the margin is 16", () => {
+		expect(DIALOG_KEYBOARD_MARGIN).toBe(16);
+	});
+
+	test("no keyboard, no lift", () => {
+		expect(resolveDialogKeyboardLift({ ...base, keyboardHeight: 0 })).toBe(0);
+	});
+
+	test("a keyboard that stays below the card and its margin does not lift it", () => {
+		// The keyboard's top is at 852 - 300 = 552, clear of 500 + 16.
+		expect(resolveDialogKeyboardLift({ ...base, keyboardHeight: 300 })).toBe(0);
+	});
+
+	test("a keyboard overlapping the card lifts it just clear, plus the margin", () => {
+		// The keyboard's top is at 852 - 400 = 452; the card's bottom needs to be at 436.
+		expect(resolveDialogKeyboardLift({ ...base, keyboardHeight: 400 })).toBe(64);
+	});
+
+	test("accepts the keyboard controller's negative height", () => {
+		expect(resolveDialogKeyboardLift({ ...base, keyboardHeight: -400 })).toBe(64);
+	});
+
+	test("never pushes the card's top under the top safe-area inset", () => {
+		// The card would need 500 + 16 - (852 - 700) = 364, but its top can rise only 300 - 59.
+		expect(resolveDialogKeyboardLift({ ...base, keyboardHeight: 700 })).toBe(241);
+	});
+
+	test("never negative, even for a card already above the inset", () => {
+		expect(resolveDialogKeyboardLift({ ...base, cardTop: 20, keyboardHeight: 700 })).toBe(0);
+	});
+
+	test("an unmeasured card is not lifted", () => {
+		expect(
+			resolveDialogKeyboardLift({ ...base, cardBottom: 0, cardTop: 0, keyboardHeight: 400, windowHeight: 852 })
+		).toBe(0);
+	});
+});

package/src/components/dialog/dialog.variants.ts

@@ -0,0 +1,173 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+
+/** The card's widths, narrowest first. */
+export const DIALOG_SIZES = ["sm", "md", "lg", "full"] as const;
+export type DialogSize = (typeof DIALOG_SIZES)[number];
+
+/** How `Dialog.Footer` sits in the card: a row inside the padding, or a muted band bled to the edges. */
+export const DIALOG_FOOTER_VARIANTS = ["plain", "panel"] as const;
+export type DialogFooterVariant = (typeof DIALOG_FOOTER_VARIANTS)[number];
+
+/** Which way `Dialog.Footer` lays out its actions. */
+export type DialogFooterDirection = "row" | "column";
+
+/** The accessibility role the card announces. */
+export type DialogRole = "dialog" | "alertdialog";
+
+/**
+ * Each size's cap on the card's width.
+ *
+ * Classes, not numbers: the card is `w-full` and the cap is a `max-w-*`, so a
+ * narrow phone shrinks every size to the gutter and a tablet stops it at the
+ * cap. The arbitrary values are written out in full because Tailwind's scanner
+ * is static — a width computed at runtime would compile to nothing.
+ */
+export const DIALOG_SIZE_CLASS = {
+	sm: "max-w-[320px]",
+	md: "max-w-[400px]",
+	lg: "max-w-[520px]",
+	full: "max-w-full",
+} as const satisfies Record<DialogSize, string>;
+
+/** The scrim's token — the foundation's, named here so the test can pin it. */
+export const DIALOG_SCRIM_TOKEN = "overlay";
+
+/** Slop around the corner ✕ — a bare glyph has no capsule to bring it toward 44pt. */
+export const DIALOG_CLOSE_HIT_SLOP = 8;
+
+/** The scale the card grows from on enter. */
+export const DIALOG_ENTER_SCALE = 0.96;
+
+/** How far below its resting place the card starts on enter, in points. */
+export const DIALOG_ENTER_TRANSLATE_Y = 8;
+
+/** The clearance kept between the card's bottom edge and the keyboard's top, in points. */
+export const DIALOG_KEYBOARD_MARGIN = 16;
+
+export const dialogVariants = tv({
+	slots: {
+		/** The foundation's scrim token. The fade is `Overlay.Scrim`'s own. */
+		scrim: "bg-overlay",
+		/**
+		 * The window-sized frame the card is centred in. The gutter is the
+		 * screen's, so a `full` card lines up with the content behind it.
+		 */
+		positioner: "absolute inset-0 items-center justify-center px-screen-gutter",
+		/**
+		 * The card. `popover` because a dialog is a layer over the app — the
+		 * token `BottomSheet` paints with too — and `rounded-lg` because that is
+		 * the card corner (see the package's Sizing section).
+		 */
+		content: "w-full gap-4 rounded-lg border border-border bg-popover p-5",
+		close: "absolute top-4 right-4 z-10",
+		header: "gap-1.5",
+		/**
+		 * Clearance for `Dialog.Close`, and nothing else — reserved on every
+		 * dialog so adding a close never reflows the title. The type is
+		 * `Text.Header`'s; a size here would be a second definition of it.
+		 */
+		title: "pr-8",
+		body: "gap-3",
+		footer: "gap-2",
+	},
+	variants: {
+		size: {
+			sm: { content: DIALOG_SIZE_CLASS.sm },
+			md: { content: DIALOG_SIZE_CLASS.md },
+			lg: { content: DIALOG_SIZE_CLASS.lg },
+			full: { content: DIALOG_SIZE_CLASS.full },
+		},
+		footer: {
+			plain: {},
+			/**
+			 * Bleeds out of the card's `p-5` on three sides, then restores it as
+			 * its own padding, so the band reaches the edges and the hairline runs
+			 * corner to corner. Only the bottom corners round: the top edge meets
+			 * the card's own fill.
+			 */
+			panel: { footer: "-mx-5 -mb-5 mt-1 rounded-b-lg border-border border-t bg-muted px-5 py-4" },
+		},
+		footerDirection: {
+			row: { footer: "flex-row items-center justify-end" },
+			/** Stacked full width, in written order — so the primary action, written last, sits last. */
+			column: { footer: "flex-col" },
+		},
+	},
+	defaultVariants: {
+		size: "md",
+		footer: "plain",
+		footerDirection: "row",
+	},
+});
+
+/**
+ * There is no `description` slot. A description is a muted `Text.Paragraph` in
+ * the header's gap column with no layout of its own, and `tv` emits `undefined`
+ * for an empty class string — a slot no test could assert against. The part
+ * merges the caller's `className` with `cn()` instead, as `BottomSheet`'s does.
+ */
+export type DialogVariantProps = VariantProps<typeof dialogVariants>;
+
+/**
+ * Whether a footer's actions sit side by side or stack.
+ *
+ * Only the `sm` card stacks: two labelled buttons in a row on a 320pt card
+ * leave each label a few characters before it truncates. Pure so the rule is
+ * reachable from `bun test`.
+ */
+export function resolveDialogFooterDirection(size: DialogSize): DialogFooterDirection {
+	return size === "sm" ? "column" : "row";
+}
+
+/**
+ * The role the card announces. A dialog the user cannot dismiss is an alert
+ * dialog: assistive technology tells them only an action will close it.
+ */
+export function resolveDialogRole(isDismissible: boolean): DialogRole {
+	return isDismissible ? "dialog" : "alertdialog";
+}
+
+export type DialogKeyboardLiftInput = {
+	/** The keyboard's height. Either sign — the keyboard controller reports it negative while open. */
+	keyboardHeight: number;
+	/** The card's top edge in window coordinates, before any lift. */
+	cardTop: number;
+	/** The card's bottom edge in window coordinates, before any lift. */
+	cardBottom: number;
+	windowHeight: number;
+	/** The top safe-area inset — the card's top never rises past it. */
+	topInset: number;
+	/** The clearance to keep between the card and the keyboard. */
+	margin: number;
+};
+
+/**
+ * How far to lift the card so the keyboard does not cover it.
+ *
+ * The smallest lift that keeps the card's bottom `margin` above the keyboard's
+ * top — zero when the keyboard is closed or already clear — capped so the
+ * card's top never rises under the top safe-area inset, and never negative. A
+ * card too tall to fit both ways keeps its top on screen: the title and the
+ * field being typed into matter more than the footer.
+ *
+ * A worklet, because it runs inside the card's animated style on every frame
+ * of the keyboard's own animation.
+ */
+export function resolveDialogKeyboardLift({
+	keyboardHeight,
+	cardTop,
+	cardBottom,
+	windowHeight,
+	topInset,
+	margin,
+}: DialogKeyboardLiftInput): number {
+	"worklet";
+	const keyboard = Math.abs(keyboardHeight);
+	if (keyboard === 0 || cardBottom <= 0) return 0;
+
+	const needed = cardBottom + margin - (windowHeight - keyboard);
+	const room = cardTop - topInset;
+
+	return Math.max(0, Math.min(needed, room));
+}

package/src/components/dialog/index.ts

@@ -0,0 +1,30 @@
+export { Dialog, type DialogProps } from "./dialog";
+export { type DialogContextValue, useDialog, useDialogContext } from "./dialog.context";
+export {
+	DIALOG_CLOSE_HIT_SLOP,
+	DIALOG_ENTER_SCALE,
+	DIALOG_ENTER_TRANSLATE_Y,
+	DIALOG_FOOTER_VARIANTS,
+	DIALOG_KEYBOARD_MARGIN,
+	DIALOG_SCRIM_TOKEN,
+	DIALOG_SIZE_CLASS,
+	DIALOG_SIZES,
+	type DialogFooterDirection,
+	type DialogFooterVariant,
+	type DialogKeyboardLiftInput,
+	type DialogRole,
+	type DialogSize,
+	type DialogVariantProps,
+	dialogVariants,
+	resolveDialogFooterDirection,
+	resolveDialogKeyboardLift,
+	resolveDialogRole,
+} from "./dialog.variants";
+export type { DialogBodyProps } from "./dialog-body";
+export type { DialogCloseProps } from "./dialog-close";
+export type { DialogContentProps } from "./dialog-content";
+export type { DialogDescriptionProps } from "./dialog-description";
+export type { DialogFooterProps } from "./dialog-footer";
+export type { DialogHeaderProps } from "./dialog-header";
+export type { DialogTitleProps } from "./dialog-title";
+export type { DialogTriggerProps } from "./dialog-trigger";

package/src/components/drawer/AGENTS.md

@@ -0,0 +1,123 @@
+# Drawer
+
+A panel that slides in from an edge and covers the app until dismissed: a navigation menu from the
+start edge, a filter panel from the end, a notifications tray from the top. Compound root plus
+`Drawer.Trigger`, `Drawer.Content`, `Drawer.Header`, `Drawer.Title`, `Drawer.Description`,
+`Drawer.Body`, `Drawer.Footer` and `Drawer.Close`, and `useDrawer()`.
+
+`import { Drawer } from "@delacour/react-native-ui/drawer";`
+
+It is drawn with the [overlay foundation](../overlay/AGENTS.md) — `Overlay.Portal`,
+`Overlay.Scrim`, `useOverlayPresence`, `useOverlayBackHandler` — so the app has to mount
+`OverlayProvider` once at its root. Without one the drawer draws inline and warns once.
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/drawer` |
+| `drawer.tsx` | Root — the open state, the ids and the focus refs — and the `Object.assign` compound surface |
+| `drawer.context.tsx` | **Leaf.** `DrawerProvider`, `DrawerPanelProvider`, `useDrawer()`, `useDrawerContext()`, `useDrawerPart()`, `useDrawerPanel()` |
+| `drawer-trigger.tsx` | `Drawer.Trigger` — donates the open with `asChild`, keeps the trigger's ref for focus return |
+| `drawer-content.tsx` | `Drawer.Content` — presence, portal, scrim, edge and extent, insets, slide, swipe, back button, focus |
+| `drawer-header.tsx` | `Drawer.Header` — the title column and a ✕ at the trailing edge |
+| `drawer-title.tsx` | `Drawer.Title` — a `Text.Header` carrying the title `nativeID` and the focus ref |
+| `drawer-description.tsx` | `Drawer.Description` — a muted `Text.Paragraph` |
+| `drawer-body.tsx` | `Drawer.Body` — a `ScrollView`, or a plain column with `isScrollable={false}` |
+| `drawer-footer.tsx` | `Drawer.Footer` — a row under a hairline |
+| `drawer-close.tsx` | `Drawer.Close` — the ✕, or with `asChild` any control that closes |
+| `use-drawer-pan.ts` | `useDrawerPan` — the swipe-to-dismiss pan, its threshold haptic and its release |
+| `drawer.variants.ts` | The slotted `tv()`, the size table, the release constants and the pure geometry — no RN imports |
+| `drawer.variants.test.ts` | Edges both directions, extents, frame extents, offsets, drag, release, exit duration, insets, slots per edge, tokens in both themes |
+
+## Design
+
+- **A side is logical, an edge is physical, and only the edge is ever measured.** `side` is what a
+  caller writes — `start`, `end`, `top`, `bottom` — and `resolveDrawerEdge(side, I18nManager.isRTL)`
+  turns it into `left`, `right`, `top` or `bottom`. Transforms and a pan's translation are physical
+  in React Native whatever the layout direction, so the offset, the drag, the release and the insets
+  are all computed against the edge. `useDrawer()` returns both.
+- **The panel is placed in a left-to-right frame, and its content gets the app's direction back.**
+  React Native swaps `left`/`right` styles under RTL by default (`swapLeftAndRightInRTL`), and an app
+  may turn that off; either way a `left-0` class would mean something different from the
+  `translateX` beside it. The `positioner` slot is an absolute fill with `direction: "ltr"`, so the
+  panel's `edge` classes, its corners and its safe-area padding are physical, and `inner` sets the
+  app's direction again so text, rows and the header's ✕ lay out as everywhere else. That is also why
+  the spec's `edge` variant could stay keyed on the physical edge.
+- **The size is a fraction of the window with a cap.** `sm` 62% to 280, `md` 78% to 320, `lg` 88% to
+  400, `full` 94% uncapped — of the width for a start/end drawer, of the height for top/bottom. A
+  fraction keeps a strip of the app in view to tap away on; the cap keeps a tablet's drawer a drawer.
+  The extent is a fixed width or height rather than a measured one, so the first frame already knows
+  how far off-screen the panel starts. **The docked edge's inset is added on top**
+  (`resolveDrawerFrameExtent`): the size measures the content, not the band under the status bar. A
+  top `sm` drawer once spent 62 of its 280pt there and clipped its third row.
+- **Insets go on every side that meets a screen edge.** `resolveDrawerInsets` pads the docked side and
+  the two beside it, and nothing on the side facing the app, so a start drawer clears the status bar,
+  the home indicator and a landscape notch, and a top drawer does not pad for the home indicator it
+  never reaches.
+- **Docked corners square, free corners round.** `bg-popover` — a layer over the app, as `Dialog` and
+  `BottomSheet` paint — with `rounded-lg`, the card step, only on the two corners facing the app.
+- **The swipe continues, it does not spring back.** The pan waits for `DRAWER_PAN_ACTIVE_OFFSET` (10pt)
+  along the panel's axis and fails on the same travel across it, so a tap reaches a row and a vertical
+  scroll in a start/end drawer's body never moves the drawer. Toward the edge the panel follows the
+  finger; away it rubber-bands toward 40pt and never reaches it. On release, past 40% of the extent or
+  on a fling toward the edge faster than 800 pt/s dismisses — a fling away always restores. A dismiss
+  carries on from where the finger left the panel at the release speed (`resolveDrawerExitDuration`,
+  80–220 ms, linear) and closes the state only when it lands; the presence exit then runs off-screen
+  and unmounts. A restore eases back in the entrance time.
+- **The scrim thins with the drag.** Its opacity is `progress × (1 − dragFraction)`. `Overlay.Scrim`
+  takes a writable shared value, so an animated reaction writes the product into one of the drawer's
+  own rather than handing it a derived value.
+- **A haptic marks the threshold, nothing else.** `selection` each time the drag crosses 40% — the
+  moment letting go changes what happens — in both directions, from the worklet through `playHaptic`.
+  None on open.
+- **The pan's worklets live in the hook.** `useDrawerPan` builds them inside a `useMemo`, so they may
+  call `drawer.variants`' module-scope worklets; those are flat — a module-scope worklet never calls
+  another function — which is why each restates the edge's sign rather than sharing a helper.
+  Per-gesture memory (`isDragging`, `isPastThreshold`) is shared values. A touch that never activated
+  returns early from `onFinalize`, so a tap during a dismiss cannot restart a restore under it.
+- **Reduce motion fades, and the swipe still works.** Under `useReducedMotion()` the open and close do
+  not slide — the panel fades in place on `progress` — but a drag still moves it: that is direct
+  manipulation, not animation. `isMotionCalm` does not still it, per the foundation.
+- **`isDismissible={false}` turns off every way out the drawer did not offer** — the scrim (which still
+  takes the touch), the back button, the escape gesture and the swipe. `Drawer.Close` still closes it.
+  `isSwipeDismissible={false}` turns off the swipe alone.
+- **Every path to closed is one `setOpen(false)`**, and the root drops a set that does not change the
+  value, so a scrim tap during a swipe's exit does not report `onOpenChange(false)` twice.
+- **The header writes its own ✕, in the flow.** A row: the title column takes the slack and the ✕
+  sits at the trailing edge, so a long title wraps before it and RTL needs no rule. `isCloseHidden`
+  drops it. There is no `title` or `description` slot — both are text presets with no layout of their
+  own, and `tv` emits `undefined` for an empty slot; the parts merge `className` with `cn()`.
+- **The body scrolls by default and takes the slack, and the footer is `mt-auto`**, so the footer sits
+  at the panel's end however short the content — even with no body, which the simulator caught: a
+  header-and-footer bottom drawer left its footer floating under the header. A top or bottom drawer's pan shares the vertical axis with a scroll — keep that
+  content short, or use a `BottomSheet`.
+- **It draws in the `modal` band**, over the navigator's header and over an open bottom sheet.
+- **Triggers and closes donate the press** with `asChild`, for `BottomSheet.Trigger`'s reason.
+- **Accessibility.** The panel is `accessibilityViewIsModal`, `role="dialog"`, labelled by the title's
+  `nativeID`; focus moves to the title once the entrance finishes and back to the trigger once the
+  exit does. `onAccessibilityEscape` and the back button close it when dismissible. The scrim is not
+  accessible. The ✕ is labelled `"Close"`.
+- **No blur backdrop.** Frosted scrims need `expo-blur`, not a peer; a follow-up for every overlay.
+
+## Preview capture (not yet shot)
+
+No demo is marked `capture` until a capture tool is available. When one is, these are the settings,
+and the flows are in `.argent/flows/previews/drawer/`:
+
+| Demo | Capture |
+| --- | --- |
+| `navigation` | `{ flow: "drawer/navigation", frame: "device", hero: true }` |
+| `filters` | `{ flow: "drawer/filters", frame: "device" }` |
+| `sizes` | `{ flow: "drawer/sizes", frame: "device" }` |
+| `notifications` | `{ flow: "drawer/notifications", frame: "device" }` |
+
+## Testing
+
+`bun test` reaches the edge resolution in both directions, the extents on a small and a wide window, the frame extent with the docked inset,
+the offset, the drag and its rubber band, the drag fraction, the release (threshold, fling toward,
+fling away), the exit duration, the insets per edge and the slots per edge with their tokens in both
+themes. All four sides from every dismissal path, the swipe's continue-and-restore, the scrolling
+body, the z-order over a sheet, VoiceOver and reduce motion are verified on a simulator through
+`/drawer` in the playground. RTL needs an app restarted with `I18nManager.forceRTL(true)`; the `rtl`
+demo shows the resolution the drawer will make.