@delacour/react-native-ui 0.1.0-alpha.20261007115740 → 0.1.0-alpha.20261007120055

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.1.0-alpha.20261007115740",
+	"version": "0.1.0-alpha.20261007120055",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -76,6 +76,7 @@
 		"./textarea": "./src/components/textarea/index.ts",
 		"./toast": "./src/components/toast/index.ts",
 		"./toggle-button": "./src/components/toggle-button/index.ts",
+		"./tooltip": "./src/components/tooltip/index.ts",
 		"./expo/navigation-theme": "./src/expo/navigation-theme.tsx",
 		"./hooks/use-calm-motion": "./src/hooks/use-calm-motion.tsx",
 		"./hooks/use-controllable-state": "./src/hooks/use-controllable-state.ts",
@@ -106,8 +107,8 @@
 	},
 	"peerDependencies": {
 		"@central-icons-react-native/round-outlined-radius-1-stroke-1.5": "^1.1",
-		"@delacour/react-native-bottom-sheet": "0.1.0-alpha.20261007115740",
-		"@delacour/react-native-charts": "0.1.0-alpha.20261007115740",
+		"@delacour/react-native-bottom-sheet": "0.1.0-alpha.20261007120055",
+		"@delacour/react-native-charts": "0.1.0-alpha.20261007120055",
 		"@legendapp/list": ">=3.3",
 		"expo-linear-gradient": ">=15",
 		"expo-router": ">=57",

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);
+}

package/src/components/tooltip/tooltip.tsx

@@ -0,0 +1,213 @@
+import { type ReactElement, type ReactNode, useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import { AccessibilityInfo } from "react-native";
+import { scheduleOnUI } from "react-native-worklets";
+import { useControllableState } from "../../hooks/use-controllable-state";
+import { useOptionalOverlay } from "../overlay/overlay.context";
+import { useAnchorMeasure } from "../popover/use-anchor-measure";
+import { playHaptic } from "../pressable";
+import { TooltipContext, type TooltipContextValue } from "./tooltip.context";
+import {
+	resolveTooltipDuration,
+	shouldTooltipActivate,
+	TOOLTIP_DEFAULTS,
+	type TooltipGesture,
+	type TooltipOpenOn,
+} from "./tooltip.variants";
+import { TooltipArrow } from "./tooltip-arrow";
+import { TooltipContent } from "./tooltip-content";
+import { TooltipDescription } from "./tooltip-description";
+import { TooltipText } from "./tooltip-text";
+import { TooltipTitle } from "./tooltip-title";
+import { TooltipTrigger } from "./tooltip-trigger";
+
+export type TooltipProps = {
+	isOpen?: boolean;
+	/** Default false. */
+	defaultOpen?: boolean;
+	onOpenChange?: (isOpen: boolean) => void;
+	/** `"longPress"` leaves the trigger's tap alone; `"press"` is for a trigger with no tap of its own. Default `"longPress"`. */
+	openOn?: TooltipOpenOn;
+	/** Auto-hide this many ms after the entrance settles. 0 = until an outside tap or the trigger again. Default 1500. */
+	duration?: number;
+	/** The text a screen reader reads for the trigger — the tooltip's words without opening it. */
+	label?: string;
+	children: ReactNode;
+};
+
+/** The one tooltip on screen. Opening another closes it. */
+let current: { id: string; close: () => void } | null = null;
+
+/** Whether VoiceOver or TalkBack is running, kept current. */
+function useScreenReaderEnabled(): boolean {
+	const [isEnabled, setEnabled] = useState(false);
+	useEffect(() => {
+		let isMounted = true;
+		AccessibilityInfo.isScreenReaderEnabled().then((value) => {
+			if (isMounted) setEnabled(value);
+		});
+		const subscription = AccessibilityInfo.addEventListener("screenReaderChanged", setEnabled);
+		return () => {
+			isMounted = false;
+			subscription.remove();
+		};
+	}, []);
+	return isEnabled;
+}
+
+function TooltipRoot({
+	isOpen: isOpenProp,
+	defaultOpen = false,
+	onOpenChange,
+	openOn = TOOLTIP_DEFAULTS.openOn,
+	duration: durationProp,
+	label,
+	children,
+}: TooltipProps): ReactElement {
+	const id = useId();
+	const [isOpen, setOpen] = useControllableState({
+		value: isOpenProp,
+		defaultValue: defaultOpen,
+		onChange: onOpenChange,
+	});
+	const isScreenReaderEnabled = useScreenReaderEnabled();
+	const duration = resolveTooltipDuration(durationProp, { isScreenReaderEnabled });
+	const trigger = useAnchorMeasure({ isEnabled: isOpen });
+	const subscribeTouchStart = useOptionalOverlay()?.subscribeTouchStart;
+
+	// Set by the trigger's own `onTouchStart`, which bubbles to it before the
+	// provider hears the same touch and closes the tooltip — so the activation
+	// that follows knows this touch began on an open tooltip and leaves it shut.
+	const wasOpenAtTriggerTouch = useRef(false);
+	const isTouchInsideContent = useRef(false);
+
+	const close = useCallback(() => setOpen(false), [setOpen]);
+
+	const activate = useCallback(
+		(gesture: TooltipGesture) => {
+			if (!shouldTooltipActivate({ openOn, gesture, isScreenReaderEnabled })) return;
+			const wasOpen = wasOpenAtTriggerTouch.current || isOpen;
+			wasOpenAtTriggerTouch.current = false;
+			if (wasOpen) {
+				setOpen(false);
+				return;
+			}
+			if (gesture === "longPress") scheduleOnUI(playHaptic, "selection");
+			setOpen(true);
+		},
+		[openOn, isScreenReaderEnabled, isOpen, setOpen]
+	);
+
+	const onTriggerTouchStart = useCallback(() => {
+		wasOpenAtTriggerTouch.current = isOpen;
+	}, [isOpen]);
+
+	const onContentTouchStart = useCallback(() => {
+		isTouchInsideContent.current = true;
+	}, []);
+
+	useEffect(() => {
+		if (!isOpen || subscribeTouchStart === undefined) return;
+		return subscribeTouchStart(() => {
+			if (isTouchInsideContent.current) {
+				isTouchInsideContent.current = false;
+				return;
+			}
+			setOpen(false);
+		});
+	}, [isOpen, subscribeTouchStart, setOpen]);
+
+	useEffect(() => {
+		if (!isOpen) return;
+		if (current !== null && current.id !== id) current.close();
+		current = { id, close };
+		return () => {
+			if (current?.id === id) current = null;
+		};
+	}, [isOpen, id, close]);
+
+	const value = useMemo<TooltipContextValue>(
+		() => ({
+			isOpen,
+			setOpen,
+			close,
+			openOn,
+			label,
+			duration,
+			activate,
+			onTriggerTouchStart,
+			onContentTouchStart,
+			anchorRect: trigger.rect,
+			triggerRef: trigger.ref,
+		}),
+		[
+			isOpen,
+			setOpen,
+			close,
+			openOn,
+			label,
+			duration,
+			activate,
+			onTriggerTouchStart,
+			onContentTouchStart,
+			trigger.rect,
+			trigger.ref,
+		]
+	);
+
+	return <TooltipContext.Provider value={value}>{children}</TooltipContext.Provider>;
+}
+
+/**
+ * A short label naming the control under the finger — what an icon-only
+ * button does, a shortcut, a one-line hint.
+ *
+ * Mobile has no hover, so it opens on a **long press** by default, with a
+ * selection haptic, and the control's own tap still does what it did;
+ * `openOn="press"` opens it on a tap instead, for a trigger with no tap of its
+ * own — an info glyph. It hides itself `duration` ms after it appears, on the
+ * trigger again, or on a tap anywhere else — and that tap still lands on what
+ * it was aimed at. Opening one tooltip closes any other.
+ *
+ * It is not interactive: anything with a button in it is a `Popover`. The
+ * panel is hidden from assistive technology; `label` reaches the trigger as
+ * its accessibility label, or its hint when it already has a label, so
+ * VoiceOver reads the words without anything opening.
+ *
+ * It draws in the overlay layer, so it needs `OverlayProvider` at the app root
+ * — which is also what hears the outside tap.
+ *
+ * @example
+ * <Tooltip label="Share">
+ *   <Tooltip.Trigger asChild>
+ *     <Button size="icon-md" variant="ghost"><Icon icon={IconShare} /></Button>
+ *   </Tooltip.Trigger>
+ *   <Tooltip.Content>
+ *     <Tooltip.Arrow />
+ *     <Tooltip.Text>Share</Tooltip.Text>
+ *   </Tooltip.Content>
+ * </Tooltip>
+ *
+ * @example
+ * <Tooltip openOn="press" duration={0}>
+ *   <Tooltip.Trigger accessibilityLabel="About sync"><Icon icon={IconCircleInfo} /></Tooltip.Trigger>
+ *   <Tooltip.Content variant="surface">
+ *     <Tooltip.Title>Sync</Tooltip.Title>
+ *     <Tooltip.Description>Changes reach your other devices within a minute.</Tooltip.Description>
+ *   </Tooltip.Content>
+ * </Tooltip>
+ */
+export const Tooltip = Object.assign(TooltipRoot, {
+	/** The control the tooltip names — `Pressable`, or `asChild` to donate the gesture. */
+	Trigger: TooltipTrigger,
+	/** The panel — teleported, measured, placed and animated; never interactive. */
+	Content: TooltipContent,
+	/** The arrow pointing from the panel at the trigger. */
+	Arrow: TooltipArrow,
+	/** The one-line label. */
+	Text: TooltipText,
+	/** A heading, for the surface variant. */
+	Title: TooltipTitle,
+	/** Supporting copy under the title, for the surface variant. */
+	Description: TooltipDescription,
+	displayName: "DelacourUI.Tooltip",
+});

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

@@ -0,0 +1,231 @@
+import { describe, expect, test } from "bun:test";
+import { createElement } from "react";
+import { declaredTokens } from "../../styles/theme-tokens.test";
+import {
+	readableTextOf,
+	resolveTooltipAccessibility,
+	resolveTooltipDuration,
+	shouldTooltipActivate,
+	TOOLTIP_DEFAULTS,
+	TOOLTIP_DURATION,
+	TOOLTIP_ENTER_DISTANCE,
+	TOOLTIP_VARIANTS,
+	tooltipVariants,
+} from "./tooltip.variants";
+
+const LIGHT = declaredTokens("light");
+const DARK = declaredTokens("dark");
+
+/** `border-t` and friends set a width, not a colour, and name no token. */
+const STRUCTURAL_BORDER_SUFFIXES = new Set(["t", "b", "l", "r", "x", "y", "s", "e"]);
+
+/** Tailwind's own size steps share the `text-` prefix with colours and name no token. */
+const TEXT_SIZES = new Set(["xs", "sm", "base", "lg", "xl", "2xl", "3xl", "4xl"]);
+
+/** Every theme token a class string paints with, with any `/alpha` suffix dropped. */
+function colorTokens(cls: string): string[] {
+	const tokens: string[] = [];
+	for (const [, utility, token] of cls.matchAll(/\b(bg|border|text)-([a-z][\w-]*)(?:\/\d+)?\b/g)) {
+		if (utility === "border" && STRUCTURAL_BORDER_SUFFIXES.has(token)) continue;
+		if (utility === "text" && TEXT_SIZES.has(token)) continue;
+		tokens.push(token);
+	}
+	return tokens;
+}
+
+/** The slots this component declares, pinned so a new one has to be added before the sweeps can miss it. */
+const SLOT_NAMES = ["content", "arrow", "text", "title", "description"] as const;
+
+describe("tooltipVariants — slots", () => {
+	test("declares every slot in both variants", () => {
+		for (const variant of TOOLTIP_VARIANTS) {
+			const slots = tooltipVariants({ variant });
+			for (const name of SLOT_NAMES) expect(typeof slots[name]).toBe("function");
+		}
+	});
+
+	test("every token a slot paints with exists in both themes", () => {
+		for (const variant of TOOLTIP_VARIANTS) {
+			const slots = tooltipVariants({ variant });
+			for (const name of SLOT_NAMES) {
+				for (const token of colorTokens(slots[name]() ?? "")) {
+					expect(LIGHT.has(token)).toBe(true);
+					expect(DARK.has(token)).toBe(true);
+				}
+			}
+		}
+	});
+
+	test("the default variant is inverted", () => {
+		expect(tooltipVariants().content()).toBe(tooltipVariants({ variant: "inverted" }).content());
+	});
+
+	test("a caller's className wins on the panel", () => {
+		const content = tooltipVariants().content({ className: "px-4" });
+		expect(content).toContain("px-4");
+		expect(content).not.toMatch(/\bpx-2\b/);
+	});
+});
+
+describe("tooltipVariants — inverted", () => {
+	const slots = tooltipVariants({ variant: "inverted" });
+
+	test("the panel is the foreground colour, a small corner and compact padding, with no border", () => {
+		const content = slots.content();
+		expect(content).toContain("bg-foreground");
+		expect(content).toContain("rounded-md");
+		expect(content).toMatch(/\bpx-2\b/);
+		expect(content).toMatch(/\bpy-1\b/);
+		expect(content).not.toMatch(/\bborder\b/);
+	});
+
+	test("the arrow wears the panel's fill and no border", () => {
+		const arrow = slots.arrow();
+		expect(arrow).toContain("bg-foreground");
+		expect(arrow).not.toMatch(/\bborder-border\b/);
+	});
+
+	test("every piece of text is drawn in the background colour, so it reads on the inverted fill", () => {
+		expect(slots.text()).toContain("text-background");
+		expect(slots.title()).toContain("text-background");
+		expect(colorTokens(slots.description())).toEqual(["background"]);
+	});
+});
+
+describe("tooltipVariants — surface", () => {
+	const slots = tooltipVariants({ variant: "surface" });
+
+	test("the panel is a popover surface with a hairline, the card corner and room for two lines", () => {
+		const content = slots.content();
+		expect(content).toContain("bg-popover");
+		expect(content).toContain("border");
+		expect(content).toContain("border-border");
+		expect(content).toContain("rounded-lg");
+		expect(content).toMatch(/\bgap-\d/);
+	});
+
+	test("the arrow is the panel's fill with the panel's border on two edges", () => {
+		const arrow = slots.arrow();
+		expect(arrow).toContain("bg-popover");
+		expect(arrow).toContain("border-border");
+		expect(arrow).toContain("border-b");
+		expect(arrow).toContain("border-r");
+	});
+
+	test("text and title sit on the popover foreground; the description is muted", () => {
+		expect(slots.text()).toContain("text-popover-foreground");
+		expect(slots.title()).toContain("text-popover-foreground");
+		expect(slots.description()).toContain("text-muted-foreground");
+	});
+});
+
+describe("resolveTooltipDuration", () => {
+	test("passes a positive duration through", () => {
+		expect(resolveTooltipDuration(800, { isScreenReaderEnabled: false })).toBe(800);
+	});
+
+	test("0 means stay until dismissed", () => {
+		expect(resolveTooltipDuration(0, { isScreenReaderEnabled: false })).toBe(0);
+	});
+
+	test("an omitted duration is the default", () => {
+		expect(resolveTooltipDuration(undefined, { isScreenReaderEnabled: false })).toBe(TOOLTIP_DURATION);
+	});
+
+	test("a negative or non-finite duration falls back to the default rather than hiding at once", () => {
+		expect(resolveTooltipDuration(-1, { isScreenReaderEnabled: false })).toBe(TOOLTIP_DURATION);
+		expect(resolveTooltipDuration(Number.NaN, { isScreenReaderEnabled: false })).toBe(TOOLTIP_DURATION);
+		expect(resolveTooltipDuration(Number.POSITIVE_INFINITY, { isScreenReaderEnabled: false })).toBe(TOOLTIP_DURATION);
+	});
+
+	test("with a screen reader on it never times out — whoever opened it reads at their own pace", () => {
+		expect(resolveTooltipDuration(800, { isScreenReaderEnabled: true })).toBe(0);
+		expect(resolveTooltipDuration(undefined, { isScreenReaderEnabled: true })).toBe(0);
+	});
+});
+
+describe("shouldTooltipActivate", () => {
+	test("a long-press tooltip opens on a long press and ignores the tap", () => {
+		expect(shouldTooltipActivate({ openOn: "longPress", gesture: "longPress", isScreenReaderEnabled: false })).toBe(
+			true
+		);
+		expect(shouldTooltipActivate({ openOn: "longPress", gesture: "press", isScreenReaderEnabled: false })).toBe(false);
+	});
+
+	test("a press tooltip opens on a tap and ignores the long press", () => {
+		expect(shouldTooltipActivate({ openOn: "press", gesture: "press", isScreenReaderEnabled: false })).toBe(true);
+		expect(shouldTooltipActivate({ openOn: "press", gesture: "longPress", isScreenReaderEnabled: false })).toBe(false);
+	});
+
+	test("with a screen reader on, a long press never opens it — the label already reached the trigger", () => {
+		expect(shouldTooltipActivate({ openOn: "longPress", gesture: "longPress", isScreenReaderEnabled: true })).toBe(
+			false
+		);
+	});
+
+	test("with a screen reader on, a press tooltip still opens, for a partially sighted user", () => {
+		expect(shouldTooltipActivate({ openOn: "press", gesture: "press", isScreenReaderEnabled: true })).toBe(true);
+	});
+});
+
+describe("resolveTooltipAccessibility", () => {
+	test("no label, nothing to add", () => {
+		expect(resolveTooltipAccessibility({})).toEqual({});
+		expect(resolveTooltipAccessibility({ label: "", triggerLabel: "Share" })).toEqual({});
+	});
+
+	test("a trigger with no label of its own is named by the tooltip", () => {
+		expect(resolveTooltipAccessibility({ label: "Share" })).toEqual({ accessibilityLabel: "Share" });
+		expect(resolveTooltipAccessibility({ label: "Share", triggerLabel: "" })).toEqual({ accessibilityLabel: "Share" });
+	});
+
+	test("a trigger that already has a label keeps it, and the tooltip becomes its hint", () => {
+		expect(resolveTooltipAccessibility({ label: "Copies a link to the clipboard", triggerLabel: "Share" })).toEqual({
+			accessibilityHint: "Copies a link to the clipboard",
+		});
+	});
+
+	test("a label identical to the trigger's is not read twice", () => {
+		expect(resolveTooltipAccessibility({ label: "Share", triggerLabel: "Share" })).toEqual({});
+	});
+});
+
+describe("readableTextOf", () => {
+	test("reads a bare string or number", () => {
+		expect(readableTextOf("Sync now")).toBe("Sync now");
+		expect(readableTextOf(3)).toBe("3");
+	});
+
+	test("reads text nested in elements, the way a screen reader names a control from its content", () => {
+		const child = createElement("Label", null, "Sync ", createElement("Strong", null, "now"));
+		expect(readableTextOf(child)).toBe("Sync now");
+	});
+
+	test("an icon-only child has no text", () => {
+		expect(readableTextOf(createElement("Icon", { icon: "share" }))).toBeUndefined();
+		expect(readableTextOf(undefined)).toBeUndefined();
+	});
+
+	test("whitespace alone is no text", () => {
+		expect(readableTextOf("  ")).toBeUndefined();
+	});
+});
+
+describe("constants", () => {
+	test("defaults match the documented API", () => {
+		expect(TOOLTIP_DEFAULTS).toEqual({
+			placement: "top",
+			align: "center",
+			offset: 6,
+			alignOffset: 0,
+			width: "content-fit",
+			variant: "inverted",
+			openOn: "longPress",
+		});
+		expect(TOOLTIP_DURATION).toBe(1500);
+	});
+
+	test("the entrance is a short slide from the resolved side", () => {
+		expect(TOOLTIP_ENTER_DISTANCE).toBe(4);
+	});
+});

package/src/components/tooltip/tooltip.variants.ts

@@ -0,0 +1,177 @@
+import { Children, isValidElement, type ReactNode } from "react";
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+import type { PopoverAlign, PopoverPlacement, PopoverWidth } from "../popover/popover.position";
+
+/** The two looks: a dark chip that reads over anything, or a popover card for a title and a line. */
+export const TOOLTIP_VARIANTS = ["inverted", "surface"] as const;
+export type TooltipVariant = (typeof TOOLTIP_VARIANTS)[number];
+
+/** What opens it: a long press leaves the trigger's own tap alone; a press is for a trigger with no tap of its own. */
+export type TooltipOpenOn = "longPress" | "press";
+
+/** The gesture that reached the trigger. */
+export type TooltipGesture = "longPress" | "press";
+
+/**
+ * What `Tooltip` and `Tooltip.Content` do when a prop is left out.
+ *
+ * Above the trigger and centred on it, 6pt clear — closer than a popover's 8,
+ * because a one-line label belongs to its control — inverted, as wide as its
+ * words, opened by a long press.
+ */
+export const TOOLTIP_DEFAULTS = {
+	placement: "top",
+	align: "center",
+	offset: 6,
+	alignOffset: 0,
+	width: "content-fit",
+	variant: "inverted",
+	openOn: "longPress",
+} as const satisfies {
+	placement: PopoverPlacement;
+	align: PopoverAlign;
+	offset: number;
+	alignOffset: number;
+	width: PopoverWidth;
+	variant: TooltipVariant;
+	openOn: TooltipOpenOn;
+};
+
+/** How long a tooltip stays after its entrance settles, in ms. */
+export const TOOLTIP_DURATION = 1500;
+
+/** How far the panel travels on its way in, toward its resolved side. No scale — a label just appears. */
+export const TOOLTIP_ENTER_DISTANCE = 4;
+
+/**
+ * How long the tooltip stays, in ms — `0` for until it is dismissed.
+ *
+ * A negative or non-finite value is a mistake, not a request to vanish at
+ * once, so it falls back to the default. With a screen reader on it never
+ * times out: whoever opened it — a press tooltip, for someone using zoom
+ * alongside VoiceOver — reads at their own pace, and dismisses it with the
+ * trigger or a tap elsewhere.
+ */
+export function resolveTooltipDuration(
+	duration: number | undefined,
+	{ isScreenReaderEnabled }: { isScreenReaderEnabled: boolean }
+): number {
+	if (isScreenReaderEnabled) return 0;
+	if (duration === undefined || !Number.isFinite(duration) || duration < 0) return TOOLTIP_DURATION;
+	return duration;
+}
+
+/**
+ * Whether a gesture on the trigger toggles the tooltip.
+ *
+ * Only the gesture `openOn` names does. With a screen reader on, a long press
+ * never opens it: the tooltip's words already reached the trigger as its label
+ * or hint, and VoiceOver's double-tap-and-hold is an action, not a request to
+ * see a label that is hidden from it anyway. A press tooltip still opens, for a
+ * partially sighted user who reads the screen as well as hearing it.
+ */
+export function shouldTooltipActivate({
+	openOn,
+	gesture,
+	isScreenReaderEnabled,
+}: {
+	openOn: TooltipOpenOn;
+	gesture: TooltipGesture;
+	isScreenReaderEnabled: boolean;
+}): boolean {
+	if (gesture !== openOn) return false;
+	return !(isScreenReaderEnabled && gesture === "longPress");
+}
+
+/**
+ * The text a screen reader would name a control by when it has no
+ * `accessibilityLabel` — every string and number in its children, at any depth.
+ *
+ * `resolveTooltipAccessibility` needs it: a `<Button>Sync now</Button>` already
+ * has a name, and treating it as unnamed would replace "Sync now" with the
+ * tooltip's words instead of adding them as a hint.
+ */
+export function readableTextOf(node: ReactNode): string | undefined {
+	const parts: string[] = [];
+	const visit = (child: ReactNode): void => {
+		if (typeof child === "string" || typeof child === "number") {
+			parts.push(String(child));
+			return;
+		}
+		if (isValidElement<{ children?: ReactNode }>(child)) Children.forEach(child.props.children, visit);
+	};
+	Children.forEach(node, visit);
+	const text = parts.join("").trim();
+	return text === "" ? undefined : text;
+}
+
+export type TooltipAccessibility = { accessibilityLabel?: string; accessibilityHint?: string };
+
+/**
+ * What the trigger tells assistive technology, so VoiceOver says the
+ * tooltip's words without anything opening.
+ *
+ * A trigger with no label of its own — an icon button — is named by the
+ * tooltip. One that has a label keeps it, and the tooltip becomes its hint;
+ * unless the two say the same thing, which would only be read twice.
+ */
+export function resolveTooltipAccessibility({
+	label,
+	triggerLabel,
+}: {
+	label?: string;
+	triggerLabel?: string;
+}): TooltipAccessibility {
+	if (label === undefined || label === "") return {};
+	if (triggerLabel === undefined || triggerLabel === "") return { accessibilityLabel: label };
+	if (triggerLabel === label) return {};
+	return { accessibilityHint: label };
+}
+
+/**
+ * Styling for every part of a tooltip.
+ *
+ * `inverted` is the default: the foreground colour as the fill and the
+ * background colour as the ink, so it reads over anything in either theme,
+ * with a small corner and padding sized for one caption-sized line. `surface`
+ * is the popover card — fill, hairline and card corner — with room for a title
+ * over a description.
+ *
+ * The arrow is drawn by Popover's `AnchoredArrow` with its own paint stripped,
+ * so the slot here carries all of it: the inverted chip has no border, so its
+ * arrow is fill alone; the surface arrow wears the border on its two outer
+ * edges, the ones that show past the panel.
+ */
+export const tooltipVariants = tv({
+	slots: {
+		content: "",
+		arrow: "",
+		text: "",
+		title: "",
+		description: "",
+	},
+	variants: {
+		variant: {
+			inverted: {
+				content: "gap-0.5 rounded-md bg-foreground px-2 py-1",
+				arrow: "bg-foreground",
+				text: "text-background",
+				title: "text-background",
+				description: "text-background/80",
+			},
+			surface: {
+				content: "gap-1 rounded-lg border border-border bg-popover px-3 py-2",
+				arrow: "border-b border-r border-border bg-popover",
+				text: "text-popover-foreground",
+				title: "text-popover-foreground",
+				description: "text-muted-foreground",
+			},
+		},
+	},
+	defaultVariants: {
+		variant: "inverted",
+	},
+});
+
+export type TooltipVariantProps = VariantProps<typeof tooltipVariants>;