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

package/src/core/footer/body-inset.ts

@@ -0,0 +1,65 @@
+/**
+ * What trails the body, in pixels: the sticky footer — content and band — when
+ * there is one, and the safe-area band alone when there is not. Both are the
+ * current values, so the reservation collapses with the band as the keyboard
+ * rises. Never negative; an unmeasured footer reserves nothing yet.
+ *
+ * A body is laid out to the sheet's bottom line and reserves this much at its
+ * end — a spacer inside a static `Content`, a trailing spacer inside a
+ * scrollable's content — so a list's rows run under the footer and the band
+ * and its last row can still be scrolled fully clear of them.
+ */
+export function bodyInset(hasFooter: boolean, footerHeight: number, band: number): number {
+	"worklet";
+	const value = hasFooter ? footerHeight : band;
+	return value > 0 ? value : 0;
+}
+
+export type BodyClipInput = {
+	/** The geometry's `contentArea` — the body sized against its detent. */
+	contentArea: number;
+	/** `bodyInset` — what the body reserves at its end. */
+	inset: number;
+	hasFooter: boolean;
+	/** The sheet's live height — `base + keyboardLift`, clamped. */
+	sheetHeight: number;
+	handleHeight: number;
+	/** The keyboard the sheet owns, positive, within the container. */
+	keyboardHeight: number;
+};
+
+/**
+ * How tall the body's clipping box is right now.
+ *
+ * The body is laid out `contentArea + inset` tall — to the sheet's bottom line
+ * — and without a footer that is the clip too: the sheet slides as one body
+ * and nothing needs hiding. Under a sticky footer the clip also follows the
+ * footer's top edge, `sheetHeight − keyboard − handle − inset`, which is where
+ * `footerTop` puts it. On the detent the two agree and the clip is exactly
+ * `contentArea`; below it — a drag to close, the close animation — the footer
+ * stays on the screen's bottom edge while the panel slides down under it, and
+ * the clip shrinks in step so no line of the body is ever drawn below the
+ * footer's top, whatever the footer's background. Never negative.
+ */
+export function bodyClip(input: BodyClipInput): number {
+	"worklet";
+	const inset = input.inset > 0 ? input.inset : 0;
+	const area = (input.contentArea > 0 ? input.contentArea : 0) + inset;
+	if (!input.hasFooter) return area;
+	const handle = input.handleHeight > 0 ? input.handleHeight : 0;
+	const keyboard = input.keyboardHeight > 0 ? input.keyboardHeight : 0;
+	const visible = input.sheetHeight - keyboard - handle - inset;
+	const clip = visible < area ? visible : area;
+	return clip > 0 ? clip : 0;
+}
+
+/**
+ * The rows' own height: a scrollable's reported content size less the
+ * trailing spacer it renders inside that content. This is what the dynamic
+ * detent counts — the spacer is the footer and the band, which the detent
+ * already adds once. An unmeasured spacer subtracts nothing; never negative.
+ */
+export function scrollContentHeight(contentSize: number, spacer: number): number {
+	const value = contentSize - (spacer > 0 ? spacer : 0);
+	return value > 0 ? value : 0;
+}

package/src/core/footer/bottom-band.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import { bandNow, bottomBand, footerHeight } from "./bottom-band";
+
+describe("bottomBand", () => {
+	test("an attached sheet reserves the safe-area inset", () => {
+		expect(bottomBand(false, 34)).toBe(34);
+	});
+
+	test("a detached sheet floats above the inset, so it has no band", () => {
+		expect(bottomBand(true, 34)).toBe(0);
+	});
+
+	test("a negative inset is treated as none", () => {
+		expect(bottomBand(false, -1)).toBe(0);
+	});
+});
+
+describe("bandNow", () => {
+	test("the band is whole with the keyboard down and gone with it up", () => {
+		expect(bandNow(34, 0)).toBe(34);
+		expect(bandNow(34, 1)).toBe(0);
+	});
+
+	test("collapses linearly with progress", () => {
+		expect(bandNow(34, 0.5)).toBe(17);
+	});
+
+	test("clamps a progress outside [0, 1]", () => {
+		expect(bandNow(34, -0.2)).toBe(34);
+		expect(bandNow(34, 1.3)).toBe(0);
+	});
+});
+
+describe("footerHeight", () => {
+	test("a footer is its content plus the band under it right now", () => {
+		expect(footerHeight(true, 56, 34)).toBe(90);
+	});
+
+	test("no footer, no height, whatever was measured", () => {
+		expect(footerHeight(false, 56, 34)).toBe(0);
+	});
+
+	test("an unmeasured footer contributes only its band", () => {
+		expect(footerHeight(true, -1, 34)).toBe(34);
+	});
+});

package/src/core/footer/bottom-band.ts

@@ -0,0 +1,30 @@
+/**
+ * The safe-area band an attached sheet reserves under its content or footer.
+ * A detached sheet already floats above the inset and reserves nothing.
+ */
+export function bottomBand(detached: boolean, bottomInset: number): number {
+	"worklet";
+	if (detached) return 0;
+	return bottomInset > 0 ? bottomInset : 0;
+}
+
+/**
+ * The band as it stands mid-keyboard: whole at `progress` 0, gone at 1. The
+ * keyboard covers the safe area, so the pixels reserved for it are the
+ * keyboard's now — and `keyboardLift` subtracts the same amount, which is
+ * what keeps the footer still.
+ */
+export function bandNow(band: number, progress: number): number {
+	"worklet";
+	const p = progress < 0 ? 0 : progress > 1 ? 1 : progress;
+	const value = (band > 0 ? band : 0) * (1 - p);
+	return value;
+}
+
+/** The sticky footer's full height right now — content plus the band under it, or nothing without a footer. */
+export function footerHeight(hasFooter: boolean, footerContentHeight: number, band: number): number {
+	"worklet";
+	if (!hasFooter) return 0;
+	const content = footerContentHeight > 0 ? footerContentHeight : 0;
+	return content + (band > 0 ? band : 0);
+}

package/src/core/footer/footer-top.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import { keyboardLift } from "../keyboard/keyboard-lift";
+import { bandNow } from "./bottom-band";
+import { footerTop } from "./footer-top";
+
+describe("footerTop", () => {
+	test("with no keyboard the footer sits above its band at the bottom of the sheet", () => {
+		expect(footerTop({ sheetHeight: 500, keyboardHeight: 0, footerContentHeight: 56, band: 34 })).toBe(410);
+	});
+
+	test("a keyboard pushes the footer up by its full height", () => {
+		expect(footerTop({ sheetHeight: 500, keyboardHeight: 300, footerContentHeight: 56, band: 0 })).toBe(144);
+	});
+
+	test("never negative — a footer taller than the sheet pins to the top", () => {
+		expect(footerTop({ sheetHeight: 40, keyboardHeight: 0, footerContentHeight: 56, band: 34 })).toBe(0);
+	});
+
+	test("an unmeasured footer subtracts nothing", () => {
+		expect(footerTop({ sheetHeight: 500, keyboardHeight: 0, footerContentHeight: -1, band: 34 })).toBe(466);
+	});
+
+	/**
+	 * The proof the whole footer/keyboard/inset model rests on.
+	 *
+	 * The sheet's height is `base + keyboardLift`, the lift is
+	 * `kb − band · p`, and the band under the footer is `band · (1 − p)`. Then
+	 * `footerTop = base + kb − band·p − kb − footer − band + band·p`
+	 *            = `base − footer − band`,
+	 * independent of `p`: the footer does not move a pixel while the keyboard
+	 * animates, only the safe-area band under it collapses, and at `p = 1` the
+	 * footer's bottom edge sits on the keyboard's top edge.
+	 */
+	test("holds still for the whole keyboard animation", () => {
+		const base = 24 + 300 + 56 + 34;
+		const band = 34;
+		const footerContentHeight = 56;
+		const fullKeyboard = 336;
+		const expected = base - footerContentHeight - band;
+
+		for (let step = 0; step <= 20; step += 1) {
+			const progress = step / 20;
+			const keyboardHeight = fullKeyboard * progress;
+			const lift = keyboardLift({ keyboardHeight, progress, band, behavior: "interactive", gapBelow: 0 });
+			const sheetHeight = base + lift;
+			const top = footerTop({ sheetHeight, keyboardHeight, footerContentHeight, band: bandNow(band, progress) });
+			expect(top).toBeCloseTo(expected, 6);
+		}
+	});
+
+	test("at full keyboard the footer's bottom edge sits on the keyboard's top edge", () => {
+		const base = 414;
+		const band = 34;
+		const footerContentHeight = 56;
+		const keyboardHeight = 336;
+		const lift = keyboardLift({ keyboardHeight, progress: 1, band, behavior: "interactive", gapBelow: 0 });
+		const sheetHeight = base + lift;
+		const top = footerTop({ sheetHeight, keyboardHeight, footerContentHeight, band: bandNow(band, 1) });
+		expect(top + footerContentHeight).toBe(sheetHeight - keyboardHeight);
+	});
+});

package/src/core/footer/footer-top.ts

@@ -0,0 +1,27 @@
+export type FooterTopInput = {
+	/** The sheet's visible height — `base + keyboardLift`. */
+	sheetHeight: number;
+	/** The keyboard the sheet owns, positive, within the container. */
+	keyboardHeight: number;
+	/** The footer's measured content, band excluded; `UNMEASURED` counts as zero. */
+	footerContentHeight: number;
+	/** The band under the footer right now — `bandNow(band, progress)`. */
+	band: number;
+};
+
+/**
+ * The sticky footer's `translateY` inside the body: the sheet's height less
+ * the keyboard, the footer's content and the band under it, never negative.
+ *
+ * Fed the current band rather than the resting one, this is constant across a
+ * keyboard animation — `footer-top.test.ts` sweeps the proof. The footer is
+ * the one thing that does not move when the keyboard does.
+ */
+export function footerTop(input: FooterTopInput): number {
+	"worklet";
+	const keyboard = input.keyboardHeight > 0 ? input.keyboardHeight : 0;
+	const footer = input.footerContentHeight > 0 ? input.footerContentHeight : 0;
+	const band = input.band > 0 ? input.band : 0;
+	const top = input.sheetHeight - keyboard - footer - band;
+	return top > 0 ? top : 0;
+}

package/src/core/footer/sheet-insets.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test";
+import { resolveSheetBottomInset, resolveSheetScrollEndPadding } from "./sheet-insets";
+
+describe("resolveSheetBottomInset", () => {
+	test("without a sticky footer the content's trailing spacer holds the safe-area band", () => {
+		expect(resolveSheetBottomInset({ bottom: 34, hasStickyFooter: false })).toBe(34);
+	});
+
+	test("with a sticky footer the footer holds the band, so the content reserves none", () => {
+		expect(resolveSheetBottomInset({ bottom: 34, hasStickyFooter: true })).toBe(0);
+	});
+
+	test("no inset, no band either way", () => {
+		expect(resolveSheetBottomInset({ bottom: 0, hasStickyFooter: false })).toBe(0);
+	});
+});
+
+describe("resolveSheetScrollEndPadding", () => {
+	test("without a sticky footer a skin adds nothing — the engine's spacer already ends the content at the band", () => {
+		expect(resolveSheetScrollEndPadding({ bottom: 34, hasStickyFooter: false, footerGap: 16 })).toBe(0);
+	});
+
+	test("with a sticky footer the scroll content ends a gap above the footer's hairline", () => {
+		expect(resolveSheetScrollEndPadding({ bottom: 34, hasStickyFooter: true, footerGap: 16 })).toBe(16);
+		expect(resolveSheetScrollEndPadding({ bottom: 0, hasStickyFooter: true, footerGap: 16 })).toBe(16);
+	});
+});

package/src/core/footer/sheet-insets.ts

@@ -0,0 +1,30 @@
+/**
+ * The safe-area band the engine reserves under a sheet's static content.
+ *
+ * The band belongs to whatever is bottom-most in the sheet: with a sticky
+ * footer that is the footer, whose styled box pads through the band, so the
+ * content reserves none of it. With no footer the content is bottom-most and
+ * `Content`'s trailing spacer holds it. This is what the engine reserves, not
+ * something a skin adds — a skin that padded the band as well would count it
+ * twice and leave a gap the height of the home indicator.
+ *
+ * Lives in the engine so the skin can re-export it without mounting a sheet.
+ */
+export function resolveSheetBottomInset(input: { hasStickyFooter: boolean; bottom: number }): number {
+	return input.hasStickyFooter ? 0 : input.bottom;
+}
+
+/**
+ * The padding a skin adds at the end of a sheet's scrollable content: a
+ * `footerGap` above a sticky footer's hairline, so the last row does not butt
+ * against it, and otherwise nothing — the engine's scrollables already end
+ * their content with a spacer the height of the footer or the band, so the
+ * rows scroll under either and the last one can be brought fully clear.
+ */
+export function resolveSheetScrollEndPadding(input: {
+	hasStickyFooter: boolean;
+	bottom: number;
+	footerGap: number;
+}): number {
+	return input.hasStickyFooter ? input.footerGap : 0;
+}

package/src/core/geometry/clamp-height.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "bun:test";
+import { clampHeight } from "./clamp-height";
+
+describe("clampHeight", () => {
+	test("inside the range the height passes through", () => {
+		expect(clampHeight(300, 0, 800)).toBe(300);
+	});
+
+	test("clamps to the closed height below and the maximum above", () => {
+		expect(clampHeight(-40, 0, 800)).toBe(0);
+		expect(clampHeight(900, 0, 800)).toBe(800);
+	});
+
+	test("a detached closed height is negative and still the floor", () => {
+		expect(clampHeight(-100, -50, 750)).toBe(-50);
+	});
+
+	test("NaN collapses to the closed height rather than freezing the sheet", () => {
+		expect(clampHeight(Number.NaN, 0, 800)).toBe(0);
+	});
+
+	test("an inverted range collapses to the closed height", () => {
+		expect(clampHeight(300, 0, -1)).toBe(0);
+	});
+});

package/src/core/geometry/clamp-height.ts

@@ -0,0 +1,12 @@
+/**
+ * A height held within `[closedHeight, maxHeight]`. `NaN` and an inverted
+ * range both collapse to the closed height: one bad frame written into `base`
+ * would otherwise freeze the sheet with nothing on screen to say why.
+ */
+export function clampHeight(height: number, closedHeight: number, maxHeight: number): number {
+	"worklet";
+	if (Number.isNaN(height) || maxHeight < closedHeight) return closedHeight;
+	if (height < closedHeight) return closedHeight;
+	if (height > maxHeight) return maxHeight;
+	return height;
+}

package/src/core/geometry/closed-height.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { availableHeight, closedHeight, restingBottom } from "./closed-height";
+
+describe("restingBottom", () => {
+	test("an attached sheet rests on the container's bottom edge", () => {
+		expect(restingBottom(false, 16, 34)).toBe(0);
+	});
+
+	test("a detached sheet rests its offset above the safe-area inset", () => {
+		expect(restingBottom(true, 16, 34)).toBe(50);
+	});
+
+	test("an unmeasured inset counts as zero", () => {
+		expect(restingBottom(true, 16, -1)).toBe(16);
+	});
+});
+
+describe("closedHeight", () => {
+	test("an attached sheet closes at zero", () => {
+		expect(closedHeight(0)).toBe(0);
+	});
+
+	test("a detached sheet closes below its resting line, so its top clears the container edge", () => {
+		expect(closedHeight(50)).toBe(-50);
+	});
+});
+
+describe("availableHeight", () => {
+	test("the container less the resting bottom", () => {
+		expect(availableHeight(800, 0)).toBe(800);
+		expect(availableHeight(800, 50)).toBe(750);
+	});
+
+	test("an unmeasured container has nothing available", () => {
+		expect(availableHeight(-1, 0)).toBe(0);
+	});
+});

package/src/core/geometry/closed-height.ts

@@ -0,0 +1,29 @@
+/**
+ * How far above the container's bottom edge the sheet rests: nothing when
+ * attached, the detached `bottomOffset` plus the safe-area inset when
+ * floating. Every height in the engine is measured up from here.
+ */
+export function restingBottom(detached: boolean, bottomOffset: number, bottomInset: number): number {
+	"worklet";
+	if (!detached) return 0;
+	const offset = bottomOffset > 0 ? bottomOffset : 0;
+	const inset = bottomInset > 0 ? bottomInset : 0;
+	return offset + inset;
+}
+
+/**
+ * The height at which the sheet is closed: `−restingBottom`, so a detached
+ * sheet's top edge clears the container's bottom edge and a
+ * `positionFor(C, restingBottom, closedHeight)` is exactly `C`.
+ */
+export function closedHeight(restingBottomValue: number): number {
+	"worklet";
+	return 0 - restingBottomValue;
+}
+
+/** The height the sheet may occupy — the container less the resting bottom, never negative. */
+export function availableHeight(containerHeight: number, restingBottomValue: number): number {
+	"worklet";
+	const available = containerHeight - restingBottomValue;
+	return available > 0 ? available : 0;
+}

package/src/core/geometry/detached-frame.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test";
+import { closedHeight } from "./closed-height";
+import { DETACHED_DEFAULTS, detachedFrame, resolveDetached } from "./detached-frame";
+import { positionFor } from "./position";
+
+describe("resolveDetached", () => {
+	test("undefined and false are attached", () => {
+		expect(resolveDetached(undefined)).toBeNull();
+		expect(resolveDetached(false)).toBeNull();
+	});
+
+	test("true takes the defaults", () => {
+		expect(resolveDetached(true)).toEqual(DETACHED_DEFAULTS);
+		expect(DETACHED_DEFAULTS).toEqual({ horizontalMargin: 16, bottomOffset: 16 });
+	});
+
+	test("an object fills in whichever default it leaves out", () => {
+		expect(resolveDetached({ horizontalMargin: 24 })).toEqual({ horizontalMargin: 24, bottomOffset: 16 });
+		expect(resolveDetached({ bottomOffset: 0 })).toEqual({ horizontalMargin: 16, bottomOffset: 0 });
+	});
+});
+
+describe("detachedFrame", () => {
+	test("the card is inset by the margin on both sides", () => {
+		expect(detachedFrame({ containerWidth: 390, horizontalMargin: 16, bottomOffset: 16, bottomInset: 34 })).toEqual({
+			left: 16,
+			width: 358,
+			restingBottom: 50,
+		});
+	});
+
+	test("a margin wider than the container collapses the width to zero rather than going negative", () => {
+		expect(detachedFrame({ containerWidth: 20, horizontalMargin: 16, bottomOffset: 16, bottomInset: 0 }).width).toBe(0);
+	});
+
+	test("an unmeasured width yields an empty frame", () => {
+		expect(detachedFrame({ containerWidth: -1, horizontalMargin: 16, bottomOffset: 16, bottomInset: 0 }).width).toBe(0);
+	});
+
+	test("closed, a detached sheet's translateY is the full container height — entirely off-screen", () => {
+		const frame = detachedFrame({ containerWidth: 390, horizontalMargin: 16, bottomOffset: 16, bottomInset: 34 });
+		expect(positionFor(800, frame.restingBottom, closedHeight(frame.restingBottom))).toBe(800);
+	});
+
+	test("open, a detached sheet's bottom edge floats restingBottom above the container edge", () => {
+		const frame = detachedFrame({ containerWidth: 390, horizontalMargin: 16, bottomOffset: 16, bottomInset: 34 });
+		const top = positionFor(800, frame.restingBottom, 300);
+		expect(800 - (top + 300)).toBe(50);
+	});
+});

package/src/core/geometry/detached-frame.ts

@@ -0,0 +1,49 @@
+/** The `detached` prop as the consumer writes it. */
+export type DetachedProp = boolean | { horizontalMargin?: number; bottomOffset?: number } | undefined;
+
+/** A detached sheet's geometry, every field filled in. */
+export type DetachedOptions = { horizontalMargin: number; bottomOffset: number };
+
+/** What `detached: true` means. */
+export const DETACHED_DEFAULTS: DetachedOptions = { horizontalMargin: 16, bottomOffset: 16 };
+
+/** The `detached` prop resolved: `null` when attached, full options when floating. */
+export function resolveDetached(detached: DetachedProp): DetachedOptions | null {
+	if (detached === undefined || detached === false) return null;
+	if (detached === true) return DETACHED_DEFAULTS;
+	return {
+		horizontalMargin: detached.horizontalMargin ?? DETACHED_DEFAULTS.horizontalMargin,
+		bottomOffset: detached.bottomOffset ?? DETACHED_DEFAULTS.bottomOffset,
+	};
+}
+
+export type DetachedFrameInput = {
+	containerWidth: number;
+	horizontalMargin: number;
+	bottomOffset: number;
+	/** The safe-area inset the card floats above. */
+	bottomInset: number;
+};
+
+export type DetachedFrame = {
+	left: number;
+	width: number;
+	/** How far above the container's bottom edge the card rests. */
+	restingBottom: number;
+};
+
+/**
+ * Where a detached card sits: inset by the margin on both sides, resting
+ * `bottomOffset` above the safe-area inset. Closed is then
+ * `translateY = containerHeight` — the card's top edge exactly at the
+ * container's bottom, resting line included — because `closedHeight` is
+ * `−restingBottom`.
+ */
+export function detachedFrame(input: DetachedFrameInput): DetachedFrame {
+	"worklet";
+	const margin = input.horizontalMargin > 0 ? input.horizontalMargin : 0;
+	const width = input.containerWidth - margin * 2;
+	const offset = input.bottomOffset > 0 ? input.bottomOffset : 0;
+	const inset = input.bottomInset > 0 ? input.bottomInset : 0;
+	return { left: margin, width: width > 0 ? width : 0, restingBottom: offset + inset };
+}

package/src/core/geometry/position.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, test } from "bun:test";
+import { positionFor } from "./position";
+
+describe("positionFor", () => {
+	test("a closed attached sheet sits at the container's bottom edge", () => {
+		expect(positionFor(800, 0, 0)).toBe(800);
+	});
+
+	test("height is measured up from the resting bottom line", () => {
+		expect(positionFor(800, 0, 300)).toBe(500);
+		expect(positionFor(800, 32, 300)).toBe(468);
+	});
+
+	test("a detached sheet closed is fully off-screen, resting line included", () => {
+		expect(positionFor(800, 32, -32)).toBe(800);
+	});
+
+	test("filling the available height puts the top at zero", () => {
+		expect(positionFor(800, 32, 768)).toBe(0);
+	});
+});

package/src/core/geometry/position.ts

@@ -0,0 +1,13 @@
+/**
+ * The `translateY` that puts `height` pixels of sheet above its resting bottom
+ * line, inside a container `containerHeight` tall.
+ *
+ * Height space is the engine's coordinate system; this is the one place it is
+ * converted to a transform. A detached sheet rests `restingBottom` above the
+ * container's bottom edge, so its closed position is the full container
+ * height and every detent sits that much higher.
+ */
+export function positionFor(containerHeight: number, restingBottom: number, height: number): number {
+	"worklet";
+	return containerHeight - restingBottom - height;
+}

package/src/core/geometry/surface-height.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "bun:test";
+import { surfaceHeight } from "./surface-height";
+
+describe("surfaceHeight", () => {
+	test("between the detents the surface follows the height", () => {
+		expect(surfaceHeight(300, 200, 400)).toBe(300);
+		expect(surfaceHeight(200, 200, 400)).toBe(200);
+		expect(surfaceHeight(400, 200, 400)).toBe(400);
+	});
+
+	test("below the first detent the surface keeps the detent's height, so a close slides the card rigidly", () => {
+		expect(surfaceHeight(120, 200, 400)).toBe(200);
+		expect(surfaceHeight(0, 200, 400)).toBe(200);
+		expect(surfaceHeight(-50, 200, 400)).toBe(200);
+	});
+
+	test("above the last detent the surface keeps the detent's height, so an over-drag lifts the card rigidly", () => {
+		expect(surfaceHeight(450, 200, 400)).toBe(400);
+	});
+
+	test("one detent is a rigid card at every height", () => {
+		expect(surfaceHeight(10, 320, 320)).toBe(320);
+		expect(surfaceHeight(500, 320, 320)).toBe(320);
+	});
+
+	test("no detents yet: never negative, never above zero", () => {
+		expect(surfaceHeight(-16, 0, 0)).toBe(0);
+		expect(surfaceHeight(-16, -16, -16)).toBe(0);
+	});
+});

package/src/core/geometry/surface-height.ts

@@ -0,0 +1,22 @@
+/**
+ * How tall a detached card's surface is right now.
+ *
+ * Between its detents the card resizes: its bottom edge stays on the resting
+ * line and the top follows `height`. Below the first detent — a drag down to
+ * close, the close animation, a rubber-band under the lowest detent — and
+ * above the last — an over-drag, a keyboard lift — the card is a rigid body:
+ * its surface keeps the detent's height and `translateY` alone moves it, so
+ * the bottom corners slide through the gap and off-screen intact rather than
+ * collapsing onto the resting line.
+ *
+ * An attached sheet never needs this: its panel is as tall as the frame and
+ * its bottom edge is always off-screen.
+ */
+export function surfaceHeight(height: number, lowestDetent: number, highestDetent: number): number {
+	"worklet";
+	const low = lowestDetent > 0 ? lowestDetent : 0;
+	const high = highestDetent > low ? highestDetent : low;
+	if (height < low) return low;
+	if (height > high) return high;
+	return height;
+}

package/src/core/haptic/crossed-detent.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { crossedDetent, detentUnder } from "./crossed-detent";
+
+const detents = [200, 400, 800];
+
+describe("detentUnder", () => {
+	test("the index of the highest detent at or below the height, -1 below the first", () => {
+		expect(detentUnder(100, detents)).toBe(-1);
+		expect(detentUnder(200, detents)).toBe(0);
+		expect(detentUnder(399, detents)).toBe(0);
+		expect(detentUnder(400, detents)).toBe(1);
+		expect(detentUnder(900, detents)).toBe(2);
+	});
+
+	test("a hair below a detent counts as on it, so a settled spring is not a phantom crossing", () => {
+		expect(detentUnder(399.8, detents)).toBe(1);
+	});
+
+	test("with no detents nothing is ever under the sheet", () => {
+		expect(detentUnder(300, [])).toBe(-1);
+	});
+});
+
+describe("crossedDetent", () => {
+	test("true when the drag crosses a detent in either direction", () => {
+		expect(crossedDetent(0, 401, detents)).toBe(true);
+		expect(crossedDetent(1, 399, detents)).toBe(true);
+	});
+
+	test("false while the drag stays between the same detents", () => {
+		expect(crossedDetent(0, 250, detents)).toBe(false);
+		expect(crossedDetent(0, 399, detents)).toBe(false);
+	});
+
+	test("crossing the lowest detent downward counts, so a haptic fires on the way to closed too", () => {
+		expect(crossedDetent(0, 150, detents)).toBe(true);
+	});
+
+	test("a frame that skips a detent is one crossing, and detentUnder says where it landed", () => {
+		expect(crossedDetent(-1, 850, detents)).toBe(true);
+		expect(detentUnder(850, detents)).toBe(2);
+	});
+});

package/src/core/haptic/crossed-detent.ts

@@ -0,0 +1,33 @@
+/** Settle tolerance: a spring at rest is within this of its target. */
+const SETTLE_EPSILON = 0.5;
+
+/**
+ * The index of the highest detent at or below `height`, `-1` below the
+ * first. A hair under a detent counts as on it, so a spring settling a
+ * fraction short is not a crossing.
+ */
+export function detentUnder(height: number, detents: readonly number[]): number {
+	"worklet";
+	let under = -1;
+	for (let index = 0; index < detents.length; index += 1) {
+		if (height + SETTLE_EPSILON >= (detents[index] as number)) under = index;
+		else break;
+	}
+	return under;
+}
+
+/**
+ * Whether a drag crossed a detent this frame: the detent now under the sheet
+ * differs from `lastIndex`, the one the pan stored last frame. On `true` the
+ * pan fires its haptic and stores `detentUnder(height, detents)`. A frame
+ * that leaps two detents is one crossing, not a burst.
+ */
+export function crossedDetent(lastIndex: number, height: number, detents: readonly number[]): boolean {
+	"worklet";
+	let under = -1;
+	for (let index = 0; index < detents.length; index += 1) {
+		if (height + SETTLE_EPSILON >= (detents[index] as number)) under = index;
+		else break;
+	}
+	return under !== lastIndex;
+}