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

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

@@ -0,0 +1,259 @@
+import { describe, expect, test } from "bun:test";
+import {
+	createToastApi,
+	createToastStore,
+	normalizeToastInput,
+	reduceToasts,
+	type ToastItem,
+	type ToastMessageItem,
+	type ToastState,
+} from "./toast.store";
+
+const AT = { now: 1000, batchIndex: 0 };
+
+function message(id: string, title = id): ToastMessageItem {
+	const item = normalizeToastInput({ id, title }, { ...AT, id });
+	if (item.kind !== "message") throw new Error("expected a message");
+	return item;
+}
+
+function ids(state: ToastState): string[] {
+	return state.map((item) => item.id);
+}
+
+/** A store whose microtasks run when the test says so, so a batch is explicit. */
+function manualStore() {
+	const queue: (() => void)[] = [];
+	let now = 0;
+	const store = createToastStore({
+		now: () => now,
+		schedule: (task) => {
+			queue.push(task);
+		},
+	});
+	return {
+		store,
+		api: createToastApi(store),
+		flush: () => {
+			for (const task of queue.splice(0)) task();
+		},
+		advance: (ms: number) => {
+			now += ms;
+		},
+	};
+}
+
+describe("normalizeToastInput", () => {
+	test("a string is a default-status message titled with it", () => {
+		const item = normalizeToastInput("Saved", { ...AT, id: "t1" });
+		expect(item).toMatchObject({
+			kind: "message",
+			id: "t1",
+			title: "Saved",
+			status: "default",
+			placement: "bottom",
+			isLoading: false,
+			isExiting: false,
+			revision: 0,
+			createdAt: 1000,
+		});
+	});
+
+	test("a render function makes a custom toast", () => {
+		const render = () => null;
+		const item = normalizeToastInput({ render, placement: "top" }, { ...AT, id: "t2" });
+		expect(item.kind).toBe("custom");
+		expect(item.placement).toBe("top");
+	});
+
+	test("an id on the options wins over the generated one", () => {
+		expect(normalizeToastInput({ id: "mine", title: "x" }, { ...AT, id: "t3" }).id).toBe("mine");
+	});
+});
+
+describe("reduceToasts", () => {
+	test("add appends, oldest first", () => {
+		const state = reduceToasts(reduceToasts([], { type: "add", item: message("a") }), {
+			type: "add",
+			item: message("b"),
+		});
+		expect(ids(state)).toEqual(["a", "b"]);
+	});
+
+	test("add with an existing id replaces it in place and bumps its revision", () => {
+		let state: ToastState = [message("a"), message("b")];
+		state = reduceToasts(state, { type: "hide", id: "a" });
+		state = reduceToasts(state, { type: "add", item: message("a", "Again") });
+		expect(ids(state)).toEqual(["a", "b"]);
+		expect(state[0]).toMatchObject({ title: "Again", revision: 1, isExiting: false });
+	});
+
+	test("update merges into the toast with that id and bumps its revision", () => {
+		const state = reduceToasts([message("a")], {
+			type: "update",
+			id: "a",
+			patch: { status: "success", description: "All done" },
+		});
+		expect(state[0]).toMatchObject({ title: "a", status: "success", description: "All done", revision: 1 });
+	});
+
+	test("update of an unknown id is the identity", () => {
+		const state: ToastState = [message("a")];
+		expect(reduceToasts(state, { type: "update", id: "zzz", patch: { title: "x" } })).toBe(state);
+	});
+
+	test("update with a title turns a custom toast into a message", () => {
+		const custom = normalizeToastInput({ id: "c", render: () => null }, { ...AT, id: "c" });
+		const [item] = reduceToasts([custom], { type: "update", id: "c", patch: { title: "Now words" } });
+		expect(item).toMatchObject({ kind: "message", title: "Now words", status: "default" });
+	});
+
+	test("hide marks the toast exiting and keeps it, so the viewport can animate it out", () => {
+		const state = reduceToasts([message("a")], { type: "hide", id: "a" });
+		expect(ids(state)).toEqual(["a"]);
+		expect(state[0]?.isExiting).toBe(true);
+	});
+
+	test("hide of an exiting or unknown toast is the identity", () => {
+		const exiting = reduceToasts([message("a")], { type: "hide", id: "a" });
+		expect(reduceToasts(exiting, { type: "hide", id: "a" })).toBe(exiting);
+		expect(reduceToasts(exiting, { type: "hide", id: "zzz" })).toBe(exiting);
+	});
+
+	test("remove drops it", () => {
+		const state = reduceToasts([message("a"), message("b")], { type: "remove", id: "a" });
+		expect(ids(state)).toEqual(["b"]);
+	});
+
+	test("hideAll marks every toast exiting", () => {
+		const state = reduceToasts([message("a"), message("b")], { type: "hideAll" });
+		expect(state.every((item: ToastItem) => item.isExiting)).toBe(true);
+	});
+});
+
+describe("createToastStore", () => {
+	test("notifies subscribers and hands out a fresh snapshot", () => {
+		const { store, api } = manualStore();
+		const before = store.getSnapshot();
+		let calls = 0;
+		const unsubscribe = store.subscribe(() => {
+			calls += 1;
+		});
+		api.show("Saved");
+		expect(calls).toBe(1);
+		expect(store.getSnapshot()).not.toBe(before);
+		unsubscribe();
+		api.show("Again");
+		expect(calls).toBe(1);
+	});
+
+	test("a no-op action keeps the snapshot and notifies no one", () => {
+		const { store, api } = manualStore();
+		api.show("Saved");
+		const snapshot = store.getSnapshot();
+		let calls = 0;
+		store.subscribe(() => {
+			calls += 1;
+		});
+		api.update("missing", { title: "x" });
+		expect(store.getSnapshot()).toBe(snapshot);
+		expect(calls).toBe(0);
+	});
+
+	test("toasts added in one tick are numbered for the stagger, and the count resets after it", () => {
+		const { store, api, flush } = manualStore();
+		api.show("one");
+		api.show("two");
+		api.show("three");
+		flush();
+		api.show("four");
+		expect(store.getSnapshot().map((item) => item.batchIndex)).toEqual([0, 1, 2, 0]);
+	});
+
+	test("ids come from a counter and never repeat", () => {
+		const { api } = manualStore();
+		const a = api.show("a");
+		const b = api.show("b");
+		expect(a.id).not.toBe(b.id);
+	});
+});
+
+describe("createToastApi", () => {
+	test("the api is callable as well as a namespace", () => {
+		const { store, api } = manualStore();
+		api("Saved");
+		expect(store.getSnapshot()[0]).toMatchObject({ title: "Saved" });
+	});
+
+	test("the status shorthands set the status, and error is destructive", () => {
+		const { store, api } = manualStore();
+		api.success("s");
+		api.info("i");
+		api.warning("w");
+		api.error("e", { description: "why" });
+		expect(store.getSnapshot().map((item) => (item.kind === "message" ? item.status : null))).toEqual([
+			"success",
+			"info",
+			"warning",
+			"destructive",
+		]);
+		expect(store.getSnapshot()[3]).toMatchObject({ description: "why" });
+	});
+
+	test("the handle hides its own toast", () => {
+		const { store, api } = manualStore();
+		const handle = api.show("Saved");
+		handle.hide();
+		expect(store.getSnapshot()[0]?.isExiting).toBe(true);
+	});
+
+	test("hide and hideAll", () => {
+		const { store, api } = manualStore();
+		const a = api.show("a");
+		api.show("b");
+		api.hide(a.id);
+		expect(store.getSnapshot().map((item) => item.isExiting)).toEqual([true, false]);
+		api.hideAll();
+		expect(store.getSnapshot().every((item) => item.isExiting)).toBe(true);
+	});
+
+	test("promise: loading, then success in place under the same id", async () => {
+		const { store, api } = manualStore();
+		const result = api.promise(Promise.resolve(3), {
+			loading: "Uploading…",
+			success: (count) => `Uploaded ${count} files`,
+			error: "Upload failed",
+		});
+		const [loading] = store.getSnapshot();
+		expect(loading).toMatchObject({ kind: "message", title: "Uploading…", isLoading: true, status: "default" });
+
+		expect(await result).toBe(3);
+		const after = store.getSnapshot();
+		expect(after).toHaveLength(1);
+		expect(after[0]).toMatchObject({
+			id: loading?.id,
+			title: "Uploaded 3 files",
+			status: "success",
+			isLoading: false,
+			revision: 1,
+		});
+	});
+
+	test("promise: loading, then error in place, and the caller still sees the rejection", async () => {
+		const { store, api } = manualStore();
+		const failure = new Error("offline");
+		const result = api.promise(Promise.reject(failure), {
+			loading: "Saving…",
+			success: "Saved",
+			error: (error) => `Failed: ${(error as Error).message}`,
+		});
+		const id = store.getSnapshot()[0]?.id;
+		await expect(result).rejects.toBe(failure);
+		expect(store.getSnapshot()[0]).toMatchObject({
+			id,
+			title: "Failed: offline",
+			status: "destructive",
+			isLoading: false,
+		});
+	});
+});

package/src/components/toast/toast.store.ts

@@ -0,0 +1,338 @@
+import type { ReactNode } from "react";
+import type { AlertStatus } from "../alert/alert.variants";
+import type { HapticFeedback } from "../pressable/pressable";
+
+/** What the toast says about what just happened — Alert's statuses, so the two read as one family. */
+export type ToastStatus = AlertStatus;
+
+/** Which edge of the screen the toast enters from and stacks against. */
+export type ToastPlacement = "top" | "bottom";
+
+/** What `toast()` returns: the toast's id and a way to hide it. */
+export type ToastHandle = {
+	id: string;
+	hide: () => void;
+};
+
+/** A single trailing action. Pressing it calls `onPress` and hides the toast. */
+export type ToastActionOptions = {
+	label: string;
+	onPress: (handle: ToastHandle) => void;
+};
+
+type ToastCommonOptions = {
+	/** Pass an existing toast's id to replace it in place rather than adding another. */
+	id?: string;
+	/** Milliseconds before it hides itself. `0` stays until hidden. Default 4000, 6000 with an action, at least 10000 under a screen reader. */
+	duration?: number;
+	/** The edge it enters from. Default `"bottom"`. */
+	placement?: ToastPlacement;
+	/** A haptic played as it appears. Defaults to the status's: success, warning, error, or none. `false` for none. */
+	haptic?: HapticFeedback | false;
+	/** Called once the toast has left the screen, however it was hidden. */
+	onHide?: () => void;
+};
+
+export type ToastOptions = ToastCommonOptions & {
+	/** Default `"default"`. Picks the glyph, the title's colour and the default haptic. */
+	status?: ToastStatus;
+	title: string;
+	description?: string;
+	action?: ToastActionOptions;
+	/** Draws a spinner for the glyph and, unless `duration` says otherwise, stays until updated. `toast.promise` sets it. */
+	isLoading?: boolean;
+};
+
+export type ToastCustomOptions = ToastCommonOptions & {
+	/** Draws the whole toast. Compose `<Toast>` inside it to keep the house look. */
+	render: (handle: ToastHandle) => ReactNode;
+};
+
+/** Anything `toast()` accepts: a title, a message, or a custom render. */
+export type ToastInput = string | ToastOptions | ToastCustomOptions;
+
+/** What `toast.update` merges in. A `title` turns a custom toast into a message; a `render` the other way. */
+export type ToastPatch = Partial<Omit<ToastOptions, "id">> & { render?: ToastCustomOptions["render"] };
+
+type ToastItemBase = {
+	id: string;
+	placement: ToastPlacement;
+	duration: number | undefined;
+	haptic: HapticFeedback | false | undefined;
+	onHide: (() => void) | undefined;
+	/** Hidden, and animating out. The viewport removes it once the exit ends. */
+	isExiting: boolean;
+	/** Bumped by every update, so the viewport restarts the clock and announces it again. */
+	revision: number;
+	/** When it was first shown, ms. */
+	createdAt: number;
+	/** Its place among toasts shown in the same tick — what the entrance stagger counts. */
+	batchIndex: number;
+};
+
+export type ToastMessageItem = ToastItemBase & {
+	kind: "message";
+	status: ToastStatus;
+	title: string;
+	description: string | undefined;
+	action: ToastActionOptions | undefined;
+	isLoading: boolean;
+};
+
+export type ToastCustomItem = ToastItemBase & {
+	kind: "custom";
+	render: ToastCustomOptions["render"];
+};
+
+/** One toast in the store. */
+export type ToastItem = ToastMessageItem | ToastCustomItem;
+
+/** Every toast, oldest first. Exiting toasts stay until the viewport removes them. */
+export type ToastState = readonly ToastItem[];
+
+export type ToastStoreAction =
+	| { type: "add"; item: ToastItem }
+	| { type: "update"; id: string; patch: ToastPatch }
+	| { type: "hide"; id: string }
+	| { type: "remove"; id: string }
+	| { type: "hideAll" };
+
+function isCustomInput(input: ToastOptions | ToastCustomOptions): input is ToastCustomOptions {
+	return "render" in input && typeof input.render === "function";
+}
+
+/** Turns whatever `toast()` was given into a store item. */
+export function normalizeToastInput(
+	input: ToastInput,
+	context: { id: string; now: number; batchIndex: number }
+): ToastItem {
+	const options: ToastOptions | ToastCustomOptions = typeof input === "string" ? { title: input } : input;
+	const base: ToastItemBase = {
+		id: options.id ?? context.id,
+		placement: options.placement ?? "bottom",
+		duration: options.duration,
+		haptic: options.haptic,
+		onHide: options.onHide,
+		isExiting: false,
+		revision: 0,
+		createdAt: context.now,
+		batchIndex: context.batchIndex,
+	};
+	if (isCustomInput(options)) return { ...base, kind: "custom", render: options.render };
+	return {
+		...base,
+		kind: "message",
+		status: options.status ?? "default",
+		title: options.title,
+		description: options.description,
+		action: options.action,
+		isLoading: options.isLoading ?? false,
+	};
+}
+
+function patchItem(item: ToastItem, patch: ToastPatch): ToastItem {
+	const base: ToastItemBase = {
+		id: item.id,
+		placement: patch.placement ?? item.placement,
+		duration: "duration" in patch ? patch.duration : item.duration,
+		haptic: "haptic" in patch ? patch.haptic : item.haptic,
+		onHide: patch.onHide ?? item.onHide,
+		isExiting: item.isExiting,
+		revision: item.revision + 1,
+		createdAt: item.createdAt,
+		batchIndex: item.batchIndex,
+	};
+	if (patch.render) return { ...base, kind: "custom", render: patch.render };
+	if (item.kind === "custom") {
+		if (patch.title === undefined) return { ...base, kind: "custom", render: item.render };
+		return {
+			...base,
+			kind: "message",
+			status: patch.status ?? "default",
+			title: patch.title,
+			description: patch.description,
+			action: patch.action,
+			isLoading: patch.isLoading ?? false,
+		};
+	}
+	return {
+		...base,
+		kind: "message",
+		status: patch.status ?? item.status,
+		title: patch.title ?? item.title,
+		description: "description" in patch ? patch.description : item.description,
+		action: "action" in patch ? patch.action : item.action,
+		isLoading: patch.isLoading ?? item.isLoading,
+	};
+}
+
+/**
+ * The store's whole behaviour, as a pure reducer.
+ *
+ * `hide` only marks a toast exiting, so the viewport can animate it out;
+ * `remove` drops it once that exit has run. An action that changes nothing
+ * returns the state it was given, so the store can skip notifying anyone.
+ */
+export function reduceToasts(state: ToastState, action: ToastStoreAction): ToastState {
+	switch (action.type) {
+		case "add": {
+			const index = state.findIndex((item) => item.id === action.item.id);
+			if (index === -1) return [...state, action.item];
+			const previous = state[index] as ToastItem;
+			const replaced: ToastItem = {
+				...action.item,
+				revision: previous.revision + 1,
+				createdAt: previous.createdAt,
+				batchIndex: previous.batchIndex,
+			};
+			return state.map((item, at) => (at === index ? replaced : item));
+		}
+		case "update": {
+			const index = state.findIndex((item) => item.id === action.id);
+			if (index === -1) return state;
+			return state.map((item, at) => (at === index ? patchItem(item, action.patch) : item));
+		}
+		case "hide": {
+			const index = state.findIndex((item) => item.id === action.id && !item.isExiting);
+			if (index === -1) return state;
+			return state.map((item, at) => (at === index ? { ...item, isExiting: true } : item));
+		}
+		case "remove": {
+			const next = state.filter((item) => item.id !== action.id);
+			return next.length === state.length ? state : next;
+		}
+		case "hideAll": {
+			if (state.every((item) => item.isExiting)) return state;
+			return state.map((item) => (item.isExiting ? item : { ...item, isExiting: true }));
+		}
+		default:
+			return state;
+	}
+}
+
+export type ToastStore = {
+	getSnapshot: () => ToastState;
+	subscribe: (listener: () => void) => () => void;
+	dispatch: (action: ToastStoreAction) => void;
+	/** Builds an item for `input`, with a fresh id and its place in this tick's batch. */
+	createItem: (input: ToastInput) => ToastItem;
+};
+
+/**
+ * A tiny external store, read with `useSyncExternalStore`.
+ *
+ * It lives outside React so `toast()` works from anywhere — an API client, a
+ * mutation's `onError` — with no provider and no hook. `schedule` closes the
+ * current batch: every toast created before it runs shares one tick, and the
+ * viewport staggers their entrances by `batchIndex`.
+ */
+export function createToastStore({
+	now = Date.now,
+	schedule = queueMicrotask,
+}: {
+	now?: () => number;
+	schedule?: (task: () => void) => void;
+} = {}): ToastStore {
+	let state: ToastState = [];
+	let counter = 0;
+	let batchSize = 0;
+	const listeners = new Set<() => void>();
+
+	return {
+		getSnapshot: () => state,
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		dispatch: (action) => {
+			const next = reduceToasts(state, action);
+			if (next === state) return;
+			state = next;
+			for (const listener of listeners) listener();
+		},
+		createItem: (input) => {
+			counter += 1;
+			if (batchSize === 0) {
+				schedule(() => {
+					batchSize = 0;
+				});
+			}
+			const batchIndex = batchSize;
+			batchSize += 1;
+			return normalizeToastInput(input, { id: `toast-${counter}`, now: now(), batchIndex });
+		},
+	};
+}
+
+type ToastShorthand = (title: string, options?: Partial<Omit<ToastOptions, "title" | "status">>) => ToastHandle;
+
+/** The messages `toast.promise` shows while the promise is pending, and once it settles. */
+export type ToastPromiseMessages<T> = {
+	loading: string;
+	success: string | ((value: T) => string);
+	error: string | ((error: unknown) => string);
+};
+
+/** `toast` — callable with a title or options, and a namespace for the rest. */
+export type ToastApi = {
+	(input: ToastInput): ToastHandle;
+	show: (input: ToastInput) => ToastHandle;
+	success: ToastShorthand;
+	info: ToastShorthand;
+	warning: ToastShorthand;
+	/** A `destructive` toast. */
+	error: ToastShorthand;
+	update: (id: string, patch: ToastPatch) => void;
+	hide: (id: string) => void;
+	hideAll: () => void;
+	/** One toast that says "loading" and becomes the success or the error in place. Resolves or rejects with `promise`. */
+	promise: <T>(promise: Promise<T>, messages: ToastPromiseMessages<T>) => Promise<T>;
+};
+
+/** The `toast` function over a store. The library's `toast` is this over one module-level store. */
+export function createToastApi(store: ToastStore): ToastApi {
+	const hide = (id: string): void => store.dispatch({ type: "hide", id });
+	const handleOf = (id: string): ToastHandle => ({ id, hide: () => hide(id) });
+
+	const show = (input: ToastInput): ToastHandle => {
+		const item = store.createItem(input);
+		store.dispatch({ type: "add", item });
+		return handleOf(item.id);
+	};
+
+	const shorthand =
+		(status: ToastStatus): ToastShorthand =>
+		(title, options) =>
+			show({ ...options, title, status });
+
+	const update = (id: string, patch: ToastPatch): void => store.dispatch({ type: "update", id, patch });
+
+	function promise<T>(pending: Promise<T>, messages: ToastPromiseMessages<T>): Promise<T> {
+		const { id } = show({ title: messages.loading, isLoading: true });
+		pending.then(
+			(value) => {
+				const title = typeof messages.success === "function" ? messages.success(value) : messages.success;
+				update(id, { status: "success", title, isLoading: false });
+			},
+			(error: unknown) => {
+				const title = typeof messages.error === "function" ? messages.error(error) : messages.error;
+				update(id, { status: "destructive", title, isLoading: false });
+			}
+		);
+		return pending;
+	}
+
+	return Object.assign(show, {
+		show,
+		success: shorthand("success"),
+		info: shorthand("info"),
+		warning: shorthand("warning"),
+		error: shorthand("destructive"),
+		update,
+		hide,
+		hideAll: () => store.dispatch({ type: "hideAll" }),
+		promise,
+	});
+}

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

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import {
+	createToastTimer,
+	isToastTimerExpired,
+	isToastTimerRunning,
+	pauseToastTimer,
+	resumeToastTimer,
+	startToastTimer,
+	toastTimerRemaining,
+} from "./toast.timer";
+
+describe("toast timer", () => {
+	test("a new timer holds its whole duration and is not running", () => {
+		const timer = createToastTimer(4000);
+		expect(timer).toEqual({ remaining: 4000, startedAt: null });
+		expect(isToastTimerRunning(timer)).toBe(false);
+	});
+
+	test("expires once its duration has run", () => {
+		const timer = startToastTimer(createToastTimer(4000), 1000);
+		expect(isToastTimerRunning(timer)).toBe(true);
+		expect(isToastTimerExpired(timer, 4999)).toBe(false);
+		expect(isToastTimerExpired(timer, 5000)).toBe(true);
+		expect(toastTimerRemaining(timer, 2500)).toBe(2500);
+	});
+
+	test("pausing keeps the time left, and resuming carries on from it", () => {
+		const running = startToastTimer(createToastTimer(4000), 0);
+		const paused = pauseToastTimer(running, 1500);
+		expect(paused).toEqual({ remaining: 2500, startedAt: null });
+
+		// However long it sits paused, nothing is spent.
+		expect(isToastTimerExpired(paused, 60_000)).toBe(false);
+		expect(toastTimerRemaining(paused, 60_000)).toBe(2500);
+
+		const resumed = resumeToastTimer(paused, 60_000);
+		expect(isToastTimerExpired(resumed, 62_499)).toBe(false);
+		expect(isToastTimerExpired(resumed, 62_500)).toBe(true);
+	});
+
+	test("pausing twice spends nothing the second time", () => {
+		const paused = pauseToastTimer(startToastTimer(createToastTimer(4000), 0), 1000);
+		expect(pauseToastTimer(paused, 3000)).toBe(paused);
+	});
+
+	test("resuming a running timer does not restart it", () => {
+		const running = startToastTimer(createToastTimer(4000), 0);
+		expect(resumeToastTimer(running, 3000)).toBe(running);
+	});
+
+	test("remaining never drops below zero", () => {
+		const paused = pauseToastTimer(startToastTimer(createToastTimer(1000), 0), 5000);
+		expect(paused.remaining).toBe(0);
+		expect(isToastTimerExpired(paused, 5000)).toBe(true);
+	});
+
+	test("a zero duration never expires, running or paused", () => {
+		const running = startToastTimer(createToastTimer(0), 0);
+		expect(isToastTimerExpired(running, Number.MAX_SAFE_INTEGER)).toBe(false);
+		expect(toastTimerRemaining(running, 1_000_000)).toBe(Number.POSITIVE_INFINITY);
+		const paused = pauseToastTimer(running, 1_000_000);
+		expect(isToastTimerExpired(resumeToastTimer(paused, 2_000_000), Number.MAX_SAFE_INTEGER)).toBe(false);
+	});
+});