@remit/web-client 0.0.1

package/src/components/mail/OutboxPane.tsx

@@ -0,0 +1,531 @@
+/**
+ * OutboxPane — compound component for the outbox view (/mail/outbox route).
+ *
+ * Usage in mail.tsx:
+ *
+ *   <OutboxPane>
+ *     <AppShellSlotted
+ *       list={<OutboxPane.List />}
+ *       reading={<OutboxPane.Reading />}
+ *     />
+ *   </OutboxPane>
+ *
+ * On phone/tablet, use `<OutboxPane.Phone />` instead of the slot sub-views.
+ */
+import {
+	outboxDetailOperationsDeleteOutboxMessageMutation,
+	outboxDetailOperationsSendOutboxMessageMutation,
+	outboxOperationsListOutboxMessagesOptions,
+	outboxOperationsListOutboxMessagesQueryKey,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type {
+	RemitImapOutboxMessageResponse,
+	RemitImapOutboxMessageStatus,
+} from "@remit/api-http-client/types.gen.ts";
+import { OutboxRow, ReadingPaneEmpty } from "@remit/ui";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useNavigate, useSearch } from "@tanstack/react-router";
+import {
+	AlertCircle,
+	AlertTriangle,
+	ArrowLeft,
+	CheckCircle,
+	Clock,
+	Loader2,
+	Send,
+} from "lucide-react";
+import {
+	createContext,
+	type ReactNode,
+	useCallback,
+	useContext,
+	useMemo,
+} from "react";
+import { useCompose } from "@/components/compose/ComposeProvider";
+import { MessageBody } from "@/components/mail/MessageBody";
+import { NavMenuButton } from "@/components/mail/NavMenuButton";
+import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
+import { buildMutationErrorBanner } from "@/components/ui/error-banners";
+import { formatDate as formatLocaleDate, toDate } from "@/lib/format";
+import { isOutboxListRow, isUnsendableStatus } from "@/lib/outbox-status";
+import { cn } from "@/lib/utils";
+
+/* ------------------------------------------------------------------ */
+/* Helpers (shared between List, Reading, Phone sub-views)             */
+/* ------------------------------------------------------------------ */
+
+const STATUS_CONFIG: Record<
+	Exclude<RemitImapOutboxMessageStatus, "draft">,
+	{ icon: typeof Send; label: string; className: string }
+> = {
+	queued: {
+		icon: Clock,
+		label: "Queued",
+		className: "text-warning",
+	},
+	sending: {
+		icon: Loader2,
+		label: "Sending…",
+		className: "text-accent-2",
+	},
+	sent: {
+		icon: CheckCircle,
+		label: "Sent",
+		className: "text-positive",
+	},
+	failed: {
+		icon: AlertCircle,
+		label: "Failed",
+		className: "text-danger",
+	},
+	blocked: {
+		icon: AlertTriangle,
+		label: "Blocked",
+		className: "text-warning",
+	},
+};
+
+const formatDate = (timestamp: number): string => {
+	const date = toDate(timestamp);
+	const isToday = date.toDateString() === new Date().toDateString();
+	return isToday
+		? formatLocaleDate(timestamp, { hour: "numeric", minute: "2-digit" })
+		: formatLocaleDate(timestamp, { month: "short", day: "numeric" });
+};
+
+const formatDateFull = (timestamp: number): string =>
+	formatLocaleDate(timestamp, { dateStyle: "medium", timeStyle: "short" });
+
+const formatRecipients = (message: RemitImapOutboxMessageResponse): string => {
+	const recipients = message.toAddresses ?? [];
+	if (recipients.length === 0) return "No recipients";
+	if (recipients.length === 1) return recipients[0];
+	return `${recipients[0]} +${recipients.length - 1}`;
+};
+
+/* ------------------------------------------------------------------ */
+/* Context                                                              */
+/* ------------------------------------------------------------------ */
+
+interface OutboxPaneContextValue {
+	messages: RemitImapOutboxMessageResponse[];
+	isLoading: boolean;
+	selectedMessageId: string | undefined;
+	selectedMessage: RemitImapOutboxMessageResponse | undefined;
+	onSelectMessage: (id: string | undefined) => void;
+}
+
+const OutboxPaneCtx = createContext<OutboxPaneContextValue | null>(null);
+
+function useOutboxPane(): OutboxPaneContextValue {
+	const ctx = useContext(OutboxPaneCtx);
+	if (!ctx) throw new Error("OutboxPane.* must be used inside <OutboxPane>");
+	return ctx;
+}
+
+/* ------------------------------------------------------------------ */
+/* Provider                                                             */
+/* ------------------------------------------------------------------ */
+
+interface OutboxPaneProps {
+	children: ReactNode;
+}
+
+function OutboxPaneProvider({ children }: OutboxPaneProps) {
+	const navigate = useNavigate();
+	// Read selectedOutboxMessageId from the URL directly — this avoids threading
+	// a prop through the parent shell for a param that only outbox uses.
+	const { selectedOutboxMessageId: selectedMessageId } = useSearch({
+		strict: false,
+	}) as { selectedOutboxMessageId?: string };
+
+	const { data: outboxResponse, isLoading } = useQuery(
+		outboxOperationsListOutboxMessagesOptions(),
+	);
+
+	// Outbox surfaces in-flight + actionable rows only. `draft` lives in the
+	// Drafts view; `sent` rows are deleted by the IMAP append handler once
+	// the message lands in Sent (issue #178), but we filter defensively so a
+	// successfully-sent row never lingers in the Outbox list even if APPEND
+	// has not completed yet (issue #193).
+	const messages = useMemo(
+		() =>
+			(outboxResponse?.items ?? []).filter((item) =>
+				isOutboxListRow(item.status),
+			),
+		[outboxResponse],
+	);
+
+	const selectedMessage = useMemo(
+		() => messages.find((m) => m.outboxMessageId === selectedMessageId),
+		[messages, selectedMessageId],
+	);
+
+	const handleSelectMessage = useCallback(
+		(id: string | undefined) => {
+			navigate({
+				to: "/mail/outbox",
+				search: (prev) => ({
+					...prev,
+					selectedOutboxMessageId: id,
+				}),
+			});
+		},
+		[navigate],
+	);
+
+	const ctx: OutboxPaneContextValue = {
+		messages,
+		isLoading,
+		selectedMessageId,
+		selectedMessage,
+		onSelectMessage: handleSelectMessage,
+	};
+
+	return (
+		<OutboxPaneCtx.Provider value={ctx}>{children}</OutboxPaneCtx.Provider>
+	);
+}
+
+/* ------------------------------------------------------------------ */
+/* Row component                                                        */
+/* ------------------------------------------------------------------ */
+
+interface OutboxMessageRowProps {
+	message: RemitImapOutboxMessageResponse;
+	isSelected: boolean;
+	onSelect: () => void;
+}
+
+function OutboxMessageRow({
+	message,
+	isSelected,
+	onSelect,
+}: OutboxMessageRowProps) {
+	const queryClient = useQueryClient();
+	const { openCompose } = useCompose();
+	const { pushError } = useErrorBanners();
+
+	const invalidateOutbox = useCallback(() => {
+		queryClient.invalidateQueries({
+			queryKey: outboxOperationsListOutboxMessagesQueryKey(),
+		});
+	}, [queryClient]);
+
+	const retryMutation = useMutation({
+		...outboxDetailOperationsSendOutboxMessageMutation(),
+		onSuccess: invalidateOutbox,
+		onError: (error) => {
+			// A failed retry must not look successful — surface it. A fatal 5xx
+			// also escalates through the global MutationCache.onError sink.
+			pushError(
+				buildMutationErrorBanner(
+					"Couldn't resend message",
+					"The message wasn't sent.",
+					error,
+				),
+			);
+		},
+	});
+
+	const deleteMutation = useMutation({
+		...outboxDetailOperationsDeleteOutboxMessageMutation(),
+		onSuccess: invalidateOutbox,
+		onError: (error) => {
+			pushError(
+				buildMutationErrorBanner(
+					"Couldn't delete message",
+					"The message wasn't deleted.",
+					error,
+				),
+			);
+		},
+	});
+
+	const status = message.status as Exclude<
+		RemitImapOutboxMessageStatus,
+		"draft"
+	>;
+	if (!STATUS_CONFIG[status]) return null;
+
+	const showError = isUnsendableStatus(message.status);
+
+	return (
+		<OutboxRow
+			recipients={formatRecipients(message)}
+			subject={message.subject || ""}
+			time={formatDate(message.sentAt ?? message.updatedAt)}
+			status={status}
+			error={showError ? (message.lastError ?? undefined) : undefined}
+			selected={isSelected}
+			onSelect={onSelect}
+			onRetry={
+				status === "failed"
+					? () =>
+							retryMutation.mutate({
+								path: { outboxMessageId: message.outboxMessageId },
+							})
+					: undefined
+			}
+			retrying={retryMutation.isPending}
+			onEdit={() =>
+				openCompose({
+					mode: "new",
+					outboxMessageId: message.outboxMessageId,
+				})
+			}
+			onDelete={() =>
+				deleteMutation.mutate({
+					path: { outboxMessageId: message.outboxMessageId },
+				})
+			}
+			deleting={deleteMutation.isPending}
+		/>
+	);
+}
+
+/* ------------------------------------------------------------------ */
+/* Detail component                                                     */
+/* ------------------------------------------------------------------ */
+
+interface OutboxMessageDetailProps {
+	message: RemitImapOutboxMessageResponse;
+	onBack?: () => void;
+}
+
+function OutboxMessageDetail({ message, onBack }: OutboxMessageDetailProps) {
+	const status = message.status as Exclude<
+		RemitImapOutboxMessageStatus,
+		"draft"
+	>;
+	const config = STATUS_CONFIG[status];
+	const StatusIcon = config?.icon ?? Send;
+	const sentLabel = message.sentAt
+		? formatDateFull(message.sentAt)
+		: formatDateFull(message.updatedAt);
+
+	return (
+		<div className="h-full overflow-y-auto bg-canvas">
+			<div className="border-b border-line p-4">
+				{onBack && (
+					<button
+						type="button"
+						onClick={onBack}
+						className="mb-3 inline-flex items-center gap-1 text-sm text-fg-muted hover:text-fg"
+					>
+						<ArrowLeft className="size-4" />
+						<span>Back</span>
+					</button>
+				)}
+				<h1 className="text-xl font-semibold mb-3">
+					{message.subject || "(No subject)"}
+				</h1>
+				<div className="space-y-1 text-sm">
+					<div className="flex gap-2">
+						<span className="text-fg-muted shrink-0 w-12">From:</span>
+						<span className="text-fg">
+							{message.fromName
+								? `${message.fromName} <${message.fromAddress}>`
+								: message.fromAddress}
+						</span>
+					</div>
+					<div className="flex gap-2">
+						<span className="text-fg-muted shrink-0 w-12">To:</span>
+						<span className="text-fg">
+							{(message.toAddresses ?? []).join(", ")}
+						</span>
+					</div>
+					{message.ccAddresses && message.ccAddresses.length > 0 && (
+						<div className="flex gap-2">
+							<span className="text-fg-muted shrink-0 w-12">Cc:</span>
+							<span className="text-fg">{message.ccAddresses.join(", ")}</span>
+						</div>
+					)}
+					<div className="flex gap-2">
+						<span className="text-fg-muted shrink-0 w-12">Date:</span>
+						<span className="text-fg">{sentLabel}</span>
+					</div>
+					{config && (
+						<div className="flex items-center gap-2 pt-2">
+							<StatusIcon
+								className={cn(
+									"size-4",
+									config.className,
+									status === "sending" && "animate-spin",
+								)}
+							/>
+							<span className={cn("text-xs font-medium", config.className)}>
+								{config.label}
+							</span>
+							{isUnsendableStatus(message.status) && message.lastError && (
+								<span className="text-xs text-fg-muted">
+									— {message.lastError}
+								</span>
+							)}
+						</div>
+					)}
+				</div>
+			</div>
+			<div className="p-4">
+				<MessageBody html={message.htmlBody} text={message.textBody} />
+			</div>
+		</div>
+	);
+}
+
+/* ------------------------------------------------------------------ */
+/* Sub-views                                                            */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Outbox list with datum bar header. Mount in the `list` slot of `AppShellSlotted`.
+ */
+function OutboxList() {
+	const { messages, isLoading, selectedMessageId, onSelectMessage } =
+		useOutboxPane();
+
+	if (isLoading) {
+		return (
+			<div className="flex h-full items-center justify-center bg-canvas">
+				<span className="text-fg-muted">Loading...</span>
+			</div>
+		);
+	}
+
+	if (messages.length === 0) {
+		return (
+			<div className="flex h-full bg-surface">
+				<ReadingPaneEmpty message="No outbox messages" showHints={false} />
+			</div>
+		);
+	}
+
+	return (
+		<div className="h-full flex flex-col bg-canvas">
+			{/* List datum bar (40px, the shared `--spacing-pane-header`): keeps
+			    the bottom hairline on the same y as the mailbox view so the grid
+			    line stays continuous across nav → outbox (no staircase, #422). */}
+			<header className="flex h-pane-header shrink-0 items-center gap-2 border-b border-line px-row-inset">
+				<NavMenuButton />
+				<h1 className="min-w-0 flex-1 truncate text-sm font-semibold text-fg">
+					Outbox
+				</h1>
+				<span className="shrink-0 text-2xs text-fg-subtle">
+					{messages.length} {messages.length === 1 ? "message" : "messages"}
+				</span>
+			</header>
+			<div className="flex-1 overflow-y-auto">
+				{messages.map((message) => (
+					<OutboxMessageRow
+						key={message.outboxMessageId}
+						message={message}
+						isSelected={selectedMessageId === message.outboxMessageId}
+						onSelect={() => onSelectMessage(message.outboxMessageId)}
+					/>
+				))}
+			</div>
+		</div>
+	);
+}
+
+/**
+ * Outbox reading pane. Mount in the `reading` slot of `AppShellSlotted`.
+ * Only rendered ≥ 1024px.
+ */
+function OutboxReading() {
+	const { selectedMessage } = useOutboxPane();
+
+	return (
+		<section className="flex h-full w-full min-w-0 flex-col bg-canvas">
+			{/* Detail datum bar (40px): outbox has no message-action toolbar,
+			    but the datum bar must be present so its bottom hairline lines
+			    up with the list pane's, keeping the grid continuous (#422). */}
+			<header className="flex h-pane-header shrink-0 items-center border-b border-line px-3" />
+			<div className="min-h-0 flex-1 overflow-hidden">
+				{selectedMessage ? (
+					<OutboxMessageDetail message={selectedMessage} />
+				) : (
+					<ReadingPaneEmpty
+						message="Select a message to read"
+						showHints={false}
+					/>
+				)}
+			</div>
+		</section>
+	);
+}
+
+/**
+ * Phone view: detail when a message is selected, or the list.
+ * Mount in the `list` slot of `AppShellSlotted` on single-pane tiers.
+ */
+function OutboxPhone() {
+	const {
+		messages,
+		isLoading,
+		selectedMessageId,
+		selectedMessage,
+		onSelectMessage,
+	} = useOutboxPane();
+
+	if (isLoading) {
+		return (
+			<div className="flex h-full items-center justify-center bg-canvas">
+				<span className="text-fg-muted">Loading...</span>
+			</div>
+		);
+	}
+
+	if (selectedMessage) {
+		return (
+			<OutboxMessageDetail
+				message={selectedMessage}
+				onBack={() => onSelectMessage(undefined)}
+			/>
+		);
+	}
+
+	if (messages.length === 0) {
+		return (
+			<div className="flex h-full bg-surface">
+				<ReadingPaneEmpty message="No outbox messages" showHints={false} />
+			</div>
+		);
+	}
+
+	return (
+		<div className="h-full flex flex-col bg-canvas">
+			<header className="flex h-pane-header shrink-0 items-center gap-2 border-b border-line px-row-inset">
+				<NavMenuButton />
+				<h1 className="min-w-0 flex-1 truncate text-sm font-semibold text-fg">
+					Outbox
+				</h1>
+				<span className="shrink-0 text-2xs text-fg-subtle">
+					{messages.length} {messages.length === 1 ? "message" : "messages"}
+				</span>
+			</header>
+			<div className="flex-1 overflow-y-auto">
+				{messages.map((message) => (
+					<OutboxMessageRow
+						key={message.outboxMessageId}
+						message={message}
+						isSelected={selectedMessageId === message.outboxMessageId}
+						onSelect={() => onSelectMessage(message.outboxMessageId)}
+					/>
+				))}
+			</div>
+		</div>
+	);
+}
+
+/* ------------------------------------------------------------------ */
+/* Compound component assembly                                          */
+/* ------------------------------------------------------------------ */
+
+const OutboxPane = Object.assign(OutboxPaneProvider, {
+	List: OutboxList,
+	Reading: OutboxReading,
+	Phone: OutboxPhone,
+});
+
+export { OutboxPane };

package/src/components/mail/PullToRefresh.tsx

@@ -0,0 +1,24 @@
+import { PullToRefresh as KitPullToRefresh } from "@remit/ui";
+import type { ReactElement } from "react";
+
+import { useTriggerSync } from "@/hooks/useTriggerSync";
+
+interface PullToRefreshProps {
+	accountId: string;
+	children: ReactElement;
+}
+
+/**
+ * Binds the kit pull-to-refresh gesture to a mailbox sync for the active
+ * account: a pull triggers the sync and the in-flight state suspends the
+ * gesture until it settles.
+ */
+export const PullToRefresh = ({ accountId, children }: PullToRefreshProps) => {
+	const { triggerAsync, isPending } = useTriggerSync(accountId);
+
+	return (
+		<KitPullToRefresh onRefresh={triggerAsync} isRefreshing={isPending}>
+			{children}
+		</KitPullToRefresh>
+	);
+};

package/src/components/mail/RawMessageView.tsx

@@ -0,0 +1,84 @@
+import { messageOperationsGetRawMessageOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQuery } from "@tanstack/react-query";
+import { ErrorState } from "@/components/ui/ErrorState";
+
+interface RawMessageViewProps {
+	/** The message whose raw RFC822/MIME source to fetch and display. */
+	messageId: string;
+	/**
+	 * Only fetch when the raw view is actually visible. The expanded card
+	 * mounts this lazily, but gating on `enabled` keeps the request from
+	 * firing if a parent ever renders it ahead of time.
+	 */
+	enabled?: boolean;
+}
+
+const LoadingSkeleton = () => (
+	// biome-ignore lint/a11y/useSemanticElements: <div> with role="status" preserves block layout; <output> is inline
+	<div
+		className="animate-pulse space-y-2"
+		role="status"
+		aria-label="Loading raw email"
+	>
+		<div className="h-4 bg-surface-sunken rounded w-full" />
+		<div className="h-4 bg-surface-sunken rounded w-11/12" />
+		<div className="h-4 bg-surface-sunken rounded w-5/6" />
+		<div className="h-4 bg-surface-sunken rounded w-3/4" />
+	</div>
+);
+
+/**
+ * Render the raw RFC822/MIME source (headers + body) of a message in a
+ * scrollable monospace block. Distinguishes loading / failed / loaded so an
+ * empty raw body is never confused with a fetch failure
+ * (memory: feedback_never_hide_failure).
+ */
+export const RawMessageView = ({
+	messageId,
+	enabled = true,
+}: RawMessageViewProps) => {
+	const { data, isLoading, isError, error, refetch } = useQuery({
+		...messageOperationsGetRawMessageOptions({ path: { messageId } }),
+		enabled,
+	});
+
+	if (isLoading) {
+		return (
+			<div className="message-body">
+				<LoadingSkeleton />
+			</div>
+		);
+	}
+
+	if (isError) {
+		return (
+			<div className="message-body">
+				<ErrorState
+					variant="inline"
+					title="Couldn't load the raw email"
+					error={error}
+					onRetry={() => refetch()}
+				/>
+			</div>
+		);
+	}
+
+	const raw = data?.raw ?? "";
+	if (raw === "") {
+		return (
+			<div className="message-body">
+				<p className="text-fg-muted text-sm italic">
+					No raw source available for this message.
+				</p>
+			</div>
+		);
+	}
+
+	return (
+		<div className="message-body">
+			<pre className="email-text whitespace-pre-wrap break-words text-sm leading-relaxed bg-surface-sunken rounded-md p-3 max-h-[32rem] overflow-auto">
+				{raw}
+			</pre>
+		</div>
+	);
+};

package/src/components/mail/ReadingPaneEmpty.render.test.ts

@@ -0,0 +1,42 @@
+/**
+ * Render invariants for the shared reading-pane zero-state and the keyboard
+ * hint bar (#785). Both ship as remit-ui components consumed by the live mail
+ * routes. Uses `react-dom/server` so no jsdom is needed.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { KeyboardHintBar, ReadingPaneEmpty } from "@remit/ui";
+import React, { createElement } from "react";
+import { renderToString } from "react-dom/server";
+
+// See MessageToolbar.render.test.ts: the SSR test loader transpiles remit-ui
+// `.tsx` with the classic JSX runtime, which needs a global `React`.
+(globalThis as { React?: typeof React }).React = React;
+
+describe("ReadingPaneEmpty (#785)", () => {
+	it("renders the prompt and the j/k/Enter Kbd hints by default", () => {
+		const html = renderToString(createElement(ReadingPaneEmpty) as never);
+		assert.match(html, /Select a thread to read/);
+		assert.match(html, /<kbd[^>]*>j<\/kbd>/);
+		assert.match(html, /<kbd[^>]*>k<\/kbd>/);
+		assert.match(html, /<kbd[^>]*>Enter<\/kbd>/);
+	});
+
+	it("can hide the hint line on touch surfaces", () => {
+		const html = renderToString(
+			createElement(ReadingPaneEmpty, { showHints: false }) as never,
+		);
+		assert.equal(/<kbd/.test(html), false);
+	});
+});
+
+describe("KeyboardHintBar (#785)", () => {
+	it("renders the default hint set", () => {
+		const html = renderToString(createElement(KeyboardHintBar) as never);
+		assert.match(html, /navigate/);
+		assert.match(html, /mute/);
+		assert.match(html, /all shortcuts/);
+		assert.match(html, /<kbd[^>]*>j<\/kbd>/);
+	});
+});