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

package/src/gesture/use-scroll-lock.ts

@@ -0,0 +1,162 @@
+import { useMemo } from "react";
+import type { Insets, NativeScrollEvent, NativeSyntheticEvent, ScrollViewProps } from "react-native";
+import {
+	type AnimatedRef,
+	type SharedValue,
+	scrollTo,
+	useAnimatedProps,
+	useAnimatedReaction,
+	useAnimatedScrollHandler,
+	useDerivedValue,
+} from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { GESTURE_SOURCE, scrollLockTarget, shouldLockScroll } from "../core";
+import type { ScrollableHandle } from "../scrollable/scrollable.types";
+import type { SheetGeometry, SheetSharedState } from "../state/state.types";
+
+export type ScrollLockOptions = {
+	/** The root's `enableContentPanningGesture`. Off, the list is never locked — nothing else could take the drag. */
+	enableContentPan: boolean;
+	/** The caller's `showsVerticalScrollIndicator`; shown only while unlocked. @default true */
+	showsVerticalScrollIndicator?: boolean;
+	/** The caller's `scrollIndicatorInsets`; `indicatorInset` is added to its `bottom`. */
+	scrollIndicatorInsets?: Insets;
+	/** What trails the body — the geometry's `bodyInset` — so the indicator ends above the footer or the band. */
+	indicatorInset?: SharedValue<number>;
+	/** The caller's `bounces`; on only while unlocked. @default true */
+	bounces?: boolean;
+	/** The caller's `decelerationRate`; `0` while locked. @default "normal" */
+	decelerationRate?: ScrollViewProps["decelerationRate"];
+	/** The caller's own scroll callbacks, called on the JS thread with the event the worklet saw. */
+	listeners?: ScrollListeners;
+};
+
+type ScrollListener = (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+
+export type ScrollListeners = Pick<
+	{ [K in keyof ScrollViewProps]?: ScrollListener },
+	"onScroll" | "onScrollBeginDrag" | "onScrollEndDrag" | "onMomentumScrollEnd"
+>;
+
+type ScrollLockProps = Pick<
+	ScrollViewProps,
+	"decelerationRate" | "showsVerticalScrollIndicator" | "bounces" | "scrollIndicatorInsets"
+>;
+
+export type ScrollLock = {
+	/** `true` while the sheet is below its highest detent: the list is held at `scrollLockedAt`. */
+	locked: SharedValue<boolean>;
+	/** For the list's `onScroll`. Tracks the offset into `scrollOffsetY` and enforces the lock. */
+	scrollHandler: ReturnType<typeof useAnimatedScrollHandler>;
+	/** For the list's `animatedProps`: deceleration, indicator and bounce, switched by the lock, and the indicator's inset. */
+	animatedProps: Partial<ScrollLockProps>;
+};
+
+/**
+ * The scroll lock: the UI-thread half of a scrollable body.
+ *
+ * Below the highest detent a drag on the list must move the sheet, not the
+ * rows. The content pan already does the moving — the native scroll and the
+ * pan are simultaneous — so this hook's job is to make sure the list does not
+ * *also* move: every scroll event while locked is answered with a `scrollTo`
+ * back to where the lock engaged, and the offset the pan reads is pinned
+ * there too, so the pan sees the list consume nothing.
+ *
+ * The lock engages when the sheet leaves its highest detent by any path — a
+ * drag, a `snapToIndex`, a keyboard — and takes the offset of that moment as
+ * its target. A list scrolled a hundred pixels, then collapsed by the handle,
+ * holds those hundred pixels rather than jumping to the top; when the sheet
+ * comes back up it continues from there.
+ *
+ * The animated props do the rest: `decelerationRate: 0` while locked so a
+ * fling has no momentum for the lock to fight, the indicator hidden so a
+ * pinned list does not flash a bar, and `bounces` off so a pull-down at the
+ * top rubber-bands the sheet and not the rows. The indicator's bottom inset
+ * follows `indicatorInset` — what the body reserves for the footer or the
+ * band — so the bar ends where the rows stop being visible.
+ */
+export function useScrollLock(
+	state: SheetSharedState,
+	geometry: SheetGeometry,
+	ref: AnimatedRef<ScrollableHandle>,
+	options: ScrollLockOptions
+): ScrollLock {
+	const {
+		enableContentPan,
+		showsVerticalScrollIndicator = true,
+		scrollIndicatorInsets,
+		indicatorInset,
+		bounces = true,
+		decelerationRate = "normal",
+		listeners,
+	} = options;
+	const onScroll = listeners?.onScroll;
+	const onScrollBeginDrag = listeners?.onScrollBeginDrag;
+	const onScrollEndDrag = listeners?.onScrollEndDrag;
+	const onMomentumScrollEnd = listeners?.onMomentumScrollEnd;
+	const { scrollOffsetY, scrollLockedAt } = state;
+	const sheetState = geometry.sheetState;
+
+	const locked = useDerivedValue(() => shouldLockScroll(sheetState.value, enableContentPan));
+
+	useAnimatedReaction(
+		() => locked.value,
+		(now, before) => {
+			if (now && before !== true) {
+				scrollLockedAt.value = scrollLockTarget(
+					scrollOffsetY.value,
+					state.gestureSource.value === GESTURE_SOURCE.CONTENT
+				);
+			}
+		}
+	);
+
+	const scrollHandler = useAnimatedScrollHandler(
+		useMemo(() => {
+			const track = (event: NativeScrollEvent, listener: ScrollListener | undefined): void => {
+				"worklet";
+				if (listener) scheduleOnRN(listener, { nativeEvent: event } as NativeSyntheticEvent<NativeScrollEvent>);
+				if (locked.value) {
+					const target = scrollLockedAt.value;
+					scrollTo(ref, 0, target, false);
+					scrollOffsetY.value = target;
+					return;
+				}
+				scrollOffsetY.value = event.contentOffset.y;
+			};
+			return {
+				onScroll: (event) => {
+					"worklet";
+					track(event, onScroll);
+				},
+				onBeginDrag: (event) => {
+					"worklet";
+					track(event, onScrollBeginDrag);
+				},
+				onEndDrag: (event) => {
+					"worklet";
+					track(event, onScrollEndDrag);
+				},
+				onMomentumEnd: (event) => {
+					"worklet";
+					track(event, onMomentumScrollEnd);
+				},
+			};
+		}, [locked, scrollLockedAt, scrollOffsetY, ref, onScroll, onScrollBeginDrag, onScrollEndDrag, onMomentumScrollEnd])
+	);
+
+	const indicatorBottom = scrollIndicatorInsets?.bottom ?? 0;
+	const animatedProps = useAnimatedProps<ScrollLockProps>(() => ({
+		decelerationRate: locked.value ? 0 : decelerationRate,
+		showsVerticalScrollIndicator: showsVerticalScrollIndicator && !locked.value,
+		bounces: bounces && !locked.value,
+		scrollIndicatorInsets: {
+			top: scrollIndicatorInsets?.top,
+			left: scrollIndicatorInsets?.left,
+			right: scrollIndicatorInsets?.right,
+			bottom: indicatorBottom + (indicatorInset ? indicatorInset.value : 0),
+		},
+	}));
+
+	return useMemo(() => ({ locked, scrollHandler, animatedProps }), [locked, scrollHandler, animatedProps]);
+}

package/src/gesture/use-sheet-pan.ts

@@ -0,0 +1,250 @@
+import { useMemo } from "react";
+import { Gesture, type GestureType, type PanGesture } from "react-native-gesture-handler";
+import { KeyboardController } from "react-native-keyboard-controller";
+import { cancelAnimation, useSharedValue } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import type { AnimateTo, SettleAt } from "../animation/animation.types";
+import {
+	crossedDetent,
+	detentUnder,
+	GESTURE_SOURCE,
+	type GestureSource,
+	listDragHeight,
+	listOwnsRelease,
+	resistOverDrag,
+	restingDetent,
+	SCROLLABLE_TYPE,
+	selectSnapHeight,
+} from "../core";
+import { ANIM_STATUS, type SheetGeometry, type SheetSharedState } from "../state/state.types";
+import {
+	CONTENT_ACTIVE_OFFSET_Y,
+	CONTENT_FAIL_OFFSET_X,
+	type SheetPanOptions,
+	type SheetPans,
+	SNAP_PROJECTION,
+} from "./gesture.types";
+
+type PanEvent = { translationY: number; velocityY: number };
+
+/** Settle tolerance: a sheet within this of a detent is on it. */
+const AT_DETENT = 0.5;
+
+/** JS-thread, so `scheduleOnRN` has a plain function to call; `dismiss` returns a promise nobody awaits. */
+function dismissKeyboard(): void {
+	void KeyboardController.dismiss();
+}
+
+/**
+ * The two pans — handle and content — sharing one set of handlers.
+ *
+ * Everything runs on the UI thread. `onStart` cancels whatever animation owns
+ * `base` and remembers where the drag began; `onChange` turns the finger's
+ * travel into a height, rubber-banded past the detents by `resistOverDrag`
+ * and never above the container; `onFinalize` picks the detent the finger was
+ * heading for with `selectSnapHeight` and hands it to `animateTo` with the
+ * release velocity. The close is a candidate only when `enablePanDownToClose`.
+ *
+ * A content pan the list owns at release — the sheet at its top, the list
+ * scrolled — does not snap, but it still settles: the finger moved `base` by
+ * hand, so no animation ran and nothing else writes `currentIndex`. `settleAt`
+ * on the detent under `base` is the bookkeeping of a finished animation
+ * without the motion; between detents (which the list ownership test should
+ * rule out) the sheet snaps to the nearest one with no velocity instead, since
+ * the release velocity is the list's momentum.
+ *
+ * The content pan waits six points of vertical travel before it claims a
+ * touch and gives up after twelve horizontal, so a tap lands on the button or
+ * the field under it and a horizontal pager inside the sheet keeps its swipe.
+ * The handle pan claims immediately — nothing under a grabber wants the touch.
+ *
+ * The handlers are built inside this `useMemo`, so they close over the core's
+ * worklets in the ordinary way. See the package `AGENTS.md`: that is legal
+ * precisely because these are not module-scope worklets.
+ *
+ * Per-gesture memory — where the drag began, the detent last under it,
+ * whether it is over-dragging — lives in shared values rather than closure
+ * variables. Each worklet gets its own copy of a captured `let`, so a write in
+ * `onStart` would never be seen by `onChange`.
+ */
+export function useSheetPan(
+	state: SheetSharedState,
+	geometry: SheetGeometry,
+	animateTo: AnimateTo,
+	settleAt: SettleAt,
+	options: SheetPanOptions
+): SheetPans {
+	const startBase = useSharedValue(0);
+	const lastDetent = useSharedValue(-1);
+	const overDragging = useSharedValue(false);
+	const startScroll = useSharedValue(0);
+	const listHeld = useSharedValue(false);
+	const { enableHandlePanningGesture, enableContentPanningGesture, onDetentHaptic, onCloseHaptic, onOverDragHaptic } =
+		options;
+
+	return useMemo(() => {
+		const begin = (source: GestureSource): void => {
+			"worklet";
+			cancelAnimation(state.base);
+			state.animStatus.value = ANIM_STATUS.IDLE;
+			state.gestureSource.value = source;
+			startBase.value = state.base.value;
+			startScroll.value = state.scrollOffsetY.value;
+			// A list scrolled and below the top is held by the lock: it has no travel
+			// to spend until the sheet reaches the highest detent.
+			listHeld.value = state.scrollOffsetY.value > 0 && state.base.value < geometry.highest.value - AT_DETENT;
+			lastDetent.value = detentUnder(state.base.value, geometry.detents.value);
+			overDragging.value = false;
+			// A finger on the sheet is a reason to put the keyboard away; the lift
+			// comes off as it goes and the drag continues from wherever `base` is.
+			if (state.config.value.enableBlurKeyboardOnGesture && state.keyboardProgress.value > 0) {
+				scheduleOnRN(dismissKeyboard);
+			}
+		};
+
+		const haptics = (raw: number, next: number, lowest: number, highest: number, detents: readonly number[]): void => {
+			"worklet";
+			const over = raw > highest || raw < lowest;
+			if (over && !overDragging.value && onOverDragHaptic) onOverDragHaptic();
+			overDragging.value = over;
+
+			if (crossedDetent(lastDetent.value, next, detents)) {
+				lastDetent.value = detentUnder(next, detents);
+				if (onDetentHaptic) onDetentHaptic();
+			}
+		};
+
+		// Whether this pan is a content pan over a registered scrollable.
+		const overList = (source: GestureSource): boolean => {
+			"worklet";
+			return source === GESTURE_SOURCE.CONTENT && state.scrollableType.value !== SCROLLABLE_TYPE.NONE;
+		};
+
+		// The finger's travel as a height. Over a list the offset the list began
+		// with is a budget spent before the sheet moves — see `listDragHeight`.
+		const dragged = (translationY: number, highest: number): number => {
+			"worklet";
+			if (!overList(state.gestureSource.value)) return startBase.value - translationY;
+			return listDragHeight({
+				startBase: startBase.value,
+				translationY,
+				startOffset: startScroll.value,
+				held: listHeld.value,
+				highest,
+			});
+		};
+
+		const move = (event: PanEvent): void => {
+			"worklet";
+			if (state.gestureSource.value === GESTURE_SOURCE.NONE) return;
+			const config = state.config.value;
+			const detents = geometry.detents.value;
+			const closed = geometry.closedHeight.value;
+			const highest = geometry.highest.value;
+			const raw = dragged(event.translationY, highest);
+
+			const lowest = config.enablePanDownToClose || detents.length === 0 ? closed : (detents[0] as number);
+			const factor = config.enableOverDrag ? config.overDragResistanceFactor : 0;
+			const next = Math.min(resistOverDrag(raw, lowest, highest, factor), geometry.maxHeight.value);
+
+			haptics(raw, next, lowest, highest, detents);
+			state.base.value = next;
+			if (listHeld.value && next >= highest - AT_DETENT) listHeld.value = false;
+		};
+
+		// The haptic for a close, the keyboard for a downward release — a release
+		// heading down under an open keyboard puts the keyboard away whatever
+		// `enableBlurKeyboardOnGesture` says — then the animation.
+		const settle = (target: number, closed: number, velocity: number): void => {
+			"worklet";
+			if (target <= closed && onCloseHaptic) onCloseHaptic();
+			if (target < startBase.value && state.keyboardProgress.value > 0) scheduleOnRN(dismissKeyboard);
+			animateTo(target, "gesture", velocity / 2);
+		};
+
+		// A release the list owns settles the sheet on the detent under `base`
+		// with no motion; `false` when it sits between detents and has to snap.
+		const settleResting = (): boolean => {
+			"worklet";
+			const resting = restingDetent(state.base.value, geometry.detents.value);
+			if (resting === null) return false;
+			settleAt(resting, "gesture");
+			return true;
+		};
+
+		const release = (event: PanEvent): void => {
+			"worklet";
+			if (state.gestureSource.value === GESTURE_SOURCE.NONE) return;
+			const source = state.gestureSource.value;
+			state.gestureSource.value = GESTURE_SOURCE.NONE;
+			const config = state.config.value;
+			const closed = geometry.closedHeight.value;
+
+			// The finger was scrolling rows at the top detent: the release is the
+			// list's momentum, not a snap — but the sheet still settles where it is.
+			const listOwns = listOwnsRelease({
+				scrollable: overList(source),
+				offset: state.scrollOffsetY.value,
+				base: state.base.value,
+				highest: geometry.highest.value,
+			});
+			if (listOwns && settleResting()) return;
+
+			// A list-owned release between detents (which `listOwnsRelease` should
+			// rule out) snaps to the nearest with no velocity and never closes.
+			const velocity = listOwns ? 0 : -event.velocityY;
+			const target = selectSnapHeight({
+				height: state.base.value,
+				velocity,
+				detents: geometry.detents.value,
+				closedHeight: config.enablePanDownToClose && !listOwns ? closed : null,
+				projection: SNAP_PROJECTION,
+			});
+
+			settle(target, closed, velocity);
+		};
+
+		const attach = (pan: PanGesture, source: GestureSource, enabled: boolean): GestureType =>
+			pan
+				.enabled(enabled)
+				.shouldCancelWhenOutside(false)
+				.onStart(() => {
+					"worklet";
+					begin(source);
+				})
+				.onChange((event) => {
+					"worklet";
+					move(event);
+				})
+				.onFinalize((event) => {
+					"worklet";
+					release(event);
+				});
+
+		const handle = attach(Gesture.Pan(), GESTURE_SOURCE.HANDLE, enableHandlePanningGesture);
+		const content = attach(
+			Gesture.Pan()
+				.activeOffsetY([-CONTENT_ACTIVE_OFFSET_Y, CONTENT_ACTIVE_OFFSET_Y])
+				.failOffsetX([-CONTENT_FAIL_OFFSET_X, CONTENT_FAIL_OFFSET_X]),
+			GESTURE_SOURCE.CONTENT,
+			enableContentPanningGesture
+		);
+
+		return { handle, content };
+	}, [
+		state,
+		geometry,
+		animateTo,
+		settleAt,
+		startBase,
+		startScroll,
+		listHeld,
+		lastDetent,
+		overDragging,
+		enableHandlePanningGesture,
+		enableContentPanningGesture,
+		onDetentHaptic,
+		onCloseHaptic,
+		onOverDragHaptic,
+	]);
+}

package/src/index.ts

@@ -0,0 +1,127 @@
+export type { AnimateListener, AnimateTo, JumpTo, SettleListener, SheetAnimation } from "./animation/animation.types";
+export { easingFor, reduceMotionFor, toReanimated } from "./animation/resolve-animation";
+export { useAnimateTo } from "./animation/use-animate-to";
+export { BottomSheet } from "./components/bottom-sheet";
+export {
+	BottomSheetAnimatedContext,
+	BottomSheetContext,
+	BottomSheetInternalContext,
+	type BottomSheetInternalValue,
+	type ContentHeightSource,
+	useBottomSheet,
+	useBottomSheetAnimated,
+	useBottomSheetInternal,
+	useOptionalBottomSheet,
+	useOptionalBottomSheetAnimated,
+	useOptionalBottomSheetInternal,
+} from "./components/bottom-sheet.context";
+export type {
+	BottomSheetAnimatedValue,
+	BottomSheetBackgroundProps,
+	BottomSheetCloseProps,
+	BottomSheetContainerProps,
+	BottomSheetContentProps,
+	BottomSheetContextValue,
+	BottomSheetDescriptionProps,
+	BottomSheetFooterProps,
+	BottomSheetHandleProps,
+	BottomSheetOverlayProps,
+	BottomSheetPortalProps,
+	BottomSheetProps,
+	BottomSheetRef,
+	BottomSheetTextInputProps,
+	BottomSheetTitleProps,
+	BottomSheetTriggerProps,
+} from "./components/bottom-sheet.types";
+export * from "./core";
+export type { HapticWorklet, SheetHaptics, SheetPanOptions, SheetPans } from "./gesture/gesture.types";
+export {
+	type ScrollListeners,
+	type ScrollLock,
+	type ScrollLockOptions,
+	useScrollLock,
+} from "./gesture/use-scroll-lock";
+export { useSheetPan } from "./gesture/use-sheet-pan";
+export { type BottomSheetTextInputHandlers, useBottomSheetTextInput } from "./keyboard/use-bottom-sheet-text-input";
+export {
+	type KeyboardAnimationValues,
+	reconcileKeyboardAnimation,
+	useKeyboardAnimationGuard,
+} from "./keyboard/use-keyboard-animation-guard";
+export {
+	type SheetKeyboardRegistry,
+	type UseSheetKeyboardOptions,
+	useSheetKeyboard,
+} from "./keyboard/use-sheet-keyboard";
+export { type ContainerLayout, useContainerLayout } from "./layout/use-container-layout";
+export { useMeasureHeight } from "./layout/use-measure-height";
+export { Slot } from "./lib/slot";
+export { useControllableState } from "./lib/use-controllable-state";
+export { BottomSheetHost, type BottomSheetHostProps } from "./portal/bottom-sheet-host";
+export { BottomSheetProvider, type BottomSheetProviderProps } from "./portal/bottom-sheet-provider";
+export { useBottomSheetHostName, useOptionalBottomSheetHostName } from "./portal/host.context";
+export {
+	INITIAL_REGISTRY,
+	isTop,
+	reduceRegistry,
+	type SheetRegistryAction,
+	type SheetRegistryEntry,
+	type SheetRegistryResult,
+	type SheetRegistryState,
+	type StackBehavior,
+	topOf,
+	zIndexOf,
+} from "./portal/sheet-registry";
+export {
+	type BottomSheetRegistryValue,
+	useBottomSheetRegistry,
+	useOptionalBottomSheetRegistry,
+} from "./portal/sheet-registry.context";
+export { BottomSheetFlatList } from "./scrollable/bottom-sheet-flat-list";
+export { BottomSheetScrollView } from "./scrollable/bottom-sheet-scroll-view";
+export { BottomSheetSectionList } from "./scrollable/bottom-sheet-section-list";
+export { createBottomSheetScrollable } from "./scrollable/create-bottom-sheet-scrollable";
+export type {
+	BottomSheetFlatListComponent,
+	BottomSheetFlatListProps,
+	BottomSheetScrollableProps,
+	BottomSheetScrollViewComponent,
+	BottomSheetScrollViewProps,
+	BottomSheetSectionListComponent,
+	BottomSheetSectionListProps,
+	FocusHook,
+	ScrollableHandle,
+	ScrollableInnerComponent,
+	ScrollableInnerProps,
+} from "./scrollable/scrollable.types";
+export {
+	ANIM_STATUS,
+	type AnimStatus,
+	type SheetGeometry,
+	type SheetSharedState,
+	type SheetWorkletConfig,
+} from "./state/state.types";
+export { useSheetGeometry } from "./state/use-sheet-geometry";
+export {
+	type IntentRequest,
+	type SheetIntentDispatch,
+	type SheetIntents,
+	useSheetIntents,
+} from "./state/use-sheet-intents";
+export { useSheetState } from "./state/use-sheet-state";
+export { BottomSheetStep } from "./steps/bottom-sheet-step";
+export { BottomSheetSteps } from "./steps/bottom-sheet-steps";
+export {
+	SheetStepContext,
+	type StepsLayoutValue,
+	useOptionalStepsLayout,
+	useStepsLayout,
+} from "./steps/steps.context";
+export type {
+	BottomSheetStepProps,
+	BottomSheetStepsProps,
+	SheetStepController,
+	UseSheetMachineOptions,
+} from "./steps/steps.types";
+export { useSheetMachine } from "./steps/use-sheet-machine";
+export { useOptionalSheetStep, useSheetStep } from "./steps/use-sheet-step";

package/src/keyboard/AGENTS.md

@@ -0,0 +1,84 @@
+# keyboard
+
+keyboard-controller's shared values, turned into the sheet's; which keyboard
+is the sheet's to answer; and what each `keyboardBehavior` does about it.
+
+## Files
+
+| Path | What |
+| --- | --- |
+| `use-sheet-keyboard.ts` | The writer reaction (`keyboardHeight`, `keyboardProgress`, `keyboardOwned`) and the behaviour reaction (`extend` / `fillParent` snaps, `restore`); returns the registry `useBottomSheetTextInput` writes into |
+| `use-bottom-sheet-text-input.ts` | `useBottomSheetTextInput()` → `{ ref, onFocus, onBlur }`, the explicit registration; inert outside a sheet |
+| `use-keyboard-animation-guard.ts` | `useKeyboardAnimationGuard` and `reconcileKeyboardAnimation` — the stale-keyboard repair over `core/keyboard/keyboard-reset-guard` |
+
+The decisions are in `core/keyboard/`: `resolveKeyboardOwner` (who owns it),
+`keyboardStep` (what a behaviour does this frame), `keyboardInContainer`,
+`keyboardLift`, `contentArea`, `isInputInsideSheet`. Nothing here contains a
+rule; it samples shared values and carries out what the core returns.
+
+## Source
+
+`useKeyboardContext().reanimated` — `height` is **negative**, pixels from the
+window's bottom edge; `progress` runs 0 to 1 and tracks an interactive
+dismiss frame by frame. `useReanimatedFocusedInput().input` is the focused
+field's frame, `null` between a blur and the next focus. All three are
+UI-thread shared values, which is why every reaction here is a
+`useAnimatedReaction` and nothing crosses to JS.
+
+`keyboardInContainer` subtracts `containerBottomOffset` — a frame that ends
+above the window's bottom is overlapped by that much less — and the result
+is the positive `keyboardHeight` the geometry reads.
+
+## Ownership
+
+`keyboardScope` picks the rule. `registered`: only a field that went through
+`useBottomSheetTextInput` or `BottomSheet.TextInput`. `inside` (the default):
+those, plus any focused input whose frame overlaps the sheet — the frame
+comes from keyboard-controller, the sheet's top from `position`, and
+`isInputInsideSheet` compares them in window space. `always`: every keyboard.
+
+Ownership is **sticky through a transition**. The focused-input frame can
+land a frame after `progress` starts, and it goes null the moment a field
+blurs while the keyboard takes another quarter second to leave; without
+stickiness the sheet would drop by the lift and chase the keyboard down. A
+different focused input releases at once — that keyboard is someone else's
+— and so does `progress` reaching zero. `resolveKeyboardOwner` is the rule,
+with its tests.
+
+The registration path is the reliable one. `ref` records the field's native
+node, `onFocus` claims, and `onBlur` releases unless React Native's own focus
+registry says another registered field already has focus — the check that
+stops a tap from one field to the next reading as a close and a reopen.
+
+## Behaviours
+
+| `keyboardBehavior` | On show | `keyboardBlurBehavior: "restore"` on hide |
+| --- | --- | --- |
+| `interactive` (default) | Nothing — `keyboardLift` is a derivation over `progress`, so the sheet rides the keyboard up and follows an interactive dismiss down | Nothing to restore; `base` never moved |
+| `extend` | `animateTo(highest, "keyboard")` | Back to the detent held before |
+| `fillParent` | `animateTo(maxHeight, "keyboard")`; no lift; the body shrinks by the keyboard | Back to the detent held before |
+| `none` | Nothing; the keyboard is not the sheet's problem | Nothing |
+
+The behaviour reaction samples `progress` and `keyboardOwned` and hands two
+consecutive samples to `keyboardStep`, which answers `apply`, `restore`,
+`release` or nothing. A rise applies once; a fall restores once; an
+interactive dismiss that turns back mid-way applies again. A finger on the
+sheet owns `base`, so neither runs while a gesture is active — the release
+settles wherever the finger left it.
+
+`enableBlurKeyboardOnGesture` (default on) dismisses the keyboard the moment
+a pan starts, and a pan that ends heading down dismisses it regardless; both
+live in `gesture/use-sheet-pan.ts`, through `KeyboardController.dismiss` on
+the JS thread.
+
+## The stale-keyboard guard
+
+On iOS `KeyboardProvider` writes its shared values on `keyboardWillShow` /
+`keyboardWillHide` and nothing else, so a teardown that produces no
+`willHide` — a native-stack pop over a focused field, an app suspend —
+leaves them pinned open app-wide, and a sheet mounted into that would lift
+for a keyboard that is not there. `reconcileKeyboardAnimation` snaps them to
+closed when React Native's focus registry says nothing is focused; the sheet
+runs it on every presentation, and `useKeyboardAnimationGuard` is the same
+thing for a screen of your own. Same decision as `@delacour/react-native-ui`'s
+guard, over the same core function, so the two never disagree.