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

package/src/components/meter/meter.variants.ts

@@ -0,0 +1,347 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+import {
+	PROGRESS_COLORS,
+	PROGRESS_DEFAULT_COLOR,
+	PROGRESS_DEFAULT_SIZE,
+	PROGRESS_MAX_VALUE,
+	PROGRESS_MIN_VALUE,
+	PROGRESS_SIZES,
+} from "../progress/progress.variants";
+
+/**
+ * What a meter's colour can say. The progress bar's set, re-exported rather than
+ * restated, because a meter is that bar with a judgement about the reading — the
+ * two have to name a colour with the same word.
+ */
+export const METER_COLORS = PROGRESS_COLORS;
+
+export const METER_SIZES = PROGRESS_SIZES;
+
+export type MeterColor = (typeof METER_COLORS)[number];
+export type MeterSize = (typeof METER_SIZES)[number];
+
+export const METER_DEFAULT_COLOR: MeterColor = PROGRESS_DEFAULT_COLOR;
+export const METER_DEFAULT_SIZE: MeterSize = PROGRESS_DEFAULT_SIZE;
+
+/** The scale a meter covers when the caller names none, or names one that is not a finite number. */
+export const METER_MIN_VALUE = PROGRESS_MIN_VALUE;
+export const METER_MAX_VALUE = PROGRESS_MAX_VALUE;
+
+/** The most blocks a segmented meter draws. Past this a block is thinner than its own gap. */
+export const METER_MAX_SEGMENTS = 100;
+
+/** How long a block takes to light or go dark. Instant under the system's reduce-motion setting. */
+export const METER_SEGMENT_FADE_MS = 180;
+
+/**
+ * Where a reading falls against `low`, `high` and `optimum`.
+ *
+ * `optimum` is the good region, `suboptimum` the one next to it, `critical` the
+ * far side of that — the three regions a gauge with a preferred end has.
+ */
+export const METER_REGIONS = ["optimum", "suboptimum", "critical"] as const;
+
+export type MeterRegion = (typeof METER_REGIONS)[number];
+
+/** What each region paints the fill. Fixed, so a region reads the same in every meter in an app. */
+export const METER_REGION_COLORS: Record<MeterRegion, MeterColor> = {
+	optimum: "success",
+	suboptimum: "warning",
+	critical: "destructive",
+};
+
+/** A point on the scale where the colour changes. `from` is in the value's own units, not a percentage. */
+export type MeterThreshold = { from: number; color: MeterColor };
+
+/**
+ * How a meter decides its colour.
+ *
+ * - `plain` — the `color` prop, whatever the reading.
+ * - `regions` — `low`, `high` and `optimum` split the scale into good, worse and
+ *   worst, painted {@link METER_REGION_COLORS}.
+ * - `thresholds` — the highest `from` the reading has reached names the colour.
+ */
+export type MeterScale =
+	| { kind: "plain" }
+	| { kind: "regions"; low: number | undefined; high: number | undefined; optimum: number | undefined }
+	| { kind: "thresholds"; thresholds: readonly MeterThreshold[] };
+
+/**
+ * Styling for a segmented meter's blocks.
+ *
+ * The continuous bar is `Progress.Track` and `Progress.Fill` as they stand, so
+ * only the blocks need slots of their own. **An unlit block is the progress
+ * track's groove**, `bg-secondary`, and a lit one the progress fill's colour, so
+ * a segmented meter and a continuous one in one card read as one instrument;
+ * the tests pin both against `progressVariants`.
+ *
+ * **The lit colour is a layer over the block, not the block's own background.**
+ * It fades its opacity in and out, which a background colour cannot do on the UI
+ * thread without interpolating two token values in JavaScript.
+ *
+ * Free of React Native imports so it stays unit-testable. See AGENTS.md.
+ */
+export const meterVariants = tv({
+	slots: {
+		/** The row of blocks. */
+		segments: "w-full flex-row gap-1",
+		/** One block: an unlit groove clipping its lit layer. */
+		segment: "relative flex-1 overflow-hidden rounded-full bg-secondary",
+		/** The lit layer. Its opacity is animated, never a class. */
+		segmentFill: "absolute inset-0 rounded-full",
+	},
+	variants: {
+		size: {
+			sm: { segment: "h-1" },
+			md: { segment: "h-2" },
+			lg: { segment: "h-3", segments: "gap-1.5" },
+		},
+		color: {
+			default: { segmentFill: "bg-foreground" },
+			primary: { segmentFill: "bg-primary" },
+			success: { segmentFill: "bg-success" },
+			warning: { segmentFill: "bg-warning" },
+			destructive: { segmentFill: "bg-destructive" },
+			info: { segmentFill: "bg-info" },
+		},
+	},
+	defaultVariants: {
+		color: METER_DEFAULT_COLOR,
+		size: METER_DEFAULT_SIZE,
+	},
+});
+
+/**
+ * A scale that is finite and ordered.
+ *
+ * A bound that is not a finite number takes the documented default, and an
+ * inverted or empty scale collapses at its floor — so it reads as empty rather
+ * than handing a negative span to the fill or `NaN` to the accessibility value.
+ */
+export function meterRange(minValue: number, maxValue: number): { minValue: number; maxValue: number } {
+	const min = Number.isFinite(minValue) ? minValue : METER_MIN_VALUE;
+	const max = Number.isFinite(maxValue) ? maxValue : METER_MAX_VALUE;
+	return { maxValue: max < min ? min : max, minValue: min };
+}
+
+/**
+ * The reading, on the scale.
+ *
+ * Clamped to its ends. `NaN` reads at the floor; an infinity is a direction, so
+ * it reads at the end it points to.
+ */
+export function meterValue(value: number, minValue: number, maxValue: number): number {
+	if (Number.isNaN(value)) return minValue;
+	return value < minValue ? minValue : value > maxValue ? maxValue : value;
+}
+
+function clamp(value: number, min: number, max: number): number {
+	return value < min ? min : value > max ? max : value;
+}
+
+/**
+ * Which region a reading falls in.
+ *
+ * `low` and `high` default to the scale's ends and `optimum` to its middle; each
+ * is clamped into the scale, and `high` is never below `low`, so a boundary
+ * written the wrong way round is pulled into order rather than inverting every
+ * region.
+ *
+ * - **`optimum` below `low`** — the bottom is good: a disk. Below `low` is
+ *   `optimum`, up to `high` is `suboptimum`, above it `critical`.
+ * - **`optimum` above `high`** — the top is good: a battery. The same, mirrored.
+ * - **`optimum` between them** — the band is good and either side is
+ *   `suboptimum`: a room's temperature.
+ */
+export function resolveMeterRegion({
+	value,
+	minValue,
+	maxValue,
+	low,
+	high,
+	optimum,
+}: {
+	value: number;
+	minValue: number;
+	maxValue: number;
+	low?: number;
+	high?: number;
+	optimum?: number;
+}): MeterRegion {
+	const reading = meterValue(value, minValue, maxValue);
+	const lowBound = clamp(low ?? minValue, minValue, maxValue);
+	const highBound = clamp(high ?? maxValue, lowBound, maxValue);
+	const best = clamp(optimum ?? (minValue + maxValue) / 2, minValue, maxValue);
+
+	if (best < lowBound) {
+		if (reading < lowBound) return "optimum";
+		return reading <= highBound ? "suboptimum" : "critical";
+	}
+	if (best > highBound) {
+		if (reading > highBound) return "optimum";
+		return reading >= lowBound ? "suboptimum" : "critical";
+	}
+	return reading >= lowBound && reading <= highBound ? "optimum" : "suboptimum";
+}
+
+/**
+ * The colour of the highest threshold the reading has reached, or `undefined`
+ * below all of them.
+ *
+ * The order the thresholds are listed in does not matter, and one whose `from`
+ * is not a finite number is ignored.
+ */
+export function thresholdColor(value: number, thresholds: readonly MeterThreshold[]): MeterColor | undefined {
+	let reached: MeterThreshold | undefined;
+	for (const threshold of thresholds) {
+		if (!Number.isFinite(threshold.from) || threshold.from > value) continue;
+		if (reached === undefined || threshold.from >= reached.from) reached = threshold;
+	}
+	return reached?.color;
+}
+
+/** What a meter was given to judge its reading by. */
+export type MeterScaleInput = {
+	low?: number;
+	high?: number;
+	optimum?: number;
+	thresholds?: readonly MeterThreshold[];
+};
+
+/** Settles which way a meter decides its colour — see {@link MeterScale}. */
+export function resolveMeterScale({ low, high, optimum, thresholds }: MeterScaleInput): MeterScale {
+	if (thresholds !== undefined) return { kind: "thresholds", thresholds };
+	if (low !== undefined || high !== undefined || optimum !== undefined) {
+		return { high, kind: "regions", low, optimum };
+	}
+	return { kind: "plain" };
+}
+
+/**
+ * The colour the fill is painted, and the region it was judged to be in.
+ *
+ * `region` is `null` unless the scale is `regions`; it is what a readout or a
+ * `valueLabel` reads to put the judgement into words, because colour alone is
+ * not an answer for anyone who cannot see it.
+ */
+export function resolveMeterColor({
+	value,
+	minValue,
+	maxValue,
+	color,
+	scale,
+}: {
+	value: number;
+	minValue: number;
+	maxValue: number;
+	color: MeterColor;
+	scale: MeterScale;
+}): { color: MeterColor; region: MeterRegion | null } {
+	const reading = meterValue(value, minValue, maxValue);
+	switch (scale.kind) {
+		case "plain":
+			return { color, region: null };
+		case "thresholds":
+			return { color: thresholdColor(reading, scale.thresholds) ?? color, region: null };
+		case "regions": {
+			const region = resolveMeterRegion({ ...scale, maxValue, minValue, value: reading });
+			return { color: METER_REGION_COLORS[region], region };
+		}
+	}
+}
+
+/**
+ * How many blocks to draw, or `null` for the continuous bar.
+ *
+ * A fractional count rounds down and a count above {@link METER_MAX_SEGMENTS}
+ * clamps to it. A count under one, or one that is not a finite number, falls
+ * back to the bar rather than drawing nothing.
+ */
+export function meterSegmentCount(segments: number | undefined): number | null {
+	if (segments === undefined || !Number.isFinite(segments)) return null;
+	const count = Math.floor(segments);
+	if (count < 1) return null;
+	return count > METER_MAX_SEGMENTS ? METER_MAX_SEGMENTS : count;
+}
+
+/** Absorbs floating-point error, so `0.7 × 10` lights seven blocks rather than six. */
+const SEGMENT_EPSILON = 1e-9;
+
+/**
+ * How many blocks a reading lights.
+ *
+ * Whole blocks only — a block is all or nothing, which is the point of drawing
+ * blocks at all. **Any reading above the floor lights at least one**: rounding
+ * down would leave the first quarter of a four-block meter dark, and "a little"
+ * looking like "none" is the one reading a meter cannot afford to get wrong.
+ */
+export function litSegments({ ratio, count }: { ratio: number; count: number }): number {
+	const clamped = clamp(ratio, 0, 1);
+	if (clamped <= 0) return 0;
+	const lit = Math.floor(clamped * count + SEGMENT_EPSILON);
+	return lit < 1 ? 1 : lit > count ? count : lit;
+}
+
+/**
+ * A settled reading, before any `valueLabel` — what a `valueLabel` function is
+ * handed to word the reading, and its judgement, itself.
+ */
+export type MeterReading = {
+	/** The reading, clamped to the scale. */
+	value: number;
+	minValue: number;
+	maxValue: number;
+	/** Where the reading sits on the scale, 0–1. */
+	ratio: number;
+	/** The reading, formatted by `formatOptions`. */
+	formatted: string;
+	/** The colour the reading was judged to be. */
+	color: MeterColor;
+	/** The region the reading falls in, when judged by `low`, `high` and `optimum`. */
+	region: MeterRegion | null;
+};
+
+/** Words for the reading: fixed, or computed from it. */
+export type MeterValueLabel = string | ((reading: MeterReading) => string);
+
+/**
+ * The text that replaces the formatted reading, on screen and to assistive
+ * technology — or `undefined` to keep the formatted reading.
+ *
+ * **A function is how a judgement reaches a screen reader.** `Meter.Output` is
+ * hidden from assistive technology because the root already speaks the value,
+ * so words a readout function draws — "Filling up" — are seen and never heard.
+ * The label is spoken, so computing it from the region says the judgement to
+ * both at once.
+ */
+export function resolveMeterValueLabel(
+	valueLabel: MeterValueLabel | undefined,
+	reading: MeterReading
+): string | undefined {
+	return typeof valueLabel === "function" ? valueLabel(reading) : valueLabel;
+}
+
+/** What a meter was given at its own call site. */
+export type MeterOwnAxes = {
+	color?: MeterColor;
+	size?: MeterSize;
+};
+
+/** Every axis settled. */
+export type MeterAxes = Required<MeterOwnAxes>;
+
+/**
+ * Settles a meter's axes.
+ *
+ * One rung, deliberately: a meter reports a reading and accepts no input, so an
+ * enclosing `Field` has no disabled or invalid state to hand it.
+ */
+export function resolveMeterAxes(own: MeterOwnAxes): MeterAxes {
+	return {
+		color: own.color ?? METER_DEFAULT_COLOR,
+		size: own.size ?? METER_DEFAULT_SIZE,
+	};
+}
+
+export type MeterVariantProps = VariantProps<typeof meterVariants>;

package/src/components/overlay/AGENTS.md

@@ -0,0 +1,89 @@
+# Overlay
+
+The layer under every overlay in this library — Dialog, Drawer, Popover, Tooltip, Toast,
+Feedback. Not a component anyone renders on its own: the provider an app mounts once, and the
+parts and hooks an overlay is drawn with.
+
+`import { Overlay, OverlayProvider, useOverlayBackHandler, useOverlayPresence } from "@delacour/react-native-ui/overlay";`
+
+`react-native-teleport` is an **optional peer**, as it is for `BottomSheet`: an app that never
+imports an overlay never resolves it. The consequence is the same one thing to do — **mount
+`OverlayProvider` once**, inside `DelacourProvider`, around `BottomSheetProvider` and the navigator.
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/overlay` |
+| `overlay.tsx` | `Overlay` — the root is the provider: teleport's `PortalProvider` (skipped when one is already above), the registry and the touch-start fan-out; the `Object.assign` names `Portal` and `Scrim`. `OverlayProvider` is the same component, under the name a root layout reads best with |
+| `overlay-portal.tsx` | `Overlay.Portal` — registers while mounted, teleports to `"root"` in a `box-none` absolute fill carrying the registry's `zIndex`; inline without a provider |
+| `overlay-scrim.tsx` | `Overlay.Scrim` — `bg-overlay`, opacity follows presence, hidden from assistive technology |
+| `overlay.context.tsx` | **Leaf.** `OverlayContext`, `TeleportProvidedContext` and their hooks. `bottom-sheet/` imports it |
+| `overlay-registry.ts` | **Pure.** The z-order reducer, `zIndexOfOverlay`, `topOverlay`, `isTopOverlay`, `OVERLAY_LAYER_BASE` |
+| `overlay-presence.ts` | **Pure.** `reducePresence` — `closed → entering → open → exiting → closed` |
+| `overlay.variants.ts` | `overlayVariants` (`scrim`), `OVERLAY_MOTION`, `OVERLAY_SCRIM_TOKEN` |
+| `use-overlay-presence.ts` | `useOverlayPresence` — keeps an overlay mounted through its exit, drives `progress` 0 → 1 |
+| `use-overlay-back-handler.ts` | `useOverlayBackHandler` — Android back, only while the overlay is the top |
+| `*.test.ts` | The registry, the presence machine, the scrim token and the motion constants |
+
+## Design
+
+- **There is exactly one teleport `PortalProvider` in an app, and this is why the folder
+  exists.** Teleport registers its hosts natively by name, and the bottom-sheet engine's
+  provider already mounts one with a `"root"` host. Six overlays each mounting their own would
+  mean seven hosts called `"root"`. So `OverlayProvider` and this library's `BottomSheetProvider`
+  each mount teleport's provider only when `TeleportProvidedContext` says none is above, and set
+  it when they do — either mount order works, and the engine's provider learned
+  `hasPortalProvider` to make the skip possible. Everything draws into one `"root"` host.
+- **One host means one z-order, so the layers are bands.** Sheets are stamped from 1 by the
+  engine's registry; overlays take `modal` 1000+, `anchored` 2000+, `toast` 3000+. Every overlay
+  draws over every sheet, a popover over the dialog that opened it, a toast over both. Within a
+  band the later open is on top, and a re-open brings an overlay forward. The number is base plus
+  **rank** in the band, never the raw open counter, so a long session cannot walk a dialog into
+  the popover band — a test opens five thousand to prove it. The cost: a sheet opened *from* a
+  dialog draws under it. Do not open a sheet from a dialog.
+- **The registry entry lives exactly as long as `Overlay.Portal` is mounted.** Mount the portal
+  only while `useOverlayPresence().isPresent`, and the registry, the z-order and the back button
+  all follow presence with nothing else to keep in sync.
+- **Back closes only the top overlay.** `useOverlayBackHandler` takes the portal's `id` and
+  subscribes only while that id is `topOverlay` among `modal` and `anchored` — a toast never takes
+  the back button. React Native calls the most recent listener first, and an overlay over a sheet
+  subscribed after it, so the overlay answers first and returns `true`.
+- **Presence is a reducer so an interrupted animation is boring.** A re-open mid-exit goes back
+  to `entering` from wherever `progress` is; a close mid-entrance goes to `exiting`. The finish
+  callback reaches React only when the timing ran to the end, and a stale finish (`entered` while
+  `exiting`) is a no-op in the reducer, so the hook keeps no generation counter.
+- **Overlay motion is behaviour, not decoration.** `isMotionCalm` does not still it — an overlay
+  that did not appear would change what the screen says — but every animation is finite, so an E2E
+  runner's settle wait ends anyway. Under reduce motion the fade still runs (opacity is not
+  motion) and `isReduced` tells the component to drop its transforms. Exit (160 ms) is quicker
+  than entrance (220 ms): a dismissed overlay should get out of the way.
+- **The scrim is `bg-overlay` at opacity 1**, the token carrying its own alpha, for
+  `BottomSheet.Overlay`'s reason. It is React Native's `Pressable`, not this library's: it wants
+  no feedback or haptic, and a Gesture Handler tap there would race a drawer's pan for the touch.
+  It always takes the touch, even with no `onDismiss`, because the app under a non-dismissible
+  dialog must not be pressable. It is hidden from assistive technology; a screen reader user
+  dismisses through the panel's `onAccessibilityEscape` or the back button.
+- **The portal's wrapper is `box-none`.** An overlay with no scrim — a toast, a tooltip — leaves
+  the app under it interactive.
+- **The provider hears every touch that starts beneath it, and claims none.** Its children sit in a
+  `flex: 1` `View` whose `onTouchStart` fans out to `subscribeTouchStart` listeners. `onTouchStart`
+  is a bubbling touch event, not a responder negotiation, so it never stops the touch reaching its
+  target or a Gesture Handler gesture; and React Native bubbles it through the React tree rather
+  than the native one, so a touch inside a teleported overlay arrives too. It exists for Tooltip,
+  whose outside tap must close it *and* still press what it landed on — a full-screen catcher
+  under the panel, Popover's way, would swallow that tap, and nothing but a common ancestor of the
+  whole app can hear a touch on a view the tooltip knows nothing about.
+- **No provider, no teleport.** Without `OverlayProvider` a portal renders inline, in an absolute
+  fill of the nearest positioned ancestor, and warns once in development; it may be clipped. That
+  is a working fallback for a `delacour add` copy in an app that has not mounted the provider yet,
+  not a supported layout.
+- **`DelacourProvider` cannot mount this** — the peer decision in
+  [DelacourProvider](../provider/AGENTS.md): teleport is optional. `apps/playground/src/app/_layout.tsx`
+  is the reference mount.
+
+## Testing
+
+`bun test` reaches the registry, the presence machine, the scrim token and the motion constants.
+The provider, the portal and the hooks are verified on a simulator through every overlay's
+gallery — the foundation has no gallery of its own, the way `DelacourProvider` has none.

package/src/components/overlay/index.ts

@@ -0,0 +1,27 @@
+export { Overlay, OverlayProvider, type OverlayProviderProps } from "./overlay";
+export {
+	OverlayContext,
+	type OverlayContextValue,
+	TeleportProvidedContext,
+	useIsTeleportProvided,
+	useOptionalOverlay,
+} from "./overlay.context";
+export { OVERLAY_MOTION, OVERLAY_SCRIM_TOKEN, type OverlayVariantProps, overlayVariants } from "./overlay.variants";
+export type { OverlayPortalProps } from "./overlay-portal";
+export { isPresent, type PresenceEvent, type PresencePhase, presenceTarget, reducePresence } from "./overlay-presence";
+export {
+	INITIAL_OVERLAY_REGISTRY,
+	isTopOverlay,
+	OVERLAY_LAYER_BASE,
+	OVERLAY_LAYERS,
+	type OverlayLayer,
+	type OverlayRegistryAction,
+	type OverlayRegistryEntry,
+	type OverlayRegistryState,
+	reduceOverlayRegistry,
+	topOverlay,
+	zIndexOfOverlay,
+} from "./overlay-registry";
+export type { OverlayScrimProps } from "./overlay-scrim";
+export { type UseOverlayBackHandlerOptions, useOverlayBackHandler } from "./use-overlay-back-handler";
+export { type OverlayPresence, type UseOverlayPresenceOptions, useOverlayPresence } from "./use-overlay-presence";

package/src/components/overlay/overlay-portal.tsx

@@ -0,0 +1,84 @@
+import { type ReactElement, type ReactNode, useEffect, useId } from "react";
+import { StyleSheet, View } from "react-native";
+import { Portal } from "react-native-teleport";
+import { useOptionalOverlay } from "./overlay.context";
+import { type OverlayLayer, zIndexOfOverlay } from "./overlay-registry";
+
+export type OverlayPortalProps = {
+	/** Which band of the z-order this overlay draws in. */
+	layer: OverlayLayer;
+	children?: ReactNode;
+	/**
+	 * The overlay's registry id. Pass the same id to `useOverlayBackHandler` so
+	 * the back button knows whether this overlay is the top. Defaults to a
+	 * `useId()` of the portal's own.
+	 */
+	id?: string;
+	/** Render where it is written instead of teleporting. Default false. */
+	isInline?: boolean;
+	/** The teleport host. Default `"root"` — the one `OverlayProvider`'s teleport provider fills the app with. */
+	hostName?: string;
+};
+
+let hasWarnedMissingProvider = false;
+
+/**
+ * Draws its children over the whole app, in its layer of the z-order.
+ *
+ * Teleport moves the native view and leaves the React tree where it was, so
+ * every context provided around the overlay's trigger — a theme, a form, a
+ * query client — still reaches what the portal draws.
+ *
+ * The overlay is in the registry for exactly as long as this is mounted, so
+ * mount it only while the overlay is present (`useOverlayPresence`). Its
+ * wrapper is an absolute fill and `box-none`: it takes no touch of its own, so
+ * an overlay with no scrim — a toast, a tooltip — leaves the app under it
+ * interactive.
+ *
+ * Without an `OverlayProvider` above, or with `isInline`, the children render
+ * where they are written, in an absolute fill of the nearest positioned
+ * ancestor — and the missing provider warns once in development.
+ */
+export function OverlayPortal({
+	layer,
+	children,
+	id,
+	isInline = false,
+	hostName = "root",
+}: OverlayPortalProps): ReactElement {
+	const ownId = useId();
+	const overlayId = id ?? ownId;
+	const registry = useOptionalOverlay();
+
+	const present = registry?.present;
+	const dismissed = registry?.dismissed;
+	useEffect(() => {
+		if (present === undefined || dismissed === undefined) return;
+		present(overlayId, layer);
+		return () => dismissed(overlayId);
+	}, [present, dismissed, overlayId, layer]);
+
+	useEffect(() => {
+		if (!__DEV__ || registry !== null || isInline || hasWarnedMissingProvider) return;
+		hasWarnedMissingProvider = true;
+		console.warn(
+			"Overlay.Portal: an overlay rendered with no <OverlayProvider> above it, so it draws inline and may be clipped. Mount OverlayProvider once at the app root."
+		);
+	}, [registry, isInline]);
+
+	const zIndex = registry === null ? 0 : zIndexOfOverlay(registry.state, overlayId);
+	const frame = (
+		<View pointerEvents="box-none" style={[StyleSheet.absoluteFill, { zIndex }]}>
+			{children}
+		</View>
+	);
+
+	if (isInline || registry === null) return frame;
+
+	return (
+		<Portal hostName={hostName} style={[StyleSheet.absoluteFill, { zIndex }]}>
+			{frame}
+		</Portal>
+	);
+}
+OverlayPortal.displayName = "DelacourUI.Overlay.Portal";

package/src/components/overlay/overlay-presence.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import { isPresent, type PresencePhase, presenceTarget, reducePresence } from "./overlay-presence";
+
+describe("reducePresence", () => {
+	const cases: [PresencePhase, Parameters<typeof reducePresence>[1]["type"], PresencePhase][] = [
+		["closed", "open", "entering"],
+		["closed", "close", "closed"],
+		["closed", "entered", "closed"],
+		["closed", "exited", "closed"],
+		["entering", "entered", "open"],
+		["entering", "close", "exiting"],
+		["entering", "open", "entering"],
+		["entering", "exited", "entering"],
+		["open", "close", "exiting"],
+		["open", "open", "open"],
+		["open", "entered", "open"],
+		["exiting", "exited", "closed"],
+		["exiting", "open", "entering"],
+		["exiting", "close", "exiting"],
+		["exiting", "entered", "exiting"],
+	];
+
+	for (const [from, event, to] of cases) {
+		test(`${from} + ${event} → ${to}`, () => {
+			expect(reducePresence(from, { type: event })).toBe(to);
+		});
+	}
+});
+
+describe("isPresent", () => {
+	test("is false only when closed", () => {
+		expect(isPresent("closed")).toBe(false);
+		expect(isPresent("entering")).toBe(true);
+		expect(isPresent("open")).toBe(true);
+		expect(isPresent("exiting")).toBe(true);
+	});
+});
+
+describe("presenceTarget", () => {
+	test("animates toward 1 while entering or open, 0 otherwise", () => {
+		expect(presenceTarget("entering")).toBe(1);
+		expect(presenceTarget("open")).toBe(1);
+		expect(presenceTarget("exiting")).toBe(0);
+		expect(presenceTarget("closed")).toBe(0);
+	});
+});

package/src/components/overlay/overlay-presence.ts

@@ -0,0 +1,49 @@
+/**
+ * Where an overlay is in its life: absent, arriving, shown, or leaving.
+ *
+ * `exiting` is the whole reason this exists — an overlay that unmounted the
+ * moment it closed would have no exit animation to play.
+ */
+export type PresencePhase = "closed" | "entering" | "open" | "exiting";
+
+export type PresenceEvent =
+	/** The owner asked for it to show. */
+	| { type: "open" }
+	/** The owner asked for it to hide. */
+	| { type: "close" }
+	/** The entrance animation finished. */
+	| { type: "entered" }
+	/** The exit animation finished. */
+	| { type: "exited" };
+
+/**
+ * The presence machine as a pure reducer.
+ *
+ * A re-open during the exit reverses into `entering` from wherever the
+ * animation is, and a close during the entrance reverses into `exiting`. A
+ * finish event from an animation that was interrupted — `entered` while
+ * already `exiting` — is stale and changes nothing, so the hook needs no
+ * generation counter to drop it.
+ */
+export function reducePresence(phase: PresencePhase, event: PresenceEvent): PresencePhase {
+	switch (event.type) {
+		case "open":
+			return phase === "closed" || phase === "exiting" ? "entering" : phase;
+		case "close":
+			return phase === "entering" || phase === "open" ? "exiting" : phase;
+		case "entered":
+			return phase === "entering" ? "open" : phase;
+		case "exited":
+			return phase === "exiting" ? "closed" : phase;
+	}
+}
+
+/** Whether the overlay is mounted: every phase but `closed`. */
+export function isPresent(phase: PresencePhase): boolean {
+	return phase !== "closed";
+}
+
+/** The progress value the phase animates toward — 1 shown, 0 hidden. */
+export function presenceTarget(phase: PresencePhase): 0 | 1 {
+	return phase === "entering" || phase === "open" ? 1 : 0;
+}