@remit/web-client 0.0.1

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

@@ -0,0 +1,111 @@
+export type ErrorBannerSeverity = "error" | "warning" | "info";
+
+export interface ErrorBannerEntry {
+	id: string;
+	severity: ErrorBannerSeverity;
+	title: string;
+	detail?: string;
+	createdAt: number;
+}
+
+export interface PushErrorInput {
+	severity?: ErrorBannerSeverity;
+	title: string;
+	detail?: string;
+}
+
+const MAX_BANNERS = 5;
+
+/**
+ * Build the banner input for a mutation failure: the error's own message when
+ * it has one, otherwise a human fallback. Shared by the previously-silent
+ * mutation `onError` handlers (signature save, outbox retry/delete, draft
+ * discard) so they surface a real detail instead of nothing. A fatal 5xx is
+ * additionally escalated globally; this only governs the soft banner copy.
+ */
+export const buildMutationErrorBanner = (
+	title: string,
+	fallback: string,
+	error: unknown,
+): PushErrorInput => ({
+	title,
+	detail: formatErrorDetail(error) ?? fallback,
+});
+
+export const formatErrorDetail = (error: unknown): string | undefined => {
+	if (error === undefined || error === null) return undefined;
+	if (error instanceof Error) return error.message || undefined;
+	if (typeof error === "string") return error || undefined;
+	if (
+		typeof error === "object" &&
+		"message" in error &&
+		typeof (error as { message: unknown }).message === "string"
+	) {
+		const message = (error as { message: string }).message;
+		return message || undefined;
+	}
+	return undefined;
+};
+
+/**
+ * Detect a "describeMessage hit a deleted/missing row" error.
+ *
+ * Soft-deleted ThreadMessage rows used to leak into the inbox list (#212);
+ * clicking one fired `describeMessage` against an already-hard-deleted
+ * Message and the backend's `NotFoundError` ("Message not found: <id>")
+ * surfaced verbatim. We now filter those rows server-side, but the UI still
+ * needs a graceful empty state when the cache is mid-refresh or the row
+ * was just deleted in another tab.
+ *
+ * The backend serializes 404s as `{ message: "Message not found: <id>" }`
+ * (see `packages/backend/src/error.ts`). The hey-api fetch client
+ * throws the parsed JSON body as the error, so we match by message prefix.
+ */
+export const isMessageNotFoundError = (error: unknown): boolean => {
+	const detail = formatErrorDetail(error);
+	if (!detail) return false;
+	return detail.startsWith("Message not found");
+};
+
+const sameInput = (
+	entry: ErrorBannerEntry,
+	input: PushErrorInput,
+	severity: ErrorBannerSeverity,
+): boolean =>
+	entry.severity === severity &&
+	entry.title === input.title &&
+	entry.detail === input.detail;
+
+export const appendBanner = (
+	current: ErrorBannerEntry[],
+	entry: ErrorBannerEntry,
+): ErrorBannerEntry[] => {
+	const filtered = current.filter(
+		(existing) =>
+			!sameInput(
+				existing,
+				{ title: entry.title, detail: entry.detail, severity: entry.severity },
+				entry.severity,
+			),
+	);
+	const next = [...filtered, entry];
+	if (next.length <= MAX_BANNERS) return next;
+	return next.slice(next.length - MAX_BANNERS);
+};
+
+export const dismissBanner = (
+	current: ErrorBannerEntry[],
+	id: string,
+): ErrorBannerEntry[] => current.filter((entry) => entry.id !== id);
+
+export const buildEntry = (
+	input: PushErrorInput,
+	id: string,
+	now: number,
+): ErrorBannerEntry => ({
+	id,
+	severity: input.severity ?? "error",
+	title: input.title,
+	detail: input.detail,
+	createdAt: now,
+});

package/src/hooks/queries/keys.ts

@@ -0,0 +1,38 @@
+export const threadKeys = {
+	all: ["threads"] as const,
+
+	lists: () => [...threadKeys.all, "list"] as const,
+
+	list: (
+		mailboxId: string,
+		filters?: { filter?: string; page?: number; cursor?: string },
+	) => [...threadKeys.lists(), mailboxId, filters] as const,
+
+	details: () => [...threadKeys.all, "detail"] as const,
+
+	detail: (threadId: string) => [...threadKeys.details(), threadId] as const,
+
+	messages: (threadId: string) =>
+		[...threadKeys.detail(threadId), "messages"] as const,
+};
+
+export const mailboxKeys = {
+	all: ["mailboxes"] as const,
+
+	lists: () => [...mailboxKeys.all, "list"] as const,
+
+	list: (accountId: string) => [...mailboxKeys.lists(), accountId] as const,
+
+	detail: (mailboxId: string) =>
+		[...mailboxKeys.all, "detail", mailboxId] as const,
+};
+
+export const messageKeys = {
+	all: ["messages"] as const,
+
+	detail: (messageId: string) =>
+		[...messageKeys.all, "detail", messageId] as const,
+
+	body: (messageId: string) =>
+		[...messageKeys.detail(messageId), "body"] as const,
+};

package/src/hooks/useArchiveMailbox.ts

@@ -0,0 +1,104 @@
+import { configOperationsGetConfigOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type {
+	RemitImapCanonicalMailboxRole,
+	RemitImapFolderAppointment,
+} from "@remit/api-http-client/types.gen.ts";
+import { useQuery } from "@tanstack/react-query";
+import { useMemo } from "react";
+
+/**
+ * RFC 032 exclusive-folder-appointment (#976): every "which mailbox plays
+ * role X" question resolves from the account's `folderAppointments` map, not
+ * from independently re-detecting SPECIAL-USE flags or hardcoded name lists.
+ * The map is server-resolved (persisted user choice, or a proposal for
+ * anything unfilled), so a single shared lookup replaces what used to be four
+ * near-identical flag-then-name detectors.
+ */
+const useFolderRoleMailbox = (
+	accountId: string | undefined,
+	role: RemitImapCanonicalMailboxRole,
+): { mailboxId: string | undefined; isLoading: boolean } => {
+	const { data: config, isLoading } = useQuery({
+		...configOperationsGetConfigOptions(),
+		staleTime: Infinity,
+		enabled: !!accountId,
+	});
+
+	const mailboxId = useMemo(() => {
+		if (!accountId) return undefined;
+		const account = config?.accounts.find((a) => a.accountId === accountId);
+		return account?.folderAppointments.find((fa) => fa.role === role)
+			?.mailboxId;
+	}, [config, accountId, role]);
+
+	return { mailboxId, isLoading };
+};
+
+/**
+ * Returns the account's appointed Archive mailbox id. `undefined` while
+ * loading or when no folder is appointed to (or proposed for) the role.
+ */
+export const useArchiveMailbox = (
+	accountId: string | undefined,
+): { archiveMailboxId: string | undefined; isLoading: boolean } => {
+	const { mailboxId, isLoading } = useFolderRoleMailbox(accountId, "Archive");
+	return { archiveMailboxId: mailboxId, isLoading };
+};
+
+/**
+ * Returns the account's appointed Drafts mailbox id. Used by the mailbox
+ * route to decide whether to render the segmented Drafts view (Remit drafts +
+ * IMAP Drafts) in place of the flat message list (issue #505).
+ */
+export const useDraftsMailbox = (
+	accountId: string | undefined,
+): { draftsMailboxId: string | undefined; isLoading: boolean } => {
+	const { mailboxId, isLoading } = useFolderRoleMailbox(accountId, "Drafts");
+	return { draftsMailboxId: mailboxId, isLoading };
+};
+
+/**
+ * Returns the account's Inbox mailbox id — the destination for "Not spam"
+ * (issue #594), which moves a message out of Junk back to the inbox.
+ */
+export const useInboxMailbox = (
+	accountId: string | undefined,
+): { inboxMailboxId: string | undefined; isLoading: boolean } => {
+	const { mailboxId, isLoading } = useFolderRoleMailbox(accountId, "Inbox");
+	return { inboxMailboxId: mailboxId, isLoading };
+};
+
+/**
+ * Returns the account's appointed Junk/Spam mailbox id, used by the triage
+ * `!` (mark junk) key (#429). The message-flags API has no `$Junk` keyword
+ * field, so "mark junk" is realized as a move to the Junk mailbox.
+ */
+export const useJunkMailbox = (
+	accountId: string | undefined,
+): { junkMailboxId: string | undefined; isLoading: boolean } => {
+	const { mailboxId, isLoading } = useFolderRoleMailbox(accountId, "Junk");
+	return { junkMailboxId: mailboxId, isLoading };
+};
+
+/**
+ * Returns an account's full role→mailbox appointment map, for callers that
+ * need more than one role at once (e.g. the Move-to picker excluding both
+ * Drafts and Sent, and ordering system folders by role). Empty while loading
+ * or when `accountId` is undefined.
+ */
+export const useFolderAppointments = (
+	accountId: string | undefined,
+): readonly RemitImapFolderAppointment[] => {
+	const { data: config } = useQuery({
+		...configOperationsGetConfigOptions(),
+		staleTime: Infinity,
+		enabled: !!accountId,
+	});
+
+	return useMemo(
+		() =>
+			config?.accounts.find((a) => a.accountId === accountId)
+				?.folderAppointments ?? [],
+		[config, accountId],
+	);
+};

package/src/hooks/useAutoMovedBadge.ts

@@ -0,0 +1,77 @@
+import type { RemitImapAutoMovedInfo } from "@remit/api-http-client/types.gen.ts";
+import { useCallback } from "react";
+import {
+	autoMovedLabel,
+	isAutoMoveInEffect,
+	resolveUndoTargetMailboxId,
+} from "@/lib/auto-moved";
+import { useInboxMailbox, useJunkMailbox } from "./useArchiveMailbox";
+import { useMoveMessages } from "./useMoveMessages";
+
+interface UseAutoMovedBadgeOptions {
+	accountId: string | undefined;
+	messageId: string;
+	threadId: string;
+	/** The message's current mailbox — the row/card it's rendered in. */
+	mailboxId: string;
+	autoMoved: RemitImapAutoMovedInfo | undefined;
+}
+
+export interface AutoMovedBadgeState {
+	/** Whether the move is still in effect and the badge should render. */
+	show: boolean;
+	label: string;
+	/** Present only when the undo target mailbox resolved. */
+	onUndo?: () => void;
+	isUndoing: boolean;
+}
+
+/**
+ * Composes the account's Inbox/Junk mailboxes with the message's `autoMoved`
+ * projection into everything the `AutoMovedBadge` kit component needs: the
+ * derived "still in effect" gate, the plain-language label, and a one-click
+ * undo bound to the existing `moveMessages` mutation (no new endpoint — moves
+ * back through the same bulk move operation, the other direction).
+ *
+ * `show` re-derives on every render from `mailboxId` — no local dismissed
+ * flag. Once `moveMessages` settles, its query invalidation refetches the
+ * thread row with its updated `mailboxId`, and the badge naturally stops
+ * showing (doc/rules/data-flow.md).
+ */
+export const useAutoMovedBadge = ({
+	accountId,
+	messageId,
+	threadId,
+	mailboxId,
+	autoMoved,
+}: UseAutoMovedBadgeOptions): AutoMovedBadgeState => {
+	const { inboxMailboxId } = useInboxMailbox(accountId);
+	const { junkMailboxId } = useJunkMailbox(accountId);
+	const { moveMessages, isPending } = useMoveMessages({
+		mailboxId,
+		threadId,
+		accountId,
+	});
+
+	const roleMailboxes = { inboxMailboxId, junkMailboxId };
+	const show = isAutoMoveInEffect(autoMoved, mailboxId, roleMailboxes);
+	const undoTargetMailboxId = autoMoved
+		? resolveUndoTargetMailboxId(autoMoved.fromPlacement, roleMailboxes)
+		: undefined;
+
+	const handleUndo = useCallback(() => {
+		if (!undoTargetMailboxId) return;
+		moveMessages([messageId], undoTargetMailboxId);
+	}, [moveMessages, messageId, undoTargetMailboxId]);
+
+	if (!show || !autoMoved) {
+		return { show: false, label: "", isUndoing: false };
+	}
+
+	return {
+		show: true,
+		label: autoMovedLabel(autoMoved.fromPlacement),
+		onUndo: undoTargetMailboxId ? handleUndo : undefined,
+		isUndoing: isPending,
+	};
+};

package/src/hooks/useCurrentMailboxName.ts

@@ -0,0 +1,99 @@
+import { mailboxOperationsListMailboxesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
+import { useQueries } from "@tanstack/react-query";
+import { useLocation, useParams } from "@tanstack/react-router";
+import { useCallback } from "react";
+import { useTranslation } from "react-i18next";
+import { buildMailboxRoleMap, labelForMailbox } from "@/lib/folder-roles";
+
+interface UseCurrentMailboxNameOptions {
+	accounts: RemitImapAccountResponse[];
+}
+
+/**
+ * Resolves a display label for the mailbox or pseudo-mailbox the user is
+ * currently looking at — used by the mobile top bar so it reads e.g.
+ * "Inbox" or "Outbox" instead of the static "Remit" branding.
+ *
+ * Priority:
+ *   - `/mail/outbox` → "Outbox"
+ *   - `/mail/$mailboxId` → display name from the mailbox query
+ *   - everything else (e.g. `/mail` mid-redirect) → `null`
+ *
+ * Reuses the same `mailboxOperationsListMailboxesOptions` queries the
+ * `MailSidebarAdapter` runs, so on warm cache (the sidebar is always
+ * mounted on `/mail/*`) this is a free lookup.
+ */
+export const useCurrentMailboxName = ({
+	accounts,
+}: UseCurrentMailboxNameOptions): string | null => {
+	const params = useParams({ strict: false });
+	const location = useLocation();
+	const mailboxId = (params as { mailboxId?: string }).mailboxId;
+	const { t } = useTranslation("mail", { useSuspense: false });
+	const translator = useCallback(
+		(key: string, fallback: string) => t(key, { defaultValue: fallback }),
+		[t],
+	);
+
+	const queries = useQueries({
+		queries: accounts.map((account) => ({
+			...mailboxOperationsListMailboxesOptions({
+				path: { accountId: account.accountId },
+			}),
+			staleTime: Infinity,
+		})),
+	});
+
+	if (location.pathname.startsWith("/mail/outbox")) return "Outbox";
+	if (!mailboxId) return null;
+
+	for (let i = 0; i < accounts.length; i++) {
+		const items = queries[i]?.data?.items;
+		if (!items) continue;
+		const match = items.find((mailbox) => mailbox.mailboxId === mailboxId);
+		if (!match) continue;
+		const roleMap = buildMailboxRoleMap(accounts[i].folderAppointments);
+		return labelForMailbox(match, roleMap.get(mailboxId), translator);
+	}
+
+	return null;
+};
+
+/**
+ * Resolves the authoritative unread (unseen) total for the current mailbox
+ * from the mailbox query — the same warm-cache `mailboxOperationsListMailboxes`
+ * data the sidebar and `useCurrentMailboxName` already read.
+ *
+ * Returns `mailbox.unseenCount` (the true server-side total), not a count
+ * derived from the loaded infinite-query pages, which would undercount on any
+ * mailbox larger than one page and creep upward as the user scrolls. Returns
+ * `null` when the mailbox isn't resolvable yet (loading, or no `mailboxId`),
+ * letting callers fall back to a loaded-derived count.
+ */
+export const useCurrentMailboxUnseenCount = ({
+	accounts,
+}: UseCurrentMailboxNameOptions): number | null => {
+	const params = useParams({ strict: false });
+	const mailboxId = (params as { mailboxId?: string }).mailboxId;
+
+	const queries = useQueries({
+		queries: accounts.map((account) => ({
+			...mailboxOperationsListMailboxesOptions({
+				path: { accountId: account.accountId },
+			}),
+			staleTime: Infinity,
+		})),
+	});
+
+	if (!mailboxId) return null;
+
+	for (const query of queries) {
+		const items = query.data?.items;
+		if (!items) continue;
+		const match = items.find((mailbox) => mailbox.mailboxId === mailboxId);
+		if (match) return match.unseenCount;
+	}
+
+	return null;
+};

package/src/hooks/useDebouncedValue.ts

@@ -0,0 +1,12 @@
+import { useEffect, useState } from "react";
+
+export const useDebouncedValue = <T>(value: T, delay: number): T => {
+	const [debouncedValue, setDebouncedValue] = useState(value);
+
+	useEffect(() => {
+		const timer = setTimeout(() => setDebouncedValue(value), delay);
+		return () => clearTimeout(timer);
+	}, [value, delay]);
+
+	return debouncedValue;
+};

package/src/hooks/useDeleteMessages.test.ts

@@ -0,0 +1,103 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
+import {
+	dropDeletedThreads,
+	removeMessagesFromItems,
+} from "./useDeleteMessages.js";
+
+const make = (
+	overrides: Partial<RemitImapThreadMessageResponse> & {
+		messageId: string;
+		threadMessageId: string;
+	},
+): RemitImapThreadMessageResponse =>
+	({
+		threadId: "t1",
+		mailboxId: "mb1",
+		subject: "s",
+		fromName: "n",
+		fromEmail: "e",
+		sentDate: "2025-01-01T00:00:00Z",
+		snippet: "",
+		hasAttachment: false,
+		hasStars: false,
+		isRead: true,
+		...overrides,
+	}) as RemitImapThreadMessageResponse;
+
+describe("removeMessagesFromItems", () => {
+	test("drops items whose messageId is in the set", () => {
+		const items = [
+			make({ messageId: "m1", threadMessageId: "tm1" }),
+			make({ messageId: "m2", threadMessageId: "tm2" }),
+			make({ messageId: "m3", threadMessageId: "tm3" }),
+		];
+		const got = removeMessagesFromItems(items, new Set(["m2"]));
+		assert.deepStrictEqual(
+			got.map((i) => i.messageId),
+			["m1", "m3"],
+		);
+	});
+
+	test("returns the input unchanged when nothing matches", () => {
+		const items = [
+			make({ messageId: "m1", threadMessageId: "tm1" }),
+			make({ messageId: "m2", threadMessageId: "tm2" }),
+		];
+		const got = removeMessagesFromItems(items, new Set(["does-not-exist"]));
+		assert.equal(got.length, 2);
+	});
+
+	test("returns an empty array when all items match", () => {
+		const items = [
+			make({ messageId: "m1", threadMessageId: "tm1" }),
+			make({ messageId: "m2", threadMessageId: "tm2" }),
+		];
+		const got = removeMessagesFromItems(items, new Set(["m1", "m2"]));
+		assert.deepStrictEqual(got, []);
+	});
+
+	test("returns an empty array for empty input", () => {
+		const got = removeMessagesFromItems([], new Set(["m1"]));
+		assert.deepStrictEqual(got, []);
+	});
+});
+
+describe("dropDeletedThreads (#212)", () => {
+	// Belt-and-braces UI filter for issue #212. If the backend regresses and
+	// returns a soft-deleted row, the inbox list must still hide it. The
+	// dedicated helper makes the regression cheap to test without rendering
+	// React.
+
+	test("drops items with isDeleted=true and keeps the rest", () => {
+		const items = [
+			make({ messageId: "m1", threadMessageId: "tm1", isDeleted: false }),
+			make({ messageId: "m2", threadMessageId: "tm2", isDeleted: true }),
+			make({ messageId: "m3", threadMessageId: "tm3" }),
+		];
+		const got = dropDeletedThreads(items);
+		assert.deepStrictEqual(
+			got.map((i) => i.messageId),
+			["m1", "m3"],
+		);
+	});
+
+	test("returns the input unchanged when nothing is deleted", () => {
+		const items = [
+			make({ messageId: "m1", threadMessageId: "tm1" }),
+			make({ messageId: "m2", threadMessageId: "tm2", isDeleted: false }),
+		];
+		const got = dropDeletedThreads(items);
+		assert.equal(got.length, 2);
+	});
+
+	test("returns an empty array when every row is deleted", () => {
+		const items = [
+			make({ messageId: "m1", threadMessageId: "tm1", isDeleted: true }),
+			make({ messageId: "m2", threadMessageId: "tm2", isDeleted: true }),
+		];
+		const got = dropDeletedThreads(items);
+		assert.deepStrictEqual(got, []);
+	});
+});