@remit/web-client 0.0.1

package/src/components/ui/ErrorState.tsx

@@ -0,0 +1,80 @@
+import { AlertCircle } from "lucide-react";
+
+interface ErrorStateProps {
+	title?: string;
+	error: unknown;
+	onRetry?: () => void;
+	variant?: "block" | "inline";
+}
+
+export const formatErrorMessage = (error: unknown): string => {
+	if (error instanceof Error) return error.message;
+	if (typeof error === "string") return error;
+	if (
+		typeof error === "object" &&
+		error !== null &&
+		"message" in error &&
+		typeof (error as { message: unknown }).message === "string"
+	) {
+		return (error as { message: string }).message;
+	}
+	return "An unexpected error occurred";
+};
+
+export const ErrorState = ({
+	title = "Couldn't load content",
+	error,
+	onRetry,
+	variant = "block",
+}: ErrorStateProps) => {
+	const message = formatErrorMessage(error);
+
+	if (variant === "inline") {
+		return (
+			<div
+				role="alert"
+				className="flex items-start gap-2 rounded-md border border-danger/40 bg-danger-soft px-3 py-2 text-sm"
+			>
+				<AlertCircle
+					className="size-4 shrink-0 text-danger mt-0.5"
+					aria-hidden="true"
+				/>
+				<div className="flex-1 min-w-0">
+					<p className="font-medium text-danger">{title}</p>
+					<p className="text-fg-muted mt-0.5 break-words">{message}</p>
+				</div>
+				{onRetry && (
+					<button
+						type="button"
+						onClick={onRetry}
+						className="shrink-0 text-sm font-medium text-accent hover:underline"
+					>
+						Retry
+					</button>
+				)}
+			</div>
+		);
+	}
+
+	return (
+		<div
+			role="alert"
+			className="flex flex-col items-center justify-center gap-3 p-8 text-center"
+		>
+			<AlertCircle className="size-8 text-danger" aria-hidden="true" />
+			<div>
+				<p className="font-medium text-danger">{title}</p>
+				<p className="text-sm text-fg-muted mt-1 break-words">{message}</p>
+			</div>
+			{onRetry && (
+				<button
+					type="button"
+					onClick={onRetry}
+					className="inline-flex items-center rounded-md border border-line bg-canvas px-4 py-2 text-sm font-medium hover:bg-surface-raised transition-colors"
+				>
+					Retry
+				</button>
+			)}
+		</div>
+	);
+};

package/src/components/ui/FatalErrorOverlay.render.test.ts

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import type { FatalError } from "@/lib/fatal-error";
+import { FatalErrorScreen } from "./FatalErrorOverlay";
+
+const recoverableFatal: FatalError = {
+	error: new Error("Request failed with status 500"),
+	message: "Request failed with status 500",
+	correlationId: "abc-123",
+	at: 0,
+	recoverable: true,
+};
+
+const deterministicFatal: FatalError = {
+	error: new Error("date value is not finite in DateTimeFormat format()"),
+	message: "date value is not finite in DateTimeFormat format()",
+	correlationId: "def-456",
+	at: 0,
+	recoverable: false,
+	stack: "Error: date value is not finite\n    at format",
+	componentStack: "\n    at AccountsSettings\n    at Route",
+};
+
+const render = (fatal: FatalError): string =>
+	renderToString(createElement(FatalErrorScreen, { fatal }) as never);
+
+describe("FatalErrorScreen — the full-screen red escalation page", () => {
+	it("renders a loud red full-screen overlay (not a benign grey label)", () => {
+		const html = render(recoverableFatal);
+		assert.match(html, /data-testid="fatal-error-overlay"/);
+		assert.match(html, /bg-red-700/);
+		assert.match(html, /fixed inset-0/);
+		assert.match(html, /role="alert"/);
+	});
+
+	it("shows the error message and correlation reference", () => {
+		const html = render(recoverableFatal);
+		assert.match(html, /Request failed with status 500/);
+		assert.match(html, /abc-123/);
+	});
+
+	it("always offers Report a bug and Copy full details", () => {
+		for (const fatal of [recoverableFatal, deterministicFatal]) {
+			const html = render(fatal);
+			assert.match(html, /Report a bug/);
+			assert.match(html, /Copy full details/);
+		}
+	});
+});
+
+describe("FatalErrorScreen — recoverable vs fatal affordances", () => {
+	it("a recoverable error offers Retry and no dead-end safe-route link", () => {
+		const html = render(recoverableFatal);
+		assert.match(html, /Retry/);
+		assert.doesNotMatch(html, /Go to inbox/);
+	});
+
+	it("a deterministic fatal offers a safe route out — never a re-crashing Retry", () => {
+		const html = render(deterministicFatal);
+		assert.doesNotMatch(html, />Retry</);
+		assert.match(html, /Go to inbox/);
+		assert.match(html, /href="\/mail"/);
+	});
+});

package/src/components/ui/FatalErrorOverlay.tsx

@@ -0,0 +1,151 @@
+import { AlertOctagon } from "lucide-react";
+import { useEffect, useState } from "react";
+import {
+	type BugReportSeed,
+	buildBugReportContext,
+	buildBugReportDetails,
+	buildGitHubIssueUrl,
+} from "@/lib/bug-report";
+import {
+	type FatalError,
+	getCurrentFatalError,
+	subscribeFatalError,
+} from "@/lib/fatal-error";
+
+/** Safe route to escape a deterministically-crashing page. `/` redirects here. */
+const SAFE_ROUTE = "/mail";
+
+/**
+ * The full-screen red escalation page. A first-party fatal — an escalated 5xx,
+ * or a render exception caught by the route error boundary — takes over the
+ * entire viewport here: loud, red, impossible to miss. Never a benign grey
+ * label.
+ *
+ * It is intentionally NOT dismissible: a fatal means the app is in an unknown
+ * state. The affordances depend on whether the error is recoverable:
+ *  - recoverable (transient 5xx / network / abort) → Retry the same action.
+ *  - fatal (deterministic render exception) → NO Retry (it re-crashes); offer a
+ *    way out to a safe route instead.
+ * Both states can Report a bug (prefilled with the stacktrace) and Copy full
+ * details.
+ */
+export const FatalErrorOverlay = () => {
+	const [fatal, setFatal] = useState<FatalError | null>(() =>
+		getCurrentFatalError(),
+	);
+
+	useEffect(() => subscribeFatalError(setFatal), []);
+
+	if (!fatal) return null;
+
+	return <FatalErrorScreen fatal={fatal} />;
+};
+
+interface FatalErrorScreenProps {
+	fatal: FatalError;
+	/**
+	 * What Retry does for a recoverable error. The route error boundary passes
+	 * TanStack's `reset`; without it, Retry reloads the page. Ignored for a
+	 * non-recoverable fatal (no Retry is shown).
+	 */
+	onRetry?: () => void;
+}
+
+const seedFromFatal = (fatal: FatalError): BugReportSeed => ({
+	errorMessage: fatal.message,
+	stack: fatal.stack,
+	componentStack: fatal.componentStack,
+});
+
+/**
+ * Presentational screen — exported so it can be rendered directly in tests and
+ * by the route-level error boundary without going through the subscription.
+ */
+export const FatalErrorScreen = ({ fatal, onRetry }: FatalErrorScreenProps) => {
+	const [copied, setCopied] = useState(false);
+
+	const handleReload = () => {
+		window.location.reload();
+	};
+
+	const handleRetry = () => {
+		if (onRetry) {
+			onRetry();
+			return;
+		}
+		handleReload();
+	};
+
+	const handleReportBug = () => {
+		const url = buildGitHubIssueUrl(
+			buildBugReportContext(seedFromFatal(fatal)),
+		);
+		window.open(url, "_blank", "noopener,noreferrer");
+	};
+
+	const handleCopyDetails = async () => {
+		const details = buildBugReportDetails(
+			buildBugReportContext(seedFromFatal(fatal)),
+		);
+		await navigator.clipboard.writeText(details);
+		setCopied(true);
+		window.setTimeout(() => setCopied(false), 2000);
+	};
+
+	const description = fatal.recoverable
+		? "The server returned an unexpected error. This is not your fault — nothing was saved or sent. Retry, or report a bug so we can fix it."
+		: "Something went wrong and this page can't recover. This is not your fault — nothing was saved or sent. Go to your inbox, or report a bug so we can fix it.";
+
+	return (
+		<div
+			role="alert"
+			aria-live="assertive"
+			data-testid="fatal-error-overlay"
+			className="fixed inset-0 z-[1000] flex flex-col items-center justify-center gap-6 bg-red-700 p-6 text-center text-white"
+		>
+			<AlertOctagon className="size-16 shrink-0" aria-hidden="true" />
+			<div className="max-w-lg space-y-3">
+				<h1 className="text-2xl font-bold tracking-tight">Something broke</h1>
+				<p className="text-base text-red-50">{description}</p>
+				<p className="break-words font-mono text-sm text-red-100">
+					{fatal.message}
+				</p>
+				<p className="font-mono text-xs text-red-200">
+					Reference: {fatal.correlationId}
+				</p>
+			</div>
+			<div className="flex flex-wrap items-center justify-center gap-3">
+				{fatal.recoverable ? (
+					<button
+						type="button"
+						onClick={handleRetry}
+						className="inline-flex min-h-11 items-center rounded-md bg-white px-5 text-sm font-semibold text-red-700 transition-colors hover:bg-red-50"
+					>
+						Retry
+					</button>
+				) : (
+					<a
+						href={SAFE_ROUTE}
+						className="inline-flex min-h-11 items-center rounded-md bg-white px-5 text-sm font-semibold text-red-700 transition-colors hover:bg-red-50"
+					>
+						Go to inbox
+					</a>
+				)}
+				<button
+					type="button"
+					onClick={handleReportBug}
+					className="inline-flex min-h-11 items-center rounded-md border border-white/70 px-5 text-sm font-semibold text-white transition-colors hover:bg-white/10"
+				>
+					Report a bug
+				</button>
+				<button
+					type="button"
+					onClick={handleCopyDetails}
+					className="inline-flex min-h-11 items-center rounded-md border border-white/70 px-5 text-sm font-semibold text-white transition-colors hover:bg-white/10"
+				>
+					{copied ? "Copied" : "Copy full details"}
+				</button>
+			</div>
+		</div>
+	);
+};

package/src/components/ui/KeyboardShortcutsModal.tsx

@@ -0,0 +1,120 @@
+import { Kbd } from "@remit/ui";
+import { X } from "lucide-react";
+import { Fragment, useCallback, useEffect } from "react";
+import { KEY_HINT_GROUPS } from "@/lib/keymap";
+import { cn } from "@/lib/utils";
+
+interface KeyboardShortcutsModalProps {
+	isOpen: boolean;
+	onClose: () => void;
+}
+
+/**
+ * The `?` help overlay (#429). Renders the full triage key map from the single
+ * source of truth (`@/lib/keymap`) using the remit-ui `Kbd` component, so the
+ * displayed bindings can never drift from what the dispatcher actually routes.
+ */
+export const KeyboardShortcutsModal = ({
+	isOpen,
+	onClose,
+}: KeyboardShortcutsModalProps) => {
+	// Close on Escape
+	const handleKeyDown = useCallback(
+		(event: KeyboardEvent) => {
+			if (event.key === "Escape") {
+				event.preventDefault();
+				onClose();
+			}
+		},
+		[onClose],
+	);
+
+	useEffect(() => {
+		if (!isOpen) return;
+		window.addEventListener("keydown", handleKeyDown);
+		return () => window.removeEventListener("keydown", handleKeyDown);
+	}, [isOpen, handleKeyDown]);
+
+	if (!isOpen) return null;
+
+	return (
+		<div
+			className="fixed inset-0 z-50 flex items-center justify-center"
+			role="dialog"
+			aria-modal="true"
+			aria-label="Keyboard shortcuts"
+			onClick={onClose}
+			onKeyDown={(e) => e.key === "Escape" && onClose()}
+		>
+			{/* Backdrop */}
+			<div className="absolute inset-0 bg-canvas/80 backdrop-blur-sm" />
+
+			{/* Modal */}
+			{/* biome-ignore lint/a11y/noStaticElementInteractions: stops event propagation from the modal content; keyboard is handled by the outer wrapper */}
+			<div
+				className={cn(
+					"relative z-10 max-h-[85vh] w-full max-w-2xl overflow-y-auto",
+					"rounded-lg border border-line bg-surface shadow-lg",
+					"p-6",
+				)}
+				onClick={(e) => e.stopPropagation()}
+				onKeyDown={(e) => {
+					if (e.key !== "Escape") e.stopPropagation();
+				}}
+			>
+				{/* Header */}
+				<div className="mb-6 flex items-center justify-between">
+					<h2 className="text-lg font-semibold">Keyboard shortcuts</h2>
+					<button
+						type="button"
+						onClick={onClose}
+						className="p-1 text-fg-muted transition-colors hover:text-fg"
+						aria-label="Close"
+					>
+						<X className="size-5" />
+					</button>
+				</div>
+
+				{/* Sections — two columns on wider modals */}
+				<div className="grid gap-x-8 gap-y-6 sm:grid-cols-2">
+					{KEY_HINT_GROUPS.map((group) => (
+						<div key={group.title}>
+							<h3 className="mb-3 text-sm font-medium text-fg-muted">
+								{group.title}
+							</h3>
+							<div className="space-y-2">
+								{group.hints.map((hint) => (
+									<div
+										key={`${hint.action}-${hint.keys.join("+")}`}
+										className="flex items-center justify-between gap-4"
+									>
+										<span className="text-sm">{hint.description}</span>
+										<span className="flex shrink-0 items-center gap-1">
+											{hint.keys.map((key, index) => (
+												<Fragment key={key}>
+													{index > 0 && hint.keys[0] === "g" && (
+														<span className="text-2xs text-fg-subtle">
+															then
+														</span>
+													)}
+													<Kbd>{key}</Kbd>
+												</Fragment>
+											))}
+										</span>
+									</div>
+								))}
+							</div>
+						</div>
+					))}
+				</div>
+
+				{/* Footer */}
+				<div className="mt-6 border-t border-line pt-4">
+					<p className="text-center text-xs text-fg-muted">
+						Press <Kbd>Esc</Kbd> to close
+					</p>
+				</div>
+			</div>
+		</div>
+	);
+};

package/src/components/ui/SlidePanel.tsx

@@ -0,0 +1,72 @@
+import { X } from "lucide-react";
+import type { ReactNode } from "react";
+import { cn } from "../../lib/utils";
+
+interface SlidePanelProps {
+	isOpen: boolean;
+	onClose: () => void;
+	title: string;
+	children: ReactNode;
+	footer?: ReactNode;
+}
+
+export const SlidePanel = ({
+	isOpen,
+	onClose,
+	title,
+	children,
+	footer,
+}: SlidePanelProps) => (
+	<>
+		{/* Backdrop overlay */}
+		{/* biome-ignore lint/a11y/useSemanticElements: full-screen backdrop overlay; <button> default styles would break fixed inset positioning */}
+		<div
+			className={cn(
+				"fixed inset-0 bg-black/30 z-40 transition-opacity",
+				isOpen ? "opacity-100" : "opacity-0 pointer-events-none",
+			)}
+			onClick={onClose}
+			onKeyDown={(e) => e.key === "Escape" && onClose()}
+			role="button"
+			tabIndex={0}
+			aria-label="Close panel"
+		/>
+
+		{/* Slide-in panel */}
+		<div
+			className={cn(
+				"fixed top-0 right-0 h-full w-full sm:w-[400px] sm:max-w-[90vw] bg-canvas border-l border-line shadow-xl z-50",
+				"transform transition-transform duration-200 ease-out",
+				isOpen ? "translate-x-0" : "translate-x-full",
+			)}
+			role="dialog"
+			aria-modal="true"
+			aria-labelledby="slide-panel-title"
+		>
+			{/* Panel header */}
+			<div className="flex items-center justify-between px-4 h-14 border-b border-line">
+				<h2 id="slide-panel-title" className="font-semibold">
+					{title}
+				</h2>
+				<button
+					type="button"
+					onClick={onClose}
+					className="p-1.5 rounded-md hover:bg-surface-raised transition-colors"
+					aria-label="Close"
+				>
+					<X className="size-5" />
+				</button>
+			</div>
+
+			{/* Panel content */}
+			<div className="h-[calc(100%-3.5rem)] flex flex-col">
+				<div className="flex-1 overflow-auto p-4">{children}</div>
+				{footer && (
+					<div className="flex justify-end gap-3 p-4 border-t border-line bg-canvas">
+						{footer}
+					</div>
+				)}
+			</div>
+		</div>
+	</>
+);

package/src/components/ui/error-banners.test.ts

@@ -0,0 +1,207 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import {
+	appendBanner,
+	buildEntry,
+	buildMutationErrorBanner,
+	dismissBanner,
+	type ErrorBannerEntry,
+	formatErrorDetail,
+	isMessageNotFoundError,
+} from "./error-banners.js";
+
+const make = (
+	overrides: Partial<ErrorBannerEntry> & { id: string },
+): ErrorBannerEntry => ({
+	severity: "error",
+	title: "default",
+	detail: undefined,
+	createdAt: 0,
+	...overrides,
+});
+
+describe("buildEntry", () => {
+	test("defaults to error severity", () => {
+		const entry = buildEntry({ title: "boom" }, "id-1", 1000);
+		assert.equal(entry.severity, "error");
+		assert.equal(entry.title, "boom");
+		assert.equal(entry.id, "id-1");
+		assert.equal(entry.createdAt, 1000);
+	});
+
+	test("preserves explicit severity and detail", () => {
+		const entry = buildEntry(
+			{ severity: "warning", title: "watch", detail: "context" },
+			"id-2",
+			2000,
+		);
+		assert.equal(entry.severity, "warning");
+		assert.equal(entry.detail, "context");
+	});
+});
+
+describe("appendBanner", () => {
+	test("adds an entry at the end of the stack", () => {
+		const a = make({ id: "1", title: "first" });
+		const b = make({ id: "2", title: "second" });
+		const got = appendBanner([a], b);
+		assert.deepStrictEqual(
+			got.map((e) => e.id),
+			["1", "2"],
+		);
+	});
+
+	test("dedupes entries with the same severity, title and detail", () => {
+		const a = make({
+			id: "1",
+			title: "Couldn't mark as read",
+			detail: "Network error",
+		});
+		const b = make({
+			id: "2",
+			title: "Couldn't mark as read",
+			detail: "Network error",
+		});
+		const got = appendBanner([a], b);
+		assert.equal(got.length, 1);
+		assert.equal(got[0]?.id, "2");
+	});
+
+	test("keeps differing detail as separate banners", () => {
+		const a = make({
+			id: "1",
+			title: "Couldn't mark as read",
+			detail: "Network error",
+		});
+		const b = make({
+			id: "2",
+			title: "Couldn't mark as read",
+			detail: "Server error",
+		});
+		const got = appendBanner([a], b);
+		assert.equal(got.length, 2);
+	});
+
+	test("caps the stack at 5 by dropping the oldest", () => {
+		let stack: ErrorBannerEntry[] = [];
+		for (let i = 0; i < 7; i++) {
+			stack = appendBanner(
+				stack,
+				make({ id: `${i}`, title: `t${i}`, createdAt: i }),
+			);
+		}
+		assert.equal(stack.length, 5);
+		assert.deepStrictEqual(
+			stack.map((e) => e.id),
+			["2", "3", "4", "5", "6"],
+		);
+	});
+});
+
+describe("dismissBanner", () => {
+	test("removes the matching entry and leaves the rest in order", () => {
+		const stack = [make({ id: "1" }), make({ id: "2" }), make({ id: "3" })];
+		const got = dismissBanner(stack, "2");
+		assert.deepStrictEqual(
+			got.map((e) => e.id),
+			["1", "3"],
+		);
+	});
+
+	test("returns the same shape when the id is unknown", () => {
+		const stack = [make({ id: "1" })];
+		const got = dismissBanner(stack, "nope");
+		assert.equal(got.length, 1);
+	});
+});
+
+describe("formatErrorDetail", () => {
+	test("returns the message of an Error", () => {
+		assert.equal(formatErrorDetail(new Error("boom")), "boom");
+	});
+
+	test("returns a non-empty string as-is", () => {
+		assert.equal(formatErrorDetail("nope"), "nope");
+	});
+
+	test("returns undefined for empty strings", () => {
+		assert.equal(formatErrorDetail(""), undefined);
+	});
+
+	test("reads object .message", () => {
+		assert.equal(formatErrorDetail({ message: "shape" }), "shape");
+	});
+
+	test("returns undefined for null/undefined", () => {
+		assert.equal(formatErrorDetail(null), undefined);
+		assert.equal(formatErrorDetail(undefined), undefined);
+	});
+
+	test("returns undefined when nothing matches", () => {
+		assert.equal(formatErrorDetail(42), undefined);
+		assert.equal(formatErrorDetail({}), undefined);
+	});
+});
+
+describe("isMessageNotFoundError (#212)", () => {
+	// Regression: clicking a stale inbox row used to hit `describeMessage`
+	// and surface the raw "Message not found: <id>" string. The frontend now
+	// detects that error shape and shows a "deleted" empty state.
+
+	test("matches the backend's NotFoundError JSON body", () => {
+		assert.equal(
+			isMessageNotFoundError({
+				message: "Message not found: alice-msg-aaaaaaa",
+			}),
+			true,
+		);
+	});
+
+	test("matches an Error instance with the same message", () => {
+		assert.equal(
+			isMessageNotFoundError(new Error("Message not found: bob-msg-aaaaaaa")),
+			true,
+		);
+	});
+
+	test("does not match unrelated errors", () => {
+		assert.equal(
+			isMessageNotFoundError({ message: "Mailbox not found: x" }),
+			false,
+		);
+		assert.equal(isMessageNotFoundError(new Error("boom")), false);
+		assert.equal(isMessageNotFoundError(null), false);
+		assert.equal(isMessageNotFoundError(undefined), false);
+		assert.equal(isMessageNotFoundError({}), false);
+	});
+});
+
+describe("buildMutationErrorBanner — previously-silent mutations now surface", () => {
+	test("uses the server error message when present (real detail, not a dot)", () => {
+		const banner = buildMutationErrorBanner(
+			"Couldn't save signature",
+			"The signature wasn't saved.",
+			new Error("Address already in use"),
+		);
+		assert.equal(banner.title, "Couldn't save signature");
+		assert.equal(banner.detail, "Address already in use");
+	});
+
+	test("falls back to a human message when the error carries none", () => {
+		const banner = buildMutationErrorBanner(
+			"Couldn't discard draft",
+			"The draft wasn't deleted.",
+			{},
+		);
+		assert.equal(banner.detail, "The draft wasn't deleted.");
+	});
+
+	test("reads .message off a plain object error body", () => {
+		const banner = buildMutationErrorBanner(
+			"Couldn't resend message",
+			"The message wasn't sent.",
+			{ message: "SMTP relay refused" },
+		);
+		assert.equal(banner.detail, "SMTP relay refused");
+	});
+});