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

package/README.md

@@ -104,7 +104,7 @@ import { BottomSheet } from "@delacour/react-native-bottom-sheet";
 
 `Container` is the panel that moves; `Content` is the static body inside it.
 Swap the body for `BottomSheet.ScrollView`, `FlatList` or `SectionList` and
-the list's content size becomes the sheet's own detent; swap it for
+the list's content size becomes the sheet's own snap point; swap it for
 `BottomSheet.Steps` with a controller from `useSheetMachine` and the sheet's
 height glides between the steps of a typed machine. `Footer` is sticky by
 default, standing on the safe-area band and riding the keyboard's edge.
@@ -119,7 +119,7 @@ take `asChild` to hand their behaviour to an element of yours.
 
 ## The maths on its own
 
-`@delacour/react-native-bottom-sheet/core` is every detent, keyboard, footer
+`@delacour/react-native-bottom-sheet/core` is every snap point, keyboard, footer
 and geometry calculation in the package, plus the step machine, importable
 with no native module in the module graph:
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-bottom-sheet",
-	"version": "0.1.0-alpha.0",
+	"version": "0.1.0-alpha.20261006140348",
 	"description": "Headless bottom sheet engine for React Native — no tokens, no className",
 	"type": "module",
 	"license": "MIT",

package/src/animation/AGENTS.md

@@ -29,7 +29,7 @@ index the sheet never reached. Settling writes `currentIndex` and schedules
 `animateOnMount: false`.
 
 `settleAt` is the completion alone: no `onAnimate`, no target recorded, `base`
-written to the detent it is already within a settle tolerance of, then the same
+written to the snap point it is already within a settle tolerance of, then the same
 `currentIndex` write and `onSettle`. The content pan uses it for a release the
 list owns — the finger carried the sheet to the top and kept scrolling, so
 nothing animated and nothing else would report the index.

package/src/animation/animation.types.ts

@@ -22,7 +22,7 @@ export type JumpTo = (target: number, source: AnimationSource) => void;
  */
 export type SettleAt = (target: number, source: AnimationSource) => void;
 
-/** What the JS thread hears when an animation lands — `count` is how many detents there were, for the handle's accessibility value. */
+/** What the JS thread hears when an animation lands — `count` is how many snap points there were, for the handle's accessibility value. */
 export type SettleListener = (index: number, height: number, source: AnimationSource, count: number) => void;
 
 /** What the JS thread hears when an animation starts. */

package/src/animation/use-animate-to.ts

@@ -25,7 +25,7 @@ export type UseAnimateToOptions = {
  * timing whose completion writes `currentIndex` and reports the settle.
  * `jumpTo` is the same without the motion — `forceClose`, a container resize,
  * and `animateOnMount: false`. `settleAt` is the completion alone: no
- * `onAnimate`, no target recorded, `base` written to the detent it is already
+ * `onAnimate`, no target recorded, `base` written to the snap point it is already
  * within a settle tolerance of. It is for the content pan whose release the
  * list owns — the finger carried the sheet to the top and kept scrolling, so
  * nothing animated and nothing would otherwise write `currentIndex`.
@@ -57,9 +57,9 @@ export function useAnimateTo(options: UseAnimateToOptions): {
 		const settle = (target: number, source: AnimationSource): void => {
 			"worklet";
 			state.animStatus.value = ANIM_STATUS.IDLE;
-			const index = Math.round(indexForHeight(target, geometry.detents.value, geometry.closedHeight.value));
+			const index = Math.round(indexForHeight(target, geometry.snapPoints.value, geometry.closedHeight.value));
 			state.currentIndex.value = index;
-			scheduleOnRN(onSettle, index, target, source, geometry.detents.value.length);
+			scheduleOnRN(onSettle, index, target, source, geometry.snapPoints.value.length);
 		};
 
 		const begin = (target: number, source: AnimationSource): void => {
@@ -67,7 +67,7 @@ export function useAnimateTo(options: UseAnimateToOptions): {
 			cancelAnimation(state.base);
 			const fromHeight = state.base.value;
 			const fromIndex = geometry.index.value;
-			const toIndex = indexForHeight(target, geometry.detents.value, geometry.closedHeight.value);
+			const toIndex = indexForHeight(target, geometry.snapPoints.value, geometry.closedHeight.value);
 			state.animStatus.value = ANIM_STATUS.RUNNING;
 			state.animSource.value = source;
 			state.animTarget.value = target;

package/src/animation/use-settle-callbacks.ts

@@ -7,9 +7,9 @@ export type UseSettleCallbacksOptions = {
 	setOpen: (open: boolean) => void;
 	/** Unmounts the portal's children once a close has landed, unless the sheet is kept mounted. */
 	setPresented: (presented: boolean) => void;
-	/** The settled index and the detent count, for the handle's accessibility value. */
+	/** The settled index and the snap point count, for the handle's accessibility value. */
 	setIndex: (index: number) => void;
-	setDetentCount: (count: number) => void;
+	setSnapPointCount: (count: number) => void;
 	onIndexChange: ((index: number, height: number, source: AnimationSource) => void) | undefined;
 	onClose: (() => void) | undefined;
 	onAnimate: AnimateListener | undefined;
@@ -41,7 +41,7 @@ export function useSettleCallbacks(options: UseSettleCallbacksOptions): {
 	const onSettle = useCallback<SettleListener>((index, height, source, count) => {
 		const current = latest.current;
 		current.setIndex(index);
-		current.setDetentCount(count);
+		current.setSnapPointCount(count);
 		if (index !== lastReported.current) {
 			lastReported.current = index;
 			current.onIndexChange?.(index, height, source);

package/src/components/AGENTS.md

@@ -67,8 +67,8 @@ No `accessible` container: one would collapse the whole sheet into a single
 VoiceOver element. Instead the panel is `accessibilityViewIsModal` while open
 under an overlay, its descendants are hidden while it is closed, and the title
 labels it through `accessibilityLabelledBy`. The handle is the sheet's one
-`adjustable` element: increment and decrement move a detent, escape closes,
-and its value reads `Detent i of n`. The overlay is hidden from assistive
+`adjustable` element: increment and decrement move a snap point, escape closes,
+and its value reads `SnapPoint i of n`. The overlay is hidden from assistive
 technology while it is transparent.
 
 ## Contexts

package/src/components/bottom-sheet-background.tsx

@@ -13,7 +13,7 @@ import type { BottomSheetBackgroundProps } from "./bottom-sheet.types";
  * The panel is as tall as the frame, so an attached surface fills it and its
  * bottom edge is always off-screen. A detached card has a visible bottom
  * edge: the surface is then the geometry's `surfaceHeight` tall, on the UI
- * thread — the sheet's height between its detents, and the nearest detent's
+ * thread — the sheet's height between its snap points, and the nearest snap point's
  * height beyond them — so the corners the skin rounds are on screen, the gap
  * under the card is the overlay's, and a close or an over-drag moves the
  * whole card as one rigid body rather than shrinking it onto the resting

package/src/components/bottom-sheet-content.tsx

@@ -20,10 +20,10 @@ const UNCLAMPED = 100_000;
  * Three boxes. The outermost is the content pan's detector and the clip: its
  * `maxHeight` follows the geometry's `bodyClip` on the UI thread, so under a
  * sticky footer nothing of the body is drawn below the footer's top edge, at
- * rest or while the sheet is dragged below its detent and the footer holds
+ * rest or while the sheet is dragged below its snap point and the footer holds
  * the screen's bottom. The middle box is the layout: `contentArea` plus the
  * `bodyInset` the body reserves at its end, which reaches the sheet's bottom
- * line, and it never reflows during a snap between detents. The innermost is
+ * line, and it never reflows during a snap between snap points. The innermost is
  * the caller's — it takes the `style` — and its measured height is what a
  * sheet sized to its content grows to. Yoga lays the inner box out at its
  * natural height whatever the outer clamps say, which is what makes the
@@ -56,7 +56,7 @@ export function BottomSheetContent({
 
 	// A detached card's surface is only as tall as the sheet, so its body is
 	// also held to what the surface shows, or the opening animation would draw
-	// the body under the card. The surface keeps its detent's height while the
+	// the body under the card. The surface keeps its snap point's height while the
 	// card slides closed, so the body slides with it, unchanged.
 	const clip = useAnimatedStyle(() => {
 		if (!layoutReady.value) return { maxHeight: UNCLAMPED };

package/src/components/bottom-sheet-footer.tsx

@@ -17,10 +17,10 @@ import type { BottomSheetFooterProps } from "./bottom-sheet.types";
  * keyboard's top edge without ever moving. Its one view — the one that takes
  * `style` and `padding` — pads through the resting safe-area band as well, so
  * the surface a caller styles reaches the sheet's bottom line and its
- * background covers the band: while the sheet is dragged below its detent the
+ * background covers the band: while the sheet is dragged below its snap point the
  * footer holds the screen's bottom edge and the body slides down behind it,
  * and a transparent band would show every line that passed. The box is
- * measured less the band into `footerContentHeight`, which the dynamic detent
+ * measured less the band into `footerContentHeight`, which the dynamic snap point
  * counts. The band is constant on purpose — the footer's translate does the
  * collapsing, and padding that shrank as well would move the footer twice.
  *
@@ -53,7 +53,7 @@ export function BottomSheetFooter({
 
 	// A layout effect, not a passive one: the flag has to reach the root's
 	// config before the handle and the content report their heights, or the
-	// first open resolves on a detent with no footer in it and the mount
+	// first open resolves on a snap point with no footer in it and the mount
 	// animation, already running, keeps the corrected list from applying.
 	useLayoutEffect(() => {
 		if (!sticky) return;

package/src/components/bottom-sheet-handle.tsx

@@ -15,9 +15,9 @@ const ACTIONS = [{ name: "increment" }, { name: "decrement" }, { name: "escape"
  * sized to its content counts it. A handle that is never written is a handle
  * of height zero; see `Container`.
  *
- * For a screen reader it is the sheet: `adjustable`, with the detent as its
- * value, increment and decrement moving one detent either way, and the escape
- * gesture closing. Nothing else in the sheet has to know about detents.
+ * For a screen reader it is the sheet: `adjustable`, with the snap point as its
+ * value, increment and decrement moving one snap point either way, and the escape
+ * gesture closing. Nothing else in the sheet has to know about snap points.
  */
 export function BottomSheetHandle({
 	style,
@@ -27,7 +27,7 @@ export function BottomSheetHandle({
 	...props
 }: BottomSheetHandleProps): ReactElement {
 	const { state, pans, handleMounted, enableHandlePanningGesture } = useBottomSheetInternal();
-	const { index, detentCount: count, snapToIndex, close } = useBottomSheet();
+	const { index, snapPointCount: count, snapToIndex, close } = useBottomSheet();
 	const onLayout = useMeasureHeight(state.handleHeight);
 
 	useEffect(() => {
@@ -56,7 +56,7 @@ export function BottomSheetHandle({
 			accessibilityActions={ACTIONS}
 			accessibilityLabel={accessibilityLabel}
 			accessibilityRole="adjustable"
-			accessibilityValue={{ text: index < 0 ? "Closed" : `Detent ${index + 1} of ${count}` }}
+			accessibilityValue={{ text: index < 0 ? "Closed" : `Snap point ${index + 1} of ${count}` }}
 			accessible
 			onAccessibilityAction={onAccessibilityAction}
 			onAccessibilityEscape={close}

package/src/components/bottom-sheet-overlay.tsx

@@ -9,7 +9,7 @@ import type { BottomSheetOverlayProps } from "./bottom-sheet.types";
  * The scrim over the app behind the sheet.
  *
  * Its opacity follows the keyboard-free index on the UI thread, so a keyboard
- * lift never dims the app and a higher detent is no darker. Omit it and the
+ * lift never dims the app and a higher snap point is no darker. Omit it and the
  * sheet has no scrim at all.
  *
  * **It is a React Native `Pressable`, never a Gesture Handler tap, and it is

package/src/components/bottom-sheet.context.tsx

@@ -70,7 +70,7 @@ export type BottomSheetInternalValue = {
 	setHasOverlay: (has: boolean) => void;
 	/** A handle sets this on mount; a container with none reports a zero handle height. */
 	handleMounted: RefObject<boolean>;
-	/** A sticky footer sets this on mount; the dynamic detent counts it and the body reserves space for it. */
+	/** A sticky footer sets this on mount; the dynamic snap point counts it and the body reserves space for it. */
 	hasFooter: boolean;
 	setHasFooter: (has: boolean) => void;
 	/** Where `useBottomSheetTextInput` registers its field. */

package/src/components/bottom-sheet.tsx

@@ -118,7 +118,7 @@ function BottomSheetRoot({
 	keepMounted = false,
 	stackBehavior = "push",
 	closeOnBack = true,
-	onDetentHaptic,
+	onSnapPointHaptic,
 	onCloseHaptic,
 	onOverDragHaptic,
 }: BottomSheetProps): ReactElement {
@@ -129,7 +129,7 @@ function BottomSheetRoot({
 	});
 	const [presented, setPresented] = useState(isOpen);
 	const [index, setIndex] = useState(CLOSED_INDEX);
-	const [detentCount, setDetentCount] = useState(0);
+	const [snapPointCount, setSnapPointCount] = useState(0);
 	const [hasOverlay, setHasOverlay] = useState(false);
 	const [hasFooter, setHasFooter] = useState(false);
 	const handleMounted = useRef(false);
@@ -140,7 +140,7 @@ function BottomSheetRoot({
 
 	const detachedOptions = useMemo(() => resolveDetached(detached), [detached]);
 
-	// A `Steps` body may override the detents and the dismissibility for the
+	// A `Steps` body may override the snap points and the dismissibility for the
 	// step it is on. A step that names its `snapPoints` is sized by them, so
 	// dynamic sizing is off while it is current.
 	const [stepOverride, setStepOverride] = useState<SheetStepOverride | null>(null);
@@ -196,7 +196,7 @@ function BottomSheetRoot({
 		setOpen,
 		setPresented,
 		setIndex,
-		setDetentCount,
+		setSnapPointCount,
 		onIndexChange,
 		onClose,
 		onAnimate,
@@ -214,7 +214,7 @@ function BottomSheetRoot({
 	const pans = useSheetPan(state, geometry, animateTo, settleAt, {
 		enableHandlePanningGesture,
 		enableContentPanningGesture,
-		onDetentHaptic,
+		onSnapPointHaptic,
 		onCloseHaptic,
 		onOverDragHaptic,
 	});
@@ -246,7 +246,9 @@ function BottomSheetRoot({
 	// the way there.
 	const isEffectivelyOpen = useCallback((): boolean => {
 		if (state.animStatus.value === ANIM_STATUS.RUNNING) {
-			return indexForHeight(state.animTarget.value, geometry.detents.value, geometry.closedHeight.value) > CLOSED_INDEX;
+			return (
+				indexForHeight(state.animTarget.value, geometry.snapPoints.value, geometry.closedHeight.value) > CLOSED_INDEX
+			);
 		}
 		return state.currentIndex.value > CLOSED_INDEX;
 	}, [state, geometry]);
@@ -262,7 +264,7 @@ function BottomSheetRoot({
 		if (isOpen) {
 			setPresented(true);
 			// A move queued by the ref on a closed sheet is a more specific open;
-			// it waits on the same layout and lands on its own detent.
+			// it waits on the same layout and lands on its own snap point.
 			if (!moveQueued.current) dispatch({ kind: "open" });
 			moveQueued.current = false;
 			return;
@@ -288,7 +290,7 @@ function BottomSheetRoot({
 			if (latestOpen.current) setOpen(false);
 		};
 		// A move on a closed sheet is an open: the state flips first so the
-		// portal mounts, and the queued intent lands on the requested detent.
+		// portal mounts, and the queued intent lands on the requested snap point.
 		const move = (request: IntentRequest): void => {
 			if (!isEffectivelyOpen() && !latestOpen.current) {
 				moveQueued.current = true;
@@ -335,8 +337,8 @@ function BottomSheetRoot({
 	}, [presented, closeOnBack, registryTop, methods]);
 
 	const contextValue = useMemo<BottomSheetContextValue>(
-		() => ({ ...methods, isOpen, setOpen, index, detentCount }),
-		[methods, isOpen, setOpen, index, detentCount]
+		() => ({ ...methods, isOpen, setOpen, index, snapPointCount }),
+		[methods, isOpen, setOpen, index, snapPointCount]
 	);
 
 	const animatedValue = useMemo<BottomSheetAnimatedValue>(
@@ -349,7 +351,7 @@ function BottomSheetRoot({
 			contentHeight: state.contentHeight,
 			footerHeight: geometry.footerHeight,
 			keyboardLift: geometry.keyboardLift,
-			detents: geometry.detents,
+			snapPoints: geometry.snapPoints,
 			closedHeight: geometry.closedHeight,
 		}),
 		[geometry, state]

package/src/components/bottom-sheet.types.ts

@@ -5,11 +5,11 @@ import type { SheetAnimation } from "../animation/animation.types";
 import type {
 	AnimationSource,
 	DetachedProp,
-	DetentSpec,
 	KeyboardBehavior,
 	KeyboardBlurBehavior,
 	KeyboardScope,
 	ReduceMotionMode,
+	SnapPointSpec,
 } from "../core";
 import type { SheetHaptics } from "../gesture/gesture.types";
 
@@ -20,12 +20,12 @@ import type { SheetHaptics } from "../gesture/gesture.types";
  * `dismiss` is `close` under the name the library this replaces used. Every
  * method is an intent: none of them animates from the JS thread, and each is
  * a no-op when it makes no sense — `close` on a closed sheet, `snapToIndex(4)`
- * with two detents.
+ * with two snap points.
  */
 export type BottomSheetRef = {
 	snapToIndex: (index: number) => void;
-	/** A height or a `%` of the available height; clamped, never added as a detent. */
-	snapToPosition: (position: DetentSpec) => void;
+	/** A height or a `%` of the available height; clamped, never added as a snap point. */
+	snapToPosition: (position: SnapPointSpec) => void;
 	expand: () => void;
 	collapse: () => void;
 	close: () => void;
@@ -48,9 +48,9 @@ export type BottomSheetProps = SheetHaptics & {
 	 * `isOpen`. One callback for every path.
 	 */
 	onOpenChange?: (isOpen: boolean) => void;
-	/** Controlled detent index. Changing it snaps an open sheet. */
+	/** Controlled snap point index. Changing it snaps an open sheet. */
 	index?: number;
-	/** The detent `open` lands on. @default 0 */
+	/** The snap point `open` lands on. @default 0 */
 	initialIndex?: number;
 	/** The settled index changed — `-1` on close. */
 	onIndexChange?: (index: number, height: number, source: AnimationSource) => void;
@@ -65,10 +65,10 @@ export type BottomSheetProps = SheetHaptics & {
 	/** The sheet reached its closed height, by any path. `onOpenChange(false)` follows. */
 	onClose?: () => void;
 	/** Heights above the resting bottom, or `%` of the available height. @default [] */
-	snapPoints?: readonly DetentSpec[];
-	/** Adds the content's own height as a detent. @default true */
+	snapPoints?: readonly SnapPointSpec[];
+	/** Adds the content's own height as a snap point. @default true */
 	dynamicSizing?: boolean;
-	/** Caps the dynamic detent. */
+	/** Caps the dynamic snap point. */
 	maxDynamicContentSize?: number;
 	/** Pixels the frame leaves clear at the top. @default 0 */
 	topInset?: number;
@@ -78,7 +78,7 @@ export type BottomSheetProps = SheetHaptics & {
 	 * A floating card: inset by `horizontalMargin` on both sides, resting
 	 * `bottomOffset` above `bottomInset`, every corner the `Background`'s to
 	 * round. `true` is `{ horizontalMargin: 16, bottomOffset: 16 }`. Closed is
-	 * fully off-screen, `%` detents resolve against the height above the resting
+	 * fully off-screen, `%` snap points resolve against the height above the resting
 	 * line, and a tap in the margins or the gap closes.
 	 */
 	detached?: DetachedProp;
@@ -88,7 +88,7 @@ export type BottomSheetProps = SheetHaptics & {
 	enableHandlePanningGesture?: boolean;
 	/** @default true */
 	enableContentPanningGesture?: boolean;
-	/** Rubber-band past the detents. @default true */
+	/** Rubber-band past the snap points. @default true */
 	enableOverDrag?: boolean;
 	/** Larger allows more travel. @default 2.5 */
 	overDragResistanceFactor?: number;
@@ -152,7 +152,7 @@ export type BottomSheetOverlayProps = Omit<ViewProps, "style"> & {
 	disappearsOnIndex?: number;
 	/** Opacity at full appearance. @default 1 */
 	opacity?: number;
-	/** What a press does: close, collapse to the first detent, snap to an index, or nothing. @default "close" */
+	/** What a press does: close, collapse to the first snap point, snap to an index, or nothing. @default "close" */
 	pressBehavior?: "close" | "collapse" | "none" | number;
 	/** Let touches reach the app behind the scrim. @default false */
 	enableTouchThrough?: boolean;
@@ -216,8 +216,8 @@ export type BottomSheetContextValue = BottomSheetRef & {
 	setOpen: (open: boolean) => void;
 	/** The settled index, `-1` closed. React state, updated on settle. */
 	index: number;
-	/** How many detents there were at the last settle. React state, for the handle's accessibility value. */
-	detentCount: number;
+	/** How many snap points there were at the last settle. React state, for the handle's accessibility value. */
+	snapPointCount: number;
 };
 
 /** What `useBottomSheetAnimated()` returns: the shared values a skin animates against. */
@@ -230,6 +230,6 @@ export type BottomSheetAnimatedValue = {
 	contentHeight: SharedValue<number>;
 	footerHeight: SharedValue<number>;
 	keyboardLift: SharedValue<number>;
-	detents: SharedValue<readonly number[]>;
+	snapPoints: SharedValue<readonly number[]>;
 	closedHeight: SharedValue<number>;
 };

package/src/core/AGENTS.md

@@ -17,7 +17,7 @@ failure mode makes a test necessary rather than a convention sufficient.
 ## Height space
 
 Every value here is a **height**: pixels of sheet visible above its resting
-bottom line. `0` is closed, detents ascend, `-1` (`UNMEASURED`) is a
+bottom line. `0` is closed, snap points ascend, `-1` (`UNMEASURED`) is a
 measurement that has not happened. `translateY` is derived from a height only
 at the moment a view needs it, by `geometry/position.ts`, and nowhere else.
 
@@ -25,14 +25,14 @@ at the moment a view needs it, by `geometry/position.ts`, and nowhere else.
 
 | Path | What |
 | --- | --- |
-| `sheet.types.ts` | `DetentSpec`, the keyboard behaviours, `AnimationSource`, `SheetIntent`, the numeric enums and the two sentinels |
+| `sheet.types.ts` | `SnapPointSpec`, the keyboard behaviours, `AnimationSource`, `SheetIntent`, the numeric enums and the two sentinels |
 | `result.ts` | The house `Result` union, copied from the private `@delacour/types` |
-| `detents/normalize-detents.ts` | `parseDetent` (JS, a `Result`) and W `normalizeDetents(spec, available)` — ascending, unique, clamped, invalid entries skipped |
-| `detents/dynamic-detent.ts` | W `dynamicDetent` — handle + content + footer content + band once, capped |
-| `detents/index-for-height.ts` | W `indexForHeight` / `heightForIndex` — piecewise-linear over `[closed, …detents]`, clamped |
-| `detents/select-snap-height.ts` | W `selectSnapHeight` — nearest candidate to `height + projection · velocity`; closes only when given a closed height |
-| `detents/over-drag.ts` | W `resistOverDrag` — slope 1 at the edge, square-root beyond; factor 0 clamps |
-| `detents/sheet-state.ts` | W `sheetState` — closed / opened / extended / overExtended / fill |
+| `snap-points/normalize-snap-points.ts` | `parseSnapPoint` (JS, a `Result`) and W `normalizeSnapPoints(spec, available)` — ascending, unique, clamped, invalid entries skipped |
+| `snap-points/dynamic-snap-point.ts` | W `dynamicSnapPoint` — handle + content + footer content + band once, capped |
+| `snap-points/index-for-height.ts` | W `indexForHeight` / `heightForIndex` — piecewise-linear over `[closed, …snapPoints]`, clamped |
+| `snap-points/select-snap-height.ts` | W `selectSnapHeight` — nearest candidate to `height + projection · velocity`; closes only when given a closed height |
+| `snap-points/over-drag.ts` | W `resistOverDrag` — slope 1 at the edge, square-root beyond; factor 0 clamps |
+| `snap-points/sheet-state.ts` | W `sheetState` — closed / opened / extended / overExtended / fill |
 | `keyboard/keyboard-lift.ts` | W `keyboardInContainer`, W `keyboardLift` — the lift, band and gap subtracted in step with progress |
 | `keyboard/keyboard-owner.ts` | W `isInputInsideSheet` — the `keyboardScope: "inside"` geometry test |
 | `keyboard/content-area.ts` | W `contentArea` — what the body may fill, never negative |
@@ -49,9 +49,9 @@ at the moment a view needs it, by `geometry/position.ts`, and nowhere else.
 | `backdrop/backdrop-opacity.ts` | W `backdropOpacity`, W `backdropInteractive` |
 | `intent/resolve-intent.ts` | W `resolveIntent(state, intent)` — `wait` / `animate` / `jump` / `null`; open means `currentIndex ≥ 0` **or** `base` above the closed height, so a stale index never strands a visible sheet |
 | `intent/layout-ready.ts` | W `isLayoutReady` |
-| `haptic/crossed-detent.ts` | W `crossedDetent` (boolean), W `detentUnder` (index) |
+| `haptic/crossed-snap-point.ts` | W `crossedSnapPoint` (boolean), W `snapPointUnder` (index) |
 | `scroll/scroll-lock.ts` | W `shouldLockScroll`, W `contentPanDrivesSheet` |
-| `scroll/scroll-pan.ts` | W `listDragHeight` — the start offset as a budget the finger spends before the sheet moves; W `listOwnsRelease`; W `restingDetent` — the detent within the settle tolerance of a base, for a release the list owned; W `scrollLockTarget` |
+| `scroll/scroll-pan.ts` | W `listDragHeight` — the start offset as a budget the finger spends before the sheet moves; W `listOwnsRelease`; W `restingSnapPoint` — the snap point within the settle tolerance of a base, for a release the list owned; W `scrollLockTarget` |
 | `animation/select-animation.ts` | `selectAnimation`, `IOS_SPRING`, `ANDROID_TIMING` — platform defaults as data, easing by name |
 
 W marks a module-scope `"worklet"`; each is flat (see the package `AGENTS.md`)
@@ -69,12 +69,12 @@ restingBottom = detached ? bottomOffset + inset : 0          closedHeight = −r
 available     = C − restingBottom                            maxHeight = available
 band          = detached ? 0 : inset                         bandNow = band · (1 − p)
 footerHeight  = hasFooter ? footerContent + bandNow : 0
-dynamicDetent = min(handle + content + (hasFooter ? footerContent : 0) + band, maxDynamicContentSize, available)
-detents       = sortAsc(unique(normalize(spec, available) ∪ {dynamicDetent if dynamicSizing}))
+dynamicSnapPoint = min(handle + content + (hasFooter ? footerContent : 0) + band, maxDynamicContentSize, available)
+snapPoints       = sortAsc(unique(normalize(spec, available) ∪ {dynamicSnapPoint if dynamicSizing}))
 keyboardLift  = behavior ∈ {interactive, extend} ? max(0, kb − band · p − (detached ? restingBottom : 0)) : 0
 height        = clamp(base + keyboardLift, closedHeight, maxHeight)
 translateY    = C − restingBottom − height
-index         = piecewise(base, [closedHeight, …detents] → [−1, 0, 1, …])      // base, never height
+index         = piecewise(base, [closedHeight, …snapPoints] → [−1, 0, 1, …])      // base, never height
 contentArea   = max(0, min(maxHeight, highest + keyboardLift) − handle − footerHeight − kb − (hasFooter ? 0 : bandNow))
 footerTop     = max(0, height − kb − footerContent − bandNow)
 bodyInset     = hasFooter ? footerHeight : bandNow
@@ -92,18 +92,18 @@ the footer or the band and its last row can still be scrolled clear of them.
 `bodyClip` is what of that may show: without a footer all of it, so a sheet
 slides as one body; under a footer only what is above the footer's live top
 edge — `height − kb − handle − footerHeight`, which is `footerTop − handle` —
-so while the sheet is dragged below its detent and the footer holds the
-screen's bottom edge, no line of the body is drawn under it. On the detent the
+so while the sheet is dragged below its snap point and the footer holds the
+screen's bottom edge, no line of the body is drawn under it. On the snap point the
 clip is exactly `contentArea`. A scrollable's `contentHeight` is
 `scrollContentHeight(contentSize, spacer)`: the spacer is the footer and the
-band, which `dynamicDetent` adds once already.
+band, which `dynamicSnapPoint` adds once already.
 
 Two deviations from the plan's signatures, both on purpose:
 
 - `resolveIntent` returns `{ action } | null` rather than `number | null`,
   because `forceClose` needs a jump the caller can tell from an animate, and
   an open before layout needs a *wait* the caller can tell from a no-op.
-- `crossedDetent` returns a boolean and `detentUnder` the index, rather than
+- `crossedSnapPoint` returns a boolean and `snapPointUnder` the index, rather than
   one function doing both — a number that means "unchanged" when it equals its
   input is a comparison the caller has to make anyway, spelled worse.
 

package/src/core/backdrop/backdrop-opacity.test.ts

@@ -12,7 +12,7 @@ describe("backdropOpacity", () => {
 		expect(backdropOpacity(-0.25, -1, 0, 0.6)).toBeCloseTo(0.45);
 	});
 
-	test("plateaus above the appearing index — a higher detent is no darker", () => {
+	test("plateaus above the appearing index — a higher snap point is no darker", () => {
 		expect(backdropOpacity(1, -1, 0, 1)).toBe(1);
 		expect(backdropOpacity(2.5, -1, 0, 0.7)).toBe(0.7);
 	});
@@ -42,7 +42,7 @@ describe("backdropInteractive", () => {
 		expect(backdropInteractive(0, -1)).toBe(true);
 	});
 
-	test("with a higher disappearing index the lowest detent leaves the app tappable", () => {
+	test("with a higher disappearing index the lowest snap point leaves the app tappable", () => {
 		expect(backdropInteractive(0, 0)).toBe(false);
 		expect(backdropInteractive(1, 0)).toBe(true);
 	});

package/src/core/backdrop/backdrop-opacity.ts

@@ -1,6 +1,6 @@
 /**
  * The overlay's opacity at an index: `0` up to `disappearsOn`, rising
- * linearly to `opacity` at `appearsOn`, and a plateau above — a higher detent
+ * linearly to `opacity` at `appearsOn`, and a plateau above — a higher snap point
  * is no darker. Fed the keyboard-free index, so a keyboard lift never dims
  * the app behind the sheet.
  *

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

@@ -24,18 +24,18 @@ describe("bodyClip", () => {
 	const at = (sheetHeight: number) =>
 		bodyClip({ contentArea: 486, inset: 90, hasFooter: true, sheetHeight, handleHeight: 24, keyboardHeight: 0 });
 
-	test("at rest on its detent the body is clipped exactly at the footer's top edge", () => {
+	test("at rest on its snap point the body is clipped exactly at the footer's top edge", () => {
 		// contentArea 486 = 600 − 24 − 90; the body is laid out 90 deeper, to the
 		// sheet's bottom line, and the clip hides that 90 behind the footer.
 		expect(at(600)).toBe(486);
 	});
 
-	test("dragged below its detent the clip follows the live height, so nothing shows under the footer", () => {
+	test("dragged below its snap point the clip follows the live height, so nothing shows under the footer", () => {
 		expect(at(500)).toBe(386);
 		expect(at(200)).toBe(86);
 	});
 
-	test("above its detent — an over-drag — the clip stays at the laid-out body", () => {
+	test("above its snap point — an over-drag — the clip stays at the laid-out body", () => {
 		expect(at(700)).toBe(486 + 90);
 	});
 

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

@@ -16,7 +16,7 @@ export function bodyInset(hasFooter: boolean, footerHeight: number, band: number
 }
 
 export type BodyClipInput = {
-	/** The geometry's `contentArea` — the body sized against its detent. */
+	/** The geometry's `contentArea` — the body sized against its snap point. */
 	contentArea: number;
 	/** `bodyInset` — what the body reserves at its end. */
 	inset: number;
@@ -35,7 +35,7 @@ export type BodyClipInput = {
  * — and without a footer that is the clip too: the sheet slides as one body
  * and nothing needs hiding. Under a sticky footer the clip also follows the
  * footer's top edge, `sheetHeight − keyboard − handle − inset`, which is where
- * `footerTop` puts it. On the detent the two agree and the clip is exactly
+ * `footerTop` puts it. On the snap point the two agree and the clip is exactly
  * `contentArea`; below it — a drag to close, the close animation — the footer
  * stays on the screen's bottom edge while the panel slides down under it, and
  * the clip shrinks in step so no line of the body is ever drawn below the
@@ -56,7 +56,7 @@ export function bodyClip(input: BodyClipInput): number {
 /**
  * The rows' own height: a scrollable's reported content size less the
  * trailing spacer it renders inside that content. This is what the dynamic
- * detent counts — the spacer is the footer and the band, which the detent
+ * snap point counts — the spacer is the footer and the band, which the snap point
  * already adds once. An unmeasured spacer subtracts nothing; never negative.
  */
 export function scrollContentHeight(contentSize: number, spacer: number): number {

package/src/core/geometry/position.ts

@@ -5,7 +5,7 @@
  * Height space is the engine's coordinate system; this is the one place it is
  * converted to a transform. A detached sheet rests `restingBottom` above the
  * container's bottom edge, so its closed position is the full container
- * height and every detent sits that much higher.
+ * height and every snap point sits that much higher.
  */
 export function positionFor(containerHeight: number, restingBottom: number, height: number): number {
 	"worklet";

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

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