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

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>;

package/src/hooks/use-calm-motion.tsx

@@ -0,0 +1,31 @@
+import { createContext, type ReactElement, type ReactNode, useContext } from "react";
+import { useReducedMotion } from "react-native-reanimated";
+import { calmMotion } from "../lib/calm-motion";
+
+const CalmMotionContext = createContext(false);
+
+export type CalmMotionProviderProps = {
+	/** Hold every decorative loop beneath this still, whatever the OS setting. */
+	isMotionCalm: boolean;
+	children: ReactNode;
+};
+
+/**
+ * Asks every decorative loop beneath it to hold still — for an E2E build, whose test runner waits
+ * for the screen to stop moving before each gesture. `DelacourProvider` mounts it from its own
+ * `isMotionCalm`; mount it by hand only in an app that composes its providers itself.
+ *
+ * Optional: without one, {@link useCalmMotion} follows the OS reduce-motion setting alone.
+ */
+export function CalmMotionProvider({ isMotionCalm, children }: CalmMotionProviderProps): ReactElement {
+	return <CalmMotionContext.Provider value={isMotionCalm}>{children}</CalmMotionContext.Provider>;
+}
+
+/**
+ * Whether decorative motion should hold still, for this device and this app: the one place a
+ * component asks whether to loop. See `calmMotion` for what counts as decorative.
+ */
+export function useCalmMotion(): boolean {
+	return calmMotion({ isMotionCalm: useContext(CalmMotionContext), isReduceMotion: useReducedMotion() });
+}
+CalmMotionProvider.displayName = "DelacourUI.CalmMotionProvider";

package/src/lib/calm-motion.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from "bun:test";
+import { calmMotion } from "./calm-motion";
+
+describe("calmMotion", () => {
+	test("moves when neither the OS nor the app asks for stillness", () => {
+		expect(calmMotion({ isReduceMotion: false, isMotionCalm: false })).toBe(false);
+	});
+
+	test("holds still under the OS reduce-motion setting", () => {
+		expect(calmMotion({ isReduceMotion: true, isMotionCalm: false })).toBe(true);
+	});
+
+	test("holds still when the app asks, whatever the OS says", () => {
+		expect(calmMotion({ isReduceMotion: false, isMotionCalm: true })).toBe(true);
+		expect(calmMotion({ isReduceMotion: true, isMotionCalm: true })).toBe(true);
+	});
+});

package/src/lib/calm-motion.ts

@@ -0,0 +1,23 @@
+/**
+ * Whether decorative motion holds still: under the OS reduce-motion setting, or whenever the app
+ * asks — `DelacourProvider`'s `isMotionCalm`.
+ *
+ * The app's half is for automation, not accessibility. A UI test runner that waits for the screen
+ * to stop moving before every gesture (Argent waits up to 3 s, Detox and Maestro idle-wait the
+ * same way) pays the whole wait on any screen holding a loop that never ends — a shimmering
+ * skeleton turns every tap there into a timeout. An E2E build passes `isMotionCalm` and the loops
+ * hold still.
+ *
+ * Only motion that is decoration asks. Motion that *is* the behaviour — a spinner saying work is
+ * in flight, a progress bar a reader reads — keeps moving: stilling it would change what the
+ * screen says.
+ */
+export function calmMotion({
+	isReduceMotion,
+	isMotionCalm,
+}: {
+	isReduceMotion: boolean;
+	isMotionCalm: boolean;
+}): boolean {
+	return isReduceMotion || isMotionCalm;
+}