@delacour/react-native-ui 0.1.0-alpha.4 → 0.2.0-alpha.20261010061731

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

@@ -1,150 +1,81 @@
-import { BottomSheetFooter as GorhomBottomSheetFooter } from "@gorhom/bottom-sheet";
-import { type ComponentProps, type ReactElement, type ReactNode, useCallback, useEffect } from "react";
-import { type LayoutChangeEvent, View, type ViewProps } from "react-native";
-import { useReanimatedKeyboardAnimation } from "react-native-keyboard-controller";
-import Animated, { type SharedValue, useAnimatedStyle } from "react-native-reanimated";
-import { useSafeAreaInsets } from "react-native-safe-area-context";
+import {
+	BottomSheet as Headless,
+	type BottomSheetFooterProps as HeadlessProps,
+} from "@delacour/react-native-bottom-sheet";
+import type { ReactElement } from "react";
+import { withUniwind } from "uniwind";
 import { BOTTOM_SHEET_FOOTER_PADDING, bottomSheetVariants } from "./bottom-sheet.variants";
 
-type GorhomFooterProps = ComponentProps<typeof GorhomBottomSheetFooter>;
+type StyledFooterComponent = (props: HeadlessProps & { className?: string }) => ReactElement | null;
 
-export type BottomSheetFooterProps = Omit<ViewProps, "children"> & {
-	/**
-	 * Pin the footer to the bottom of the sheet, above the keyboard, instead of
-	 * leaving it in the content's flow.
-	 *
-	 * Off by default, matching `Screen.Footer` — a footer holding a submit button
-	 * under a short sheet wants to sit where it was written, and a sheet only
-	 * needs the pinned treatment once its body can scroll under one.
-	 *
-	 * @default false
-	 */
-	sticky?: boolean;
+// Built once at module scope; the classes land on the engine's inner, measured
+// view, after its own `padding`, so the gutter here wins the horizontal axis.
+const StyledFooter = withUniwind(Headless.Footer) as unknown as StyledFooterComponent;
+
+export type BottomSheetFooterProps = HeadlessProps & {
 	className?: string;
-	children?: ReactNode;
-	/**
-	 * The sheet's own footer position. Injected by `BottomSheet.Container` when it
-	 * hoists a sticky footer; never written at a call site.
-	 */
-	animatedFooterPosition?: GorhomFooterProps["animatedFooterPosition"];
-	/**
-	 * Where this footer publishes its measured height. Injected alongside the
-	 * position, and read by whatever the sheet's body is so it can reserve exactly
-	 * what the footer covers. Never written at a call site.
-	 */
-	footerHeight?: SharedValue<number>;
 };
 
 /**
- * A row of controls at the bottom of the sheet — pinned, or in the flow.
- *
- * **A sticky footer is not rendered where it is written.** gorhom takes it as a
- * `footerComponent` render prop rather than as a child, so
- * `BottomSheet.Container` lifts this element out of its children and clones it
- * into that slot with the sheet's animated footer position attached. An inline
- * footer needs none of that and stays exactly where it was put.
- *
- * The two branches deliberately look different. An inline footer is in the flow
- * and inherits the sheet's surface; a pinned one draws OVER the content, so it
- * brings a background and a top hairline of its own — without them the content
- * scrolls straight through it and its buttons are legible only where they happen
- * to overlap blank space. That is `Screen.Footer`'s rule about its backing, one
- * component along.
- *
- * **A pinned footer is TALLER by the safe-area band; it is not moved up by it.**
- * gorhom's own `bottomInset` translates the whole footer up instead, which
- * leaves a band the height of the home indicator between the footer and the
- * bottom of the sheet — and the content scrolls through it in plain view. So
- * `bottomInset` stays 0 and the band becomes the footer's own `paddingBottom`,
- * which puts its surface against the bottom of the screen where it belongs.
- *
- * The keyboard then needs that band back, and **only that band**. Its own
- * padding stays, so the controls never end up flush against the keyboard, and
- * the footer genuinely gets shorter rather than sliding down — which is what
- * lets the body's reserve shrink with it instead of over-reserving by the height
- * of a home indicator that is no longer there.
+ * A row of controls at the bottom of the sheet — in the flow, or pinned.
  *
- * It publishes its measured height into the sheet. `BottomSheet.Content` reserves
- * exactly that plus a gap with a spacer, and `BottomSheet.ScrollView` gives it up
- * as its own frame so its scroll indicator stops at this footer's hairline. The
- * height is a shared value read by an animated style either way, never
- * content-container padding — `Screen` reserves its own chrome the same way and
- * for the same reason.
+ * **`sticky` is off by default, matching `Screen.Footer`**, and that is the one
+ * place this skin overrides the engine's default: a footer holding a submit
+ * button under a short sheet wants to sit where it was written, and a sheet
+ * only needs the pinned treatment once its body can scroll under one. Write a
+ * pinned footer inside `Container`, after the body; an inline one inside the
+ * body, where it should scroll.
  *
- * **Do not put a `KeyboardStickyView` in here.** gorhom's `animatedFooterPosition`
- * already carries the footer clear of the keyboard; this translate only gives up
- * the safe-area band on top of that. A third mechanism moving the same view
- * would fight both for prop ownership every frame.
+ * The two branches deliberately look different. An inline footer is in the
+ * flow and inherits the sheet's surface; a pinned one draws OVER the content,
+ * so it brings a background and a top hairline of its own — without them the
+ * content scrolls straight through it. That is `Screen.Footer`'s rule about its
+ * backing, one component along.
  *
- * Written with `sticky` but rendered outside a container, it falls back to the
- * inline branch rather than throwing: there is no footer position to ride, and a
- * row of buttons in the flow is the useful failure.
+ * Everything else is the engine's: a pinned footer is translated to the
+ * geometry's footer line, which the core proves holds still through a keyboard
+ * animation, so its buttons land on the keyboard's top edge without moving;
+ * the safe-area band under it is a spacer the geometry owns; and its measured
+ * height is what the body reserves and the dynamic snap point counts. The
+ * `padding` goes to the engine rather than a class for that reason — it has to
+ * be inside the measured box.
  *
  * @example
- * <BottomSheet.Footer>
- *   <Button onPress={save}>Save</Button>
- * </BottomSheet.Footer>
+ * <BottomSheet.Container>
+ *   <BottomSheet.Content>{fields}</BottomSheet.Content>
+ *   <BottomSheet.Footer sticky>
+ *     <Button onPress={save}>Save</Button>
+ *   </BottomSheet.Footer>
+ * </BottomSheet.Container>
  *
  * @example
- * <BottomSheet.Footer sticky>
- *   <Button onPress={submit}>Submit</Button>
- * </BottomSheet.Footer>
+ * // In the flow — inside the body, scrolling with it.
+ * <BottomSheet.ScrollView>
+ *   {copy}
+ *   <BottomSheet.Footer>
+ *     <Button>Continue</Button>
+ *   </BottomSheet.Footer>
+ * </BottomSheet.ScrollView>
  */
 export function BottomSheetFooter({
-	animatedFooterPosition,
 	className,
-	children,
-	footerHeight,
-	onLayout,
 	sticky = false,
-	style,
+	padding,
 	...props
 }: BottomSheetFooterProps): ReactElement {
-	const { bottom } = useSafeAreaInsets();
-	const { progress } = useReanimatedKeyboardAnimation();
 	const slots = bottomSheetVariants();
 
-	// The footer keeps its own padding and gives up only the safe-area band, which
-	// collapses as the keyboard arrives. `progress` runs 0 → 1 over the keyboard's
-	// own animation, so the two travel together.
-	const padding = useAnimatedStyle(() => ({
-		paddingBottom: BOTTOM_SHEET_FOOTER_PADDING + bottom * (1 - progress.value),
-		paddingTop: BOTTOM_SHEET_FOOTER_PADDING,
-	}));
-
-	const handleLayout = useCallback(
-		(event: LayoutChangeEvent) => {
-			if (footerHeight) footerHeight.value = event.nativeEvent.layout.height;
-			onLayout?.(event);
-		},
-		[footerHeight, onLayout]
-	);
-
-	useEffect(() => {
-		return () => {
-			if (footerHeight) footerHeight.value = 0;
-		};
-	}, [footerHeight]);
-
-	if (!sticky || animatedFooterPosition === undefined) {
-		return (
-			<View className={slots.footer({ className })} style={style} {...props}>
-				{children}
-			</View>
-		);
+	if (!sticky) {
+		return <StyledFooter className={slots.footer({ className })} padding={padding} sticky={false} {...props} />;
 	}
 
 	return (
-		<GorhomBottomSheetFooter animatedFooterPosition={animatedFooterPosition} bottomInset={0}>
-			<Animated.View
-				className={slots.stickyFooter({ className })}
-				onLayout={handleLayout}
-				style={[padding, style]}
-				{...props}
-			>
-				{children}
-			</Animated.View>
-		</GorhomBottomSheetFooter>
+		<StyledFooter
+			className={slots.stickyFooter({ className })}
+			padding={padding ?? BOTTOM_SHEET_FOOTER_PADDING}
+			sticky
+			{...props}
+		/>
 	);
 }
 BottomSheetFooter.displayName = "DelacourUI.BottomSheet.Footer";

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

@@ -1,36 +1,41 @@
-import type { BottomSheetHandleProps as GorhomBottomSheetHandleProps } from "@gorhom/bottom-sheet";
+import {
+	BottomSheet as Headless,
+	type BottomSheetHandleProps as HeadlessProps,
+} from "@delacour/react-native-bottom-sheet";
 import type { ReactElement } from "react";
-import { View, type ViewProps } from "react-native";
+import { type StyleProp, View, type ViewStyle } from "react-native";
+import { withUniwind } from "uniwind";
 import { bottomSheetVariants } from "./bottom-sheet.variants";
 
-export type BottomSheetHandleProps = Partial<GorhomBottomSheetHandleProps> &
-	Omit<ViewProps, "children"> & {
-		className?: string;
-		/** Style for the pill itself. What gorhom's `handleIndicatorStyle` becomes. */
-		indicatorStyle?: ViewProps["style"];
-		indicatorClassName?: string;
-	};
+type StyledHandleComponent = (props: HeadlessProps & { className?: string }) => ReactElement | null;
+
+// Built at module scope, or every render mints a new component type and the
+// engine's pan re-attaches to a fresh view.
+const StyledHandle = withUniwind(Headless.Handle) as unknown as StyledHandleComponent;
+
+export type BottomSheetHandleProps = HeadlessProps & {
+	className?: string;
+	/** Classes for the grabber itself. */
+	indicatorClassName?: string;
+	indicatorStyle?: StyleProp<ViewStyle>;
+};
 
 /**
- * The grabber at the top of the sheet.
+ * The grabber's row.
  *
- * Supplied to gorhom as `handleComponent` for the same reason the background is:
- * this package paints with classNames, and gorhom's `handleStyle` /
- * `handleIndicatorStyle` cannot carry one. Both still arrive — gorhom passes
- * them down as `style` and `indicatorStyle` — so a caller who has a style object
- * rather than a class is not locked out.
+ * The engine's handle draws nothing of its own: it owns the pan, measures
+ * itself into the sheet's height, and is the adjustable element a screen
+ * reader steps through the snap points with. This puts the pill inside it, and
+ * classes on both.
  *
- * The pill is drawn but never announced: gorhom's own handle container wraps this
- * in the `Animated.View` that owns the pan and carries the accessibility surface,
- * so a second announced element here would put a nameless control in front of
- * every sheet.
+ * Pass children to replace the pill; the row, the pan and the accessibility
+ * stay.
  *
- * The two animated variables are destructured off rather than spread — see
- * `BottomSheetBackground`.
+ * @example
+ * <BottomSheet.Handle indicatorClassName="bg-primary" />
  */
 export function BottomSheetHandle({
-	animatedIndex: _animatedIndex,
-	animatedPosition: _animatedPosition,
+	children,
 	className,
 	indicatorClassName,
 	indicatorStyle,
@@ -39,9 +44,9 @@ export function BottomSheetHandle({
 	const slots = bottomSheetVariants();
 
 	return (
-		<View className={slots.handle({ className })} {...props}>
-			<View className={slots.handleIndicator({ className: indicatorClassName })} style={indicatorStyle} />
-		</View>
+		<StyledHandle className={slots.handle({ className })} {...props}>
+			{children ?? <View className={slots.handleIndicator({ className: indicatorClassName })} style={indicatorStyle} />}
+		</StyledHandle>
 	);
 }
 BottomSheetHandle.displayName = "DelacourUI.BottomSheet.Handle";

package/src/components/bottom-sheet/bottom-sheet-legend-list.tsx

@@ -0,0 +1,69 @@
+import {
+	type BottomSheetScrollableProps,
+	createBottomSheetScrollable,
+	SCROLLABLE_TYPE,
+	useBottomSheetInternal,
+} from "@delacour/react-native-bottom-sheet";
+import type { LegendListRef } from "@legendapp/list/react-native";
+import { AnimatedLegendList, type AnimatedLegendListProps } from "@legendapp/list/reanimated";
+import type { ReactElement, Ref } from "react";
+import { withUniwind } from "uniwind";
+import { cn } from "../../lib/cn";
+import { BOTTOM_SHEET_FOOTER_GAP, bottomSheetVariants } from "./bottom-sheet.variants";
+
+/**
+ * `AnimatedLegendList` as a sheet body.
+ *
+ * Made once at module scope, as the factory requires: the wrapper drives the
+ * list with `animatedProps` and an animated `onScroll`, and a component made
+ * inside a render is a new type every frame. Registered as a flat list, which
+ * is what it is to the sheet — one scroll offset, one drag budget.
+ */
+const SheetLegendList = createBottomSheetScrollable(AnimatedLegendList, SCROLLABLE_TYPE.FLAT_LIST);
+
+/** The class props restated so `<ItemT>` survives `withUniwind` — see `bottom-sheet-flat-list.tsx`. */
+type StyledLegendListComponent = <ItemT>(
+	props: AnimatedLegendListProps<ItemT> &
+		BottomSheetScrollableProps & { ref?: Ref<LegendListRef>; className?: string; contentContainerClassName?: string }
+) => ReactElement | null;
+
+const StyledLegendList = withUniwind(SheetLegendList) as unknown as StyledLegendListComponent;
+
+export type BottomSheetLegendListProps<ItemT> = Omit<AnimatedLegendListProps<ItemT>, "renderScrollComponent"> &
+	BottomSheetScrollableProps & {
+		ref?: Ref<LegendListRef>;
+		className?: string;
+		/** Classes for the content container. Same gutter and gap as `Content`. */
+		contentContainerClassName?: string;
+	};
+
+/**
+ * A `LegendList` body, for a list long enough that `FlatList`'s virtualisation
+ * shows.
+ *
+ * Built here rather than in the engine because `@legendapp/list` is this
+ * library's optional peer, not the engine's: the engine exports the factory,
+ * and this is what the factory is for. The same scroll lock, drag budget and
+ * content-size snap point as the other three bodies.
+ *
+ * @example
+ * <BottomSheet.LegendList data={rows} keyExtractor={(row) => row.id} renderItem={renderRow} />
+ */
+export function BottomSheetLegendList<ItemT>({
+	className,
+	contentContainerClassName,
+	contentContainerStyle,
+	...props
+}: BottomSheetLegendListProps<ItemT>): ReactElement {
+	const { hasFooter } = useBottomSheetInternal();
+
+	return (
+		<StyledLegendList
+			className={cn(className)}
+			contentContainerClassName={bottomSheetVariants().scrollContent({ className: contentContainerClassName })}
+			contentContainerStyle={[{ paddingBottom: hasFooter ? BOTTOM_SHEET_FOOTER_GAP : 0 }, contentContainerStyle]}
+			{...props}
+		/>
+	);
+}
+BottomSheetLegendList.displayName = "DelacourUI.BottomSheet.LegendList";

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

@@ -1,180 +1,58 @@
 import {
-	BottomSheetBackdrop,
-	type BottomSheetBackdropProps,
-	useBottomSheet as useGorhomBottomSheet,
-} from "@gorhom/bottom-sheet";
-import type { ReactElement, ReactNode } from "react";
-import { StyleSheet } from "react-native";
-import Animated, { useAnimatedStyle } from "react-native-reanimated";
+	BottomSheet as Headless,
+	type BottomSheetOverlayProps as HeadlessProps,
+} from "@delacour/react-native-bottom-sheet";
+import type { ReactElement } from "react";
 import { withUniwind } from "uniwind";
-import { Pressable } from "../pressable";
 import {
 	BOTTOM_SHEET_BACKDROP_INDICES,
 	BOTTOM_SHEET_OVERLAY_OPACITY,
 	bottomSheetVariants,
 } from "./bottom-sheet.variants";
 
-/**
- * gorhom's backdrop is third-party and takes a `style`, never a `className`, and
- * it is a leaf — there is no inner view to hang classes on the way
- * `BottomSheet.Content` and `BottomSheet.Footer` do. So it is wrapped, once, at
- * module scope. In render `withUniwind` would mint a new component type every
- * frame and remount the scrim mid-fade. See AGENTS.md rule 7.
- */
-const StyledBackdrop = withUniwind(BottomSheetBackdrop);
+type StyledOverlayComponent = (props: HeadlessProps & { className?: string }) => ReactElement | null;
+
+// Third-party to Uniwind, so `className` needs the wrapper, built once at
+// module scope.
+const StyledOverlay = withUniwind(Headless.Overlay) as unknown as StyledOverlayComponent;
 
-export type BottomSheetOverlayProps = Partial<BottomSheetBackdropProps> & {
+export type BottomSheetOverlayProps = HeadlessProps & {
 	className?: string;
-	/**
-	 * Opacity at full appearance.
-	 *
-	 * Defaults to 1 rather than gorhom's 0.5, because `--overlay` carries
-	 * its own alpha — the two would otherwise multiply and land the scrim at a
-	 * fifth of what the theme asked for.
-	 */
-	opacity?: number;
-	/** Snap index the scrim is fully in by. @default 0, the first snap point */
-	appearsOnIndex?: number;
-	/** Snap index the scrim is gone by. @default -1, the closed position */
-	disappearsOnIndex?: number;
-	/** Let touches reach the app behind the scrim. @default false */
-	enableTouchThrough?: boolean;
-	/** Close the sheet when the scrim is pressed. @default true */
-	isCloseOnPress?: boolean;
-	/** Announced on the pressable scrim. Ignored when it does not close. */
-	accessibilityLabel?: string;
-	onPress?: () => void;
-	children?: ReactNode;
 };
 
 /**
  * The scrim over the app behind the sheet.
  *
- * **It is not rendered where it is written.** gorhom takes the backdrop as a
- * `backdropComponent` render prop rather than as a child, so
- * `BottomSheet.Portal` lifts this element out of its own children, publishes it
- * on context, and `BottomSheet.Container` clones it into that slot with the
- * sheet's animated position attached. Writing it as a sibling of the container is
- * what makes the anatomy read like the thing it draws.
- *
- * Omit it and the sheet has no scrim at all — gorhom's own default for
- * `backdropComponent` is nothing.
- *
- * **gorhom's own press handling is deliberately turned off, and the press area
- * is rebuilt here.** Its backdrop puts a full-screen `Gesture.Tap()` behind the
- * sheet, and Gesture Handler resolves a touch between competing GESTURES: a
- * `Button` in the sheet has one of its own and wins, but a `TextInput` has none,
- * so the backdrop takes the tap and the sheet closes instead of the field
- * focusing. That is why gorhom ships its own `BottomSheetTextInput` — and taking
- * that route would mean this package's `Input`, with its variants, its
- * `Input.Group` and its `Field` cascade, could not be used in a sheet at all.
+ * `bg-overlay`, a token that carries its own alpha, so the `opacity` here is 1
+ * and the two theme variants can differ. The engine fades it with the sheet's
+ * index — never with the keyboard — and makes it a plain `Pressable` written
+ * before the panel, which is what lets a tap on a field inside the sheet reach
+ * the field.
  *
- * So the scrim keeps `pressBehavior="none"` — no gesture anywhere — and a
- * `Pressable` is laid over the region ABOVE the sheet, sized from the sheet's own
- * `animatedPosition`. It never overlaps the sheet, so there is nothing for it to
- * take, and pressing the part of the scrim anyone can actually see still closes.
- * The colour and the fade stay gorhom's, driven off the sheet's position on the
- * UI thread; the slot therefore carries no `opacity-*`, or a class and an
- * animated style would be two writers of one property.
+ * Omit it and the sheet has no scrim at all. `pressBehavior="none"` keeps it
+ * and makes it inert, for a sheet that must be answered.
  *
  * @example
  * <BottomSheet.Overlay />
  *
  * @example
- * // A scrim that does not close the sheet — a decision the caller has to make.
- * <BottomSheet.Overlay isCloseOnPress={false} />
+ * <BottomSheet.Overlay pressBehavior="none" />
  */
 export function BottomSheetOverlay({
-	accessibilityLabel = "Close",
-	animatedIndex,
-	animatedPosition,
 	appearsOnIndex = BOTTOM_SHEET_BACKDROP_INDICES.appearsOnIndex,
 	className,
 	disappearsOnIndex = BOTTOM_SHEET_BACKDROP_INDICES.disappearsOnIndex,
-	isCloseOnPress = true,
 	opacity = BOTTOM_SHEET_OVERLAY_OPACITY,
-	onPress,
 	...props
 }: BottomSheetOverlayProps): ReactElement {
-	if (animatedIndex === undefined || animatedPosition === undefined) {
-		throw new Error(
-			"BottomSheet.Overlay must be written inside a <BottomSheet.Portal>, beside its <BottomSheet.Container>."
-		);
-	}
-
 	return (
-		<>
-			<StyledBackdrop
-				animatedIndex={animatedIndex}
-				animatedPosition={animatedPosition}
-				appearsOnIndex={appearsOnIndex}
-				className={bottomSheetVariants().overlay({ className })}
-				disappearsOnIndex={disappearsOnIndex}
-				opacity={opacity}
-				pressBehavior="none"
-				{...props}
-			/>
-			{isCloseOnPress ? (
-				<BottomSheetOverlayPressArea
-					accessibilityLabel={accessibilityLabel}
-					animatedPosition={animatedPosition}
-					onPress={onPress}
-				/>
-			) : null}
-		</>
+		<StyledOverlay
+			appearsOnIndex={appearsOnIndex}
+			className={bottomSheetVariants().overlay({ className })}
+			disappearsOnIndex={disappearsOnIndex}
+			opacity={opacity}
+			{...props}
+		/>
 	);
 }
 BottomSheetOverlay.displayName = "DelacourUI.BottomSheet.Overlay";
-
-/**
- * The pressable band between the top of the screen and the top of the sheet.
- *
- * Its height is the sheet's own `animatedPosition`, so it grows and shrinks with
- * the sheet on the UI thread and stops exactly where the sheet begins — which is
- * the whole point. The `Pressable` is a child rather than the animated view
- * itself because `Pressable` takes no `style`: its own `Animated.View` already
- * owns one, and a second would fight it for prop ownership every frame.
- *
- * It reads gorhom's `useBottomSheet()` rather than this package's. The backdrop
- * is rendered by gorhom's own container, OUTSIDE the children
- * `BottomSheet.Container` re-publishes its context around, so the sheet's own
- * handle is the one thing in scope here — and closing through it lands on
- * `onDismiss`, which is where `onOpenChange` already is.
- */
-function BottomSheetOverlayPressArea({
-	accessibilityLabel,
-	animatedPosition,
-	onPress,
-}: {
-	accessibilityLabel: string;
-	animatedPosition: NonNullable<BottomSheetBackdropProps["animatedPosition"]>;
-	onPress?: () => void;
-}): ReactElement {
-	const { close } = useGorhomBottomSheet();
-
-	const style = useAnimatedStyle(() => ({ height: Math.max(0, animatedPosition.value) }));
-
-	const handlePress = () => {
-		onPress?.();
-		close();
-	};
-
-	return (
-		<Animated.View style={[styles.pressArea, style]}>
-			<Pressable
-				accessibilityLabel={accessibilityLabel}
-				accessibilityRole="button"
-				className="flex-1"
-				feedback="none"
-				onPress={handlePress}
-			/>
-		</Animated.View>
-	);
-}
-BottomSheetOverlayPressArea.displayName = "DelacourUI.BottomSheet.Overlay.PressArea";
-
-// A style rather than a class: the height beside it is an animated value, and the
-// two have to arrive on the same node.
-const styles = StyleSheet.create({
-	pressArea: { left: 0, position: "absolute", right: 0, top: 0 },
-});

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

@@ -0,0 +1,42 @@
+import {
+	BottomSheetProvider as HeadlessProvider,
+	type BottomSheetProviderProps as HeadlessProviderProps,
+} from "@delacour/react-native-bottom-sheet";
+import type { ReactElement } from "react";
+import { TeleportProvidedContext, useIsTeleportProvided } from "../overlay/overlay.context";
+
+export type BottomSheetProviderProps = Omit<HeadlessProviderProps, "hasPortalProvider">;
+
+/**
+ * The engine's provider, mounted once by the app — and aware of
+ * `OverlayProvider`.
+ *
+ * Both providers need teleport's `PortalProvider`, and there must be exactly
+ * one: teleport registers hosts natively by name, so two would mean two hosts
+ * called `"root"`. Whichever of the two mounts outermost mounts it and says so
+ * through `TeleportProvidedContext`; the inner one skips its own. Sheets and
+ * overlays then share one `"root"` host, ordered by `zIndex` — every overlay's
+ * band starts above every sheet's.
+ *
+ * The overlay folder's context file is a leaf (rule 3): it imports nothing but
+ * React, so this cross-folder import cannot close a cycle.
+ *
+ * @example
+ * <DelacourProvider>
+ *   <OverlayProvider>
+ *     <BottomSheetProvider>
+ *       <Stack />
+ *     </BottomSheetProvider>
+ *   </OverlayProvider>
+ * </DelacourProvider>
+ */
+export function BottomSheetProvider({ children }: BottomSheetProviderProps): ReactElement {
+	const isTeleportProvided = useIsTeleportProvided();
+
+	return (
+		<HeadlessProvider hasPortalProvider={isTeleportProvided}>
+			<TeleportProvidedContext.Provider value>{children}</TeleportProvidedContext.Provider>
+		</HeadlessProvider>
+	);
+}
+BottomSheetProvider.displayName = "DelacourUI.BottomSheet.Provider";