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

package/src/gesture/use-sheet-pan.ts

@@ -5,16 +5,16 @@ import { cancelAnimation, useSharedValue } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
 import type { AnimateTo, SettleAt } from "../animation/animation.types";
 import {
-	crossedDetent,
-	detentUnder,
+	crossedSnapPoint,
 	GESTURE_SOURCE,
 	type GestureSource,
 	listDragHeight,
 	listOwnsRelease,
 	resistOverDrag,
-	restingDetent,
+	restingSnapPoint,
 	SCROLLABLE_TYPE,
 	selectSnapHeight,
+	snapPointUnder,
 } from "../core";
 import { ANIM_STATUS, type SheetGeometry, type SheetSharedState } from "../state/state.types";
 import {
@@ -27,8 +27,8 @@ import {
 
 type PanEvent = { translationY: number; velocityY: 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;
 
 /** JS-thread, so `scheduleOnRN` has a plain function to call; `dismiss` returns a promise nobody awaits. */
 function dismissKeyboard(): void {
@@ -40,16 +40,16 @@ function dismissKeyboard(): void {
  *
  * Everything runs on the UI thread. `onStart` cancels whatever animation owns
  * `base` and remembers where the drag began; `onChange` turns the finger's
- * travel into a height, rubber-banded past the detents by `resistOverDrag`
- * and never above the container; `onFinalize` picks the detent the finger was
+ * travel into a height, rubber-banded past the snap points by `resistOverDrag`
+ * and never above the container; `onFinalize` picks the snap point the finger was
  * heading for with `selectSnapHeight` and hands it to `animateTo` with the
  * release velocity. The close is a candidate only when `enablePanDownToClose`.
  *
  * A content pan the list owns at release — the sheet at its top, the list
  * scrolled — does not snap, but it still settles: the finger moved `base` by
  * hand, so no animation ran and nothing else writes `currentIndex`. `settleAt`
- * on the detent under `base` is the bookkeeping of a finished animation
- * without the motion; between detents (which the list ownership test should
+ * on the snap point under `base` is the bookkeeping of a finished animation
+ * without the motion; between snap points (which the list ownership test should
  * rule out) the sheet snaps to the nearest one with no velocity instead, since
  * the release velocity is the list's momentum.
  *
@@ -62,7 +62,7 @@ function dismissKeyboard(): void {
  * worklets in the ordinary way. See the package `AGENTS.md`: that is legal
  * precisely because these are not module-scope worklets.
  *
- * Per-gesture memory — where the drag began, the detent last under it,
+ * Per-gesture memory — where the drag began, the snap point last under it,
  * whether it is over-dragging — lives 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`.
@@ -75,12 +75,17 @@ export function useSheetPan(
 	options: SheetPanOptions
 ): SheetPans {
 	const startBase = useSharedValue(0);
-	const lastDetent = useSharedValue(-1);
+	const lastSnapPoint = useSharedValue(-1);
 	const overDragging = useSharedValue(false);
 	const startScroll = useSharedValue(0);
 	const listHeld = useSharedValue(false);
-	const { enableHandlePanningGesture, enableContentPanningGesture, onDetentHaptic, onCloseHaptic, onOverDragHaptic } =
-		options;
+	const {
+		enableHandlePanningGesture,
+		enableContentPanningGesture,
+		onSnapPointHaptic,
+		onCloseHaptic,
+		onOverDragHaptic,
+	} = options;
 
 	return useMemo(() => {
 		const begin = (source: GestureSource): void => {
@@ -91,9 +96,9 @@ export function useSheetPan(
 			startBase.value = state.base.value;
 			startScroll.value = state.scrollOffsetY.value;
 			// A list scrolled and below the top is held by the lock: it has no travel
-			// to spend until the sheet reaches the highest detent.
-			listHeld.value = state.scrollOffsetY.value > 0 && state.base.value < geometry.highest.value - AT_DETENT;
-			lastDetent.value = detentUnder(state.base.value, geometry.detents.value);
+			// to spend until the sheet reaches the highest snap point.
+			listHeld.value = state.scrollOffsetY.value > 0 && state.base.value < geometry.highest.value - AT_SNAP_POINT;
+			lastSnapPoint.value = snapPointUnder(state.base.value, geometry.snapPoints.value);
 			overDragging.value = false;
 			// A finger on the sheet is a reason to put the keyboard away; the lift
 			// comes off as it goes and the drag continues from wherever `base` is.
@@ -102,15 +107,21 @@ export function useSheetPan(
 			}
 		};
 
-		const haptics = (raw: number, next: number, lowest: number, highest: number, detents: readonly number[]): void => {
+		const haptics = (
+			raw: number,
+			next: number,
+			lowest: number,
+			highest: number,
+			snapPoints: readonly number[]
+		): void => {
 			"worklet";
 			const over = raw > highest || raw < lowest;
 			if (over && !overDragging.value && onOverDragHaptic) onOverDragHaptic();
 			overDragging.value = over;
 
-			if (crossedDetent(lastDetent.value, next, detents)) {
-				lastDetent.value = detentUnder(next, detents);
-				if (onDetentHaptic) onDetentHaptic();
+			if (crossedSnapPoint(lastSnapPoint.value, next, snapPoints)) {
+				lastSnapPoint.value = snapPointUnder(next, snapPoints);
+				if (onSnapPointHaptic) onSnapPointHaptic();
 			}
 		};
 
@@ -138,18 +149,18 @@ export function useSheetPan(
 			"worklet";
 			if (state.gestureSource.value === GESTURE_SOURCE.NONE) return;
 			const config = state.config.value;
-			const detents = geometry.detents.value;
+			const snapPoints = geometry.snapPoints.value;
 			const closed = geometry.closedHeight.value;
 			const highest = geometry.highest.value;
 			const raw = dragged(event.translationY, highest);
 
-			const lowest = config.enablePanDownToClose || detents.length === 0 ? closed : (detents[0] as number);
+			const lowest = config.enablePanDownToClose || snapPoints.length === 0 ? closed : (snapPoints[0] as number);
 			const factor = config.enableOverDrag ? config.overDragResistanceFactor : 0;
 			const next = Math.min(resistOverDrag(raw, lowest, highest, factor), geometry.maxHeight.value);
 
-			haptics(raw, next, lowest, highest, detents);
+			haptics(raw, next, lowest, highest, snapPoints);
 			state.base.value = next;
-			if (listHeld.value && next >= highest - AT_DETENT) listHeld.value = false;
+			if (listHeld.value && next >= highest - AT_SNAP_POINT) listHeld.value = false;
 		};
 
 		// The haptic for a close, the keyboard for a downward release — a release
@@ -162,11 +173,11 @@ export function useSheetPan(
 			animateTo(target, "gesture", velocity / 2);
 		};
 
-		// A release the list owns settles the sheet on the detent under `base`
-		// with no motion; `false` when it sits between detents and has to snap.
+		// A release the list owns settles the sheet on the snap point under `base`
+		// with no motion; `false` when it sits between snap points and has to snap.
 		const settleResting = (): boolean => {
 			"worklet";
-			const resting = restingDetent(state.base.value, geometry.detents.value);
+			const resting = restingSnapPoint(state.base.value, geometry.snapPoints.value);
 			if (resting === null) return false;
 			settleAt(resting, "gesture");
 			return true;
@@ -180,7 +191,7 @@ export function useSheetPan(
 			const config = state.config.value;
 			const closed = geometry.closedHeight.value;
 
-			// The finger was scrolling rows at the top detent: the release is the
+			// The finger was scrolling rows at the top snap point: the release is the
 			// list's momentum, not a snap — but the sheet still settles where it is.
 			const listOwns = listOwnsRelease({
 				scrollable: overList(source),
@@ -190,13 +201,13 @@ export function useSheetPan(
 			});
 			if (listOwns && settleResting()) return;
 
-			// A list-owned release between detents (which `listOwnsRelease` should
+			// A list-owned release between snap points (which `listOwnsRelease` should
 			// rule out) snaps to the nearest with no velocity and never closes.
 			const velocity = listOwns ? 0 : -event.velocityY;
 			const target = selectSnapHeight({
 				height: state.base.value,
 				velocity,
-				detents: geometry.detents.value,
+				snapPoints: geometry.snapPoints.value,
 				closedHeight: config.enablePanDownToClose && !listOwns ? closed : null,
 				projection: SNAP_PROJECTION,
 			});
@@ -239,11 +250,11 @@ export function useSheetPan(
 		startBase,
 		startScroll,
 		listHeld,
-		lastDetent,
+		lastSnapPoint,
 		overDragging,
 		enableHandlePanningGesture,
 		enableContentPanningGesture,
-		onDetentHaptic,
+		onSnapPointHaptic,
 		onCloseHaptic,
 		onOverDragHaptic,
 	]);

package/src/keyboard/AGENTS.md

@@ -55,8 +55,8 @@ stops a tap from one field to the next reading as a close and a reopen.
 | `keyboardBehavior` | On show | `keyboardBlurBehavior: "restore"` on hide |
 | --- | --- | --- |
 | `interactive` (default) | Nothing — `keyboardLift` is a derivation over `progress`, so the sheet rides the keyboard up and follows an interactive dismiss down | Nothing to restore; `base` never moved |
-| `extend` | `animateTo(highest, "keyboard")` | Back to the detent held before |
-| `fillParent` | `animateTo(maxHeight, "keyboard")`; no lift; the body shrinks by the keyboard | Back to the detent held before |
+| `extend` | `animateTo(highest, "keyboard")` | Back to the snap point held before |
+| `fillParent` | `animateTo(maxHeight, "keyboard")`; no lift; the body shrinks by the keyboard | Back to the snap point held before |
 | `none` | Nothing; the keyboard is not the sheet's problem | Nothing |
 
 The behaviour reaction samples `progress` and `keyboardOwned` and hands two

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

@@ -48,9 +48,9 @@ export type UseSheetKeyboardOptions = {
  *
  * The second is the behaviour. `interactive` and `none` need none: one lifts
  * by derivation, the other ignores the keyboard. `extend` and `fillParent`
- * snap — to the highest detent or the container — when an owned keyboard
+ * snap — to the highest snap point or the container — when an owned keyboard
  * rises, and `keyboardBlurBehavior: "restore"` sends the sheet back to the
- * detent it held when the keyboard leaves. `keyboardStep` in the core makes
+ * snap point it held when the keyboard leaves. `keyboardStep` in the core makes
  * that call from two consecutive samples; this reaction only carries it out,
  * and stays out of the way of a gesture that owns `base`.
  */
@@ -139,7 +139,7 @@ export function useSheetKeyboard({
 				if (dragging) return;
 				applied.value = true;
 				indexBefore.value = running
-					? Math.round(indexForHeight(state.animTarget.value, geometry.detents.value, closed))
+					? Math.round(indexForHeight(state.animTarget.value, geometry.snapPoints.value, closed))
 					: state.currentIndex.value;
 				const target = config.keyboardBehavior === "fillParent" ? geometry.maxHeight.value : geometry.highest.value;
 				if (running || Math.abs(target - state.base.value) > 0.5) animateTo(target, "keyboard", 0);
@@ -151,9 +151,9 @@ export function useSheetKeyboard({
 			indexBefore.value = CLOSED_INDEX;
 			if (step !== "restore" || dragging || !sheetOpen || index < 0) return;
 
-			const detents = geometry.detents.value;
-			if (detents.length === 0) return;
-			const target = heightForIndex(Math.min(index, detents.length - 1), detents, closed);
+			const snapPoints = geometry.snapPoints.value;
+			if (snapPoints.length === 0) return;
+			const target = heightForIndex(Math.min(index, snapPoints.length - 1), snapPoints, closed);
 			if (Math.abs(target - state.base.value) > 0.5) animateTo(target, "keyboard", 0);
 		},
 		[state, geometry, animateTo, progress, applied, indexBefore]

package/src/layout/AGENTS.md

@@ -13,11 +13,11 @@ How the sheet learns the sizes the geometry needs.
 
 | Value | By | Read for |
 | --- | --- | --- |
-| `containerHeight`, `containerWidth` | the frame `Portal` renders | every detent, `position`, the detached frame |
+| `containerHeight`, `containerWidth` | the frame `Portal` renders | every snap point, `position`, the detached frame |
 | `containerBottomOffset` | the same frame, via `measureInWindow` | how much of a keyboard overlaps the sheet at all (BSHEET-3) |
-| `handleHeight` | `Handle` | the dynamic detent, `contentArea` |
-| `contentHeight` | `Content`'s inner box | the dynamic detent |
-| `footerContentHeight` | `Footer`'s inner box (BSHEET-3) | the dynamic detent, `footerTop` |
+| `handleHeight` | `Handle` | the dynamic snap point, `contentArea` |
+| `contentHeight` | `Content`'s inner box | the dynamic snap point |
+| `footerContentHeight` | `Footer`'s inner box (BSHEET-3) | the dynamic snap point, `footerTop` |
 
 Scrollables (BSHEET-4) feed `contentHeight` from `onContentSizeChange`
 instead of a layout.
@@ -40,7 +40,7 @@ The frame's height goes through `acceptContainerLayout`, which refuses
 Android's adjustResize double-count while a keyboard is up. Inert until
 BSHEET-3 writes `keyboardHeight`, and correct once it does. A height that is
 accepted while the sheet is open makes the intent reaction jump the sheet to
-the same index in the re-derived detents (`state/`).
+the same index in the re-derived snap points (`state/`).
 
 ## No synchronous first read
 

package/src/portal/AGENTS.md

@@ -7,7 +7,7 @@ context and the registry that `Portal` reads.
 
 | Path | What |
 | --- | --- |
-| `bottom-sheet-provider.tsx` | `BottomSheetProvider` — teleport's `PortalProvider`, the registry provider and the host-name context set to `"root"`. The app mounts it once |
+| `bottom-sheet-provider.tsx` | `BottomSheetProvider` — teleport's `PortalProvider`, the registry provider and the host-name context set to `"root"`. The app mounts it once. `hasPortalProvider` skips the teleport provider when one is already above |
 | `bottom-sheet-host.tsx` | `BottomSheet.Host` — a teleport `PortalHost` (absolute fill, `box-none`) that provides its own name as the nearest one. The recipe for a native modal |
 | `host.context.tsx` | `BottomSheetHostNameContext` — the nearest host's name, `null` with no provider; `useBottomSheetHostName` / `useOptionalBottomSheetHostName` |
 | `sheet-registry.ts` | The pure reducer: `reduceRegistry`, `topOf`, `zIndexOf`, `isTop`, `INITIAL_REGISTRY`. Tested without a renderer |
@@ -86,16 +86,25 @@ thread, turns `overflow` visible so a card's shadow is not clipped, and is
 overlay. The frame is `overflow: visible` too. The overlay is unchanged — it
 fills the frame, margins and gap included, so a tap there closes. The rest is
 `core/`: `closedHeight` is `−restingBottom`, so closed is `translateY =
-containerHeight` and the card is fully off-screen; `%` detents resolve against
+containerHeight` and the card is fully off-screen; `%` snap points resolve against
 the height above the resting line; `keyboardLift` subtracts the gap. The
 corners are the consumer's `Background` style.
 
 **The card moves as one rigid body.** The panel is as tall as the frame, so a
 detached `Background` is sized by the geometry's `surfaceHeight`
-(`core/geometry/surface-height.ts`): the sheet's `height` between its detents,
-the first detent's height below them and the last's above. A drag down to
-close, the close animation, a rubber-band under the lowest detent and an
+(`core/geometry/surface-height.ts`): the sheet's `height` between its snap points,
+the first snap point's height below them and the last's above. A drag down to
+close, the close animation, a rubber-band under the lowest snap point and an
 over-drag past the highest therefore leave the surface, the body and the
 footer exactly as they were and let `translateY` alone move the card, bottom
 corners included, through the gap and off the screen. `Content` clamps its
 body to `surfaceHeight − handleHeight` for the same reason.
+
+## Sharing teleport's provider
+
+There must be one teleport `PortalProvider` per app: teleport registers hosts natively by name,
+and two providers would mean two hosts called `"root"`. `hasPortalProvider` lets an app that
+already mounts one — `@delacour/react-native-ui`'s `OverlayProvider` is the case it was added for
+— mount the sheet registry and host name alone. Sheets then teleport into the outer provider's
+`"root"`, and their registry `z` (from 1) still orders them among themselves; the skin's overlays
+draw in bands above 1000. The skin's `BottomSheetProvider` passes the flag for you.

package/src/portal/bottom-sheet-provider.tsx

@@ -5,6 +5,13 @@ import { SheetRegistryProvider } from "./sheet-registry.context";
 
 export type BottomSheetProviderProps = {
 	children?: ReactNode;
+	/**
+	 * A teleport `PortalProvider` is already mounted above, so do not mount a
+	 * second. Teleport registers hosts natively by name, and two providers
+	 * would mean two hosts called `"root"`. Sheets then draw into the outer
+	 * provider's `"root"` host. Default `false`.
+	 */
+	hasPortalProvider?: boolean;
 };
 
 /**
@@ -18,16 +25,21 @@ export type BottomSheetProviderProps = {
  * without a ref; and the host-name context, set to `"root"`, which is what
  * makes a `Portal` written anywhere below teleport there without being told.
  *
+ * `hasPortalProvider` drops the first of the three, for an app that already
+ * mounts teleport's provider for something else — `@delacour/react-native-ui`'s
+ * `OverlayProvider` is the case it exists for.
+ *
  * Nothing else. `GestureHandlerRootView`, `SafeAreaProvider` and
  * `KeyboardProvider` are the app's — see the package `AGENTS.md`.
  */
-export function BottomSheetProvider({ children }: BottomSheetProviderProps): ReactElement {
-	return (
-		<PortalProvider>
-			<SheetRegistryProvider>
-				<BottomSheetHostNameContext.Provider value="root">{children}</BottomSheetHostNameContext.Provider>
-			</SheetRegistryProvider>
-		</PortalProvider>
+export function BottomSheetProvider({ children, hasPortalProvider = false }: BottomSheetProviderProps): ReactElement {
+	const registry = (
+		<SheetRegistryProvider>
+			<BottomSheetHostNameContext.Provider value="root">{children}</BottomSheetHostNameContext.Provider>
+		</SheetRegistryProvider>
 	);
+	if (hasPortalProvider) return registry;
+
+	return <PortalProvider>{registry}</PortalProvider>;
 }
 BottomSheetProvider.displayName = "DelacourBottomSheet.BottomSheet.Provider";

package/src/scrollable/AGENTS.md

@@ -24,12 +24,12 @@ The content pan and the list's native scroll are **simultaneous**: the list's
 `Native` gesture is declared `simultaneousWithExternalGesture(pans.content)`,
 so both see every touch. The rule for who moves is the sheet's state:
 
-- **Below the highest detent — locked.** Every scroll event is answered with
+- **Below the highest snap point — locked.** Every scroll event is answered with
   `scrollTo(ref, 0, scrollLockedAt, false)` and the offset the pan reads is
   pinned there, so the list consumes nothing and the pan moves the sheet. The
   indicator is hidden, `bounces` is off and `decelerationRate` is `0`, so a
   fling has no momentum for the lock to fight.
-- **At the highest detent — unlocked.** The list scrolls. The pan treats the
+- **At the highest snap point — unlocked.** The list scrolls. The pan treats the
   offset the list *began* the gesture with as a budget the finger spends
   downward before the sheet moves (`listDragHeight`): the list scrolls
   one-for-one under the same finger, so it reaches its top exactly as the
@@ -38,7 +38,7 @@ so both see every touch. The rule for who moves is the sheet's state:
   over-dragging.
 - **A release while scrolled at the top** belongs to the list
   (`listOwnsRelease`): the velocity is the list's momentum, not a snap. The
-  library this replaces snapped here and hopped a detent under interrupted
+  library this replaces snapped here and hopped a snap point under interrupted
   scrolls.
 
 The budget is the offset at the *start* of the gesture, never the live one.
@@ -78,14 +78,14 @@ earlier answer and is gone: it ended the list above the footer with the rows
 cut at that edge and an empty band under them.
 
 `onContentSizeChange`, less the spacer's own measured height
-(`scrollContentHeight`), writes `contentHeight`, which is the dynamic detent's
+(`scrollContentHeight`), writes `contentHeight`, which is the dynamic snap point's
 measurement. A `BottomSheet.ScrollView` of forty rows therefore needs neither
 `snapPoints` nor `dynamicSizing={false}`: it sizes to its rows, capped by
 `maxDynamicContentSize`, and scrolls inside that. The content size and the
 spacer's layout arrive as two events from one commit; both are held in refs
 and folded into a single write after the batch, because the first open
 resolves on whatever `contentHeight` says first and the mount animation, once
-running, ignores a corrected detent list — a frame of rows-plus-spacer would
+running, ignores a corrected snap point list — a frame of rows-plus-spacer would
 open the sheet a footer too tall. `contentHeight` goes back to `UNMEASURED` on
 unmount for the same reason `useMeasureHeight` resets it.
 

package/src/scrollable/bottom-sheet-scroll-view.tsx

@@ -4,7 +4,7 @@ import { createBottomSheetScrollable } from "./create-bottom-sheet-scrollable";
 import type { BottomSheetScrollViewComponent } from "./scrollable.types";
 
 /**
- * A `ScrollView` as the sheet's body: locked below the highest detent, sized
+ * A `ScrollView` as the sheet's body: locked below the highest snap point, sized
  * to its content when the sheet is dynamic. `Animated.ScrollView` is
  * Reanimated's own, made once at module scope.
  */

package/src/scrollable/create-bottom-sheet-scrollable.tsx

@@ -58,7 +58,7 @@ function footerElement(footer: ScrollableListFooter | undefined): ReactElement |
  *   object `Content` uses; the inner is a `Native` gesture on the list itself,
  *   declared simultaneous with that pan and kept alive when the finger leaves
  *   the view. Both run at once, and the pan subtracts what the list consumed.
- * - The scroll lock (`useScrollLock`). Below the highest detent the list is
+ * - The scroll lock (`useScrollLock`). Below the highest snap point the list is
  *   held where it was, so the pan moves the sheet; at the highest it scrolls,
  *   and a drag down at the top hands back to the sheet. The indicator hides,
  *   bounce switches off and momentum is cut while locked.
@@ -72,11 +72,11 @@ function footerElement(footer: ScrollableListFooter | undefined): ReactElement |
  *   shows below the footer's top edge, at rest or while the sheet is dragged
  *   down; the list itself does not shrink to that clip (see `styles.list`).
  * - Content size. `onContentSizeChange` less the spacer's own measured height
- *   feeds `contentHeight`, which is the dynamic detent's measurement: a
+ *   feeds `contentHeight`, which is the dynamic snap point's measurement: a
  *   `ScrollView` of forty rows needs no `snapPoints` and no
  *   `dynamicSizing={false}` — it sizes to its rows up to
  *   `maxDynamicContentSize`, then scrolls. The two layout events land in one
- *   batch and are folded into one write, so the detent never sees the rows
+ *   batch and are folded into one write, so the snap point never sees the rows
  *   plus the spacer for a frame — a first open resolved on that sum would
  *   animate to it and ignore the correction.
  * - Registration. On focus the list tells the sheet what kind it is, and on

package/src/state/AGENTS.md

@@ -9,9 +9,9 @@ queue that moves them.
 | --- | --- |
 | `state.types.ts` | `SheetSharedState` (the raw shared values), `SheetGeometry` (the derived ones), `SheetWorkletConfig` (the props a worklet reads), `ANIM_STATUS` |
 | `use-sheet-state.ts` | Allocates the raw values once per sheet; mirrors `snapPoints` and the config into them, keyed on serialisation rather than identity |
-| `use-detents.ts` | `detents` — `normalizeDetents` plus the dynamic detent once handle and content have measured |
+| `use-snap-points.ts` | `snapPoints` — `normalizeSnapPoints` plus the dynamic snap point once handle and content have measured |
 | `use-sheet-geometry.ts` | Every formula in `core/AGENTS.md` as a `useDerivedValue`, in dependency order |
-| `use-sheet-intents.ts` | The JS-thread `dispatch`, the reaction that resolves an intent on the UI thread, and the reaction that follows a detent change or a container resize |
+| `use-sheet-intents.ts` | The JS-thread `dispatch`, the reaction that resolves an intent on the UI thread, and the reaction that follows a snap point change or a container resize |
 
 ## The model
 
@@ -47,9 +47,9 @@ would see a closed sheet, resolve to nothing, and let the sheet finish opening.
 The first open a sheet resolves is reported as `"mount"` and, with
 `animateOnMount: false`, jumps. `mountPending` is that flag.
 
-## Detents moving under a settled sheet
+## Snap points moving under a settled sheet
 
-The second reaction watches the detent list and the container height. When
+The second reaction watches the snap point list and the container height. When
 the list changes with the sheet idle and open, the sheet animates to the same
 index in the new list — dynamic content growing, a `snapPoints` change. When
 the container changed, it jumps there instead: a rotation is not something to

package/src/state/state.types.ts

@@ -2,7 +2,6 @@ import type { SharedValue } from "react-native-reanimated";
 import type {
 	AnimationSource,
 	DetachedOptions,
-	DetentSpec,
 	GestureSource,
 	KeyboardBehavior,
 	KeyboardBlurBehavior,
@@ -10,6 +9,7 @@ import type {
 	ScrollableType,
 	SheetIntent,
 	SheetState,
+	SnapPointSpec,
 } from "../core";
 
 /** Whether an animation is running. Numeric so the UI thread never serialises a string. */
@@ -68,7 +68,7 @@ export type SheetSharedState = {
 	gestureSource: SharedValue<GestureSource>;
 	/** The scrollable's live offset, written by its scroll handler; negative while bounced past the top. */
 	scrollOffsetY: SharedValue<number>;
-	/** Where the scrollable is held while the sheet is below its highest detent. */
+	/** Where the scrollable is held while the sheet is below its highest snap point. */
 	scrollLockedAt: SharedValue<number>;
 	/** Which scrollable is the body, `NONE` for static content. Set by `createBottomSheetScrollable` on focus. */
 	scrollableType: SharedValue<ScrollableType>;
@@ -82,7 +82,7 @@ export type SheetSharedState = {
 	/** Whether the next open is the mount open — reported as `"mount"` and skipped by `animateOnMount: false`. */
 	mountPending: SharedValue<boolean>;
 	/** The `snapPoints` prop, string-keyed so identity churn is harmless. */
-	detentSpec: SharedValue<readonly DetentSpec[]>;
+	snapPointSpec: SharedValue<readonly SnapPointSpec[]>;
 	config: SharedValue<SheetWorkletConfig>;
 };
 
@@ -93,14 +93,14 @@ export type SheetSharedState = {
 export type SheetGeometry = {
 	restingBottom: SharedValue<number>;
 	closedHeight: SharedValue<number>;
-	/** The height the sheet may occupy; what a `%` detent resolves against. */
+	/** The height the sheet may occupy; what a `%` snap point resolves against. */
 	maxHeight: SharedValue<number>;
 	/** The safe-area band an attached sheet reserves. */
 	band: SharedValue<number>;
 	bandNow: SharedValue<number>;
-	/** Ascending, unique, the dynamic detent included when sizing to content. */
-	detents: SharedValue<readonly number[]>;
-	/** The last detent, or the closed height when there is none yet. */
+	/** Ascending, unique, the dynamic snap point included when sizing to content. */
+	snapPoints: SharedValue<readonly number[]>;
+	/** The last snap point, or the closed height when there is none yet. */
 	highest: SharedValue<number>;
 	keyboardLift: SharedValue<number>;
 	/** `base + keyboardLift`, clamped. What the view shows. */
@@ -111,7 +111,7 @@ export type SheetGeometry = {
 	index: SharedValue<number>;
 	sheetState: SharedValue<SheetState>;
 	layoutReady: SharedValue<boolean>;
-	/** What the body may fill above the footer or the band, sized against its detent. */
+	/** What the body may fill above the footer or the band, sized against its snap point. */
 	contentArea: SharedValue<number>;
 	footerHeight: SharedValue<number>;
 	footerTop: SharedValue<number>;
@@ -121,12 +121,12 @@ export type SheetGeometry = {
 	 * How tall the body's clipping box is: `contentArea + bodyInset` — the body
 	 * is laid out to the sheet's bottom line — held under a sticky footer to
 	 * the footer's live top edge, so nothing of the body shows below it while
-	 * the sheet is lower than its detent.
+	 * the sheet is lower than its snap point.
 	 */
 	bodyClip: SharedValue<number>;
 	/**
-	 * How tall a detached card's surface is: `height` between the detents, the
-	 * first detent's height below them and the last's above, so a close, a
+	 * How tall a detached card's surface is: `height` between the snap points, the
+	 * first snap point's height below them and the last's above, so a close, a
 	 * rubber-band and an over-drag move the card as a rigid body. Equal to
 	 * `height` when attached.
 	 */

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

@@ -20,7 +20,7 @@ import {
 	surfaceHeight,
 } from "../core";
 import type { SheetGeometry, SheetSharedState } from "./state.types";
-import { useDetents } from "./use-detents";
+import { useSnapPoints } from "./use-snap-points";
 
 /**
  * Where an unmeasured panel goes: far enough down that no frame of it shows
@@ -46,9 +46,9 @@ export function useSheetGeometry(state: SheetSharedState): SheetGeometry {
 	const maxHeight = useDerivedValue(() => availableHeight(state.containerHeight.value, resting.value));
 	const band = useDerivedValue(() => bottomBand(state.config.value.detached !== null, state.config.value.bottomInset));
 	const bandCurrent = useDerivedValue(() => bandNow(band.value, state.keyboardProgress.value));
-	const detents = useDetents(state, maxHeight, band);
+	const snapPoints = useSnapPoints(state, maxHeight, band);
 	const highest = useDerivedValue(() => {
-		const list = detents.value;
+		const list = snapPoints.value;
 		return list.length > 0 ? (list[list.length - 1] as number) : closed.value;
 	});
 	// The keyboard the sheet answers to: owned, and under a behaviour that does
@@ -71,9 +71,9 @@ export function useSheetGeometry(state: SheetSharedState): SheetGeometry {
 		if (!(container > 0)) return OFFSCREEN;
 		return positionFor(container, resting.value, height.value);
 	});
-	const index = useDerivedValue(() => indexForHeight(state.base.value, detents.value, closed.value));
+	const index = useDerivedValue(() => indexForHeight(state.base.value, snapPoints.value, closed.value));
 	const sheetStateValue = useDerivedValue(() =>
-		sheetState(state.base.value, height.value, detents.value, closed.value, maxHeight.value)
+		sheetState(state.base.value, height.value, snapPoints.value, closed.value, maxHeight.value)
 	);
 	const layoutReady = useDerivedValue(() =>
 		isLayoutReady({
@@ -88,9 +88,9 @@ export function useSheetGeometry(state: SheetSharedState): SheetGeometry {
 	const footer = useDerivedValue(() =>
 		footerHeight(state.config.value.hasFooter, state.footerContentHeight.value, bandCurrent.value)
 	);
-	// The body is sized against the highest detent rather than `base`, so it
-	// never reflows during a snap between detents — but a `fillParent` snap
-	// takes `base` above every detent, and the body follows it up.
+	// The body is sized against the highest snap point rather than `base`, so it
+	// never reflows during a snap between snap points — but a `fillParent` snap
+	// takes `base` above every snap point, and the body follows it up.
 	const area = useDerivedValue(() => {
 		const sheetHeight = Math.min(maxHeight.value, Math.max(highest.value, state.base.value) + lift.value);
 		return contentArea({
@@ -126,7 +126,7 @@ export function useSheetGeometry(state: SheetSharedState): SheetGeometry {
 
 	const surface = useDerivedValue(() => {
 		if (state.config.value.detached === null) return height.value;
-		const list = detents.value;
+		const list = snapPoints.value;
 		const lowest = list.length > 0 ? (list[0] as number) : 0;
 		return surfaceHeight(height.value, lowest, highest.value);
 	});
@@ -138,7 +138,7 @@ export function useSheetGeometry(state: SheetSharedState): SheetGeometry {
 			maxHeight,
 			band,
 			bandNow: bandCurrent,
-			detents,
+			snapPoints,
 			highest,
 			keyboardLift: lift,
 			height,
@@ -159,7 +159,7 @@ export function useSheetGeometry(state: SheetSharedState): SheetGeometry {
 			maxHeight,
 			band,
 			bandCurrent,
-			detents,
+			snapPoints,
 			highest,
 			lift,
 			height,