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

package/src/core/snap-points/index-for-height.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "bun:test";
+import { heightForIndex, indexForHeight } from "./index-for-height";
+
+const snapPoints = [200, 400, 800];
+
+describe("indexForHeight", () => {
+	test("each snap point maps to its own integer index", () => {
+		expect(indexForHeight(200, snapPoints, 0)).toBe(0);
+		expect(indexForHeight(400, snapPoints, 0)).toBe(1);
+		expect(indexForHeight(800, snapPoints, 0)).toBe(2);
+	});
+
+	test("the closed height is -1", () => {
+		expect(indexForHeight(0, snapPoints, 0)).toBe(-1);
+		expect(indexForHeight(-32, snapPoints, -32)).toBe(-1);
+	});
+
+	test("between snap points the index is fractional, so the backdrop can follow a drag", () => {
+		expect(indexForHeight(100, snapPoints, 0)).toBeCloseTo(-0.5);
+		expect(indexForHeight(300, snapPoints, 0)).toBeCloseTo(0.5);
+		expect(indexForHeight(600, snapPoints, 0)).toBeCloseTo(1.5);
+	});
+
+	test("clamps beyond either end — an over-drag never reports a snap point that does not exist", () => {
+		expect(indexForHeight(-100, snapPoints, 0)).toBe(-1);
+		expect(indexForHeight(900, snapPoints, 0)).toBe(2);
+	});
+
+	test("with no snap points every height is closed", () => {
+		expect(indexForHeight(300, [], 0)).toBe(-1);
+	});
+
+	test("a snap point coinciding with the closed height does not divide by zero", () => {
+		expect(Number.isFinite(indexForHeight(0, [0, 400], 0))).toBe(true);
+		expect(indexForHeight(400, [0, 400], 0)).toBe(1);
+	});
+});
+
+describe("heightForIndex", () => {
+	test("round-trips every snap point", () => {
+		for (const [index, height] of snapPoints.entries()) {
+			expect(heightForIndex(index, snapPoints, 0)).toBe(height);
+			expect(indexForHeight(heightForIndex(index, snapPoints, 0), snapPoints, 0)).toBe(index);
+		}
+	});
+
+	test("-1 is the closed height, resting line included", () => {
+		expect(heightForIndex(-1, snapPoints, 0)).toBe(0);
+		expect(heightForIndex(-1, snapPoints, -32)).toBe(-32);
+	});
+
+	test("clamps an out-of-range index to the nearest end", () => {
+		expect(heightForIndex(5, snapPoints, 0)).toBe(800);
+		expect(heightForIndex(-3, snapPoints, 0)).toBe(0);
+	});
+
+	test("a fractional index interpolates, mirroring indexForHeight", () => {
+		expect(heightForIndex(0.5, snapPoints, 0)).toBe(300);
+		expect(heightForIndex(-0.5, snapPoints, 0)).toBe(100);
+	});
+
+	test("with no snap points every index is closed", () => {
+		expect(heightForIndex(0, [], -16)).toBe(-16);
+	});
+});

package/src/core/{detents → snap-points}/index-for-height.ts

@@ -1,21 +1,21 @@
 import { CLOSED_INDEX } from "../sheet.types";
 
 /**
- * The index a height corresponds to: `-1` closed, `0` the lowest detent,
+ * The index a height corresponds to: `-1` closed, `0` the lowest snap point,
  * fractional in between, clamped at both ends.
  *
- * Piecewise-linear over `[closedHeight, ...detents]` → `[-1, 0, 1, …]`. It is
+ * Piecewise-linear over `[closedHeight, ...snapPoints]` → `[-1, 0, 1, …]`. It is
  * fed `base`, never `height`, so a keyboard lift moves the sheet without
  * moving the index or the backdrop that follows it.
  */
-export function indexForHeight(height: number, detents: readonly number[], closedHeight: number): number {
+export function indexForHeight(height: number, snapPoints: readonly number[], closedHeight: number): number {
 	"worklet";
-	const count = detents.length;
+	const count = snapPoints.length;
 	if (count === 0 || height <= closedHeight) return CLOSED_INDEX;
 
 	let lower = closedHeight;
 	for (let index = 0; index < count; index += 1) {
-		const upper = detents[index] as number;
+		const upper = snapPoints[index] as number;
 		if (height <= upper) {
 			const span = upper - lower;
 			if (span <= 0) return index;
@@ -28,17 +28,17 @@ export function indexForHeight(height: number, detents: readonly number[], close
 
 /**
  * The inverse: the height at an index, `-1` being the closed height. Integers
- * land on detents, fractions interpolate, and an out-of-range index clamps.
+ * land on snap points, fractions interpolate, and an out-of-range index clamps.
  */
-export function heightForIndex(index: number, detents: readonly number[], closedHeight: number): number {
+export function heightForIndex(index: number, snapPoints: readonly number[], closedHeight: number): number {
 	"worklet";
-	const count = detents.length;
+	const count = snapPoints.length;
 	if (count === 0 || index <= CLOSED_INDEX) return closedHeight;
-	if (index >= count - 1) return detents[count - 1] as number;
+	if (index >= count - 1) return snapPoints[count - 1] as number;
 
 	const upperIndex = Math.ceil(index);
-	const lower = upperIndex === 0 ? closedHeight : (detents[upperIndex - 1] as number);
-	const upper = detents[upperIndex] as number;
+	const lower = upperIndex === 0 ? closedHeight : (snapPoints[upperIndex - 1] as number);
+	const upper = snapPoints[upperIndex] as number;
 	const fraction = index - (upperIndex - 1);
 	return lower + (upper - lower) * fraction;
 }

package/src/core/snap-points/normalize-snap-points.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "bun:test";
+import type { SnapPointSpec } from "../sheet.types";
+import { normalizeSnapPoints, parseSnapPoint } from "./normalize-snap-points";
+
+describe("parseSnapPoint", () => {
+	test("a finite non-negative number is pixels", () => {
+		expect(parseSnapPoint(300)).toEqual({ success: true, data: { kind: "px", value: 300 } });
+		expect(parseSnapPoint(0)).toEqual({ success: true, data: { kind: "px", value: 0 } });
+	});
+
+	test("a percentage string is a fraction of the available height", () => {
+		expect(parseSnapPoint("50%")).toEqual({ success: true, data: { kind: "percent", value: 50 } });
+		expect(parseSnapPoint("12.5%")).toEqual({ success: true, data: { kind: "percent", value: 12.5 } });
+	});
+
+	test("refuses NaN, infinities and negatives by name", () => {
+		for (const bad of [Number.NaN, Number.POSITIVE_INFINITY, -1] as const) {
+			expect(parseSnapPoint(bad)).toEqual({ success: false, error: { code: "invalid-snap-point", value: bad } });
+		}
+	});
+
+	test("refuses a string that is not a percentage", () => {
+		for (const bad of ["50", "abc%", "%", "-10%", "50px"]) {
+			expect(parseSnapPoint(bad as SnapPointSpec)).toEqual({
+				success: false,
+				error: { code: "invalid-snap-point", value: bad },
+			});
+		}
+	});
+
+	test("refuses anything that is not a number or a string", () => {
+		expect(parseSnapPoint(undefined as unknown as SnapPointSpec)).toEqual({
+			success: false,
+			error: { code: "invalid-snap-point", value: undefined },
+		});
+	});
+});
+
+describe("normalizeSnapPoints", () => {
+	test("pixels pass through", () => {
+		expect(normalizeSnapPoints([200, 400], 800)).toEqual([200, 400]);
+	});
+
+	test("percentages resolve against the available height", () => {
+		expect(normalizeSnapPoints(["25%", "50%", "100%"], 800)).toEqual([200, 400, 800]);
+	});
+
+	test("mixed specs sort ascending regardless of authoring order", () => {
+		expect(normalizeSnapPoints(["100%", 100, "50%"], 800)).toEqual([100, 400, 800]);
+	});
+
+	test("duplicates collapse, including a pixel and a percentage that agree", () => {
+		expect(normalizeSnapPoints([400, "50%", 400], 800)).toEqual([400]);
+	});
+
+	test("clamps to the available height and to zero", () => {
+		expect(normalizeSnapPoints([1000, "150%"], 800)).toEqual([800]);
+	});
+
+	test("skips an invalid spec rather than poisoning the list", () => {
+		expect(normalizeSnapPoints([Number.NaN, "x%" as SnapPointSpec, 300], 800)).toEqual([300]);
+	});
+
+	test("an unmeasured or zero available height yields nothing to snap to", () => {
+		expect(normalizeSnapPoints(["50%"], -1)).toEqual([]);
+		expect(normalizeSnapPoints([300], 0)).toEqual([]);
+	});
+
+	test("an empty spec is an empty list", () => {
+		expect(normalizeSnapPoints([], 800)).toEqual([]);
+	});
+});

package/src/core/{detents/normalize-detents.ts → snap-points/normalize-snap-points.ts}

@@ -1,21 +1,21 @@
 import { err, ok, type Result } from "../result";
-import type { DetentSpec } from "../sheet.types";
+import type { SnapPointSpec } from "../sheet.types";
 
-/** A detent with its unit made explicit. */
-export type ParsedDetent = { kind: "px"; value: number } | { kind: "percent"; value: number };
+/** A snap point with its unit made explicit. */
+export type ParsedSnapPoint = { kind: "px"; value: number } | { kind: "percent"; value: number };
 
-/** Why a detent could not be read. `value` is what the consumer wrote. */
-export type DetentError = { code: "invalid-snap-point"; value: unknown };
+/** Why a snap point could not be read. `value` is what the consumer wrote. */
+export type SnapPointError = { code: "invalid-snap-point"; value: unknown };
 
 /**
- * Reads one detent as the consumer wrote it — `300` or `"50%"` — refusing
+ * Reads one snap point as the consumer wrote it — `300` or `"50%"` — refusing
  * `NaN`, infinities, negatives and any string that is not a percentage.
  *
  * This is the JS-thread validator, for `snapToPosition` and for surfacing a
  * bad `snapPoints` prop by name. The worklet below re-implements the same
  * parse inline, because a module-scope worklet may not call it.
  */
-export function parseDetent(spec: DetentSpec): Result<ParsedDetent, DetentError> {
+export function parseSnapPoint(spec: SnapPointSpec): Result<ParsedSnapPoint, SnapPointError> {
 	if (typeof spec === "number") {
 		if (!Number.isFinite(spec) || spec < 0) return err({ code: "invalid-snap-point", value: spec });
 		return ok({ kind: "px", value: spec });
@@ -36,10 +36,10 @@ export function parseDetent(spec: DetentSpec): Result<ParsedDetent, DetentError>
  * the resting bottom for a detached sheet. While it is unmeasured (or zero)
  * there is nothing to snap to, and the result is empty rather than a list of
  * zeros. An invalid entry is skipped, never written into the list: one `NaN`
- * in `detents` freezes a sheet.
+ * in `snapPoints` freezes a sheet.
  */
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the flat-worklet rule forbids extracting helpers; see the doc comment above.
-export function normalizeDetents(spec: readonly DetentSpec[], available: number): number[] {
+export function normalizeSnapPoints(spec: readonly SnapPointSpec[], available: number): number[] {
 	"worklet";
 	if (!(available > 0)) return [];
 

package/src/core/{detents → snap-points}/select-snap-height.test.ts

@@ -1,22 +1,22 @@
 import { describe, expect, test } from "bun:test";
 import { selectSnapHeight } from "./select-snap-height";
 
-const detents = [200, 400, 800];
+const snapPoints = [200, 400, 800];
 const at = (height: number, velocity = 0, closedHeight: number | null = 0) =>
-	selectSnapHeight({ height, velocity, detents, closedHeight, projection: 0.2 });
+	selectSnapHeight({ height, velocity, snapPoints, closedHeight, projection: 0.2 });
 
 describe("selectSnapHeight", () => {
-	test("at rest, the nearest detent wins", () => {
+	test("at rest, the nearest snap point wins", () => {
 		expect(at(250)).toBe(200);
 		expect(at(350)).toBe(400);
 		expect(at(700)).toBe(800);
 	});
 
-	test("velocity projects the release point — a flick upward reaches the next detent", () => {
+	test("velocity projects the release point — a flick upward reaches the next snap point", () => {
 		expect(at(250, 1000)).toBe(400);
 	});
 
-	test("a flick downward from just above a detent falls through it", () => {
+	test("a flick downward from just above a snap point falls through it", () => {
 		expect(at(420, -1500)).toBe(200);
 	});
 
@@ -34,16 +34,18 @@ describe("selectSnapHeight", () => {
 		expect(at(700, -4000, null)).toBe(200);
 	});
 
-	test("a projection past the highest detent still lands on it", () => {
+	test("a projection past the highest snap point still lands on it", () => {
 		expect(at(700, 5000)).toBe(800);
 	});
 
-	test("exactly between two detents, the lower one wins", () => {
+	test("exactly between two snap points, the lower one wins", () => {
 		expect(at(300)).toBe(200);
 	});
 
 	test("with nothing to snap to, the height is left where it is", () => {
-		expect(selectSnapHeight({ height: 123, velocity: 0, detents: [], closedHeight: null, projection: 0.2 })).toBe(123);
+		expect(selectSnapHeight({ height: 123, velocity: 0, snapPoints: [], closedHeight: null, projection: 0.2 })).toBe(
+			123
+		);
 	});
 
 	test("a NaN velocity is treated as rest rather than poisoning the target", () => {

package/src/core/{detents → snap-points}/select-snap-height.ts

@@ -3,8 +3,8 @@ export type SelectSnapHeightInput = {
 	height: number;
 	/** Release velocity in height space — upward positive, so pass `-velocityY`. */
 	velocity: number;
-	/** Ascending detents. */
-	detents: readonly number[];
+	/** Ascending snap points. */
+	snapPoints: readonly number[];
 	/** The closed height when closing is allowed from this gesture, else `null`. */
 	closedHeight: number | null;
 	/** Seconds of velocity to project — the `0.2` the previous engine used. */
@@ -12,7 +12,7 @@ export type SelectSnapHeightInput = {
 };
 
 /**
- * The detent a released drag settles at: the candidate nearest to where the
+ * The snap point a released drag settles at: the candidate nearest to where the
  * finger was heading, `height + projection · velocity`.
  *
  * Closing is a candidate only when `closedHeight` is given; the pan passes
@@ -31,8 +31,8 @@ export function selectSnapHeight(input: SelectSnapHeightInput): number {
 		bestDistance = Math.abs(projected - input.closedHeight);
 	}
 
-	for (let index = 0; index < input.detents.length; index += 1) {
-		const candidate = input.detents[index] as number;
+	for (let index = 0; index < input.snapPoints.length; index += 1) {
+		const candidate = input.snapPoints[index] as number;
 		const distance = Math.abs(projected - candidate);
 		if (distance < bestDistance) {
 			best = candidate;

package/src/core/snap-points/sheet-state.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { SHEET_STATE } from "../sheet.types";
+import { sheetState } from "./sheet-state";
+
+const snapPoints = [200, 400];
+const maxHeight = 800;
+
+describe("sheetState", () => {
+	test("at or below the closed height the sheet is closed", () => {
+		expect(sheetState(0, 0, snapPoints, 0, maxHeight)).toBe(SHEET_STATE.CLOSED);
+		expect(sheetState(-10, -10, snapPoints, 0, maxHeight)).toBe(SHEET_STATE.CLOSED);
+		expect(sheetState(-32, -32, snapPoints, -32, maxHeight)).toBe(SHEET_STATE.CLOSED);
+	});
+
+	test("between closed and the highest snap point it is opened", () => {
+		expect(sheetState(200, 200, snapPoints, 0, maxHeight)).toBe(SHEET_STATE.OPENED);
+		expect(sheetState(300, 300, snapPoints, 0, maxHeight)).toBe(SHEET_STATE.OPENED);
+	});
+
+	test("at the highest snap point it is extended", () => {
+		expect(sheetState(400, 400, snapPoints, 0, maxHeight)).toBe(SHEET_STATE.EXTENDED);
+	});
+
+	test("a hair below the highest snap point still counts as extended, so a settled spring unlocks the list", () => {
+		expect(sheetState(399.7, 399.7, snapPoints, 0, maxHeight)).toBe(SHEET_STATE.EXTENDED);
+	});
+
+	test("above the highest snap point — over-drag or a keyboard lift — it is over-extended", () => {
+		expect(sheetState(450, 450, snapPoints, 0, maxHeight)).toBe(SHEET_STATE.OVER_EXTENDED);
+		expect(sheetState(400, 600, snapPoints, 0, maxHeight)).toBe(SHEET_STATE.OVER_EXTENDED);
+	});
+
+	test("filling the available height is fill, whatever the snap points say", () => {
+		expect(sheetState(800, 800, snapPoints, 0, maxHeight)).toBe(SHEET_STATE.FILL);
+		expect(sheetState(400, 800, snapPoints, 0, maxHeight)).toBe(SHEET_STATE.FILL);
+		expect(sheetState(800, 800, [200, 800], 0, maxHeight)).toBe(SHEET_STATE.FILL);
+	});
+
+	test("with no snap points anything open is extended, so a dynamic sheet still unlocks its list", () => {
+		expect(sheetState(300, 300, [], 0, maxHeight)).toBe(SHEET_STATE.EXTENDED);
+	});
+});

package/src/core/{detents → snap-points}/sheet-state.ts

@@ -4,19 +4,19 @@ import { SHEET_STATE, type SheetState } from "../sheet.types";
 const SETTLE_EPSILON = 0.5;
 
 /**
- * Where the sheet is relative to its detents.
+ * Where the sheet is relative to its snap points.
  *
  * `base` decides closed and extended — the keyboard-free height is what the
  * gesture and the scroll lock reason about. `height` decides fill and
  * over-extended, because a keyboard lift or an over-drag pushes the visible
- * sheet past the highest detent without moving `base`. With no detents (a
- * dynamic sheet whose content is the only detent, before it measures) any
+ * sheet past the highest snap point without moving `base`. With no snap points (a
+ * dynamic sheet whose content is the only snap point, before it measures) any
  * open height is extended, so the list under it is never locked.
  */
 export function sheetState(
 	base: number,
 	height: number,
-	detents: readonly number[],
+	snapPoints: readonly number[],
 	closedHeight: number,
 	maxHeight: number
 ): SheetState {
@@ -24,8 +24,8 @@ export function sheetState(
 	if (base <= closedHeight + SETTLE_EPSILON) return SHEET_STATE.CLOSED;
 	if (height >= maxHeight - SETTLE_EPSILON) return SHEET_STATE.FILL;
 
-	const count = detents.length;
-	const highest = count > 0 ? (detents[count - 1] as number) : base;
+	const count = snapPoints.length;
+	const highest = count > 0 ? (snapPoints[count - 1] as number) : base;
 	if (height > highest + SETTLE_EPSILON) return SHEET_STATE.OVER_EXTENDED;
 	if (base >= highest - SETTLE_EPSILON) return SHEET_STATE.EXTENDED;
 	return SHEET_STATE.OPENED;

package/src/gesture/AGENTS.md

@@ -12,31 +12,31 @@ The two pans that drive a sheet, and the haptic hooks they fire.
 ## The handlers
 
 `onStart` cancels the animation that owns `base`, records the source (handle
-or content), where the drag began and which detent was under it.
+or content), where the drag began and which snap point was under it.
 
 `onChange` turns the finger's travel into a height — `startBase −
 translationY`, less the scrollable's offset for a content pan once BSHEET-4
 wires one — rubber-banded by `resistOverDrag` past the lowest and highest
-detent and never above the container. The lowest is the closed height when
-`enablePanDownToClose`, else the first detent. `crossedDetent` decides the
-detent haptic; entering the rubber band fires the over-drag haptic once.
+snap point and never above the container. The lowest is the closed height when
+`enablePanDownToClose`, else the first snap point. `crossedSnapPoint` decides the
+snap point haptic; entering the rubber band fires the over-drag haptic once.
 
 `onFinalize`, not `onEnd`: a gesture that fails after activating never fires
-`onEnd`, and the sheet would be stranded between detents. `selectSnapHeight`
+`onEnd`, and the sheet would be stranded between snap points. `selectSnapHeight`
 projects the release velocity a fifth of a second ahead and picks the nearest
 candidate, closing only when the pan may close, and `animateTo` gets half the
 velocity in height space — upward positive, so `−velocityY`.
 
 A content pan over a scrollable is shared with the list. When `listOwnsRelease`
-says the release is the list's — the sheet at its highest detent, the list
+says the release is the list's — the sheet at its highest snap point, the list
 scrolled — the sheet does not snap, but it **still settles**: the finger moved
 `base` by hand, so no animation ran and nothing else would write
-`currentIndex`. `restingDetent` names the detent under `base` and `settleAt`
+`currentIndex`. `restingSnapPoint` names the snap point under `base` and `settleAt`
 does the bookkeeping of a finished animation without the motion —
 `currentIndex`, then `onSettle`, so the handle's accessibility value and
 `onIndexChange` catch up. A `return` there once left the index at the previous
-detent (or at `-1`) under a sheet sitting at 90%, and the next overlay tap did
-nothing because `close` read the sheet as already closed. Between detents,
+snap point (or at `-1`) under a sheet sitting at 90%, and the next overlay tap did
+nothing because `close` read the sheet as already closed. Between snap points,
 which the ownership test should rule out, the sheet snaps to the nearest with
 no velocity and never closes: the release velocity is the list's momentum.
 
@@ -51,14 +51,14 @@ view. Scrollables (BSHEET-4) wrap their native gesture in
 
 ## Per-gesture memory
 
-Where the drag began, the detent last under it and whether it is over-dragging
+Where the drag began, the snap point last under it and whether it is over-dragging
 live in shared values rather than closure variables. Each worklet gets its own
 copy of a captured `let`, so a write in `onStart` would never be seen by
 `onChange`.
 
 ## Haptics
 
-The package imports nothing from a haptics library. `onDetentHaptic`,
+The package imports nothing from a haptics library. `onSnapPointHaptic`,
 `onCloseHaptic` and `onOverDragHaptic` are worklets the consumer passes —
 `Presets.System.selection` from pulsar is one already — and they run inside the
 gesture handler, in the frame the crossing happened.

package/src/gesture/gesture.types.ts

@@ -8,11 +8,11 @@ import type { GestureType } from "react-native-gesture-handler";
 export type HapticWorklet = () => void;
 
 export type SheetHaptics = {
-	/** A drag crossed a detent. */
-	onDetentHaptic?: HapticWorklet;
+	/** A drag crossed a snap point. */
+	onSnapPointHaptic?: HapticWorklet;
 	/** A drag let go on a close. */
 	onCloseHaptic?: HapticWorklet;
-	/** A drag left the detent range and the rubber band took over. */
+	/** A drag left the snap point range and the rubber band took over. */
 	onOverDragHaptic?: HapticWorklet;
 };
 

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

@@ -44,7 +44,7 @@ type ScrollLockProps = Pick<
 >;
 
 export type ScrollLock = {
-	/** `true` while the sheet is below its highest detent: the list is held at `scrollLockedAt`. */
+	/** `true` while the sheet is below its highest snap point: the list is held at `scrollLockedAt`. */
 	locked: SharedValue<boolean>;
 	/** For the list's `onScroll`. Tracks the offset into `scrollOffsetY` and enforces the lock. */
 	scrollHandler: ReturnType<typeof useAnimatedScrollHandler>;
@@ -55,14 +55,14 @@ export type ScrollLock = {
 /**
  * The scroll lock: the UI-thread half of a scrollable body.
  *
- * Below the highest detent a drag on the list must move the sheet, not the
+ * Below the highest snap point a drag on the list must move the sheet, not the
  * rows. The content pan already does the moving — the native scroll and the
  * pan are simultaneous — so this hook's job is to make sure the list does not
  * *also* move: every scroll event while locked is answered with a `scrollTo`
  * back to where the lock engaged, and the offset the pan reads is pinned
  * there too, so the pan sees the list consume nothing.
  *
- * The lock engages when the sheet leaves its highest detent by any path — a
+ * The lock engages when the sheet leaves its highest snap point by any path — a
  * drag, a `snapToIndex`, a keyboard — and takes the offset of that moment as
  * its target. A list scrolled a hundred pixels, then collapsed by the handle,
  * holds those hundred pixels rather than jumping to the top; when the sheet