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

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

@@ -0,0 +1,235 @@
+import type { ReactNode, Ref } from "react";
+import type { PressableProps, TextInput, TextInputProps, TextProps, View, ViewProps } from "react-native";
+import type { SharedValue } from "react-native-reanimated";
+import type { SheetAnimation } from "../animation/animation.types";
+import type {
+	AnimationSource,
+	DetachedProp,
+	DetentSpec,
+	KeyboardBehavior,
+	KeyboardBlurBehavior,
+	KeyboardScope,
+	ReduceMotionMode,
+} from "../core";
+import type { SheetHaptics } from "../gesture/gesture.types";
+
+/**
+ * The imperative surface, for the things with no declarative form.
+ *
+ * `open` and `close` are the same state a controlled `isOpen` drives;
+ * `dismiss` is `close` under the name the library this replaces used. Every
+ * method is an intent: none of them animates from the JS thread, and each is
+ * a no-op when it makes no sense — `close` on a closed sheet, `snapToIndex(4)`
+ * with two detents.
+ */
+export type BottomSheetRef = {
+	snapToIndex: (index: number) => void;
+	/** A height or a `%` of the available height; clamped, never added as a detent. */
+	snapToPosition: (position: DetentSpec) => void;
+	expand: () => void;
+	collapse: () => void;
+	close: () => void;
+	/** Closes with no animation. */
+	forceClose: () => void;
+	open: () => void;
+	dismiss: () => void;
+};
+
+export type BottomSheetProps = SheetHaptics & {
+	children?: ReactNode;
+	ref?: Ref<BottomSheetRef>;
+	/** 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 overlay, `BottomSheet.Close`, the ref, or a controlled
+	 * `isOpen`. One callback for every path.
+	 */
+	onOpenChange?: (isOpen: boolean) => void;
+	/** Controlled detent index. Changing it snaps an open sheet. */
+	index?: number;
+	/** The detent `open` lands on. @default 0 */
+	initialIndex?: number;
+	/** The settled index changed — `-1` on close. */
+	onIndexChange?: (index: number, height: number, source: AnimationSource) => void;
+	/** An animation started. */
+	onAnimate?: (
+		fromIndex: number,
+		toIndex: number,
+		fromHeight: number,
+		toHeight: number,
+		source: AnimationSource
+	) => void;
+	/** The sheet reached its closed height, by any path. `onOpenChange(false)` follows. */
+	onClose?: () => void;
+	/** Heights above the resting bottom, or `%` of the available height. @default [] */
+	snapPoints?: readonly DetentSpec[];
+	/** Adds the content's own height as a detent. @default true */
+	dynamicSizing?: boolean;
+	/** Caps the dynamic detent. */
+	maxDynamicContentSize?: number;
+	/** Pixels the frame leaves clear at the top. @default 0 */
+	topInset?: number;
+	/** The safe-area inset an attached sheet reserves under its content. @default 0 */
+	bottomInset?: number;
+	/**
+	 * A floating card: inset by `horizontalMargin` on both sides, resting
+	 * `bottomOffset` above `bottomInset`, every corner the `Background`'s to
+	 * round. `true` is `{ horizontalMargin: 16, bottomOffset: 16 }`. Closed is
+	 * fully off-screen, `%` detents resolve against the height above the resting
+	 * line, and a tap in the margins or the gap closes.
+	 */
+	detached?: DetachedProp;
+	/** @default true */
+	enablePanDownToClose?: boolean;
+	/** @default true */
+	enableHandlePanningGesture?: boolean;
+	/** @default true */
+	enableContentPanningGesture?: boolean;
+	/** Rubber-band past the detents. @default true */
+	enableOverDrag?: boolean;
+	/** Larger allows more travel. @default 2.5 */
+	overDragResistanceFactor?: number;
+	/** @default "interactive" */
+	keyboardBehavior?: KeyboardBehavior;
+	/** @default "restore" */
+	keyboardBlurBehavior?: KeyboardBlurBehavior;
+	/** @default "inside" */
+	keyboardScope?: KeyboardScope;
+	/** @default true */
+	enableBlurKeyboardOnGesture?: boolean;
+	/** A spring or a timing. Platform default when omitted. */
+	animation?: SheetAnimation;
+	/** Beats the config's own `reduceMotion`. */
+	overrideReduceMotion?: ReduceMotionMode;
+	/** Animate the first open, or land on it. @default true */
+	animateOnMount?: boolean;
+	/** Keep the portal's children mounted while closed. @default false */
+	keepMounted?: boolean;
+	/**
+	 * What opening does to the other sheets already open in the same host:
+	 * `push` stacks on top of them, `replace` closes them. @default "push"
+	 */
+	stackBehavior?: "push" | "replace";
+	/** Android's back button closes the sheet while it is the top one in its host. @default true */
+	closeOnBack?: boolean;
+};
+
+export type BottomSheetTriggerProps = Omit<PressableProps, "children"> & {
+	children?: ReactNode;
+	/** Hand `onPress` to the child rather than rendering a Pressable around it. */
+	asChild?: boolean;
+	ref?: Ref<View>;
+};
+
+export type BottomSheetPortalProps = {
+	children?: ReactNode;
+	style?: ViewProps["style"];
+	ref?: Ref<View>;
+	/**
+	 * Render where written — an absolute fill of the nearest positioned
+	 * ancestor — rather than teleporting to a host. A persistent drawer, a map's
+	 * result list. Never unmounts unless `unmountOnClose` says so.
+	 */
+	inline?: boolean;
+	/** The `BottomSheet.Host` to teleport to. Default: the nearest one — `root` under a bare provider. */
+	hostName?: string;
+	/**
+	 * Unmount the children once a close has settled. Default `true` when
+	 * teleported and `false` when inline; the root's `keepMounted` forces it off.
+	 */
+	unmountOnClose?: boolean;
+};
+
+export type BottomSheetOverlayProps = Omit<ViewProps, "style"> & {
+	style?: ViewProps["style"];
+	ref?: Ref<View>;
+	/** The index the scrim is fully in by. @default 0 */
+	appearsOnIndex?: number;
+	/** The index the scrim is gone by. @default -1 */
+	disappearsOnIndex?: number;
+	/** Opacity at full appearance. @default 1 */
+	opacity?: number;
+	/** What a press does: close, collapse to the first detent, snap to an index, or nothing. @default "close" */
+	pressBehavior?: "close" | "collapse" | "none" | number;
+	/** Let touches reach the app behind the scrim. @default false */
+	enableTouchThrough?: boolean;
+	/** Announced on the pressable scrim. @default "Close" */
+	accessibilityLabel?: string;
+	onPress?: () => void;
+};
+
+export type BottomSheetContainerProps = ViewProps & {
+	ref?: Ref<View>;
+};
+
+export type BottomSheetBackgroundProps = ViewProps & {
+	ref?: Ref<View>;
+};
+
+export type BottomSheetHandleProps = ViewProps & {
+	ref?: Ref<View>;
+	/** Overrides the root's `enableHandlePanningGesture` for this handle. */
+	enablePanningGesture?: boolean;
+};
+
+export type BottomSheetContentProps = ViewProps & {
+	ref?: Ref<View>;
+	/** Extra space between the content and a sticky footer. @default 0 */
+	footerGap?: number;
+};
+
+export type BottomSheetFooterProps = ViewProps & {
+	ref?: Ref<View>;
+	/**
+	 * Stay put over the body and ride the keyboard by transform. Off, it is a
+	 * plain `View` for a footer that scrolls with the content. @default true
+	 */
+	sticky?: boolean;
+	/** Padding on the measured inner view, so it counts in the sheet's height. */
+	padding?: number;
+};
+
+export type BottomSheetTextInputProps = TextInputProps & {
+	ref?: Ref<TextInput>;
+};
+
+export type BottomSheetCloseProps = Omit<PressableProps, "children"> & {
+	children?: ReactNode;
+	asChild?: boolean;
+	ref?: Ref<View>;
+};
+
+export type BottomSheetTitleProps = TextProps & {
+	asChild?: boolean;
+};
+
+export type BottomSheetDescriptionProps = TextProps & {
+	asChild?: boolean;
+};
+
+/** What `useBottomSheet()` returns: the open state and every ref method. */
+export type BottomSheetContextValue = BottomSheetRef & {
+	isOpen: boolean;
+	setOpen: (open: boolean) => void;
+	/** The settled index, `-1` closed. React state, updated on settle. */
+	index: number;
+	/** How many detents there were at the last settle. React state, for the handle's accessibility value. */
+	detentCount: number;
+};
+
+/** What `useBottomSheetAnimated()` returns: the shared values a skin animates against. */
+export type BottomSheetAnimatedValue = {
+	animatedIndex: SharedValue<number>;
+	animatedPosition: SharedValue<number>;
+	animatedHeight: SharedValue<number>;
+	containerHeight: SharedValue<number>;
+	handleHeight: SharedValue<number>;
+	contentHeight: SharedValue<number>;
+	footerHeight: SharedValue<number>;
+	keyboardLift: SharedValue<number>;
+	detents: SharedValue<readonly number[]>;
+	closedHeight: SharedValue<number>;
+};

package/src/core/AGENTS.md

@@ -0,0 +1,160 @@
+# core
+
+Every number the sheet computes, and nothing that renders.
+
+## The rule
+
+**No runtime import of `react`, `react-native`, `react-native-reanimated`,
+`react-native-gesture-handler`, `react-native-worklets`,
+`react-native-keyboard-controller`, `react-native-safe-area-context`,
+`react-native-teleport` or `react-native-pulsar`.** Type-only imports are
+fine. Nothing here imports from outside `core/` either — a `../` would pull a
+hook or a component down into the maths, and into `bun test` with it.
+
+`src/purity.test.ts` enforces both. See the package `AGENTS.md` for why the
+failure mode makes a test necessary rather than a convention sufficient.
+
+## Height space
+
+Every value here is a **height**: pixels of sheet visible above its resting
+bottom line. `0` is closed, detents ascend, `-1` (`UNMEASURED`) is a
+measurement that has not happened. `translateY` is derived from a height only
+at the moment a view needs it, by `geometry/position.ts`, and nowhere else.
+
+## Files
+
+| Path | What |
+| --- | --- |
+| `sheet.types.ts` | `DetentSpec`, the keyboard behaviours, `AnimationSource`, `SheetIntent`, the numeric enums and the two sentinels |
+| `result.ts` | The house `Result` union, copied from the private `@delacour/types` |
+| `detents/normalize-detents.ts` | `parseDetent` (JS, a `Result`) and W `normalizeDetents(spec, available)` — ascending, unique, clamped, invalid entries skipped |
+| `detents/dynamic-detent.ts` | W `dynamicDetent` — handle + content + footer content + band once, capped |
+| `detents/index-for-height.ts` | W `indexForHeight` / `heightForIndex` — piecewise-linear over `[closed, …detents]`, clamped |
+| `detents/select-snap-height.ts` | W `selectSnapHeight` — nearest candidate to `height + projection · velocity`; closes only when given a closed height |
+| `detents/over-drag.ts` | W `resistOverDrag` — slope 1 at the edge, square-root beyond; factor 0 clamps |
+| `detents/sheet-state.ts` | W `sheetState` — closed / opened / extended / overExtended / fill |
+| `keyboard/keyboard-lift.ts` | W `keyboardInContainer`, W `keyboardLift` — the lift, band and gap subtracted in step with progress |
+| `keyboard/keyboard-owner.ts` | W `isInputInsideSheet` — the `keyboardScope: "inside"` geometry test |
+| `keyboard/content-area.ts` | W `contentArea` — what the body may fill, never negative |
+| `keyboard/container-layout-guard.ts` | `acceptContainerLayout` — refuses Android's adjustResize double-count |
+| `keyboard/keyboard-reset-guard.ts` | W `shouldResetKeyboardAnimation` — the stale keyboard-controller guard, ported from `react-native-ui` |
+| `footer/footer-top.ts` | W `footerTop` — constant across a keyboard animation; the sweep test proves it |
+| `footer/bottom-band.ts` | W `bottomBand`, W `bandNow`, W `footerHeight` |
+| `footer/body-inset.ts` | W `bodyInset` — what trails the body, footer or band; W `bodyClip` — the body's clipping box, held to the footer's live top edge; `scrollContentHeight` — a scrollable's content size less its trailing spacer |
+| `footer/sheet-insets.ts` | `resolveSheetBottomInset` (what the engine reserves under static content), `resolveSheetScrollEndPadding` (what a skin adds at the end of scroll content — the `footerGap`, never the band) — re-exported by the skin |
+| `geometry/closed-height.ts` | W `restingBottom`, W `closedHeight`, W `availableHeight` |
+| `geometry/position.ts` | W `positionFor` — height to `translateY`, the only conversion |
+| `geometry/clamp-height.ts` | W `clampHeight` — `NaN` collapses to closed |
+| `geometry/detached-frame.ts` | `resolveDetached`, `DETACHED_DEFAULTS`, W `detachedFrame` — left, width, resting bottom |
+| `backdrop/backdrop-opacity.ts` | W `backdropOpacity`, W `backdropInteractive` |
+| `intent/resolve-intent.ts` | W `resolveIntent(state, intent)` — `wait` / `animate` / `jump` / `null`; open means `currentIndex ≥ 0` **or** `base` above the closed height, so a stale index never strands a visible sheet |
+| `intent/layout-ready.ts` | W `isLayoutReady` |
+| `haptic/crossed-detent.ts` | W `crossedDetent` (boolean), W `detentUnder` (index) |
+| `scroll/scroll-lock.ts` | W `shouldLockScroll`, W `contentPanDrivesSheet` |
+| `scroll/scroll-pan.ts` | W `listDragHeight` — the start offset as a budget the finger spends before the sheet moves; W `listOwnsRelease`; W `restingDetent` — the detent within the settle tolerance of a base, for a release the list owned; W `scrollLockTarget` |
+| `animation/select-animation.ts` | `selectAnimation`, `IOS_SPRING`, `ANDROID_TIMING` — platform defaults as data, easing by name |
+
+W marks a module-scope `"worklet"`; each is flat (see the package `AGENTS.md`)
+and re-implements the little it needs of its siblings inline. Every export
+goes through `index.ts` by name.
+
+## Formulas
+
+With `C` the container height, `inset` the safe-area bottom, `kb` the owned
+keyboard within the container (positive) and `p` keyboard-controller's
+`progress`:
+
+```
+restingBottom = detached ? bottomOffset + inset : 0          closedHeight = −restingBottom
+available     = C − restingBottom                            maxHeight = available
+band          = detached ? 0 : inset                         bandNow = band · (1 − p)
+footerHeight  = hasFooter ? footerContent + bandNow : 0
+dynamicDetent = min(handle + content + (hasFooter ? footerContent : 0) + band, maxDynamicContentSize, available)
+detents       = sortAsc(unique(normalize(spec, available) ∪ {dynamicDetent if dynamicSizing}))
+keyboardLift  = behavior ∈ {interactive, extend} ? max(0, kb − band · p − (detached ? restingBottom : 0)) : 0
+height        = clamp(base + keyboardLift, closedHeight, maxHeight)
+translateY    = C − restingBottom − height
+index         = piecewise(base, [closedHeight, …detents] → [−1, 0, 1, …])      // base, never height
+contentArea   = max(0, min(maxHeight, highest + keyboardLift) − handle − footerHeight − kb − (hasFooter ? 0 : bandNow))
+footerTop     = max(0, height − kb − footerContent − bandNow)
+bodyInset     = hasFooter ? footerHeight : bandNow
+bodyClip      = hasFooter ? max(0, min(contentArea + bodyInset, height − kb − handle − bodyInset)) : contentArea + bodyInset
+backdrop      = index ≥ appearsOn ? opacity : index ≤ disappearsOn ? 0 : linear
+```
+
+The footer proof: `footerTop = base + kb − band·p − kb − footerContent − band + band·p = base − footerContent − band`,
+independent of `p`. `footer/footer-top.test.ts` sweeps it in twenty steps.
+
+The body — `Content`'s layout box, a scrollable's viewport — is laid out
+`contentArea + bodyInset` tall, to the sheet's bottom line, and reserves
+`bodyInset` at its end as a spacer inside itself, so a list's rows run under
+the footer or the band and its last row can still be scrolled clear of them.
+`bodyClip` is what of that may show: without a footer all of it, so a sheet
+slides as one body; under a footer only what is above the footer's live top
+edge — `height − kb − handle − footerHeight`, which is `footerTop − handle` —
+so while the sheet is dragged below its detent and the footer holds the
+screen's bottom edge, no line of the body is drawn under it. On the detent the
+clip is exactly `contentArea`. A scrollable's `contentHeight` is
+`scrollContentHeight(contentSize, spacer)`: the spacer is the footer and the
+band, which `dynamicDetent` adds once already.
+
+Two deviations from the plan's signatures, both on purpose:
+
+- `resolveIntent` returns `{ action } | null` rather than `number | null`,
+  because `forceClose` needs a jump the caller can tell from an animate, and
+  an open before layout needs a *wait* the caller can tell from a no-op.
+- `crossedDetent` returns a boolean and `detentUnder` the index, rather than
+  one function doing both — a number that means "unchanged" when it equals its
+  input is a comparison the caller has to make anyway, spelled worse.
+
+## Design
+
+- **Pure means testable, and testable is the point.** `bun test` cannot render
+  a React Native component, so anything worth asserting has to live here. A
+  decision that looks like it belongs in a `.tsx` because it is only used once
+  is only used once *today*. Put it here.
+
+- **A `"worklet"` directive is a string, not an import.** It costs a module
+  nothing in purity, which is how the per-frame maths stays testable while
+  running on the UI thread.
+
+- **Enums are numbers.** A shared value holding a string serialises on every
+  write, and `gestureSource` is written every frame of a pan.
+
+- **A degenerate input returns a finite number, never `NaN`.** One `NaN`
+  written into `base` freezes a sheet permanently, with nothing on screen to
+  say why.
+
+## Machine
+
+`machine/` is the typed multi-step engine `BottomSheet.Steps` runs on, and it
+is deliberately nothing more than a config and a reducer.
+
+| Path | What |
+| --- | --- |
+| `machine/machine.types.ts` | `SheetMachineConfig`, `SheetStateNode`, `SheetMachineSnapshot`, `SheetTransitionError`, `SheetMachine` |
+| `machine/transition.ts` | `transition(states, snapshot, event)` — the one step, as a `Result` |
+| `machine/define-sheet-machine.ts` | `defineSheetMachine(config)` — `initial`, `transition`, `can`, `steps`, `directionOf`, `nodeOf` |
+| `machine/step-transition.ts` | `stepFrame(transition, role, direction, progress, width)` — the opacity and offset of a step mid-change, for `crossfade` / `slide` / `none`; `stepOverride(node)` — the `snapPoints` / `dismissible` a step asks of the root |
+
+- **A snapshot is a value.** `{ value, context, history }` in, a new one out;
+  `assign` returns a fresh context and the incoming snapshot is never touched.
+  That is what makes `useSheetMachine` a `useReducer` and lets a test replay a
+  whole form in three lines.
+- **A refusal is data.** `transition` returns `err({ code: "no-transition" })`
+  or `err({ code: "guard-rejected", from, to })` rather than throwing, and
+  `can` is just `transition(...).success` — which is how a Next button is
+  disabled while a guard says no.
+- **A self-target edits in place.** `EDIT: { target: "details", assign }`
+  keeps `value`, updates `context` and does not push `history`; only a change
+  of step appends the step it left.
+- **`steps` is declaration order**, and `directionOf(from, to)` reads the
+  target's explicit `direction` first, else compares indices. Per-step
+  `snapPoints` and `dismissible` are surfaced untouched through `nodeOf` for
+  the nested config override in `steps/`.
+- **`on` narrows per event type.** The handler under `on.EDIT` sees
+  `Extract<E, { type: "EDIT" }>`, so `assign` can read `event.field` without a
+  cast. `transition.ts` widens back to `E` once, at dispatch, where the type
+  has already chosen the handler.
+- **Anything with the same shape may stand in.** An XState adapter is any
+  object satisfying `SheetMachine`; nothing here is checked by identity.

package/src/core/animation/select-animation.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+import { ANDROID_TIMING, IOS_SPRING, selectAnimation } from "./select-animation";
+
+describe("selectAnimation", () => {
+	test("iOS defaults to the house spring, reduce motion following the system", () => {
+		expect(selectAnimation(undefined, "ios", undefined)).toEqual({ ...IOS_SPRING, reduceMotion: "system" });
+		expect(IOS_SPRING).toEqual({
+			type: "spring",
+			damping: 500,
+			stiffness: 1000,
+			mass: 3,
+			overshootClamping: true,
+			restDisplacementThreshold: 10,
+			restSpeedThreshold: 10,
+		});
+	});
+
+	test("Android defaults to a 250ms timing with an exponential ease-out, named not imported", () => {
+		expect(selectAnimation(undefined, "android", undefined)).toEqual({ ...ANDROID_TIMING, reduceMotion: "system" });
+		expect(ANDROID_TIMING).toEqual({ type: "timing", duration: 250, easing: "outExp" });
+	});
+
+	test("any other platform takes the timing — a spring with no native driver is the worse guess", () => {
+		expect(selectAnimation(undefined, "web", undefined).type).toBe("timing");
+	});
+
+	test("a partial spring fills in the house defaults", () => {
+		expect(selectAnimation({ type: "spring", damping: 30 }, "android", undefined)).toEqual({
+			...IOS_SPRING,
+			damping: 30,
+			reduceMotion: "system",
+		});
+	});
+
+	test("a partial timing fills in the house defaults", () => {
+		expect(selectAnimation({ type: "timing", easing: "linear" }, "ios", undefined)).toEqual({
+			type: "timing",
+			duration: 250,
+			easing: "linear",
+			reduceMotion: "system",
+		});
+	});
+
+	test("overrideReduceMotion wins over the system setting", () => {
+		expect(selectAnimation(undefined, "ios", "never").reduceMotion).toBe("never");
+		expect(selectAnimation({ type: "timing" }, "ios", "always").reduceMotion).toBe("always");
+	});
+
+	test("a config's own reduceMotion is kept unless overridden", () => {
+		expect(selectAnimation({ type: "spring", reduceMotion: "never" }, "ios", undefined).reduceMotion).toBe("never");
+		expect(selectAnimation({ type: "spring", reduceMotion: "never" }, "ios", "always").reduceMotion).toBe("always");
+	});
+
+	test("returns a fresh object each time, so a caller may mutate the velocity in", () => {
+		expect(selectAnimation(undefined, "ios", undefined)).not.toBe(selectAnimation(undefined, "ios", undefined));
+	});
+});

package/src/core/animation/select-animation.ts

@@ -0,0 +1,104 @@
+/**
+ * An easing by name. `src/animation` maps each to a Reanimated `Easing`; the
+ * core never imports one, so the defaults stay plain data and testable.
+ */
+export type EasingName = "linear" | "outExp" | "outCubic" | "inOutCubic";
+
+/** Reanimated's `ReduceMotion`, by name for the same reason. */
+export type ReduceMotionMode = "system" | "always" | "never";
+
+/** `Platform.OS`, widened so the core does not import it. */
+export type PlatformName = "ios" | "android" | "web" | "windows" | "macos" | (string & {});
+
+/** The `animation` prop: a spring or a timing, every field optional. */
+export type SheetAnimationConfig =
+	| {
+			type: "spring";
+			damping?: number;
+			stiffness?: number;
+			mass?: number;
+			overshootClamping?: boolean;
+			restDisplacementThreshold?: number;
+			restSpeedThreshold?: number;
+			reduceMotion?: ReduceMotionMode;
+	  }
+	| {
+			type: "timing";
+			duration?: number;
+			easing?: EasingName;
+			reduceMotion?: ReduceMotionMode;
+	  };
+
+/** A config with every field filled, ready for `withSpring` / `withTiming`. */
+export type ResolvedAnimation =
+	| {
+			type: "spring";
+			damping: number;
+			stiffness: number;
+			mass: number;
+			overshootClamping: boolean;
+			restDisplacementThreshold: number;
+			restSpeedThreshold: number;
+			reduceMotion: ReduceMotionMode;
+	  }
+	| {
+			type: "timing";
+			duration: number;
+			easing: EasingName;
+			reduceMotion: ReduceMotionMode;
+	  };
+
+/** The iOS default — a stiff, over-damped spring that settles in about a frame's worth of frames. */
+export const IOS_SPRING = {
+	type: "spring",
+	damping: 500,
+	stiffness: 1000,
+	mass: 3,
+	overshootClamping: true,
+	restDisplacementThreshold: 10,
+	restSpeedThreshold: 10,
+} as const satisfies Omit<Extract<ResolvedAnimation, { type: "spring" }>, "reduceMotion">;
+
+/** The Android default — 250ms with an exponential ease-out. */
+export const ANDROID_TIMING = {
+	type: "timing",
+	duration: 250,
+	easing: "outExp",
+} as const satisfies Omit<Extract<ResolvedAnimation, { type: "timing" }>, "reduceMotion">;
+
+/**
+ * The animation a sheet moves with: the consumer's config over the platform
+ * default, every field filled in, reduce motion resolved.
+ *
+ * iOS gets the spring and everything else the timing — a spring is the worse
+ * guess wherever there is no native driver tuned for it. `overrideReduceMotion`
+ * beats the config's own `reduceMotion`, which beats `"system"`. Returns a new
+ * object each call so the caller may write a velocity into it.
+ */
+export function selectAnimation(
+	config: SheetAnimationConfig | undefined,
+	platform: PlatformName,
+	overrideReduceMotion: ReduceMotionMode | undefined
+): ResolvedAnimation {
+	const reduceMotion = overrideReduceMotion ?? config?.reduceMotion ?? "system";
+	const resolved: SheetAnimationConfig = config ?? (platform === "ios" ? IOS_SPRING : ANDROID_TIMING);
+
+	if (resolved.type === "spring") {
+		return {
+			type: "spring",
+			damping: resolved.damping ?? IOS_SPRING.damping,
+			stiffness: resolved.stiffness ?? IOS_SPRING.stiffness,
+			mass: resolved.mass ?? IOS_SPRING.mass,
+			overshootClamping: resolved.overshootClamping ?? IOS_SPRING.overshootClamping,
+			restDisplacementThreshold: resolved.restDisplacementThreshold ?? IOS_SPRING.restDisplacementThreshold,
+			restSpeedThreshold: resolved.restSpeedThreshold ?? IOS_SPRING.restSpeedThreshold,
+			reduceMotion,
+		};
+	}
+	return {
+		type: "timing",
+		duration: resolved.duration ?? ANDROID_TIMING.duration,
+		easing: resolved.easing ?? ANDROID_TIMING.easing,
+		reduceMotion,
+	};
+}

package/src/core/backdrop/backdrop-opacity.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "bun:test";
+import { backdropInteractive, backdropOpacity } from "./backdrop-opacity";
+
+describe("backdropOpacity", () => {
+	test("closed is transparent, the appearing index is fully opaque", () => {
+		expect(backdropOpacity(-1, -1, 0, 1)).toBe(0);
+		expect(backdropOpacity(0, -1, 0, 1)).toBe(1);
+	});
+
+	test("fades in between the disappearing and appearing indices", () => {
+		expect(backdropOpacity(-0.5, -1, 0, 1)).toBeCloseTo(0.5);
+		expect(backdropOpacity(-0.25, -1, 0, 0.6)).toBeCloseTo(0.45);
+	});
+
+	test("plateaus above the appearing index — a higher detent is no darker", () => {
+		expect(backdropOpacity(1, -1, 0, 1)).toBe(1);
+		expect(backdropOpacity(2.5, -1, 0, 0.7)).toBe(0.7);
+	});
+
+	test("stays transparent up to the disappearing index when it is above closed", () => {
+		expect(backdropOpacity(-1, 0, 1, 1)).toBe(0);
+		expect(backdropOpacity(0, 0, 1, 1)).toBe(0);
+		expect(backdropOpacity(0.5, 0, 1, 1)).toBeCloseTo(0.5);
+		expect(backdropOpacity(1, 0, 1, 1)).toBe(1);
+	});
+
+	test("an appearing index at or below the disappearing one is a step, not a division by zero", () => {
+		expect(backdropOpacity(-1, 0, 0, 1)).toBe(0);
+		expect(backdropOpacity(0, 0, 0, 1)).toBe(1);
+		expect(Number.isFinite(backdropOpacity(0, 1, 0, 1))).toBe(true);
+	});
+
+	test("an over-drag below closed never goes negative", () => {
+		expect(backdropOpacity(-1.3, -1, 0, 1)).toBe(0);
+	});
+});
+
+describe("backdropInteractive", () => {
+	test("the backdrop takes taps once the sheet is past the index it disappears at", () => {
+		expect(backdropInteractive(-1, -1)).toBe(false);
+		expect(backdropInteractive(-0.5, -1)).toBe(true);
+		expect(backdropInteractive(0, -1)).toBe(true);
+	});
+
+	test("with a higher disappearing index the lowest detent leaves the app tappable", () => {
+		expect(backdropInteractive(0, 0)).toBe(false);
+		expect(backdropInteractive(1, 0)).toBe(true);
+	});
+});

package/src/core/backdrop/backdrop-opacity.ts

@@ -0,0 +1,21 @@
+/**
+ * The overlay's opacity at an index: `0` up to `disappearsOn`, rising
+ * linearly to `opacity` at `appearsOn`, and a plateau above — a higher detent
+ * is no darker. Fed the keyboard-free index, so a keyboard lift never dims
+ * the app behind the sheet.
+ *
+ * `appearsOn ≤ disappearsOn` is a step at `appearsOn` rather than a division
+ * by zero.
+ */
+export function backdropOpacity(index: number, disappearsOn: number, appearsOn: number, opacity: number): number {
+	"worklet";
+	if (index >= appearsOn) return opacity;
+	if (index <= disappearsOn) return 0;
+	return ((index - disappearsOn) / (appearsOn - disappearsOn)) * opacity;
+}
+
+/** Whether the overlay should take taps — anywhere above the index it disappears at. */
+export function backdropInteractive(index: number, disappearsOn: number): boolean {
+	"worklet";
+	return index > disappearsOn;
+}

package/src/core/detents/dynamic-detent.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+import { dynamicDetent } from "./dynamic-detent";
+
+const measured = { handleHeight: 24, contentHeight: 300, footerContentHeight: 56, band: 34, available: 800 };
+
+describe("dynamicDetent", () => {
+	test("without a footer the sheet is handle, content and the safe-area band", () => {
+		expect(dynamicDetent({ ...measured, hasFooter: false })).toBe(24 + 300 + 34);
+	});
+
+	test("with a footer the footer content is included, and the band is counted once", () => {
+		expect(dynamicDetent({ ...measured, hasFooter: true })).toBe(24 + 300 + 56 + 34);
+	});
+
+	test("a detached sheet has no band, so it contributes nothing", () => {
+		expect(dynamicDetent({ ...measured, band: 0, hasFooter: true })).toBe(24 + 300 + 56);
+	});
+
+	test("never exceeds the available height", () => {
+		expect(dynamicDetent({ ...measured, contentHeight: 2000, hasFooter: true })).toBe(800);
+	});
+
+	test("maxDynamicContentSize caps below the available height", () => {
+		expect(dynamicDetent({ ...measured, contentHeight: 2000, hasFooter: false, maxDynamicContentSize: 500 })).toBe(500);
+	});
+
+	test("maxDynamicContentSize above the available height changes nothing", () => {
+		expect(dynamicDetent({ ...measured, contentHeight: 2000, hasFooter: false, maxDynamicContentSize: 5000 })).toBe(
+			800
+		);
+	});
+
+	test("unmeasured parts count as zero rather than pulling the sum negative", () => {
+		expect(dynamicDetent({ ...measured, handleHeight: -1, footerContentHeight: -1, hasFooter: true })).toBe(300 + 34);
+	});
+
+	test("an unmeasured container yields zero, never a negative height", () => {
+		expect(dynamicDetent({ ...measured, available: -1, hasFooter: false })).toBe(0);
+	});
+});