@delacour/react-native-ui 0.1.0-alpha.3

package/src/components/badge/badge.variants.ts

@@ -0,0 +1,238 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+
+/** How the surface is painted. Orthogonal to {@link BADGE_COLORS}. */
+export const BADGE_VARIANTS = ["solid", "soft", "outline", "ghost"] as const;
+
+/** What the surface means. Orthogonal to {@link BADGE_VARIANTS}. */
+export const BADGE_COLORS = ["default", "primary", "success", "warning", "destructive", "info"] as const;
+
+export const BADGE_SIZES = ["sm", "md", "lg"] as const;
+
+export type BadgeVariant = (typeof BADGE_VARIANTS)[number];
+export type BadgeColor = (typeof BADGE_COLORS)[number];
+export type BadgeSize = (typeof BADGE_SIZES)[number];
+
+/**
+ * Theme token whose value gives an `Icon` composed into the badge its colour.
+ *
+ * The badge's counterpart to `BUTTON_FOREGROUND_TOKEN`, and it exists for the
+ * same reason: a colour that has to reach an SVG paint prop cannot be a class.
+ * Every entry names the token its own `label` slot resolves to, so a glyph and
+ * the text beside it are always the same shade — a test asserts the pair.
+ *
+ * Nested rather than flattened to twenty-four keys so adding a colour is a
+ * compile error in four places instead of a silent gap in one.
+ */
+export const BADGE_FOREGROUND_TOKEN: Record<BadgeVariant, Record<BadgeColor, string>> = {
+	solid: {
+		default: "secondary-foreground",
+		primary: "primary-foreground",
+		success: "success-foreground",
+		warning: "warning-foreground",
+		destructive: "destructive-foreground",
+		info: "info-foreground",
+	},
+	soft: {
+		default: "muted-foreground",
+		primary: "tertiary-foreground",
+		success: "success-soft-foreground",
+		warning: "warning-soft-foreground",
+		destructive: "destructive-soft-foreground",
+		info: "info-soft-foreground",
+	},
+	outline: {
+		default: "muted-foreground",
+		primary: "foreground",
+		success: "success-soft-foreground",
+		warning: "warning-soft-foreground",
+		destructive: "destructive-soft-foreground",
+		info: "info-soft-foreground",
+	},
+	ghost: {
+		default: "muted-foreground",
+		primary: "foreground",
+		success: "success-soft-foreground",
+		warning: "warning-soft-foreground",
+		destructive: "destructive-soft-foreground",
+		info: "info-soft-foreground",
+	},
+};
+
+/**
+ * Styling for every part of a badge.
+ *
+ * Two axes rather than one. `variant` says how the surface is painted and
+ * `color` says what it means, so a caller reaches `soft` + `warning` without the
+ * library having to enumerate a `warning-soft` name for it — the combinatorial
+ * growth `Button`'s single axis would pay here, where six semantic colours are
+ * the point of the component rather than an afterthought. Neither axis carries a
+ * surface on its own, so the twenty-four real pairings live in
+ * `compoundVariants`.
+ *
+ * `self-start` is load-bearing. A badge is sized by its content, and inside a
+ * gap column every child is stretch-aligned by default — without it, a one-word
+ * badge spans the whole screen.
+ *
+ * `border border-transparent` sits in the base rather than on `outline` alone.
+ * A border declared only where it is visible makes the badge two points wider
+ * the moment a caller switches variant; reserving it in the box means `outline`
+ * changes nothing but the colour.
+ *
+ * `overflow-hidden` is likewise not tidiness — a pressed badge fades to the
+ * edge of its own capsule.
+ *
+ * A size is padding and never a height. `Text` respects OS font scaling, so a
+ * fixed height clips the label at a large accessibility step instead of growing
+ * with it, and unlike `h-button-*` a badge lines up against no chrome that would
+ * force the number. The icon step indexes the shared `--spacing-icon-*` scale so
+ * a glyph in a badge matches every other glyph in the library.
+ *
+ * The neutral end of the matrix reuses tokens the theme already has instead of
+ * minting `--primary-soft`: this theme's `primary` is a near-black, whose
+ * tint *is* the neutral fill, so a new token would duplicate `secondary` exactly.
+ * `soft` takes `tertiary` for `primary` and `muted` for `default` — two fills the
+ * theme already tunes per mode — which keeps all twenty-four cells distinct.
+ *
+ * The root holds no `text-*` utility: a React Native `View` does not cascade
+ * colour to a `Text` descendant, so label colour lives on the `label` slot and
+ * icon colour is resolved from {@link BADGE_FOREGROUND_TOKEN}.
+ *
+ * Free of React Native imports so it stays unit-testable — `bun test` cannot
+ * parse React Native's Flow-typed source. See AGENTS.md.
+ */
+export const badgeVariants = tv({
+	slots: {
+		root: "flex-row items-center justify-center self-start overflow-hidden rounded-full border border-transparent",
+		label: "text-center font-medium",
+		startContent: "items-center justify-center",
+		endContent: "items-center justify-center",
+		closeButton: "items-center justify-center rounded-full",
+		/** Edge length an `Icon` composed into the badge inherits. */
+		icon: "",
+	},
+	variants: {
+		// Neither axis paints a surface alone — see `compoundVariants`. What
+		// each variant does carry is whether the box has a fill at all.
+		variant: {
+			solid: {},
+			soft: {},
+			outline: { root: "bg-transparent" },
+			ghost: { root: "bg-transparent" },
+		},
+		color: {
+			default: {},
+			primary: {},
+			success: {},
+			warning: {},
+			destructive: {},
+			info: {},
+		},
+		size: {
+			sm: {
+				root: "gap-1 px-2 py-0.5",
+				label: "text-xs",
+				closeButton: "-mr-0.5",
+				icon: "size-icon-xs",
+			},
+			md: {
+				root: "gap-1.5 px-2.5 py-1",
+				label: "text-sm",
+				closeButton: "-mr-1",
+				icon: "size-icon-sm",
+			},
+			lg: {
+				root: "gap-2 px-3 py-1.5",
+				label: "text-base",
+				closeButton: "-mr-1.5",
+				icon: "size-icon-md",
+			},
+		},
+		// The empty `false` branch is load-bearing typing, not a placeholder.
+		// See the note in button.variants.ts.
+		isDisabled: { true: { root: "opacity-50" }, false: {} },
+	},
+	compoundVariants: [
+		{ variant: "solid", color: "default", class: { root: "bg-secondary", label: "text-secondary-foreground" } },
+		{ variant: "solid", color: "primary", class: { root: "bg-primary", label: "text-primary-foreground" } },
+		{ variant: "solid", color: "success", class: { root: "bg-success", label: "text-success-foreground" } },
+		{ variant: "solid", color: "warning", class: { root: "bg-warning", label: "text-warning-foreground" } },
+		{ variant: "solid", color: "destructive", class: { root: "bg-destructive", label: "text-destructive-foreground" } },
+		{ variant: "solid", color: "info", class: { root: "bg-info", label: "text-info-foreground" } },
+
+		{ variant: "soft", color: "default", class: { root: "bg-muted", label: "text-muted-foreground" } },
+		{ variant: "soft", color: "primary", class: { root: "bg-tertiary", label: "text-tertiary-foreground" } },
+		{
+			variant: "soft",
+			color: "success",
+			class: { root: "bg-success-soft", label: "text-success-soft-foreground" },
+		},
+		{
+			variant: "soft",
+			color: "warning",
+			class: { root: "bg-warning-soft", label: "text-warning-soft-foreground" },
+		},
+		{
+			variant: "soft",
+			color: "destructive",
+			class: { root: "bg-destructive-soft", label: "text-destructive-soft-foreground" },
+		},
+		{ variant: "soft", color: "info", class: { root: "bg-info-soft", label: "text-info-soft-foreground" } },
+
+		{ variant: "outline", color: "default", class: { root: "border-border", label: "text-muted-foreground" } },
+		{ variant: "outline", color: "primary", class: { root: "border-primary", label: "text-foreground" } },
+		{
+			variant: "outline",
+			color: "success",
+			class: { root: "border-success", label: "text-success-soft-foreground" },
+		},
+		{
+			variant: "outline",
+			color: "warning",
+			class: { root: "border-warning", label: "text-warning-soft-foreground" },
+		},
+		{
+			variant: "outline",
+			color: "destructive",
+			class: { root: "border-destructive", label: "text-destructive-soft-foreground" },
+		},
+		{ variant: "outline", color: "info", class: { root: "border-info", label: "text-info-soft-foreground" } },
+
+		{ variant: "ghost", color: "default", class: { label: "text-muted-foreground" } },
+		{ variant: "ghost", color: "primary", class: { label: "text-foreground" } },
+		{ variant: "ghost", color: "success", class: { label: "text-success-soft-foreground" } },
+		{ variant: "ghost", color: "warning", class: { label: "text-warning-soft-foreground" } },
+		{ variant: "ghost", color: "destructive", class: { label: "text-destructive-soft-foreground" } },
+		{ variant: "ghost", color: "info", class: { label: "text-info-soft-foreground" } },
+	],
+	defaultVariants: {
+		variant: "solid",
+		color: "default",
+		size: "md",
+		isDisabled: false,
+	},
+});
+
+/**
+ * Whether the root should render as a `Pressable` rather than a plain `View`.
+ *
+ * A badge is content until a caller gives it something to do. Mounting a
+ * `GestureDetector` regardless would put one under every tag in a list of fifty
+ * and announce each of them to assistive technology as a button with no action.
+ *
+ * `onClose` is deliberately not read here: the dismiss control is its own
+ * pressable, so a badge that can only be dismissed still has an inert root.
+ *
+ * Pure, so the matrix is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveBadgeInteractive({
+	onPress,
+	onLongPress,
+}: {
+	onPress?: () => void;
+	onLongPress?: () => void;
+}): boolean {
+	return onPress !== undefined || onLongPress !== undefined;
+}
+
+export type BadgeVariantProps = VariantProps<typeof badgeVariants>;

package/src/components/badge/index.ts

@@ -0,0 +1,17 @@
+export { Badge, type BadgeProps } from "./badge";
+export { type BadgeContextValue, BadgeProvider, useBadge, useBadgeContext } from "./badge.context";
+export type { BadgeSlotProps } from "./badge.types";
+export {
+	BADGE_COLORS,
+	BADGE_FOREGROUND_TOKEN,
+	BADGE_SIZES,
+	BADGE_VARIANTS,
+	type BadgeColor,
+	type BadgeSize,
+	type BadgeVariant,
+	type BadgeVariantProps,
+	badgeVariants,
+	resolveBadgeInteractive,
+} from "./badge.variants";
+export type { BadgeCloseButtonProps } from "./badge-close-button";
+export type { BadgeLabelProps } from "./badge-label";

package/src/components/bottom-sheet/AGENTS.md

@@ -0,0 +1,232 @@
+# BottomSheet
+
+A panel that slides up over everything, on `@gorhom/bottom-sheet`'s modal. The
+library's first overlay. Compound root plus `BottomSheet.Trigger`,
+`BottomSheet.Portal`, `BottomSheet.Overlay`, `BottomSheet.Container`,
+`BottomSheet.Content`, `BottomSheet.ScrollView`, `BottomSheet.Close`,
+`BottomSheet.Title`, `BottomSheet.Description` and `BottomSheet.Footer`.
+
+`import { BottomSheet } from "@delacour/react-native-ui/bottom-sheet";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/bottom-sheet` |
+| `bottom-sheet.tsx` | Root + the `Object.assign` compound surface |
+| `bottom-sheet-trigger.tsx` | `BottomSheet.Trigger` |
+| `bottom-sheet-portal.tsx` | `BottomSheet.Portal`, and the overlay hoist |
+| `bottom-sheet-overlay.tsx` | `BottomSheet.Overlay` — one of the two `withUniwind` wrappers |
+| `bottom-sheet-container.tsx` | `BottomSheet.Container`, the modal, and the footer hoist |
+| `bottom-sheet-content.tsx` | `BottomSheet.Content` |
+| `bottom-sheet-scroll-view.tsx` | `BottomSheet.ScrollView` — the other wrapper |
+| `bottom-sheet-close.tsx` | `BottomSheet.Close` |
+| `bottom-sheet-title.tsx` | `BottomSheet.Title` |
+| `bottom-sheet-description.tsx` | `BottomSheet.Description` |
+| `bottom-sheet-footer.tsx` | `BottomSheet.Footer`, its sticky and inline branches |
+| `bottom-sheet-background.tsx` | The sheet's surface — internal |
+| `bottom-sheet-handle.tsx` | The grabber — internal |
+| `bottom-sheet.context.tsx` | Three contexts — the sheet, the portal, the container |
+| `bottom-sheet.variants.ts` | Pure `tv()` slots + two resolvers, no RN imports |
+| `bottom-sheet.variants.test.ts` | |
+| `use-bottom-sheet-input.ts` | What an `Input` needs to be a field the sheet owns |
+
+## Design
+
+- **Two parts are not drawn where they are written, and that is the component.**
+  gorhom takes the scrim and a pinned footer as *render props* on the modal —
+  `backdropComponent` and `footerComponent` — not as children. `BottomSheet.Portal`
+  lifts the `Overlay` out of its own children and publishes it on context;
+  `BottomSheet.Container` lifts a `Footer sticky` out of its own and clones both
+  into those slots. The alternative was a `backdrop` prop and a `footer` prop on
+  the container, which would put two parts of the anatomy somewhere the anatomy
+  cannot see them. `hoistOverlay` and `hoistFooter` live with the part that lifts
+  its own children — the rule `withIndicator` follows in [`radio.tsx`](../radio/AGENTS.md) — and the
+  decision inside the second, `resolveFooterPlacement`, is pure so `bun test`
+  reaches the matrix.
+- **The scrim's press area stops at the top of the sheet, and rebuilding it that
+  way is the only reason `Input` works in here.** gorhom's backdrop puts a
+  full-screen `Gesture.Tap()` behind the sheet. Gesture Handler resolves a touch
+  between competing GESTURES, so a `Button` in the sheet has one of its own and
+  wins — but a `TextInput` has none, the backdrop takes the tap, and the sheet
+  CLOSES instead of the field focusing. That is what gorhom's own
+  `BottomSheetTextInput` exists to fix, and taking that route would have left
+  this package's `Input` — its variants, its `Input.Group`, its `Field`
+  cascade — unusable inside a sheet. So `BottomSheet.Overlay` passes
+  `pressBehavior="none"` (no gesture anywhere) and lays a `Pressable` over the
+  band ABOVE the sheet, sized from the sheet's own `animatedPosition`. It cannot
+  overlap the sheet, so there is nothing for it to take, and the part of the
+  scrim anyone can actually see still closes. Confirmed both ways on a
+  simulator — with gorhom's backdrop the field could not be focused at all.
+- **Never call `dismiss()` on a modal that was never presented.** gorhom's modal
+  starts at status `INITIAL`; `dismiss()` reads that as a live sheet closing and
+  moves it to `DISMISSING`, where it stays. The next `present()` mounts the
+  portal and renders the sheet — and it never animates in, never lays out its
+  content and never fires `onChange`. Nothing throws, nothing is logged, and the
+  screen simply does not change. `BottomSheet.Container` keeps a
+  `hasPresentedRef` so the effect that mirrors `isOpen` only ever dismisses
+  something it opened. This cost an afternoon; do not "simplify" the guard away.
+- **A portal breaks context, so the container re-publishes its own.** The sheet's
+  children are rendered by `@gorhom/portal` into a host inside
+  `BottomSheetModalProvider` — a different place in the React tree from where
+  they were written — so the `BottomSheetContext` the root provides does not
+  reach them, and `BottomSheet.Close` throws "must be rendered inside a
+  `<BottomSheet>`". `BottomSheet.Container` wraps the modal's children in the
+  same provider again. `BottomSheet.Overlay` cannot be covered that way — gorhom
+  renders the backdrop outside those children — so its press area reads gorhom's
+  `useBottomSheet()` instead, which lands on `onDismiss` and therefore on
+  `onOpenChange` anyway.
+- **There is no size and no colour axis.** A sheet has one shape and one surface;
+  a second way to paint it would be a second thing to keep in step for no
+  question anyone is asking. `bottomSheetVariants` is slots and nothing else.
+
+## Footer and keyboard
+
+- **`BottomSheet.Footer` is inline by default, and `sticky` pins it.** Same word,
+  same default as [`Screen.Footer`](../screen/AGENTS.md), so the two cannot be read as opposites. The
+  two branches deliberately look different: an inline footer is in the flow and
+  inherits the sheet's surface, while a pinned one draws OVER the content and so
+  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 — `Screen.Footer`'s rule about its backing, one
+  component along. A footer written `sticky` but rendered outside a container
+  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.
+- **A pinned footer is TALLER by the safe-area band; it is not moved up by it.**
+  gorhom's `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 — with the content scrolling through it in plain view. So `bottomInset`
+  stays 0 and the band is part of the footer's own `paddingBottom`, putting its
+  surface against the bottom of the screen.
+- **The keyboard takes the band back, and ONLY the band.**
+  `BOTTOM_SHEET_FOOTER_PADDING` is always there and the band collapses into it as
+  `useReanimatedKeyboardAnimation()`'s `progress` runs 0 → 1, so the controls
+  never end up flush against the keyboard. Sliding the whole footer down by the
+  band instead — the first thing tried — parks its padding behind the keyboard
+  along with it, and the buttons sit on the keys. It also has to be the footer
+  genuinely getting *shorter* rather than moving, because that is what lets the
+  body's reserve shrink with it instead of holding back the height of a home
+  indicator that is no longer on screen. Both numbers are constants rather than
+  classes, for `SCREEN_FOOTER_PADDING`'s reason: an animated padding cannot be a
+  class, and the reserve maths has to read the same value.
+- **The footer publishes its measured height and the body reserves it with an
+  animated spacer.** Not gorhom's `enableFooterMarginAdjustment`, which turns that
+  height into content-container padding through React state — and since the
+  footer changes height on every frame of the keyboard animation, that is a
+  commit per frame. A shared value read by a spacer's animated style costs
+  nothing on the JS thread; [`Screen`](../screen/AGENTS.md) reserves its own chrome exactly this way.
+  The spacer sits OUTSIDE the classed content box, or the content's own `gap`
+  lands in front of it and silently doubles `BOTTOM_SHEET_FOOTER_GAP`. The
+  container owns the shared value because the footer and the body are siblings in
+  gorhom's tree and neither can see the other.
+- **Do not put a `KeyboardStickyView` inside a sheet.** This is the one keyboard
+  rule that differs from [`Screen`](../screen/AGENTS.md). gorhom's `animatedFooterPosition` already
+  carries a pinned footer clear of the keyboard and the translate above 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.
+- **Exactly one thing in the sheet pays for the home indicator.** With a pinned
+  footer that is the footer, whose own padding carries the band and whose height
+  the body already reserves; the content asking for it too would count it twice.
+  With no pinned footer the content is the bottom-most thing and takes it.
+  `resolveSheetBottomInset` is that decision and it is pure, so `bun test` reaches
+  it. As everywhere else the band comes from `useSafeAreaInsets()` and never from
+  `pb-safe`.
+
+## Styling
+
+- **`BottomSheet.ScrollView` puts its classes on an inner `View`, not on gorhom's
+  content container**, and that is not tidiness. Uniwind compiles a
+  `contentContainerClassName` into an **array** alongside any
+  `contentContainerStyle`; gorhom's footer-margin adjustment then reads
+  `paddingBottom` off a flattened style, an array flattens to an array, the band
+  reads as zero and the last row hides behind a pinned footer. One writer for
+  that style, and it is the inset. A scrollable sheet also needs
+  `enableDynamicSizing={false}` and explicit `snapPoints`, or the sheet grows to
+  the content and there is nothing to scroll within.
+- **Two `withUniwind` wrappers, and only two.** `BottomSheetBackdrop` and
+  `BottomSheetScrollView` are leaves that take a `style` and no `className`, so
+  each is wrapped once, at module scope, in its own file (rule 7).
+  `BottomSheetView` and `BottomSheetFooter` are **not** wrapped: both take
+  children, so an ordinary `View` nested inside carries the classes instead —
+  the move [`Screen.Footer`](../screen/AGENTS.md) already makes with `KeyboardStickyView`. Reach for a
+  nested view before a wrapper whenever the third-party component has room for
+  one. The scroll view's wrapper also needs its signature restated, the way
+  `Screen.LegendList`'s does — `withUniwind`'s mapped return type collapses a
+  scrollable's animated props to a single entry.
+- **`BottomSheet.Container` takes no `className`.** gorhom's modal wears an
+  animated style its own position writes every frame, so a class would reach
+  nothing `backgroundClassName` does not reach better. The background and the
+  handle are supplied as `backgroundComponent` and `handleComponent` — this
+  package's own views, so they take classes — and a `backgroundStyle`,
+  `handleStyle` or `handleIndicatorStyle` still arrives, forwarded as the `style`
+  each is handed. **Forwarding the background's `style` is load-bearing:** gorhom
+  passes `[StyleSheet.absoluteFill, backgroundStyle]`, and dropping it renders the
+  sheet transparent over the app.
+
+## Behaviour and defaults
+
+- **One callback for every way a sheet closes.** A swipe down, a press on the
+  scrim, `BottomSheet.Close` and a controlled `isOpen` all arrive at
+  `onOpenChange`, because presenting is driven by state and gorhom's `onDismiss`
+  is consumed rather than forwarded. gorhom's own `onClose` fires for the gesture
+  alone, which is the shape that makes a caller wire three handlers and still
+  miss one. `useBottomSheet().sheetRef` remains for the imperative calls with no
+  declarative form — `snapToIndex`, `expand`, `collapse`.
+- **`accessible` defaults to `false`, and it is the least obvious line in the
+  component.** 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 inside becomes unreachable to VoiceOver — the form gallery
+  route was a single "Bottom Sheet" element until this default was flipped. It is
+  [`Field`](../field/AGENTS.md)'s rule one component along: the row is `accessible={false}` so the
+  control stays the element a screen reader sees. Verified with
+  `native-describe-screen` on a simulator, not assumed.
+- **Three defaults differ from gorhom's, and each is a modal-sheet decision.**
+  `enablePanDownToClose` is on, because a modal sheet has no collapsed resting
+  state to pan down to. The backdrop appears on index `0` and disappears on `-1`
+  rather than `1` and `0`, for the same reason — gorhom's defaults suit a
+  persistent sheet that dims the app only once expanded. And the keyboard trio
+  is `interactive` / `restore` / `adjustResize`: leaving Android on gorhom's
+  `adjustPan` slides the whole window up instead of resizing it and puts the
+  footer off-screen, where `resize` is already what Expo configures and what
+  `KeyboardProvider` requires. All are ordinary props; `BOTTOM_SHEET_KEYBOARD_DEFAULTS`
+  is a const so a test pins the trio rather than three inline literals.
+- **`--overlay` is a token, not a `bg-black/50`.** A pure-black scrim over
+  a near-black dark theme is nearly invisible, so the two variants carry
+  different alphas — and because the alpha lives in the token, the backdrop's
+  `opacity` defaults to **1** rather than gorhom's 0.5, which would multiply the
+  two and land the scrim at a fifth of what the theme asked for. It takes no
+  `-foreground`: nothing is drawn on a scrim, and the sheet in front brings its
+  own. A test pins the token against both `@variant` blocks and pins the opacity
+  against the alpha being there.
+
+## Input
+
+- **`useBottomSheetInput()` is why `Input` still works in here.** A sheet only
+  grows for the keyboard when it knows the focused field is one of its own, and
+  gorhom's answer is to use its `BottomSheetTextInput` — which would leave this
+  package's `Input`, its variants, its `Input.Group` and its `Field` cascade
+  unusable inside a sheet. The registration is exposed as `{ onFocus, onBlur, ref }`
+  instead, so `Input` imports nothing from `@gorhom/bottom-sheet` and the hook is
+  inert outside a sheet. The `ref` is not optional polish: without it, moving
+  focus between two fields in one sheet reads as the keyboard closing and
+  reopening and the sheet resizes twice on the way. It covers the keyboard half only:
+  a *drag* across a field can still be claimed by the sheet's content pan, since
+  gorhom's input is built on Gesture Handler's `TextInput` and this one is not.
+  If that ever bites, the fix is `enableContentPanningGesture={false}` on the
+  container. The *tap* half is the scrim's problem and is solved above.
+
+## Structure
+
+- **There is no `bottom-sheet.types.ts`.** Nothing is shared by two modules that
+  is not already a type somewhere better: the text parts take `TextPresetProps`,
+  which `Text` already exports, and the container reads its footer's props from
+  `bottom-sheet-footer.tsx` directly — no cycle, since a part never imports the
+  container. A types leaf holding one alias would be a file with nothing in it.
+- **There is no `FullWindowOverlay`, so nothing imports `react-native-screens`.**
+  `BottomSheetModal` hosts itself in the `BottomSheetModalProvider` that
+  `DelacourProvider` mounts, which covers everything short of drawing over a
+  *native* stack modal. gorhom's `containerComponent` is the escape hatch if a
+  call site ever needs that; it is not worth the optional peer, the iOS element
+  inspector and the keyboard caveats before then.
+

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

@@ -0,0 +1,35 @@
+import type { BottomSheetBackgroundProps as GorhomBottomSheetBackgroundProps } from "@gorhom/bottom-sheet";
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { bottomSheetVariants } from "./bottom-sheet.variants";
+
+export type BottomSheetBackgroundProps = Partial<GorhomBottomSheetBackgroundProps> & {
+	className?: string;
+};
+
+/**
+ * The sheet's own surface, drawn 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.
+ *
+ * **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.
+ *
+ * The two animated variables are destructured off rather than spread: they are
+ * shared values, and a `View` has no use for either.
+ */
+export function BottomSheetBackground({
+	animatedIndex: _animatedIndex,
+	animatedPosition: _animatedPosition,
+	className,
+	style,
+	...props
+}: BottomSheetBackgroundProps): ReactElement {
+	return <View className={bottomSheetVariants().background({ className })} style={style} {...props} />;
+}
+BottomSheetBackground.displayName = "DelacourUI.BottomSheet.Background";

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

@@ -0,0 +1,60 @@
+import { type ReactElement, useCallback } 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">;
+
+/**
+ * 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`.
+ *
+ * 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.
+ *
+ * @example
+ * <BottomSheet.Content>
+ *   <BottomSheet.Close />
+ *   <BottomSheet.Title>Filters</BottomSheet.Title>
+ * </BottomSheet.Content>
+ */
+export function BottomSheetClose({
+	accessibilityLabel = "Close",
+	className,
+	feedback = "fade",
+	hitSlop = BOTTOM_SHEET_CLOSE_HIT_SLOP,
+	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>
+	);
+}
+BottomSheetClose.displayName = "DelacourUI.BottomSheet.Close";