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

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

@@ -1,35 +1,44 @@
-import type { BottomSheetBackgroundProps as GorhomBottomSheetBackgroundProps } from "@gorhom/bottom-sheet";
+import {
+	BottomSheet as Headless,
+	type BottomSheetBackgroundProps as HeadlessProps,
+	useBottomSheetInternal,
+} from "@delacour/react-native-bottom-sheet";
 import type { ReactElement } from "react";
-import { View } from "react-native";
+import { withUniwind } from "uniwind";
 import { bottomSheetVariants } from "./bottom-sheet.variants";
 
-export type BottomSheetBackgroundProps = Partial<GorhomBottomSheetBackgroundProps> & {
+type StyledBackgroundComponent = (props: HeadlessProps & { className?: string }) => ReactElement | null;
+
+// Third-party to Uniwind, so `className` needs the wrapper — and it has to be
+// built at module scope or every render mints a new component type.
+const StyledBackground = withUniwind(Headless.Background) as unknown as StyledBackgroundComponent;
+
+export type BottomSheetBackgroundProps = HeadlessProps & {
 	className?: string;
 };
 
 /**
- * The sheet's own surface, drawn behind the handle and the content.
+ * The sheet's surface: the box behind the handle and the content.
  *
- * Supplied to gorhom as `backgroundComponent` rather than styled through
- * `backgroundStyle`, so the surface is a className like every other surface in
- * this package — and so `backgroundClassName` on `BottomSheet.Container` has
- * something to reach. A `backgroundStyle` a caller passes still arrives, merged
- * into the `style` below.
+ * `bg-popover`, top corners rounded — and every corner when the root is
+ * `detached`, because a floating card has a bottom edge on screen. The engine
+ * sizes it: an attached surface fills the panel and its bottom edge is always
+ * off-screen; a detached one is exactly the sheet's height, so the corners this
+ * rounds are the ones you see.
  *
- * **Forwarding `style` is load-bearing.** gorhom hands this component
- * `[StyleSheet.absoluteFill, backgroundStyle]`; drop it and the surface collapses
- * to nothing and the sheet renders transparent over the app.
+ * `Container` writes one for you unless you write it — see there.
  *
- * The two animated variables are destructured off rather than spread: they are
- * shared values, and a `View` has no use for either.
+ * @example
+ * <BottomSheet.Background className="bg-card" />
  */
-export function BottomSheetBackground({
-	animatedIndex: _animatedIndex,
-	animatedPosition: _animatedPosition,
-	className,
-	style,
-	...props
-}: BottomSheetBackgroundProps): ReactElement {
-	return <View className={bottomSheetVariants().background({ className })} style={style} {...props} />;
+export function BottomSheetBackground({ className, ...props }: BottomSheetBackgroundProps): ReactElement {
+	const { detached } = useBottomSheetInternal();
+
+	return (
+		<StyledBackground
+			className={bottomSheetVariants({ detached: detached !== null }).background({ className })}
+			{...props}
+		/>
+	);
 }
 BottomSheetBackground.displayName = "DelacourUI.BottomSheet.Background";

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

@@ -1,8 +1,8 @@
-import { type ReactElement, useCallback } from "react";
+import { BottomSheet as Headless } from "@delacour/react-native-bottom-sheet";
+import type { ReactElement } from "react";
 import { IconCrossSmall } from "../../icons/central";
 import { Icon } from "../icon";
 import { Pressable, type PressableProps } from "../pressable";
-import { useBottomSheetPart } from "./bottom-sheet.context";
 import { BOTTOM_SHEET_CLOSE_HIT_SLOP, bottomSheetVariants } from "./bottom-sheet.variants";
 
 export type BottomSheetCloseProps = Omit<PressableProps, "asChild" | "busy" | "children" | "disabled">;
@@ -10,17 +10,17 @@ export type BottomSheetCloseProps = Omit<PressableProps, "asChild" | "busy" | "c
 /**
  * The sheet's dismiss control.
  *
- * Positioned out of the content's flow, in the top-right of the sheet, so it does
- * not push the title down or take a row of its own. `BottomSheet.Title` reserves
- * the clearance for it on every sheet — see `bottomSheetVariants`.
+ * The engine's `Close asChild` around this library's `Pressable`, so the press
+ * is the library's — `fade` rather than a spring, because a scale on a glyph
+ * this small reads as a jitter, the reason `Badge.CloseButton` presses the same
+ * way — and the close is the engine's: the same path a swipe-down and a scrim
+ * press take, so a caller has one `onOpenChange` to watch rather than three.
  *
- * Closing goes through the same `onOpenChange` a swipe-down and a backdrop press
- * do, so a caller has one callback to watch rather than three.
- *
- * `fade` rather than a spring: a scale on a glyph this small reads as a jitter,
- * the reason `Badge.CloseButton` presses the same way. The slop is there because
- * a bare glyph in a corner has no padded capsule to bring it up to the 44pt
- * minimum — the case `Checkbox` mints slop for.
+ * Positioned out of the content's flow, in the top-right of the sheet, so it
+ * does not push the title down or take a row of its own. `BottomSheet.Title`
+ * reserves the clearance for it on every sheet — see `bottomSheetVariants`.
+ * The slop is there because a bare glyph in a corner has no padded capsule to
+ * bring it up to the 44pt minimum — the case `Checkbox` mints slop for.
  *
  * @example
  * <BottomSheet.Content>
@@ -36,25 +36,18 @@ export function BottomSheetClose({
 	onPress,
 	...props
 }: BottomSheetCloseProps): ReactElement {
-	const { close } = useBottomSheetPart("BottomSheet.Close");
-
-	const handlePress = useCallback(() => {
-		close();
-		onPress?.();
-	}, [close, onPress]);
-
 	return (
-		<Pressable
-			accessibilityLabel={accessibilityLabel}
-			accessibilityRole="button"
-			className={bottomSheetVariants().close({ className })}
-			feedback={feedback}
-			hitSlop={hitSlop}
-			onPress={handlePress}
-			{...props}
-		>
-			<Icon color="muted-foreground" icon={IconCrossSmall} />
-		</Pressable>
+		<Headless.Close accessibilityLabel={accessibilityLabel} asChild onPress={onPress}>
+			<Pressable
+				accessibilityRole="button"
+				className={bottomSheetVariants().close({ className })}
+				feedback={feedback}
+				hitSlop={hitSlop}
+				{...props}
+			>
+				<Icon color="muted-foreground" icon={IconCrossSmall} />
+			</Pressable>
+		</Headless.Close>
 	);
 }
 BottomSheetClose.displayName = "DelacourUI.BottomSheet.Close";

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

@@ -1,45 +1,27 @@
 import {
-	type BottomSheetBackdropProps,
-	BottomSheetModal,
-	type BottomSheetModalProps,
-	type BottomSheetBackgroundProps as GorhomBottomSheetBackgroundProps,
-	type BottomSheetFooterProps as GorhomBottomSheetFooterProps,
-	type BottomSheetHandleProps as GorhomBottomSheetHandleProps,
-} from "@gorhom/bottom-sheet";
-import {
-	Children,
-	cloneElement,
-	isValidElement,
-	type ReactElement,
-	type ReactNode,
-	useCallback,
-	useEffect,
-	useMemo,
-	useRef,
-} from "react";
-import { useSharedValue } from "react-native-reanimated";
-import { useKeyboardAnimationGuard } from "../../hooks/use-keyboard-state-sync";
-import {
-	BottomSheetContainerProvider,
-	BottomSheetProvider,
-	useBottomSheetPart,
-	useBottomSheetPortalContext,
-} from "./bottom-sheet.context";
-import {
-	BOTTOM_SHEET_KEYBOARD_DEFAULTS,
-	type BottomSheetFooterFlag,
-	type BottomSheetFooterPlacement,
-	resolveFooterPlacement,
-} from "./bottom-sheet.variants";
+	BottomSheet as Headless,
+	type BottomSheetContainerProps as HeadlessProps,
+} from "@delacour/react-native-bottom-sheet";
+import { Children, isValidElement, type ReactElement, type ReactNode } from "react";
+import { withUniwind } from "uniwind";
+import { cn } from "../../lib/cn";
 import { BottomSheetBackground } from "./bottom-sheet-background";
-import { BottomSheetFooter, type BottomSheetFooterProps } from "./bottom-sheet-footer";
 import { BottomSheetHandle } from "./bottom-sheet-handle";
 
-export type BottomSheetContainerProps = Omit<
-	BottomSheetModalProps,
-	"backdropComponent" | "backgroundComponent" | "children" | "footerComponent" | "handleComponent" | "onDismiss" | "ref"
-> & {
-	children?: ReactNode;
+/**
+ * The engine's panel, taught `className`.
+ *
+ * `withUniwind`'s return type maps over a component's props and loses the
+ * shape of anything animated, so the signature is restated. Built at module
+ * scope: in render it would mint a new component type every pass and remount
+ * the whole sheet.
+ */
+type StyledContainerComponent = (props: HeadlessProps & { className?: string }) => ReactElement | null;
+
+const StyledContainer = withUniwind(Headless.Container) as unknown as StyledContainerComponent;
+
+export type BottomSheetContainerProps = HeadlessProps & {
+	className?: string;
 	/** Classes for the sheet's surface — the box behind the handle and the content. */
 	backgroundClassName?: string;
 	/** Classes for the row the grabber sits in. */
@@ -48,43 +30,29 @@ export type BottomSheetContainerProps = Omit<
 	handleIndicatorClassName?: string;
 };
 
+/** Whether any direct child is one of the two parts the container would otherwise write itself. */
+function hasSurfaceParts(children: ReactNode): boolean {
+	return Children.toArray(children).some(
+		(child) => isValidElement(child) && (child.type === BottomSheetBackground || child.type === BottomSheetHandle)
+	);
+}
+
 /**
- * The sheet itself: the surface that slides up, and everything inside it.
- *
- * Every gorhom prop passes through, so snap points, dynamic sizing, the pan
- * gestures and the animation configs are all reachable. Four are not, because
- * this component supplies them: the backdrop and the footer are cloned from the
- * parts a caller wrote, and the background and the handle are rendered as views
- * of this package's own so they can take a `className` rather than a style.
- *
- * **It takes no `className`.** gorhom's modal wears an animated style that the
- * sheet's own position writes to every frame, so there is nothing here for a
- * class to reach that `backgroundClassName` does not already reach better. The
- * same trade `Screen.Footer` makes — that file takes a `style` and never a
- * `className`, and so wraps nothing in `withUniwind`.
+ * The panel — the surface that moves.
  *
- * **Presenting is driven by state, never by the ref.** `isOpen` on the root is
- * the one source, so a swipe-down, a backdrop press, `BottomSheet.Close` and a
- * programmatic close all arrive at the same `onOpenChange`. gorhom's own
- * `onDismiss` is therefore not forwarded: two callbacks for one event is two
- * things that can disagree. `useBottomSheet().sheetRef` is still there for the
- * imperative calls with no declarative form — `snapToIndex`, `expand`.
+ * The engine positions it, sizes it to the frame and translates it by the
+ * sheet's geometry; this adds classes and the two parts every sheet has.
  *
- * **`accessible` defaults to `false`, and that is not a small thing.** gorhom
- * marks the sheet's content container `accessible` with the label "Bottom
- * Sheet" and the `adjustable` role. On iOS an `accessible` container collapses
- * its whole subtree into ONE element, so every field, button and line of copy in
- * the sheet becomes unreachable to VoiceOver — a form in a sheet cannot be
- * filled in at all. This is `Field`'s rule one component along: the row is
- * `accessible={false}` so the control stays the element a screen reader sees.
- * Pass `accessible` to opt back into gorhom's behaviour for a sheet whose body
- * really is one adjustable thing.
+ * **It writes `Background` and `Handle` for you** when the children hold
+ * neither, so the common sheet is `Container > Content` and nothing else. Write
+ * either one yourself and it writes nothing — a container with a custom handle
+ * and no surface is a decision, not an omission. The three `*ClassName` props
+ * reach the parts it writes; a part you write takes its own `className`.
  *
- * Three defaults differ from gorhom's. `enablePanDownToClose` is on, because a
- * modal sheet has no collapsed resting state to pan down to. And the keyboard
- * trio comes from `BOTTOM_SHEET_KEYBOARD_DEFAULTS` — see that const for why
- * Android must not be left on `adjustPan`. Both are ordinary props, so either
- * can be turned back off.
+ * **Sizing and behaviour live on the root, not here.** `snapPoints`,
+ * `dynamicSizing`, `maxDynamicContentSize`, `keyboardBehavior` and the rest
+ * are `BottomSheet`'s props: the engine resolves them once for every part, and
+ * a panel that carried them would be a second place to look.
  *
  * @example
  * <BottomSheet.Container>
@@ -92,155 +60,33 @@ export type BottomSheetContainerProps = Omit<
  * </BottomSheet.Container>
  *
  * @example
- * // A scrollable sheet needs a fixed height to scroll within.
- * <BottomSheet.Container enableDynamicSizing={false} snapPoints={["50%", "90%"]}>
- *   <BottomSheet.ScrollView>{rows}</BottomSheet.ScrollView>
- *   <BottomSheet.Footer sticky>{actions}</BottomSheet.Footer>
+ * // A custom grabber; the surface still comes with it.
+ * <BottomSheet.Container backgroundClassName="bg-card">
+ *   <BottomSheet.Background className="bg-card" />
+ *   <BottomSheet.Handle><MyGrabber /></BottomSheet.Handle>
+ *   <BottomSheet.Content>{…}</BottomSheet.Content>
  * </BottomSheet.Container>
  */
 export function BottomSheetContainer({
-	accessible = false,
 	backgroundClassName,
 	children,
-	enablePanDownToClose = true,
+	className,
 	handleClassName,
 	handleIndicatorClassName,
 	...props
 }: BottomSheetContainerProps): ReactElement {
-	const sheet = useBottomSheetPart("BottomSheet.Container");
-	const { isOpen, setOpen, sheetRef } = sheet;
-	const portal = useBottomSheetPortalContext();
-	// A sheet that opens while `KeyboardProvider`'s shared values are pinned open
-	// by a keyboard that vanished without a `will` event would size itself for a
-	// keyboard that is not there. `Screen.Footer` runs the same repair on mount.
-	useKeyboardAnimationGuard();
-
-	// Whether this sheet has ever been presented. A JS ref rather than state:
-	// nothing renders differently for it, and it has to be readable inside the
-	// effect that sets it.
-	const hasPresentedRef = useRef(false);
-
-	const { content, footer, placement } = useMemo(() => hoistFooter(children), [children]);
-	const hasStickyFooter = placement === "sticky";
-	const overlay = portal?.overlay ?? null;
-
-	// Written by the pinned footer's own onLayout, read by the body — the
-	// content's spacer, or the scroll view's margin. It lives here because the two
-	// are siblings in gorhom's tree and neither can see the other — the footer is
-	// rendered outside the children this file wraps.
-	const footerHeight = useSharedValue(0);
-
-	const containerValue = useMemo(() => ({ footerHeight, hasStickyFooter }), [footerHeight, hasStickyFooter]);
-
-	const backdropComponent = useMemo(
-		() =>
-			overlay === null ? undefined : (backdropProps: BottomSheetBackdropProps) => cloneElement(overlay, backdropProps),
-		[overlay]
+	const surface = hasSurfaceParts(children) ? null : (
+		<>
+			<BottomSheetBackground className={backgroundClassName} />
+			<BottomSheetHandle className={handleClassName} indicatorClassName={handleIndicatorClassName} />
+		</>
 	);
 
-	const footerComponent = useMemo(
-		() =>
-			footer === null
-				? undefined
-				: (footerProps: GorhomBottomSheetFooterProps) => cloneElement(footer, { ...footerProps, footerHeight }),
-		[footer, footerHeight]
-	);
-
-	const backgroundComponent = useCallback(
-		(backgroundProps: GorhomBottomSheetBackgroundProps) => (
-			<BottomSheetBackground {...backgroundProps} className={backgroundClassName} />
-		),
-		[backgroundClassName]
-	);
-
-	const handleComponent = useCallback(
-		(handleProps: GorhomBottomSheetHandleProps) => (
-			<BottomSheetHandle {...handleProps} className={handleClassName} indicatorClassName={handleIndicatorClassName} />
-		),
-		[handleClassName, handleIndicatorClassName]
-	);
-
-	const handleDismiss = useCallback(() => {
-		hasPresentedRef.current = false;
-		setOpen(false);
-	}, [setOpen]);
-
-	useEffect(() => {
-		if (isOpen) {
-			hasPresentedRef.current = true;
-			sheetRef.current?.present();
-			return;
-		}
-
-		// Dismissing a modal that was never presented is NOT a no-op, and this is
-		// the sharpest edge in the component. gorhom's modal starts at status
-		// `INITIAL`; `dismiss()` reads that as a live sheet being closed and moves
-		// it to `DISMISSING`, where it stays. The next `present()` then mounts the
-		// portal and renders the sheet — and it never animates in, never lays out
-		// its content, and never fires `onChange`. Nothing is logged, nothing
-		// throws, and the screen simply does not change.
-		if (!hasPresentedRef.current) return;
-		hasPresentedRef.current = false;
-		sheetRef.current?.dismiss();
-	}, [isOpen, sheetRef]);
-
 	return (
-		<BottomSheetModal
-			accessible={accessible}
-			backdropComponent={backdropComponent}
-			backgroundComponent={backgroundComponent}
-			enablePanDownToClose={enablePanDownToClose}
-			footerComponent={footerComponent}
-			handleComponent={handleComponent}
-			onDismiss={handleDismiss}
-			ref={sheetRef}
-			{...BOTTOM_SHEET_KEYBOARD_DEFAULTS}
-			{...props}
-		>
-			<BottomSheetProvider value={sheet}>
-				<BottomSheetContainerProvider value={containerValue}>{content}</BottomSheetContainerProvider>
-			</BottomSheetProvider>
-		</BottomSheetModal>
+		<StyledContainer className={cn(className)} {...props}>
+			{surface}
+			{children}
+		</StyledContainer>
 	);
 }
 BottomSheetContainer.displayName = "DelacourUI.BottomSheet.Container";
-
-/**
- * Splits a container's children into the body and a footer to be pinned.
- *
- * gorhom takes a footer as a `footerComponent` render prop rather than as a
- * child, so a sticky one has to leave the tree it was written in; an inline one
- * stays put and is simply part of the body. {@link resolveFooterPlacement} is the
- * decision and is pure, so `bun test` reaches the whole matrix — this walk only
- * turns children into the flags it reads.
- *
- * Lives here rather than with the parts: it is the container that lifts its own
- * children, and importing it from `bottom-sheet-footer.tsx` would close a cycle.
- * See AGENTS.md.
- */
-function hoistFooter(children: ReactNode): {
-	content: ReactNode;
-	footer: ReactElement<BottomSheetFooterProps> | null;
-	placement: BottomSheetFooterPlacement;
-} {
-	const items = Children.toArray(children);
-	const flags: BottomSheetFooterFlag[] = [];
-	let footer: ReactElement<BottomSheetFooterProps> | null = null;
-
-	for (const child of items) {
-		if (!isValidElement(child) || child.type !== BottomSheetFooter) {
-			flags.push({ isFooter: false, isSticky: false });
-			continue;
-		}
-
-		const element = child as ReactElement<BottomSheetFooterProps>;
-		const isSticky = element.props.sticky === true;
-		flags.push({ isFooter: true, isSticky });
-		if (isSticky) footer ??= element;
-	}
-
-	const placement = resolveFooterPlacement(flags);
-	if (placement !== "sticky" || footer === null) return { content: items, footer: null, placement };
-
-	return { content: items.filter((child) => child !== footer), footer, placement };
-}

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

@@ -1,12 +1,18 @@
-import { BottomSheetView } from "@gorhom/bottom-sheet";
+import {
+	BottomSheet as Headless,
+	type BottomSheetContentProps as HeadlessProps,
+} from "@delacour/react-native-bottom-sheet";
 import type { ReactElement } from "react";
-import { View, type ViewProps } from "react-native";
-import Animated, { useAnimatedStyle } from "react-native-reanimated";
-import { useSafeAreaInsets } from "react-native-safe-area-context";
-import { useBottomSheetContainerContext } from "./bottom-sheet.context";
-import { BOTTOM_SHEET_FOOTER_GAP, bottomSheetVariants, resolveSheetBottomInset } from "./bottom-sheet.variants";
+import { withUniwind } from "uniwind";
+import { BOTTOM_SHEET_FOOTER_GAP, bottomSheetVariants } from "./bottom-sheet.variants";
 
-export type BottomSheetContentProps = ViewProps & {
+type StyledContentComponent = (props: HeadlessProps & { className?: string }) => ReactElement | null;
+
+// Built once at module scope; the classes land on the engine's inner, measured
+// view, which is the one that takes `style`.
+const StyledContent = withUniwind(Headless.Content) as unknown as StyledContentComponent;
+
+export type BottomSheetContentProps = HeadlessProps & {
 	className?: string;
 };
 
@@ -14,28 +20,12 @@ export type BottomSheetContentProps = ViewProps & {
  * The sheet's body — what a caller writes the title, the copy and the controls
  * into.
  *
- * Two boxes, and neither is a `withUniwind` wrapper. gorhom's `BottomSheetView`
- * is the outer one: it measures itself into the sheet's layout state, which is
- * what makes `enableDynamicSizing` size the sheet to whatever is inside. The
- * inner `View` is an ordinary React Native one and carries every class, so this
- * file wraps nothing — the same move `Screen.Footer` makes with
- * `KeyboardStickyView`.
- *
- * **A pinned footer is reserved by a spacer, not by gorhom's
- * `enableFooterMarginAdjustment`.** That prop turns the footer's measured height
- * into content-container padding through React state — a commit on every frame
- * of the keyboard animation, because the footer changes height as it gives up
- * its safe-area band. A spacer whose height is an animated style off the same
- * shared value costs nothing on the JS thread, and `Screen` already reserves its
- * own chrome exactly this way. The spacer sits OUTSIDE the classed box so the
- * content's own `gap` does not land in front of it and quietly double the
- * {@link BOTTOM_SHEET_FOOTER_GAP} the footer is held off by.
- *
- * **The safe-area band goes on the OUTER box, and only when nothing else is
- * paying for it** — a pinned footer's own box carries it, so
- * {@link resolveSheetBottomInset} withholds it here. The band comes from
- * `useSafeAreaInsets()` and never from `pb-safe`, which compiles to
- * `env(safe-area-inset-bottom)` and resolves to zero on React Native.
+ * The engine's `Content` with the library's gutter and gap on its measured
+ * box. Everything the old body had to do by hand is the engine's now: the
+ * body is clamped to the space the handle, a sticky footer, the keyboard and
+ * the safe-area band leave; a spacer the footer's height plus `footerGap`
+ * keeps the last line above a pinned footer; and the band under it is
+ * reserved by the geometry rather than padded here.
  *
  * @example
  * <BottomSheet.Content>
@@ -43,24 +33,11 @@ export type BottomSheetContentProps = ViewProps & {
  *   <BottomSheet.Description>This cannot be undone.</BottomSheet.Description>
  * </BottomSheet.Content>
  */
-export function BottomSheetContent({ className, children, style, ...props }: BottomSheetContentProps): ReactElement {
-	const container = useBottomSheetContainerContext();
-	const { bottom } = useSafeAreaInsets();
-	const hasStickyFooter = container?.hasStickyFooter ?? false;
-	const footerHeight = container?.footerHeight;
-	const paddingBottom = resolveSheetBottomInset({ bottom, hasStickyFooter });
-
-	const reserve = useAnimatedStyle(() => ({
-		height: footerHeight === undefined ? 0 : footerHeight.value + BOTTOM_SHEET_FOOTER_GAP,
-	}));
-
-	return (
-		<BottomSheetView style={{ paddingBottom }}>
-			<View className={bottomSheetVariants().content({ className })} style={style} {...props}>
-				{children}
-			</View>
-			{hasStickyFooter ? <Animated.View style={reserve} /> : null}
-		</BottomSheetView>
-	);
+export function BottomSheetContent({
+	className,
+	footerGap = BOTTOM_SHEET_FOOTER_GAP,
+	...props
+}: BottomSheetContentProps): ReactElement {
+	return <StyledContent className={bottomSheetVariants().content({ className })} footerGap={footerGap} {...props} />;
 }
 BottomSheetContent.displayName = "DelacourUI.BottomSheet.Content";

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

@@ -1,3 +1,4 @@
+import { BottomSheet as Headless } from "@delacour/react-native-bottom-sheet";
 import type { ReactElement } from "react";
 import { cn } from "../../lib/cn";
 import { Text, type TextPresetProps } from "../text";
@@ -10,7 +11,8 @@ export type BottomSheetDescriptionProps = TextPresetProps;
  * *Is* a `Text.Paragraph`, defaulting to the muted token — the title is what the
  * sheet is about and this is what it means, so the two need to read as a
  * hierarchy rather than as two equal lines. `color` is an ordinary prop, so a
- * description that needs the page colour asks for it.
+ * description that needs the page colour asks for it. The engine's
+ * `Description asChild` gives it the `nativeID` a skin can describe the panel by.
  *
  * It has no slot in `bottomSheetVariants`, and that is deliberate: it carries no
  * layout of its own, and `tv` emits `undefined` for an empty class string, so a
@@ -24,6 +26,10 @@ export function BottomSheetDescription({
 	color = "muted",
 	...props
 }: BottomSheetDescriptionProps): ReactElement {
-	return <Text.Paragraph className={cn(className)} color={color} {...props} />;
+	return (
+		<Headless.Description asChild>
+			<Text.Paragraph className={cn(className)} color={color} {...props} />
+		</Headless.Description>
+	);
 }
 BottomSheetDescription.displayName = "DelacourUI.BottomSheet.Description";

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

@@ -0,0 +1,65 @@
+import {
+	BottomSheet as Headless,
+	type BottomSheetFlatListProps as HeadlessProps,
+	useBottomSheetInternal,
+} from "@delacour/react-native-bottom-sheet";
+import type { ReactElement, Ref } from "react";
+import type { FlatList } from "react-native";
+import { withUniwind } from "uniwind";
+import { cn } from "../../lib/cn";
+import { BOTTOM_SHEET_FOOTER_GAP, bottomSheetVariants } from "./bottom-sheet.variants";
+
+/**
+ * The class props `withUniwind` adds, restated so the generic survives.
+ *
+ * `withUniwind`'s own return type maps over a component's props and collapses
+ * `<ItemT>` in the process, which would leave `data` and `renderItem` checking
+ * against `unknown`. Writing the signature out keeps inference and still
+ * declares exactly the two props the wrapper adds — the same move
+ * `Screen.LegendList` makes.
+ */
+type StyledFlatListComponent = <ItemT>(
+	props: HeadlessProps<ItemT> & { ref?: Ref<FlatList<ItemT>>; className?: string; contentContainerClassName?: string }
+) => ReactElement | null;
+
+// Built at module scope, or every render mints a new component type and
+// remounts the list.
+const StyledFlatList = withUniwind(Headless.FlatList) as unknown as StyledFlatListComponent;
+
+export type BottomSheetFlatListProps<ItemT> = HeadlessProps<ItemT> & {
+	ref?: Ref<FlatList<ItemT>>;
+	className?: string;
+	/** Classes for the content container. Same gutter and gap as `Content`. */
+	contentContainerClassName?: string;
+};
+
+/**
+ * A virtualised body.
+ *
+ * The engine's `FlatList` — the scroll lock, the drag budget and content size
+ * as the dynamic snap point are all its — with the library's gutter on the content
+ * container. A virtualised list has no inner box to put the classes on, so
+ * here they go on `contentContainerClassName`; the engine flattens the
+ * resulting style to one object before the list measures it.
+ *
+ * @example
+ * <BottomSheet.FlatList data={rows} keyExtractor={(row) => row.id} renderItem={renderRow} />
+ */
+export function BottomSheetFlatList<ItemT>({
+	className,
+	contentContainerClassName,
+	contentContainerStyle,
+	...props
+}: BottomSheetFlatListProps<ItemT>): ReactElement {
+	const { hasFooter } = useBottomSheetInternal();
+
+	return (
+		<StyledFlatList
+			className={cn(className)}
+			contentContainerClassName={bottomSheetVariants().scrollContent({ className: contentContainerClassName })}
+			contentContainerStyle={[{ paddingBottom: hasFooter ? BOTTOM_SHEET_FOOTER_GAP : 0 }, contentContainerStyle]}
+			{...props}
+		/>
+	);
+}
+BottomSheetFlatList.displayName = "DelacourUI.BottomSheet.FlatList";