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

package/src/components/tooltip/AGENTS.md

@@ -0,0 +1,133 @@
+# Tooltip
+
+A short label naming the control under the finger — what an icon-only button does, a shortcut, a
+one-line hint. It is not interactive: anything with a button in it is a [Popover](../popover/AGENTS.md).
+
+`import { Tooltip } from "@delacour/react-native-ui/tooltip";`
+
+It draws through the overlay foundation, so it needs `OverlayProvider` at the app root and
+`react-native-teleport` installed — see [Overlay](../overlay/AGENTS.md). The provider is also what
+hears an outside tap; without it the tooltip renders inline, may be clipped, and closes only on its
+timer or the trigger.
+
+## Anatomy
+
+```tsx
+<Tooltip isOpen? defaultOpen? onOpenChange? openOn? duration? label?>
+  <Tooltip.Trigger asChild><Button size="icon-md" variant="ghost" /></Tooltip.Trigger>
+  <Tooltip.Content placement? align? offset? alignOffset? variant? width? minWidth? maxHeight? isScrollable?>
+    <Tooltip.Arrow />
+    <Tooltip.Text />                         // inverted: the one line
+    <Tooltip.Title /> <Tooltip.Description /> // surface: a heading and a line
+  </Tooltip.Content>
+</Tooltip>
+```
+
+`useTooltip()` returns `{ isOpen, setOpen, close }`.
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/tooltip` |
+| `tooltip.tsx` | `Tooltip` — open state, the screen-reader check, activation, the outside-tap subscription, the one-open-at-a-time rule; the `Object.assign` names every part |
+| `tooltip.context.tsx` | **Leaf.** `TooltipContext`, `useTooltip`, and the content context the arrow and text read |
+| `tooltip.variants.ts` | The slotted `tv()` — `content`, `arrow`, `text`, `title`, `description` per variant — the defaults, and the pure `resolveTooltipDuration`, `shouldTooltipActivate`, `resolveTooltipAccessibility`, `readableTextOf` |
+| `tooltip.variants.test.ts` | Both variants and their tokens in both themes, the three resolvers, the defaults |
+| `tooltip-trigger.tsx` | `Tooltip.Trigger` — `Pressable`, or `asChild` to donate the long press or the press; the anchor; the label or hint |
+| `tooltip-content.tsx` | `Tooltip.Content` — the portal, the panel, the timer |
+| `tooltip-arrow.tsx` | `Tooltip.Arrow` — Popover's `AnchoredArrow` in the variant's paint |
+| `tooltip-text.tsx` | `Tooltip.Text` — `Text.Caption`, inked for the variant |
+| `tooltip-title.tsx` | `Tooltip.Title` — `Text.Label`, for the surface variant |
+| `tooltip-description.tsx` | `Tooltip.Description` — `Text.Caption`, for the surface variant |
+
+## Builds on Popover's leaves
+
+`popover/popover.position.ts`, `popover/use-anchor-measure.ts`, `popover/use-anchored-content.ts`,
+`popover/popover-arrow.tsx` and `popover/popover.variants.ts` are imported **directly**, never
+`../popover` — package rule 3's leaf exception, written down in Popover's own doc. So the tooltip
+measures, flips, shifts, clamps and aims its arrow exactly as a popover does, and none of it is
+re-tested here. It keeps Popover's collision padding and arrow inset; the inset is sized for the
+card corner, which is larger than the inverted chip's `rounded-md`, so it clears both.
+
+## Design
+
+- **A long press opens it, so the control keeps its tap.** Mobile has no hover. A tooltip that
+  opened on a tap would take the tap from the button it names, so the default `openOn` is
+  `"longPress"`, with a `selection` haptic — fired from the UI thread through `playHaptic`, because
+  `Pressable`'s `haptic` plays on press-in, which is every tap. The trigger's own `onLongPress`
+  still runs, after the tooltip's. A tap shorter than the long-press delay still presses the
+  button; one held past it fails as a tap, so a long press never also presses it. `openOn="press"`
+  is for a trigger with no tap of its own — an info glyph.
+- **`asChild` donates the gesture.** For `Popover.Trigger`'s reason: a `Button` inside a pressable
+  trigger would win the touch and the tooltip would never open. The trigger hands its handler to
+  the child as `onLongPress` or `onPress`, chained ahead of the child's own by `mergeProps`, and
+  composes the measuring ref onto the child's — so the child has to be built on `Pressable`.
+- **An outside tap closes it and still lands.** Popover swallows an outside tap behind an invisible
+  catcher, which is right for a panel with things to press in it and wrong for a label: a tooltip
+  in the way of the next tap would make the app feel stuck. So there is no catcher. The panel is
+  `pointerEvents="none"` — a tap on it falls through too — and the tooltip subscribes, while open,
+  to `OverlayProvider`'s `subscribeTouchStart`, which hears every touch starting anywhere beneath
+  the provider without claiming it, and closes. Only the provider can do this: nothing else is an
+  ancestor of a view the tooltip knows nothing about. See [Overlay](../overlay/AGENTS.md).
+- **The trigger again closes it, and that rides on bubbling order.** A touch on the trigger reaches
+  the trigger's `onTouchStart` before it bubbles to the provider, so the trigger records whether
+  the tooltip was open when this touch began; then the provider closes it; then the long press or
+  press arrives and, seeing it was open, leaves it closed rather than re-opening what the touch
+  just shut. In long-press mode a plain tap on the trigger closes it too — the user has moved on to
+  the button.
+- **It hides itself.** `duration` ms (1500 by default) after the entrance settles, so a slow
+  entrance never eats into the time the words are on screen. `0` keeps it until an outside tap or
+  the trigger. A negative or non-finite duration is a mistake, not a request to vanish, and takes
+  the default (`resolveTooltipDuration`).
+- **One at a time.** A module-level slot holds the open tooltip's id and close; opening another
+  closes it. Two labels pointing at two controls at once say nothing about either.
+- **`inverted` is the default look.** The foreground colour as the fill and the background colour
+  as the ink reads over anything in either theme, which is what a label floating over arbitrary
+  content needs; a compact `rounded-md` chip sized for one caption-sized line. `surface` is the
+  popover card — fill, hairline, card corner — with room for `Tooltip.Title` over
+  `Tooltip.Description`. The text parts read the variant from the panel, so neither needs a class
+  at the call site.
+- **The arrow is Popover's, repainted.** `AnchoredArrow` with `isUnstyled`, so Popover's paint is
+  stripped and the variant's `arrow` slot is all there is: fill alone on the borderless chip, fill
+  plus the border on its two outer edges on the card.
+- **Motion is a fade and 4pt.** From `useAnchoredContent`: an invisible measure frame, then a fade
+  and a 4pt slide from the resolved side, with no scale — a label appears, it does not grow.
+  Under reduce motion only the fade runs.
+
+## Accessibility
+
+- **The trigger carries the words.** `resolveTooltipAccessibility`: `label` becomes the trigger's
+  `accessibilityLabel` when it has none — an icon button — or its `accessibilityHint` when it does;
+  a label identical to the trigger's is dropped rather than read twice. An `asChild` trigger's
+  label is read off the child's props, and visible text counts as a label (`readableTextOf`): a
+  `<Button>Sync now</Button>` is already named, and an early build replaced "Sync now" with the
+  tooltip's words — found on a simulator with the `surface` demo. So VoiceOver says the tooltip's words without anything
+  opening.
+- **The panel is never read and never takes focus.** `accessibilityElementsHidden` and
+  `importantForAccessibility="no-hide-descendants"` on the positioner; non-modal overlays never move
+  focus (the overlay plan's rule). Reading it as well would say everything twice.
+- **With a screen reader on, a long press does not open it** (`shouldTooltipActivate`) — the words
+  already reached the trigger, and double-tap-and-hold is an action. A press tooltip still opens,
+  for someone using zoom alongside VoiceOver, and then never times out
+  (`resolveTooltipDuration`): they read at their own pace.
+- **Android back closes it** while it is the top overlay, so a tooltip opened over a popover does
+  not leave back doing nothing.
+
+## Out of scope
+
+- Following a trigger that scrolls while open — the panel stays where it opened, as Popover's does,
+  and the timer clears it soon after.
+- Interactive content. A button in a tooltip cannot be pressed; that is a `Popover`.
+
+## Testing
+
+`bun test` reaches the variants and the three resolvers. Positioning is Popover's and tested there.
+Everything else — the long press and its haptic, the button's tap surviving it, the timer, an
+outside tap closing it and still landing, one-at-a-time, VoiceOver reading `label` — is verified on
+a simulator through `apps/playground`'s `/tooltip` gallery.
+
+Preview media is not captured yet (see the overlay plan); the flows are in
+`.argent/flows/previews/tooltip/`. When a capture tool is back, mark these `capture`:
+`icon-buttons` `{ flow: "tooltip/icon-buttons", frame: "device", hero: true }`, and `press`,
+`placements`, `surface` `{ flow: "tooltip/<id>", frame: "device" }`.

package/src/components/tooltip/index.ts

@@ -0,0 +1,28 @@
+export { Tooltip, type TooltipProps } from "./tooltip";
+export {
+	TooltipContext,
+	type TooltipContextValue,
+	useTooltip,
+} from "./tooltip.context";
+export {
+	readableTextOf,
+	resolveTooltipAccessibility,
+	resolveTooltipDuration,
+	shouldTooltipActivate,
+	TOOLTIP_DEFAULTS,
+	TOOLTIP_DURATION,
+	TOOLTIP_ENTER_DISTANCE,
+	TOOLTIP_VARIANTS,
+	type TooltipAccessibility,
+	type TooltipGesture,
+	type TooltipOpenOn,
+	type TooltipVariant,
+	type TooltipVariantProps,
+	tooltipVariants,
+} from "./tooltip.variants";
+export type { TooltipArrowProps } from "./tooltip-arrow";
+export type { TooltipContentProps } from "./tooltip-content";
+export type { TooltipDescriptionProps } from "./tooltip-description";
+export type { TooltipTextProps } from "./tooltip-text";
+export type { TooltipTitleProps } from "./tooltip-title";
+export type { TooltipTriggerProps } from "./tooltip-trigger";

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

@@ -0,0 +1,40 @@
+import type { ReactElement } from "react";
+import { AnchoredArrow } from "../popover/popover-arrow";
+import { useOptionalTooltipContent } from "./tooltip.context";
+import { tooltipVariants } from "./tooltip.variants";
+
+export type TooltipArrowProps = {
+	className?: string;
+};
+
+/**
+ * The panel's arrow — Popover's `AnchoredArrow`, wearing the tooltip's paint.
+ *
+ * Write it anywhere inside `Tooltip.Content`: it reads the resolved placement
+ * and offset from the panel, follows a flip, points at the trigger's centre
+ * even after the panel shifted along an edge, and is lifted out of a
+ * scrollable body. Popover's own paint is stripped and the variant's slot
+ * supplies it, so an inverted chip's arrow is the foreground fill with no
+ * border and a surface card's is the popover fill with its hairline.
+ *
+ * @example
+ * <Tooltip.Content>
+ *   <Tooltip.Arrow />
+ *   <Tooltip.Text>Share</Tooltip.Text>
+ * </Tooltip.Content>
+ */
+export function TooltipArrow({ className }: TooltipArrowProps): ReactElement | null {
+	const content = useOptionalTooltipContent();
+	if (content === null) return null;
+
+	return (
+		<AnchoredArrow
+			arrowOffset={content.arrowOffset}
+			className={tooltipVariants({ variant: content.variant }).arrow({ className })}
+			isUnstyled
+			placement={content.placement}
+			size={content.size}
+		/>
+	);
+}
+TooltipArrow.displayName = "DelacourUI.Tooltip.Arrow";

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

@@ -0,0 +1,179 @@
+import {
+	Children,
+	isValidElement,
+	type ReactElement,
+	type ReactNode,
+	useCallback,
+	useEffect,
+	useId,
+	useMemo,
+	useRef,
+} from "react";
+import { ScrollView, View, type ViewProps } from "react-native";
+import Animated from "react-native-reanimated";
+import { Overlay, useOverlayBackHandler } from "../overlay";
+import type { PopoverAlign, PopoverPlacement, PopoverWidth } from "../popover/popover.position";
+import { POPOVER_ARROW_INSET, POPOVER_COLLISION_PADDING } from "../popover/popover.variants";
+import { useAnchoredContent } from "../popover/use-anchored-content";
+import { TooltipContentContext, type TooltipContentContextValue, useTooltipContext } from "./tooltip.context";
+import { TOOLTIP_DEFAULTS, TOOLTIP_ENTER_DISTANCE, type TooltipVariant, tooltipVariants } from "./tooltip.variants";
+import { TooltipArrow } from "./tooltip-arrow";
+
+export type TooltipContentProps = ViewProps & {
+	className?: string;
+	/** The side of the trigger the panel prefers. It flips when that side lacks room. Default `"top"`. */
+	placement?: PopoverPlacement;
+	/** Which edges line up along the cross axis; logical under RTL. Default `"center"`. */
+	align?: PopoverAlign;
+	/** The gap between trigger and panel, in points. Default 6. */
+	offset?: number;
+	/** A nudge along the cross axis, inward from the aligned edge. Default 0. */
+	alignOffset?: number;
+	/** `"inverted"` — a dark chip for one line; `"surface"` — a popover card for a title and a description. Default `"inverted"`. */
+	variant?: TooltipVariant;
+	/** A number, the trigger'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` — the one case the panel takes a touch. Default false. */
+	isScrollable?: boolean;
+};
+
+/** Pulls `Tooltip.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 === TooltipArrow) 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, measures itself invisibly, resolves where it fits —
+ * Popover's resolver, so it flips and shifts the same way — and fades in from
+ * 4pt toward its resolved side; under reduce motion it only fades. `duration`
+ * ms after that entrance settles it hides itself.
+ *
+ * It takes no touch: there is no catcher under it and the panel is
+ * `pointerEvents="none"`, so a tap anywhere — the panel included — reaches
+ * what is under it, and the provider closes the tooltip on the way. Only an
+ * `isScrollable` body takes a touch, to scroll. It is hidden from assistive
+ * technology and never takes focus: its words already reached the trigger.
+ * Android back closes it while it is the top overlay.
+ *
+ * @example
+ * <Tooltip.Content placement="bottom">
+ *   <Tooltip.Arrow />
+ *   <Tooltip.Text>Copy link</Tooltip.Text>
+ * </Tooltip.Content>
+ */
+export function TooltipContent({
+	children,
+	className,
+	placement = TOOLTIP_DEFAULTS.placement,
+	align = TOOLTIP_DEFAULTS.align,
+	offset = TOOLTIP_DEFAULTS.offset,
+	alignOffset = TOOLTIP_DEFAULTS.alignOffset,
+	variant = TOOLTIP_DEFAULTS.variant,
+	width = TOOLTIP_DEFAULTS.width,
+	minWidth,
+	maxHeight,
+	isScrollable = false,
+	style,
+	onTouchStart,
+	...props
+}: TooltipContentProps): ReactElement | null {
+	const { isOpen, close, duration, anchorRect, onContentTouchStart } = useTooltipContext();
+	const overlayId = useId();
+	const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+	const clearTimer = useCallback(() => {
+		if (timer.current === null) return;
+		clearTimeout(timer.current);
+		timer.current = null;
+	}, []);
+
+	const startTimer = useCallback(() => {
+		clearTimer();
+		if (duration > 0) timer.current = setTimeout(close, duration);
+	}, [clearTimer, close, duration]);
+
+	useEffect(() => {
+		if (!isOpen) clearTimer();
+	}, [isOpen, clearTimer]);
+	useEffect(() => clearTimer, [clearTimer]);
+
+	const anchored = useAnchoredContent({
+		isOpen,
+		anchor: anchorRect,
+		placement,
+		align,
+		offset,
+		alignOffset,
+		collisionPadding: POPOVER_COLLISION_PADDING,
+		arrowInset: POPOVER_ARROW_INSET,
+		width,
+		minWidth,
+		maxHeight,
+		enterDistance: TOOLTIP_ENTER_DISTANCE,
+		enterScale: 1,
+		onEntered: startTimer,
+	});
+
+	useOverlayBackHandler({ id: overlayId, isEnabled: anchored.isMounted, onBack: close });
+
+	const contentContext = useMemo<TooltipContentContextValue>(
+		() => ({
+			variant,
+			placement: anchored.position?.placement ?? placement,
+			arrowOffset: anchored.position?.arrowOffset ?? 0,
+			size: anchored.size ?? { width: 0, height: 0 },
+		}),
+		[variant, anchored.position?.placement, placement, anchored.position?.arrowOffset, anchored.size]
+	);
+
+	if (!anchored.isMounted) return null;
+
+	const { arrows, body } = partitionArrow(children);
+
+	return (
+		<Overlay.Portal id={overlayId} layer="anchored">
+			<Animated.View
+				accessibilityElementsHidden
+				importantForAccessibility="no-hide-descendants"
+				onLayout={anchored.onLayout}
+				pointerEvents={isScrollable ? "box-none" : "none"}
+				style={[anchored.positionerStyle, anchored.animatedStyle]}
+			>
+				<View
+					accessible={false}
+					className={tooltipVariants({ variant }).content({ className })}
+					onTouchStart={(event) => {
+						onContentTouchStart();
+						onTouchStart?.(event);
+					}}
+					style={[anchored.frameStyle, style]}
+					{...props}
+				>
+					<TooltipContentContext.Provider value={contentContext}>
+						{isScrollable ? (
+							<ScrollView className="shrink grow-0" contentContainerClassName="gap-1">
+								{body}
+							</ScrollView>
+						) : (
+							body
+						)}
+						{arrows}
+					</TooltipContentContext.Provider>
+				</View>
+			</Animated.View>
+		</Overlay.Portal>
+	);
+}
+TooltipContent.displayName = "DelacourUI.Tooltip.Content";

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

@@ -0,0 +1,19 @@
+import type { ReactElement } from "react";
+import { Text, type TextPresetProps } from "../text";
+import { useOptionalTooltipContent } from "./tooltip.context";
+import { TOOLTIP_DEFAULTS, tooltipVariants } from "./tooltip.variants";
+
+export type TooltipDescriptionProps = TextPresetProps;
+
+/**
+ * Supporting copy under the title — a `Text.Caption`, muted on a surface card
+ * and the background colour at 80% on an inverted chip.
+ *
+ * @example
+ * <Tooltip.Description>Changes reach your other devices within a minute.</Tooltip.Description>
+ */
+export function TooltipDescription({ className, ...props }: TooltipDescriptionProps): ReactElement {
+	const variant = useOptionalTooltipContent()?.variant ?? TOOLTIP_DEFAULTS.variant;
+	return <Text.Caption className={tooltipVariants({ variant }).description({ className })} {...props} />;
+}
+TooltipDescription.displayName = "DelacourUI.Tooltip.Description";

package/src/components/tooltip/tooltip-text.tsx

@@ -0,0 +1,21 @@
+import type { ReactElement } from "react";
+import { Text, type TextPresetProps } from "../text";
+import { useOptionalTooltipContent } from "./tooltip.context";
+import { TOOLTIP_DEFAULTS, tooltipVariants } from "./tooltip.variants";
+
+export type TooltipTextProps = TextPresetProps;
+
+/**
+ * The one-line label — a `Text.Caption`, inked for the panel it sits on: the
+ * background colour on an inverted chip, the popover foreground on a surface
+ * card. Caption rather than label because a tooltip is an aside to its
+ * control, not a second control.
+ *
+ * @example
+ * <Tooltip.Text>Share</Tooltip.Text>
+ */
+export function TooltipText({ className, ...props }: TooltipTextProps): ReactElement {
+	const variant = useOptionalTooltipContent()?.variant ?? TOOLTIP_DEFAULTS.variant;
+	return <Text.Caption className={tooltipVariants({ variant }).text({ className })} {...props} />;
+}
+TooltipText.displayName = "DelacourUI.Tooltip.Text";

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

@@ -0,0 +1,20 @@
+import type { ReactElement } from "react";
+import { Text, type TextPresetProps } from "../text";
+import { useOptionalTooltipContent } from "./tooltip.context";
+import { TOOLTIP_DEFAULTS, tooltipVariants } from "./tooltip.variants";
+
+export type TooltipTitleProps = TextPresetProps;
+
+/**
+ * A heading over a description, for the surface variant — a `Text.Label`, the
+ * size a popover's title takes. Not announced as a header: the panel is hidden
+ * from assistive technology, and its words reach the trigger through `label`.
+ *
+ * @example
+ * <Tooltip.Title>Sync</Tooltip.Title>
+ */
+export function TooltipTitle({ className, ...props }: TooltipTitleProps): ReactElement {
+	const variant = useOptionalTooltipContent()?.variant ?? TOOLTIP_DEFAULTS.variant;
+	return <Text.Label className={tooltipVariants({ variant }).title({ className })} {...props} />;
+}
+TooltipTitle.displayName = "DelacourUI.Tooltip.Title";

package/src/components/tooltip/tooltip-trigger.tsx

@@ -0,0 +1,103 @@
+import { isValidElement, type ReactElement } from "react";
+import type { GestureResponderEvent } from "react-native";
+import { Slot } from "../../lib/slot";
+import { Pressable, type PressableProps } from "../pressable";
+import { useTooltipContext } from "./tooltip.context";
+import { readableTextOf, resolveTooltipAccessibility } from "./tooltip.variants";
+
+export type TooltipTriggerProps = PressableProps;
+
+/** The `accessibilityLabel` an `asChild` trigger's child already carries, if any. */
+function childLabel(children: PressableProps["children"]): string | undefined {
+	if (!isValidElement<{ accessibilityLabel?: unknown }>(children)) return undefined;
+	const label = children.props.accessibilityLabel;
+	return typeof label === "string" ? label : undefined;
+}
+
+/**
+ * What the trigger is already called: its own label, the child's when it is
+ * donated to, or else its visible text — which is what a screen reader names
+ * a control by when nothing else does.
+ */
+function triggerName(
+	accessibilityLabel: string | undefined,
+	asChild: boolean,
+	children: PressableProps["children"]
+): string | undefined {
+	return accessibilityLabel ?? (asChild ? childLabel(children) : undefined) ?? readableTextOf(children);
+}
+
+/**
+ * The control the tooltip names, and the view the panel is anchored to.
+ *
+ * On its own it is this library's `Pressable`. **`asChild` donates the
+ * gesture** rather than wrapping the child, for `Popover.Trigger`'s reason —
+ * a `Button` inside a pressable trigger would win the touch. With the default
+ * `openOn="longPress"` the trigger hands the child an `onLongPress`; with
+ * `"press"`, an `onPress`. Either is chained ahead of the child's own, so the
+ * child's handler still runs, and a long press never costs the child its tap:
+ * a tap held past the long-press delay fails, so `onPress` does not fire for
+ * it. The measuring ref is composed onto the child's own, so the child has to
+ * be built on `Pressable`.
+ *
+ * The tooltip's `label` becomes the trigger's accessibility label when it has
+ * none, or its hint when it does — and visible text counts as a name, so a
+ * `<Button>Sync now</Button>` keeps saying "Sync now".
+ *
+ * @example
+ * <Tooltip.Trigger asChild>
+ *   <Button size="icon-md" variant="ghost"><Icon icon={IconShare} /></Button>
+ * </Tooltip.Trigger>
+ */
+export function TooltipTrigger({
+	asChild = false,
+	accessibilityLabel,
+	children,
+	onPress,
+	onLongPress,
+	onTouchStart,
+	...props
+}: TooltipTriggerProps): ReactElement {
+	const { openOn, label, activate, onTriggerTouchStart, triggerRef } = useTooltipContext();
+
+	const accessibility = resolveTooltipAccessibility({
+		label,
+		triggerLabel: triggerName(accessibilityLabel, asChild, children),
+	});
+
+	const handlers = {
+		onTouchStart: (event: GestureResponderEvent) => {
+			onTriggerTouchStart();
+			onTouchStart?.(event);
+		},
+		onPress:
+			openOn === "press"
+				? () => {
+						activate("press");
+						onPress?.();
+					}
+				: onPress,
+		onLongPress:
+			openOn === "longPress"
+				? () => {
+						activate("longPress");
+						onLongPress?.();
+					}
+				: onLongPress,
+	};
+
+	if (asChild) {
+		return (
+			<Slot {...props} accessibilityLabel={accessibilityLabel} {...accessibility} {...handlers} ref={triggerRef}>
+				{children}
+			</Slot>
+		);
+	}
+
+	return (
+		<Pressable {...props} accessibilityLabel={accessibilityLabel} {...accessibility} {...handlers} ref={triggerRef}>
+			{children}
+		</Pressable>
+	);
+}
+TooltipTrigger.displayName = "DelacourUI.Tooltip.Trigger";

package/src/components/tooltip/tooltip.context.tsx

@@ -0,0 +1,68 @@
+import { createContext, useContext } from "react";
+import type { AnchoredSize, AnchorRect, PopoverPlacement } from "../popover/popover.position";
+import type { MeasurableNode } from "../popover/use-anchor-measure";
+import type { TooltipGesture, TooltipOpenOn, TooltipVariant } from "./tooltip.variants";
+
+/** What `Tooltip` shares with its parts. */
+export type TooltipContextValue = {
+	isOpen: boolean;
+	setOpen: (isOpen: boolean) => void;
+	close: () => void;
+	openOn: TooltipOpenOn;
+	/** The tooltip's words, for the trigger's label or hint. */
+	label: string | undefined;
+	/** ms after the entrance settles before it hides; 0 for never. Already resolved against the screen reader. */
+	duration: number;
+	/** The trigger reports a gesture; the root decides whether it toggles. */
+	activate: (gesture: TooltipGesture) => void;
+	/** The trigger reports that a touch started on it — before the provider hears the same touch. */
+	onTriggerTouchStart: () => void;
+	/** The panel reports that a touch started on it, so a scrollable body is not an outside tap. */
+	onContentTouchStart: () => void;
+	/** The trigger's frame in window coordinates, `null` until it is measured on open. */
+	anchorRect: AnchorRect | null;
+	/** The callback ref `Tooltip.Trigger` measures through. */
+	triggerRef: (node: MeasurableNode | null) => void;
+};
+
+export const TooltipContext = createContext<TooltipContextValue | null>(null);
+TooltipContext.displayName = "DelacourUI.Tooltip.Context";
+
+/**
+ * The tooltip a part sits in — open state and the close. Throws outside a
+ * `<Tooltip>`.
+ *
+ * @example
+ * function Hint() {
+ *   const { isOpen } = useTooltip();
+ *   return isOpen ? <Text.Caption>Shown</Text.Caption> : null;
+ * }
+ */
+export function useTooltip(): Pick<TooltipContextValue, "isOpen" | "setOpen" | "close"> {
+	const context = useContext(TooltipContext);
+	if (context === null) throw new Error("useTooltip must be used inside a <Tooltip>.");
+	return context;
+}
+
+/** The full context, for the parts. Throws outside a `<Tooltip>`. */
+export function useTooltipContext(): TooltipContextValue {
+	const context = useContext(TooltipContext);
+	if (context === null) throw new Error("Tooltip parts must be used inside a <Tooltip>.");
+	return context;
+}
+
+/** What `Tooltip.Content` shares with the parts drawn inside the panel. */
+export type TooltipContentContextValue = {
+	variant: TooltipVariant;
+	placement: PopoverPlacement;
+	arrowOffset: number;
+	size: AnchoredSize;
+};
+
+export const TooltipContentContext = createContext<TooltipContentContextValue | null>(null);
+TooltipContentContext.displayName = "DelacourUI.Tooltip.ContentContext";
+
+/** The panel's variant and placement, or `null` outside `Tooltip.Content`. */
+export function useOptionalTooltipContent(): TooltipContentContextValue | null {
+	return useContext(TooltipContentContext);
+}