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

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

@@ -1,73 +1,106 @@
-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 {
+	BottomSheetHost,
+	BottomSheet as Headless,
+	type BottomSheetProps as HeadlessBottomSheetProps,
+} from "@delacour/react-native-bottom-sheet";
+import type { ReactElement } from "react";
+import { Presets } from "react-native-pulsar";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { useKeyboardAnimationGuard } from "../../hooks/use-keyboard-state-sync";
+import { BottomSheetBackground } from "./bottom-sheet-background";
 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 { BottomSheetFlatList } from "./bottom-sheet-flat-list";
 import { BottomSheetFooter } from "./bottom-sheet-footer";
+import { BottomSheetHandle } from "./bottom-sheet-handle";
+import { BottomSheetLegendList } from "./bottom-sheet-legend-list";
 import { BottomSheetOverlay } from "./bottom-sheet-overlay";
-import { BottomSheetPortal } from "./bottom-sheet-portal";
+import { BottomSheetProvider } from "./bottom-sheet-provider";
 import { BottomSheetScrollView } from "./bottom-sheet-scroll-view";
+import { BottomSheetSectionList } from "./bottom-sheet-section-list";
+import { BottomSheetStep, BottomSheetSteps } from "./bottom-sheet-steps";
+import { BottomSheetTextInput } from "./bottom-sheet-text-input";
 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;
-};
+/**
+ * Every prop the engine's root takes, with two defaults this skin fills in:
+ * `bottomInset` is the device's safe-area bottom unless a caller says
+ * otherwise, and the two haptics are the library's own.
+ */
+export type BottomSheetProps = HeadlessBottomSheetProps;
 
-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,
-	});
+/**
+ * The haptics the sheet plays, as module-scope worklets.
+ *
+ * Both run on the UI thread from inside the engine's pan, so they are
+ * `Presets.System.*` — themselves worklets — and nothing else: a JS function
+ * here would be `undefined is not a function` at the moment a finger crosses a
+ * snap point. `selection` on a snap point because that is what a picker's tick feels
+ * like, and `impactLight` on a close because letting go of a sheet is a
+ * heavier event than passing a stop, but not by much.
+ */
+const snapPointHaptic = Presets.System.selection;
+const closeHaptic = Presets.System.impactLight;
 
-	const open = useCallback(() => setOpen(true), [setOpen]);
-	const close = useCallback(() => setOpen(false), [setOpen]);
+/**
+ * The engine's root with this library's defaults on it. It renders no view of
+ * its own.
+ *
+ * Three things happen here and nowhere else in the skin:
+ *
+ * - **`bottomInset` defaults to the safe-area bottom**, read from
+ *   `useSafeAreaInsets()`. The engine reserves that band under the body or the
+ *   sticky footer and gives it back to the keyboard as it arrives; a caller
+ *   never pads for the home indicator by hand.
+ * - **The haptics are on by default.** Pass `onSnapPointHaptic={undefined}` to
+ *   turn one off, or a worklet of your own to change it.
+ * - **The stale-keyboard guard runs on mount.** A sheet mounted while
+ *   `KeyboardProvider`'s shared values are pinned open by a keyboard that
+ *   vanished without a `will` event would lift for a keyboard that is not
+ *   there; `Screen.Footer` runs the same repair for the same reason.
+ *
+ * `topInset` is left at the engine's zero, so a `%` snap point is a fraction of the
+ * whole window — the same fraction it was before this rewrite.
+ */
+function BottomSheetRoot({
+	bottomInset,
+	onSnapPointHaptic = snapPointHaptic,
+	onCloseHaptic = closeHaptic,
+	...props
+}: BottomSheetProps): ReactElement {
+	const insets = useSafeAreaInsets();
+	useKeyboardAnimationGuard();
 
-	const context = useMemo<BottomSheetContextValue>(
-		() => ({ close, isOpen: isSheetOpen, open, setOpen, sheetRef }),
-		[close, isSheetOpen, open, setOpen]
+	return (
+		<Headless
+			bottomInset={bottomInset ?? insets.bottom}
+			onCloseHaptic={onCloseHaptic}
+			onSnapPointHaptic={onSnapPointHaptic}
+			{...props}
+		/>
 	);
-
-	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.
+ * A thin Uniwind skin over `@delacour/react-native-bottom-sheet`: every part
+ * here is the engine's part with this library's classes, `Text` presets and
+ * `Pressable` on it. The engine owns the state, the geometry, the gestures,
+ * the keyboard, the portal and the accessibility; this file owns what it looks
+ * like.
  *
- * **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.
+ * **The app mounts `BottomSheetProvider` once**, inside `DelacourProvider` and
+ * around its navigator. `DelacourProvider` cannot do it — the engine is an
+ * optional peer of this library — so the provider is exported from this
+ * subpath for the app to place. Without it a `Portal` renders where it is
+ * written, which is the inline sheet.
  *
  * 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.
+ * state, or nothing at all and let the sheet hold it.
  *
  * @example
  * <BottomSheet>
@@ -90,12 +123,12 @@ function BottomSheetRoot({ children, defaultOpen = false, isOpen, onOpenChange }
  * </BottomSheet>
  *
  * @example
- * // Controlled, and opened from somewhere other than a trigger.
- * <BottomSheet isOpen={isOpen} onOpenChange={setOpen}>
+ * // Controlled, snapped, and scrolling.
+ * <BottomSheet dynamicSizing={false} isOpen={isOpen} onOpenChange={setOpen} snapPoints={["50%", "90%"]}>
  *   <BottomSheet.Portal>
  *     <BottomSheet.Overlay />
  *     <BottomSheet.Container>
- *       <BottomSheet.Content>{…}</BottomSheet.Content>
+ *       <BottomSheet.ScrollView>{rows}</BottomSheet.ScrollView>
  *     </BottomSheet.Container>
  *   </BottomSheet.Portal>
  * </BottomSheet>
@@ -103,23 +136,43 @@ function BottomSheetRoot({ children, defaultOpen = false, isOpen, onOpenChange }
 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. */
+	/** Everything drawn above the app, teleported to the nearest host. `inline` to render in place. */
+	Portal: Headless.Portal,
+	/** The scrim. Omit it and the sheet has none. */
 	Overlay: BottomSheetOverlay,
-	/** The sheet itself. Every gorhom prop passes through it. */
+	/** The panel that moves. Brings its own `Background` and `Handle` unless you write them. */
 	Container: BottomSheetContainer,
-	/** The sheet's body, sized to itself under `enableDynamicSizing`. */
+	/** The panel's surface — `bg-popover`, top corners rounded, every corner when `detached`. */
+	Background: BottomSheetBackground,
+	/** The grabber's row, and the sheet's one adjustable accessibility element. */
+	Handle: BottomSheetHandle,
+	/** The static body. A sheet sized to its content is sized to this. */
 	Content: BottomSheetContent,
-	/** A scrolling body. Needs `enableDynamicSizing={false}` and snap points. */
+	/** A scrolling body. Sizes to its rows, capped by `maxDynamicContentSize`, or fills explicit `snapPoints`. */
 	ScrollView: BottomSheetScrollView,
+	/** A virtualised body. */
+	FlatList: BottomSheetFlatList,
+	/** A virtualised body with sticky section headers. */
+	SectionList: BottomSheetSectionList,
+	/** A `LegendList` body. Needs the optional `@legendapp/list` peer. */
+	LegendList: BottomSheetLegendList,
+	/** Controls at the bottom. `sticky` pins them over the body and rides the keyboard. */
+	Footer: BottomSheetFooter,
 	/** 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. */
+	/** The sheet's heading — a `Text.Header` that labels the panel for a screen reader. */
 	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,
+	/** An `Input` registered with the sheet, so the keyboard it raises is the sheet's. */
+	TextInput: BottomSheetTextInput,
+	/** A body whose contents follow a step machine and whose height glides between them. */
+	Steps: BottomSheetSteps,
+	/** One step of a `Steps` body. */
+	Step: BottomSheetStep,
+	/** A place for sheets to teleport to other than the root — the recipe for a native modal. */
+	Host: BottomSheetHost,
+	/** The engine's provider, sharing `OverlayProvider`'s teleport host. Mount it once, inside `DelacourProvider`. */
+	Provider: BottomSheetProvider,
 	displayName: "DelacourUI.BottomSheet",
 });

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

@@ -1,16 +1,14 @@
 import { describe, expect, test } from "bun:test";
+import { resolveSheetBottomInset, resolveSheetScrollEndPadding } from "@delacour/react-native-bottom-sheet/core";
 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,
 } from "./bottom-sheet.variants";
 
 const LIGHT = declaredTokens("light");
@@ -32,6 +30,7 @@ function colorTokens(cls: string): string[] {
 }
 
 const SLOTS = bottomSheetVariants();
+const DETACHED = bottomSheetVariants({ detached: true });
 
 /**
  * The slots this component declares, pinned rather than derived.
@@ -47,6 +46,8 @@ const SLOT_NAMES = [
 	"handleIndicator",
 	"content",
 	"scrollContent",
+	"steps",
+	"step",
 	"footer",
 	"stickyFooter",
 	"close",
@@ -81,8 +82,8 @@ describe("the overlay token", () => {
 			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.
+		// Any other opacity would multiply against that alpha and land the scrim
+		// somewhere the theme did not ask for.
 		expect(BOTTOM_SHEET_OVERLAY_OPACITY).toBe(1);
 	});
 
@@ -112,74 +113,28 @@ describe("every token the slots name", () => {
 
 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.
+		// A modal sheet has no resting state: presented or gone.
 		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", () => {
+describe("the inset helpers the engine's core exports", () => {
+	// They used to live here. They moved to the engine so the engine's own footer
+	// and body could share them; the skin re-exports them for the callers that
+	// imported them from `@delacour/react-native-ui/bottom-sheet`.
+	test("give the safe-area band to static 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.
+	test("hold content off a pinned footer by the gap alone, never the band", () => {
+		// The footer's own box carries the band; the content asking for it too
+		// would count 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);
+		expect(
+			resolveSheetScrollEndPadding({ bottom: 34, footerGap: BOTTOM_SHEET_FOOTER_GAP, hasStickyFooter: true })
+		).toBe(BOTTOM_SHEET_FOOTER_GAP);
 	});
 });
 
@@ -211,7 +166,7 @@ describe("bottomSheetVariants slots", () => {
 		expect(declared.sort()).toEqual([...SLOT_NAMES].sort());
 	});
 
-	test("the sheet's surface rounds its top corners only", () => {
+	test("an attached sheet's surface rounds its top corners only", () => {
 		const background = SLOTS.background();
 		expect(background).toMatch(/\brounded-t-/);
 		expect(background).not.toMatch(/\brounded-b-/);
@@ -220,6 +175,17 @@ describe("bottomSheetVariants slots", () => {
 		expect(background).not.toMatch(/\brounded-(?:none|xs|sm|md|lg|xl|2xl|3xl|full)\b/);
 	});
 
+	test("a detached card's surface rounds every corner, and only once", () => {
+		const background = DETACHED.background();
+		// The card floats, so its bottom edge is on screen and needs the radius.
+		expect(background).toMatch(/\brounded-2xl\b/);
+		// tailwind-merge has to have replaced the top-only radius, not stacked
+		// beside it — two radius utilities on one view is order-dependent.
+		expect(background).not.toMatch(/\brounded-t-/);
+		// The surface itself is unchanged.
+		expect(colorTokens(background)).toEqual(colorTokens(SLOTS.background()));
+	});
+
 	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.
@@ -229,10 +195,10 @@ describe("bottomSheetVariants slots", () => {
 		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.
+	test("a pinned footer writes its vertical padding as the engine's prop, never a class", () => {
+		// The engine measures the footer's inner box into the sheet's height, and
+		// padding handed to its `padding` prop lands on that box. A class on the
+		// outer view would be height the snap point never counts.
 		expect(SLOTS.stickyFooter()).not.toMatch(/\bp[tby]?-[\d.]+\b/);
 		expect(BOTTOM_SHEET_FOOTER_PADDING).toBeGreaterThan(0);
 	});
@@ -256,9 +222,20 @@ describe("bottomSheetVariants slots", () => {
 		expect(SLOTS.scrollContent()).toMatch(/\bpx-screen-gutter\b/);
 	});
 
+	test("a multi-step body keeps the gutter on the stack and the vertical padding on each step", () => {
+		// The engine measures each `Step`, not the box around the stack, so
+		// vertical padding on `steps` would be height the sheet never counts.
+		expect(SLOTS.steps()).toMatch(/\bpx-screen-gutter\b/);
+		expect(SLOTS.steps()).not.toMatch(/\bp[tby]-[\d.]+\b/);
+		expect(SLOTS.step()).not.toMatch(/\bpx-/);
+		// A step reads like static content: same gap, same top padding.
+		expect(SLOTS.step().match(/\bgap-[\d.]+\b/)?.[0]).toBe(SLOTS.content().match(/\bgap-[\d.]+\b/)?.[0]);
+		expect(SLOTS.step().match(/\bpt-[\d.]+\b/)?.[0]).toBe(SLOTS.content().match(/\bpt-[\d.]+\b/)?.[0]);
+	});
+
 	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.
+		// The engine animates the scrim's opacity off the sheet's index; a class
+		// here would be a second writer of the same style property.
 		expect(SLOTS.overlay()).not.toMatch(/\bopacity-\d/);
 	});
 

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

@@ -13,45 +13,23 @@ 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.
+ * **1.** The alpha lives in `--overlay`, so any other number here would multiply
+ * against it and land the scrim somewhere the theme did not ask 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.
+ * The snap point 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`).
+ * 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`). These are the engine's own defaults too; they are named
+ * here so the test that pins them has something to read.
  */
 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`.
  *
@@ -62,22 +40,23 @@ export const BOTTOM_SHEET_KEYBOARD_DEFAULTS = {
 export const BOTTOM_SHEET_CLOSE_HIT_SLOP = 8;
 
 /**
- * The padding a pinned footer keeps whatever the keyboard is doing.
+ * The padding a pinned footer's measured box carries.
  *
- * 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.
+ * A number rather than a `p-4`, because it is handed to the engine's `padding`
+ * prop: the engine measures the footer's inner box into the dynamic snap point,
+ * and padding written there is counted where a class on the outer view would
+ * not be. The horizontal gutter still comes from the `stickyFooter` slot, which
+ * is merged after it.
  */
 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.
+ * Also a number, because it is the engine's `footerGap` — added to the spacer it
+ * reserves under the body 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;
 
@@ -85,7 +64,7 @@ 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.
+		 * opacity the engine drives off the sheet's own index.
 		 */
 		overlay: "bg-overlay",
 		/**
@@ -94,7 +73,8 @@ export const bottomSheetVariants = tv({
 		 * 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.
+		 * radius there shows as two notches of the app behind it. The `detached`
+		 * variant is the exception — a floating card has a visible bottom edge.
 		 */
 		background: "rounded-t-2xl bg-popover",
 		handle: "items-center justify-center pt-3 pb-1",
@@ -102,6 +82,14 @@ export const bottomSheetVariants = tv({
 		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",
+		/**
+		 * A multi-step body. The gutter only: the engine measures each `Step`, not
+		 * the box around the stack, so vertical padding here would be height the
+		 * sheet never counts.
+		 */
+		steps: "px-screen-gutter",
+		/** One step of a multi-step body — `content` less the gutter `steps` already carries. */
+		step: "gap-4 pt-2",
 		footer: "gap-3 px-screen-gutter pt-4",
 		/**
 		 * A pinned footer draws OVER the content, so unlike the inline one it has
@@ -110,9 +98,8 @@ export const bottomSheetVariants = tv({
 		 * 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}.
+		 * It carries no vertical padding: that is the engine's `padding` prop, so
+		 * the measured box counts it. 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",
@@ -131,69 +118,27 @@ export const bottomSheetVariants = tv({
 		 */
 		title: "pr-8",
 	},
+	variants: {
+		/**
+		 * A floating card. Every corner is on screen, so every corner rounds;
+		 * `rounded-2xl` replaces `rounded-t-2xl` through tailwind-merge rather
+		 * than stacking beside it.
+		 */
+		detached: {
+			true: {
+				background: "rounded-2xl",
+			},
+		},
+	},
 });
 
 /**
- * There is no `description` or `scrollView` slot.
+ * There is no `description`, `panel`, `portal` 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.
+ * None has any layout of its own — a description is a `Text.Paragraph` in a
+ * gap column, the panel is a transparent frame the engine positions, 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 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;
-}