@delacour/react-native-bottom-sheet 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,132 @@
+# @delacour/react-native-bottom-sheet
+
+A headless bottom sheet engine for React Native — Gesture Handler for the
+pans, Reanimated for the motion, keyboard-controller for the keyboard,
+teleport for the portal.
+
+No tokens, no `className`, no theme. Every radius, colour and inset is a
+`style` you pass in. If you want a sheet already wearing a design system, use
+[`@delacour/react-native-ui/bottom-sheet`](https://ui.delacour.co.nz/docs/native/components/bottom-sheet),
+which is this engine with the tokens attached.
+
+Documentation: [ui.delacour.co.nz/docs/bottom-sheet](https://ui.delacour.co.nz/docs/bottom-sheet).
+
+> **Alpha.** This package, `@delacour/react-native-ui` and
+> `@delacour/react-native-charts` publish to npm's `alpha` tag, and every alpha
+> is also `latest`.
+
+## Install
+
+```bash
+bun add @delacour/react-native-bottom-sheet@alpha
+bunx expo install react-native-gesture-handler react-native-reanimated react-native-worklets react-native-keyboard-controller react-native-safe-area-context react-native-teleport
+```
+
+The native peers go through `expo install`, so the SDK picks versions it can
+build; `react` and `react-native` are already in any app.
+
+**Fabric only, dev client only.** `react-native-teleport` moves native views
+between hosts, which needs the new architecture — the default since React
+Native 0.76 and the only architecture in Expo SDK 53 and later. It is a native
+module, so it does not run in Expo Go: build a dev client
+(`npx expo run:ios`, or an EAS development build) and rebuild it after
+installing.
+
+| Peer | Range | Why |
+| --- | --- | --- |
+| `react` | `>=19` | Ref-as-prop |
+| `react-native` | `>=0.81` | Fabric `getBoundingClientRect` |
+| `react-native-gesture-handler` | `>=2.28` | The handle and content pans |
+| `react-native-reanimated` | `>=4` | Every animated value |
+| `react-native-worklets` | `>=0.5` | `scheduleOnRN` from the UI thread |
+| `react-native-keyboard-controller` | `>=1.18` | The only keyboard source — frame-accurate height and progress |
+| `react-native-safe-area-context` | `>=5` | The bottom band under a sticky footer |
+| `react-native-teleport` | `>=1.2` | The portal — the React tree stays put, so context reaches every part |
+
+The package has no runtime dependencies of its own.
+
+## Providers
+
+Your app mounts four, in this order. The package renders only the last — a
+nested gesture root is dead weight, and a nested `KeyboardProvider` is a
+second keyboard that disagrees with the first.
+
+```tsx
+import { BottomSheetProvider } from "@delacour/react-native-bottom-sheet";
+import { GestureHandlerRootView } from "react-native-gesture-handler";
+import { KeyboardProvider } from "react-native-keyboard-controller";
+import { initialWindowMetrics, SafeAreaProvider } from "react-native-safe-area-context";
+
+<GestureHandlerRootView style={{ flex: 1 }}>
+  <SafeAreaProvider initialMetrics={initialWindowMetrics}>
+    <KeyboardProvider>
+      <BottomSheetProvider>{children}</BottomSheetProvider>
+    </KeyboardProvider>
+  </SafeAreaProvider>
+</GestureHandlerRootView>;
+```
+
+`BottomSheetProvider` is the root host every sheet teleports to, so a sheet
+draws over the navigator wherever it was written. Without it a `Portal`
+renders where it is written, as an inline sheet.
+
+## Anatomy
+
+```tsx
+import { BottomSheet } from "@delacour/react-native-bottom-sheet";
+
+<BottomSheet snapPoints={["40%", "90%"]}>
+  <BottomSheet.Trigger>
+    <Text>Open</Text>
+  </BottomSheet.Trigger>
+  <BottomSheet.Portal>
+    <BottomSheet.Overlay style={{ backgroundColor: "rgba(0,0,0,0.4)" }} />
+    <BottomSheet.Container>
+      <BottomSheet.Background style={{ backgroundColor: "#fff", borderTopLeftRadius: 16, borderTopRightRadius: 16 }} />
+      <BottomSheet.Handle style={{ alignItems: "center", paddingVertical: 12 }}>
+        <View style={{ width: 36, height: 5, borderRadius: 3, backgroundColor: "#ccc" }} />
+      </BottomSheet.Handle>
+      <BottomSheet.Content style={{ padding: 16 }}>
+        <BottomSheet.Title>Filters</BottomSheet.Title>
+        <BottomSheet.Description>Narrow the list down.</BottomSheet.Description>
+        <BottomSheet.TextInput placeholder="Search" />
+        <BottomSheet.Close>
+          <Text>Close</Text>
+        </BottomSheet.Close>
+      </BottomSheet.Content>
+      <BottomSheet.Footer padding={16}>
+        <Button title="Apply" onPress={apply} />
+      </BottomSheet.Footer>
+    </BottomSheet.Container>
+  </BottomSheet.Portal>
+</BottomSheet>;
+```
+
+`Container` is the panel that moves; `Content` is the static body inside it.
+Swap the body for `BottomSheet.ScrollView`, `FlatList` or `SectionList` and
+the list's content size becomes the sheet's own detent; swap it for
+`BottomSheet.Steps` with a controller from `useSheetMachine` and the sheet's
+height glides between the steps of a typed machine. `Footer` is sticky by
+default, standing on the safe-area band and riding the keyboard's edge.
+`<BottomSheet.Portal inline>` renders in place; `<BottomSheet.Host name>`
+gives a native modal a target of its own; `detached` floats the sheet as a
+card.
+
+Sizing and behaviour — `snapPoints`, `dynamicSizing`, `maxDynamicContentSize`,
+`keyboardBehavior`, `detached`, the haptic worklet props — are the root's.
+Every part takes `style` and `ref`, and the parts that render text or a press
+take `asChild` to hand their behaviour to an element of yours.
+
+## The maths on its own
+
+`@delacour/react-native-bottom-sheet/core` is every detent, keyboard, footer
+and geometry calculation in the package, plus the step machine, importable
+with no native module in the module graph:
+
+```ts
+import { defineSheetMachine, positionFor, UNMEASURED } from "@delacour/react-native-bottom-sheet/core";
+```
+
+## Licence
+
+MIT

package/package.json

@@ -0,0 +1,57 @@
+{
+	"name": "@delacour/react-native-bottom-sheet",
+	"version": "0.1.0-alpha.0",
+	"description": "Headless bottom sheet engine for React Native — no tokens, no className",
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/delacournz/delacour-ui.git",
+		"directory": "packages/react-native-bottom-sheet"
+	},
+	"keywords": [
+		"react-native",
+		"bottom-sheet",
+		"reanimated",
+		"gesture-handler",
+		"keyboard-controller",
+		"expo"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"README.md"
+	],
+	"sideEffects": false,
+	"exports": {
+		".": "./src/index.ts",
+		"./core": "./src/core/index.ts"
+	},
+	"scripts": {
+		"fmt": "biome format --write ./src",
+		"lint": "biome lint --write ./src",
+		"check": "biome check ./src",
+		"typecheck": "tsc --noEmit",
+		"test": "bun test"
+	},
+	"peerDependencies": {
+		"react": ">=19",
+		"react-native": ">=0.81",
+		"react-native-gesture-handler": ">=2.28",
+		"react-native-keyboard-controller": ">=1.18",
+		"react-native-reanimated": ">=4",
+		"react-native-safe-area-context": ">=5",
+		"react-native-teleport": ">=1.2",
+		"react-native-worklets": ">=0.5"
+	},
+	"devDependencies": {
+		"@delacour/biome-config": "workspace:*",
+		"@delacour/tsconfig": "workspace:*",
+		"@types/bun": "^1.3.8",
+		"@types/react": "catalog:",
+		"react-native-teleport": "^1.2.2",
+		"typescript": "^5.9.3"
+	}
+}

package/src/animation/AGENTS.md

@@ -0,0 +1,58 @@
+# animation
+
+How `base` moves, and how the JS thread hears about it.
+
+## Files
+
+| Path | What |
+| --- | --- |
+| `animation.types.ts` | `SheetAnimation` (the prop), `AnimateTo` / `JumpTo` / `SettleAt` (the worklets), `SettleListener` / `AnimateListener` (what JS hears) |
+| `resolve-animation.ts` | Easing and reduce-motion names to Reanimated's values; `toReanimated` turns the core's resolved config into a `withSpring` / `withTiming` config |
+| `use-animate-to.ts` | `animateTo(target, source, velocity)`, `jumpTo(target, source)` and `settleAt(target, source)`, hook-scope worklets |
+| `use-settle-callbacks.ts` | The two JS listeners, stable for the sheet's lifetime, reading every prop through a ref |
+
+## The shape
+
+`selectAnimation` in the core picks the config as plain data — the consumer's
+over the platform default, iOS a spring and everything else a timing, easing by
+name. `resolve-animation.ts` is the one place a name becomes a Reanimated
+function, and it runs on the JS thread once per config change.
+
+`animateTo` cancels whatever owns `base`, records the target and the source in
+the shared state, schedules `onAnimate` on JS, and hands `base` to the spring
+or the timing. The completion callback settles only on `finished === true`:
+a cancelled animation is someone else's now, and settling it would report an
+index the sheet never reached. Settling writes `currentIndex` and schedules
+`onSettle`.
+
+`jumpTo` is `animateTo` without the motion — `forceClose`, a container resize,
+`animateOnMount: false`.
+
+`settleAt` is the completion alone: no `onAnimate`, no target recorded, `base`
+written to the detent it is already within a settle tolerance of, then the same
+`currentIndex` write and `onSettle`. The content pan uses it for a release the
+list owns — the finger carried the sheet to the top and kept scrolling, so
+nothing animated and nothing else would report the index.
+
+## Reanimated 4
+
+`scheduleOnRN` comes from `react-native-worklets`, not from Reanimated;
+`cancelAnimation`, `withSpring`, `withTiming`, `Easing` and `ReduceMotion` from
+Reanimated. Reanimated 4 replaced the spring's `restDisplacementThreshold` and
+`restSpeedThreshold` with one relative `energyThreshold`, so those two fields
+of the core's `IOS_SPRING` are kept as data and not forwarded; with
+`overshootClamping` and a stiff spring, the default threshold
+settles within a frame or two of them.
+
+## The listeners
+
+`useSettleCallbacks` returns two functions that never change identity. Every
+prop they read goes through a ref, because `scheduleOnRN` calls the function
+the worklet captured when it was built — a listener that closed over
+`onIndexChange` directly would call the callback from the render the gesture
+began in.
+
+A settle at `-1` is where a physical close becomes state: `onClose`, then
+`setOpen(false)` — the root's `onOpenChange(false)` — then `setPresented(false)`
+and the portal's children unmount unless `keepMounted`. Any other settle reports
+through `onIndexChange` only when the index moved.

package/src/animation/animation.types.ts

@@ -0,0 +1,35 @@
+import type { AnimationSource, SheetAnimationConfig } from "../core";
+
+/** The `animation` prop — a spring or a timing, every field optional. */
+export type SheetAnimation = SheetAnimationConfig;
+
+/**
+ * Moves `base` to a height. A hook-scope worklet: callable from a gesture
+ * callback, a reaction or the intent resolver, all on the UI thread.
+ *
+ * `velocity` is in height space per second — upward positive — and only a
+ * spring reads it.
+ */
+export type AnimateTo = (target: number, source: AnimationSource, velocity: number) => void;
+
+/** Puts `base` at a height with no animation and settles immediately. */
+export type JumpTo = (target: number, source: AnimationSource) => void;
+
+/**
+ * Settles at a height the sheet is already on — the bookkeeping of a finished
+ * animation with no animation: `currentIndex`, then `onSettle`. For a release
+ * that moved the sheet by hand and never animated.
+ */
+export type SettleAt = (target: number, source: AnimationSource) => void;
+
+/** What the JS thread hears when an animation lands — `count` is how many detents there were, for the handle's accessibility value. */
+export type SettleListener = (index: number, height: number, source: AnimationSource, count: number) => void;
+
+/** What the JS thread hears when an animation starts. */
+export type AnimateListener = (
+	fromIndex: number,
+	toIndex: number,
+	fromHeight: number,
+	toHeight: number,
+	source: AnimationSource
+) => void;

package/src/animation/resolve-animation.ts

@@ -0,0 +1,75 @@
+import {
+	Easing,
+	type EasingFunction,
+	ReduceMotion,
+	type WithSpringConfig,
+	type WithTimingConfig,
+} from "react-native-reanimated";
+import type { EasingName, ReduceMotionMode, ResolvedAnimation } from "../core";
+
+/**
+ * A core easing name to Reanimated's function. The core keeps its defaults as
+ * data so `bun test` can read them; this is the one place the name becomes a
+ * function, and it happens on the JS thread before any worklet runs.
+ */
+export function easingFor(name: EasingName): EasingFunction {
+	switch (name) {
+		case "linear":
+			return Easing.linear;
+		case "outCubic":
+			return Easing.out(Easing.cubic);
+		case "inOutCubic":
+			return Easing.inOut(Easing.cubic);
+		default:
+			return Easing.out(Easing.exp);
+	}
+}
+
+export function reduceMotionFor(mode: ReduceMotionMode): ReduceMotion {
+	switch (mode) {
+		case "always":
+			return ReduceMotion.Always;
+		case "never":
+			return ReduceMotion.Never;
+		default:
+			return ReduceMotion.System;
+	}
+}
+
+/** A resolved animation as the Reanimated config `withSpring` / `withTiming` takes. */
+export type ReanimatedAnimation =
+	| { type: "spring"; config: WithSpringConfig }
+	| { type: "timing"; config: WithTimingConfig };
+
+/**
+ * Turns the core's plain-data resolution into a Reanimated config, once, on
+ * the JS thread.
+ *
+ * Reanimated 4 replaced `restDisplacementThreshold` / `restSpeedThreshold`
+ * with a single relative `energyThreshold`, so the two rest thresholds the
+ * core carries — the previous engine's defaults, kept as data for a future runtime that
+ * reads them — are not forwarded. With `overshootClamping` and a stiff spring
+ * the default energy threshold settles within a frame or two of them anyway.
+ */
+export function toReanimated(resolved: ResolvedAnimation): ReanimatedAnimation {
+	if (resolved.type === "spring") {
+		return {
+			type: "spring",
+			config: {
+				damping: resolved.damping,
+				stiffness: resolved.stiffness,
+				mass: resolved.mass,
+				overshootClamping: resolved.overshootClamping,
+				reduceMotion: reduceMotionFor(resolved.reduceMotion),
+			},
+		};
+	}
+	return {
+		type: "timing",
+		config: {
+			duration: resolved.duration,
+			easing: easingFor(resolved.easing),
+			reduceMotion: reduceMotionFor(resolved.reduceMotion),
+		},
+	};
+}

package/src/animation/use-animate-to.ts

@@ -0,0 +1,107 @@
+import { useMemo } from "react";
+import { Platform } from "react-native";
+import { cancelAnimation, withSpring, withTiming } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { type AnimationSource, indexForHeight, type ReduceMotionMode, selectAnimation } from "../core";
+import { ANIM_STATUS, type SheetGeometry, type SheetSharedState } from "../state/state.types";
+import type { AnimateListener, AnimateTo, JumpTo, SettleAt, SettleListener, SheetAnimation } from "./animation.types";
+import { toReanimated } from "./resolve-animation";
+
+export type UseAnimateToOptions = {
+	state: SheetSharedState;
+	geometry: SheetGeometry;
+	animation: SheetAnimation | undefined;
+	overrideReduceMotion: ReduceMotionMode | undefined;
+	/** Stable across renders — the root wraps its props in refs. */
+	onSettle: SettleListener;
+	onAnimate: AnimateListener;
+};
+
+/**
+ * The one way `base` moves.
+ *
+ * `animateTo` cancels whatever is in flight, records the target and source,
+ * tells the JS thread an animation started, and hands `base` to a spring or a
+ * timing whose completion writes `currentIndex` and reports the settle.
+ * `jumpTo` is the same without the motion — `forceClose`, a container resize,
+ * and `animateOnMount: false`. `settleAt` is the completion alone: no
+ * `onAnimate`, no target recorded, `base` written to the detent it is already
+ * within a settle tolerance of. It is for the content pan whose release the
+ * list owns — the finger carried the sheet to the top and kept scrolling, so
+ * nothing animated and nothing would otherwise write `currentIndex`.
+ *
+ * Both are hook-scope worklets: they close over `indexForHeight` from the core
+ * in the ordinary way, which is what the flat-worklet rule permits and what a
+ * module-scope worklet could not do.
+ *
+ * A cancelled animation does not settle. The gesture that cancelled it will,
+ * and an animation that interrupted it has its own completion; settling on
+ * `finished === false` would report an index the sheet never reached.
+ */
+export function useAnimateTo(options: UseAnimateToOptions): {
+	animateTo: AnimateTo;
+	jumpTo: JumpTo;
+	settleAt: SettleAt;
+} {
+	const { state, geometry, animation, overrideReduceMotion, onSettle, onAnimate } = options;
+	const platform = Platform.OS;
+	const animationKey = JSON.stringify(animation ?? null);
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: `animation` is keyed by its serialisation
+	const resolved = useMemo(
+		() => toReanimated(selectAnimation(animation, platform, overrideReduceMotion)),
+		[animationKey, platform, overrideReduceMotion]
+	);
+
+	return useMemo(() => {
+		const settle = (target: number, source: AnimationSource): void => {
+			"worklet";
+			state.animStatus.value = ANIM_STATUS.IDLE;
+			const index = Math.round(indexForHeight(target, geometry.detents.value, geometry.closedHeight.value));
+			state.currentIndex.value = index;
+			scheduleOnRN(onSettle, index, target, source, geometry.detents.value.length);
+		};
+
+		const begin = (target: number, source: AnimationSource): void => {
+			"worklet";
+			cancelAnimation(state.base);
+			const fromHeight = state.base.value;
+			const fromIndex = geometry.index.value;
+			const toIndex = indexForHeight(target, geometry.detents.value, geometry.closedHeight.value);
+			state.animStatus.value = ANIM_STATUS.RUNNING;
+			state.animSource.value = source;
+			state.animTarget.value = target;
+			scheduleOnRN(onAnimate, fromIndex, toIndex, fromHeight, target, source);
+		};
+
+		const animateTo: AnimateTo = (target, source, velocity) => {
+			"worklet";
+			begin(target, source);
+			const complete = (finished?: boolean): void => {
+				"worklet";
+				if (finished === true) settle(target, source);
+			};
+			if (resolved.type === "spring") {
+				state.base.value = withSpring(target, { ...resolved.config, velocity }, complete);
+				return;
+			}
+			state.base.value = withTiming(target, resolved.config, complete);
+		};
+
+		const jumpTo: JumpTo = (target, source) => {
+			"worklet";
+			begin(target, source);
+			state.base.value = target;
+			settle(target, source);
+		};
+
+		const settleAt: SettleAt = (target, source) => {
+			"worklet";
+			cancelAnimation(state.base);
+			state.base.value = target;
+			settle(target, source);
+		};
+
+		return { animateTo, jumpTo, settleAt };
+	}, [state, geometry, resolved, onSettle, onAnimate]);
+}

package/src/animation/use-settle-callbacks.ts

@@ -0,0 +1,60 @@
+import { useCallback, useRef } from "react";
+import { type AnimationSource, CLOSED_INDEX } from "../core";
+import type { AnimateListener, SettleListener } from "./animation.types";
+
+export type UseSettleCallbacksOptions = {
+	isOpen: boolean;
+	setOpen: (open: boolean) => void;
+	/** Unmounts the portal's children once a close has landed, unless the sheet is kept mounted. */
+	setPresented: (presented: boolean) => void;
+	/** The settled index and the detent count, for the handle's accessibility value. */
+	setIndex: (index: number) => void;
+	setDetentCount: (count: number) => void;
+	onIndexChange: ((index: number, height: number, source: AnimationSource) => void) | undefined;
+	onClose: (() => void) | undefined;
+	onAnimate: AnimateListener | undefined;
+};
+
+/**
+ * The JS-thread half of an animation: two listeners the UI thread schedules
+ * through `scheduleOnRN`, stable for the sheet's lifetime so the worklets that
+ * capture them never rebuild.
+ *
+ * Every prop they read goes through a ref. `scheduleOnRN` takes the function
+ * it was handed at the time the worklet was built, so a listener that closed
+ * over `onIndexChange` directly would call the callback from the render the
+ * gesture began in.
+ *
+ * A settle at `-1` is the one place a physical close becomes state: `onClose`,
+ * then `setOpen(false)` — which is `onOpenChange(false)` — then the portal
+ * unmounts. A settle anywhere else reports through `onIndexChange` only when
+ * the index actually moved.
+ */
+export function useSettleCallbacks(options: UseSettleCallbacksOptions): {
+	onSettle: SettleListener;
+	onAnimate: AnimateListener;
+} {
+	const latest = useRef(options);
+	latest.current = options;
+	const lastReported = useRef(CLOSED_INDEX);
+
+	const onSettle = useCallback<SettleListener>((index, height, source, count) => {
+		const current = latest.current;
+		current.setIndex(index);
+		current.setDetentCount(count);
+		if (index !== lastReported.current) {
+			lastReported.current = index;
+			current.onIndexChange?.(index, height, source);
+		}
+		if (index !== CLOSED_INDEX) return;
+		current.onClose?.();
+		if (current.isOpen) current.setOpen(false);
+		current.setPresented(false);
+	}, []);
+
+	const onAnimate = useCallback<AnimateListener>((fromIndex, toIndex, fromHeight, toHeight, source) => {
+		latest.current.onAnimate?.(fromIndex, toIndex, fromHeight, toHeight, source);
+	}, []);
+
+	return { onSettle, onAnimate };
+}

package/src/components/AGENTS.md

@@ -0,0 +1,80 @@
+# components
+
+The compound `BottomSheet` and its parts. Every part accepts `style` and `ref`;
+none takes a class; every `displayName` is `DelacourBottomSheet.BottomSheet.X`.
+
+## Files
+
+| Path | What |
+| --- | --- |
+| `bottom-sheet.tsx` | The root — state, geometry, animation, pans, intents, the imperative ref, and the `Object.assign` that names the parts |
+| `bottom-sheet.types.ts` | Every prop type, `BottomSheetRef`, `BottomSheetContextValue`, `BottomSheetAnimatedValue` |
+| `bottom-sheet.context.tsx` | Three contexts: `BottomSheet` (open state and ref methods), `BottomSheetAnimated` (the shared values), `BottomSheetInternal` (what the parts share) |
+| `bottom-sheet-trigger.tsx` | Opens the sheet; `asChild` donates `onPress` |
+| `bottom-sheet-portal.tsx` | The frame the sheet measures itself against — inside a teleport `Portal` to the nearest host under a provider, in place with `inline` or without one; registers the sheet as presented |
+| `bottom-sheet-overlay.tsx` | The scrim: a React Native `Pressable`, written before the panel |
+| `bottom-sheet-container.tsx` | The panel — the surface that moves; inset by `detachedFrame` and `box-none` when detached |
+| `bottom-sheet-background.tsx` | The panel's absolute-fill surface, `pointerEvents: none`; exactly the sheet's `height` tall when detached |
+| `bottom-sheet-handle.tsx` | The grabber's row: the handle pan and the adjustable accessibility element |
+| `bottom-sheet-content.tsx` | The static body: the content pan, the `bodyClip` clip, the `contentArea + bodyInset` layout box, the measured inner box and the inset spacer |
+| `bottom-sheet-footer.tsx` | The sticky footer: translated to `footerTop`, its styled box padded through the band and measured less the band into `footerContentHeight` |
+| `bottom-sheet-close.tsx` | The dismiss control; `asChild` donates `onPress` |
+| `bottom-sheet-title.tsx` | The heading; publishes the `nativeID` the panel is labelled by |
+| `bottom-sheet-description.tsx` | Supporting copy; publishes a `nativeID` of its own |
+
+`Host` and `Provider` live in `src/portal` and are named on the compound from
+there. Parts that arrive later: `Footer` and `TextInput` (BSHEET-3), `ScrollView`,
+`FlatList` and `SectionList` (BSHEET-4), `Steps` and `Step` (BSHEET-6b).
+
+## The render tree
+
+```
+teleport Portal — only under a provider (absoluteFill of the host, zIndex from the registry)
+ Portal — the frame (absolute, top: topInset, box-none, overflow hidden, zIndex; measures the container)
+  Overlay  (absoluteFill — margins and gap included, opacity from index, pointerEvents auto|none, RN Pressable)
+  Container — the panel (absoluteFill, translateY: position; detached: left/width from detachedFrame, overflow visible, box-none)
+    Background (absoluteFill, pointerEvents none; detached: height = sheet height)
+    Handle     (pan detector; measures handleHeight)
+    Content    (pan detector; clip: overflow hidden, animated maxHeight = bodyClip)
+      layout box (animated maxHeight = contentArea + bodyInset; height too under fillParent)
+        inner box (measures contentHeight) + trailing spacer (bodyInset, + footerGap above a footer)
+    Footer     (absolute, translateY: footerTop; the styled box pads through the band, measures footerContentHeight = box − band)
+```
+
+The overlay is written **before** the panel on purpose. Native hit-testing
+walks siblings back to front, so a touch on the panel never reaches the
+overlay and a touch beside it does — with no Gesture Handler tap anywhere to
+out-compete a `TextInput`. That was the first risk in the plan, and it holds
+on the simulator: a field inside the sheet focuses on the first tap.
+
+## State opens, intents move
+
+`isOpen` — controlled through `isOpen`/`onOpenChange`, or held by the root —
+is the one source of truth for whether the sheet is open. Flipping it true
+sets `presented` (which mounts the portal's children) and dispatches an
+`open` intent, which resolves once every measurement has landed. Every close
+path — swipe, overlay, `Close`, the ref, a controlled `isOpen: false` —
+animates to the closed height, and the settle at `-1` is what flips `isOpen`
+back and unmounts the children. Closing a sheet that is not open is nothing.
+
+The ref's `close()` checks the sheet's effective openness on the JS thread
+before dispatching, so a `close()` while a queued open is still waiting on
+layout clears the queue rather than racing it.
+
+## Accessibility
+
+No `accessible` container: one would collapse the whole sheet into a single
+VoiceOver element. Instead the panel is `accessibilityViewIsModal` while open
+under an overlay, its descendants are hidden while it is closed, and the title
+labels it through `accessibilityLabelledBy`. The handle is the sheet's one
+`adjustable` element: increment and decrement move a detent, escape closes,
+and its value reads `Detent i of n`. The overlay is hidden from assistive
+technology while it is transparent.
+
+## Contexts
+
+All three are provided once, by the root. A teleported portal keeps the React
+tree in place, so they reach every part without being re-provided — and so
+does every context the app provides around the trigger.
+`useBottomSheetInternal` is exported for a part written outside the package —
+a skin's `Footer`, a scrollable — and never for an app.

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

@@ -0,0 +1,34 @@
+import type { ReactElement } from "react";
+import { StyleSheet } from "react-native";
+import Animated, { useAnimatedStyle } from "react-native-reanimated";
+import { useBottomSheetInternal } from "./bottom-sheet.context";
+import type { BottomSheetBackgroundProps } from "./bottom-sheet.types";
+
+/**
+ * The panel's surface: an absolute fill behind the handle and the body that
+ * takes no touches. Colour, radius and shadow arrive as `style` — this is
+ * where a skin puts `rounded-t-2xl bg-popover`, and a detached sheet rounds
+ * every corner here.
+ *
+ * The panel is as tall as the frame, so an attached surface fills it and its
+ * bottom edge is always off-screen. A detached card has a visible bottom
+ * edge: the surface is then the geometry's `surfaceHeight` tall, on the UI
+ * thread — the sheet's height between its detents, and the nearest detent's
+ * height beyond them — so the corners the skin rounds are on screen, the gap
+ * under the card is the overlay's, and a close or an over-drag moves the
+ * whole card as one rigid body rather than shrinking it onto the resting
+ * line.
+ */
+export function BottomSheetBackground({ style, ref, ...props }: BottomSheetBackgroundProps): ReactElement {
+	const { geometry, detached } = useBottomSheetInternal();
+	const surface = geometry.surfaceHeight;
+	const isDetached = detached !== null;
+
+	const sized = useAnimatedStyle(() => {
+		if (!isDetached) return { bottom: 0, height: undefined };
+		return { bottom: undefined, height: surface.value };
+	});
+
+	return <Animated.View pointerEvents="none" ref={ref} style={[StyleSheet.absoluteFill, style, sized]} {...props} />;
+}
+BottomSheetBackground.displayName = "DelacourBottomSheet.BottomSheet.Background";