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

package/src/keyboard/use-bottom-sheet-text-input.ts

@@ -0,0 +1,79 @@
+import { type RefCallback, useCallback, useRef } from "react";
+import { findNodeHandle, TextInput } from "react-native";
+import { useOptionalBottomSheetInternal } from "../components/bottom-sheet.context";
+
+/**
+ * `findNodeHandle` for a value React Native's own types do not admit.
+ *
+ * `TextInput.State.currentlyFocusedInput()` returns a Fabric host instance and
+ * the shipped signature still describes the pre-Fabric parameter; the runtime
+ * accepts it. One cast, in one place.
+ */
+function nodeHandleOf(instance: unknown): number | null {
+	return findNodeHandle(instance as Parameters<typeof findNodeHandle>[0]);
+}
+
+export type BottomSheetTextInputHandlers = {
+	ref: RefCallback<TextInput | null>;
+	onFocus: () => void;
+	onBlur: () => void;
+};
+
+/**
+ * Registers a text field as the sheet's own, so the keyboard it raises is the
+ * sheet's to lift for whatever `keyboardScope` says.
+ *
+ * Spread the result onto any `TextInput` — yours, a skin's, a library's:
+ *
+ * ```tsx
+ * <TextInput {...useBottomSheetTextInput()} placeholder="Name" />
+ * ```
+ *
+ * `BottomSheet.TextInput` is this over React Native's `TextInput`, for the
+ * plain case. All three handlers matter: `ref` puts the field's native node
+ * in the sheet's registry, `onFocus` claims the keyboard, and `onBlur` gives
+ * it up — unless focus moved to another registered field in the same sheet,
+ * which React Native's own focus registry already knows. Without that check
+ * a tap from one field to the next would read as the keyboard closing and
+ * reopening, and the sheet would resize twice between two taps that never
+ * dismissed it.
+ *
+ * Outside a sheet the handlers are inert, so a form shared between a screen
+ * and a sheet needs no branch.
+ */
+export function useBottomSheetTextInput(): BottomSheetTextInputHandlers {
+	const registry = useOptionalBottomSheetInternal()?.keyboard ?? null;
+	const registered = useRef<number | null>(null);
+
+	const ref = useCallback<RefCallback<TextInput | null>>(
+		(instance) => {
+			if (registry === null) return;
+			const previous = registered.current;
+			if (previous !== null) {
+				registry.nodes.current.delete(previous);
+				registered.current = null;
+			}
+			if (instance === null) return;
+			const node = nodeHandleOf(instance);
+			if (node === null) return;
+			registry.nodes.current.add(node);
+			registered.current = node;
+		},
+		[registry]
+	);
+
+	const onFocus = useCallback(() => {
+		if (registry === null) return;
+		registry.focused.value = true;
+	}, [registry]);
+
+	const onBlur = useCallback(() => {
+		if (registry === null) return;
+		const focused = TextInput.State.currentlyFocusedInput();
+		const node = focused == null ? null : nodeHandleOf(focused);
+		if (node !== null && registry.nodes.current.has(node)) return;
+		registry.focused.value = false;
+	}, [registry]);
+
+	return { ref, onFocus, onBlur };
+}

package/src/keyboard/use-keyboard-animation-guard.ts

@@ -0,0 +1,59 @@
+import { useCallback, useEffect } from "react";
+import { TextInput } from "react-native";
+import { useKeyboardContext } from "react-native-keyboard-controller";
+import type { SharedValue } from "react-native-reanimated";
+import { scheduleOnUI } from "react-native-worklets";
+import { shouldResetKeyboardAnimation } from "../core";
+
+/** The one pair of animation values `KeyboardProvider` shares with the whole app. */
+export type KeyboardAnimationValues = {
+	progress: SharedValue<number>;
+	height: SharedValue<number>;
+};
+
+/**
+ * Snaps `KeyboardProvider`'s shared progress and height back to closed when
+ * they are provably stale.
+ *
+ * The focus check stays on the JS thread — React Native's focus registry
+ * lives there, and it is the one signal keyboard-controller's own missed
+ * notifications cannot poison — and the read-and-write happens inside one
+ * worklet, so the decision is made against the UI thread's own values.
+ * A snap, never an animation: the keyboard is already gone.
+ */
+export function reconcileKeyboardAnimation({ progress, height }: KeyboardAnimationValues): void {
+	if (TextInput.State.currentlyFocusedInput() != null) return;
+
+	scheduleOnUI(() => {
+		"worklet";
+		if (!shouldResetKeyboardAnimation({ hasFocusedInput: false, height: height.value, progress: progress.value })) {
+			return;
+		}
+		progress.value = 0;
+		height.value = 0;
+	});
+}
+
+/**
+ * Repairs a keyboard `KeyboardProvider` still believes is up.
+ *
+ * On iOS the provider's shared values are written by `keyboardWillShow` /
+ * `keyboardWillHide` alone, so any teardown that produces no `willHide` — a
+ * native-stack pop over a focused field, an interrupted interactive dismiss,
+ * an app suspend — leaves them pinned open, app-wide. A sheet mounted into
+ * that state would lift for a keyboard that is not there.
+ *
+ * Idempotent and cheap: a no-op whenever a field is genuinely focused. The
+ * sheet runs it every time its portal presents; a screen of your own can run
+ * it on mount the same way. The same decision as
+ * `@delacour/react-native-ui`'s `useKeyboardAnimationGuard`, over the same
+ * core function, so the two never disagree about what stale means.
+ */
+export function useKeyboardAnimationGuard(): void {
+	const { reanimated } = useKeyboardContext();
+	const reconcile = useCallback(() => reconcileKeyboardAnimation(reanimated), [reanimated]);
+
+	useEffect(() => {
+		reconcile();
+	}, [reconcile]);
+}

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

@@ -0,0 +1,163 @@
+import { type RefObject, useEffect, useMemo, useRef } from "react";
+import { useWindowDimensions } from "react-native";
+import { useKeyboardContext, useReanimatedFocusedInput } from "react-native-keyboard-controller";
+import { type SharedValue, useAnimatedReaction, useSharedValue } from "react-native-reanimated";
+import type { AnimateTo } from "../animation/animation.types";
+import {
+	CLOSED_INDEX,
+	GESTURE_SOURCE,
+	heightForIndex,
+	indexForHeight,
+	isInputInsideSheet,
+	keyboardInContainer,
+	keyboardStep,
+	resolveKeyboardOwner,
+} from "../core";
+import { ANIM_STATUS, type SheetGeometry, type SheetSharedState } from "../state/state.types";
+import { reconcileKeyboardAnimation } from "./use-keyboard-animation-guard";
+
+/**
+ * What `useBottomSheetTextInput` writes into: the native nodes of every
+ * registered field, and whether one of them holds focus.
+ */
+export type SheetKeyboardRegistry = {
+	nodes: RefObject<Set<number>>;
+	focused: SharedValue<boolean>;
+};
+
+export type UseSheetKeyboardOptions = {
+	state: SheetSharedState;
+	geometry: SheetGeometry;
+	animateTo: AnimateTo;
+	/** Whether the portal's children are mounted; the stale-keyboard guard runs on each presentation. */
+	presented: boolean;
+};
+
+/**
+ * The keyboard, from keyboard-controller's shared values into the sheet's.
+ *
+ * Two reactions. The first is the writer: every frame the keyboard's `height`
+ * (negative, from the window's bottom edge) or `progress` moves, or the
+ * focused input's frame changes, it writes `keyboardHeight` (positive, within
+ * the container), `keyboardProgress` and `keyboardOwned`. Ownership goes
+ * through `resolveKeyboardOwner` — a registered field, or under `inside` a
+ * focused input whose frame overlaps the sheet, and sticky through a
+ * transition once claimed. Everything the geometry derives from those three
+ * — the lift, the body's area, the footer's place — follows on the UI thread
+ * with no further code here.
+ *
+ * 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
+ * rises, and `keyboardBlurBehavior: "restore"` sends the sheet back to the
+ * detent 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`.
+ */
+export function useSheetKeyboard({
+	state,
+	geometry,
+	animateTo,
+	presented,
+}: UseSheetKeyboardOptions): SheetKeyboardRegistry {
+	const { reanimated } = useKeyboardContext();
+	const { height, progress } = reanimated;
+	const { input } = useReanimatedFocusedInput();
+	const { height: windowHeight } = useWindowDimensions();
+	const nodes = useRef(new Set<number>());
+	const focused = useSharedValue(false);
+	const indexBefore = useSharedValue(CLOSED_INDEX);
+	const applied = useSharedValue(false);
+
+	useEffect(() => {
+		if (presented) reconcileKeyboardAnimation(reanimated);
+	}, [presented, reanimated]);
+
+	useAnimatedReaction(
+		() => ({
+			raw: height.value,
+			progress: progress.value,
+			layout: input.value,
+			registered: focused.value,
+			offset: state.containerBottomOffset.value,
+			container: state.containerHeight.value,
+			position: geometry.position.value,
+		}),
+		(current) => {
+			const keyboardHeight = keyboardInContainer(current.raw, current.offset);
+			const containerBottom = windowHeight - current.offset;
+			const layout = current.layout;
+			const inside =
+				layout !== null &&
+				current.container > 0 &&
+				isInputInsideSheet({
+					inputY: layout.layout.absoluteY,
+					inputHeight: layout.layout.height,
+					sheetTop: containerBottom - current.container + current.position,
+					containerBottom,
+				});
+			const owned = resolveKeyboardOwner({
+				scope: state.config.value.keyboardScope,
+				registeredFocused: current.registered,
+				inputInside: inside,
+				inputFocused: layout !== null,
+				progress: current.progress,
+				previousOwned: state.keyboardOwned.value,
+			});
+			if (state.keyboardHeight.value !== keyboardHeight) state.keyboardHeight.value = keyboardHeight;
+			if (state.keyboardProgress.value !== current.progress) state.keyboardProgress.value = current.progress;
+			if (state.keyboardOwned.value !== owned) state.keyboardOwned.value = owned;
+		},
+		[state, geometry, height, progress, input, focused, windowHeight]
+	);
+
+	useAnimatedReaction(
+		() => ({ progress: progress.value, owned: state.keyboardOwned.value }),
+		(current, previous) => {
+			if (previous === null) return;
+			const config = state.config.value;
+			const closed = geometry.closedHeight.value;
+			const running = state.animStatus.value === ANIM_STATUS.RUNNING;
+			const sheetOpen = running ? state.animTarget.value > closed : state.base.value > closed;
+
+			const step = keyboardStep({
+				behavior: config.keyboardBehavior,
+				blurBehavior: config.keyboardBlurBehavior,
+				progress: current.progress,
+				previousProgress: previous.progress,
+				owned: current.owned,
+				previousOwned: previous.owned,
+				applied: applied.value,
+				sheetOpen,
+			});
+			if (step === null) return;
+
+			// A finger on the sheet owns `base`; the release will settle it.
+			const dragging = state.gestureSource.value !== GESTURE_SOURCE.NONE;
+
+			if (step === "apply") {
+				if (dragging) return;
+				applied.value = true;
+				indexBefore.value = running
+					? Math.round(indexForHeight(state.animTarget.value, geometry.detents.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);
+				return;
+			}
+
+			applied.value = false;
+			const index = indexBefore.value;
+			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);
+			if (Math.abs(target - state.base.value) > 0.5) animateTo(target, "keyboard", 0);
+		},
+		[state, geometry, animateTo, progress, applied, indexBefore]
+	);
+
+	return useMemo<SheetKeyboardRegistry>(() => ({ nodes, focused }), [focused]);
+}

package/src/layout/AGENTS.md

@@ -0,0 +1,52 @@
+# layout
+
+How the sheet learns the sizes the geometry needs.
+
+## Files
+
+| Path | What |
+| --- | --- |
+| `use-measure-height.ts` | An `onLayout` that writes a view's height into a shared value, and resets it to `UNMEASURED` on unmount |
+| `use-container-layout.ts` | The frame's `onLayout` and ref: height and width, plus `measureInWindow` for the offset between the frame's bottom and the window's |
+
+## What is measured
+
+| Value | By | Read for |
+| --- | --- | --- |
+| `containerHeight`, `containerWidth` | the frame `Portal` renders | every detent, `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` |
+
+Scrollables (BSHEET-4) feed `contentHeight` from `onContentSizeChange`
+instead of a layout.
+
+## The reset is the point
+
+A portal that unmounts its children on close takes the handle and the content
+with it. If their heights stayed, `layoutReady` would be true for a sheet with
+nothing in it and the next open would animate before the new content had
+measured. Every measuring hook resets its value to `UNMEASURED` on unmount, so
+the open goes back on the intent queue until the measurement lands again.
+
+A handle that is never written is a handle of height zero: `Container` reports
+that on mount when no `Handle` registered, so a handle-less sheet is not a
+sheet that never becomes ready.
+
+## Container resize
+
+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/`).
+
+## No synchronous first read
+
+The plan mentioned a Fabric `getBoundingClientRect` in a layout effect for a
+synchronous first measurement. It is not here: the open intent waits on
+`layoutReady` anyway, so the only thing a synchronous read would buy is one
+frame off the first open, and it would buy it with a host-instance method the
+type definitions do not yet name. Add it here, in these two hooks, if that
+frame ever shows.

package/src/layout/use-container-layout.ts

@@ -0,0 +1,63 @@
+import { type RefObject, useCallback, useEffect, useRef } from "react";
+import { Dimensions, type LayoutChangeEvent, type View } from "react-native";
+import { acceptContainerLayout, UNMEASURED } from "../core";
+import type { SheetSharedState } from "../state/state.types";
+
+export type ContainerLayout = {
+	ref: RefObject<View | null>;
+	onLayout: (event: LayoutChangeEvent) => void;
+};
+
+/**
+ * Measures the frame every sheet renders around itself.
+ *
+ * `onLayout` gives the height and width; `measureInWindow` gives where the
+ * frame's bottom edge sits relative to the window's, which is what a keyboard
+ * has to clear before it overlaps the sheet — a frame inside a tab bar's
+ * screen ends above the window, and the keyboard's first pixels overlap
+ * nothing.
+ *
+ * The 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.
+ *
+ * Unmounting resets every value to `UNMEASURED`, for the same reason
+ * `useMeasureHeight` does.
+ */
+export function useContainerLayout(state: SheetSharedState): ContainerLayout {
+	const ref = useRef<View | null>(null);
+	const { containerHeight, containerWidth, containerBottomOffset, keyboardHeight, keyboardProgress } = state;
+
+	useEffect(
+		() => () => {
+			containerHeight.value = UNMEASURED;
+			containerWidth.value = UNMEASURED;
+			containerBottomOffset.value = 0;
+		},
+		[containerHeight, containerWidth, containerBottomOffset]
+	);
+
+	const onLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			const { height, width } = event.nativeEvent.layout;
+			if (containerWidth.value !== width) containerWidth.value = width;
+
+			const accepted = acceptContainerLayout({
+				prev: containerHeight.value,
+				next: height,
+				keyboardHeight: keyboardHeight.value,
+				progress: keyboardProgress.value,
+			});
+			if (accepted && containerHeight.value !== height) containerHeight.value = height;
+
+			ref.current?.measureInWindow((_x, y, _width, measuredHeight) => {
+				const offset = Dimensions.get("window").height - (y + measuredHeight);
+				const clamped = Number.isFinite(offset) && offset > 0 ? offset : 0;
+				if (containerBottomOffset.value !== clamped) containerBottomOffset.value = clamped;
+			});
+		},
+		[containerHeight, containerWidth, containerBottomOffset, keyboardHeight, keyboardProgress]
+	);
+
+	return { ref, onLayout };
+}

package/src/layout/use-measure-height.ts

@@ -0,0 +1,40 @@
+import { useCallback, useEffect } from "react";
+import type { LayoutChangeEvent } from "react-native";
+import type { SharedValue } from "react-native-reanimated";
+import { UNMEASURED } from "../core";
+
+/**
+ * Feeds a view's height into a shared value from its `onLayout`, and resets
+ * it to `UNMEASURED` when the view goes away.
+ *
+ * The reset is the important half. A portal that unmounts its children on
+ * close takes the handle and the content with it; if their heights stayed,
+ * `layoutReady` would be true for a sheet with nothing in it and the next open
+ * would animate before the new content had measured. `-1` puts the open back
+ * on the queue until the measurement lands again.
+ *
+ * `subtract` takes a constant off every measurement, never below zero: the
+ * footer measures its styled box, which pads through the safe-area band, and
+ * records the box less the band.
+ *
+ * Written once per part rather than shared with the container, because a part
+ * only wants its own height; the container also wants its offset from the
+ * window's bottom.
+ */
+export function useMeasureHeight(target: SharedValue<number>, subtract = 0): (event: LayoutChangeEvent) => void {
+	useEffect(
+		() => () => {
+			target.value = UNMEASURED;
+		},
+		[target]
+	);
+
+	return useCallback(
+		(event: LayoutChangeEvent) => {
+			const measured = event.nativeEvent.layout.height - subtract;
+			const height = measured > 0 ? measured : 0;
+			if (target.value !== height) target.value = height;
+		},
+		[target, subtract]
+	);
+}

package/src/lib/AGENTS.md

@@ -0,0 +1,35 @@
+# lib
+
+Four utilities copied from `@delacour/react-native-ui`, with the one thing
+this package must not have removed.
+
+## Files
+
+| Path | What |
+| --- | --- |
+| `slot.tsx` | `Slot` — renders its props into its single child; what backs every `asChild` |
+| `merge-props.ts` | Child props win; event handlers chain slot-first; `style` arrays flatten with the child last |
+| `compose-refs.ts` | Fans one node out to several refs, honouring React 19 cleanup returns |
+| `use-controllable-state.ts` | Controlled or uncontrolled from one hook; the mode is locked in on first render |
+
+## What changed in the copy
+
+`merge-props.ts` in the skin also merges class strings through its `cn`. This
+package has no class strings to merge — `src/no-classname.test.ts` — so the
+branch is gone and nothing here imports `cn`. Everything else is the same
+file, and should stay the same file: a fix in one belongs in both.
+
+## Why copied rather than imported
+
+`@delacour/react-native-ui` is the skin over this engine, and it depends on
+the engine as an optional peer. The engine importing the skin's `lib` would
+close that cycle, and a published package cannot reach into a sibling
+workspace's `src` anyway. Four small files is the price of a clean direction.
+
+## Slot and animated styles
+
+Do not pass a Reanimated style through `Slot`. React Native deep freezes style
+props on a non-animated component in development, and Reanimated's effect then
+throws trying to write to the frozen object. No part here does; a part that
+needs to would render the child through an animated counterpart of its own
+type, the way the skin's `Pressable` does.

package/src/lib/compose-refs.ts

@@ -0,0 +1,37 @@
+import type { Ref } from "react";
+
+type RefCleanup = () => void;
+
+/**
+ * Fans a single node out to several refs.
+ *
+ * React 19 lets a callback ref return a cleanup function. When any of the given
+ * refs does, the composed ref returns a cleanup of its own that runs each child
+ * cleanup and nulls out every object ref.
+ */
+export function composeRefs<T>(...refs: (Ref<T> | undefined)[]): (node: T | null) => RefCleanup | undefined {
+	return (node) => {
+		const cleanups: RefCleanup[] = [];
+
+		for (const ref of refs) {
+			if (!ref) continue;
+
+			if (typeof ref === "function") {
+				const result = ref(node);
+				if (typeof result === "function") cleanups.push(result);
+				continue;
+			}
+
+			ref.current = node;
+		}
+
+		if (cleanups.length === 0) return undefined;
+
+		return () => {
+			for (const cleanup of cleanups) cleanup();
+			for (const ref of refs) {
+				if (ref && typeof ref !== "function") ref.current = null;
+			}
+		};
+	};
+}

package/src/lib/merge-props.ts

@@ -0,0 +1,42 @@
+type UnknownProps = Record<string, unknown>;
+
+function isEventHandlerKey(key: string): boolean {
+	return key.startsWith("on") && key.length > 2 && key[2] === key[2]?.toUpperCase();
+}
+
+/**
+ * Merges a slot's own props with those of the element it renders into.
+ *
+ * Child props win, with two exceptions: event handlers are chained
+ * slot-first-then-child so neither side is silently dropped, and `style` is
+ * flattened into an array with the child last (React Native resolves style
+ * arrays left to right).
+ *
+ * The copy in `@delacour/react-native-ui` also merges class strings; this
+ * package has none to merge, which is the whole point of it.
+ */
+export function mergeProps<T extends UnknownProps>(slotProps: UnknownProps, childProps: UnknownProps): T {
+	const merged: UnknownProps = { ...slotProps };
+
+	for (const key of Object.keys(childProps)) {
+		const slotValue = slotProps[key];
+		const childValue = childProps[key];
+
+		if (isEventHandlerKey(key) && typeof slotValue === "function" && typeof childValue === "function") {
+			merged[key] = (...args: unknown[]) => {
+				(slotValue as (...a: unknown[]) => unknown)(...args);
+				return (childValue as (...a: unknown[]) => unknown)(...args);
+			};
+			continue;
+		}
+
+		if (key === "style" && slotValue != null && childValue != null) {
+			merged[key] = [slotValue, childValue].flat();
+			continue;
+		}
+
+		merged[key] = childValue;
+	}
+
+	return merged as T;
+}

package/src/lib/slot.tsx

@@ -0,0 +1,44 @@
+import { Children, cloneElement, isValidElement, type ReactElement, type ReactNode, type Ref } from "react";
+import { composeRefs } from "./compose-refs";
+import { mergeProps } from "./merge-props";
+
+type SlotProps = {
+	children?: ReactNode;
+	[key: string]: unknown;
+};
+
+type ChildProps = Record<string, unknown> & { ref?: Ref<unknown> };
+
+/**
+ * Renders its props into its single child instead of emitting an element.
+ *
+ * This is what backs every `asChild` prop here: `<BottomSheet.Trigger asChild>`
+ * hands its `onPress` to the button inside it with no extra view in the tree.
+ * Props are combined by {@link mergeProps} and refs by {@link composeRefs}.
+ *
+ * React 19 exposes `ref` as an ordinary prop, so no `forwardRef` is involved.
+ *
+ * Do not pass a Reanimated style through this. React Native deep freezes style
+ * props on a non-animated component in development, and Reanimated's effect
+ * then throws trying to write to the frozen object.
+ */
+export function Slot({ children, ...slotProps }: SlotProps): ReactElement {
+	const count = Children.count(children);
+
+	if (count !== 1) {
+		throw new Error(`Slot expects exactly one child element, received ${count}. Did you mean to omit \`asChild\`?`);
+	}
+
+	const child = Children.only(children);
+
+	if (!isValidElement(child)) {
+		throw new Error("Slot expects a single React element child; text and fragments cannot receive props.");
+	}
+
+	const childProps = child.props as ChildProps;
+	const merged = mergeProps<ChildProps>(slotProps, childProps);
+	merged.ref = composeRefs(slotProps.ref as Ref<unknown> | undefined, childProps.ref);
+
+	return cloneElement(child, merged);
+}
+Slot.displayName = "DelacourBottomSheet.Slot";

package/src/lib/use-controllable-state.ts

@@ -0,0 +1,45 @@
+import { useCallback, useRef, useState } from "react";
+
+type UseControllableStateOptions<T> = {
+	/** Controlled value. When not `undefined` the hook defers to the caller. */
+	value?: T;
+	/** Initial value used while uncontrolled. */
+	defaultValue: T;
+	onChange?: (value: T) => void;
+};
+
+/**
+ * Supports both controlled and uncontrolled usage from one hook.
+ *
+ * While `value` is undefined the state is held internally; once a value is
+ * passed the caller owns it and the setter only reports upward. Which mode is
+ * in play is locked in on first render — switching later is a caller bug and
+ * warns in development rather than silently changing behaviour.
+ */
+export function useControllableState<T>({
+	value,
+	defaultValue,
+	onChange,
+}: UseControllableStateOptions<T>): [T, (next: T) => void] {
+	const isControlled = value !== undefined;
+	const wasControlled = useRef(isControlled);
+	const [uncontrolled, setUncontrolled] = useState<T>(defaultValue);
+
+	if (process.env.NODE_ENV !== "production" && wasControlled.current !== isControlled) {
+		console.warn(
+			`useControllableState: switched from ${wasControlled.current ? "controlled" : "uncontrolled"} to ` +
+				`${isControlled ? "controlled" : "uncontrolled"}. Pick one for the lifetime of the component.`
+		);
+		wasControlled.current = isControlled;
+	}
+
+	const setValue = useCallback(
+		(next: T) => {
+			if (!isControlled) setUncontrolled(next);
+			onChange?.(next);
+		},
+		[isControlled, onChange]
+	);
+
+	return [isControlled ? value : uncontrolled, setValue];
+}