@remit/web-client 0.0.191 → 0.0.192

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.191",
+  "version": "0.0.192",
   "type": "module",
   "description": "Remit web client, published as composable primitives — the app shell, auth shells, and runtime config. A distributor imports what it composes and bundles it.",
   "exports": {

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

@@ -0,0 +1,133 @@
+/**
+ * The Empty Trash strip and its three refusals (#847). Rendered as the app
+ * renders it — no providers, because every fact it shows arrives as a prop and
+ * the 409 is what decides which one.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import React, { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import {
+	EmptyTrashBar,
+	type EmptyTrashBarProps,
+	emptyTrashConfirmCopy,
+} from "@/components/mail/EmptyTrashBar";
+import { deleteConfirmationCopy } from "@/lib/format";
+
+(globalThis as { React?: typeof React }).React = React;
+
+const noop = () => {};
+
+const propsFor = (
+	overrides: Partial<EmptyTrashBarProps>,
+): EmptyTrashBarProps => ({
+	messageCount: 128,
+	isEmptying: false,
+	onEmpty: noop,
+	onRepair: noop,
+	children: createElement("div", { id: "list" }, "list"),
+	...overrides,
+});
+
+const render = (overrides: Partial<EmptyTrashBarProps>): string =>
+	renderToString(createElement(EmptyTrashBar, propsFor(overrides)));
+
+const text = (html: string): string =>
+	html
+		.replace(/<[^>]*>/g, " ")
+		.replace(/&#x27;/g, "'")
+		.replace(/&#x2F;/g, "/")
+		.replace(/&quot;/g, '"')
+		.replace(/&amp;/g, "&")
+		.replace(/\s+/g, " ")
+		.trim();
+
+describe("EmptyTrashBar", () => {
+	it("offers the verb when the open Trash folder holds mail", () => {
+		const html = render({});
+		assert.match(text(html), /Empty Trash/);
+		assert.match(html, /id="list"/);
+	});
+
+	it("offers nothing over an empty folder, and still renders the list", () => {
+		const html = render({ messageCount: 0 });
+		assert.doesNotMatch(text(html), /Empty Trash/);
+		assert.match(html, /id="list"/);
+	});
+
+	it("disables the button while the empty is in flight", () => {
+		const html = render({ isEmptying: true });
+		assert.match(text(html), /Emptying/);
+		assert.match(html, /disabled/);
+	});
+
+	it("reports the service's own count once the run finishes", () => {
+		const html = render({ messageCount: 0, deletedCount: 128 });
+		assert.match(text(html), /128 messages erased from the mail server\./);
+	});
+
+	it("keeps the refusal standing after the folder count drops to zero", () => {
+		const html = render({ messageCount: 0, refusalReason: "none" });
+		assert.match(text(html), /No folder on this account is set as Trash\./);
+	});
+
+	it("words `unconfirmed` with deleteConfirmationCopy's own sentence", () => {
+		const copy = deleteConfirmationCopy(0, "unconfirmed", {
+			trashFolderLabel: "Deleted Items",
+		});
+		const html = text(
+			render({
+				refusalReason: "unconfirmed",
+				trashFolderLabel: "Deleted Items",
+			}),
+		);
+		assert.match(html, new RegExp(literal(copy.title)));
+		assert.match(html, new RegExp(literal(copy.description)));
+		assert.match(html, new RegExp(literal(copy.confirmLabel)));
+	});
+
+	it("names the folder a stale appointment lost", () => {
+		const html = text(
+			render({ refusalReason: "stale", staleFolderLabel: "Archive/Bin" }),
+		);
+		assert.match(html, /Nothing was emptied\./);
+		assert.match(html, /Archive\/Bin — is gone from the mail server\./);
+		assert.match(html, /Pick another folder/);
+	});
+
+	it("drops the folder clause when the lost folder has no name", () => {
+		const html = text(render({ refusalReason: "stale" }));
+		assert.match(
+			html,
+			/The folder you chose for Trash is gone from the mail server\./,
+		);
+	});
+
+	it("offers a folder to pick when the account appoints no Trash", () => {
+		const html = text(render({ refusalReason: "none" }));
+		assert.match(html, /No folder on this account is set as Trash\./);
+		assert.match(html, /Pick a folder/);
+	});
+
+	it("asks the confirmation as the expunge it is", () => {
+		const copy = emptyTrashConfirmCopy(128);
+		assert.equal(copy.title, "Empty Trash?");
+		assert.equal(
+			copy.description,
+			"128 messages are erased from the mail server and cannot be restored.",
+		);
+		assert.equal(copy.confirmLabel, "Empty Trash");
+	});
+
+	it("counts a single message in the singular", () => {
+		assert.equal(
+			emptyTrashConfirmCopy(1).description,
+			"1 message is erased from the mail server and cannot be restored.",
+		);
+	});
+});
+
+function literal(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/components/mail/EmptyTrashBar.tsx

@@ -0,0 +1,181 @@
+import { Banner, Button, ConfirmDialog } from "@remit/ui";
+import { Trash2 } from "lucide-react";
+import { type ReactNode, useState } from "react";
+import type { FolderRoleRefusalReason } from "@/components/ui/folder-role-refusal";
+import { deleteConfirmationCopy, formatNumber } from "@/lib/format";
+
+const quantified = (count: number): string =>
+	count === 1 ? "1 message" : `${formatNumber(count)} messages`;
+
+export interface EmptyTrashConfirmCopy {
+	title: string;
+	description: string;
+	confirmLabel: string;
+}
+
+/** The confirmation the button opens, worded for an expunge. */
+export const emptyTrashConfirmCopy = (
+	count: number,
+): EmptyTrashConfirmCopy => ({
+	title: "Empty Trash?",
+	description: `${quantified(count)} ${count === 1 ? "is" : "are"} erased from the mail server and cannot be restored.`,
+	confirmLabel: "Empty Trash",
+});
+
+export interface EmptyTrashRefusalCopy {
+	headline: string;
+	body: string;
+	actionLabel: string;
+}
+
+export interface EmptyTrashRefusalContext {
+	/** The folder reader guessed, for `unconfirmed`. */
+	trashFolderLabel?: string;
+	/** The folder that vanished, for `stale`. */
+	staleFolderLabel?: string;
+}
+
+/**
+ * What the strip says when the server refused. `unconfirmed` borrows
+ * `deleteConfirmationCopy`'s words so the dialog and this strip cannot drift
+ * apart on the one refusal both can raise (#887 F4).
+ */
+export const emptyTrashRefusalCopy = (
+	reason: FolderRoleRefusalReason,
+	context: EmptyTrashRefusalContext = {},
+): EmptyTrashRefusalCopy => {
+	const { trashFolderLabel, staleFolderLabel } = context;
+
+	if (reason === "unconfirmed") {
+		const copy = deleteConfirmationCopy(0, "unconfirmed", { trashFolderLabel });
+		return {
+			headline: copy.title,
+			body: copy.description,
+			actionLabel: copy.confirmLabel,
+		};
+	}
+	if (reason === "stale") {
+		return {
+			headline: "Nothing was emptied.",
+			body: staleFolderLabel
+				? `The folder you chose for Trash — ${staleFolderLabel} — is gone from the mail server.`
+				: "The folder you chose for Trash is gone from the mail server.",
+			actionLabel: "Pick another folder",
+		};
+	}
+	return {
+		headline: "Nothing was emptied.",
+		body: "No folder on this account is set as Trash.",
+		actionLabel: "Pick a folder",
+	};
+};
+
+export interface EmptyTrashBarProps extends EmptyTrashRefusalContext {
+	/** Messages the open Trash folder holds. */
+	messageCount: number;
+	isEmptying: boolean;
+	/** The service's own count, from the run that just finished. */
+	deletedCount?: number;
+	/** The reason the server refused, kept until the user acts on it. */
+	refusalReason?: FolderRoleRefusalReason;
+	onEmpty: () => void;
+	/** Opens the appointment prompt for the standing refusal. */
+	onRepair: () => void;
+	children: ReactNode;
+}
+
+/**
+ * The Empty Trash strip above the Trash folder's list, and the refusals the
+ * server answers it with (#847). The button always acts — it is never
+ * pre-refused from what the client thinks the appointment is, because the 409
+ * is the authority and a warning over a folder nobody has tried to empty is
+ * noise.
+ */
+export function EmptyTrashBar({
+	messageCount,
+	isEmptying,
+	deletedCount,
+	refusalReason,
+	trashFolderLabel,
+	staleFolderLabel,
+	onEmpty,
+	onRepair,
+	children,
+}: EmptyTrashBarProps) {
+	const [confirming, setConfirming] = useState(false);
+
+	// The folder is emptied and nothing was refused: there is no verb left to
+	// offer. A standing refusal or a report of what went outlives the rows,
+	// so the user is never left to guess what the press did.
+	if (
+		messageCount < 1 &&
+		refusalReason === undefined &&
+		deletedCount === undefined
+	)
+		return <>{children}</>;
+
+	const refusal = refusalReason
+		? emptyTrashRefusalCopy(refusalReason, {
+				trashFolderLabel,
+				staleFolderLabel,
+			})
+		: undefined;
+	const confirm = emptyTrashConfirmCopy(messageCount);
+
+	return (
+		<div className="relative flex h-full min-h-0 flex-col">
+			<div className="shrink-0 px-row-inset pt-2">
+				<div className="flex flex-col gap-2 rounded-md border border-line px-3 py-2">
+					<div className="flex items-center justify-end gap-2">
+						{deletedCount !== undefined && (
+							<p className="mr-auto text-2xs text-fg-subtle" role="status">
+								{`${quantified(deletedCount)} erased from the mail server.`}
+							</p>
+						)}
+						<Button
+							variant="ghost"
+							size="sm"
+							icon={<Trash2 className="size-3.5" aria-hidden />}
+							disabled={isEmptying || messageCount < 1}
+							aria-busy={isEmptying}
+							onClick={() => setConfirming(true)}
+						>
+							{isEmptying ? "Emptying…" : "Empty Trash"}
+						</Button>
+					</div>
+					{refusal && (
+						<Banner tone="warning" variant="soft">
+							<div className="flex flex-col gap-2">
+								<p className="font-semibold text-fg">{refusal.headline}</p>
+								<p className="text-sm">{refusal.body}</p>
+								<Button
+									variant="primary"
+									size="sm"
+									className="self-start"
+									onClick={onRepair}
+								>
+									{refusal.actionLabel}
+								</Button>
+							</div>
+						</Banner>
+					)}
+				</div>
+			</div>
+			<div className="min-h-0 flex-1">{children}</div>
+			<ConfirmDialog
+				isOpen={confirming}
+				title={confirm.title}
+				description={confirm.description}
+				confirmLabel={confirm.confirmLabel}
+				destructive
+				// The dialog hands the decision over and closes; the in-flight state
+				// lives on the strip's own button, which is where the verb is.
+				onConfirm={() => {
+					setConfirming(false);
+					onEmpty();
+				}}
+				onCancel={() => setConfirming(false)}
+			/>
+		</div>
+	);
+}

package/src/components/mail/MailboxPane.tsx

@@ -47,6 +47,7 @@ import {
 } from "react";
 import { ConversationView } from "@/components/mail/ConversationView";
 import { DraftsView } from "@/components/mail/DraftsView";
+import { EmptyTrashBar } from "@/components/mail/EmptyTrashBar";
 import { IntelligenceDrawer } from "@/components/mail/IntelligenceDrawer";
 import { IntelligencePane } from "@/components/mail/IntelligencePane";
 import {
@@ -60,8 +61,11 @@ import {
 	useArchiveMailbox,
 	useDraftsMailbox,
 	useJunkMailbox,
+	useTrashByAccount,
+	useTrashMailbox,
 } from "@/hooks/useArchiveMailbox";
 import {
+	useCurrentMailboxMessageCount,
 	useCurrentMailboxName,
 	useCurrentMailboxUnseenCount,
 } from "@/hooks/useCurrentMailboxName";
@@ -69,6 +73,7 @@ import {
 	dropDeletedThreads,
 	useDeleteMessages,
 } from "@/hooks/useDeleteMessages";
+import { useEmptyTrash } from "@/hooks/useEmptyTrash";
 import type { EscalationSearchQuery } from "@/hooks/useEscalatedActions";
 import { useIntelligenceData } from "@/hooks/useIntelligenceData";
 import { useIntelligenceDrawer } from "@/hooks/useIntelligenceDrawer";
@@ -886,6 +891,18 @@ function MailboxList() {
 	const listTitle = mailboxName ?? "Inbox";
 	const preset = useMemo(() => inboxFilterConfig(), []);
 
+	// Empty Trash, on the same test the Spam rescue strip uses: the open mailbox
+	// is the one this account appoints to the role. Whether it may be emptied is
+	// never decided here — the press goes to the server and the 409 answers it.
+	const { trashMailboxId } = useTrashMailbox(mailboxAccountId);
+	const trashMessageCount = useCurrentMailboxMessageCount({ accounts });
+	const { trashByAccount } = useTrashByAccount();
+	const emptyTrash = useEmptyTrash({
+		accountId: mailboxAccountId,
+		mailboxId,
+	});
+	const isTrashFolder = trashMailboxId != null && trashMailboxId === mailboxId;
+
 	// The account owning this folder — undefined for the instant before
 	// `useMailboxAccount` resolves it, which simply means there is nothing to
 	// refresh yet.
@@ -1025,7 +1042,7 @@ function MailboxList() {
 			messageList
 		);
 
-	const body =
+	const spamBody =
 		isSpamFolder && rescueCandidates.length > 0 && mailboxAccountId ? (
 			<SpamRescue
 				accountId={mailboxAccountId}
@@ -1039,6 +1056,27 @@ function MailboxList() {
 			listBody
 		);
 
+	const body = isTrashFolder ? (
+		<EmptyTrashBar
+			messageCount={trashMessageCount}
+			isEmptying={emptyTrash.isEmptying}
+			deletedCount={emptyTrash.deletedCount}
+			refusalReason={emptyTrash.refusal?.reason}
+			trashFolderLabel={mailboxName ?? undefined}
+			staleFolderLabel={
+				mailboxAccountId
+					? trashByAccount.get(mailboxAccountId)?.staleFolderPath
+					: undefined
+			}
+			onEmpty={emptyTrash.emptyTrash}
+			onRepair={emptyTrash.repair}
+		>
+			{spamBody}
+		</EmptyTrashBar>
+	) : (
+		spamBody
+	);
+
 	return (
 		<MailViewChrome
 			title={listTitle}

package/src/components/mail/empty-trash-bar.stories.tsx

@@ -0,0 +1,121 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { EmptyTrashBar } from "@/components/mail/EmptyTrashBar";
+
+/**
+ * Emptying Trash from the mailbox pane, and the three refusals the server can
+ * answer with (#847).
+ *
+ * The strip sits where the Spam rescue banner sits — above the list, in flow —
+ * and the button always acts. Nothing here is pre-refused from what the client
+ * believes the Trash appointment is: the press reaches the server and the 409
+ * is the authority, so a folder nobody has tried to empty carries no warning.
+ * A refusal is a standing fact about the account rather than an event, so it
+ * lands under the button and stays there until the user repairs it.
+ */
+const meta: Meta<typeof EmptyTrashBar> = {
+	title: "Flows/Mail/Empty Trash",
+	component: EmptyTrashBar,
+	parameters: { layout: "fullscreen" },
+};
+export default meta;
+
+type Story = StoryObj<typeof EmptyTrashBar>;
+
+const noop = () => {};
+
+const TrashList = () => (
+	<ul className="divide-y divide-line">
+		{[
+			["Re: invoice 4421", "Bookkeeping"],
+			["Your parcel could not be delivered", "PostNL"],
+			["Weekly digest", "Hacker Newsletter"],
+		].map(([subject, from]) => (
+			<li key={subject} className="px-row-inset py-3">
+				<p className="text-sm text-fg">{subject}</p>
+				<p className="text-2xs text-fg-subtle">{from}</p>
+			</li>
+		))}
+	</ul>
+);
+
+const base = {
+	messageCount: 128,
+	isEmptying: false,
+	trashFolderLabel: "Deleted Items",
+	onEmpty: noop,
+	onRepair: noop,
+	children: <TrashList />,
+};
+
+const Frame = ({ children }: { children: React.ReactNode }) => (
+	<div className="h-[520px] w-full max-w-2xl overflow-hidden border border-line bg-canvas">
+		{children}
+	</div>
+);
+
+/** The folder holds mail, so the verb is offered — quietly, and to the right. */
+export const Idle: Story = {
+	render: () => (
+		<Frame>
+			<EmptyTrashBar {...base} />
+		</Frame>
+	),
+};
+
+/** The press is in flight: the button says so and refuses a second one. */
+export const Emptying: Story = {
+	render: () => (
+		<Frame>
+			<EmptyTrashBar {...base} isEmptying />
+		</Frame>
+	),
+};
+
+/**
+ * What the run reported, straight from the service. A second press re-marks
+ * the same rows and honestly reports the same N — never 0 over an expunge.
+ */
+export const Emptied: Story = {
+	render: () => (
+		<Frame>
+			<EmptyTrashBar {...base} deletedCount={128} />
+		</Frame>
+	),
+};
+
+/**
+ * reader matched the folder by name and nobody confirmed it. The words are
+ * `deleteConfirmationCopy`'s, so the dialog and this strip say the same thing.
+ */
+export const RefusedUnconfirmed: Story = {
+	name: "Refused (unconfirmed)",
+	render: () => (
+		<Frame>
+			<EmptyTrashBar {...base} refusalReason="unconfirmed" />
+		</Frame>
+	),
+};
+
+/** The folder the user chose is gone from the mail server, and is named. */
+export const RefusedStale: Story = {
+	name: "Refused (stale)",
+	render: () => (
+		<Frame>
+			<EmptyTrashBar
+				{...base}
+				refusalReason="stale"
+				staleFolderLabel="Archive/Bin"
+			/>
+		</Frame>
+	),
+};
+
+/** Nothing on this account is set as Trash, so there is nothing to empty. */
+export const RefusedNone: Story = {
+	name: "Refused (none)",
+	render: () => (
+		<Frame>
+			<EmptyTrashBar {...base} refusalReason="none" />
+		</Frame>
+	),
+};

package/src/hooks/useArchiveMailbox.ts

@@ -81,6 +81,17 @@ export const useJunkMailbox = (
 	return { junkMailboxId: mailboxId, isLoading };
 };
 
+/**
+ * Returns the account's appointed Trash mailbox id, which is how the mailbox
+ * pane tells it is looking at Trash and may offer to empty it (#847).
+ */
+export const useTrashMailbox = (
+	accountId: string | undefined,
+): { trashMailboxId: string | undefined; isLoading: boolean } => {
+	const { mailboxId, isLoading } = useFolderRoleMailbox(accountId, "Trash");
+	return { trashMailboxId: mailboxId, isLoading };
+};
+
 /**
  * Each account's appointed Trash mailbox, keyed by account. The delete
  * confirmation needs it to tell a move-to-Trash apart from a delete inside

package/src/hooks/useCurrentMailboxName.ts

@@ -97,3 +97,36 @@ export const useCurrentMailboxUnseenCount = ({
 
 	return null;
 };
+
+/**
+ * The current mailbox's total message count, from the same warm-cache mailbox
+ * query. `0` while it is unresolvable, so a surface gated on "holds at least
+ * one message" — Empty Trash (#847) — stays down rather than offering a verb
+ * over a folder nothing is known about yet.
+ */
+export const useCurrentMailboxMessageCount = ({
+	accounts,
+}: UseCurrentMailboxNameOptions): number => {
+	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 0;
+
+	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.messageCount;
+	}
+
+	return 0;
+};

package/src/hooks/useEmptyTrash.render.test.ts

@@ -0,0 +1,194 @@
+/**
+ * What a refusal and a report are *about* (#847). The mailbox pane never
+ * remounts on a route change, so both are scoped: account A's standing refusal
+ * must not render over account B's Trash, and a count from a folder that was
+ * emptied must not outlive the folder it counted. The empty is also issued
+ * against the Trash `/config` names at that moment, so the replay after a
+ * repair invalidates the folder it actually emptied.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { configOperationsGetConfigQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { QueryClientProvider } from "@tanstack/react-query";
+import { act, createElement } from "react";
+import { RoleAppointmentPromptProvider } from "@/components/mail/RoleAppointmentPromptProvider";
+import { ErrorBannerProvider } from "@/components/ui/ErrorBannerProvider";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { type HttpMock, mockFetch } from "../test-support/http";
+import { type EmptyTrashState, useEmptyTrash } from "./useEmptyTrash";
+
+const ACCOUNT_A = "acc-a";
+const ACCOUNT_B = "acc-b";
+const TRASH_A = "mbx-trash-a";
+const TRASH_B = "mbx-trash-b";
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+let state: EmptyTrashState | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http?.restore();
+	http = undefined;
+	state = undefined;
+});
+
+const CONFIG = {
+	accounts: [
+		{
+			accountId: ACCOUNT_A,
+			email: "a@example.com",
+			folderAppointments: [
+				{ role: "Trash", mailboxId: TRASH_A, source: "Proposed" },
+			],
+		},
+		{
+			accountId: ACCOUNT_B,
+			email: "b@example.com",
+			folderAppointments: [
+				{ role: "Trash", mailboxId: TRASH_B, source: "Appointed" },
+			],
+		},
+	],
+};
+
+/** Fresh every call — a `Response` body can only be read once. */
+const refusal = (): Response =>
+	new Response(
+		JSON.stringify({
+			status: 409,
+			message: "Trash is not confirmed",
+			code: "folder_role_unresolved",
+			details: { reason: "unconfirmed", role: "Trash", accountId: ACCOUNT_A },
+		}),
+		{ status: 409, headers: { "content-type": "application/json" } },
+	);
+
+/** Account A refuses the empty; account B allows it. */
+const respond = (path: string): unknown => {
+	if (path.endsWith("/config")) return CONFIG;
+	if (path.endsWith(`/accounts/${ACCOUNT_A}/trash/empty`)) return refusal();
+	if (path.endsWith(`/accounts/${ACCOUNT_B}/trash/empty`))
+		return { deletedCount: 7 };
+	return {};
+};
+
+const Probe = ({
+	accountId,
+	mailboxId,
+}: {
+	accountId: string;
+	mailboxId: string;
+}) => {
+	state = useEmptyTrash({ accountId, mailboxId });
+	return null;
+};
+
+const tree = (accountId: string, mailboxId: string) =>
+	createElement(
+		QueryClientProvider,
+		{ client: harness?.queryClient as never },
+		createElement(
+			ErrorBannerProvider,
+			null,
+			createElement(
+				RoleAppointmentPromptProvider,
+				null,
+				createElement(Probe, { accountId, mailboxId }),
+			),
+		),
+	);
+
+const settle = async (done: () => boolean = () => false): Promise<void> => {
+	if (!harness) throw new Error("nothing mounted");
+	for (let round = 0; round < 40; round += 1) {
+		await harness.flush();
+		await harness.wait(0);
+		if (done()) return;
+	}
+};
+
+const mount = async (accountId: string, mailboxId: string): Promise<void> => {
+	http = mockFetch((call) => respond(call.path));
+	harness = createDomHarness();
+	await harness.renderAsync(tree(accountId, mailboxId));
+	await settle(() => state !== undefined);
+};
+
+/** The same mounted pane, now looking at another folder — never a remount. */
+const openInstead = async (
+	accountId: string,
+	mailboxId: string,
+): Promise<void> => {
+	if (!harness) throw new Error("nothing mounted");
+	await harness.renderAsync(tree(accountId, mailboxId));
+	await settle();
+};
+
+const press = async (done: () => boolean): Promise<void> => {
+	await act(async () => {
+		state?.emptyTrash();
+	});
+	await settle(done);
+};
+
+describe("useEmptyTrash scope", () => {
+	it("drops a refusal raised on one mailbox when another is opened", async () => {
+		await mount(ACCOUNT_A, TRASH_A);
+		await press(() => state?.refusal !== undefined);
+		assert.equal(state?.refusal?.reason, "unconfirmed");
+		assert.equal(state?.refusal?.accountId, ACCOUNT_A);
+
+		await openInstead(ACCOUNT_B, TRASH_B);
+		assert.equal(state?.refusal, undefined);
+	});
+
+	it("drops a report of what was emptied when another mailbox is opened", async () => {
+		await mount(ACCOUNT_B, TRASH_B);
+		await press(() => state?.deletedCount !== undefined);
+		assert.equal(state?.deletedCount, 7);
+
+		await openInstead(ACCOUNT_A, TRASH_A);
+		assert.equal(state?.deletedCount, undefined);
+	});
+
+	it("issues the empty against the account the pane is on", async () => {
+		await mount(ACCOUNT_A, TRASH_A);
+		await press(() => state?.refusal !== undefined);
+		await openInstead(ACCOUNT_B, TRASH_B);
+		await press(() => state?.deletedCount !== undefined);
+
+		const empties = (http?.calls ?? []).filter((call) =>
+			call.path.endsWith("/trash/empty"),
+		);
+		assert.equal(empties.length, 2);
+		assert.ok(empties[0].path.endsWith(`/accounts/${ACCOUNT_A}/trash/empty`));
+		assert.ok(empties[1].path.endsWith(`/accounts/${ACCOUNT_B}/trash/empty`));
+	});
+
+	it("drops the refusal once the account's Trash resolution changes", async () => {
+		await mount(ACCOUNT_A, TRASH_A);
+		await press(() => state?.refusal !== undefined);
+		assert.ok(state?.refusal);
+
+		// A repair made anywhere else — the settings pane, another tab — lands
+		// here as a new `/config`, and the refusal it answered is spent.
+		await act(async () => {
+			harness?.queryClient.setQueryData(configOperationsGetConfigQueryKey(), {
+				accounts: [
+					{
+						...CONFIG.accounts[0],
+						folderAppointments: [
+							{ role: "Trash", mailboxId: TRASH_A, source: "Appointed" },
+						],
+					},
+					CONFIG.accounts[1],
+				],
+			});
+		});
+		await settle(() => state?.refusal === undefined);
+		assert.equal(state?.refusal, undefined);
+	});
+});

package/src/hooks/useEmptyTrash.ts

@@ -0,0 +1,187 @@
+/**
+ * Emptying an account's Trash, and the refusal the server answers it with.
+ *
+ * The press always reaches the server (#847): the client's `/config` is a read
+ * that can be stale, so a folder-role refusal is the server's to make, and the
+ * 409 is the only authority the surface listens to. On that refusal the strip
+ * states it in place and the repair opens the appointment prompt, which replays
+ * the empty once a folder is confirmed (#887 D16 item 1).
+ */
+import {
+	configOperationsGetConfigQueryKey,
+	mailboxOperationsListMailboxesQueryKey,
+	trashOperationsEmptyTrashMutation,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { ConfigOperationsGetConfigResponse } from "@remit/api-http-client/types.gen.ts";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useRef, useState } from "react";
+import { useRoleAppointmentPrompt } from "@/components/mail/RoleAppointmentPromptProvider";
+import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
+import { formatErrorDetail } from "@/components/ui/error-banners";
+import {
+	type FolderRoleRefusal,
+	isFolderRoleRefusal,
+} from "@/components/ui/folder-role-refusal";
+import {
+	invalidateThreadListQueries,
+	threadListCacheKeys,
+} from "@/lib/thread-list-cache";
+import { useTrashByAccount } from "./useArchiveMailbox";
+
+interface UseEmptyTrashOptions {
+	accountId: string | undefined;
+	/** The open mailbox the strip is mounted over. */
+	mailboxId: string;
+}
+
+export interface EmptyTrashState {
+	emptyTrash: () => void;
+	isEmptying: boolean;
+	/** What the last finished run reported, straight from the service. */
+	deletedCount: number | undefined;
+	refusal: FolderRoleRefusal | undefined;
+	repair: () => void;
+}
+
+/**
+ * What a report or a refusal is about. Both are facts about one account's
+ * Trash as it resolved at the time, so neither may survive the mailbox or the
+ * account changing under a pane that never remounts — nor a resolution
+ * repaired elsewhere, which is the "or the resolution changes" the refusal
+ * persists until.
+ */
+const scopeOf = (
+	accountId: string | undefined,
+	mailboxId: string,
+	trashMailboxId: string | undefined,
+	source: string | undefined,
+): string =>
+	`${accountId ?? ""}|${mailboxId}|${trashMailboxId ?? ""}|${source ?? ""}`;
+
+interface EmptyTrashRun {
+	scope: string;
+	deletedCount?: number;
+	refusal?: FolderRoleRefusal;
+}
+
+interface EmptyTrashContext {
+	scope: string;
+	/** The folder the empty was issued against, whose listing it invalidates. */
+	listMailboxId: string;
+}
+
+export const useEmptyTrash = ({
+	accountId,
+	mailboxId,
+}: UseEmptyTrashOptions): EmptyTrashState => {
+	const queryClient = useQueryClient();
+	const { pushError } = useErrorBanners();
+	const { requestAppointment } = useRoleAppointmentPrompt();
+	const { trashByAccount } = useTrashByAccount();
+
+	const trash = accountId ? trashByAccount.get(accountId) : undefined;
+	const scope = scopeOf(accountId, mailboxId, trash?.mailboxId, trash?.source);
+
+	const [run, setRun] = useState<EmptyTrashRun>({ scope });
+	if (run.scope !== scope) setRun({ scope });
+	const current = run.scope === scope ? run : undefined;
+
+	/**
+	 * The Trash as `/config` reads *now*, straight from the cache. After a
+	 * repair the appointment names a different folder, and the replay must
+	 * invalidate that folder's listing rather than the one this pane opened —
+	 * a render has not necessarily flushed by the time the replay is called.
+	 */
+	const listMailboxIdNow = useCallback((): string => {
+		const config = queryClient.getQueryData<ConfigOperationsGetConfigResponse>(
+			configOperationsGetConfigQueryKey(),
+		);
+		const account = config?.accounts.find((one) => one.accountId === accountId);
+		const appointed = account?.folderAppointments.find(
+			(one) => one.role === "Trash",
+		)?.mailboxId;
+		return appointed ?? mailboxId;
+	}, [queryClient, accountId, mailboxId]);
+
+	// What the run in flight is about, for the same reason: a press on one
+	// folder must not read as a press on the next one the pane opens.
+	const inFlight = useRef<string>(undefined);
+
+	const { mutateAsync, isPending } = useMutation({
+		...trashOperationsEmptyTrashMutation(),
+		onMutate: (): EmptyTrashContext => {
+			inFlight.current = scope;
+			return { scope, listMailboxId: listMailboxIdNow() };
+		},
+		onSuccess: (data, _variables, context) => {
+			if (context.scope !== scope) return;
+			// The service's count, never a local tally. A second press re-marks the
+			// same rows and reports N again — that is what the folder still holds,
+			// and reporting 0 over an expunge is the failure #887 is about.
+			setRun({ scope, deletedCount: data.deletedCount });
+		},
+		onError: (error, _variables, context) => {
+			const refused = isFolderRoleRefusal(error);
+			if (!refused) {
+				pushError({
+					title: "Couldn't empty Trash",
+					detail: formatErrorDetail(error),
+					error,
+				});
+				return;
+			}
+			// A refusal that outlived what it was about states somebody else's
+			// problem over this folder.
+			if (context?.scope !== scope) return;
+			setRun({ scope, refusal: refused });
+		},
+		onSettled: (_data, _error, _variables, context) => {
+			if (inFlight.current === context?.scope) inFlight.current = undefined;
+			invalidateThreadListQueries(
+				queryClient,
+				threadListCacheKeys([context?.listMailboxId ?? mailboxId]),
+			);
+			if (!accountId) return;
+			queryClient.invalidateQueries({
+				queryKey: mailboxOperationsListMailboxesQueryKey({
+					path: { accountId },
+				}),
+			});
+		},
+	});
+
+	// `onError` above has already stated the failure; the rejection reaching the
+	// caller would only report it a second time.
+	const issue = useCallback((): Promise<void> => {
+		if (!accountId) return Promise.resolve();
+		setRun({ scope });
+		return mutateAsync({ path: { accountId } }).then(
+			() => {},
+			() => {},
+		);
+	}, [accountId, scope, mutateAsync]);
+
+	const emptyTrash = useCallback(() => {
+		void issue();
+	}, [issue]);
+
+	const repair = useCallback(() => {
+		const refusal = current?.refusal;
+		if (!refusal) return;
+		requestAppointment({
+			accountId: refusal.accountId,
+			role: refusal.role,
+			reason: refusal.reason,
+			action: { kind: "emptyTrash" },
+			onAppointed: issue,
+		});
+	}, [current, requestAppointment, issue]);
+
+	return {
+		emptyTrash,
+		isEmptying: isPending && inFlight.current === scope,
+		deletedCount: current?.deletedCount,
+		refusal: current?.refusal,
+		repair,
+	};
+};