@delacour/react-native-ui 0.1.0-alpha.20260925053522

package/src/components/bottom-sheet/bottom-sheet.tsx

@@ -0,0 +1,125 @@
+import { type ReactElement, type ReactNode, useCallback, useMemo, useRef } from "react";
+import { useControllableState } from "../../hooks/use-controllable-state";
+import { type BottomSheetContextValue, type BottomSheetHandle, BottomSheetProvider } from "./bottom-sheet.context";
+import { BottomSheetClose } from "./bottom-sheet-close";
+import { BottomSheetContainer } from "./bottom-sheet-container";
+import { BottomSheetContent } from "./bottom-sheet-content";
+import { BottomSheetDescription } from "./bottom-sheet-description";
+import { BottomSheetFooter } from "./bottom-sheet-footer";
+import { BottomSheetOverlay } from "./bottom-sheet-overlay";
+import { BottomSheetPortal } from "./bottom-sheet-portal";
+import { BottomSheetScrollView } from "./bottom-sheet-scroll-view";
+import { BottomSheetTitle } from "./bottom-sheet-title";
+import { BottomSheetTrigger } from "./bottom-sheet-trigger";
+
+export type BottomSheetProps = {
+	children?: ReactNode;
+	/** Controlled open state. Leave it off and the sheet holds its own. */
+	isOpen?: boolean;
+	/** Initial open state while uncontrolled. */
+	defaultOpen?: boolean;
+	/**
+	 * Called whenever the sheet opens or closes — by a trigger, a swipe down, a
+	 * press on the backdrop, `BottomSheet.Close`, or a controlled `isOpen`.
+	 *
+	 * One callback for every path, deliberately. gorhom's own `onClose` fires for
+	 * the gesture alone, which is the shape that makes a caller wire three
+	 * handlers and still miss one.
+	 */
+	onOpenChange?: (isOpen: boolean) => void;
+};
+
+function BottomSheetRoot({ children, defaultOpen = false, isOpen, onOpenChange }: BottomSheetProps): ReactElement {
+	const sheetRef = useRef<BottomSheetHandle | null>(null);
+	const [isSheetOpen, setOpen] = useControllableState<boolean>({
+		defaultValue: defaultOpen,
+		onChange: onOpenChange,
+		value: isOpen,
+	});
+
+	const open = useCallback(() => setOpen(true), [setOpen]);
+	const close = useCallback(() => setOpen(false), [setOpen]);
+
+	const context = useMemo<BottomSheetContextValue>(
+		() => ({ close, isOpen: isSheetOpen, open, setOpen, sheetRef }),
+		[close, isSheetOpen, open, setOpen]
+	);
+
+	return <BottomSheetProvider value={context}>{children}</BottomSheetProvider>;
+}
+
+/**
+ * A panel that slides up from the bottom of the screen, over everything.
+ *
+ * The library's first overlay, built on `@gorhom/bottom-sheet`'s modal. It
+ * renders no view of its own — it owns the open state and hands it to the parts
+ * through context, so a trigger anywhere inside can open a sheet declared
+ * anywhere else in the same tree.
+ *
+ * **The app must mount `DelacourProvider` at its root.** The sheet hosts itself in
+ * the `BottomSheetModalProvider` that provider's innermost layer supplies, and it
+ * needs the gesture root above it for the pan.
+ *
+ * **Two parts are not drawn where they are written.** `BottomSheet.Overlay` and a
+ * `BottomSheet.Footer sticky` are lifted out of the tree and handed to gorhom as
+ * render props — see `BottomSheet.Portal` and `BottomSheet.Container` for why the
+ * anatomy is worth that. Everything else renders in place.
+ *
+ * Controlled or not, from one hook: pass `isOpen` and `onOpenChange` to own the
+ * state, or nothing at all and let the sheet hold it. Which mode is in play is
+ * locked in on first render.
+ *
+ * @example
+ * <BottomSheet>
+ *   <BottomSheet.Trigger asChild>
+ *     <Button variant="secondary">Open</Button>
+ *   </BottomSheet.Trigger>
+ *   <BottomSheet.Portal>
+ *     <BottomSheet.Overlay />
+ *     <BottomSheet.Container>
+ *       <BottomSheet.Content>
+ *         <BottomSheet.Close />
+ *         <BottomSheet.Title>Keep yourself safe</BottomSheet.Title>
+ *         <BottomSheet.Description>Update to the latest version.</BottomSheet.Description>
+ *       </BottomSheet.Content>
+ *       <BottomSheet.Footer sticky>
+ *         <Button onPress={update}>Update now</Button>
+ *       </BottomSheet.Footer>
+ *     </BottomSheet.Container>
+ *   </BottomSheet.Portal>
+ * </BottomSheet>
+ *
+ * @example
+ * // Controlled, and opened from somewhere other than a trigger.
+ * <BottomSheet isOpen={isOpen} onOpenChange={setOpen}>
+ *   <BottomSheet.Portal>
+ *     <BottomSheet.Overlay />
+ *     <BottomSheet.Container>
+ *       <BottomSheet.Content>{…}</BottomSheet.Content>
+ *     </BottomSheet.Container>
+ *   </BottomSheet.Portal>
+ * </BottomSheet>
+ */
+export const BottomSheet = Object.assign(BottomSheetRoot, {
+	/** The control that opens the sheet. `asChild` to make a `Button` the trigger. */
+	Trigger: BottomSheetTrigger,
+	/** Everything drawn above the app. Lifts the overlay out to the container. */
+	Portal: BottomSheetPortal,
+	/** The scrim. Written beside the container, drawn as its backdrop. */
+	Overlay: BottomSheetOverlay,
+	/** The sheet itself. Every gorhom prop passes through it. */
+	Container: BottomSheetContainer,
+	/** The sheet's body, sized to itself under `enableDynamicSizing`. */
+	Content: BottomSheetContent,
+	/** A scrolling body. Needs `enableDynamicSizing={false}` and snap points. */
+	ScrollView: BottomSheetScrollView,
+	/** The dismiss control, positioned out of the content's flow. */
+	Close: BottomSheetClose,
+	/** The sheet's heading — a `Text.Header` with the close control's clearance. */
+	Title: BottomSheetTitle,
+	/** Supporting copy under the title — a muted `Text.Paragraph`. */
+	Description: BottomSheetDescription,
+	/** Controls at the bottom. `sticky` pins them above the keyboard. */
+	Footer: BottomSheetFooter,
+	displayName: "DelacourUI.BottomSheet",
+});

package/src/components/bottom-sheet/bottom-sheet.variants.test.ts

@@ -0,0 +1,293 @@
+import { describe, expect, test } from "bun:test";
+import { declaredTokens, tokenValue } from "../../styles/theme-tokens.test";
+import {
+	BOTTOM_SHEET_BACKDROP_INDICES,
+	BOTTOM_SHEET_CLOSE_HIT_SLOP,
+	BOTTOM_SHEET_FOOTER_GAP,
+	BOTTOM_SHEET_FOOTER_PADDING,
+	BOTTOM_SHEET_KEYBOARD_DEFAULTS,
+	BOTTOM_SHEET_OVERLAY_OPACITY,
+	BOTTOM_SHEET_OVERLAY_TOKEN,
+	bottomSheetVariants,
+	resolveFooterPlacement,
+	resolveSheetBottomInset,
+	resolveSheetScrollEndPadding,
+} from "./bottom-sheet.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;
+}
+
+const SLOTS = bottomSheetVariants();
+
+/**
+ * The slots this component declares, pinned rather than derived.
+ *
+ * `tv` adds a `base` slot of its own that emits nothing, so iterating the
+ * returned object sweeps one entry that is not ours. Listing them also means a
+ * new slot has to be added here before the checks below can miss it.
+ */
+const SLOT_NAMES = [
+	"overlay",
+	"background",
+	"handle",
+	"handleIndicator",
+	"content",
+	"scrollContent",
+	"footer",
+	"stickyFooter",
+	"close",
+	"title",
+] as const;
+
+describe("the theme.css reader", () => {
+	// The token assertions below are only worth anything if the parse found something.
+	test("finds both variants", () => {
+		expect(LIGHT.size).toBeGreaterThan(0);
+		expect(DARK.size).toBeGreaterThan(0);
+	});
+});
+
+describe("the overlay token", () => {
+	test("is declared in both variants", () => {
+		expect(LIGHT.has(BOTTOM_SHEET_OVERLAY_TOKEN)).toBe(true);
+		expect(DARK.has(BOTTOM_SHEET_OVERLAY_TOKEN)).toBe(true);
+	});
+
+	test("is the token the overlay slot actually paints", () => {
+		expect(SLOTS.overlay()).toContain(`bg-${BOTTOM_SHEET_OVERLAY_TOKEN}`);
+	});
+
+	test("carries its own alpha in both variants, which is what makes the opacity 1", () => {
+		for (const variant of ["light", "dark"] as const) {
+			const value = tokenValue(variant, BOTTOM_SHEET_OVERLAY_TOKEN);
+			if (value === undefined) throw new Error(`theme.css declares no --overlay under ${variant}`);
+
+			const alpha = Number(value.match(/\/\s*([\d.]+)%\s*\)/)?.[1]) / 100;
+			expect(alpha).toBeGreaterThan(0);
+			expect(alpha).toBeLessThan(1);
+		}
+
+		// Leaving gorhom's 0.5 in place would multiply against that alpha and land
+		// the scrim at roughly a fifth of what the theme asked for.
+		expect(BOTTOM_SHEET_OVERLAY_OPACITY).toBe(1);
+	});
+
+	test("the two variants differ — a black scrim over a near-black theme is invisible", () => {
+		const light = tokenValue("light", BOTTOM_SHEET_OVERLAY_TOKEN);
+		const dark = tokenValue("dark", BOTTOM_SHEET_OVERLAY_TOKEN);
+		expect(light).not.toBe(dark);
+	});
+});
+
+describe("every token the slots name", () => {
+	test("is declared in both variants of theme.css", () => {
+		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", () => {
+		// Every assertion above passes vacuously if the extractor matches nothing.
+		expect(colorTokens(SLOTS.stickyFooter())).toEqual(expect.arrayContaining(["popover", "border"]));
+		expect(colorTokens(SLOTS.handleIndicator())).toContain("muted-foreground");
+	});
+});
+
+describe("the backdrop indices", () => {
+	test("show the scrim from the first snap point and hide it only when closed", () => {
+		// gorhom's own defaults (1 / 0) suit a persistent sheet resting collapsed
+		// on screen. A modal sheet has no resting state.
+		expect(BOTTOM_SHEET_BACKDROP_INDICES.appearsOnIndex).toBe(0);
+		expect(BOTTOM_SHEET_BACKDROP_INDICES.disappearsOnIndex).toBe(-1);
+		expect(BOTTOM_SHEET_BACKDROP_INDICES.disappearsOnIndex).toBeLessThan(BOTTOM_SHEET_BACKDROP_INDICES.appearsOnIndex);
+	});
+});
+
+describe("the keyboard defaults", () => {
+	test("follow the keyboard, restore on blur, and resize the Android window", () => {
+		expect(BOTTOM_SHEET_KEYBOARD_DEFAULTS).toEqual({
+			keyboardBehavior: "interactive",
+			keyboardBlurBehavior: "restore",
+			android_keyboardInputMode: "adjustResize",
+		});
+	});
+
+	test("does not leave Android on gorhom's adjustPan", () => {
+		// `adjustPan` slides the whole window up instead of resizing it, which puts
+		// a sheet's footer off-screen. `resize` is what Expo configures and what
+		// `KeyboardProvider` requires, so this is the value that matches reality.
+		expect(BOTTOM_SHEET_KEYBOARD_DEFAULTS.android_keyboardInputMode).not.toBe("adjustPan");
+	});
+});
+
+describe("resolveFooterPlacement", () => {
+	const footer = (isSticky: boolean) => ({ isFooter: true, isSticky });
+	const other = { isFooter: false, isSticky: false };
+
+	test("reports none for children holding no footer", () => {
+		expect(resolveFooterPlacement([])).toBe("none");
+		expect(resolveFooterPlacement([other, other])).toBe("none");
+	});
+
+	test("reports inline for a footer that did not ask to be pinned", () => {
+		expect(resolveFooterPlacement([other, footer(false)])).toBe("inline");
+	});
+
+	test("reports sticky for one that did, wherever it sits", () => {
+		expect(resolveFooterPlacement([footer(true), other])).toBe("sticky");
+		expect(resolveFooterPlacement([other, footer(true)])).toBe("sticky");
+	});
+
+	test("lets a single sticky footer win over an inline one", () => {
+		// Two footers is not a state worth expressing, and the pinned one is the
+		// one a caller meant.
+		expect(resolveFooterPlacement([footer(false), footer(true)])).toBe("sticky");
+		expect(resolveFooterPlacement([footer(true), footer(false)])).toBe("sticky");
+	});
+
+	test("never reads a sticky flag off a child that is not a footer", () => {
+		expect(resolveFooterPlacement([{ isFooter: false, isSticky: true }])).toBe("none");
+	});
+});
+
+describe("resolveSheetBottomInset", () => {
+	test("gives the safe-area band to the content when nothing is pinned below it", () => {
+		expect(resolveSheetBottomInset({ bottom: 34, hasStickyFooter: false })).toBe(34);
+	});
+
+	test("withholds it once a pinned footer's own box is carrying it", () => {
+		// gorhom adds the footer's whole measured height — band included — to the
+		// content's reserve, so asking for it here too counts it twice.
+		expect(resolveSheetBottomInset({ bottom: 34, hasStickyFooter: true })).toBe(0);
+	});
+
+	test("is a no-op on a device with no bottom inset", () => {
+		expect(resolveSheetBottomInset({ bottom: 0, hasStickyFooter: false })).toBe(0);
+	});
+});
+
+describe("resolveSheetScrollEndPadding", () => {
+	test("gives the safe-area band to the content when nothing is pinned below it", () => {
+		expect(resolveSheetScrollEndPadding({ bottom: 34, hasStickyFooter: false })).toBe(34);
+	});
+
+	test("holds the content off a pinned footer by the gap alone", () => {
+		// The scroll view's frame already stops at the footer's top edge, so the
+		// footer's height — band included — is not the content's to reserve.
+		expect(resolveSheetScrollEndPadding({ bottom: 34, hasStickyFooter: true })).toBe(BOTTOM_SHEET_FOOTER_GAP);
+	});
+
+	test("keeps the gap on a device with no bottom inset", () => {
+		expect(resolveSheetScrollEndPadding({ bottom: 0, hasStickyFooter: true })).toBe(BOTTOM_SHEET_FOOTER_GAP);
+	});
+});
+
+describe("bottomSheetVariants slots", () => {
+	test("the title slot carries layout only, never type", () => {
+		// The type comes from the `Text.Header` the part renders. A `text-lg` here
+		// would be a second definition of that preset which can drift from it.
+		expect(SLOTS.title()).not.toMatch(/\btext-\w/);
+		expect(SLOTS.title()).not.toMatch(/\bfont-\w/);
+	});
+
+	test("the title reserves room for the close control on every sheet", () => {
+		// Reserved unconditionally, the way `Badge` reserves its border on every
+		// variant: conditional clearance reflows the title the moment one is added.
+		expect(SLOTS.title()).toMatch(/\bpr-[\d.]+\b/);
+	});
+
+	test("every slot emits something, so none of them is untestable", () => {
+		// `tv` returns undefined for an empty class string, and a slot that says
+		// nothing is a slot no assertion here can reach.
+		for (const name of SLOT_NAMES) {
+			expect({ emits: typeof SLOTS[name](), name }).toEqual({ emits: "string", name });
+		}
+	});
+
+	test("declares no slot the pinned list has not seen", () => {
+		// `base` is tv's own, and is the one entry that is not ours.
+		const declared = Object.keys(SLOTS).filter((name) => name !== "base");
+		expect(declared.sort()).toEqual([...SLOT_NAMES].sort());
+	});
+
+	test("the sheet's surface rounds its top corners only", () => {
+		const background = SLOTS.background();
+		expect(background).toMatch(/\brounded-t-/);
+		expect(background).not.toMatch(/\brounded-b-/);
+		// A bare `rounded-*` would round the bottom edge too, and that edge runs off
+		// the screen — the radius shows as two notches of the app behind it.
+		expect(background).not.toMatch(/\brounded-(?:none|xs|sm|md|lg|xl|2xl|3xl|full)\b/);
+	});
+
+	test("a pinned footer brings a surface and a line where an inline one does not", () => {
+		// It draws OVER the content, so without them the content scrolls straight
+		// through it. An inline footer is in the flow and needs neither.
+		expect(SLOTS.stickyFooter()).toMatch(/\bbg-\w/);
+		expect(SLOTS.stickyFooter()).toMatch(/\bborder-t\b/);
+		expect(SLOTS.footer()).not.toMatch(/\bbg-\w/);
+		expect(SLOTS.footer()).not.toMatch(/\bborder-t\b/);
+	});
+
+	test("a pinned footer writes its vertical padding as a style, never a class", () => {
+		// The bottom padding is animated — the safe-area band collapses into it as
+		// the keyboard arrives — and a class cannot carry an animated value. The
+		// top is written the same way so the two cannot drift.
+		expect(SLOTS.stickyFooter()).not.toMatch(/\bp[tby]?-[\d.]+\b/);
+		expect(BOTTOM_SHEET_FOOTER_PADDING).toBeGreaterThan(0);
+	});
+
+	test("the content is held off a pinned footer by a real gap", () => {
+		// Without it the last row sits flush against the footer's hairline, which
+		// reads as content clipped rather than content ended.
+		expect(BOTTOM_SHEET_FOOTER_GAP).toBeGreaterThan(0);
+	});
+
+	test("both footers share their gutter and gap, so pinning one moves nothing sideways", () => {
+		const gutter = /\bpx-screen-gutter\b/;
+		expect(SLOTS.footer()).toMatch(gutter);
+		expect(SLOTS.stickyFooter()).toMatch(gutter);
+		expect(SLOTS.footer().match(/\bgap-[\d.]+\b/)?.[0]).toBe(SLOTS.stickyFooter().match(/\bgap-[\d.]+\b/)?.[0]);
+	});
+
+	test("scrolling content sits on the same gutter as static content", () => {
+		// A sheet should not shift sideways because its body became scrollable.
+		expect(SLOTS.content()).toMatch(/\bpx-screen-gutter\b/);
+		expect(SLOTS.scrollContent()).toMatch(/\bpx-screen-gutter\b/);
+	});
+
+	test("the overlay sets no opacity of its own", () => {
+		// gorhom animates the scrim's opacity off the sheet's position; a class here
+		// would be a second writer of the same style property.
+		expect(SLOTS.overlay()).not.toMatch(/\bopacity-\d/);
+	});
+
+	test("the close control is positioned out of the content flow", () => {
+		expect(SLOTS.close()).toContain("absolute");
+		expect(BOTTOM_SHEET_CLOSE_HIT_SLOP).toBeGreaterThan(0);
+	});
+
+	test("the grabber is a pill with both dimensions set", () => {
+		const indicator = SLOTS.handleIndicator();
+		expect(indicator).toMatch(/\bh-[\d.]+\b/);
+		expect(indicator).toMatch(/\bw-[\d.]+\b/);
+		expect(indicator).toContain("rounded-full");
+	});
+});

package/src/components/bottom-sheet/bottom-sheet.variants.ts

@@ -0,0 +1,220 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+
+/**
+ * The scrim token, named here so a test can pin it against `theme.css`.
+ *
+ * A token rather than a `bg-black/50` written at a call site: the two theme
+ * variants carry different alphas, because a pure-black scrim over a near-black
+ * dark theme is nearly invisible.
+ */
+export const BOTTOM_SHEET_OVERLAY_TOKEN = "overlay";
+
+/**
+ * The backdrop's opacity at full appearance.
+ *
+ * **1, not gorhom's 0.5.** The alpha lives in `--overlay`, so leaving the
+ * library default in place would multiply the two and land the scrim at roughly
+ * a fifth of what the theme asked for. One source for the alpha, and it is the
+ * token — which is also what lets the two theme variants differ.
+ */
+export const BOTTOM_SHEET_OVERLAY_OPACITY = 1;
+
+/**
+ * The snap indices the scrim appears and disappears on.
+ *
+ * gorhom defaults to `{ appearsOnIndex: 1, disappearsOnIndex: 0 }`, which suits
+ * a persistent sheet that rests collapsed on the screen and only dims the app
+ * once it is expanded. A modal sheet has no resting state: it is either
+ * presented or gone, so the scrim belongs from the FIRST snap point (`0`) and
+ * is only absent when the sheet is closed (`-1`).
+ */
+export const BOTTOM_SHEET_BACKDROP_INDICES = { appearsOnIndex: 0, disappearsOnIndex: -1 } as const;
+
+/**
+ * Keyboard behaviour every `BottomSheet.Container` starts from.
+ *
+ * A const rather than three defaults spelled inline, so `bun test` pins them and
+ * a retune is one edit rather than three.
+ *
+ * - `interactive` — the sheet grows to keep its content above the keyboard,
+ *   following it frame by frame rather than snapping once it has settled.
+ * - `restore` — blurring returns the sheet to the snap point it was on. Without
+ *   it a sheet that grew for the keyboard stays grown over empty screen.
+ * - `adjustResize` — gorhom's own default is `adjustPan`, which leaves the
+ *   Android window height alone and slides the whole view up, so a sheet's
+ *   footer lands off-screen. `resize` is already what Expo configures and what
+ *   `KeyboardProvider` requires, so this is the value that matches the window.
+ */
+export const BOTTOM_SHEET_KEYBOARD_DEFAULTS = {
+	keyboardBehavior: "interactive",
+	keyboardBlurBehavior: "restore",
+	android_keyboardInputMode: "adjustResize",
+} as const;
+
+/**
+ * Slop around `BottomSheet.Close`.
+ *
+ * The glyph is a bare icon in a corner with no padded capsule to absorb the
+ * difference against the 44pt minimum — the case `Checkbox` mints slop for and
+ * `Badge.CloseButton` does not need.
+ */
+export const BOTTOM_SHEET_CLOSE_HIT_SLOP = 8;
+
+/**
+ * The padding a pinned footer keeps whatever the keyboard is doing.
+ *
+ * A number rather than a `p-4`, and for `SCREEN_FOOTER_PADDING`'s reason: the
+ * footer's bottom padding is an animated value — the safe-area band collapses
+ * into it as the keyboard arrives — and a class cannot carry one. Its top
+ * padding is written the same way so the two cannot drift.
+ */
+export const BOTTOM_SHEET_FOOTER_PADDING = 16;
+
+/**
+ * The gap between the last of the content and a pinned footer.
+ *
+ * Also a number, because the reserve it belongs to is computed at runtime from
+ * the footer's measured height. Without it the last row of a list sits flush
+ * against the footer's hairline, which reads as content clipped rather than
+ * content ended.
+ */
+export const BOTTOM_SHEET_FOOTER_GAP = 16;
+
+export const bottomSheetVariants = tv({
+	slots: {
+		/**
+		 * The scrim. Carries the colour and nothing else — the fade is an animated
+		 * opacity gorhom drives off the sheet's own position.
+		 */
+		overlay: "bg-overlay",
+		/**
+		 * The sheet's surface. `popover` rather than `card`: a sheet is a layer
+		 * over the app, which is what that token already means, and it is the one
+		 * surface token nothing else in the package had claimed.
+		 *
+		 * Only the top corners round. The bottom edge runs off the screen, and a
+		 * radius there shows as two notches of the app behind it.
+		 */
+		background: "rounded-t-2xl bg-popover",
+		handle: "items-center justify-center pt-3 pb-1",
+		handleIndicator: "h-1 w-9 rounded-full bg-muted-foreground/40",
+		content: "gap-4 px-screen-gutter pt-2",
+		/** A scrollable body's content container. Same treatment as `content`. */
+		scrollContent: "gap-4 px-screen-gutter pt-2",
+		footer: "gap-3 px-screen-gutter pt-4",
+		/**
+		 * A pinned footer draws OVER the content, so unlike the inline one it has
+		 * to bring a surface and a line of its own — otherwise the content scrolls
+		 * straight through it and its buttons are legible only where they happen
+		 * to overlap blank space. The same reason `Screen.Footer`'s backing lives
+		 * inside its sticky view.
+		 *
+		 * It carries no vertical padding: that is an animated style, because the
+		 * safe-area band inside it collapses as the keyboard arrives. See
+		 * {@link BOTTOM_SHEET_FOOTER_PADDING}.
+		 */
+		stickyFooter: "gap-3 border-border border-t bg-popover px-screen-gutter",
+		close: "absolute top-4 right-4 z-10",
+		/**
+		 * Clearance for `BottomSheet.Close`, and nothing else.
+		 *
+		 * The close control is absolutely positioned, so it is out of the flow and
+		 * a long title runs straight under it. The gutter is reserved on every
+		 * sheet rather than only where a close is written, for the reason `Badge`
+		 * reserves its border on every variant: declaring it conditionally makes
+		 * the title reflow the moment someone adds one.
+		 *
+		 * No type. That comes from the `Text` preset the part renders, the way
+		 * `Field.Label` *is* a `Text.Label` — a `text-lg font-semibold` here would
+		 * be a second definition of `Text.Header` that can drift from it.
+		 */
+		title: "pr-8",
+	},
+});
+
+/**
+ * There is no `description` or `scrollView` slot.
+ *
+ * Neither has any layout of its own — a description is a `Text.Paragraph` in a
+ * gap column and a scroll view fills whatever it is given — and `tv` emits
+ * `undefined` for a slot whose class string is empty, so a slot that says
+ * nothing is a slot no test can assert against. Those two parts merge the
+ * caller's `className` with `cn()` instead.
+ */
+export type BottomSheetVariantProps = VariantProps<typeof bottomSheetVariants>;
+
+/** Where a `BottomSheet.Footer` among a container's children has to be rendered. */
+export type BottomSheetFooterPlacement = "sticky" | "inline" | "none";
+
+/** One child of a `BottomSheet.Container`, reduced to what the placement turns on. */
+export type BottomSheetFooterFlag = {
+	isFooter: boolean;
+	isSticky: boolean;
+};
+
+/**
+ * Whether a container's children hold a footer, and where it has to go.
+ *
+ * gorhom takes a footer as a `footerComponent` render prop rather than as a
+ * child, so a sticky one has to be lifted out of the tree it was written in and
+ * handed over; an inline one simply stays put. This is the decision, kept pure
+ * so `bun test` reaches the whole matrix — the walk over `Children.toArray` that
+ * produces the flags lives with its caller, the way `withIndicator` does in
+ * `radio.tsx`.
+ *
+ * A single sticky footer anywhere in the children wins, because two footers is
+ * not a state worth expressing and the pinned one is the one a caller meant.
+ */
+export function resolveFooterPlacement(flags: readonly BottomSheetFooterFlag[]): BottomSheetFooterPlacement {
+	let hasFooter = false;
+
+	for (const flag of flags) {
+		if (!flag.isFooter) continue;
+		if (flag.isSticky) return "sticky";
+		hasFooter = true;
+	}
+
+	return hasFooter ? "inline" : "none";
+}
+
+/**
+ * The safe-area band `BottomSheet.Content` and `BottomSheet.ScrollView` reserve.
+ *
+ * Exactly one thing in the sheet pays for the home indicator. A pinned footer is
+ * the bottom-most thing there is, and its own box carries the band so its surface
+ * reaches the bottom of the screen — gorhom then adds that whole measured height
+ * to the content's reserve, so the content asking for the band as well would
+ * count it twice and leave a gap the height of the indicator above the footer.
+ * With no pinned footer the content IS the bottom-most thing and takes it.
+ */
+export function resolveSheetBottomInset({
+	hasStickyFooter,
+	bottom,
+}: {
+	hasStickyFooter: boolean;
+	bottom: number;
+}): number {
+	return hasStickyFooter ? 0 : bottom;
+}
+
+/**
+ * The padding at the end of `BottomSheet.ScrollView`'s content.
+ *
+ * A scroll view does not reserve a pinned footer the way `BottomSheet.Content`
+ * does — its FRAME stops at the footer's top edge instead, so the scroll
+ * indicator and the overscroll bounce end there too rather than running on
+ * underneath it. That leaves the content only the gap to hold it off the
+ * footer's hairline. With no pinned footer the content is the bottom-most thing
+ * in the sheet and takes the safe-area band, as {@link resolveSheetBottomInset}
+ * has it.
+ */
+export function resolveSheetScrollEndPadding({
+	hasStickyFooter,
+	bottom,
+}: {
+	hasStickyFooter: boolean;
+	bottom: number;
+}): number {
+	return hasStickyFooter ? BOTTOM_SHEET_FOOTER_GAP : resolveSheetBottomInset({ bottom, hasStickyFooter });
+}

package/src/components/bottom-sheet/index.ts

@@ -0,0 +1,40 @@
+export { BottomSheet, type BottomSheetProps } from "./bottom-sheet";
+export {
+	type BottomSheetContainerContextValue,
+	BottomSheetContainerProvider,
+	type BottomSheetContextValue,
+	type BottomSheetHandle,
+	type BottomSheetPortalContextValue,
+	BottomSheetPortalProvider,
+	BottomSheetProvider,
+	useBottomSheet,
+	useBottomSheetContainerContext,
+	useBottomSheetContext,
+	useBottomSheetPortalContext,
+} from "./bottom-sheet.context";
+export {
+	BOTTOM_SHEET_BACKDROP_INDICES,
+	BOTTOM_SHEET_CLOSE_HIT_SLOP,
+	BOTTOM_SHEET_FOOTER_GAP,
+	BOTTOM_SHEET_FOOTER_PADDING,
+	BOTTOM_SHEET_KEYBOARD_DEFAULTS,
+	BOTTOM_SHEET_OVERLAY_OPACITY,
+	BOTTOM_SHEET_OVERLAY_TOKEN,
+	type BottomSheetFooterFlag,
+	type BottomSheetFooterPlacement,
+	type BottomSheetVariantProps,
+	bottomSheetVariants,
+	resolveFooterPlacement,
+	resolveSheetBottomInset,
+} from "./bottom-sheet.variants";
+export type { BottomSheetCloseProps } from "./bottom-sheet-close";
+export type { BottomSheetContainerProps } from "./bottom-sheet-container";
+export type { BottomSheetContentProps } from "./bottom-sheet-content";
+export type { BottomSheetDescriptionProps } from "./bottom-sheet-description";
+export type { BottomSheetFooterProps } from "./bottom-sheet-footer";
+export type { BottomSheetOverlayProps } from "./bottom-sheet-overlay";
+export type { BottomSheetPortalProps } from "./bottom-sheet-portal";
+export type { BottomSheetScrollViewProps } from "./bottom-sheet-scroll-view";
+export type { BottomSheetTitleProps } from "./bottom-sheet-title";
+export type { BottomSheetTriggerProps } from "./bottom-sheet-trigger";
+export { type BottomSheetInputHandlers, useBottomSheetInput } from "./use-bottom-sheet-input";