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

package/src/core/index.ts

@@ -0,0 +1,92 @@
+export {
+	ANDROID_TIMING,
+	type EasingName,
+	IOS_SPRING,
+	type PlatformName,
+	type ReduceMotionMode,
+	type ResolvedAnimation,
+	type SheetAnimationConfig,
+	selectAnimation,
+} from "./animation/select-animation";
+export { backdropInteractive, backdropOpacity } from "./backdrop/backdrop-opacity";
+export { type DynamicDetentInput, dynamicDetent } from "./detents/dynamic-detent";
+export { heightForIndex, indexForHeight } from "./detents/index-for-height";
+export { type DetentError, normalizeDetents, type ParsedDetent, parseDetent } from "./detents/normalize-detents";
+export { resistOverDrag } from "./detents/over-drag";
+export { type SelectSnapHeightInput, selectSnapHeight } from "./detents/select-snap-height";
+export { sheetState } from "./detents/sheet-state";
+export { type BodyClipInput, bodyClip, bodyInset, scrollContentHeight } from "./footer/body-inset";
+export { bandNow, bottomBand, footerHeight } from "./footer/bottom-band";
+export { type FooterTopInput, footerTop } from "./footer/footer-top";
+export { resolveSheetBottomInset, resolveSheetScrollEndPadding } from "./footer/sheet-insets";
+export { clampHeight } from "./geometry/clamp-height";
+export { availableHeight, closedHeight, restingBottom } from "./geometry/closed-height";
+export {
+	DETACHED_DEFAULTS,
+	type DetachedFrame,
+	type DetachedFrameInput,
+	type DetachedOptions,
+	type DetachedProp,
+	detachedFrame,
+	resolveDetached,
+} from "./geometry/detached-frame";
+export { positionFor } from "./geometry/position";
+export { surfaceHeight } from "./geometry/surface-height";
+export { crossedDetent, detentUnder } from "./haptic/crossed-detent";
+export { isLayoutReady, type LayoutReadyInput } from "./intent/layout-ready";
+export { type IntentResolution, type IntentState, resolveIntent } from "./intent/resolve-intent";
+export { acceptContainerLayout, type ContainerLayoutInput } from "./keyboard/container-layout-guard";
+export { type ContentAreaInput, contentArea } from "./keyboard/content-area";
+export { type KeyboardLiftInput, keyboardInContainer, keyboardLift } from "./keyboard/keyboard-lift";
+export { type InputInsideSheetInput, isInputInsideSheet } from "./keyboard/keyboard-owner";
+export { type KeyboardOwnerInput, resolveKeyboardOwner } from "./keyboard/keyboard-ownership";
+export { type KeyboardAnimationState, shouldResetKeyboardAnimation } from "./keyboard/keyboard-reset-guard";
+export { type KeyboardStep, type KeyboardStepInput, keyboardStep } from "./keyboard/keyboard-step";
+export {
+	defineSheetMachine,
+	resolveTarget,
+	type SheetEvent,
+	type SheetMachine,
+	type SheetMachineConfig,
+	type SheetMachineSnapshot,
+	type SheetStateNode,
+	type SheetStates,
+	type SheetStepDirection,
+	type SheetStepFrame,
+	type SheetStepOverride,
+	type SheetStepRole,
+	type SheetStepTransition,
+	type SheetTransitionError,
+	type SheetTransitionObject,
+	type SheetTransitionResult,
+	type SheetTransitionTarget,
+	stepFrame,
+	stepOverride,
+	transition,
+} from "./machine";
+export { type ErrorResult, err, ok, type Result, type SuccessResult } from "./result";
+export { type ContentPanInput, contentPanDrivesSheet, shouldLockScroll } from "./scroll/scroll-lock";
+export {
+	type ListDragInput,
+	type ListOwnsReleaseInput,
+	listDragHeight,
+	listOwnsRelease,
+	restingDetent,
+	scrollLockTarget,
+} from "./scroll/scroll-pan";
+export {
+	type AnimationSource,
+	CLOSED_INDEX,
+	type DetentSpec,
+	GESTURE_SOURCE,
+	type GestureSource,
+	type KeyboardBehavior,
+	type KeyboardBlurBehavior,
+	type KeyboardScope,
+	SCROLLABLE_TYPE,
+	type ScrollableType,
+	SHEET_STATE,
+	type SheetIntent,
+	type SheetState,
+	UNMEASURED,
+} from "./sheet.types";

package/src/core/intent/layout-ready.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { isLayoutReady } from "./layout-ready";
+
+const measured = {
+	containerHeight: 800,
+	handleHeight: 24,
+	contentHeight: 300,
+	footerContentHeight: 56,
+	dynamicSizing: true,
+	hasFooter: true,
+};
+
+describe("isLayoutReady", () => {
+	test("ready once every measurement the configuration needs has landed", () => {
+		expect(isLayoutReady(measured)).toBe(true);
+	});
+
+	test("never ready without a container", () => {
+		expect(isLayoutReady({ ...measured, containerHeight: -1 })).toBe(false);
+		expect(isLayoutReady({ ...measured, containerHeight: 0 })).toBe(false);
+	});
+
+	test("waits for the handle — a zero-height handle counts as measured", () => {
+		expect(isLayoutReady({ ...measured, handleHeight: -1 })).toBe(false);
+		expect(isLayoutReady({ ...measured, handleHeight: 0 })).toBe(true);
+	});
+
+	test("waits for content only when sizing to it", () => {
+		expect(isLayoutReady({ ...measured, contentHeight: -1 })).toBe(false);
+		expect(isLayoutReady({ ...measured, contentHeight: -1, dynamicSizing: false })).toBe(true);
+	});
+
+	test("waits for the footer only when there is one", () => {
+		expect(isLayoutReady({ ...measured, footerContentHeight: -1 })).toBe(false);
+		expect(isLayoutReady({ ...measured, footerContentHeight: -1, hasFooter: false })).toBe(true);
+	});
+});

package/src/core/intent/layout-ready.ts

@@ -0,0 +1,24 @@
+export type LayoutReadyInput = {
+	containerHeight: number;
+	handleHeight: number;
+	contentHeight: number;
+	footerContentHeight: number;
+	/** Whether the content's height is a detent, and so has to be known. */
+	dynamicSizing: boolean;
+	hasFooter: boolean;
+};
+
+/**
+ * Whether every measurement this configuration needs has landed, which is
+ * what an open intent waits on. The container must be real; the handle must
+ * have reported (zero is a report); content only matters when the sheet sizes
+ * to it, and the footer only when there is one.
+ */
+export function isLayoutReady(input: LayoutReadyInput): boolean {
+	"worklet";
+	if (!(input.containerHeight > 0)) return false;
+	if (input.handleHeight < 0) return false;
+	if (input.dynamicSizing && input.contentHeight < 0) return false;
+	if (input.hasFooter && input.footerContentHeight < 0) return false;
+	return true;
+}

package/src/core/intent/resolve-intent.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, test } from "bun:test";
+import type { SheetIntent } from "../sheet.types";
+import { type IntentState, resolveIntent } from "./resolve-intent";
+
+const ready: IntentState = {
+	currentIndex: -1,
+	base: 0,
+	layoutReady: true,
+	detents: [200, 400, 800],
+	closedHeight: 0,
+	maxHeight: 800,
+	initialIndex: 0,
+};
+const open: IntentState = { ...ready, currentIndex: 1, base: 400 };
+/** A sheet visibly open whose settled index never caught up — a release the list owned. */
+const staleClosed: IntentState = { ...ready, currentIndex: -1, base: 800 };
+const unmeasured: IntentState = { ...ready, layoutReady: false, detents: [] };
+
+const intent = (kind: SheetIntent["kind"], extra: Record<string, unknown> = {}): SheetIntent =>
+	({ id: 1, kind, ...extra }) as SheetIntent;
+
+describe("resolveIntent", () => {
+	describe("open", () => {
+		test("animates a closed sheet to its initial index", () => {
+			expect(resolveIntent(ready, intent("open"))).toEqual({ action: "animate", target: 200 });
+			expect(resolveIntent({ ...ready, initialIndex: 2 }, intent("open"))).toEqual({ action: "animate", target: 800 });
+		});
+
+		test("an initial index past the last detent lands on the last", () => {
+			expect(resolveIntent({ ...ready, initialIndex: 9 }, intent("open"))).toEqual({ action: "animate", target: 800 });
+		});
+
+		test("waits for layout rather than animating from a guess", () => {
+			expect(resolveIntent(unmeasured, intent("open"))).toEqual({ action: "wait" });
+		});
+
+		test("is a no-op on a sheet that is already open", () => {
+			expect(resolveIntent(open, intent("open"))).toBeNull();
+			expect(resolveIntent(staleClosed, intent("open"))).toBeNull();
+		});
+
+		test("with nothing to open to there is nothing to do", () => {
+			expect(resolveIntent({ ...ready, detents: [] }, intent("open"))).toBeNull();
+		});
+	});
+
+	describe("close", () => {
+		test("animates an open sheet to its closed height", () => {
+			expect(resolveIntent(open, intent("close"))).toEqual({ action: "animate", target: 0 });
+			expect(resolveIntent({ ...open, closedHeight: -50 }, intent("close"))).toEqual({
+				action: "animate",
+				target: -50,
+			});
+		});
+
+		test("a visibly open sheet closes even when its settled index still says closed", () => {
+			expect(resolveIntent(staleClosed, intent("close"))).toEqual({ action: "animate", target: 0 });
+			expect(resolveIntent(staleClosed, intent("forceClose"))).toEqual({ action: "jump", target: 0 });
+			expect(resolveIntent(staleClosed, intent("snapToIndex", { index: -1 }))).toEqual({
+				action: "animate",
+				target: 0,
+			});
+		});
+
+		test("a sheet resting within the settle tolerance of closed is closed", () => {
+			expect(resolveIntent({ ...ready, base: 0.4 }, intent("close"))).toBeNull();
+			expect(resolveIntent({ ...ready, closedHeight: -50, base: -49.8 }, intent("close"))).toBeNull();
+		});
+
+		test("a never-opened detached sheet (negative closedHeight, base 0) is closed, so open resolves", () => {
+			const detached: IntentState = { ...ready, currentIndex: -1, closedHeight: -50, base: 0 };
+			expect(resolveIntent(detached, intent("open"))).not.toBeNull();
+			expect(resolveIntent(detached, intent("close"))).toBeNull();
+		});
+
+		test("closing a closed sheet is nothing — no deadlock, no phantom onClose", () => {
+			expect(resolveIntent(ready, intent("close"))).toBeNull();
+			expect(resolveIntent(unmeasured, intent("close"))).toBeNull();
+		});
+	});
+
+	describe("forceClose", () => {
+		test("jumps an open sheet closed without animating", () => {
+			expect(resolveIntent(open, intent("forceClose"))).toEqual({ action: "jump", target: 0 });
+		});
+
+		test("is nothing on a closed sheet", () => {
+			expect(resolveIntent(ready, intent("forceClose"))).toBeNull();
+		});
+	});
+
+	describe("snapToIndex", () => {
+		test("animates to the detent at that index", () => {
+			expect(resolveIntent(open, intent("snapToIndex", { index: 2 }))).toEqual({ action: "animate", target: 800 });
+		});
+
+		test("-1 closes", () => {
+			expect(resolveIntent(open, intent("snapToIndex", { index: -1 }))).toEqual({ action: "animate", target: 0 });
+		});
+
+		test("an index that does not exist is refused", () => {
+			expect(resolveIntent(open, intent("snapToIndex", { index: 3 }))).toBeNull();
+			expect(resolveIntent(open, intent("snapToIndex", { index: -2 }))).toBeNull();
+			expect(resolveIntent(open, intent("snapToIndex", { index: 1.5 }))).toBeNull();
+		});
+
+		test("waits for layout", () => {
+			expect(resolveIntent(unmeasured, intent("snapToIndex", { index: 0 }))).toEqual({ action: "wait" });
+		});
+	});
+
+	describe("snapToPosition", () => {
+		test("a pixel height animates as written, without becoming a detent", () => {
+			expect(resolveIntent(open, intent("snapToPosition", { position: 333 }))).toEqual({
+				action: "animate",
+				target: 333,
+			});
+		});
+
+		test("a percentage resolves against the height available", () => {
+			expect(resolveIntent(open, intent("snapToPosition", { position: "50%" }))).toEqual({
+				action: "animate",
+				target: 400,
+			});
+		});
+
+		test("clamps to what the sheet can show", () => {
+			expect(resolveIntent(open, intent("snapToPosition", { position: 5000 }))).toEqual({
+				action: "animate",
+				target: 800,
+			});
+			expect(resolveIntent({ ...open, closedHeight: -50 }, intent("snapToPosition", { position: -500 }))).toEqual({
+				action: "animate",
+				target: -50,
+			});
+		});
+
+		test("an invalid position is refused", () => {
+			expect(resolveIntent(open, intent("snapToPosition", { position: "abc" }))).toBeNull();
+			expect(resolveIntent(open, intent("snapToPosition", { position: Number.NaN }))).toBeNull();
+		});
+
+		test("waits for layout", () => {
+			expect(resolveIntent(unmeasured, intent("snapToPosition", { position: 100 }))).toEqual({ action: "wait" });
+		});
+	});
+
+	describe("expand and collapse", () => {
+		test("expand animates to the highest detent, collapse to the lowest", () => {
+			expect(resolveIntent(open, intent("expand"))).toEqual({ action: "animate", target: 800 });
+			expect(resolveIntent(open, intent("collapse"))).toEqual({ action: "animate", target: 200 });
+		});
+
+		test("both open a closed sheet", () => {
+			expect(resolveIntent(ready, intent("expand"))).toEqual({ action: "animate", target: 800 });
+		});
+
+		test("both wait for layout and refuse an empty detent list", () => {
+			expect(resolveIntent(unmeasured, intent("expand"))).toEqual({ action: "wait" });
+			expect(resolveIntent({ ...ready, detents: [] }, intent("collapse"))).toBeNull();
+		});
+	});
+});

package/src/core/intent/resolve-intent.ts

@@ -0,0 +1,98 @@
+import type { SheetIntent } from "../sheet.types";
+
+/** Settle tolerance: a base within this of the closed height is closed. */
+const SETTLE_EPSILON = 0.5;
+
+/** What the resolver needs to know about the sheet at the moment an intent lands. */
+export type IntentState = {
+	/** The settled index, `-1` closed. */
+	currentIndex: number;
+	/**
+	 * The keyboard-free height right now. A sheet is open when either says so:
+	 * a release the list owned once left `currentIndex` at `-1` under a sheet
+	 * sitting at its top, and a `close` read it as closed and did nothing.
+	 */
+	base: number;
+	layoutReady: boolean;
+	/** Ascending, normalised detents. */
+	detents: readonly number[];
+	closedHeight: number;
+	/** The height the sheet may occupy — what a `%` position resolves against. */
+	maxHeight: number;
+	/** The index `open` targets. */
+	initialIndex: number;
+};
+
+/**
+ * What an intent turns into.
+ *
+ * `wait` keeps it queued for the next layout; `animate` and `jump` name a
+ * target height; `null` is nothing at all — closing a closed sheet, opening
+ * an open one, an index that does not exist.
+ */
+export type IntentResolution =
+	| { action: "wait" }
+	| { action: "animate"; target: number }
+	| { action: "jump"; target: number };
+
+/**
+ * Resolves a request from the JS thread into a height to go to, or nothing.
+ *
+ * This is where present/dismiss's deadlocks go to die: a close before an
+ * open is `null`, not a queued dismiss that fires when the sheet finally
+ * presents; an open before the first layout waits for it rather than animating
+ * from a guess; `forceClose` jumps. `snapToPosition` resolves a `%` against
+ * `maxHeight` and clamps, without ever adding a detent.
+ *
+ * Runs on the UI thread inside the intent reaction, so it is a flat worklet
+ * and re-implements the little it needs of `heightForIndex` and `parseDetent`
+ * inline.
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the flat-worklet rule forbids extracting helpers; see the doc comment above.
+export function resolveIntent(state: IntentState, intent: SheetIntent): IntentResolution | null {
+	"worklet";
+	const detents = state.detents;
+	const count = detents.length;
+	// A detached sheet's closed height is negative and `base` starts at 0, so a
+	// never-opened card must not read as open: a sheet is visibly open only when
+	// its height is positive, hence the floor at 0.
+	const isOpen = state.currentIndex >= 0 || state.base > Math.max(state.closedHeight, 0) + SETTLE_EPSILON;
+
+	if (intent.kind === "close") {
+		return isOpen ? { action: "animate", target: state.closedHeight } : null;
+	}
+	if (intent.kind === "forceClose") {
+		return isOpen ? { action: "jump", target: state.closedHeight } : null;
+	}
+	if (intent.kind === "open" && isOpen) return null;
+	if (!state.layoutReady) return { action: "wait" };
+
+	if (intent.kind === "open") {
+		if (count === 0) return null;
+		const index =
+			state.initialIndex < 0 ? 0 : state.initialIndex > count - 1 ? count - 1 : Math.floor(state.initialIndex);
+		return { action: "animate", target: detents[index] as number };
+	}
+	if (intent.kind === "snapToIndex") {
+		const index = intent.index;
+		if (index === -1) return isOpen ? { action: "animate", target: state.closedHeight } : null;
+		if (!Number.isInteger(index) || index < 0 || index > count - 1) return null;
+		return { action: "animate", target: detents[index] as number };
+	}
+	if (intent.kind === "snapToPosition") {
+		const position = intent.position;
+		let height = Number.NaN;
+		if (typeof position === "number") {
+			height = position;
+		} else if (typeof position === "string" && position.length > 1 && position.charCodeAt(position.length - 1) === 37) {
+			height = (Number(position.slice(0, -1)) / 100) * state.maxHeight;
+		}
+		if (!Number.isFinite(height)) return null;
+		const clamped =
+			height < state.closedHeight ? state.closedHeight : height > state.maxHeight ? state.maxHeight : height;
+		return { action: "animate", target: clamped };
+	}
+	if (count === 0) return null;
+	if (intent.kind === "expand") return { action: "animate", target: detents[count - 1] as number };
+	return { action: "animate", target: detents[0] as number };
+}

package/src/core/keyboard/container-layout-guard.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test";
+import { acceptContainerLayout } from "./container-layout-guard";
+
+describe("acceptContainerLayout", () => {
+	test("the first measurement is always accepted", () => {
+		expect(acceptContainerLayout({ prev: -1, next: 800, keyboardHeight: 336, progress: 1 })).toBe(true);
+	});
+
+	test("growth is always accepted", () => {
+		expect(acceptContainerLayout({ prev: 800, next: 900, keyboardHeight: 336, progress: 1 })).toBe(true);
+	});
+
+	test("a shrink with no keyboard in play is a real resize", () => {
+		expect(acceptContainerLayout({ prev: 800, next: 600, keyboardHeight: 0, progress: 0 })).toBe(true);
+	});
+
+	test("a shrink by the keyboard's height while it is up is adjustResize double-counting, and is refused", () => {
+		expect(acceptContainerLayout({ prev: 800, next: 464, keyboardHeight: 336, progress: 1 })).toBe(false);
+	});
+
+	test("a shrink smaller than the keyboard mid-animation is refused too — the frame is chasing the keyboard", () => {
+		expect(acceptContainerLayout({ prev: 800, next: 700, keyboardHeight: 336, progress: 0.4 })).toBe(false);
+	});
+
+	test("a shrink larger than the keyboard is a rotation or a split view, keyboard or not", () => {
+		expect(acceptContainerLayout({ prev: 800, next: 400, keyboardHeight: 336, progress: 1 })).toBe(true);
+	});
+
+	test("the same value is accepted, so a re-layout to the same size is not a phantom refusal", () => {
+		expect(acceptContainerLayout({ prev: 800, next: 800, keyboardHeight: 336, progress: 1 })).toBe(true);
+	});
+});

package/src/core/keyboard/container-layout-guard.ts

@@ -0,0 +1,31 @@
+export type ContainerLayoutInput = {
+	/** The container height on record; `UNMEASURED` before the first layout. */
+	prev: number;
+	/** The height `onLayout` just reported. */
+	next: number;
+	/** The keyboard within the container, positive. */
+	keyboardHeight: number;
+	/** keyboard-controller's `progress`. */
+	progress: number;
+};
+
+/** Slack for a keyboard height rounded differently by the two sources. */
+const TOLERANCE = 2;
+
+/**
+ * Whether a container `onLayout` is a real resize or Android's `adjustResize`
+ * shrinking the window under a keyboard the sheet is already lifting for.
+ *
+ * Accepting the second would count the keyboard twice: once as the lift, once
+ * as a smaller container with every percent detent re-derived against it.
+ * So while the keyboard is in play, a shrink no larger than the keyboard is
+ * refused. A shrink larger than that — a rotation, a split view — is real
+ * whatever the keyboard is doing, and growth and first measurement always
+ * land.
+ */
+export function acceptContainerLayout(input: ContainerLayoutInput): boolean {
+	if (input.prev < 0 || input.next >= input.prev) return true;
+	if (!(input.progress > 0) || !(input.keyboardHeight > 0)) return true;
+	const shrink = input.prev - input.next;
+	return shrink > input.keyboardHeight + TOLERANCE;
+}

package/src/core/keyboard/content-area.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import { contentArea } from "./content-area";
+
+describe("contentArea", () => {
+	test("the body gets what the handle, footer and keyboard leave", () => {
+		expect(
+			contentArea({ sheetHeight: 600, handleHeight: 24, footerHeight: 90, keyboardHeight: 0, trailingBand: 0 })
+		).toBe(486);
+	});
+
+	test("without a footer the safe-area band trails the content instead", () => {
+		expect(
+			contentArea({ sheetHeight: 600, handleHeight: 24, footerHeight: 0, keyboardHeight: 0, trailingBand: 34 })
+		).toBe(542);
+	});
+
+	test("a keyboard the sheet owns takes its height off the body", () => {
+		expect(
+			contentArea({ sheetHeight: 800, handleHeight: 24, footerHeight: 90, keyboardHeight: 336, trailingBand: 0 })
+		).toBe(350);
+	});
+
+	test("never negative — a keyboard taller than the sheet leaves an empty body, not an inverted one", () => {
+		expect(
+			contentArea({ sheetHeight: 200, handleHeight: 24, footerHeight: 90, keyboardHeight: 336, trailingBand: 0 })
+		).toBe(0);
+	});
+
+	test("unmeasured parts subtract nothing", () => {
+		expect(
+			contentArea({ sheetHeight: 600, handleHeight: -1, footerHeight: -1, keyboardHeight: 0, trailingBand: 0 })
+		).toBe(600);
+	});
+});

package/src/core/keyboard/content-area.ts

@@ -0,0 +1,26 @@
+export type ContentAreaInput = {
+	/** The sheet's visible height for sizing the body — `min(maxHeight, highest + keyboardLift)`. */
+	sheetHeight: number;
+	handleHeight: number;
+	/** The sticky footer's full height, band included; zero without one. */
+	footerHeight: number;
+	/** The keyboard the sheet owns, positive, within the container. */
+	keyboardHeight: number;
+	/** The safe-area band trailing the content when there is no footer to hold it. */
+	trailingBand: number;
+};
+
+/**
+ * The height the body may fill: whatever the handle, the footer, the keyboard
+ * and the trailing band leave of the sheet. Never negative, and an unmeasured
+ * part subtracts nothing.
+ */
+export function contentArea(input: ContentAreaInput): number {
+	"worklet";
+	const handle = input.handleHeight > 0 ? input.handleHeight : 0;
+	const footer = input.footerHeight > 0 ? input.footerHeight : 0;
+	const keyboard = input.keyboardHeight > 0 ? input.keyboardHeight : 0;
+	const band = input.trailingBand > 0 ? input.trailingBand : 0;
+	const area = input.sheetHeight - handle - footer - keyboard - band;
+	return area > 0 ? area : 0;
+}

package/src/core/keyboard/keyboard-lift.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+import type { KeyboardBehavior } from "../sheet.types";
+import { keyboardInContainer, keyboardLift } from "./keyboard-lift";
+
+describe("keyboardInContainer", () => {
+	test("keyboard-controller's height is negative; the container's share is positive", () => {
+		expect(keyboardInContainer(-336, 0)).toBe(336);
+	});
+
+	test("a container ending above the window bottom is overlapped by less of the keyboard", () => {
+		expect(keyboardInContainer(-336, 80)).toBe(256);
+	});
+
+	test("a container the keyboard never reaches sees zero", () => {
+		expect(keyboardInContainer(-100, 200)).toBe(0);
+		expect(keyboardInContainer(0, 0)).toBe(0);
+	});
+
+	test("an unmeasured offset counts as zero rather than inflating the keyboard", () => {
+		expect(keyboardInContainer(-336, -1)).toBe(336);
+	});
+});
+
+describe("keyboardLift", () => {
+	const input = { keyboardHeight: 336, progress: 1, band: 34, gapBelow: 0 };
+
+	test("interactive and extend lift by the keyboard less the collapsed safe-area band", () => {
+		for (const behavior of ["interactive", "extend"] as const satisfies KeyboardBehavior[]) {
+			expect(keyboardLift({ ...input, behavior })).toBe(336 - 34);
+		}
+	});
+
+	test("the band collapses in step with the keyboard's progress", () => {
+		expect(keyboardLift({ ...input, behavior: "interactive", progress: 0.5, keyboardHeight: 168 })).toBe(168 - 17);
+	});
+
+	test("fillParent and none never lift — fill grows the sheet, none ignores the keyboard", () => {
+		for (const behavior of ["fillParent", "none"] as const satisfies KeyboardBehavior[]) {
+			expect(keyboardLift({ ...input, behavior })).toBe(0);
+		}
+	});
+
+	test("a detached sheet already floats above the bottom, so its gap comes off the lift", () => {
+		expect(keyboardLift({ ...input, band: 0, gapBelow: 50, behavior: "interactive" })).toBe(336 - 50);
+	});
+
+	test("never negative — a keyboard shorter than the gap leaves the sheet alone", () => {
+		expect(keyboardLift({ ...input, keyboardHeight: 20, band: 0, gapBelow: 50, behavior: "interactive" })).toBe(0);
+	});
+
+	test("no keyboard, no lift, whatever the behaviour", () => {
+		expect(keyboardLift({ ...input, keyboardHeight: 0, progress: 0, behavior: "interactive" })).toBe(0);
+	});
+});

package/src/core/keyboard/keyboard-lift.ts

@@ -0,0 +1,47 @@
+import type { KeyboardBehavior } from "../sheet.types";
+
+/**
+ * How much of the keyboard overlaps the sheet's container.
+ *
+ * keyboard-controller reports `height` as a **negative** number of pixels from
+ * the window's bottom edge. A container whose bottom sits
+ * `containerBottomOffset` above that edge is overlapped by that much less.
+ */
+export function keyboardInContainer(rawKeyboardHeight: number, containerBottomOffset: number): number {
+	"worklet";
+	const offset = containerBottomOffset > 0 ? containerBottomOffset : 0;
+	const overlap = -rawKeyboardHeight - offset;
+	return overlap > 0 ? overlap : 0;
+}
+
+export type KeyboardLiftInput = {
+	/** The keyboard the sheet owns, positive, already reduced to the container. */
+	keyboardHeight: number;
+	/** keyboard-controller's `progress`, 0 closed through 1 open. */
+	progress: number;
+	/** The safe-area band under an attached sheet; zero when detached. */
+	band: number;
+	behavior: KeyboardBehavior;
+	/** A detached sheet's resting bottom — pixels it already floats above the edge. */
+	gapBelow: number;
+};
+
+/**
+ * The extra height a keyboard adds on top of `base`.
+ *
+ * Only `interactive` and `extend` lift. The sheet already spends `band`
+ * pixels on the safe area under the footer, and those pixels are the
+ * keyboard's now, so they come off the lift in step with `progress`; a
+ * detached sheet's gap comes off the same way. That subtraction is what holds
+ * `footerTop` still for the whole keyboard animation — see `footer/footer-top`.
+ */
+export function keyboardLift(input: KeyboardLiftInput): number {
+	"worklet";
+	if (input.behavior !== "interactive" && input.behavior !== "extend") return 0;
+
+	const progress = input.progress < 0 ? 0 : input.progress > 1 ? 1 : input.progress;
+	const band = input.band > 0 ? input.band : 0;
+	const gap = input.gapBelow > 0 ? input.gapBelow : 0;
+	const lift = input.keyboardHeight - band * progress - gap;
+	return lift > 0 ? lift : 0;
+}