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

package/src/steps/AGENTS.md

@@ -0,0 +1,100 @@
+# steps
+
+`BottomSheet.Steps` and `BottomSheet.Step` — a body whose contents change
+with a machine, and whose height glides between them — plus the hooks that
+run the machine and read it.
+
+## Files
+
+| Path | What |
+| --- | --- |
+| `steps.types.ts` | `SheetStepController` (a snapshot plus `send`, `can`, `matches`, `reset`, `direction`), `UseSheetMachineOptions`, the two parts' props |
+| `use-sheet-machine.ts` | `useSheetMachine(machine, { onTransition?, onRejected? })` — the machine as React state |
+| `steps.context.tsx` | `SheetStepContext` (the controller, untyped at the boundary) and `StepsLayoutContext` (what `Steps` tells each `Step`) |
+| `use-sheet-step.ts` | `useSheetStep<S, C, E>()` / `useOptionalSheetStep()` — the controller with its generics asserted back on |
+| `bottom-sheet-steps.tsx` | The body: `Content` with an animated-height stack inside, the `contentHeight` write, the per-step override, the reset on close |
+| `bottom-sheet-step.tsx` | One step: absolutely positioned, measured while current, framed by `stepFrame` |
+
+The machine itself — `defineSheetMachine`, `transition`, `stepFrame`,
+`stepOverride` — is pure and lives in `core/machine`.
+
+## The model
+
+```tsx
+const machine = defineSheetMachine<Step, Context, Event>({ initial: "details", context, states: { … } });
+
+function Form() {
+  const controller = useSheetMachine(machine);
+  return (
+    <BottomSheet>
+      <BottomSheet.Portal>
+        <BottomSheet.Overlay />
+        <BottomSheet.Container>
+          <BottomSheet.Handle />
+          <BottomSheet.Steps controller transition="crossfade">
+            <BottomSheet.Step name="details">…</BottomSheet.Step>
+            <BottomSheet.Step name="confirm">…</BottomSheet.Step>
+          </BottomSheet.Steps>
+          <BottomSheet.Footer><Actions /></BottomSheet.Footer>
+        </BottomSheet.Container>
+      </BottomSheet.Portal>
+    </BottomSheet>
+  );
+}
+
+function Actions() {
+  const { send, can, matches } = useSheetStep<Step, Context, Event>();
+  …
+}
+```
+
+- **`useSheetMachine` is `useState` over `machine.transition`, not
+  `useReducer`.** A reducer has to be pure and React may run it twice;
+  `onRejected` is a side effect a form wants exactly once. The latest snapshot
+  is also kept in a ref so two `send`s in one tick chain. `direction` is
+  `machine.directionOf(from, to)` of the last change of step, and a `reset`
+  reads as `back`.
+- **`Steps` is `Content` with a stack inside.** It renders `Content` itself,
+  so the content pan, the `contentArea` clamp, the detached clamp and the
+  footer spacer are all the same code; the stack is an `Animated.View` whose
+  height is a shared value. Only the current step and, during a change, the
+  one leaving are rendered; each is absolutely positioned across the top of
+  the stack, measured by its `onLayout` while current.
+- **The height glides because the detent moves once.** When the current step
+  measures, `Steps` writes the number to the sheet's `contentHeight` straight
+  away and springs the stack's height to it. The dynamic detent re-derives on
+  the UI thread, the root's detent-change reaction (`state/use-sheet-intents.ts`)
+  animates `base` to the same index in the new list with the sheet's own
+  animation, and — because the stack's spring is resolved from the same
+  config — the panel's top edge and the body's bottom edge move together. A
+  sheet resting on an explicit detent does not move at all. If the sheet was
+  busy when the detent moved (a step change mid-open), the stack animation's
+  completion nudges `base` onto its detent.
+- **`Content` stops measuring.** The internal context's
+  `contentHeightSource` reads `steps` while a `Steps` body is mounted, and
+  `Content`'s `onLayout` returns early; its layout events would otherwise be
+  the stack mid-animation, a frame stale. The unmount reset to `UNMEASURED`
+  still runs, so the next open waits for the first step to measure again.
+- **A step's `snapPoints` replace the root's, and turn dynamic sizing off,
+  while it is current.** A step that names its detents is sized by them.
+  `dismissible: false` switches off pan-down-to-close and the overlay's press
+  for that step — `Close` and the ref still work. Both go through
+  `setStepOverride` on the root (`components/bottom-sheet.tsx`), because the
+  overlay is not a descendant of the body.
+- **Transitions are `stepFrame` over one `progress`.** `crossfade` fades
+  the two across each other, `slide` moves them a container-width apart along
+  `direction`, `none` swaps them. `progress` runs `0 → 1` on the incoming
+  step's first layout, with the same animation as the height, and the outgoing
+  step is dropped when it completes.
+- **`resetOnClose` resets from two places.** The `isOpen` flip, for a body
+  that stays mounted (inline, `keepMounted`), and the unmount cleanup, for one
+  the portal takes down — a close settles, the root sets `isOpen` false and
+  `presented` false in one render, and only the cleanup runs.
+- **`useSheetStep` reaches a `Footer`.** The footer is written beside the
+  body, not inside it, so `Steps` also registers its controller with the root
+  through `setStepController`; the hook reads the context first and the
+  registration second. Anywhere inside the `BottomSheet` works once the body
+  has mounted.
+- **Vertical padding goes on the `Step`, not on `Steps`.** `Steps`'s `style`
+  lands on `Content`'s inner view around the stack, and the sheet's height is
+  what the step measures — padding around the stack is not counted.

package/src/steps/bottom-sheet-step.tsx

@@ -0,0 +1,61 @@
+import type { ReactElement } from "react";
+import { StyleSheet } from "react-native";
+import Animated, { useAnimatedStyle } from "react-native-reanimated";
+import { stepFrame } from "../core";
+import { useStepsLayout } from "./steps.context";
+import type { BottomSheetStepProps } from "./steps.types";
+
+/**
+ * One step's body. Rendered by `Steps` only while it is the current step or
+ * the one on its way out, so a step that is neither costs nothing.
+ *
+ * Absolutely positioned across the top of the stack, so two steps can overlap
+ * during a change and neither pushes the other down; the stack's own height
+ * is animated by `Steps` from what the current step measures here. Its frame
+ * — opacity and horizontal offset — is `stepFrame` over the shared `progress`,
+ * on the UI thread.
+ */
+export function BottomSheetStep<S extends string>({
+	name,
+	children,
+	style,
+	ref,
+	onLayout,
+	...props
+}: BottomSheetStepProps<S>): ReactElement | null {
+	const { active, outgoing, direction, transition, progress, width, onActiveLayout } = useStepsLayout();
+	const role = name === active ? "incoming" : name === outgoing ? "outgoing" : null;
+
+	const frame = useAnimatedStyle(() => {
+		if (role === null) return { opacity: 0, transform: [{ translateX: 0 }] };
+		const { opacity, translateX } = stepFrame(transition, role, direction, progress.value, width.value);
+		return { opacity, transform: [{ translateX }] };
+	});
+
+	if (role === null) return null;
+
+	const measure =
+		role === "incoming"
+			? (event: Parameters<typeof onActiveLayout>[0]): void => {
+					onActiveLayout(event);
+					onLayout?.(event);
+				}
+			: onLayout;
+
+	return (
+		<Animated.View
+			onLayout={measure}
+			pointerEvents={role === "incoming" ? "auto" : "none"}
+			ref={ref}
+			style={[styles.step, style, frame]}
+			{...props}
+		>
+			{children}
+		</Animated.View>
+	);
+}
+BottomSheetStep.displayName = "DelacourBottomSheet.BottomSheet.Step";
+
+const styles = StyleSheet.create({
+	step: { left: 0, position: "absolute", right: 0, top: 0 },
+});

package/src/steps/bottom-sheet-steps.tsx

@@ -0,0 +1,215 @@
+import { type ReactElement, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { type LayoutChangeEvent, Platform, StyleSheet } from "react-native";
+import Animated, { useAnimatedStyle, useSharedValue, withSpring, withTiming } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { type ReanimatedAnimation, toReanimated } from "../animation/resolve-animation";
+import { useBottomSheet, useBottomSheetInternal } from "../components/bottom-sheet.context";
+import { BottomSheetContent } from "../components/bottom-sheet-content";
+import {
+	GESTURE_SOURCE,
+	heightForIndex,
+	type SheetEvent,
+	type SheetStepDirection,
+	selectAnimation,
+	stepOverride,
+	UNMEASURED,
+} from "../core";
+import { ANIM_STATUS } from "../state/state.types";
+import { SheetStepContext, StepsLayoutContext, type StepsLayoutValue } from "./steps.context";
+import type { BottomSheetStepsProps, SheetStepController } from "./steps.types";
+
+type Stage<S extends string> = { active: S; outgoing: S | null; direction: SheetStepDirection };
+
+/** Hands `value` to a spring or a timing, with `complete` on the UI thread once it lands. */
+function animateWith(animation: ReanimatedAnimation, value: number, complete: (finished?: boolean) => void): number {
+	if (animation.type === "spring") return withSpring(value, animation.config, complete);
+	return withTiming(value, animation.config, complete);
+}
+
+/**
+ * A multi-step body: the `Content` of a sheet whose contents change with a
+ * machine.
+ *
+ * It is `Content` with a stack inside — each `Step` is absolutely positioned
+ * across the top of the stack and only the current step and, during a change,
+ * the one leaving are rendered. The stack's height is a shared value animated
+ * to whatever the current step measures, and that same measurement is written
+ * to the sheet's `contentHeight` the moment it lands, so the dynamic detent
+ * moves once and the root's detent-change reaction animates `base` there with
+ * the same spring the body is using: the panel's top edge and the body's
+ * bottom edge glide together, and a sheet resting on an explicit detent does
+ * not move at all. Should the sheet have been busy when the detent moved — a
+ * step change mid-open — the height animation's completion nudges it onto its
+ * detent.
+ *
+ * `Content`'s own measurement is switched off while this is the body, or its
+ * layout events would race the animated height with stale numbers.
+ *
+ * The step the machine is on decides two things about the sheet: its
+ * `snapPoints` replace the root's while it is current (and dynamic sizing is
+ * off for it — a step that names its detents is sized by them), and
+ * `dismissible: false` disables pan-down-to-close and the overlay's press.
+ * Both go through the root, since the overlay is not a descendant of the body.
+ *
+ * The controller is provided to every descendant through `SheetStepContext`,
+ * and registered with the root so a `Footer` written beside this body reaches
+ * it through `useSheetStep` too.
+ */
+export function BottomSheetSteps<S extends string, C, E extends SheetEvent>({
+	controller,
+	transition = "crossfade",
+	animation,
+	resetOnClose = true,
+	footerGap,
+	children,
+	style,
+	ref,
+	...props
+}: BottomSheetStepsProps<S, C, E>): ReactElement {
+	const internal = useBottomSheetInternal();
+	const { state, geometry, animateTo, setContentHeightSource, setStepOverride, setStepController } = internal;
+	const { isOpen } = useBottomSheet();
+	const stepHeight = useSharedValue(UNMEASURED);
+	const progress = useSharedValue(1);
+
+	const [stage, setStage] = useState<Stage<S>>({ active: controller.value, outgoing: null, direction: "forward" });
+	const changePending = useRef(false);
+	const lastHeight = useRef(UNMEASURED);
+
+	// Derived during render, so the incoming step mounts in the same commit the
+	// machine moved in and its first layout is the one that starts the change.
+	if (controller.value !== stage.active) {
+		changePending.current = true;
+		setStage({
+			active: controller.value,
+			outgoing: transition === "none" ? null : stage.active,
+			direction: controller.direction,
+		});
+	}
+
+	const animationKey = JSON.stringify(animation ?? internal.animation ?? null);
+	// biome-ignore lint/correctness/useExhaustiveDependencies: the animation is keyed by its serialisation
+	const resolved = useMemo(
+		() => toReanimated(selectAnimation(animation ?? internal.animation, Platform.OS, internal.overrideReduceMotion)),
+		[animationKey, internal.overrideReduceMotion]
+	);
+
+	useLayoutEffect(() => {
+		setContentHeightSource("steps");
+		return () => setContentHeightSource("content");
+	}, [setContentHeightSource]);
+
+	const { machine, value } = controller;
+	useLayoutEffect(() => {
+		setStepOverride(stepOverride(machine.nodeOf(value)));
+	}, [machine, value, setStepOverride]);
+	useEffect(() => () => setStepOverride(null), [setStepOverride]);
+
+	// The ref during render, so a `Footer` rendered after this body in the
+	// same pass reads the controller; the state from an effect, to re-render
+	// anything that did not.
+	const untyped = controller as unknown as SheetStepController<string, unknown, SheetEvent>;
+	internal.stepControllerRef.current = untyped;
+	useLayoutEffect(() => {
+		setStepController(untyped);
+	}, [untyped, setStepController]);
+	useEffect(
+		() => () => {
+			internal.stepControllerRef.current = null;
+			setStepController(null);
+		},
+		[internal.stepControllerRef, setStepController]
+	);
+
+	// A close resets the machine: through the `isOpen` flip for a body that
+	// stays mounted, and through unmount for one the portal takes down.
+	const latest = useRef({ controller, resetOnClose });
+	latest.current = { controller, resetOnClose };
+	useEffect(() => {
+		if (isOpen || !latest.current.resetOnClose) return;
+		latest.current.controller.reset();
+	}, [isOpen]);
+	useEffect(
+		() => () => {
+			if (latest.current.resetOnClose) latest.current.controller.reset();
+		},
+		[]
+	);
+
+	const finishChange = useCallback(() => {
+		setStage((current) => (current.outgoing === null ? current : { ...current, outgoing: null }));
+	}, []);
+
+	const onActiveLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			const height = event.nativeEvent.layout.height;
+			const changing = changePending.current;
+			changePending.current = false;
+			if (lastHeight.current === height && !changing) return;
+			const first = lastHeight.current < 0;
+			lastHeight.current = height;
+			state.contentHeight.value = height;
+			if (first) {
+				stepHeight.value = height;
+				return;
+			}
+
+			const settle = (finished?: boolean): void => {
+				"worklet";
+				if (finished !== true) return;
+				const busy = state.animStatus.value !== ANIM_STATUS.IDLE || state.gestureSource.value !== GESTURE_SOURCE.NONE;
+				const index = state.currentIndex.value;
+				const detents = geometry.detents.value;
+				if (busy || index < 0 || detents.length === 0) return;
+				const target = heightForIndex(Math.min(index, detents.length - 1), detents, geometry.closedHeight.value);
+				if (Math.abs(target - state.base.value) > 0.5) animateTo(target, "snapPoints", 0);
+			};
+			stepHeight.value = animateWith(resolved, height, settle);
+
+			if (!changing) return;
+			if (transition === "none") {
+				progress.value = 1;
+				return;
+			}
+			const complete = (finished?: boolean): void => {
+				"worklet";
+				if (finished === true) scheduleOnRN(finishChange);
+			};
+			progress.value = 0;
+			progress.value = animateWith(resolved, 1, complete);
+		},
+		[state, geometry, animateTo, resolved, transition, stepHeight, progress, finishChange]
+	);
+
+	const stack = useAnimatedStyle(() => ({
+		height: stepHeight.value >= 0 ? stepHeight.value : undefined,
+	}));
+
+	const layoutValue = useMemo<StepsLayoutValue>(
+		() => ({
+			active: stage.active,
+			outgoing: stage.outgoing,
+			direction: stage.direction,
+			transition,
+			progress,
+			width: state.containerWidth,
+			onActiveLayout,
+		}),
+		[stage, transition, progress, state.containerWidth, onActiveLayout]
+	);
+
+	return (
+		<SheetStepContext.Provider value={untyped}>
+			<StepsLayoutContext.Provider value={layoutValue}>
+				<BottomSheetContent footerGap={footerGap} ref={ref} style={style} {...props}>
+					<Animated.View style={[styles.stack, stack]}>{children}</Animated.View>
+				</BottomSheetContent>
+			</StepsLayoutContext.Provider>
+		</SheetStepContext.Provider>
+	);
+}
+BottomSheetSteps.displayName = "DelacourBottomSheet.BottomSheet.Steps";
+
+const styles = StyleSheet.create({
+	stack: { overflow: "hidden", width: "100%" },
+});

package/src/steps/steps.context.tsx

@@ -0,0 +1,73 @@
+import { createContext, useContext } from "react";
+import type { LayoutChangeEvent } from "react-native";
+import type { SharedValue } from "react-native-reanimated";
+import { useOptionalBottomSheetInternal } from "../components/bottom-sheet.context";
+import type { SheetEvent, SheetStepDirection, SheetStepTransition } from "../core";
+import type { SheetStepController } from "./steps.types";
+
+const OUTSIDE = (hook: string): Error =>
+	new Error(
+		`[@delacour/react-native-bottom-sheet] ${hook} outside <BottomSheet.Steps>. A step reads its controller from context.`
+	);
+
+/**
+ * The controller `BottomSheet.Steps` was given, for every descendant — a
+ * step's own buttons, a title that names the step. A `Footer` written beside
+ * the body rather than inside it is not a descendant, so `Steps` also
+ * registers the controller with the root and `useSheetStep` falls back to
+ * that: anywhere inside the `BottomSheet` works once the body has mounted.
+ *
+ * Typed loosely at the context boundary: a provider cannot carry the machine's
+ * generics through `createContext`, so `useSheetStep<S, C, E>()` asserts them
+ * back at the call site, the way a typed selector would.
+ */
+export const SheetStepContext = createContext<SheetStepController<string, unknown, SheetEvent> | null>(null);
+SheetStepContext.displayName = "DelacourBottomSheet.StepContext";
+
+/** Untyped at the boundary; `use-sheet-step.ts` puts the machine's generics back. */
+export function useSheetStep(): SheetStepController<string, unknown, SheetEvent> {
+	const value = useContext(SheetStepContext);
+	const registered = useOptionalBottomSheetInternal()?.stepControllerRef.current ?? null;
+	const controller = value ?? registered;
+	if (controller === null) throw OUTSIDE("useSheetStep");
+	return controller;
+}
+
+export function useOptionalSheetStep(): SheetStepController<string, unknown, SheetEvent> | null {
+	const value = useContext(SheetStepContext);
+	const registered = useOptionalBottomSheetInternal()?.stepControllerRef.current ?? null;
+	return value ?? registered;
+}
+
+/**
+ * What `Steps` tells each `Step`: whether it is the one arriving or the one
+ * leaving, how far the change has run, and where to report its height.
+ * Internal to the folder.
+ */
+export type StepsLayoutValue = {
+	/** The step the machine is on. */
+	active: string;
+	/** The step on its way out during a transition, `null` otherwise. */
+	outgoing: string | null;
+	direction: SheetStepDirection;
+	transition: SheetStepTransition;
+	/** `0` at the start of a change, `1` once the incoming step is fully in. */
+	progress: SharedValue<number>;
+	/** The frame's width, for `slide`. */
+	width: SharedValue<number>;
+	/** The active step's measured height, from its `onLayout`. */
+	onActiveLayout: (event: LayoutChangeEvent) => void;
+};
+
+export const StepsLayoutContext = createContext<StepsLayoutValue | null>(null);
+StepsLayoutContext.displayName = "DelacourBottomSheet.StepsLayoutContext";
+
+export function useStepsLayout(): StepsLayoutValue {
+	const value = useContext(StepsLayoutContext);
+	if (value === null) throw OUTSIDE("BottomSheet.Step");
+	return value;
+}
+
+export function useOptionalStepsLayout(): StepsLayoutValue | null {
+	return useContext(StepsLayoutContext);
+}

package/src/steps/steps.types.ts

@@ -0,0 +1,61 @@
+import type { ReactNode, Ref } from "react";
+import type { View, ViewProps } from "react-native";
+import type { SheetAnimation } from "../animation/animation.types";
+import type {
+	SheetEvent,
+	SheetMachine,
+	SheetMachineSnapshot,
+	SheetStepDirection,
+	SheetStepTransition,
+	SheetTransitionError,
+} from "../core";
+
+/**
+ * What `useSheetMachine` returns and `BottomSheet.Steps` takes.
+ *
+ * A snapshot plus the verbs: `send` an event, ask whether one `can` be sent,
+ * test the current step with `matches`. `direction` is which way the last
+ * change of step read, for the transition the body animates. An XState
+ * adapter is any object with this shape — nothing checks its identity.
+ */
+export type SheetStepController<S extends string, C, E extends SheetEvent> = SheetMachineSnapshot<S, C> & {
+	/** The machine the controller runs, for `nodeOf` and `steps`. */
+	machine: SheetMachine<S, C, E>;
+	/** The steps in declaration order. */
+	steps: readonly S[];
+	/** Which way the last change of step went. `forward` until one happens. */
+	direction: SheetStepDirection;
+	send: (event: E) => void;
+	/** Whether `send` would move — for disabling a Next button. */
+	can: (event: E) => boolean;
+	matches: (step: S) => boolean;
+	/** Back to `machine.initial`. `Steps` calls it after a close when `resetOnClose`. */
+	reset: () => void;
+};
+
+export type UseSheetMachineOptions<S extends string, C, E extends SheetEvent> = {
+	/** A transition succeeded: the snapshot it left and the one it reached. */
+	onTransition?: (from: SheetMachineSnapshot<S, C>, to: SheetMachineSnapshot<S, C>, event: E) => void;
+	/** A transition was refused. The snapshot is unchanged. */
+	onRejected?: (error: SheetTransitionError<S>, event: E) => void;
+};
+
+export type BottomSheetStepsProps<S extends string, C, E extends SheetEvent> = Omit<ViewProps, "children"> & {
+	children?: ReactNode;
+	ref?: Ref<View>;
+	controller: SheetStepController<S, C, E>;
+	/** How one step gives way to the next. @default "crossfade" */
+	transition?: SheetStepTransition;
+	/** The spring or timing for the height and the transition. The root's `animation` when omitted. */
+	animation?: SheetAnimation;
+	/** Send the controller back to its initial step once the sheet has closed. @default true */
+	resetOnClose?: boolean;
+	/** Extra space between the steps and a sticky footer. @default 0 */
+	footerGap?: number;
+};
+
+export type BottomSheetStepProps<S extends string = string> = ViewProps & {
+	ref?: Ref<View>;
+	/** The step this body belongs to — a key of the machine's `states`. */
+	name: S;
+};

package/src/steps/use-sheet-machine.ts

@@ -0,0 +1,70 @@
+import { useCallback, useMemo, useRef, useState } from "react";
+import type { SheetEvent, SheetMachine, SheetMachineSnapshot, SheetStepDirection } from "../core";
+import type { SheetStepController, UseSheetMachineOptions } from "./steps.types";
+
+type MachineState<S extends string, C> = { snapshot: SheetMachineSnapshot<S, C>; direction: SheetStepDirection };
+
+/**
+ * Runs a sheet machine as React state.
+ *
+ * `send` is `machine.transition` over the latest snapshot: a success becomes
+ * the new state and `onTransition` hears about it, a refusal leaves the state
+ * alone and `onRejected` hears why. The latest snapshot lives in a ref as
+ * well as in state, so two `send`s in one tick chain rather than both reading
+ * the render they were made in.
+ *
+ * Not a `useReducer`, on purpose: a reducer has to be pure and React may run
+ * it twice, and `onRejected` is a side effect a caller wants exactly once.
+ *
+ * `can` and `matches` close over the rendered snapshot, not the ref, and are
+ * rebuilt with it: the React Compiler memoises `can({ type: "NEXT" })` on the
+ * identity of `can`, and a stable `can` reading a ref returned the answer
+ * from the render it was first called in — the Next button never unlocked.
+ * `send` and `reset` stay stable; they are actions, not questions.
+ */
+export function useSheetMachine<S extends string, C, E extends SheetEvent>(
+	machine: SheetMachine<S, C, E>,
+	options: UseSheetMachineOptions<S, C, E> = {}
+): SheetStepController<S, C, E> {
+	const [state, setState] = useState<MachineState<S, C>>({ snapshot: machine.initial, direction: "forward" });
+	const latest = useRef(state);
+	const callbacks = useRef(options);
+	callbacks.current = options;
+
+	const send = useCallback(
+		(event: E) => {
+			const from = latest.current.snapshot;
+			const result = machine.transition(from, event);
+			if (!result.success) {
+				callbacks.current.onRejected?.(result.error, event);
+				return;
+			}
+			const to = result.data;
+			const direction = to.value === from.value ? latest.current.direction : machine.directionOf(from.value, to.value);
+			latest.current = { snapshot: to, direction };
+			setState(latest.current);
+			callbacks.current.onTransition?.(from, to, event);
+		},
+		[machine]
+	);
+
+	const reset = useCallback(() => {
+		latest.current = { snapshot: machine.initial, direction: "back" };
+		setState(latest.current);
+	}, [machine]);
+
+	const { snapshot, direction } = state;
+	return useMemo<SheetStepController<S, C, E>>(
+		() => ({
+			...snapshot,
+			machine,
+			steps: machine.steps,
+			direction,
+			send,
+			can: (event) => machine.can(snapshot, event),
+			matches: (step) => snapshot.value === step,
+			reset,
+		}),
+		[snapshot, direction, machine, send, reset]
+	);
+}

package/src/steps/use-sheet-step.ts

@@ -0,0 +1,29 @@
+import type { SheetEvent } from "../core";
+import { useOptionalSheetStep as useOptionalUntyped, useSheetStep as useUntyped } from "./steps.context";
+import type { SheetStepController } from "./steps.types";
+
+/**
+ * The controller of the nearest `BottomSheet.Steps` — or the one registered
+ * with the enclosing `BottomSheet`, for a part written beside the body such
+ * as a `Footer` — with the machine's generics asserted back on.
+ *
+ * A context cannot carry `<S, C, E>` through `createContext`, so the hook in
+ * `steps.context.tsx` returns the untyped controller and this one narrows it
+ * the way a typed selector would: `useSheetStep<Step, Context, Event>()` is
+ * the caller's promise that the enclosing `Steps` runs that machine.
+ */
+export function useSheetStep<
+	S extends string = string,
+	C = unknown,
+	E extends SheetEvent = SheetEvent,
+>(): SheetStepController<S, C, E> {
+	return useUntyped() as unknown as SheetStepController<S, C, E>;
+}
+
+export function useOptionalSheetStep<
+	S extends string = string,
+	C = unknown,
+	E extends SheetEvent = SheetEvent,
+>(): SheetStepController<S, C, E> | null {
+	return useOptionalUntyped() as unknown as SheetStepController<S, C, E> | null;
+}