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

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

@@ -1,21 +1,21 @@
 /**
  * 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
+ * Between its snap points the card resizes: its bottom edge stays on the resting
+ * line and the top follows `height`. Below the first snap point — a drag down to
+ * close, the close animation, a rubber-band under the lowest snap point — 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
+ * its surface keeps the snap point'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 {
+export function surfaceHeight(height: number, lowestSnapPoint: number, highestSnapPoint: number): number {
 	"worklet";
-	const low = lowestDetent > 0 ? lowestDetent : 0;
-	const high = highestDetent > low ? highestDetent : low;
+	const low = lowestSnapPoint > 0 ? lowestSnapPoint : 0;
+	const high = highestSnapPoint > low ? highestSnapPoint : low;
 	if (height < low) return low;
 	if (height > high) return high;
 	return height;

package/src/core/haptic/crossed-snap-point.test.ts

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

package/src/core/haptic/crossed-snap-point.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 snap point at or below `height`, `-1` below the
+ * first. A hair under a snap point counts as on it, so a spring settling a
+ * fraction short is not a crossing.
+ */
+export function snapPointUnder(height: number, snapPoints: readonly number[]): number {
+	"worklet";
+	let under = -1;
+	for (let index = 0; index < snapPoints.length; index += 1) {
+		if (height + SETTLE_EPSILON >= (snapPoints[index] as number)) under = index;
+		else break;
+	}
+	return under;
+}
+
+/**
+ * Whether a drag crossed a snap point this frame: the snap point now under the sheet
+ * differs from `lastIndex`, the one the pan stored last frame. On `true` the
+ * pan fires its haptic and stores `snapPointUnder(height, snapPoints)`. A frame
+ * that leaps two snap points is one crossing, not a burst.
+ */
+export function crossedSnapPoint(lastIndex: number, height: number, snapPoints: readonly number[]): boolean {
+	"worklet";
+	let under = -1;
+	for (let index = 0; index < snapPoints.length; index += 1) {
+		if (height + SETTLE_EPSILON >= (snapPoints[index] as number)) under = index;
+		else break;
+	}
+	return under !== lastIndex;
+}

package/src/core/index.ts

@@ -9,12 +9,6 @@ export {
 	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";
@@ -32,7 +26,7 @@ export {
 } from "./geometry/detached-frame";
 export { positionFor } from "./geometry/position";
 export { surfaceHeight } from "./geometry/surface-height";
-export { crossedDetent, detentUnder } from "./haptic/crossed-detent";
+export { crossedSnapPoint, snapPointUnder } from "./haptic/crossed-snap-point";
 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";
@@ -71,13 +65,12 @@ export {
 	type ListOwnsReleaseInput,
 	listDragHeight,
 	listOwnsRelease,
-	restingDetent,
+	restingSnapPoint,
 	scrollLockTarget,
 } from "./scroll/scroll-pan";
 export {
 	type AnimationSource,
 	CLOSED_INDEX,
-	type DetentSpec,
 	GESTURE_SOURCE,
 	type GestureSource,
 	type KeyboardBehavior,
@@ -88,5 +81,17 @@ export {
 	SHEET_STATE,
 	type SheetIntent,
 	type SheetState,
+	type SnapPointSpec,
 	UNMEASURED,
 } from "./sheet.types";
+export { type DynamicSnapPointInput, dynamicSnapPoint } from "./snap-points/dynamic-snap-point";
+export { heightForIndex, indexForHeight } from "./snap-points/index-for-height";
+export {
+	normalizeSnapPoints,
+	type ParsedSnapPoint,
+	parseSnapPoint,
+	type SnapPointError,
+} from "./snap-points/normalize-snap-points";
+export { resistOverDrag } from "./snap-points/over-drag";
+export { type SelectSnapHeightInput, selectSnapHeight } from "./snap-points/select-snap-height";
+export { sheetState } from "./snap-points/sheet-state";

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

@@ -3,7 +3,7 @@ export type LayoutReadyInput = {
 	handleHeight: number;
 	contentHeight: number;
 	footerContentHeight: number;
-	/** Whether the content's height is a detent, and so has to be known. */
+	/** Whether the content's height is a snap point, and so has to be known. */
 	dynamicSizing: boolean;
 	hasFooter: boolean;
 };

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

@@ -6,7 +6,7 @@ const ready: IntentState = {
 	currentIndex: -1,
 	base: 0,
 	layoutReady: true,
-	detents: [200, 400, 800],
+	snapPoints: [200, 400, 800],
 	closedHeight: 0,
 	maxHeight: 800,
 	initialIndex: 0,
@@ -14,7 +14,7 @@ const ready: IntentState = {
 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 unmeasured: IntentState = { ...ready, layoutReady: false, snapPoints: [] };
 
 const intent = (kind: SheetIntent["kind"], extra: Record<string, unknown> = {}): SheetIntent =>
 	({ id: 1, kind, ...extra }) as SheetIntent;
@@ -26,7 +26,7 @@ describe("resolveIntent", () => {
 			expect(resolveIntent({ ...ready, initialIndex: 2 }, intent("open"))).toEqual({ action: "animate", target: 800 });
 		});
 
-		test("an initial index past the last detent lands on the last", () => {
+		test("an initial index past the last snap point lands on the last", () => {
 			expect(resolveIntent({ ...ready, initialIndex: 9 }, intent("open"))).toEqual({ action: "animate", target: 800 });
 		});
 
@@ -40,7 +40,7 @@ describe("resolveIntent", () => {
 		});
 
 		test("with nothing to open to there is nothing to do", () => {
-			expect(resolveIntent({ ...ready, detents: [] }, intent("open"))).toBeNull();
+			expect(resolveIntent({ ...ready, snapPoints: [] }, intent("open"))).toBeNull();
 		});
 	});
 
@@ -90,7 +90,7 @@ describe("resolveIntent", () => {
 	});
 
 	describe("snapToIndex", () => {
-		test("animates to the detent at that index", () => {
+		test("animates to the snap point at that index", () => {
 			expect(resolveIntent(open, intent("snapToIndex", { index: 2 }))).toEqual({ action: "animate", target: 800 });
 		});
 
@@ -110,7 +110,7 @@ describe("resolveIntent", () => {
 	});
 
 	describe("snapToPosition", () => {
-		test("a pixel height animates as written, without becoming a detent", () => {
+		test("a pixel height animates as written, without becoming a snap point", () => {
 			expect(resolveIntent(open, intent("snapToPosition", { position: 333 }))).toEqual({
 				action: "animate",
 				target: 333,
@@ -146,7 +146,7 @@ describe("resolveIntent", () => {
 	});
 
 	describe("expand and collapse", () => {
-		test("expand animates to the highest detent, collapse to the lowest", () => {
+		test("expand animates to the highest snap point, collapse to the lowest", () => {
 			expect(resolveIntent(open, intent("expand"))).toEqual({ action: "animate", target: 800 });
 			expect(resolveIntent(open, intent("collapse"))).toEqual({ action: "animate", target: 200 });
 		});
@@ -155,9 +155,9 @@ describe("resolveIntent", () => {
 			expect(resolveIntent(ready, intent("expand"))).toEqual({ action: "animate", target: 800 });
 		});
 
-		test("both wait for layout and refuse an empty detent list", () => {
+		test("both wait for layout and refuse an empty snap point list", () => {
 			expect(resolveIntent(unmeasured, intent("expand"))).toEqual({ action: "wait" });
-			expect(resolveIntent({ ...ready, detents: [] }, intent("collapse"))).toBeNull();
+			expect(resolveIntent({ ...ready, snapPoints: [] }, intent("collapse"))).toBeNull();
 		});
 	});
 });

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

@@ -14,8 +14,8 @@ export type IntentState = {
 	 */
 	base: number;
 	layoutReady: boolean;
-	/** Ascending, normalised detents. */
-	detents: readonly number[];
+	/** Ascending, normalised snap points. */
+	snapPoints: readonly number[];
 	closedHeight: number;
 	/** The height the sheet may occupy — what a `%` position resolves against. */
 	maxHeight: number;
@@ -42,17 +42,17 @@ export type IntentResolution =
  * 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.
+ * `maxHeight` and clamps, without ever adding a snap point.
  *
  * 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`
+ * and re-implements the little it needs of `heightForIndex` and `parseSnapPoint`
  * 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;
+	const snapPoints = state.snapPoints;
+	const count = snapPoints.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.
@@ -71,13 +71,13 @@ export function resolveIntent(state: IntentState, intent: SheetIntent): IntentRe
 		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 };
+		return { action: "animate", target: snapPoints[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 };
+		return { action: "animate", target: snapPoints[index] as number };
 	}
 	if (intent.kind === "snapToPosition") {
 		const position = intent.position;
@@ -93,6 +93,6 @@ export function resolveIntent(state: IntentState, intent: SheetIntent): IntentRe
 		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 };
+	if (intent.kind === "expand") return { action: "animate", target: snapPoints[count - 1] as number };
+	return { action: "animate", target: snapPoints[0] as number };
 }

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

@@ -17,7 +17,7 @@ const TOLERANCE = 2;
  * 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.
+ * as a smaller container with every percent snap point 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

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

@@ -18,10 +18,10 @@ export type KeyboardStepInput = {
 /**
  * What the behaviour reaction does this frame.
  *
- * `apply` — snap for the keyboard: `extend` to the highest detent,
+ * `apply` — snap for the keyboard: `extend` to the highest snap point,
  * `fillParent` to the container. `restore` — the keyboard is leaving or focus
  * left the sheet, and `keyboardBlurBehavior: "restore"` sends the sheet back
- * to the detent it held before. `release` — the same moment under
+ * to the snap point it held before. `release` — the same moment under
  * `blurBehavior: "none"`: nothing moves, but the record clears so the next
  * rise applies again. `null` — nothing.
  */

package/src/core/machine/machine.types.ts

@@ -8,7 +8,7 @@
  * controller.
  */
 import type { Result } from "../result";
-import type { DetentSpec } from "../sheet.types";
+import type { SnapPointSpec } from "../sheet.types";
 
 /** The least an event can be. Discriminate on `type`; carry anything else. */
 export type SheetEvent = { type: string };
@@ -37,7 +37,7 @@ export type SheetTransitionTarget<S extends string, C, E extends SheetEvent> = S
  */
 export type SheetStateNode<S extends string, C, E extends SheetEvent> = {
 	on?: { [T in E["type"]]?: SheetTransitionTarget<S, C, Extract<E, { type: T }>> };
-	snapPoints?: readonly DetentSpec[];
+	snapPoints?: readonly SnapPointSpec[];
 	dismissible?: boolean;
 	direction?: SheetStepDirection;
 };

package/src/core/machine/step-transition.ts

@@ -6,7 +6,7 @@
  * frame from it here. Kept in core so the three transitions are a table a
  * test can read rather than three `useAnimatedStyle`s a device has to show.
  */
-import type { DetentSpec } from "../sheet.types";
+import type { SnapPointSpec } from "../sheet.types";
 import type { SheetEvent, SheetStateNode, SheetStepDirection } from "./machine.types";
 
 /** The `transition` prop of `BottomSheet.Steps`. */
@@ -47,7 +47,7 @@ export function stepFrame(
 
 /** What a step asks the root to change while it is current. */
 export type SheetStepOverride = {
-	snapPoints: readonly DetentSpec[] | undefined;
+	snapPoints: readonly SnapPointSpec[] | undefined;
 	dismissible: boolean | undefined;
 };
 

package/src/core/scroll/scroll-lock.test.ts

@@ -3,12 +3,12 @@ import { SHEET_STATE } from "../sheet.types";
 import { contentPanDrivesSheet, shouldLockScroll } from "./scroll-lock";
 
 describe("shouldLockScroll", () => {
-	test("locked below the highest detent — a drag on the list moves the sheet, not the rows", () => {
+	test("locked below the highest snap point — a drag on the list moves the sheet, not the rows", () => {
 		expect(shouldLockScroll(SHEET_STATE.CLOSED, true)).toBe(true);
 		expect(shouldLockScroll(SHEET_STATE.OPENED, true)).toBe(true);
 	});
 
-	test("unlocked at the highest detent and beyond", () => {
+	test("unlocked at the highest snap point and beyond", () => {
 		expect(shouldLockScroll(SHEET_STATE.EXTENDED, true)).toBe(false);
 		expect(shouldLockScroll(SHEET_STATE.OVER_EXTENDED, true)).toBe(false);
 		expect(shouldLockScroll(SHEET_STATE.FILL, true)).toBe(false);

package/src/core/scroll/scroll-lock.ts

@@ -3,8 +3,8 @@ import { SHEET_STATE, type SheetState } from "../sheet.types";
 /**
  * Whether a scrollable inside the sheet is pinned in place.
  *
- * Below the highest detent a drag on the list moves the sheet, not the rows,
- * so the list is held at its lock offset every frame. At the highest detent
+ * Below the highest snap point a drag on the list moves the sheet, not the rows,
+ * so the list is held at its lock offset every frame. At the highest snap point
  * and beyond it scrolls. With the content pan disabled there is nothing else
  * the drag could do, so the list is never locked.
  */

package/src/core/scroll/scroll-pan.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { SCROLLABLE_TYPE } from "../sheet.types";
-import { listDragHeight, listOwnsRelease, restingDetent, scrollLockTarget } from "./scroll-pan";
+import { listDragHeight, listOwnsRelease, restingSnapPoint, scrollLockTarget } from "./scroll-pan";
 
 describe("listDragHeight", () => {
 	const highest = 600;
@@ -41,7 +41,7 @@ describe("listDragHeight", () => {
 describe("listOwnsRelease", () => {
 	const highest = 600;
 
-	test("a content pan released with the list scrolled and the sheet at the highest detent is the list's", () => {
+	test("a content pan released with the list scrolled and the sheet at the highest snap point is the list's", () => {
 		expect(listOwnsRelease({ scrollable: true, offset: 120, base: 600, highest })).toBe(true);
 		expect(listOwnsRelease({ scrollable: true, offset: 120, base: 599.7, highest })).toBe(true);
 	});
@@ -51,7 +51,7 @@ describe("listOwnsRelease", () => {
 		expect(listOwnsRelease({ scrollable: true, offset: -12, base: 600, highest })).toBe(false);
 	});
 
-	test("below the highest detent the sheet takes it whatever the offset", () => {
+	test("below the highest snap point the sheet takes it whatever the offset", () => {
 		expect(listOwnsRelease({ scrollable: true, offset: 120, base: 300, highest })).toBe(false);
 	});
 
@@ -60,22 +60,22 @@ describe("listOwnsRelease", () => {
 	});
 });
 
-describe("restingDetent", () => {
-	const detents = [200, 400, 600];
+describe("restingSnapPoint", () => {
+	const snapPoints = [200, 400, 600];
 
-	test("a base on a detent, or within the settle tolerance of one, is resting on it", () => {
-		expect(restingDetent(600, detents)).toBe(600);
-		expect(restingDetent(599.7, detents)).toBe(600);
-		expect(restingDetent(400.4, detents)).toBe(400);
+	test("a base on a snap point, or within the settle tolerance of one, is resting on it", () => {
+		expect(restingSnapPoint(600, snapPoints)).toBe(600);
+		expect(restingSnapPoint(599.7, snapPoints)).toBe(600);
+		expect(restingSnapPoint(400.4, snapPoints)).toBe(400);
 	});
 
-	test("a base between detents rests on none", () => {
-		expect(restingDetent(500, detents)).toBeNull();
-		expect(restingDetent(598, detents)).toBeNull();
+	test("a base between snap points rests on none", () => {
+		expect(restingSnapPoint(500, snapPoints)).toBeNull();
+		expect(restingSnapPoint(598, snapPoints)).toBeNull();
 	});
 
-	test("with no detents nothing can be rested on", () => {
-		expect(restingDetent(0, [])).toBeNull();
+	test("with no snap points nothing can be rested on", () => {
+		expect(restingSnapPoint(0, [])).toBeNull();
 	});
 });
 

package/src/core/scroll/scroll-pan.ts

@@ -7,7 +7,7 @@ export type ListDragInput = {
 	startOffset: number;
 	/**
 	 * Whether the list is being held by the lock at that offset — it began
-	 * scrolled *and* below the highest detent — and the sheet has not reached
+	 * scrolled *and* below the highest snap point — and the sheet has not reached
 	 * the top yet this gesture. A held list scrolls nothing, so it has no
 	 * budget to spend.
 	 */
@@ -45,43 +45,43 @@ export type ListOwnsReleaseInput = {
 	highest: number;
 };
 
-/** Settle tolerance: a sheet within this of a detent is on it. */
-const AT_DETENT = 0.5;
+/** Settle tolerance: a sheet within this of a snap point is on it. */
+const AT_SNAP_POINT = 0.5;
 
 /**
  * Whether a released content pan belongs to the list rather than the sheet:
- * the sheet is on its highest detent and the list is scrolled, so the finger
+ * the sheet is on its highest snap point and the list is scrolled, so the finger
  * was scrolling rows and the release velocity is the list's momentum, not a
  * snap. Snapping here is what made the library this replaces hop from the
- * top to a lower detent under a series of interrupted scrolls.
+ * top to a lower snap point under a series of interrupted scrolls.
  */
 export function listOwnsRelease(input: ListOwnsReleaseInput): boolean {
 	"worklet";
 	if (!input.scrollable) return false;
 	if (input.offset <= 0) return false;
-	return input.base >= input.highest - AT_DETENT;
+	return input.base >= input.highest - AT_SNAP_POINT;
 }
 
 /**
- * The detent a base is resting on — the one within the settle tolerance of
+ * The snap point a base is resting on — the one within the settle tolerance of
  * it — or `null` when it sits between two.
  *
  * A release the list owns still has to settle the sheet's bookkeeping: the
  * finger carried the sheet to the top and kept going, so no animation ran and
- * nothing wrote `currentIndex`. The pan asks which detent `base` is on and
- * settles there without motion; between detents it snaps instead.
+ * nothing wrote `currentIndex`. The pan asks which snap point `base` is on and
+ * settles there without motion; between snap points it snaps instead.
  */
-export function restingDetent(base: number, detents: readonly number[]): number | null {
+export function restingSnapPoint(base: number, snapPoints: readonly number[]): number | null {
 	"worklet";
-	for (let index = 0; index < detents.length; index += 1) {
-		const detent = detents[index] as number;
-		if (Math.abs(base - detent) <= AT_DETENT) return detent;
+	for (let index = 0; index < snapPoints.length; index += 1) {
+		const snapPoint = snapPoints[index] as number;
+		if (Math.abs(base - snapPoint) <= AT_SNAP_POINT) return snapPoint;
 	}
 	return null;
 }
 
 /**
- * Where a list is held while the sheet is below its highest detent.
+ * Where a list is held while the sheet is below its highest snap point.
  *
  * Wherever it was when the lock engaged, never above the top — a handle drag
  * or a `snapToIndex` on a scrolled list keeps its rows. A content pan is the

package/src/core/sheet.types.ts

@@ -8,13 +8,13 @@
  */
 
 /**
- * A detent as the consumer writes it — pixels of sheet visible above its
+ * A snap point as the consumer writes it — pixels of sheet visible above its
  * resting bottom line, or a percentage of the height available to the sheet.
  *
- * Height space throughout: `0` is closed, detents ascend, and `translateY` is
+ * Height space throughout: `0` is closed, snap points ascend, and `translateY` is
  * derived from a height only at the moment a view needs it.
  */
-export type DetentSpec = number | `${number}%`;
+export type SnapPointSpec = number | `${number}%`;
 
 /** What the sheet does when a keyboard it owns appears. */
 export type KeyboardBehavior = "interactive" | "extend" | "fillParent" | "none";
@@ -47,7 +47,7 @@ export type SheetIntent =
 	| { id: number; kind: "close" }
 	| { id: number; kind: "forceClose" }
 	| { id: number; kind: "snapToIndex"; index: number }
-	| { id: number; kind: "snapToPosition"; position: DetentSpec }
+	| { id: number; kind: "snapToPosition"; position: SnapPointSpec }
 	| { id: number; kind: "expand" }
 	| { id: number; kind: "collapse" };
 
@@ -60,7 +60,7 @@ export const GESTURE_SOURCE = {
 
 export type GestureSource = (typeof GESTURE_SOURCE)[keyof typeof GESTURE_SOURCE];
 
-/** Where the sheet sits relative to its detents. */
+/** Where the sheet sits relative to its snap points. */
 export const SHEET_STATE = {
 	CLOSED: 0,
 	OPENED: 1,

package/src/core/snap-points/dynamic-snap-point.test.ts

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

package/src/core/{detents/dynamic-detent.ts → snap-points/dynamic-snap-point.ts}

@@ -1,5 +1,5 @@
-/** Everything the dynamic detent is a sum of, in height space. */
-export type DynamicDetentInput = {
+/** Everything the dynamic snap point is a sum of, in height space. */
+export type DynamicSnapPointInput = {
 	/** Measured handle height; `UNMEASURED` counts as zero. */
 	handleHeight: number;
 	/** Measured content height; `UNMEASURED` counts as zero. */
@@ -11,19 +11,19 @@ export type DynamicDetentInput = {
 	hasFooter: boolean;
 	/** The height the sheet may occupy. */
 	available: number;
-	/** An optional cap on the whole detent, below `available`. */
+	/** An optional cap on the whole snap point, below `available`. */
 	maxDynamicContentSize?: number;
 };
 
 /**
- * The detent a sheet sized to its content settles at.
+ * The snap point a sheet sized to its content settles at.
  *
  * Handle, content and — unlike the library this replaces — the footer's
  * content are all in, and the safe-area band exactly once: it lives inside the
  * footer when there is one and under the content when there is not. Capped by
  * `maxDynamicContentSize` and always by `available`.
  */
-export function dynamicDetent(input: DynamicDetentInput): number {
+export function dynamicSnapPoint(input: DynamicSnapPointInput): number {
 	"worklet";
 	const handle = input.handleHeight > 0 ? input.handleHeight : 0;
 	const content = input.contentHeight > 0 ? input.contentHeight : 0;