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

package/src/core/keyboard/keyboard-owner.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+import { isInputInsideSheet } from "./keyboard-owner";
+
+const sheet = { sheetTop: 400, containerBottom: 800 };
+
+describe("isInputInsideSheet", () => {
+	test("an input wholly within the sheet's frame is the sheet's", () => {
+		expect(isInputInsideSheet({ ...sheet, inputY: 500, inputHeight: 44 })).toBe(true);
+	});
+
+	test("an input above the sheet belongs to the screen behind it", () => {
+		expect(isInputInsideSheet({ ...sheet, inputY: 100, inputHeight: 44 })).toBe(false);
+	});
+
+	test("an input ending exactly at the sheet's top edge is not inside", () => {
+		expect(isInputInsideSheet({ ...sheet, inputY: 356, inputHeight: 44 })).toBe(false);
+	});
+
+	test("an input straddling the sheet's top edge counts — it was scrolled half out, not moved out", () => {
+		expect(isInputInsideSheet({ ...sheet, inputY: 380, inputHeight: 44 })).toBe(true);
+	});
+
+	test("an input below the container is not inside", () => {
+		expect(isInputInsideSheet({ ...sheet, inputY: 900, inputHeight: 44 })).toBe(false);
+	});
+
+	test("a zero-height or unmeasured input never claims a keyboard", () => {
+		expect(isInputInsideSheet({ ...sheet, inputY: 500, inputHeight: 0 })).toBe(false);
+		expect(isInputInsideSheet({ ...sheet, inputY: -1, inputHeight: -1 })).toBe(false);
+	});
+
+	test("before the sheet has measured nothing is inside it", () => {
+		expect(isInputInsideSheet({ sheetTop: -1, containerBottom: -1, inputY: 500, inputHeight: 44 })).toBe(false);
+	});
+});

package/src/core/keyboard/keyboard-owner.ts

@@ -0,0 +1,25 @@
+export type InputInsideSheetInput = {
+	/** The focused input's top, in window coordinates. */
+	inputY: number;
+	inputHeight: number;
+	/** The sheet's top edge, in window coordinates — `containerTop + position`. */
+	sheetTop: number;
+	/** The bottom edge of the sheet's container, in window coordinates. */
+	containerBottom: number;
+};
+
+/**
+ * Whether a focused input lies inside the sheet, which is the geometry
+ * fallback for keyboard ownership under `keyboardScope: "inside"`.
+ *
+ * Any vertical overlap counts: an input the list scrolled half under the
+ * sheet's top edge is still the sheet's input. An unmeasured frame on either
+ * side claims nothing.
+ */
+export function isInputInsideSheet(input: InputInsideSheetInput): boolean {
+	"worklet";
+	if (!(input.inputHeight > 0) || input.inputY < 0) return false;
+	if (input.sheetTop < 0 || input.containerBottom <= 0) return false;
+	const inputBottom = input.inputY + input.inputHeight;
+	return inputBottom > input.sheetTop && input.inputY < input.containerBottom;
+}

package/src/core/keyboard/keyboard-ownership.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test";
+import { resolveKeyboardOwner } from "./keyboard-ownership";
+
+const idle = {
+	registeredFocused: false,
+	inputInside: false,
+	inputFocused: false,
+	progress: 0,
+	previousOwned: false,
+} as const;
+
+describe("resolveKeyboardOwner", () => {
+	test("registered scope counts only a registered input", () => {
+		expect(resolveKeyboardOwner({ ...idle, scope: "registered", registeredFocused: true })).toBe(true);
+		expect(resolveKeyboardOwner({ ...idle, scope: "registered", inputInside: true })).toBe(false);
+	});
+
+	test("inside scope counts a registered input or one whose frame lies in the sheet", () => {
+		expect(resolveKeyboardOwner({ ...idle, scope: "inside", registeredFocused: true })).toBe(true);
+		expect(resolveKeyboardOwner({ ...idle, scope: "inside", inputInside: true })).toBe(true);
+		expect(resolveKeyboardOwner({ ...idle, scope: "inside" })).toBe(false);
+	});
+
+	test("always scope claims every keyboard, focused input or not", () => {
+		expect(resolveKeyboardOwner({ ...idle, scope: "always" })).toBe(true);
+		expect(resolveKeyboardOwner({ ...idle, scope: "always", progress: 1 })).toBe(true);
+	});
+
+	// Risk 2: the focused-input layout can lag `progress` by a frame, and it
+	// goes null before a hide finishes. Once owned, the keyboard stays owned
+	// until it is fully down.
+	test("an owned keyboard stays owned for the rest of its transition after the candidate goes away", () => {
+		for (const progress of [1, 0.6, 0.01]) {
+			expect(resolveKeyboardOwner({ ...idle, scope: "inside", progress, previousOwned: true })).toBe(true);
+			expect(resolveKeyboardOwner({ ...idle, scope: "registered", progress, previousOwned: true })).toBe(true);
+		}
+	});
+
+	test("ownership is released once the keyboard is down and nothing claims it", () => {
+		expect(resolveKeyboardOwner({ ...idle, scope: "inside", progress: 0, previousOwned: true })).toBe(false);
+	});
+
+	test("a candidate claims a keyboard that is already up — focus moved from the screen into the sheet", () => {
+		expect(resolveKeyboardOwner({ ...idle, scope: "inside", progress: 1, inputInside: true })).toBe(true);
+	});
+
+	test("focus moving to a field outside the sheet releases the keyboard while it is still up", () => {
+		expect(
+			resolveKeyboardOwner({ ...idle, scope: "inside", progress: 1, previousOwned: true, inputFocused: true })
+		).toBe(false);
+	});
+
+	test("under registered scope an unregistered field inside the sheet is someone else's too", () => {
+		expect(
+			resolveKeyboardOwner({
+				...idle,
+				scope: "registered",
+				progress: 1,
+				previousOwned: true,
+				inputFocused: true,
+				inputInside: true,
+			})
+		).toBe(false);
+	});
+
+	test("a keyboard never owned is not claimed mid-transition by stickiness alone", () => {
+		expect(resolveKeyboardOwner({ ...idle, scope: "inside", progress: 0.5 })).toBe(false);
+	});
+});

package/src/core/keyboard/keyboard-ownership.ts

@@ -0,0 +1,39 @@
+import type { KeyboardScope } from "../sheet.types";
+
+export type KeyboardOwnerInput = {
+	scope: KeyboardScope;
+	/** A `useBottomSheetTextInput` field holds focus. */
+	registeredFocused: boolean;
+	/** The focused input's frame lies inside the sheet — `isInputInsideSheet`. */
+	inputInside: boolean;
+	/** keyboard-controller reports a focused input at all; `false` between a blur and the next focus. */
+	inputFocused: boolean;
+	/** keyboard-controller's `progress`, 0 closed through 1 open. */
+	progress: number;
+	/** What this resolved to last frame. */
+	previousOwned: boolean;
+};
+
+/**
+ * Whether the keyboard on screen is the sheet's to lift for.
+ *
+ * A candidate — a registered field, or under `inside` any focused input whose
+ * frame overlaps the sheet — claims it outright, up or down. A focused input
+ * that is not a candidate is someone else's, and the sheet lets go at once.
+ * With no focused input at all the answer is sticky: a keyboard the sheet
+ * owned stays owned until `progress` is back at zero. That covers the two
+ * ways the signal lies mid-transition — the focused-input layout can land a
+ * frame after `progress` starts moving, and it goes null the moment a field
+ * blurs, while the keyboard takes another quarter second to leave. Letting go
+ * early would drop the sheet by the lift and then have it chase the keyboard
+ * down.
+ */
+export function resolveKeyboardOwner(input: KeyboardOwnerInput): boolean {
+	"worklet";
+	if (input.scope === "always") return true;
+	const candidate =
+		input.scope === "registered" ? input.registeredFocused : input.registeredFocused || input.inputInside;
+	if (candidate) return true;
+	if (input.inputFocused) return false;
+	return input.previousOwned && input.progress > 0;
+}

package/src/core/keyboard/keyboard-reset-guard.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "bun:test";
+import { shouldResetKeyboardAnimation } from "./keyboard-reset-guard";
+
+describe("shouldResetKeyboardAnimation", () => {
+	test("leaves a genuinely focused keyboard alone", () => {
+		// Every open-looking state is legitimate while an input holds focus,
+		// including a mid-animation one.
+		for (const [progress, height] of [
+			[0, 0],
+			[0.5, -160],
+			[1, -336],
+		] as const) {
+			expect(shouldResetKeyboardAnimation({ hasFocusedInput: true, height, progress })).toBe(false);
+		}
+	});
+
+	test("repairs an open state with nothing focused", () => {
+		expect(shouldResetKeyboardAnimation({ hasFocusedInput: false, height: -336, progress: 1 })).toBe(true);
+	});
+
+	test("repairs a half-open state, which is what an interrupted dismiss leaves behind", () => {
+		expect(shouldResetKeyboardAnimation({ hasFocusedInput: false, height: -160, progress: 0.5 })).toBe(true);
+	});
+
+	test("repairs either value on its own — the two are written separately", () => {
+		expect(shouldResetKeyboardAnimation({ hasFocusedInput: false, height: 0, progress: 1 })).toBe(true);
+		expect(shouldResetKeyboardAnimation({ hasFocusedInput: false, height: -336, progress: 0 })).toBe(true);
+	});
+
+	test("is a no-op on an already-closed state, so mounting never schedules a pointless write", () => {
+		expect(shouldResetKeyboardAnimation({ hasFocusedInput: false, height: 0, progress: 0 })).toBe(false);
+	});
+});

package/src/core/keyboard/keyboard-reset-guard.ts

@@ -0,0 +1,33 @@
+export type KeyboardAnimationState = {
+	/** `KeyboardProvider`'s shared progress, 0 closed through 1 open. */
+	progress: number;
+	/** `KeyboardProvider`'s shared height, negative while open. */
+	height: number;
+	/** Whether React Native's focus registry holds a focused `TextInput`. */
+	hasFocusedInput: boolean;
+};
+
+/**
+ * Whether `KeyboardProvider`'s shared animation values are provably stale.
+ *
+ * A port of `@delacour/react-native-ui`'s `shouldResetKeyboardAnimation`, so
+ * the engine's `useKeyboardAnimationGuard` and the wrapper's `Screen.Footer`
+ * guard agree on what stale means. keyboard-controller can be left holding an
+ * open keyboard after a dismiss its notifications never reported — a modal
+ * closing over a focused input is the classic — and the sheet would then lift
+ * for a keyboard that is not there.
+ *
+ * `hasFocusedInput` MUST come from React Native's own focus registry
+ * (`TextInput.State.currentlyFocusedInput()`), never from
+ * `KeyboardController.isVisible()`. The latter is fed by the very
+ * `keyboardWillShow` / `keyboardDidHide` notifications that go missing in the
+ * failure this guard exists for, so in the broken case it reads a stale `true`
+ * and would veto the repair. RN's registry is driven by the input's own native
+ * focus and blur — a genuinely independent signal.
+ */
+export function shouldResetKeyboardAnimation(state: KeyboardAnimationState): boolean {
+	"worklet";
+	// Never fight a real, focused keyboard.
+	if (state.hasFocusedInput) return false;
+	return state.progress !== 0 || state.height !== 0;
+}

package/src/core/keyboard/keyboard-step.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from "bun:test";
+import { keyboardStep } from "./keyboard-step";
+
+const base = {
+	behavior: "extend",
+	blurBehavior: "restore",
+	progress: 0,
+	previousProgress: 0,
+	owned: true,
+	previousOwned: true,
+	applied: false,
+	sheetOpen: true,
+} as const;
+
+describe("keyboardStep", () => {
+	test("applies on the first frame the keyboard rises for an owned input", () => {
+		expect(keyboardStep({ ...base, progress: 0.1 })).toBe("apply");
+	});
+
+	test("applies once — a rising keyboard already applied for is left alone", () => {
+		expect(keyboardStep({ ...base, progress: 0.5, previousProgress: 0.1, applied: true })).toBe(null);
+	});
+
+	test("applies when ownership arrives a frame late, mid-rise", () => {
+		expect(keyboardStep({ ...base, progress: 0.4, previousProgress: 0.4, previousOwned: false })).toBe("apply");
+	});
+
+	test("applies when focus moves into the sheet under a keyboard that is already up", () => {
+		expect(keyboardStep({ ...base, progress: 1, previousProgress: 1, previousOwned: false })).toBe("apply");
+	});
+
+	test("restores when the keyboard starts down", () => {
+		expect(keyboardStep({ ...base, progress: 0.9, previousProgress: 1, applied: true })).toBe("restore");
+	});
+
+	test("restores when focus leaves the sheet under a keyboard that stays up", () => {
+		expect(keyboardStep({ ...base, progress: 1, previousProgress: 1, owned: false, applied: true })).toBe("restore");
+	});
+
+	test("an interactive dismiss that turns back re-applies", () => {
+		expect(keyboardStep({ ...base, progress: 0.6, previousProgress: 0.4, applied: false })).toBe("apply");
+	});
+
+	test("blur behaviour none never restores, and clears the record so the next rise applies again", () => {
+		expect(keyboardStep({ ...base, blurBehavior: "none", progress: 0.9, previousProgress: 1, applied: true })).toBe(
+			"release"
+		);
+	});
+
+	test("interactive and none never apply — the lift is a derivation, not a snap", () => {
+		expect(keyboardStep({ ...base, behavior: "interactive", progress: 0.1 })).toBe(null);
+		expect(keyboardStep({ ...base, behavior: "none", progress: 0.1 })).toBe(null);
+	});
+
+	test("a keyboard nobody owns does nothing", () => {
+		expect(keyboardStep({ ...base, progress: 0.1, owned: false, previousOwned: false })).toBe(null);
+	});
+
+	test("a closed sheet never snaps for a keyboard", () => {
+		expect(keyboardStep({ ...base, progress: 0.1, sheetOpen: false })).toBe(null);
+	});
+
+	test("a keyboard that falls without anything applied is nothing to restore", () => {
+		expect(keyboardStep({ ...base, progress: 0.5, previousProgress: 0.6 })).toBe(null);
+	});
+});

package/src/core/keyboard/keyboard-step.ts

@@ -0,0 +1,53 @@
+import type { KeyboardBehavior, KeyboardBlurBehavior } from "../sheet.types";
+
+export type KeyboardStepInput = {
+	behavior: KeyboardBehavior;
+	blurBehavior: KeyboardBlurBehavior;
+	/** keyboard-controller's `progress` this frame and last. */
+	progress: number;
+	previousProgress: number;
+	/** `resolveKeyboardOwner` this frame and last. */
+	owned: boolean;
+	previousOwned: boolean;
+	/** Whether the behaviour's snap has run for the keyboard currently up. */
+	applied: boolean;
+	/** The sheet is above its closed height, settled or on the way. */
+	sheetOpen: boolean;
+};
+
+/**
+ * What the behaviour reaction does this frame.
+ *
+ * `apply` — snap for the keyboard: `extend` to the highest detent,
+ * `fillParent` to the container. `restore` — the keyboard is leaving or focus
+ * left the sheet, and `keyboardBlurBehavior: "restore"` sends the sheet back
+ * to the detent it held before. `release` — the same moment under
+ * `blurBehavior: "none"`: nothing moves, but the record clears so the next
+ * rise applies again. `null` — nothing.
+ */
+export type KeyboardStep = "apply" | "restore" | "release" | null;
+
+/**
+ * The show/hide decision, as a pure function of two consecutive samples.
+ *
+ * `interactive` and `none` never snap — one lifts by derivation, the other
+ * does nothing — so they always return `null`. For the two that do, a rise
+ * (`progress` climbing, or ownership arriving under a keyboard already up)
+ * applies once, and a fall (`progress` dropping, or ownership leaving)
+ * restores once; an interactive dismiss that turns back mid-way applies
+ * again, because the fall already restored.
+ */
+export function keyboardStep(input: KeyboardStepInput): KeyboardStep {
+	"worklet";
+	if (input.behavior !== "extend" && input.behavior !== "fillParent") return null;
+
+	const rising = input.progress > input.previousProgress || (input.owned && !input.previousOwned);
+	const falling = input.progress < input.previousProgress || (!input.owned && input.previousOwned);
+
+	if (input.applied) {
+		if (!falling) return null;
+		return input.blurBehavior === "restore" ? "restore" : "release";
+	}
+	if (!input.owned || !input.sheetOpen || input.progress <= 0) return null;
+	return rising ? "apply" : null;
+}

package/src/core/machine/define-sheet-machine.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, test } from "bun:test";
+import { defineSheetMachine } from "./define-sheet-machine";
+import type { SheetMachineSnapshot } from "./machine.types";
+
+type Step = "details" | "confirm" | "success";
+type Context = { name: string; agreed: boolean };
+type Event =
+	| { type: "NEXT" }
+	| { type: "BACK" }
+	| { type: "EDIT"; field: keyof Context; value: Context[keyof Context] }
+	| { type: "RESET" };
+
+const machine = defineSheetMachine<Step, Context, Event>({
+	id: "checkout",
+	initial: "details",
+	context: { name: "", agreed: false },
+	states: {
+		details: {
+			snapPoints: ["50%"],
+			on: {
+				NEXT: { target: "confirm", guard: (context) => context.name.length > 0 },
+				EDIT: {
+					target: "details",
+					assign: (context, event) => ({ ...context, [event.field]: event.value }),
+				},
+			},
+		},
+		confirm: {
+			on: {
+				NEXT: { target: "success", guard: (context) => context.agreed },
+				BACK: "details",
+				EDIT: {
+					target: "confirm",
+					assign: (context, event) => ({ ...context, [event.field]: event.value }),
+				},
+			},
+		},
+		success: {
+			snapPoints: [240],
+			dismissible: false,
+			on: { RESET: { target: "details", assign: () => ({ name: "", agreed: false }) } },
+		},
+	},
+});
+
+const filled: SheetMachineSnapshot<Step, Context> = {
+	value: "details",
+	context: { name: "Ada", agreed: false },
+	history: [],
+};
+
+describe("defineSheetMachine", () => {
+	test("initial snapshot is the configured initial state, context and an empty history", () => {
+		expect(machine.initial).toEqual({ value: "details", context: { name: "", agreed: false }, history: [] });
+		expect(machine.config.id).toBe("checkout");
+	});
+
+	test("steps are the states in declaration order", () => {
+		expect(machine.steps).toEqual(["details", "confirm", "success"]);
+	});
+
+	test("nodeOf exposes per-step snapPoints and dismissible", () => {
+		expect(machine.nodeOf("details").snapPoints).toEqual(["50%"]);
+		expect(machine.nodeOf("details").dismissible).toBeUndefined();
+		expect(machine.nodeOf("success").snapPoints).toEqual([240]);
+		expect(machine.nodeOf("success").dismissible).toBe(false);
+	});
+
+	describe("transition", () => {
+		test("succeeds on a bare string target and appends the origin to history", () => {
+			const result = machine.transition({ ...filled, value: "confirm", history: ["details"] }, { type: "BACK" });
+			expect(result).toEqual({
+				success: true,
+				data: { value: "details", context: filled.context, history: ["details", "confirm"] },
+			});
+		});
+
+		test("fails with no-transition when the state does not handle the event", () => {
+			expect(machine.transition(machine.initial, { type: "BACK" })).toEqual({
+				success: false,
+				error: { code: "no-transition", from: "details", event: "BACK" },
+			});
+		});
+
+		test("fails with guard-rejected when the guard says no", () => {
+			expect(machine.transition(machine.initial, { type: "NEXT" })).toEqual({
+				success: false,
+				error: { code: "guard-rejected", from: "details", to: "confirm", event: "NEXT" },
+			});
+		});
+
+		test("passes a guard once context allows it", () => {
+			const result = machine.transition(filled, { type: "NEXT" });
+			expect(result.success).toBe(true);
+			if (result.success) expect(result.data.value).toBe("confirm");
+		});
+
+		test("a self-target with assign keeps value, updates context and does not push history", () => {
+			const result = machine.transition(machine.initial, { type: "EDIT", field: "name", value: "Ada" });
+			expect(result).toEqual({
+				success: true,
+				data: { value: "details", context: { name: "Ada", agreed: false }, history: [] },
+			});
+		});
+
+		test("assign never mutates the incoming snapshot", () => {
+			const before = { value: "details" as const, context: { name: "", agreed: false }, history: [] as Step[] };
+			const original = structuredClone(before);
+			machine.transition(before, { type: "EDIT", field: "agreed", value: true });
+			expect(before).toEqual(original);
+		});
+
+		test("history is not shared with the incoming snapshot", () => {
+			const result = machine.transition(filled, { type: "NEXT" });
+			if (!result.success) throw new Error("expected success");
+			expect(result.data.history).not.toBe(filled.history);
+			expect(filled.history).toEqual([]);
+		});
+
+		test("assign runs before the target is entered so a reset lands with fresh context", () => {
+			const result = machine.transition(
+				{ value: "success", context: { name: "Ada", agreed: true }, history: ["details", "confirm"] },
+				{ type: "RESET" }
+			);
+			expect(result).toEqual({
+				success: true,
+				data: { value: "details", context: { name: "", agreed: false }, history: ["details", "confirm", "success"] },
+			});
+		});
+	});
+
+	describe("can", () => {
+		test("is true only when transition would succeed", () => {
+			expect(machine.can(machine.initial, { type: "NEXT" })).toBe(false);
+			expect(machine.can(machine.initial, { type: "BACK" })).toBe(false);
+			expect(machine.can(filled, { type: "NEXT" })).toBe(true);
+			expect(machine.can(machine.initial, { type: "EDIT", field: "name", value: "x" })).toBe(true);
+		});
+	});
+
+	describe("directionOf", () => {
+		test("follows declaration order when the target declares no direction", () => {
+			expect(machine.directionOf("details", "confirm")).toBe("forward");
+			expect(machine.directionOf("confirm", "details")).toBe("back");
+			expect(machine.directionOf("details", "success")).toBe("forward");
+			expect(machine.directionOf("details", "details")).toBe("forward");
+		});
+
+		test("an explicit direction on the target node wins over index order", () => {
+			const explicit = defineSheetMachine<"a" | "b" | "c", Record<string, never>, { type: "GO" }>({
+				initial: "a",
+				context: {},
+				states: {
+					a: { direction: "back", on: { GO: "b" } },
+					b: { on: { GO: "c" } },
+					c: { direction: "back", on: { GO: "a" } },
+				},
+			});
+			expect(explicit.directionOf("b", "c")).toBe("back");
+			expect(explicit.directionOf("c", "a")).toBe("back");
+			expect(explicit.directionOf("a", "b")).toBe("forward");
+		});
+	});
+
+	test("a full details → confirm → success run", () => {
+		let snapshot = machine.initial;
+		const send = (event: Event): void => {
+			const result = machine.transition(snapshot, event);
+			if (!result.success) throw new Error(`${result.error.code} on ${event.type} from ${result.error.from}`);
+			snapshot = result.data;
+		};
+
+		expect(machine.can(snapshot, { type: "NEXT" })).toBe(false);
+		send({ type: "EDIT", field: "name", value: "Ada" });
+		send({ type: "NEXT" });
+		expect(snapshot.value).toBe("confirm");
+		expect(machine.can(snapshot, { type: "NEXT" })).toBe(false);
+		send({ type: "EDIT", field: "agreed", value: true });
+		send({ type: "NEXT" });
+		expect(snapshot).toEqual({
+			value: "success",
+			context: { name: "Ada", agreed: true },
+			history: ["details", "confirm"],
+		});
+		expect(machine.nodeOf(snapshot.value).dismissible).toBe(false);
+	});
+});

package/src/core/machine/define-sheet-machine.ts

@@ -0,0 +1,35 @@
+/**
+ * A typed multi-step machine for a sheet body, with no XState in the graph.
+ *
+ * `defineSheetMachine` reads a config once and hands back the functions
+ * `BottomSheet.Steps` and `useSheetMachine` need: `transition` and `can` for
+ * the reducer, `steps` and `directionOf` for the animation, `nodeOf` for the
+ * per-step `snapPoints` and `dismissible` overrides. Any object with the same
+ * shape — an XState adapter, say — can stand in for it.
+ */
+import type { SheetEvent, SheetMachine, SheetMachineConfig, SheetStepDirection } from "./machine.types";
+import { transition } from "./transition";
+
+export function defineSheetMachine<S extends string, C, E extends SheetEvent>(
+	config: SheetMachineConfig<S, C, E>
+): SheetMachine<S, C, E> {
+	const { states } = config;
+	const steps = Object.keys(states) as S[];
+	const indexOf = new Map(steps.map((step, index) => [step, index]));
+
+	const directionOf = (from: S, to: S): SheetStepDirection => {
+		const explicit = states[to].direction;
+		if (explicit !== undefined) return explicit;
+		return (indexOf.get(to) ?? 0) < (indexOf.get(from) ?? 0) ? "back" : "forward";
+	};
+
+	return {
+		config,
+		initial: { value: config.initial, context: config.context, history: [] },
+		transition: (snapshot, event) => transition(states, snapshot, event),
+		can: (snapshot, event) => transition(states, snapshot, event).success,
+		steps,
+		directionOf,
+		nodeOf: (step) => states[step],
+	};
+}

package/src/core/machine/index.ts

@@ -0,0 +1,23 @@
+export { defineSheetMachine } from "./define-sheet-machine";
+export type {
+	SheetEvent,
+	SheetMachine,
+	SheetMachineConfig,
+	SheetMachineSnapshot,
+	SheetStateNode,
+	SheetStates,
+	SheetStepDirection,
+	SheetTransitionError,
+	SheetTransitionObject,
+	SheetTransitionResult,
+	SheetTransitionTarget,
+} from "./machine.types";
+export {
+	type SheetStepFrame,
+	type SheetStepOverride,
+	type SheetStepRole,
+	type SheetStepTransition,
+	stepFrame,
+	stepOverride,
+} from "./step-transition";
+export { resolveTarget, transition } from "./transition";