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

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

@@ -0,0 +1,80 @@
+/**
+ * The vocabulary of the sheet state machine.
+ *
+ * A machine is a plain description — states, the events each handles, and
+ * where they lead — and a snapshot is a plain value. Nothing here holds state;
+ * `transition` takes a snapshot and returns the next one, which is what lets
+ * `useSheetMachine` be a `useReducer` and an XState user substitute their own
+ * controller.
+ */
+import type { Result } from "../result";
+import type { DetentSpec } from "../sheet.types";
+
+/** The least an event can be. Discriminate on `type`; carry anything else. */
+export type SheetEvent = { type: string };
+
+/** Which way a step change reads, for the transition the body animates. */
+export type SheetStepDirection = "forward" | "back";
+
+/**
+ * A transition spelled out: where it goes, whether it may, and what it does to
+ * context on the way. `assign` returns a new context and never mutates the one
+ * it was given.
+ */
+export type SheetTransitionObject<S extends string, C, E extends SheetEvent> = {
+	target: S;
+	guard?: (context: C, event: E) => boolean;
+	assign?: (context: C, event: E) => C;
+};
+
+/** A transition as written — a bare target, or the object above. */
+export type SheetTransitionTarget<S extends string, C, E extends SheetEvent> = S | SheetTransitionObject<S, C, E>;
+
+/**
+ * One step. `on` maps an event type to its transition, and the handler for a
+ * given `type` sees only that member of the event union. The sheet-facing
+ * fields override the root configuration while the step is current.
+ */
+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[];
+	dismissible?: boolean;
+	direction?: SheetStepDirection;
+};
+
+/** Every step, keyed by name. Declaration order is step order. */
+export type SheetStates<S extends string, C, E extends SheetEvent> = { [K in S]: SheetStateNode<S, C, E> };
+
+export type SheetMachineConfig<S extends string, C, E extends SheetEvent> = {
+	id?: string;
+	initial: S;
+	context: C;
+	states: SheetStates<S, C, E>;
+};
+
+/** Where a machine is: the current step, its context and the steps that led here. */
+export type SheetMachineSnapshot<S extends string, C> = {
+	value: S;
+	context: C;
+	history: readonly S[];
+};
+
+export type SheetTransitionError<S extends string> =
+	| { code: "no-transition"; from: S; event: string }
+	| { code: "guard-rejected"; from: S; to: S; event: string };
+
+export type SheetTransitionResult<S extends string, C> = Result<SheetMachineSnapshot<S, C>, SheetTransitionError<S>>;
+
+export type SheetMachine<S extends string, C, E extends SheetEvent> = {
+	config: SheetMachineConfig<S, C, E>;
+	initial: SheetMachineSnapshot<S, C>;
+	/** The next snapshot, or why there is none. Never throws, never mutates. */
+	transition: (snapshot: SheetMachineSnapshot<S, C>, event: E) => SheetTransitionResult<S, C>;
+	/** Whether `transition` would succeed — for disabling a Next button. */
+	can: (snapshot: SheetMachineSnapshot<S, C>, event: E) => boolean;
+	/** The steps in declaration order. */
+	steps: readonly S[];
+	/** The target's explicit `direction`, else declaration order. */
+	directionOf: (from: S, to: S) => SheetStepDirection;
+	nodeOf: (step: S) => SheetStateNode<S, C, E>;
+};

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

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import { stepFrame, stepOverride } from "./step-transition";
+
+describe("stepFrame", () => {
+	test("crossfade fades the incoming in and the outgoing out", () => {
+		expect(stepFrame("crossfade", "incoming", "forward", 0.25, 390)).toEqual({ opacity: 0.25, translateX: 0 });
+		expect(stepFrame("crossfade", "outgoing", "forward", 0.25, 390)).toEqual({ opacity: 0.75, translateX: 0 });
+	});
+
+	test("slide moves the incoming in from the right and the outgoing out to the left when going forward", () => {
+		expect(stepFrame("slide", "incoming", "forward", 0, 390)).toEqual({ opacity: 1, translateX: 390 });
+		expect(stepFrame("slide", "incoming", "forward", 1, 390)).toEqual({ opacity: 1, translateX: 0 });
+		expect(stepFrame("slide", "outgoing", "forward", 0.5, 390)).toEqual({ opacity: 1, translateX: -195 });
+	});
+
+	test("slide mirrors when going back", () => {
+		expect(stepFrame("slide", "incoming", "back", 0, 390)).toEqual({ opacity: 1, translateX: -390 });
+		expect(stepFrame("slide", "outgoing", "back", 1, 390)).toEqual({ opacity: 1, translateX: 390 });
+	});
+
+	test("none shows the incoming and hides the outgoing at once", () => {
+		expect(stepFrame("none", "incoming", "forward", 0, 390)).toEqual({ opacity: 1, translateX: 0 });
+		expect(stepFrame("none", "outgoing", "forward", 0, 390)).toEqual({ opacity: 0, translateX: 0 });
+	});
+
+	test("an unmeasured width slides nothing rather than off to minus one", () => {
+		expect(stepFrame("slide", "incoming", "forward", 0, -1)).toEqual({ opacity: 1, translateX: 0 });
+	});
+});
+
+describe("stepOverride", () => {
+	test("a step with nothing declared overrides nothing", () => {
+		expect(stepOverride({})).toEqual({ snapPoints: undefined, dismissible: undefined });
+	});
+
+	test("a step's snapPoints and dismissible are surfaced as the override", () => {
+		expect(stepOverride({ snapPoints: ["35%"], dismissible: false })).toEqual({
+			snapPoints: ["35%"],
+			dismissible: false,
+		});
+	});
+
+	test("an explicit dismissible: true is kept, not collapsed to undefined", () => {
+		expect(stepOverride({ dismissible: true })).toEqual({ snapPoints: undefined, dismissible: true });
+	});
+});

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

@@ -0,0 +1,59 @@
+/**
+ * How one step gives way to the next, as a number per frame.
+ *
+ * `BottomSheet.Steps` drives a single `progress` from `0` to `1` when the
+ * machine changes step, and both the outgoing and the incoming step read their
+ * 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 { SheetEvent, SheetStateNode, SheetStepDirection } from "./machine.types";
+
+/** The `transition` prop of `BottomSheet.Steps`. */
+export type SheetStepTransition = "crossfade" | "slide" | "none";
+
+/** Which side of a step change a view is on. */
+export type SheetStepRole = "incoming" | "outgoing";
+
+export type SheetStepFrame = { opacity: number; translateX: number };
+
+/**
+ * The opacity and horizontal offset of a step at `progress` through a change.
+ *
+ * `crossfade` fades the two across each other; `slide` moves the incoming step
+ * in from the side the direction points away from and the outgoing one out the
+ * other way, a whole `width` each; `none` swaps them on the first frame. An
+ * unmeasured width (`< 0`) slides nothing.
+ */
+export function stepFrame(
+	transition: SheetStepTransition,
+	role: SheetStepRole,
+	direction: SheetStepDirection,
+	progress: number,
+	width: number
+): SheetStepFrame {
+	"worklet";
+	if (transition === "crossfade") {
+		return { opacity: role === "incoming" ? progress : 1 - progress, translateX: 0 };
+	}
+	if (transition === "slide") {
+		const span = width > 0 ? width : 0;
+		const sign = direction === "forward" ? 1 : -1;
+		const translateX = role === "incoming" ? (1 - progress) * span * sign : -progress * span * sign;
+		return { opacity: 1, translateX };
+	}
+	return { opacity: role === "incoming" ? 1 : 0, translateX: 0 };
+}
+
+/** What a step asks the root to change while it is current. */
+export type SheetStepOverride = {
+	snapPoints: readonly DetentSpec[] | undefined;
+	dismissible: boolean | undefined;
+};
+
+/** The override a step node declares — nothing more than its two sheet-facing fields, read once per step change. */
+export function stepOverride<S extends string, C, E extends SheetEvent>(
+	node: SheetStateNode<S, C, E>
+): SheetStepOverride {
+	return { snapPoints: node.snapPoints, dismissible: node.dismissible };
+}

package/src/core/machine/transition.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+import type { SheetStates } from "./machine.types";
+import { resolveTarget, transition } from "./transition";
+
+type Event = { type: "GO" } | { type: "SET"; n: number };
+type Context = { n: number };
+const states: SheetStates<"one" | "two", Context, Event> = {
+	one: {
+		on: {
+			GO: "two",
+			SET: { target: "one", assign: (_context, event) => ({ n: event.n }) },
+		},
+	},
+	two: { on: { GO: { target: "one", guard: (context) => context.n > 0 } } },
+};
+
+describe("transition", () => {
+	test("resolveTarget widens a bare state name to a transition object", () => {
+		expect(resolveTarget("two")).toEqual({ target: "two" });
+		const object = { target: "two" as const, guard: () => true };
+		expect(resolveTarget(object)).toBe(object);
+	});
+
+	test("moves between states and records the origin", () => {
+		expect(transition(states, { value: "one", context: { n: 0 }, history: [] }, { type: "GO" })).toEqual({
+			success: true,
+			data: { value: "two", context: { n: 0 }, history: ["one"] },
+		});
+	});
+
+	test("applies assign with the narrowed event", () => {
+		expect(transition(states, { value: "one", context: { n: 0 }, history: [] }, { type: "SET", n: 4 })).toEqual({
+			success: true,
+			data: { value: "one", context: { n: 4 }, history: [] },
+		});
+	});
+
+	test("reports guard-rejected with both ends of the edge", () => {
+		expect(transition(states, { value: "two", context: { n: 0 }, history: ["one"] }, { type: "GO" })).toEqual({
+			success: false,
+			error: { code: "guard-rejected", from: "two", to: "one", event: "GO" },
+		});
+	});
+
+	test("reports no-transition for an unhandled event", () => {
+		expect(transition(states, { value: "two", context: { n: 1 }, history: [] }, { type: "SET", n: 1 })).toEqual({
+			success: false,
+			error: { code: "no-transition", from: "two", event: "SET" },
+		});
+	});
+});

package/src/core/machine/transition.ts

@@ -0,0 +1,58 @@
+/**
+ * The one step of a sheet machine: a snapshot and an event in, the next
+ * snapshot or a typed refusal out.
+ *
+ * A refusal is data, not an exception. A `NEXT` the guard rejects is the
+ * normal case for a form with an empty field, and the caller wants to know
+ * which edge said no rather than catch something.
+ */
+import { err, ok } from "../result";
+import type {
+	SheetEvent,
+	SheetMachineSnapshot,
+	SheetStates,
+	SheetTransitionObject,
+	SheetTransitionResult,
+	SheetTransitionTarget,
+} from "./machine.types";
+
+/** A bare state name widened to the object form; an object returned as is. */
+export function resolveTarget<S extends string, C, E extends SheetEvent>(
+	target: SheetTransitionTarget<S, C, E>
+): SheetTransitionObject<S, C, E> {
+	return typeof target === "string" ? { target } : target;
+}
+
+/**
+ * The transition `states[value].on[event.type]`, seen with the whole event
+ * union. Per-type narrowing is the author's contract with `on`; at the moment
+ * of dispatch the event's `type` has already selected the handler that was
+ * written for it, so widening back to `E` here loses nothing.
+ */
+function transitionFor<S extends string, C, E extends SheetEvent>(
+	states: SheetStates<S, C, E>,
+	value: S,
+	type: E["type"]
+): SheetTransitionTarget<S, C, E> | undefined {
+	const on = states[value].on as { [T in E["type"]]?: SheetTransitionTarget<S, C, E> } | undefined;
+	return on?.[type];
+}
+
+export function transition<S extends string, C, E extends SheetEvent>(
+	states: SheetStates<S, C, E>,
+	snapshot: SheetMachineSnapshot<S, C>,
+	event: E
+): SheetTransitionResult<S, C> {
+	const from = snapshot.value;
+	const found = transitionFor(states, from, event.type);
+	if (found === undefined) return err({ code: "no-transition", from, event: event.type });
+
+	const { target, guard, assign } = resolveTarget(found);
+	if (guard !== undefined && !guard(snapshot.context, event)) {
+		return err({ code: "guard-rejected", from, to: target, event: event.type });
+	}
+
+	const context = assign === undefined ? snapshot.context : assign(snapshot.context, event);
+	const history = target === from ? snapshot.history : [...snapshot.history, from];
+	return ok({ value: target, context, history });
+}

package/src/core/result.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, test } from "bun:test";
+import { err, ok } from "./result";
+
+describe("Result", () => {
+	test("ok wraps a value", () => {
+		expect(ok(3)).toEqual({ success: true, data: 3 });
+	});
+
+	test("err keeps a typed error rather than flattening it to a string", () => {
+		expect(err({ code: "invalid-snap-point" as const })).toEqual({
+			success: false,
+			error: { code: "invalid-snap-point" },
+		});
+	});
+});

package/src/core/result.ts

@@ -0,0 +1,20 @@
+/**
+ * The house `Result` — the shape `@delacour/types` defines, copied rather than
+ * imported.
+ *
+ * `@delacour/types` is a private workspace package and this one publishes. A
+ * `workspace:*` dependency on something npm has never seen would resolve for
+ * every workspace consumer and for nobody else; the twelve lines below are
+ * cheaper than making the types package public for a single union.
+ */
+export type SuccessResult<Success> = { success: true; data: Success };
+export type ErrorResult<Error = string> = { success: false; error: Error };
+export type Result<Success, Error = string> = SuccessResult<Success> | ErrorResult<Error>;
+
+export function ok<T>(data: T): SuccessResult<T> {
+	return { success: true, data };
+}
+
+export function err<E>(error: E): ErrorResult<E> {
+	return { success: false, error };
+}

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

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+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", () => {
+		expect(shouldLockScroll(SHEET_STATE.CLOSED, true)).toBe(true);
+		expect(shouldLockScroll(SHEET_STATE.OPENED, true)).toBe(true);
+	});
+
+	test("unlocked at the highest detent 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);
+	});
+
+	test("never locked when the content pan is off — the list is the only thing that can move", () => {
+		expect(shouldLockScroll(SHEET_STATE.OPENED, false)).toBe(false);
+	});
+});
+
+describe("contentPanDrivesSheet", () => {
+	test("while locked the pan always drives the sheet", () => {
+		expect(contentPanDrivesSheet({ locked: true, contentOffsetY: 120, translationY: -10 })).toBe(true);
+	});
+
+	test("unlocked and scrolled, the list owns the drag", () => {
+		expect(contentPanDrivesSheet({ locked: false, contentOffsetY: 120, translationY: 10 })).toBe(false);
+		expect(contentPanDrivesSheet({ locked: false, contentOffsetY: 120, translationY: -10 })).toBe(false);
+	});
+
+	test("unlocked at the top, a downward drag pulls the sheet and an upward one scrolls the list", () => {
+		expect(contentPanDrivesSheet({ locked: false, contentOffsetY: 0, translationY: 10 })).toBe(true);
+		expect(contentPanDrivesSheet({ locked: false, contentOffsetY: 0, translationY: -10 })).toBe(false);
+	});
+
+	test("a bounced-past-the-top offset counts as the top", () => {
+		expect(contentPanDrivesSheet({ locked: false, contentOffsetY: -30, translationY: 10 })).toBe(true);
+	});
+});

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

@@ -0,0 +1,35 @@
+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
+ * and beyond it scrolls. With the content pan disabled there is nothing else
+ * the drag could do, so the list is never locked.
+ */
+export function shouldLockScroll(state: SheetState, enableContentPan: boolean): boolean {
+	"worklet";
+	if (!enableContentPan) return false;
+	return state !== SHEET_STATE.EXTENDED && state !== SHEET_STATE.OVER_EXTENDED && state !== SHEET_STATE.FILL;
+}
+
+export type ContentPanInput = {
+	/** `shouldLockScroll` right now. */
+	locked: boolean;
+	/** The scrollable's offset; negative when bounced past the top. */
+	contentOffsetY: number;
+	/** The pan's translation this gesture; positive is downward. */
+	translationY: number;
+};
+
+/**
+ * Whether the content pan should move the sheet rather than let the list
+ * scroll: always while locked, and at the top of an unlocked list only when
+ * the finger is pulling down. Everything else is the list's.
+ */
+export function contentPanDrivesSheet(input: ContentPanInput): boolean {
+	"worklet";
+	if (input.locked) return true;
+	return input.contentOffsetY <= 0 && input.translationY > 0;
+}

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

@@ -0,0 +1,99 @@
+import { describe, expect, test } from "bun:test";
+import { SCROLLABLE_TYPE } from "../sheet.types";
+import { listDragHeight, listOwnsRelease, restingDetent, scrollLockTarget } from "./scroll-pan";
+
+describe("listDragHeight", () => {
+	const highest = 600;
+
+	test("at the top with the list scrolled, the finger spends the offset before the sheet moves", () => {
+		const at = (translationY: number) =>
+			listDragHeight({ startBase: 600, translationY, startOffset: 204, held: false, highest });
+		expect(at(100)).toBe(600);
+		expect(at(204)).toBe(600);
+		expect(at(254)).toBe(550);
+	});
+
+	test("at the top with the list at its top, a pull-down moves the sheet at once", () => {
+		expect(listDragHeight({ startBase: 600, translationY: 30, startOffset: 0, held: false, highest })).toBe(570);
+	});
+
+	test("an upward drag at the top never over-drags: the list scrolls and bounces instead", () => {
+		expect(listDragHeight({ startBase: 600, translationY: -100, startOffset: 0, held: false, highest })).toBe(600);
+		expect(listDragHeight({ startBase: 600, translationY: -100, startOffset: 204, held: false, highest })).toBe(600);
+	});
+
+	test("a list held by the lock has no budget: the drag moves the sheet whatever it holds", () => {
+		expect(listDragHeight({ startBase: 300, translationY: -100, startOffset: 204, held: true, highest })).toBe(400);
+		expect(listDragHeight({ startBase: 300, translationY: 50, startOffset: 204, held: true, highest })).toBe(250);
+	});
+
+	test("once a held list's sheet reaches the top the budget applies, and the clamp absorbs it", () => {
+		expect(listDragHeight({ startBase: 300, translationY: -300, startOffset: 204, held: false, highest })).toBe(600);
+		expect(listDragHeight({ startBase: 300, translationY: -96, startOffset: 204, held: false, highest })).toBe(600);
+		expect(listDragHeight({ startBase: 300, translationY: -90, startOffset: 204, held: false, highest })).toBe(594);
+	});
+
+	test("a bounce past the top when the gesture began counts as no budget", () => {
+		expect(listDragHeight({ startBase: 600, translationY: 30, startOffset: -20, held: false, highest })).toBe(570);
+	});
+});
+
+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", () => {
+		expect(listOwnsRelease({ scrollable: true, offset: 120, base: 600, highest })).toBe(true);
+		expect(listOwnsRelease({ scrollable: true, offset: 120, base: 599.7, highest })).toBe(true);
+	});
+
+	test("at the top of the list the sheet takes it", () => {
+		expect(listOwnsRelease({ scrollable: true, offset: 0, base: 600, highest })).toBe(false);
+		expect(listOwnsRelease({ scrollable: true, offset: -12, base: 600, highest })).toBe(false);
+	});
+
+	test("below the highest detent the sheet takes it whatever the offset", () => {
+		expect(listOwnsRelease({ scrollable: true, offset: 120, base: 300, highest })).toBe(false);
+	});
+
+	test("static content never hands a release to a list", () => {
+		expect(listOwnsRelease({ scrollable: false, offset: 120, base: 600, highest })).toBe(false);
+	});
+});
+
+describe("restingDetent", () => {
+	const detents = [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 between detents rests on none", () => {
+		expect(restingDetent(500, detents)).toBeNull();
+		expect(restingDetent(598, detents)).toBeNull();
+	});
+
+	test("with no detents nothing can be rested on", () => {
+		expect(restingDetent(0, [])).toBeNull();
+	});
+});
+
+describe("scrollLockTarget", () => {
+	test("a handle drag or a snap holds the list where it is, never above the top", () => {
+		expect(scrollLockTarget(140, false)).toBe(140);
+		expect(scrollLockTarget(0, false)).toBe(0);
+		expect(scrollLockTarget(-40, false)).toBe(0);
+	});
+
+	test("a content pan leaves the top only once the list is at its top, so it locks at zero", () => {
+		expect(scrollLockTarget(9, true)).toBe(0);
+	});
+});
+
+describe("SCROLLABLE_TYPE", () => {
+	test("static content is zero, so a fresh shared value means no scrollable", () => {
+		expect(SCROLLABLE_TYPE.NONE).toBe(0);
+		expect(new Set(Object.values(SCROLLABLE_TYPE)).size).toBe(4);
+	});
+});

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

@@ -0,0 +1,96 @@
+export type ListDragInput = {
+	/** `base` when the gesture began. */
+	startBase: number;
+	/** The pan's translation this gesture; positive is downward. */
+	translationY: number;
+	/** The list's offset when the gesture began. */
+	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
+	 * the top yet this gesture. A held list scrolls nothing, so it has no
+	 * budget to spend.
+	 */
+	held: boolean;
+	highest: number;
+};
+
+/**
+ * The height a content pan over a scrollable drags to.
+ *
+ * The pan and the native scroll are simultaneous, and the finger's travel is
+ * shared: what the list scrolls, the sheet must not also move by. Rather than
+ * subtract the list's live offset — which races the pan by a frame, so the
+ * sheet dips, the lock engages and the list freezes — the offset the list
+ * *began* with is a budget the finger has to spend downward before the sheet
+ * moves. The list scrolls one-for-one under the same finger, so it reaches its
+ * top exactly as the budget runs out, and the sheet takes over from there.
+ * Upward, the budget only grows the clamp's slack: a list scrolls up freely
+ * and bounces past the top of the sheet rather than over-dragging it, which is
+ * what the `highest` clamp does.
+ */
+export function listDragHeight(input: ListDragInput): number {
+	"worklet";
+	const budget = input.held ? 0 : Math.max(0, input.startOffset);
+	return Math.min(input.startBase - input.translationY + budget, input.highest);
+}
+
+export type ListOwnsReleaseInput = {
+	/** Whether a scrollable is registered with the sheet at all. */
+	scrollable: boolean;
+	/** The list's offset at release. */
+	offset: number;
+	/** The keyboard-free height at release. */
+	base: number;
+	highest: number;
+};
+
+/** Settle tolerance: a sheet within this of a detent is on it. */
+const AT_DETENT = 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
+ * 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.
+ */
+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;
+}
+
+/**
+ * The detent 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.
+ */
+export function restingDetent(base: number, detents: 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;
+	}
+	return null;
+}
+
+/**
+ * Where a list is held while the sheet is below its highest detent.
+ *
+ * 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
+ * exception: it only leaves the top once the finger has spent the list's
+ * whole offset, so the list *is* at the top, whatever the last scroll event
+ * to land before the lock reported.
+ */
+export function scrollLockTarget(offset: number, byContentPan: boolean): number {
+	"worklet";
+	if (byContentPan) return 0;
+	return Math.max(0, offset);
+}