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

package/src/components/toast/toast.timer.ts

@@ -0,0 +1,51 @@
+/**
+ * A toast's auto-hide clock, as plain data.
+ *
+ * `startedAt` is `null` while paused; `remaining` is what was left when it last
+ * stopped. Every function returns a new value and reads the time it is given,
+ * so pause and resume are exact and the whole clock is reachable from
+ * `bun test`. The viewport turns `toastTimerRemaining` into one `setTimeout`
+ * per run and clears it on every pause.
+ *
+ * A duration of `0` means "until hidden" and is stored as an infinite
+ * `remaining`, which no arithmetic here ever brings down to zero.
+ */
+export type ToastTimer = {
+	remaining: number;
+	startedAt: number | null;
+};
+
+/** A paused clock holding `duration` ms. `0` never expires. */
+export function createToastTimer(duration: number): ToastTimer {
+	return { remaining: duration > 0 ? duration : Number.POSITIVE_INFINITY, startedAt: null };
+}
+
+export function isToastTimerRunning(timer: ToastTimer): boolean {
+	return timer.startedAt !== null;
+}
+
+/** Starts the clock at `now`. A running clock is returned as it is. */
+export function startToastTimer(timer: ToastTimer, now: number): ToastTimer {
+	return timer.startedAt === null ? { remaining: timer.remaining, startedAt: now } : timer;
+}
+
+/** Stops the clock at `now`, keeping what is left. A paused clock is returned as it is. */
+export function pauseToastTimer(timer: ToastTimer, now: number): ToastTimer {
+	if (timer.startedAt === null) return timer;
+	return { remaining: Math.max(0, timer.remaining - (now - timer.startedAt)), startedAt: null };
+}
+
+/** Carries on from where `pauseToastTimer` left it. */
+export function resumeToastTimer(timer: ToastTimer, now: number): ToastTimer {
+	return startToastTimer(timer, now);
+}
+
+/** Milliseconds left at `now` — `Infinity` for a toast that stays until hidden. */
+export function toastTimerRemaining(timer: ToastTimer, now: number): number {
+	if (timer.startedAt === null) return timer.remaining;
+	return Math.max(0, timer.remaining - (now - timer.startedAt));
+}
+
+export function isToastTimerExpired(timer: ToastTimer, now: number): boolean {
+	return toastTimerRemaining(timer, now) <= 0;
+}

package/src/components/toast/toast.tsx

@@ -0,0 +1,132 @@
+import { type ReactElement, type ReactNode, useCallback, useMemo, useState } from "react";
+import { type AccessibilityActionEvent, View, type ViewProps } from "react-native";
+import { IconDefaultsProvider } from "../icon";
+import {
+	type ToastContextValue,
+	ToastProvider,
+	type ToastRegisteredAction,
+	useToastItemContext,
+} from "./toast.context";
+import type { ToastStatus } from "./toast.store";
+import { resolveToastRole, TOAST_FOREGROUND_TOKEN, toastVariants } from "./toast.variants";
+import { ToastAction } from "./toast-action";
+import { ToastClose } from "./toast-close";
+import { ToastContent } from "./toast-content";
+import { ToastDescription } from "./toast-description";
+import { ToastIndicator } from "./toast-indicator";
+import { ToastTitle } from "./toast-title";
+
+export type ToastProps = ViewProps & {
+	className?: string;
+	/** What the toast says: `default`, `info`, `success`, `warning` or `destructive`. Picks the glyph and the title's colour. */
+	status?: ToastStatus;
+	/** Hides the toast — the close control, the action and a screen reader's dismiss call it. Inside the viewport it defaults to hiding the toast being drawn. */
+	onHide?: () => void;
+	children?: ReactNode;
+};
+
+function noop(): void {}
+
+function ToastRoot({
+	status = "default",
+	onHide,
+	className,
+	children,
+	accessibilityActions,
+	onAccessibilityAction,
+	...props
+}: ToastProps): ReactElement {
+	const item = useToastItemContext();
+	const hide = onHide ?? item?.hide ?? noop;
+	const [action, setAction] = useState<ToastRegisteredAction | null>(null);
+
+	const context = useMemo<ToastContextValue>(() => ({ status, hide, registerAction: setAction }), [status, hide]);
+
+	const slots = toastVariants({ status });
+	const iconClassName = slots.icon();
+	const iconColor = TOAST_FOREGROUND_TOKEN[status];
+	const iconDefaults = useMemo(() => ({ className: iconClassName, color: iconColor }), [iconClassName, iconColor]);
+
+	const actions = useMemo(
+		() => [
+			...(action ? [{ name: "activate", label: action.label }] : []),
+			{ name: "escape" },
+			{ name: "dismiss", label: "Dismiss" },
+			...(accessibilityActions ?? []),
+		],
+		[action, accessibilityActions]
+	);
+
+	const handleAccessibilityAction = useCallback(
+		(event: AccessibilityActionEvent) => {
+			const { actionName } = event.nativeEvent;
+			if (actionName === "activate" && action) action.run();
+			else if (actionName === "escape" || actionName === "dismiss") hide();
+			onAccessibilityAction?.(event);
+		},
+		[action, hide, onAccessibilityAction]
+	);
+
+	// One accessible element: VoiceOver and TalkBack read the title and the
+	// description as one message, and the action and ✕ are its actions rather
+	// than two more stops. It never takes focus — it is announced instead.
+	return (
+		<ToastProvider value={context}>
+			<View
+				accessibilityActions={actions}
+				accessibilityLiveRegion="polite"
+				accessibilityRole={resolveToastRole(status)}
+				accessible
+				className={slots.root({ className })}
+				onAccessibilityAction={handleAccessibilityAction}
+				{...props}
+			>
+				<IconDefaultsProvider value={iconDefaults}>{children}</IconDefaultsProvider>
+			</View>
+		</ToastProvider>
+	);
+}
+
+/**
+ * The toast card — a glyph, a title, a description, an action and a ✕ — on a
+ * `popover` surface with a hairline.
+ *
+ * The viewport draws one of these for every `toast()`; compose it yourself
+ * only inside a custom `render`, where it keeps the house look and hides the
+ * toast it is drawn in with no `onHide` of its own. `status` is Alert's
+ * vocabulary and colours the glyph and the title from Alert's token, so a toast
+ * and an alert saying the same thing read as one family.
+ *
+ * One accessible element: the title and the description are read as one
+ * message, the action is its `activate` and the ✕ its `escape` and "Dismiss".
+ * `role="alert"` for a failure; a polite live region on Android.
+ *
+ * @example
+ * toast.show({
+ *   render: ({ hide }) => (
+ *     <Toast status="success">
+ *       <Toast.Indicator />
+ *       <Toast.Content>
+ *         <Toast.Title>Invite sent</Toast.Title>
+ *         <Toast.Description>priya@example.com can join now.</Toast.Description>
+ *       </Toast.Content>
+ *       <Toast.Close />
+ *     </Toast>
+ *   ),
+ * });
+ */
+export const Toast = Object.assign(ToastRoot, {
+	/** The leading status glyph — Alert's for the same status. Children replace it. */
+	Indicator: ToastIndicator,
+	/** The column holding the title and the description. */
+	Content: ToastContent,
+	/** What happened, in the status's colour. */
+	Title: ToastTitle,
+	/** A muted line under the title. */
+	Description: ToastDescription,
+	/** One compact text button; pressing it also hides the toast. */
+	Action: ToastAction,
+	/** A trailing ✕ that hides the toast. */
+	Close: ToastClose,
+	displayName: "DelacourUI.Toast",
+});

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

@@ -0,0 +1,393 @@
+import { describe, expect, test } from "bun:test";
+import { declaredTokens } from "../../styles/theme-tokens.test";
+import { ALERT_FOREGROUND_TOKEN, ALERT_STATUSES } from "../alert/alert.variants";
+import {
+	resolveToastAnnouncement,
+	resolveToastDepthStyle,
+	resolveToastDrag,
+	resolveToastDuration,
+	resolveToastEnterDelay,
+	resolveToastHaptic,
+	resolveToastInterrupts,
+	resolveToastRelease,
+	resolveToastRole,
+	resolveToastStack,
+	resolveToastStackedHeight,
+	TOAST_DURATION,
+	TOAST_ENTER_DISTANCE,
+	TOAST_FOREGROUND_TOKEN,
+	TOAST_PLACEMENTS,
+	TOAST_RUBBER_BAND,
+	TOAST_STACK,
+	TOAST_STAGGER_MS,
+	TOAST_STATUSES,
+	TOAST_SWIPE,
+	type ToastStackInput,
+	toastVariants,
+} from "./toast.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 = [
+	"viewport",
+	"stack",
+	"item",
+	"root",
+	"indicator",
+	"content",
+	"title",
+	"description",
+	"action",
+	"actionLabel",
+	"close",
+	"icon",
+] as const;
+
+describe("toastVariants", () => {
+	test("declares every slot", () => {
+		const slots = toastVariants();
+		for (const name of SLOT_NAMES) expect(typeof slots[name]).toBe("function");
+	});
+
+	test("every token a slot paints with exists in both themes, for every status", () => {
+		for (const status of TOAST_STATUSES) {
+			const slots = toastVariants({ status });
+			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 statuses are Alert's", () => {
+		expect(TOAST_STATUSES).toBe(ALERT_STATUSES);
+		expect(TOAST_FOREGROUND_TOKEN).toBe(ALERT_FOREGROUND_TOKEN);
+	});
+
+	test("the title takes Alert's foreground token per status", () => {
+		for (const status of TOAST_STATUSES) {
+			expect(toastVariants({ status }).title()).toContain(`text-${ALERT_FOREGROUND_TOKEN[status]}`);
+		}
+	});
+
+	test("the card is a popover surface with the card corner and a hairline, and no shadow", () => {
+		const root = toastVariants().root();
+		expect(root).toContain("bg-popover");
+		expect(root).toMatch(/\bborder\b/);
+		expect(root).toContain("border-border");
+		expect(root).toContain("rounded-lg");
+		expect(root).toContain("flex-row");
+		expect(root).toContain("max-w-[560px]");
+		expect(root).not.toMatch(/\bshadow/);
+	});
+
+	test("the description is muted whatever the status", () => {
+		for (const status of TOAST_STATUSES) {
+			expect(toastVariants({ status }).description()).toContain("text-muted-foreground");
+		}
+	});
+
+	test("the action's label is the primary colour, on the label and not the pressable (rule 1)", () => {
+		expect(toastVariants().actionLabel()).toContain("text-primary");
+		expect(toastVariants().action()).not.toMatch(/\btext-(?!xs|sm|base)/);
+	});
+
+	test("the root holds no text colour (rule 1)", () => {
+		expect(toastVariants().root()).not.toMatch(/\btext-/);
+	});
+
+	test("a caller's className wins on the card", () => {
+		const root = toastVariants().root({ className: "px-6" });
+		expect(root).toContain("px-6");
+		expect(root).not.toMatch(/\bpx-4\b/);
+	});
+});
+
+describe("resolveToastDuration", () => {
+	const quiet = { isScreenReaderEnabled: false };
+	const reader = { isScreenReaderEnabled: true };
+
+	test("defaults to 4000, and 6000 with an action", () => {
+		expect(resolveToastDuration({}, quiet)).toBe(TOAST_DURATION.default);
+		expect(resolveToastDuration({ hasAction: true }, quiet)).toBe(TOAST_DURATION.withAction);
+		expect(TOAST_DURATION).toMatchObject({ default: 4000, withAction: 6000 });
+	});
+
+	test("an explicit duration wins, and 0 stays until hidden", () => {
+		expect(resolveToastDuration({ duration: 1500 }, quiet)).toBe(1500);
+		expect(resolveToastDuration({ duration: 0, hasAction: true }, quiet)).toBe(0);
+	});
+
+	test("a loading toast stays until updated unless it says otherwise", () => {
+		expect(resolveToastDuration({ isLoading: true }, quiet)).toBe(0);
+		expect(resolveToastDuration({ isLoading: true, duration: 2000 }, quiet)).toBe(2000);
+	});
+
+	test("nonsense falls back to the default", () => {
+		expect(resolveToastDuration({ duration: -1 }, quiet)).toBe(TOAST_DURATION.default);
+		expect(resolveToastDuration({ duration: Number.NaN }, quiet)).toBe(TOAST_DURATION.default);
+	});
+
+	test("under a screen reader every timed toast stays at least 10 seconds (WCAG 2.2.1)", () => {
+		expect(TOAST_DURATION.screenReaderMinimum).toBe(10_000);
+		expect(resolveToastDuration({}, reader)).toBe(10_000);
+		expect(resolveToastDuration({ duration: 1500 }, reader)).toBe(10_000);
+		expect(resolveToastDuration({ duration: 20_000 }, reader)).toBe(20_000);
+		expect(resolveToastDuration({ duration: 0 }, reader)).toBe(0);
+	});
+});
+
+function stackItem(id: string, overrides: Partial<ToastStackInput> = {}): ToastStackInput {
+	return { id, placement: "bottom", isExiting: false, ...overrides };
+}
+
+describe("resolveToastStack", () => {
+	test("newest in front, and at most three drawn", () => {
+		const items = ["a", "b", "c", "d", "e"].map((id) => stackItem(id));
+		expect(resolveToastStack(items, "bottom")).toEqual([
+			{ id: "e", depth: 0, isVisible: true, isExiting: false },
+			{ id: "d", depth: 1, isVisible: true, isExiting: false },
+			{ id: "c", depth: 2, isVisible: true, isExiting: false },
+			{ id: "b", depth: 3, isVisible: false, isExiting: false },
+			{ id: "a", depth: 4, isVisible: false, isExiting: false },
+		]);
+		expect(TOAST_STACK.maxVisible).toBe(3);
+	});
+
+	test("only the asked placement", () => {
+		const items = [stackItem("a", { placement: "top" }), stackItem("b"), stackItem("c", { placement: "top" })];
+		expect(resolveToastStack(items, "top").map((entry) => entry.id)).toEqual(["c", "a"]);
+	});
+
+	test("an exiting toast keeps its slot while it leaves and frees it for the queue", () => {
+		const items = [stackItem("a"), stackItem("b"), stackItem("c"), stackItem("d", { isExiting: true })];
+		expect(resolveToastStack(items, "bottom")).toEqual([
+			{ id: "d", depth: 0, isVisible: true, isExiting: true },
+			{ id: "c", depth: 0, isVisible: true, isExiting: false },
+			{ id: "b", depth: 1, isVisible: true, isExiting: false },
+			{ id: "a", depth: 2, isVisible: true, isExiting: false },
+		]);
+	});
+
+	test("an exiting toast that was never drawn is not drawn on its way out", () => {
+		const items = [stackItem("a", { isExiting: true }), stackItem("b"), stackItem("c"), stackItem("d")];
+		expect(resolveToastStack(items, "bottom")[3]).toEqual({ id: "a", depth: 3, isVisible: false, isExiting: true });
+	});
+});
+
+describe("resolveToastDepthStyle", () => {
+	test("the front toast is untouched", () => {
+		expect(resolveToastDepthStyle(0, "bottom")).toEqual({ translateY: 0, scale: 1, opacity: 1 });
+	});
+
+	test("each older toast sits 8pt further toward the entry edge, smaller and fainter", () => {
+		expect(resolveToastDepthStyle(1, "bottom")).toEqual({ translateY: 8, scale: 0.95, opacity: 0.75 });
+		const top = resolveToastDepthStyle(2, "top");
+		expect(top.translateY).toBe(-16);
+		expect(top.scale).toBeCloseTo(0.9);
+		expect(top.opacity).toBeCloseTo(0.5);
+	});
+});
+
+describe("resolveToastStackedHeight", () => {
+	test("the front toast keeps its own height", () => {
+		expect(resolveToastStackedHeight({ depth: 0, natural: 90, front: 60 })).toBe(90);
+	});
+
+	test("a toast behind takes the front one's height, so a taller one cannot show over it", () => {
+		expect(resolveToastStackedHeight({ depth: 1, natural: 90, front: 60 })).toBe(60);
+		expect(resolveToastStackedHeight({ depth: 2, natural: 40, front: 60 })).toBe(60);
+	});
+
+	test("moving to the front, it eases from the front's height back to its own", () => {
+		expect(resolveToastStackedHeight({ depth: 0.5, natural: 90, front: 60 })).toBe(75);
+	});
+
+	test("unmeasured, it is left alone", () => {
+		expect(resolveToastStackedHeight({ depth: 1, natural: 0, front: 60 })).toBeNull();
+		expect(resolveToastStackedHeight({ depth: 1, natural: 90, front: 0 })).toBeNull();
+	});
+});
+
+describe("resolveToastEnterDelay", () => {
+	test("toasts shown in one tick enter 220ms apart", () => {
+		expect(TOAST_STAGGER_MS).toBe(220);
+		expect(resolveToastEnterDelay({ createdAt: 0, batchIndex: 0, now: 0 })).toBe(0);
+		expect(resolveToastEnterDelay({ createdAt: 0, batchIndex: 2, now: 0 })).toBe(440);
+	});
+
+	test("a queued toast drawn later owes no delay", () => {
+		expect(resolveToastEnterDelay({ createdAt: 0, batchIndex: 4, now: 5000 })).toBe(0);
+	});
+});
+
+describe("resolveToastDrag", () => {
+	test("sideways and toward the entry edge follow the finger", () => {
+		expect(resolveToastDrag({ placement: "bottom", translationX: -50, translationY: 30 })).toEqual({ x: -50, y: 30 });
+		expect(resolveToastDrag({ placement: "top", translationX: 0, translationY: -30 })).toEqual({ x: 0, y: -30 });
+	});
+
+	test("toward the centre rubber-bands, never past the limit", () => {
+		const pulled = resolveToastDrag({ placement: "bottom", translationX: 0, translationY: -400 });
+		expect(pulled.y).toBeLessThan(0);
+		expect(pulled.y).toBeGreaterThan(-TOAST_RUBBER_BAND);
+		const small = resolveToastDrag({ placement: "top", translationX: 0, translationY: 10 });
+		expect(small.y).toBeGreaterThan(0);
+		expect(small.y).toBeLessThan(10);
+	});
+});
+
+describe("resolveToastRelease", () => {
+	const size = { width: 300, height: 60 };
+	const still = { velocityX: 0, velocityY: 0 };
+
+	test("a short drag settles back", () => {
+		expect(resolveToastRelease({ placement: "bottom", translationX: 20, translationY: 10, ...still, ...size })).toEqual(
+			{ kind: "settle" }
+		);
+	});
+
+	test("past 40% sideways dismisses that way", () => {
+		expect(TOAST_SWIPE.distanceRatio).toBe(0.4);
+		expect(resolveToastRelease({ placement: "bottom", translationX: 130, translationY: 0, ...still, ...size })).toEqual(
+			{ kind: "dismiss", axis: "x", direction: 1 }
+		);
+		expect(resolveToastRelease({ placement: "top", translationX: -130, translationY: 0, ...still, ...size })).toEqual({
+			kind: "dismiss",
+			axis: "x",
+			direction: -1,
+		});
+	});
+
+	test("past 40% of its height toward the entry edge dismisses", () => {
+		expect(resolveToastRelease({ placement: "bottom", translationX: 0, translationY: 30, ...still, ...size })).toEqual({
+			kind: "dismiss",
+			axis: "y",
+			direction: 1,
+		});
+		expect(resolveToastRelease({ placement: "top", translationX: 0, translationY: -30, ...still, ...size })).toEqual({
+			kind: "dismiss",
+			axis: "y",
+			direction: -1,
+		});
+	});
+
+	test("toward the centre never dismisses, however far", () => {
+		expect(
+			resolveToastRelease({ placement: "bottom", translationX: 0, translationY: -200, ...still, ...size })
+		).toEqual({ kind: "settle" });
+		expect(
+			resolveToastRelease({
+				placement: "top",
+				translationX: 0,
+				translationY: 200,
+				velocityX: 0,
+				velocityY: 2000,
+				...size,
+			})
+		).toEqual({ kind: "settle" });
+	});
+
+	test("a fling over 800pt/s dismisses however short", () => {
+		expect(TOAST_SWIPE.velocity).toBe(800);
+		expect(
+			resolveToastRelease({
+				placement: "bottom",
+				translationX: 10,
+				translationY: 0,
+				velocityX: 900,
+				velocityY: 0,
+				...size,
+			})
+		).toEqual({ kind: "dismiss", axis: "x", direction: 1 });
+		expect(
+			resolveToastRelease({
+				placement: "top",
+				translationX: 0,
+				translationY: -5,
+				velocityX: 0,
+				velocityY: -900,
+				...size,
+			})
+		).toEqual({ kind: "dismiss", axis: "y", direction: -1 });
+	});
+
+	test("the dominant axis wins when both would dismiss", () => {
+		expect(
+			resolveToastRelease({
+				placement: "bottom",
+				translationX: 200,
+				translationY: 40,
+				velocityX: 0,
+				velocityY: 0,
+				...size,
+			})
+		).toEqual({ kind: "dismiss", axis: "x", direction: 1 });
+	});
+});
+
+describe("resolveToastHaptic", () => {
+	test("success, warning and destructive play their notification; the rest are silent", () => {
+		expect(resolveToastHaptic("success", undefined)).toBe("success");
+		expect(resolveToastHaptic("warning", undefined)).toBe("warning");
+		expect(resolveToastHaptic("destructive", undefined)).toBe("error");
+		expect(resolveToastHaptic("info", undefined)).toBe(false);
+		expect(resolveToastHaptic("default", undefined)).toBe(false);
+	});
+
+	test("the caller's choice wins, including false", () => {
+		expect(resolveToastHaptic("success", false)).toBe(false);
+		expect(resolveToastHaptic("default", "light")).toBe("light");
+	});
+});
+
+describe("accessibility", () => {
+	test("the announcement is the title, then the description", () => {
+		expect(resolveToastAnnouncement({ title: "Saved" })).toBe("Saved");
+		expect(resolveToastAnnouncement({ title: "Upload failed", description: "Try again" })).toBe(
+			"Upload failed. Try again"
+		);
+	});
+
+	test("warnings and failures interrupt; the rest queue", () => {
+		expect(resolveToastInterrupts("destructive")).toBe(true);
+		expect(resolveToastInterrupts("warning")).toBe(true);
+		expect(resolveToastInterrupts("success")).toBe(false);
+		expect(resolveToastInterrupts("default")).toBe(false);
+	});
+
+	test("only a failure is an alert", () => {
+		expect(resolveToastRole("destructive")).toBe("alert");
+		expect(resolveToastRole("warning")).toBe("none");
+		expect(resolveToastRole("success")).toBe("none");
+	});
+});
+
+describe("constants", () => {
+	test("placements, entrance and stack steps", () => {
+		expect(TOAST_PLACEMENTS).toEqual(["top", "bottom"]);
+		expect(TOAST_ENTER_DISTANCE).toBe(16);
+		expect(TOAST_STACK).toMatchObject({ depthOffset: 8, depthScale: 0.05, depthOpacity: 0.25 });
+	});
+});