@delacour/react-native-bottom-sheet 0.2.0 → 0.3.0-alpha.20261023075140

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-bottom-sheet",
-	"version": "0.2.0",
+	"version": "0.3.0-alpha.20261023075140",
 	"description": "Headless bottom sheet engine for React Native — no tokens, no className",
 	"type": "module",
 	"license": "MIT",

package/src/components/bottom-sheet.tsx

@@ -110,6 +110,7 @@ function BottomSheetRoot({
 	overDragResistanceFactor = 2.5,
 	keyboardBehavior = "interactive",
 	keyboardBlurBehavior = "restore",
+	keyboardLiftLimit = "container",
 	keyboardScope = "inside",
 	enableBlurKeyboardOnGesture = true,
 	animation,
@@ -168,6 +169,7 @@ function BottomSheetRoot({
 			animateOnMount,
 			keyboardBehavior,
 			keyboardBlurBehavior,
+			keyboardLiftLimit,
 			keyboardScope,
 			enableBlurKeyboardOnGesture,
 		}),
@@ -184,6 +186,7 @@ function BottomSheetRoot({
 			animateOnMount,
 			keyboardBehavior,
 			keyboardBlurBehavior,
+			keyboardLiftLimit,
 			keyboardScope,
 			enableBlurKeyboardOnGesture,
 		]

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

@@ -14,6 +14,7 @@ import type {
 	DetachedProp,
 	KeyboardBehavior,
 	KeyboardBlurBehavior,
+	KeyboardLiftLimit,
 	KeyboardScope,
 	ReduceMotionMode,
 	SnapPointSpec,
@@ -75,7 +76,7 @@ export type BottomSheetProps = SheetHaptics & {
 	snapPoints?: readonly SnapPointSpec[];
 	/** Adds the content's own height as a snap point. @default true */
 	dynamicSizing?: boolean;
-	/** Caps the dynamic snap point. */
+	/** Caps the dynamic snap point, and how high a keyboard may lift the sheet. */
 	maxDynamicContentSize?: number;
 	/** Pixels the frame leaves clear at the top. @default 0 */
 	topInset?: number;
@@ -103,6 +104,8 @@ export type BottomSheetProps = SheetHaptics & {
 	keyboardBehavior?: KeyboardBehavior;
 	/** @default "restore" */
 	keyboardBlurBehavior?: KeyboardBlurBehavior;
+	/** Whether `maxDynamicContentSize` also stops the keyboard's lift. @default "container" */
+	keyboardLiftLimit?: KeyboardLiftLimit;
 	/** @default "inside" */
 	keyboardScope?: KeyboardScope;
 	/** @default true */

package/src/core/AGENTS.md

@@ -33,7 +33,7 @@ at the moment a view needs it, by `geometry/position.ts`, and nowhere else.
 | `snap-points/select-snap-height.ts` | W `selectSnapHeight` — nearest candidate to `height + projection · velocity`; closes only when given a closed height |
 | `snap-points/over-drag.ts` | W `resistOverDrag` — slope 1 at the edge, square-root beyond; factor 0 clamps |
 | `snap-points/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-lift.ts` | W `keyboardInContainer`, W `keyboardLift` — the lift, band and gap subtracted in step with progress, stopped at the ceiling; W `keyboardCeiling` — a capped dynamic sheet is lifted no higher than its cap |
 | `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 |
@@ -71,11 +71,12 @@ band          = detached ? 0 : inset                         bandNow = band · (
 footerHeight  = hasFooter ? footerContent + bandNow : 0
 dynamicSnapPoint = min(handle + content + (hasFooter ? footerContent : 0) + band, maxDynamicContentSize, available)
 snapPoints       = sortAsc(unique(normalize(spec, available) ∪ {dynamicSnapPoint if dynamicSizing}))
-keyboardLift  = behavior ∈ {interactive, extend} ? max(0, kb − band · p − (detached ? restingBottom : 0)) : 0
+ceiling       = keyboardLiftLimit = maxDynamicContentSize && dynamicSizing && maxDynamicContentSize ? min(maxDynamicContentSize, maxHeight) : maxHeight
+keyboardLift  = behavior ∈ {interactive, extend} ? clamp(kb − band · p − (detached ? restingBottom : 0), 0, ceiling − base) : 0
 height        = clamp(base + keyboardLift, closedHeight, maxHeight)
 translateY    = C − restingBottom − height
 index         = piecewise(base, [closedHeight, …snapPoints] → [−1, 0, 1, …])      // base, never height
-contentArea   = max(0, min(maxHeight, highest + keyboardLift) − handle − footerHeight − kb − (hasFooter ? 0 : bandNow))
+contentArea   = max(0, min(maxHeight, highest + keyboardLift(base = highest)) − 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

package/src/core/index.ts

@@ -31,7 +31,13 @@ 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 KeyboardCeilingInput,
+	type KeyboardLiftInput,
+	keyboardCeiling,
+	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";
@@ -75,6 +81,7 @@ export {
 	type GestureSource,
 	type KeyboardBehavior,
 	type KeyboardBlurBehavior,
+	type KeyboardLiftLimit,
 	type KeyboardScope,
 	SCROLLABLE_TYPE,
 	type ScrollableType,

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

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import type { KeyboardBehavior } from "../sheet.types";
-import { keyboardInContainer, keyboardLift } from "./keyboard-lift";
+import { keyboardCeiling, keyboardInContainer, keyboardLift } from "./keyboard-lift";
 
 describe("keyboardInContainer", () => {
 	test("keyboard-controller's height is negative; the container's share is positive", () => {
@@ -52,3 +52,48 @@ describe("keyboardLift", () => {
 		expect(keyboardLift({ ...input, keyboardHeight: 0, progress: 0, behavior: "interactive" })).toBe(0);
 	});
 });
+
+describe("keyboardLift under a ceiling", () => {
+	const input = { keyboardHeight: 336, progress: 1, band: 0, gapBelow: 0, behavior: "interactive" as const };
+
+	test("a short sheet lifts until its top reaches the ceiling, and no further", () => {
+		expect(keyboardLift({ ...input, base: 600, ceiling: 724 })).toBe(124);
+	});
+
+	test("a sheet already at the ceiling stays where it is; the keyboard covers its bottom", () => {
+		expect(keyboardLift({ ...input, base: 724, ceiling: 724 })).toBe(0);
+	});
+
+	test("a snap point above the ceiling is never pulled down — the lift is zero, not negative", () => {
+		expect(keyboardLift({ ...input, base: 800, ceiling: 724 })).toBe(0);
+	});
+
+	test("a ceiling the lift never reaches changes nothing", () => {
+		expect(keyboardLift({ ...input, base: 200, ceiling: 724 })).toBe(336);
+	});
+
+	test("without a ceiling the lift is the keyboard's", () => {
+		expect(keyboardLift({ ...input, base: 724 })).toBe(336);
+	});
+});
+
+describe("keyboardCeiling", () => {
+	const capped = { limit: "maxDynamicContentSize", dynamicSizing: true, maxHeight: 852 } as const;
+
+	test("a dynamic sheet with a cap is lifted no higher than the cap", () => {
+		expect(keyboardCeiling({ ...capped, maxDynamicContentSize: 724 })).toBe(724);
+	});
+
+	test("a cap above the container changes nothing", () => {
+		expect(keyboardCeiling({ ...capped, maxDynamicContentSize: 900 })).toBe(852);
+	});
+
+	test("no cap, or explicit snap points, leave the container as the ceiling", () => {
+		expect(keyboardCeiling({ ...capped, maxDynamicContentSize: undefined })).toBe(852);
+		expect(keyboardCeiling({ ...capped, dynamicSizing: false, maxDynamicContentSize: 724 })).toBe(852);
+	});
+
+	test("the default limit is the container, cap or no cap", () => {
+		expect(keyboardCeiling({ ...capped, limit: "container", maxDynamicContentSize: 724 })).toBe(852);
+	});
+});

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

@@ -1,4 +1,4 @@
-import type { KeyboardBehavior } from "../sheet.types";
+import type { KeyboardBehavior, KeyboardLiftLimit } from "../sheet.types";
 
 /**
  * How much of the keyboard overlaps the sheet's container.
@@ -24,6 +24,10 @@ export type KeyboardLiftInput = {
 	behavior: KeyboardBehavior;
 	/** A detached sheet's resting bottom — pixels it already floats above the edge. */
 	gapBelow: number;
+	/** The keyboard-free height the lift sits on. Read only with `ceiling`. */
+	base?: number;
+	/** The height the lift may not carry `base` past — see `keyboardCeiling`. */
+	ceiling?: number;
 };
 
 /**
@@ -43,5 +47,35 @@ export function keyboardLift(input: KeyboardLiftInput): number {
 	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;
+	if (!(lift > 0)) return 0;
+	if (input.ceiling === undefined) return lift;
+	const room = input.ceiling - (input.base ?? 0);
+	if (!(room > 0)) return 0;
+	return lift < room ? lift : room;
+}
+
+export type KeyboardCeilingInput = {
+	limit: KeyboardLiftLimit;
+	dynamicSizing: boolean;
+	maxDynamicContentSize: number | undefined;
+	/** The container's available height. */
+	maxHeight: number;
+};
+
+/**
+ * The height a keyboard may lift the sheet to.
+ *
+ * The container's top, unless `limit` is `maxDynamicContentSize` and the sheet
+ * sizes to its content under that cap: then the lift stops at the cap and the
+ * keyboard covers the sheet's bottom instead, the body shrinking by it as
+ * always. Decided on the UI thread, in the frame the keyboard moves — a caller
+ * shrinking the cap from a JS keyboard event lands a few frames late, and the
+ * sheet overshoots to the container's top before settling.
+ */
+export function keyboardCeiling(input: KeyboardCeilingInput): number {
+	"worklet";
+	const cap = input.maxDynamicContentSize;
+	if (input.limit !== "maxDynamicContentSize" || !input.dynamicSizing || cap === undefined) return input.maxHeight;
+	const bounded = cap > 0 ? cap : 0;
+	return bounded < input.maxHeight ? bounded : input.maxHeight;
 }

package/src/core/sheet.types.ts

@@ -22,6 +22,15 @@ export type KeyboardBehavior = "interactive" | "extend" | "fillParent" | "none";
 /** What the sheet does when the keyboard it lifted for goes away. */
 export type KeyboardBlurBehavior = "none" | "restore";
 
+/**
+ * How high a keyboard may lift the sheet.
+ *
+ * `container` — to the container's top. `maxDynamicContentSize` — a sheet
+ * sized to its content stops at that cap, and the keyboard covers its bottom
+ * instead; for a caller whose cap already keeps the page in view.
+ */
+export type KeyboardLiftLimit = "container" | "maxDynamicContentSize";
+
 /**
  * Which focused inputs count as the sheet's own.
  *

package/src/state/state.types.ts

@@ -5,6 +5,7 @@ import type {
 	GestureSource,
 	KeyboardBehavior,
 	KeyboardBlurBehavior,
+	KeyboardLiftLimit,
 	KeyboardScope,
 	ScrollableType,
 	SheetIntent,
@@ -38,6 +39,7 @@ export type SheetWorkletConfig = {
 	animateOnMount: boolean;
 	keyboardBehavior: KeyboardBehavior;
 	keyboardBlurBehavior: KeyboardBlurBehavior;
+	keyboardLiftLimit: KeyboardLiftLimit;
 	keyboardScope: KeyboardScope;
 	enableBlurKeyboardOnGesture: boolean;
 };

package/src/state/use-sheet-geometry.ts

@@ -13,6 +13,7 @@ import {
 	footerTop,
 	indexForHeight,
 	isLayoutReady,
+	keyboardCeiling,
 	keyboardLift,
 	positionFor,
 	restingBottom,
@@ -56,6 +57,17 @@ export function useSheetGeometry(state: SheetSharedState): SheetGeometry {
 	const keyboardEffective = useDerivedValue(() =>
 		state.keyboardOwned.value && state.config.value.keyboardBehavior !== "none" ? state.keyboardHeight.value : 0
 	);
+	// Under `keyboardLiftLimit="maxDynamicContentSize"` a capped dynamic sheet is
+	// lifted no higher than its cap — decided here, on the UI thread, so it holds
+	// from the keyboard's first frame.
+	const ceiling = useDerivedValue(() =>
+		keyboardCeiling({
+			limit: state.config.value.keyboardLiftLimit,
+			dynamicSizing: state.config.value.dynamicSizing,
+			maxDynamicContentSize: state.config.value.maxDynamicContentSize,
+			maxHeight: maxHeight.value,
+		})
+	);
 	const lift = useDerivedValue(() =>
 		keyboardLift({
 			keyboardHeight: keyboardEffective.value,
@@ -63,6 +75,8 @@ export function useSheetGeometry(state: SheetSharedState): SheetGeometry {
 			band: band.value,
 			behavior: state.config.value.keyboardBehavior,
 			gapBelow: resting.value,
+			base: state.base.value,
+			ceiling: ceiling.value,
 		})
 	);
 	const height = useDerivedValue(() => clampHeight(state.base.value + lift.value, closed.value, maxHeight.value));
@@ -92,7 +106,17 @@ export function useSheetGeometry(state: SheetSharedState): SheetGeometry {
 	// never reflows during a snap between snap points — but a `fillParent` snap
 	// takes `base` above every snap point, and the body follows it up.
 	const area = useDerivedValue(() => {
-		const sheetHeight = Math.min(maxHeight.value, Math.max(highest.value, state.base.value) + lift.value);
+		const from = Math.max(highest.value, state.base.value);
+		const fromLift = keyboardLift({
+			keyboardHeight: keyboardEffective.value,
+			progress: state.keyboardProgress.value,
+			band: band.value,
+			behavior: state.config.value.keyboardBehavior,
+			gapBelow: resting.value,
+			base: from,
+			ceiling: ceiling.value,
+		});
+		const sheetHeight = Math.min(maxHeight.value, from + fromLift);
 		return contentArea({
 			sheetHeight,
 			handleHeight: state.handleHeight.value,

package/src/state/use-sheet-state.ts

@@ -64,6 +64,7 @@ export function useSheetState(snapPoints: readonly SnapPointSpec[], config: Shee
 		animateOnMount,
 		keyboardBehavior,
 		keyboardBlurBehavior,
+		keyboardLiftLimit,
 		keyboardScope,
 		enableBlurKeyboardOnGesture,
 	} = config;
@@ -83,6 +84,7 @@ export function useSheetState(snapPoints: readonly SnapPointSpec[], config: Shee
 			animateOnMount,
 			keyboardBehavior,
 			keyboardBlurBehavior,
+			keyboardLiftLimit,
 			keyboardScope,
 			enableBlurKeyboardOnGesture,
 		};
@@ -100,6 +102,7 @@ export function useSheetState(snapPoints: readonly SnapPointSpec[], config: Shee
 		animateOnMount,
 		keyboardBehavior,
 		keyboardBlurBehavior,
+		keyboardLiftLimit,
 		keyboardScope,
 		enableBlurKeyboardOnGesture,
 	]);