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

package/src/components/pressable/pressable.tsx

@@ -0,0 +1,256 @@
+import {
+	Children,
+	type ComponentRef,
+	type ComponentType,
+	createElement,
+	isValidElement,
+	type ReactElement,
+	type ReactNode,
+	type Ref,
+	useMemo,
+} from "react";
+import type { AccessibilityState, ViewProps } from "react-native";
+import { Gesture, GestureDetector } from "react-native-gesture-handler";
+import { Presets } from "react-native-pulsar";
+import Animated, { useAnimatedStyle, useSharedValue, withSpring } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { composeRefs } from "../../lib/compose-refs";
+import { mergeProps } from "../../lib/merge-props";
+import { type PressableFeedback, resolvePressedState } from "./pressable.variants";
+
+const PRESS_SPRING = { damping: 18, mass: 0.4, stiffness: 320 } as const;
+
+/**
+ * Animated counterpart of each component type seen by `asChild`.
+ *
+ * `Animated.createAnimatedComponent` must be called once per type, never per
+ * render — a fresh wrapper each render remounts the subtree.
+ */
+const animatedTypeCache = new WeakMap<object, ComponentType<Record<string, unknown>>>();
+
+function resolveAnimatedType(type: unknown): ComponentType<Record<string, unknown>> {
+	if (typeof type !== "function" && typeof type !== "object") {
+		throw new Error("Pressable asChild expects a component element, not an intrinsic or text node.");
+	}
+
+	const key = type as object;
+	const cached = animatedTypeCache.get(key);
+	if (cached) return cached;
+
+	const created = Animated.createAnimatedComponent(type as ComponentType<Record<string, unknown>>) as ComponentType<
+		Record<string, unknown>
+	>;
+	animatedTypeCache.set(key, created);
+	return created;
+}
+
+export type HapticFeedback = "selection" | "light" | "medium" | "heavy" | "success" | "warning" | "error";
+
+/**
+ * Fires a haptic preset from the UI thread.
+ *
+ * Every branch is a worklet, so this runs inside the gesture callback itself —
+ * the tap and the haptic land in the same frame rather than waiting on a round
+ * trip to the JS thread.
+ *
+ * Exported because it is the library's *only* haptic vocabulary, and a second
+ * component with a gesture of its own — `Slider`, whose pan ticks as the value
+ * crosses a step — must reach this switch rather than fork one. It is safe to
+ * import across a component folder: nothing in `pressable/` imports a component
+ * that could import it back, so there is no cycle for Metro to serve half of.
+ */
+export function playHaptic(feedback: HapticFeedback): void {
+	"worklet";
+	switch (feedback) {
+		case "selection":
+			Presets.System.selection();
+			return;
+		case "light":
+			Presets.System.impactLight();
+			return;
+		case "medium":
+			Presets.System.impactMedium();
+			return;
+		case "heavy":
+			Presets.System.impactHeavy();
+			return;
+		case "success":
+			Presets.System.notificationSuccess();
+			return;
+		case "warning":
+			Presets.System.notificationWarning();
+			return;
+		case "error":
+			Presets.System.notificationError();
+			return;
+		default:
+			return;
+	}
+}
+
+export type PressableProps = Omit<ViewProps, "style"> & {
+	children?: ReactNode;
+	className?: string;
+	disabled?: boolean;
+	/**
+	 * Work is in flight: presses are blocked and a screen reader announces the
+	 * element as busy, but not as disabled. Use this over `disabled` for a
+	 * temporary state the component clears itself, so assistive tech reports a
+	 * control that is momentarily unavailable rather than one that is inert.
+	 */
+	busy?: boolean;
+	onPress?: () => void;
+	onLongPress?: () => void;
+	/** Haptic played on press-in. Off by default. */
+	haptic?: false | HapticFeedback;
+	/**
+	 * How the press moves the element: `scale`, `fade`, `scale-fade` or `none`.
+	 * `pressedScale` / `pressedOpacity` still win on the axis they name.
+	 */
+	feedback?: PressableFeedback;
+	/** Scale at full press. 1 disables the scale. Overrides `feedback`. */
+	pressedScale?: number;
+	/** Opacity at full press. 1 disables the fade. Overrides `feedback`. */
+	pressedOpacity?: number;
+	/** Render into the single child element instead of emitting a View. */
+	asChild?: boolean;
+	ref?: Ref<ComponentRef<typeof Animated.View>>;
+};
+
+/**
+ * The interaction primitive every pressable component in this library builds on.
+ *
+ * Press feedback runs entirely on the UI thread: a Gesture Handler tap drives a
+ * shared value, a spring maps it to scale and opacity, and the haptic fires in
+ * the same worklet. Only `onPress` and `onLongPress` cross back to JS.
+ *
+ * How far each axis travels comes from `feedback`, the named vocabulary every
+ * pressable in this library shares, or from `pressedScale` / `pressedOpacity`
+ * for a value the named modes do not cover.
+ *
+ * Built on the Gesture API rather than a ready-made pressable so the animation,
+ * the haptic and the gesture stay on one thread, and so nothing depends on
+ * Gesture Handler's own `Pressable`, which was renamed in its v3.
+ */
+export function Pressable({
+	children,
+	className,
+	disabled = false,
+	busy = false,
+	onPress,
+	onLongPress,
+	haptic = false,
+	feedback,
+	pressedScale,
+	pressedOpacity,
+	asChild = false,
+	accessibilityState,
+	ref,
+	...props
+}: PressableProps): ReactElement {
+	const pressed = useSharedValue(0);
+	const interactive = !disabled && !busy;
+	// Destructured to primitives on purpose. Reanimated's plugin collects what
+	// the worklet closes over, and a fresh object each render would rebuild the
+	// animated style every render.
+	const { opacity: targetOpacity, scale: targetScale } = resolvePressedState(feedback, pressedScale, pressedOpacity);
+
+	const gesture = useMemo(() => {
+		const tap = Gesture.Tap()
+			.enabled(interactive)
+			.shouldCancelWhenOutside(true)
+			.onBegin(() => {
+				"worklet";
+				pressed.value = withSpring(1, PRESS_SPRING);
+				if (haptic) playHaptic(haptic);
+			})
+			.onEnd(() => {
+				"worklet";
+				if (onPress) scheduleOnRN(onPress);
+			})
+			.onFinalize(() => {
+				"worklet";
+				pressed.value = withSpring(0, PRESS_SPRING);
+			});
+
+		if (!onLongPress) return tap;
+
+		const longPress = Gesture.LongPress()
+			.enabled(interactive)
+			.shouldCancelWhenOutside(true)
+			.onStart(() => {
+				"worklet";
+				scheduleOnRN(onLongPress);
+			});
+
+		return Gesture.Simultaneous(tap, longPress);
+	}, [haptic, interactive, onLongPress, onPress, pressed]);
+
+	const animatedStyle = useAnimatedStyle(() => ({
+		opacity: 1 - pressed.value * (1 - targetOpacity),
+		transform: [{ scale: 1 - pressed.value * (1 - targetScale) }],
+	}));
+
+	// Built once and spread at both render sites: a caller-supplied
+	// `accessibilityState` merges into it rather than being clobbered by the
+	// `{...props}` spread that lands after it.
+	const state: AccessibilityState = { ...accessibilityState, busy, disabled };
+
+	const content = asChild ? (
+		renderAsChild(children, {
+			accessibilityState: state,
+			accessible: true,
+			className,
+			ref,
+			style: animatedStyle,
+			...props,
+		})
+	) : (
+		<Animated.View
+			accessibilityRole="button"
+			accessibilityState={state}
+			// Without this the view is not an accessibility element on iOS, and the
+			// role, state and label above never reach VoiceOver — a composed label
+			// on an icon-sized button included. It also merges the children into one
+			// element, which is what a control should be.
+			accessible
+			className={className}
+			ref={ref}
+			style={animatedStyle}
+			{...props}
+		>
+			{children}
+		</Animated.View>
+	);
+
+	return <GestureDetector gesture={gesture}>{content}</GestureDetector>;
+}
+Pressable.displayName = "DelacourUI.Pressable";
+
+/**
+ * Renders the pressable's props into its single child, with no wrapper element.
+ *
+ * The child is rendered through the animated counterpart of its own type rather
+ * than cloned as-is. A Reanimated style handed to a plain component is deep
+ * frozen by React Native in development, and Reanimated's own effect then fails
+ * writing to it — so the element receiving the style has to be an animated one.
+ */
+function renderAsChild(children: ReactNode, slotProps: Record<string, unknown>): ReactElement {
+	const count = Children.count(children);
+	if (count !== 1) {
+		throw new Error(
+			`Pressable asChild expects exactly one child element, received ${count}. Drop \`asChild\` to render a View.`
+		);
+	}
+
+	const child = Children.only(children);
+	if (!isValidElement(child)) {
+		throw new Error("Pressable asChild expects a single React element child; text and fragments cannot take props.");
+	}
+
+	const childProps = child.props as Record<string, unknown> & { ref?: Ref<unknown> };
+	const merged = mergeProps<Record<string, unknown>>(slotProps, childProps);
+	merged.ref = composeRefs(slotProps.ref as Ref<unknown> | undefined, childProps.ref);
+
+	return createElement(resolveAnimatedType(child.type), merged);
+}

package/src/components/pressable/pressable.variants.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test } from "bun:test";
+import {
+	PRESSABLE_FEEDBACK,
+	PRESSABLE_FEEDBACK_FALLBACK,
+	PRESSABLE_FEEDBACKS,
+	resolvePressedState,
+} from "./pressable.variants";
+
+describe("PRESSABLE_FEEDBACK", () => {
+	test("covers every named feedback", () => {
+		for (const feedback of PRESSABLE_FEEDBACKS) {
+			expect(PRESSABLE_FEEDBACK[feedback]).toBeDefined();
+		}
+	});
+
+	test("gives every named feedback a distinct pair", () => {
+		const seen = new Set(PRESSABLE_FEEDBACKS.map((feedback) => JSON.stringify(PRESSABLE_FEEDBACK[feedback])));
+		expect(seen.size).toBe(PRESSABLE_FEEDBACKS.length);
+	});
+
+	// 1 is the neutral value on either axis, so a single-axis mode leaves the
+	// other one alone rather than nudging it.
+	test("scale shrinks without dimming", () => {
+		expect(PRESSABLE_FEEDBACK.scale.opacity).toBe(1);
+		expect(PRESSABLE_FEEDBACK.scale.scale).toBeLessThan(1);
+	});
+
+	test("fade dims without scaling", () => {
+		expect(PRESSABLE_FEEDBACK.fade.scale).toBe(1);
+		expect(PRESSABLE_FEEDBACK.fade.opacity).toBeLessThan(1);
+	});
+
+	test("none moves neither axis", () => {
+		expect(PRESSABLE_FEEDBACK.none).toEqual({ opacity: 1, scale: 1 });
+	});
+
+	// The load-bearing one: `scale-fade` is the union of the two single-axis
+	// modes, not a third set of numbers. Tuning `scale` or `fade` has to carry
+	// through, or the name stops describing what the mode does.
+	test("scale-fade takes each axis from the mode that owns it", () => {
+		expect(PRESSABLE_FEEDBACK["scale-fade"]).toEqual({
+			opacity: PRESSABLE_FEEDBACK.fade.opacity,
+			scale: PRESSABLE_FEEDBACK.scale.scale,
+		});
+	});
+
+	test("every mode stays within the range the press interpolates over", () => {
+		for (const feedback of PRESSABLE_FEEDBACKS) {
+			const { opacity, scale } = PRESSABLE_FEEDBACK[feedback];
+			expect(opacity).toBeGreaterThan(0);
+			expect(opacity).toBeLessThanOrEqual(1);
+			expect(scale).toBeGreaterThan(0);
+			expect(scale).toBeLessThanOrEqual(1);
+		}
+	});
+});
+
+describe("resolvePressedState", () => {
+	test("maps each named feedback to its pair", () => {
+		for (const feedback of PRESSABLE_FEEDBACKS) {
+			expect(resolvePressedState(feedback, undefined, undefined)).toEqual(PRESSABLE_FEEDBACK[feedback]);
+		}
+	});
+
+	// Naming the fallback would either change what a bare Pressable has always
+	// done or make `scale-fade` fade less than `fade`. It stays unnamed instead.
+	test("falls back to the pair a bare pressable has always used", () => {
+		expect(resolvePressedState(undefined, undefined, undefined)).toEqual(PRESSABLE_FEEDBACK_FALLBACK);
+		expect(PRESSABLE_FEEDBACK_FALLBACK).toEqual({ opacity: 0.9, scale: 0.97 });
+	});
+
+	test("an explicit value beats the fallback on its own axis", () => {
+		expect(resolvePressedState(undefined, 1, undefined)).toEqual({
+			opacity: PRESSABLE_FEEDBACK_FALLBACK.opacity,
+			scale: 1,
+		});
+		expect(resolvePressedState(undefined, undefined, 1)).toEqual({
+			opacity: 1,
+			scale: PRESSABLE_FEEDBACK_FALLBACK.scale,
+		});
+	});
+
+	test("an explicit value beats a named feedback on its own axis", () => {
+		expect(resolvePressedState("scale-fade", undefined, 0.2)).toEqual({
+			opacity: 0.2,
+			scale: PRESSABLE_FEEDBACK["scale-fade"].scale,
+		});
+		expect(resolvePressedState("none", 0.5, undefined)).toEqual({ opacity: 1, scale: 0.5 });
+	});
+
+	test("both explicit values leave nothing of the named feedback", () => {
+		expect(resolvePressedState("scale", 0.5, 0.5)).toEqual({ opacity: 0.5, scale: 0.5 });
+	});
+
+	// 0 is a legitimate value on either axis and must not read as "unset".
+	test("treats an explicit zero as a value, not an absence", () => {
+		expect(resolvePressedState("scale", 0, 0)).toEqual({ opacity: 0, scale: 0 });
+	});
+});

package/src/components/pressable/pressable.variants.ts

@@ -0,0 +1,63 @@
+export const PRESSABLE_FEEDBACKS = ["scale", "fade", "scale-fade", "none"] as const;
+
+export type PressableFeedback = (typeof PRESSABLE_FEEDBACKS)[number];
+
+/** What a press interpolates towards. 1 is the neutral value on either axis. */
+export type PressedState = {
+	opacity: number;
+	scale: number;
+};
+
+/**
+ * How a press moves each axis, by name.
+ *
+ * `scale-fade` is composed from the two single-axis modes rather than given
+ * numbers of its own, so tuning `scale` or `fade` carries through to it and the
+ * name keeps describing what the mode does.
+ *
+ * There is no mode involving a ripple, ink or highlight overlay — AGENTS.md
+ * rules those out for every pressable in this library.
+ *
+ * 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 PRESSABLE_FEEDBACK: Record<PressableFeedback, PressedState> = {
+	scale: { opacity: 1, scale: 0.97 },
+	fade: { opacity: 0.6, scale: 1 },
+	"scale-fade": { opacity: 0.6, scale: 0.97 },
+	none: { opacity: 1, scale: 1 },
+};
+
+/**
+ * The pair a pressable uses with no `feedback` and no explicit values.
+ *
+ * Deliberately not one of the named modes. It fades less than `fade` does, so
+ * naming it would either change what a bare `Pressable` has always done or
+ * force `scale-fade` to fade less than `fade` — and a caller who wants a named
+ * mode can just say so.
+ */
+export const PRESSABLE_FEEDBACK_FALLBACK: PressedState = { opacity: 0.9, scale: 0.97 };
+
+/**
+ * Folds a named feedback and any explicit values into the pair a press
+ * interpolates towards.
+ *
+ * An explicit `pressedScale` / `pressedOpacity` wins on its own axis and leaves
+ * the other one to the named mode, so `feedback="scale-fade"` with
+ * `pressedOpacity={0.2}` is a deeper fade at the mode's scale rather than an
+ * all-or-nothing choice between the two APIs.
+ *
+ * Pure, so the whole matrix is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolvePressedState(
+	feedback: PressableFeedback | undefined,
+	pressedScale: number | undefined,
+	pressedOpacity: number | undefined
+): PressedState {
+	const named = feedback ? PRESSABLE_FEEDBACK[feedback] : PRESSABLE_FEEDBACK_FALLBACK;
+
+	return {
+		opacity: pressedOpacity ?? named.opacity,
+		scale: pressedScale ?? named.scale,
+	};
+}

package/src/components/provider/AGENTS.md

@@ -0,0 +1,90 @@
+# DelacourProvider
+
+Every provider an app needs at its root, in one component. Mount it once, around
+everything — a root layout, an `App.tsx`.
+
+`import { DelacourProvider } from "@delacour/react-native-ui/provider";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/provider` |
+| `provider.tsx` | `DelacourProvider` — the app's root layer stack; its `displayName` is `DelacourUI.Provider`, because prefix-plus-symbol would stutter and this matches its export subpath |
+
+## Design
+
+- **Five layers, outermost first**: `GestureHandlerRootView` →
+  `SafeAreaProvider` → `KeyboardProvider` → `<KeyboardStateSync />` beside the
+  children → `BottomSheetModalProvider` around them. The order is not stylistic.
+  The gesture root has to be an ancestor native view of every handler a
+  `Pressable` creates, and its absence is *silent* — no error, no warning,
+  presses simply stop landing. `KeyboardStateSync` has to be a CHILD of
+  `KeyboardProvider`, because it calls `useKeyboardContext()`, and it stays a
+  SIBLING of the modal provider rather than moving inside it: the repair is
+  global and has to outlive any layer that can remount.
+- **`initialMetrics` defaults to `initialWindowMetrics`, and that is
+  load-bearing.** `SafeAreaProvider` renders `null` — not unstyled children,
+  *nothing* — until its native view reports the first `onInsetsChange`, so
+  without the seed every cold start shows a blank frame. The seed is a snapshot
+  taken at native module init, so it is stale when the app launches into a
+  rotated or split-screen window — stale for exactly one commit, because the
+  native measurement overwrites it. A blank frame on every launch is the worse
+  trade. `initialMetrics={null}` opts out: a default parameter only fires on
+  `undefined`, so `null` is a value rather than an absence, the same rule
+  `pressedScale` follows.
+- **`style` reaches the gesture root and carries no default.**
+  `GestureHandlerRootView` applies its own `{ flex: 1 }` whenever `style` is
+  undefined, so merging one in here would both duplicate it and make the prop
+  behave differently than it does upstream. Pass a style and that `flex: 1` is
+  gone — include it yourself.
+- **No per-layer escape hatches, and no layer-named props.** No
+  `gestureHandler={false}`, no `safeAreaProps`, no `keyboardProps`. A boolean
+  that turns off the gesture root has "nothing responds to a press" as its
+  failure mode, which is the least debuggable outcome in the package. And a prop
+  surface that names the layers changes shape every time a layer is added:
+  `children`, `style` and `initialMetrics` say nothing about what is inside, so a
+  future `BottomSheetModalProvider` or portal host is an edit to one file rather
+  than a breaking change. An app that genuinely needs a different stack composes
+  the providers by hand — they are all public from their own packages, and this
+  is a convenience, not a gate.
+- **A new layer goes innermost.** Anything that draws above the app — a
+  bottom-sheet modal provider, a portal host, a toast host — has to sit inside
+  every provider it reads, so it wraps `{children}` and nothing else moves. A
+  layer that brings a new native peer is a peer-dependency decision first.
+  `BottomSheetModalProvider` is the case this rule was written for and now the
+  case it governs: it reads the gesture root for its pan, the safe area for its
+  insets and the keyboard values a sheet's footer rides, so it is last.
+- **`@gorhom/bottom-sheet` is a required peer because of this component**, on
+  exactly the argument `react-native-keyboard-controller` already carries. It was
+  optional while nothing imported it. The recommended root now does, so every app
+  resolves it, and a flag saying otherwise would only suppress the install
+  warning that explains the Metro resolution error coming out of the app's root
+  layout. It is pure JavaScript over Reanimated and Gesture Handler — both
+  required peers already — so this costs an install and no native build. Rule 3's
+  promise survives intact: `/button` still pulls nothing sheet-related.
+- **Deliberately not idempotent.** It does not detect an enclosing copy of
+  itself. Nesting `GestureHandlerRootView` costs a `View`; nesting
+  `SafeAreaProvider` seeds from the parent's insets and costs a native view;
+  nesting `KeyboardProvider` is the one that actually breaks — two pairs of
+  shared values, two sets of native observers, and the outer `KeyboardStateSync`
+  repairing values nobody reads. That is also the only layer that cannot be
+  detected: `useKeyboardContext()` returns a module-private default object
+  outside a provider, that object is not exported, and the hook `console.warn`s
+  whenever it hands one back, so a detection read would print a warning in every
+  correctly-mounted app. A guard covering the two harmless layers and missing the
+  harmful one is worse than none — it teaches callers that nesting is fine.
+- **`react-native-keyboard-controller` is a required peer because of this
+  component.** It was optional while [`Screen`](../screen/AGENTS.md) was the only importer: an app that
+  never imported `Screen` never resolved it. The recommended root now imports it,
+  so every app resolves it, and the flag had stopped describing reality — all it
+  still did was suppress the install warning that would have explained the Metro
+  resolution error coming out of the app's root layout. Rule 3's promise is
+  per-subpath and survives intact: `/button` still pulls nothing
+  keyboard-related.
+- **Nothing here for `bun test`, and no `provider.variants.ts` to give it
+  some.** The component is four nested elements and one default parameter;
+  extracting a `resolveInitialMetrics()` would be a unit test of `??`. The rule
+  that pure decisions live in a `*.variants.ts` has no decision here to
+  relocate.
+- **No gallery route.** See [Adding a component](../../../AGENTS.md#adding-a-component).

package/src/components/provider/index.ts

@@ -0,0 +1 @@
+export { DelacourProvider, type DelacourProviderProps } from "./provider";

package/src/components/provider/provider.tsx

@@ -0,0 +1,105 @@
+import { BottomSheetModalProvider } from "@gorhom/bottom-sheet";
+import type { ReactElement, ReactNode } from "react";
+import type { StyleProp, ViewStyle } from "react-native";
+import { GestureHandlerRootView } from "react-native-gesture-handler";
+import { KeyboardProvider } from "react-native-keyboard-controller";
+import { initialWindowMetrics, type Metrics, SafeAreaProvider } from "react-native-safe-area-context";
+import { KeyboardStateSync } from "../../hooks/use-keyboard-state-sync";
+
+export type DelacourProviderProps = {
+	children: ReactNode;
+	/**
+	 * Safe-area insets and frame to render the first frame against, before the
+	 * native provider has measured anything.
+	 *
+	 * Defaults to `initialWindowMetrics`, the snapshot the native module captured
+	 * at launch, because `SafeAreaProvider` renders NOTHING — not unstyled
+	 * children, `null` — until its first `onInsetsChange` lands. Without a seed
+	 * every cold start shows a blank frame.
+	 *
+	 * Pass `null` to opt out. A default parameter only fires on `undefined`, so
+	 * `null` is a value here rather than an absence.
+	 */
+	initialMetrics?: Metrics | null;
+	/**
+	 * Style for the outermost `GestureHandlerRootView`.
+	 *
+	 * Forwarded untouched, with no default merged in: the gesture root applies
+	 * its own `{ flex: 1 }` whenever `style` is undefined. Pass one and that
+	 * default is gone, so include `flex: 1` unless the root genuinely should not
+	 * fill the window.
+	 */
+	style?: StyleProp<ViewStyle>;
+};
+
+/**
+ * Every provider this library needs at an app's root, in one component.
+ *
+ * Mount it ONCE, around everything — a root layout, an `App.tsx`. It is not
+ * idempotent and does not detect an enclosing copy of itself; see AGENTS.md.
+ *
+ * Five layers, outermost first, and the order is not stylistic:
+ *
+ * 1. `GestureHandlerRootView` — an ancestor native view every gesture handler
+ *    `Pressable` creates has to attach to. Its absence is silent: no error, no
+ *    warning, presses simply stop landing.
+ * 2. `SafeAreaProvider` — the insets `Screen`'s navbar, footer and scroll
+ *    reserves are all computed from, seeded so the first frame is not blank.
+ * 3. `KeyboardProvider` — the shared animation values `Screen.Footer` rides.
+ * 4. `KeyboardStateSync` — a child of the keyboard provider, because it calls
+ *    `useKeyboardContext()`. It repairs the one pair of animation values that
+ *    provider shares with the whole app: on iOS they are written only from the
+ *    `will` events, so a keyboard that vanishes without one — an interactive
+ *    dismiss interrupted by navigation, a stack pop, an app suspend — leaves
+ *    every screen in the app believing it is still open.
+ * 5. `BottomSheetModalProvider` — the host every `BottomSheet` portals into. It
+ *    goes innermost because it draws ABOVE the app and reads every layer over
+ *    it: the gesture root for the pan, the safe area for its insets, and the
+ *    keyboard values a sheet's footer rides. It wraps `{children}` and nothing
+ *    else moves, which is what a new layer here always looks like.
+ *
+ * `KeyboardStateSync` stays a SIBLING of it rather than a child. The repair is
+ * global and has to run for the whole app's lifetime; inside a layer that can
+ * remount it would be torn down with it.
+ *
+ * There are no per-layer escape hatches and no layer-named props on purpose.
+ * An app that needs a different stack composes the providers by hand; they are
+ * all public from their own packages, and this is a convenience, not a gate.
+ *
+ * @example
+ * // expo-router root layout. The css import must stay the first statement.
+ * import "../styles/global.css";
+ * import { DelacourProvider } from "@delacour/react-native-ui/provider";
+ * import { Stack } from "expo-router";
+ *
+ * export default function RootLayout() {
+ *   return (
+ *     <DelacourProvider>
+ *       <Stack screenOptions={{ headerShown: false }} />
+ *     </DelacourProvider>
+ *   );
+ * }
+ *
+ * @example
+ * // Measure the safe area from scratch, accepting the blank first frame — an
+ * // app that launches into a rotated or split-screen window and cannot
+ * // tolerate one stale frame.
+ * <DelacourProvider initialMetrics={null}>{children}</DelacourProvider>
+ */
+export function DelacourProvider({
+	children,
+	initialMetrics = initialWindowMetrics,
+	style,
+}: DelacourProviderProps): ReactElement {
+	return (
+		<GestureHandlerRootView style={style}>
+			<SafeAreaProvider initialMetrics={initialMetrics}>
+				<KeyboardProvider>
+					<KeyboardStateSync />
+					<BottomSheetModalProvider>{children}</BottomSheetModalProvider>
+				</KeyboardProvider>
+			</SafeAreaProvider>
+		</GestureHandlerRootView>
+	);
+}
+DelacourProvider.displayName = "DelacourUI.Provider";