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

package/src/components/popover/AGENTS.md

@@ -0,0 +1,138 @@
+# Popover
+
+A small panel anchored to the control that opened it, with the screen around it still visible —
+a rename field beside a title, a note on a badge, a short list of options.
+
+`import { Popover, usePopover } from "@delacour/react-native-ui/popover";`
+
+It draws through the overlay foundation, so it needs `OverlayProvider` at the app root and
+`react-native-teleport` installed — see [Overlay](../overlay/AGENTS.md). Without the provider it
+renders inline and may be clipped.
+
+## Anatomy
+
+```tsx
+<Popover isOpen? defaultOpen? onOpenChange? isDismissible?>
+  <Popover.Trigger asChild><Button /></Popover.Trigger>
+  <Popover.Anchor />                       // optional — anchor to this instead of the trigger
+  <Popover.Content placement? align? offset? alignOffset? width? minWidth? maxHeight?
+                   isScrollable? isUnstyled? background? hasScrim? scrimClassName?>
+    <Popover.Arrow />
+    <Popover.Close />
+    <Popover.Title /> <Popover.Description />
+    …
+  </Popover.Content>
+</Popover>
+```
+
+`usePopover()` returns `{ isOpen, setOpen, close, placement }` — `placement` is the side the panel
+actually landed on, after any flip.
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/popover` |
+| `popover.tsx` | `Popover` — open state, the two anchor measures, the context; the `Object.assign` names every part |
+| `popover.context.tsx` | **Leaf.** `PopoverContext`, `usePopover`, and the content context the arrow and title read |
+| `popover.position.ts` | **Leaf, pure, imports nothing.** `resolveAnchoredPosition`, `resolvePopoverWidth`, `resolveEnterTranslate`, `resolveTransformOrigin`, `resolveArrowFrame` and their types |
+| `popover.position.test.ts` | The placement matrix — every placement and align, flip and no-flip, shift at each edge, `maxHeight`, the arrow, RTL, `alignOffset`, widths, motion geometry |
+| `popover.variants.ts` | The slotted `tv()` — `scrim`, `dismissLayer`, `content`, `arrow`, `title`, `description`, `close` — and the numeric constants |
+| `popover.variants.test.ts` | Slots, `isUnstyled`, tokens in both themes, the arrow inset against `--radius` |
+| `use-anchor-measure.ts` | **Leaf.** `useAnchorMeasure` — `measureInWindow` on enable and on window-size change |
+| `use-anchored-content.ts` | **Leaf.** `useAnchoredContent` — the off-screen measure frame, the resolve, presence, the animated style |
+| `popover-arrow.tsx` | **Leaf.** `AnchoredArrow` (placement passed in) and `Popover.Arrow` (placement read from the panel) |
+| `popover-trigger.tsx` | `Popover.Trigger` — `Pressable`, or `asChild` to donate the press; the default anchor |
+| `popover-anchor.tsx` | `Popover.Anchor` — a non-collapsing `View`, or `asChild` |
+| `popover-content.tsx` | `Popover.Content` — the portal, the dismiss layer or scrim, the panel |
+| `popover-title.tsx` | `Popover.Title` — `Text.Label` as a header, the panel's label |
+| `popover-description.tsx` | `Popover.Description` — `Text.Caption` |
+| `popover-close.tsx` | `Popover.Close` — the corner ✕, or `asChild` around a button |
+
+## The anchored leaves — Tooltip imports them
+
+Tooltip, and later Menu, Context Menu and Select, are anchored panels too. They import
+`popover.position.ts`, `use-anchor-measure.ts`, `use-anchored-content.ts` and `popover-arrow.tsx`
+**directly**, never `./popover` or `./index` — package rule 3's leaf exception. **None of the four
+may import `./popover`, `./index` or any part file.** `popover-arrow.tsx` reads
+`popover.context.tsx`, itself a leaf; the other three import only `popover.position.ts`, the
+variants and the overlay foundation. Break that and a Tooltip import closes a cycle Metro serves
+half-initialised.
+
+## Design
+
+- **Placement is a preference, and the rules are a test each.** `resolveAnchoredPosition` keeps
+  the preferred side, and flips to the opposite **only** when the preferred side cannot hold the
+  panel *and* the opposite has more room — a panel that fits nowhere does not ping-pong to a side
+  that is just as bad. Then it aligns along the cross axis, shifts to stay inside
+  `window − safe area − 8pt`, and clamps both axes, so it is never off-screen. `maxHeight` is
+  `min(maxHeight, room on the resolved side)`, which is what keeps a tall panel on screen.
+- **`align` is logical on top and bottom.** Under RTL `start` is the right edge; on a side
+  placement it is always the top. `alignOffset` nudges inward from whichever edge is aligned.
+- **The arrow points at the anchor's centre, not the panel's.** After a shift the panel is no
+  longer centred on its trigger; the arrow still is, clamped `POPOVER_ARROW_INSET` clear of each
+  corner so it never hangs off the curve. The inset is the card radius plus the arrow's
+  half-diagonal, pinned against `tokens.css`'s `--radius` by a test.
+- **The arrow is a square turned 45°, bordered on two edges.** `resolveArrowFrame` turns its
+  bordered corner toward the anchor in each placement, so the two bordered edges are the ones
+  outside the panel and the bare inner half covers the panel's own border where they meet.
+- **Measured in window coordinates, placed by translate.** `measureInWindow` is what makes a
+  trigger inside a `ScrollView`, a bottom sheet or under the header land the panel in the right
+  place — the panel is teleported to a host that fills the window. The panel sits at the window's
+  origin and moves by `translateX/Y`, never `left`/`top`: a translate is not layout, so moving it
+  never re-wraps a content-fit panel and never fires another `onLayout`.
+- **The panel sits inside a positioner, and the safe-span cap is on the positioner.** The
+  positioner is measured, translated and animated, and carries `maxWidth` = the safe span; the
+  panel inside it carries the classes and the resolved width and `maxHeight`. An inline
+  `maxWidth` on the panel itself beat every class, so a caller's `max-w-64` was silently ignored
+  — found on a simulator with the `arrow` demo.
+- **One invisible frame before the entrance.** The panel mounts at opacity 0, reports its size,
+  is resolved, and only then is presence told to open — so the entrance always starts from the
+  right side and the right place. Presence follows `isOpen && position !== null`; the exit does
+  not wait for anything.
+- **The entrance comes from the anchor.** A 6pt slide back toward the anchor and a `0.96 → 1`
+  scale about the arrow (`transformOrigin`), driven by presence's `progress`. Under reduce motion
+  both collapse and only the fade runs. A window-size change — a rotation — re-measures the anchor
+  a frame later and moves the panel there directly, with no animation.
+- **The keyboard is the bottom of the screen.** `useAnchoredContent` tracks keyboard-controller's
+  show/hide events and takes `max(safe bottom, keyboard height)` as the bottom inset, so a field
+  inside the panel flips it above its trigger instead of typing under the keyboard.
+- **Outside taps close, and are swallowed.** Under the panel sits an invisible absolute-fill
+  React Native `Pressable` — or `Overlay.Scrim` with `hasScrim` — that closes on a tap when
+  dismissible. It never passes the tap through: the mobile convention, and the reason a tap
+  outside never presses the button under it. With `isDismissible={false}` it still takes the
+  touch and does nothing, for the scrim's reason.
+- **`width`.** `"trigger"` is the anchor's measured width, `"full"` the safe span, a number as
+  given, each raised to `minWidth` and capped at the safe span; `"content-fit"` (the default)
+  lets the content size itself, with `minWidth` as a floor and the safe span as `maxWidth`.
+- **`isScrollable` wraps the body in a `ScrollView`, and lifts `Popover.Arrow` out of it** —
+  detected by element type — so the arrow is never scrolled or clipped. Without it a body taller
+  than `maxHeight` is cut off.
+- **`isUnstyled` strips the surface, the border, the corner and the padding** of the panel and the
+  arrow's paint, keeping the gap. `background` is drawn absolutely behind the content, for a
+  caller painting their own surface.
+- **Triggers donate the press.** `Popover.Trigger asChild` hands the toggle to the child's
+  `onPress` and composes the measuring ref onto the child's, for `BottomSheet.Trigger`'s reason —
+  so the child must be built on `Pressable`. It reports `accessibilityState.expanded`.
+- **`Popover.Anchor` takes the measuring from the trigger while it is mounted.** The root keeps one
+  `useAnchorMeasure` per candidate and enables only the one in use; the trigger still opens the
+  panel and still takes focus back.
+- **Modal for assistive technology.** The panel is `accessibilityViewIsModal`, `role="dialog"`,
+  labelled by the title's `nativeID`; on entry focus goes to the title (or the panel), on exit back
+  to the trigger, and `onAccessibilityEscape` closes it. Android back closes it while it is the top
+  overlay (`useOverlayBackHandler`).
+- **Draws in the `anchored` band.** Over every sheet and over the dialog it was opened from — the
+  foundation's z-order.
+
+## Out of scope
+
+- A sheet presentation on small screens — compose `BottomSheet` instead.
+- A frosted backdrop — needs `expo-blur`, not a peer.
+- Following an anchor that scrolls while the panel is open — the panel stays where it opened.
+
+## Testing
+
+`bun test` reaches the position resolver and the variants. Everything else — the measure frame,
+the motion, the keyboard, dismissal, focus — is verified on a simulator through
+`apps/playground`'s `/popover` gallery, whose `edge-collision` demo puts triggers in the four
+corners to prove flip and shift.

package/src/components/popover/index.ts

@@ -0,0 +1,48 @@
+export { Popover, type PopoverProps } from "./popover";
+export {
+	PopoverContext,
+	type PopoverContextValue,
+	usePopover,
+} from "./popover.context";
+export {
+	type AnchoredBounds,
+	type AnchoredInput,
+	type AnchoredInsets,
+	type AnchoredPosition,
+	type AnchoredSize,
+	type AnchorRect,
+	type PopoverAlign,
+	type PopoverPlacement,
+	type PopoverWidth,
+	type ResolvedPopoverWidth,
+	resolveAnchoredPosition,
+	resolveArrowFrame,
+	resolveEnterTranslate,
+	resolvePopoverWidth,
+	resolveTransformOrigin,
+} from "./popover.position";
+export {
+	POPOVER_ARROW_INSET,
+	POPOVER_ARROW_SIZE,
+	POPOVER_CLOSE_HIT_SLOP,
+	POPOVER_COLLISION_PADDING,
+	POPOVER_DEFAULTS,
+	POPOVER_ENTER_DISTANCE,
+	POPOVER_ENTER_SCALE,
+	type PopoverVariantProps,
+	popoverVariants,
+} from "./popover.variants";
+export type { PopoverAnchorProps } from "./popover-anchor";
+export type { AnchoredArrowProps, PopoverArrowProps } from "./popover-arrow";
+export type { PopoverCloseProps } from "./popover-close";
+export type { PopoverContentProps } from "./popover-content";
+export type { PopoverDescriptionProps } from "./popover-description";
+export type { PopoverTitleProps } from "./popover-title";
+export type { PopoverTriggerProps } from "./popover-trigger";
+export {
+	type AnchorMeasure,
+	type MeasurableNode,
+	type UseAnchorMeasureOptions,
+	useAnchorMeasure,
+} from "./use-anchor-measure";
+export { type AnchoredContent, type UseAnchoredContentOptions, useAnchoredContent } from "./use-anchored-content";

package/src/components/popover/popover-anchor.tsx

@@ -0,0 +1,49 @@
+import { type ReactElement, useEffect } from "react";
+import { View, type ViewProps } from "react-native";
+import { Slot } from "../../lib/slot";
+import { usePopoverContext } from "./popover.context";
+
+export type PopoverAnchorProps = ViewProps & {
+	className?: string;
+	/** Anchor to the single child itself rather than a wrapping view. */
+	asChild?: boolean;
+};
+
+/**
+ * Anchors the panel to a different view than the trigger — a whole row whose
+ * trailing button opens it, a field whose icon does.
+ *
+ * While it is mounted the panel measures this instead of the trigger; the
+ * trigger still opens it and still takes focus back on close. Without
+ * `asChild` it is a plain `View` that never collapses, so it always has a
+ * native frame to measure.
+ *
+ * @example
+ * <Popover>
+ *   <Popover.Anchor className="flex-row items-center gap-2">
+ *     <Input value={tag} />
+ *     <Popover.Trigger asChild><Button size="icon-md" variant="ghost">…</Button></Popover.Trigger>
+ *   </Popover.Anchor>
+ *   <Popover.Content width="trigger">…</Popover.Content>
+ * </Popover>
+ */
+export function PopoverAnchor({ asChild = false, children, ...props }: PopoverAnchorProps): ReactElement {
+	const { anchorRef, registerAnchor } = usePopoverContext();
+
+	useEffect(() => registerAnchor(), [registerAnchor]);
+
+	if (asChild) {
+		return (
+			<Slot {...props} ref={anchorRef}>
+				{children}
+			</Slot>
+		);
+	}
+
+	return (
+		<View collapsable={false} {...props} ref={anchorRef}>
+			{children}
+		</View>
+	);
+}
+PopoverAnchor.displayName = "DelacourUI.Popover.Anchor";

package/src/components/popover/popover-arrow.tsx

@@ -0,0 +1,89 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { useOptionalPopoverContent } from "./popover.context";
+import { type AnchoredSize, type PopoverPlacement, resolveArrowFrame } from "./popover.position";
+import { POPOVER_ARROW_SIZE, popoverVariants } from "./popover.variants";
+
+export type AnchoredArrowProps = {
+	/** The side the panel was placed on — the arrow sits on the edge facing the anchor. */
+	placement: PopoverPlacement;
+	/** From `resolveAnchoredPosition`: along that edge, toward the anchor's centre. */
+	arrowOffset: number;
+	/** The panel's measured size. */
+	size: AnchoredSize;
+	/** Strips the arrow's fill and border, for a panel drawn with its own `background`. */
+	isUnstyled?: boolean;
+	className?: string;
+};
+
+/**
+ * A square turned 45°, half of it past the panel's edge, pointing at the anchor.
+ *
+ * It wears the panel's fill and the panel's border on its two outer edges, and
+ * its inner half lies over the panel — covering the panel's own border where
+ * the two meet, so the arrow reads as part of the panel rather than a tab stuck
+ * to it. `resolveArrowFrame` turns it per placement.
+ *
+ * Hidden from assistive technology: it is decoration.
+ *
+ * **A leaf.** Tooltip imports it with its own placement; it imports nothing
+ * from `./popover` or `./index`.
+ */
+export function AnchoredArrow({
+	placement,
+	arrowOffset,
+	size,
+	isUnstyled = false,
+	className,
+}: AnchoredArrowProps): ReactElement {
+	const frame = resolveArrowFrame(placement, arrowOffset, size, POPOVER_ARROW_SIZE);
+
+	return (
+		<View
+			accessibilityElementsHidden
+			accessible={false}
+			className={popoverVariants({ isUnstyled }).arrow({ className })}
+			importantForAccessibility="no-hide-descendants"
+			pointerEvents="none"
+			style={{
+				left: frame.left,
+				top: frame.top,
+				width: POPOVER_ARROW_SIZE,
+				height: POPOVER_ARROW_SIZE,
+				transform: [{ rotate: `${frame.rotate}deg` }],
+			}}
+		/>
+	);
+}
+AnchoredArrow.displayName = "DelacourUI.Popover.AnchoredArrow";
+
+export type PopoverArrowProps = {
+	className?: string;
+};
+
+/**
+ * The panel's arrow. Write it anywhere inside `Popover.Content` — it reads the
+ * resolved placement and offset from the panel, follows a flip, and is lifted
+ * out of a scrollable body so it is never scrolled or clipped.
+ *
+ * @example
+ * <Popover.Content>
+ *   <Popover.Arrow />
+ *   <Popover.Title>Rename</Popover.Title>
+ * </Popover.Content>
+ */
+export function PopoverArrow({ className }: PopoverArrowProps): ReactElement | null {
+	const content = useOptionalPopoverContent();
+	if (content === null) return null;
+
+	return (
+		<AnchoredArrow
+			arrowOffset={content.arrowOffset}
+			className={className}
+			isUnstyled={content.isUnstyled}
+			placement={content.placement}
+			size={content.size}
+		/>
+	);
+}
+PopoverArrow.displayName = "DelacourUI.Popover.Arrow";

package/src/components/popover/popover-close.tsx

@@ -0,0 +1,73 @@
+import type { ReactElement } from "react";
+import { IconCrossSmall } from "../../icons/central";
+import { Slot } from "../../lib/slot";
+import { Icon } from "../icon";
+import { Pressable, type PressableProps } from "../pressable";
+import { usePopoverContext } from "./popover.context";
+import { POPOVER_CLOSE_HIT_SLOP, popoverVariants } from "./popover.variants";
+
+export type PopoverCloseProps =
+	| ({ asChild: true; children: ReactElement } & Omit<PressableProps, "asChild" | "children">)
+	| ({ asChild?: false; accessibilityLabel?: string } & Omit<PressableProps, "asChild" | "children">);
+
+/**
+ * Closes the popover.
+ *
+ * Without `asChild` it is the ✕ in the panel's top-right corner: out of the
+ * flow, `fade` feedback and an 8pt slop for `BottomSheet.Close`'s reasons, and
+ * `Popover.Title` reserves its clearance. With `asChild` it donates the close to
+ * its child's `onPress` — a "Done" button in the panel's footer.
+ *
+ * @example
+ * <Popover.Close />
+ *
+ * @example
+ * <Popover.Close asChild>
+ *   <Button size="sm">Save</Button>
+ * </Popover.Close>
+ */
+export function PopoverClose(props: PopoverCloseProps): ReactElement {
+	const { close } = usePopoverContext();
+
+	if (props.asChild) {
+		const { asChild: _asChild, children, onPress, ...rest } = props;
+		const press = () => {
+			close();
+			onPress?.();
+		};
+		return (
+			<Slot {...rest} onPress={press}>
+				{children}
+			</Slot>
+		);
+	}
+
+	const {
+		asChild: _asChild,
+		accessibilityLabel = "Close",
+		className,
+		feedback = "fade",
+		hitSlop = POPOVER_CLOSE_HIT_SLOP,
+		onPress,
+		...rest
+	} = props;
+	const press = () => {
+		close();
+		onPress?.();
+	};
+
+	return (
+		<Pressable
+			accessibilityLabel={accessibilityLabel}
+			accessibilityRole="button"
+			className={popoverVariants().close({ className })}
+			feedback={feedback}
+			hitSlop={hitSlop}
+			onPress={press}
+			{...rest}
+		>
+			<Icon color="muted-foreground" icon={IconCrossSmall} />
+		</Pressable>
+	);
+}
+PopoverClose.displayName = "DelacourUI.Popover.Close";

package/src/components/popover/popover-content.tsx

@@ -0,0 +1,235 @@
+import {
+	Children,
+	isValidElement,
+	type ReactElement,
+	type ReactNode,
+	useCallback,
+	useEffect,
+	useId,
+	useMemo,
+	useRef,
+} from "react";
+import { AccessibilityInfo, Pressable as NativePressable, ScrollView, View, type ViewProps } from "react-native";
+import Animated from "react-native-reanimated";
+import { Overlay, useOverlayBackHandler } from "../overlay";
+import { PopoverContentContext, type PopoverContentContextValue, usePopoverContext } from "./popover.context";
+import type { PopoverAlign, PopoverPlacement, PopoverWidth } from "./popover.position";
+import {
+	POPOVER_ARROW_INSET,
+	POPOVER_COLLISION_PADDING,
+	POPOVER_DEFAULTS,
+	POPOVER_ENTER_DISTANCE,
+	POPOVER_ENTER_SCALE,
+	popoverVariants,
+} from "./popover.variants";
+import { PopoverArrow } from "./popover-arrow";
+import type { MeasurableNode } from "./use-anchor-measure";
+import { useAnchoredContent } from "./use-anchored-content";
+
+export type PopoverContentProps = ViewProps & {
+	className?: string;
+	/** The side of the anchor the panel prefers. It flips when that side lacks room. Default `"bottom"`. */
+	placement?: PopoverPlacement;
+	/** Which edges line up along the cross axis; logical under RTL. Default `"center"`. */
+	align?: PopoverAlign;
+	/** The gap between anchor and panel, in points. Default 8. */
+	offset?: number;
+	/** A nudge along the cross axis, inward from the aligned edge. Default 0. */
+	alignOffset?: number;
+	/** A number, the anchor's width, the content's own, or the safe span. Default `"content-fit"`. */
+	width?: PopoverWidth;
+	minWidth?: number;
+	/** Clamped to the room on the resolved side. */
+	maxHeight?: number;
+	/** Scroll the body when it is taller than `maxHeight`. Default false. */
+	isScrollable?: boolean;
+	/** No surface, border, corner or padding — draw your own with `background`. */
+	isUnstyled?: boolean;
+	/** Drawn behind the content, filling the panel. */
+	background?: ReactNode;
+	/** Dim the app behind the panel. Default false — an outside tap still closes it. */
+	hasScrim?: boolean;
+	scrimClassName?: string;
+};
+
+/** Pulls `Popover.Arrow` out of the body, so a scrolling body never scrolls or clips it. */
+function partitionArrow(children: ReactNode): { arrows: ReactNode[]; body: ReactNode[] } {
+	const arrows: ReactNode[] = [];
+	const body: ReactNode[] = [];
+	Children.forEach(children, (child) => {
+		if (isValidElement(child) && child.type === PopoverArrow) arrows.push(child);
+		else body.push(child);
+	});
+	return { arrows, body };
+}
+
+/**
+ * The panel, drawn over the app and anchored to the trigger.
+ *
+ * Renders nothing while closed. On open it mounts in the `anchored` band of
+ * the overlay z-order — above every sheet and dialog — measures itself
+ * invisibly, resolves where it fits, and enters from its resolved side. The
+ * placement is a preference: the panel flips across the anchor when that side
+ * lacks room and slides along it to stay inside the safe area and above the
+ * keyboard.
+ *
+ * Under the panel, an invisible layer the size of the screen — or the scrim,
+ * with `hasScrim` — closes the popover on a tap when it is dismissible. It
+ * swallows the tap rather than passing it through to what is under it. Android
+ * back closes it while it is the top overlay.
+ *
+ * The panel is a modal view labelled by its title: VoiceOver focus is held
+ * inside it, moves to the title (or the panel) on entry and back to the
+ * trigger on exit, and the escape gesture closes it.
+ *
+ * @example
+ * <Popover.Content align="start" width="trigger" minWidth={260}>
+ *   <Popover.Arrow />
+ *   <Popover.Title>Rename</Popover.Title>
+ *   <Input value={name} onChangeText={setName} />
+ * </Popover.Content>
+ */
+export function PopoverContent({
+	children,
+	className,
+	placement = POPOVER_DEFAULTS.placement,
+	align = POPOVER_DEFAULTS.align,
+	offset = POPOVER_DEFAULTS.offset,
+	alignOffset = POPOVER_DEFAULTS.alignOffset,
+	width = POPOVER_DEFAULTS.width,
+	minWidth,
+	maxHeight,
+	isScrollable = false,
+	isUnstyled = false,
+	background,
+	hasScrim = false,
+	scrimClassName,
+	style,
+	...props
+}: PopoverContentProps): ReactElement | null {
+	const { isOpen, close, isDismissible, anchorRect, triggerNode, onPlaced } = usePopoverContext();
+	const overlayId = useId();
+	const titleId = useId();
+	const panelNode = useRef<MeasurableNode | null>(null);
+	const titleNode = useRef<MeasurableNode | null>(null);
+
+	const focusIn = useCallback(() => {
+		const target = titleNode.current ?? panelNode.current;
+		if (target !== null) AccessibilityInfo.sendAccessibilityEvent(target, "focus");
+	}, []);
+
+	const focusBack = useCallback(() => {
+		if (triggerNode.current !== null) AccessibilityInfo.sendAccessibilityEvent(triggerNode.current, "focus");
+	}, [triggerNode]);
+
+	const anchored = useAnchoredContent({
+		isOpen,
+		anchor: anchorRect,
+		placement,
+		align,
+		offset,
+		alignOffset,
+		collisionPadding: POPOVER_COLLISION_PADDING,
+		arrowInset: POPOVER_ARROW_INSET,
+		width,
+		minWidth,
+		maxHeight,
+		enterDistance: POPOVER_ENTER_DISTANCE,
+		enterScale: POPOVER_ENTER_SCALE,
+		onEntered: focusIn,
+		onExited: focusBack,
+	});
+
+	const resolvedPlacement = anchored.position?.placement ?? placement;
+	useEffect(() => onPlaced(resolvedPlacement), [onPlaced, resolvedPlacement]);
+
+	const dismiss = useCallback(() => {
+		if (isDismissible) close();
+	}, [isDismissible, close]);
+
+	useOverlayBackHandler({ id: overlayId, isEnabled: anchored.isMounted && isDismissible, onBack: close });
+
+	const titleRef = useCallback((node: MeasurableNode | null) => {
+		titleNode.current = node;
+	}, []);
+	const panelRef = useCallback((node: MeasurableNode | null) => {
+		panelNode.current = node;
+	}, []);
+
+	const contentContext = useMemo<PopoverContentContextValue>(
+		() => ({
+			placement: resolvedPlacement,
+			arrowOffset: anchored.position?.arrowOffset ?? 0,
+			size: anchored.size ?? { width: 0, height: 0 },
+			isUnstyled,
+			titleId,
+			titleRef,
+		}),
+		[resolvedPlacement, anchored.position?.arrowOffset, anchored.size, isUnstyled, titleId, titleRef]
+	);
+
+	if (!anchored.isMounted) return null;
+
+	const slots = popoverVariants({ isUnstyled });
+	const { arrows, body } = partitionArrow(children);
+
+	// The catcher is written before the panel, so view order gives a touch on
+	// the panel to the panel; it is React Native's own Pressable for the scrim's
+	// reason — no feedback, no haptic, no gesture to race.
+	return (
+		<Overlay.Portal id={overlayId} layer="anchored">
+			{hasScrim ? (
+				<Overlay.Scrim
+					className={slots.scrim({ className: scrimClassName })}
+					onDismiss={dismiss}
+					progress={anchored.presence.progress}
+				/>
+			) : (
+				<NativePressable
+					accessibilityElementsHidden
+					accessible={false}
+					className={slots.dismissLayer()}
+					importantForAccessibility="no-hide-descendants"
+					onPress={dismiss}
+				/>
+			)}
+			<Animated.View
+				onLayout={anchored.onLayout}
+				pointerEvents="box-none"
+				style={[anchored.positionerStyle, anchored.animatedStyle]}
+			>
+				<View
+					accessibilityLabelledBy={titleId}
+					accessibilityViewIsModal
+					className={slots.content({ className })}
+					onAccessibilityEscape={isDismissible ? close : undefined}
+					ref={panelRef}
+					role="dialog"
+					style={[anchored.frameStyle, style]}
+					{...props}
+				>
+					<PopoverContentContext.Provider value={contentContext}>
+						{background === undefined ? null : (
+							<View className="absolute inset-0" pointerEvents="none">
+								{background}
+							</View>
+						)}
+						{isScrollable ? (
+							<ScrollView
+								className="shrink grow-0"
+								contentContainerClassName="gap-2"
+								keyboardShouldPersistTaps="handled"
+							>
+								{body}
+							</ScrollView>
+						) : (
+							body
+						)}
+						{arrows}
+					</PopoverContentContext.Provider>
+				</View>
+			</Animated.View>
+		</Overlay.Portal>
+	);
+}
+PopoverContent.displayName = "DelacourUI.Popover.Content";

package/src/components/popover/popover-description.tsx

@@ -0,0 +1,18 @@
+import type { ReactElement } from "react";
+import { Text, type TextPresetProps } from "../text";
+import { popoverVariants } from "./popover.variants";
+
+export type PopoverDescriptionProps = TextPresetProps;
+
+/**
+ * Supporting copy under the title — a `Text.Caption`, so it sits on the muted
+ * token at the label's size and reads as the title's explanation rather than a
+ * second heading.
+ *
+ * @example
+ * <Popover.Description>Shown to everyone in the workspace.</Popover.Description>
+ */
+export function PopoverDescription({ className, ...props }: PopoverDescriptionProps): ReactElement {
+	return <Text.Caption className={popoverVariants().description({ className })} {...props} />;
+}
+PopoverDescription.displayName = "DelacourUI.Popover.Description";

package/src/components/popover/popover-title.tsx

@@ -0,0 +1,33 @@
+import type { ReactElement } from "react";
+import { Text, type TextPresetProps } from "../text";
+import { useOptionalPopoverContent } from "./popover.context";
+import { popoverVariants } from "./popover.variants";
+
+export type PopoverTitleProps = TextPresetProps;
+
+/**
+ * The panel's heading.
+ *
+ * *Is* a `Text.Label`, announced as a header — a popover is a small panel, and a
+ * section heading's 20pt would outweigh the trigger it hangs from. The slot adds
+ * clearance for `Popover.Close` and no type of its own. It carries the
+ * `nativeID` the panel is labelled by, and accessibility focus lands on it when
+ * the panel opens.
+ *
+ * @example
+ * <Popover.Title>Rename</Popover.Title>
+ */
+export function PopoverTitle({ className, ...props }: PopoverTitleProps): ReactElement {
+	const content = useOptionalPopoverContent();
+
+	return (
+		<Text.Label
+			accessibilityRole="header"
+			className={popoverVariants().title({ className })}
+			nativeID={content?.titleId}
+			ref={content?.titleRef}
+			{...props}
+		/>
+	);
+}
+PopoverTitle.displayName = "DelacourUI.Popover.Title";