@rapidmx/web-client 0.16.0 → 0.17.2

package/apps/shared/mail/permanentDelete.ts

@@ -0,0 +1,160 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { Message, emptyFolder, listMessages, purgeMessage } from "@rapidmx/react-shared/mail/mailApi.js";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { displaySubject } from "../components/mail/reading/EncryptedPreview.js";
+import { notifySessionExpired } from "../notifications/apiErrors.js";
+import { notify } from "../notifications/store.js";
+import { LIST_PAGE_SIZE, MAX_LIST_PAGES, listAllPages } from "./listAllPages.js";
+
+/**
+ * Permanent delete: what "Delete" does to a message that is already in Deleted Items (and what "Empty folder" does to Deleted Items and
+ * Junk Email). Unlike a move into Deleted Items it cannot be undone, so it is never reached without a confirmation (see
+ * `usePermanentDelete()`, which asks it, runs what is in here and tells the folder badges and the reader).
+ *
+ * Server side it is `DELETE /mail/messages/:uid?purge=true` (a hard delete - the row and its search document are gone, not a
+ * recoverable soft delete) per message, and `DELETE /mail/messages?folderUid=` (`truncate`) for a whole folder. Both refuse a message under
+ * an active legal hold with a `409`; the per-message form refuses one message at a time, so a selection is deleted as far as it can be and
+ * each refusal is reported (`PurgeFailure`), rather than the first stopping the rest.
+ */
+
+/** How many purge requests are on the wire at once: a few at a time is quick, and the server publishes each folder's counts as they land. */
+export const PURGE_CONCURRENCY = 4;
+
+/** The folder types "Empty folder" is offered for: Outlook's Deleted Items and Junk Email. */
+export const EMPTIABLE_FOLDER_TYPES: readonly string[] = ["deleted_items", "junk"];
+
+/** A message the server refused to delete, and what it said. */
+export interface PurgeFailure {
+    message: Message;
+    /** The server's own words (a legal hold names itself), or a stand-in when it did not answer. */
+    reason: string;
+    /** The response's status - `undefined` when there was no response. */
+    status?: number;
+}
+
+/** What deleting several messages came to: those that are gone, and those that are not (with why). Together they are all that was asked for. */
+export interface PurgeOutcome {
+    deleted: Message[];
+    failed: PurgeFailure[];
+}
+
+/** What emptying a folder came to. */
+export interface EmptyFolderOutcome extends PurgeOutcome {
+    /** Nothing is left in the folder as far as this knows: the whole-folder request went through, or every message listed was deleted. */
+    emptied: boolean;
+}
+
+function describeFailure(err: unknown): { reason: string; status?: number } {
+    if (err instanceof ApiRequestError) {
+        return { reason: err.message || `The server answered ${err.status}.`, status: err.status };
+    }
+    return { reason: "The server couldn't be reached." };
+}
+
+/** `1 message`, `3 messages`. */
+export function messageCount(count: number): string {
+    return `${count} message${count === 1 ? "" : "s"}`;
+}
+
+/**
+ * Permanently deletes `messages`, each in its own request, a few at a time. Never rejects: a refusal (a legal hold, a share without the right
+ * to delete, a message that is already gone) is recorded against its message and the rest carry on. `deleted` and `failed` keep the order of
+ * `messages`.
+ */
+export async function purgeMessages(messages: Message[]): Promise<PurgeOutcome> {
+    const failures: (PurgeFailure | null)[] = new Array(messages.length).fill(null);
+    let next = 0;
+    async function worker(): Promise<void> {
+        while (next < messages.length) {
+            const index = next++;
+            try {
+                await purgeMessage(messages[index].uid);
+            } catch (err) {
+                failures[index] = { message: messages[index], ...describeFailure(err) };
+            }
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(PURGE_CONCURRENCY, messages.length) }, worker));
+    return {
+        deleted: messages.filter((_, index) => failures[index] === null),
+        failed: failures.filter((failure): failure is PurgeFailure => failure !== null),
+    };
+}
+
+/**
+ * Permanently deletes everything in `folderUid`: one request for the whole folder, which is all or nothing. The server refuses it as a whole
+ * when a message in it is under a legal hold (`409`) or when the caller may delete messages but not empty a folder (`403`, a delegate) - and
+ * then this lists the folder and deletes message by message instead, so what may go does and each refusal is reported. Any other failure
+ * (the server is down) rejects, and the caller says so.
+ */
+export async function purgeFolder(
+    folderUid: string,
+    paging: { pageSize: number; maxPages: number } = { pageSize: LIST_PAGE_SIZE, maxPages: MAX_LIST_PAGES },
+): Promise<EmptyFolderOutcome> {
+    try {
+        await emptyFolder(folderUid);
+        return { emptied: true, deleted: [], failed: [] };
+    } catch (err) {
+        if (!(err instanceof ApiRequestError) || (err.status !== 403 && err.status !== 409)) {
+            throw err;
+        }
+    }
+    const listed = await listAllPages((page) => listMessages(folderUid, { limit: paging.pageSize, page }), paging.pageSize, paging.maxPages);
+    const outcome = await purgeMessages(listed.items);
+    return { ...outcome, emptied: outcome.failed.length === 0 && !listed.truncated };
+}
+
+/** The line for one refusal, in the notification's details. */
+function failureLine(failure: PurgeFailure): string {
+    return `${displaySubject(failure.message.subject) || "(no subject)"}: ${failure.reason}`;
+}
+
+/**
+ * Tells the reader what a delete of several messages came to: "3 messages permanently deleted" (no Undo - there is none), or "2 deleted, 1
+ * could not be deleted" with the server's reasons.
+ */
+export function notifyPurged(outcome: PurgeOutcome): void {
+    const { deleted, failed } = outcome;
+    if (failed.length === 0) {
+        notify({ kind: "success", title: `${messageCount(deleted.length)} permanently deleted` });
+        return;
+    }
+    if (failed.some((failure) => failure.status === 401)) {
+        notifySessionExpired();
+        return;
+    }
+    const reasons = [...new Set(failed.map((failure) => failure.reason))];
+    notify({
+        kind: deleted.length > 0 ? "warning" : "error",
+        title:
+            deleted.length > 0
+                ? `${deleted.length} deleted, ${failed.length} could not be deleted`
+                : `Couldn't permanently delete ${failed.length === 1 ? "that message" : "those messages"}`,
+        message: reasons.slice(0, 3).join(" ") + (reasons.length > 3 ? ` (and ${reasons.length - 3} more reasons)` : ""),
+        details: failed.map(failureLine),
+        sticky: true,
+    });
+}
+
+/**
+ * Tells the reader what emptying `folderName` came to. `count` is how many messages it held, when that was known: the whole-folder request
+ * does not say. A folder that had to be deleted message by message reports as `notifyPurged()` does, plus a word when it was too big to be
+ * done in one go.
+ */
+export function notifyFolderEmptied(folderName: string, outcome: EmptyFolderOutcome, count?: number): void {
+    if (outcome.deleted.length === 0 && outcome.failed.length === 0 && outcome.emptied) {
+        notify({
+            kind: "success",
+            title: count === undefined ? `${folderName} emptied` : `${messageCount(count)} permanently deleted`,
+            message: count === undefined ? "Everything in it was permanently deleted." : `${folderName} is now empty.`,
+        });
+        return;
+    }
+    notifyPurged(outcome);
+    if (!outcome.emptied && outcome.failed.length === 0) {
+        notify({ kind: "info", title: `${folderName} is not empty yet`, message: "It holds more than could be deleted in one go. Empty it again to carry on." });
+    }
+}

package/apps/shared/mail/reportNotices.ts

@@ -0,0 +1,66 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { MessageReportKind, MessageReportResult } from "@rapidmx/react-shared/mail/mailApi.js";
+
+/** Where a notification's "Manage blocked senders" goes: the Blocked and safe senders page of the mailbox. */
+export function senderListsHref(mailboxUid: string): string {
+    return `/settings/blocked-senders?mailboxUid=${encodeURIComponent(mailboxUid)}`;
+}
+
+/** What a pop-up says about reporting `kind`: the title, and the folder the message goes to. */
+const KINDS: Record<MessageReportKind, { title: string; noun: string; folder: string }> = {
+    junk: { title: "Reported as junk", noun: "junk", folder: "Junk Email" },
+    phishing: { title: "Reported as phishing", noun: "phishing", folder: "Junk Email" },
+    not_junk: { title: "Marked as not junk", noun: "not junk", folder: "the Inbox" },
+};
+
+/** The noun of `kind` for a failure's title ("Couldn't report this message as phishing"). */
+export function reportNoun(kind: MessageReportKind): string {
+    return KINDS[kind].noun;
+}
+
+/** The title of a pop-up for a report of `kind`. */
+export function reportTitle(kind: MessageReportKind): string {
+    return KINDS[kind].title;
+}
+
+/** The name of the folder a report of `kind` files the message in. */
+export function reportFolderName(kind: MessageReportKind): string {
+    return KINDS[kind].folder;
+}
+
+/** What a pop-up for a report says. `hint` is the small muted line: only for the two things a reader may want to know about (the filter could not be
+ * taught, or the message is encrypted so it was not), never for the ones that are simply how the server is set up. */
+export interface ReportNotice {
+    title: string;
+    message: string;
+    hint?: string;
+}
+
+/**
+ * The words for what the server did with a report (`reportMessage()`'s answer): where the message went, whether the spam filter learned from it, and - for
+ * a report of phishing - that the server recorded it. `subject` names the message. `alwaysTrust` says the reader asked for the sender to be trusted.
+ */
+export function reportNotice(result: MessageReportResult, subject: string, alwaysTrust: boolean): ReportNotice {
+    const kind = KINDS[result.kind];
+    const where = result.moved ? `was moved to ${kind.folder}` : `is already in ${kind.folder}`;
+    const learned = result.learned ? " and used to train the spam filter" : "";
+    const parts = [`“${subject}” ${where}${learned}.`];
+    if (result.kind === "phishing") {
+        parts.push("The report was recorded in the audit log.");
+    }
+    if (result.safeSender) {
+        parts.push(`Mail from ${result.safeSender} that passes authentication is no longer sent to Junk Email.`);
+    } else if (alwaysTrust) {
+        parts.push("The message names no address that could be trusted.");
+    }
+    const hint =
+        result.learnSkipped === "failed"
+            ? "The spam filter could not be trained from this report."
+            : result.learnSkipped === "encrypted"
+              ? "Not used to train the spam filter: the message is encrypted."
+              : undefined;
+    return { title: kind.title, message: parts.join(" "), hint };
+}

package/apps/shared/mail/senderBlocking.ts

@@ -0,0 +1,141 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import {
+    MailFilterRule,
+    createMailFilterRule,
+    deleteMailFilterRule,
+    listMailFilterRules,
+    updateMailFilterRule,
+} from "@rapidmx/react-shared/mail/mailFilterRulesApi.js";
+
+/**
+ * "Block sender" and "Never block sender", expressed as the mailbox's own mail filter rules - the server has no blocked-senders list.
+ * A rule's "From contains" is a case-insensitive substring match on the From header (restapi's `matchesConditions()`), which is the
+ * closest thing there is to "from equals": it also matches a longer address that ends in this one (`joann@x.com` for `ann@x.com`).
+ *
+ * - **Block** is `From contains <address>` -> move to the mailbox's Junk Email, stop processing more rules, ahead of every other rule
+ * (a sequence below all of them), so nothing else files the sender's mail first.
+ * - **Never block** is `From contains <address>` -> move to the Inbox, stop processing, likewise first. It keeps the sender's mail out of
+ * the reader's own blocking and filing rules. It cannot keep it out of Junk when the spam filter sends it there: mail the spam filter
+ * has judged junk skips every rule (restapi's `ScanQueueJob.deliverMessage()`).
+ *
+ * Rules are found by what they do, not by their name, so one the reader renamed or made by hand is still the rule for that sender.
+ */
+
+/** Every rule listing asks for up to this many, which is the most the mail server reads when it filters a delivery. */
+const RULE_LIMIT = 500;
+
+export const BLOCK_RULE_PREFIX = "Block ";
+export const NEVER_BLOCK_RULE_PREFIX = "Never block ";
+
+/** `addresses` trimmed, lowercased and without repeats, keeping only what has an `@`. */
+export function normalizeAddresses(addresses: (string | undefined)[]): string[] {
+    return [...new Set(addresses.map((address) => address?.trim().toLowerCase() ?? "").filter((address) => address.includes("@")))];
+}
+
+/** Whether `rule` is "From contains ..." (every address of `addresses` among them, and nothing else) and moves to `folderUid` and stops. */
+function isSenderRule(rule: MailFilterRule, addresses: string[], folderUid: string): boolean {
+    const conditions = rule.conditions as Record<string, unknown>;
+    const only = Object.keys(conditions).every((key) => key === "fromContains" || conditions[key] === undefined);
+    const from = (rule.conditions.fromContains ?? []).map((entry) => entry.toLowerCase());
+    return (
+        only &&
+        addresses.every((address) => from.includes(address)) &&
+        rule.stopProcessingRules &&
+        rule.actions.length === 1 &&
+        rule.actions[0].type === "move_to_folder" &&
+        rule.actions[0].folderUid === folderUid
+    );
+}
+
+/** What blocking a sender did: `created` the rule, found it `existing` (and on), or turned an existing one back on. */
+export interface BlockResult {
+    outcome: "created" | "existing" | "enabled";
+    rule: MailFilterRule;
+}
+
+/** What "Never block" did: the block rules it took away, and the rule that keeps the sender in the Inbox (`created` now or found). */
+export interface NeverBlockResult {
+    removed: MailFilterRule[];
+    outcome: "created" | "existing" | "enabled";
+    rule: MailFilterRule;
+}
+
+/** A sequence that puts a new rule ahead of every rule the mailbox has. */
+function firstSequence(rules: MailFilterRule[]): number {
+    return Math.min(0, ...rules.map((rule) => rule.sequence)) - 1;
+}
+
+/** Finds the rule that does `folderUid` for `addresses`, makes one (named `${prefix}${addresses[0]}`) if there is none, and turns a found one on. */
+async function ensureRule(
+    rules: MailFilterRule[],
+    mailboxUid: string,
+    addresses: string[],
+    folderUid: string,
+    prefix: string,
+): Promise<{ outcome: "created" | "existing" | "enabled"; rule: MailFilterRule }> {
+    const found = rules.find((rule) => isSenderRule(rule, addresses, folderUid));
+    if (found) {
+        if (found.enabled) {
+            return { outcome: "existing", rule: found };
+        }
+        // The whole rule, as the filters page saves one: the update replaces the record.
+        const { uid, version, name, sequence, stopProcessingRules, conditions, actions } = found;
+        return { outcome: "enabled", rule: await updateMailFilterRule({ uid, version, name, enabled: true, sequence, stopProcessingRules, conditions, actions }) };
+    }
+    const rule = await createMailFilterRule({
+        mailboxUid,
+        name: `${prefix}${addresses[0]}`,
+        sequence: firstSequence(rules),
+        stopProcessingRules: true,
+        conditions: { fromContains: addresses },
+        actions: [{ type: "move_to_folder", folderUid }],
+    });
+    return { outcome: "created", rule };
+}
+
+/** Takes away every rule that is `folderUid` for `addresses`. */
+async function removeRules(rules: MailFilterRule[], addresses: string[], folderUid: string): Promise<MailFilterRule[]> {
+    const doomed = rules.filter((rule) => isSenderRule(rule, addresses, folderUid));
+    for (const rule of doomed) {
+        await deleteMailFilterRule(rule.uid, rule.version);
+    }
+    return doomed;
+}
+
+/**
+ * Blocks a sender: mail from `addresses` (its envelope sender and From header address, when they differ - a mailing list or a bulk sender
+ * usually has both) goes to `junkFolderUid` from now on. Idempotent: the rule is made once, and a rule that was turned off is turned on.
+ * A "Never block" rule for the same sender is taken away, since the two would fight.
+ */
+export async function blockSender(mailboxUid: string, addresses: string[], junkFolderUid: string, inboxFolderUid: string): Promise<BlockResult> {
+    const rules = await listMailFilterRules(mailboxUid, { limit: RULE_LIMIT });
+    await removeRules(rules, addresses, inboxFolderUid);
+    return ensureRule(rules, mailboxUid, addresses, junkFolderUid, BLOCK_RULE_PREFIX);
+}
+
+/** Never blocks a sender: takes away the block rule for `addresses` and makes (once) the rule that keeps their mail in the Inbox. */
+export async function neverBlockSender(
+    mailboxUid: string,
+    addresses: string[],
+    junkFolderUid: string,
+    inboxFolderUid: string,
+): Promise<NeverBlockResult> {
+    const rules = await listMailFilterRules(mailboxUid, { limit: RULE_LIMIT });
+    const removed = await removeRules(rules, addresses, junkFolderUid);
+    const kept = await ensureRule(
+        rules.filter((rule) => !removed.includes(rule)),
+        mailboxUid,
+        addresses,
+        inboxFolderUid,
+        NEVER_BLOCK_RULE_PREFIX,
+    );
+    return { removed, ...kept };
+}
+
+/** Takes back a rule this module made (the notification's Undo). */
+export function removeSenderRule(rule: MailFilterRule): Promise<void> {
+    return deleteMailFilterRule(rule.uid, rule.version);
+}

package/apps/shared/mail/useMailboxUpdateAccess.ts

@@ -0,0 +1,60 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import type { Mailbox } from "@rapidmx/react-shared/mail/mailApi.js";
+import { getMyMailboxAccess } from "@rapidmx/react-shared/mail/mailboxAccessApi.js";
+
+/** What the server said about the caller's update access to a mailbox, remembered per mailbox for the page load. */
+const answers = new Map<string, Promise<boolean | undefined>>();
+
+/** Forgets every remembered answer - for the tests, and anything that changes the caller's access mid-session. */
+export function clearMailboxUpdateAccessCache(): void {
+    answers.clear();
+}
+
+/** Whether the caller may change things in `mailboxUid` (move, mark and flag its messages, add its filters): the server's own ACL check. Never rejects; `undefined` when it could not be asked (which is not cached). */
+function fetchUpdateAccess(mailboxUid: string): Promise<boolean | undefined> {
+    let answer = answers.get(mailboxUid);
+    if (!answer) {
+        answer = getMyMailboxAccess(mailboxUid).then(
+            (access) => access.canUpdate,
+            () => {
+                answers.delete(mailboxUid);
+                return undefined;
+            },
+        );
+        answers.set(mailboxUid, answer);
+    }
+    return answer;
+}
+
+/**
+ * Whether the reader may change the messages of `mailbox`: `false` only for a mailbox shared with them (`accessRole: "delegate"`) that
+ * the server says they may not update - a view-only share. Everything else is `true` from the first render: the reader's own mailbox
+ * needs no request, and a mailbox that is unknown (the shell has not listed it), or whose access could not be read, is treated as
+ * writable - the server still refuses what is not allowed, and hiding a usable action over a failed lookup is worse than offering one
+ * that then says why it failed.
+ */
+export function useMailboxUpdateAccess(mailbox: Mailbox | undefined): boolean {
+    const uid = mailbox?.uid;
+    const delegated = mailbox?.accessRole === "delegate";
+    const [writable, setWritable] = useState(true);
+    useEffect(() => {
+        setWritable(true);
+        if (!uid || !delegated) {
+            return;
+        }
+        let cancelled = false;
+        void fetchUpdateAccess(uid).then((canUpdate) => {
+            if (!cancelled && canUpdate === false) {
+                setWritable(false);
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [uid, delegated]);
+    return writable;
+}

package/apps/shared/mail/usePermanentDelete.tsx

@@ -0,0 +1,160 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { ReactElement, useRef, useState } from "react";
+import type { Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import PermanentDeleteDialog from "../components/mail/PermanentDeleteDialog.js";
+import { useMailShell } from "../components/mail/layout/MailShell.js";
+import { notifyApiError } from "../notifications/apiErrors.js";
+import { removeLocalEntity } from "../search/localIndexRpcClient.js";
+import {
+    EmptyFolderOutcome,
+    PurgeOutcome,
+    messageCount,
+    notifyFolderEmptied,
+    notifyPurged,
+    purgeFolder,
+    purgeMessages,
+} from "./permanentDelete.js";
+
+/** The folder "Empty folder" is about. */
+export interface EmptiableFolder {
+    uid: string;
+    name: string;
+}
+
+export interface PermanentDelete {
+    /**
+     * Asks, then permanently deletes `messages` (Delete in Deleted Items - the Delete menu item of a message card calls this too). Resolves
+     * with what came of it once the dialog is gone, and everything a delete has to tell has been told: the folder badges follow, the local
+     * search index drops the messages, and a notification says "N messages permanently deleted" or which could not be and why. Resolves
+     * `null` - and sends nothing - when the reader cancels, when `messages` is empty, or while another request is already open.
+     */
+    requestPermanentDelete: (messages: Message[]) => Promise<PurgeOutcome | null>;
+    /**
+     * Asks, then permanently deletes everything in `folder`. `count` is how many messages it holds when that is known (the dialog and the
+     * notification then say so). Resolves as `requestPermanentDelete()` does; a request that failed outright (the server is down) has said so and resolves an
+     * outcome with nothing deleted, so the caller reloads what it lists.
+     */
+    requestEmptyFolder: (folder: EmptiableFolder, count?: number) => Promise<EmptyFolderOutcome | null>;
+    /** A request is open (the dialog is up, or the delete is on the wire): what should hold every other action of the list meanwhile. */
+    busy: boolean;
+    /** The confirmation dialog - render it once, anywhere (it is a portal). */
+    dialog: ReactElement;
+}
+
+type Request = { kind: "messages"; messages: Message[] } | { kind: "folder"; folder: EmptiableFolder; count?: number };
+
+interface Pending {
+    request: Request;
+    resolve: (outcome: never) => void;
+}
+
+/**
+ * The one place a permanent delete is confirmed and carried out - for the mail list (the selection bar, the Delete key, Empty folder) and
+ * for a message card's own Delete, so all of them ask the same question, delete the same way and report the same way. Call it inside the
+ * mail shell (it keeps that shell's folder badges right).
+ *
+ * The reader always confirms: nothing is remembered between requests.
+ */
+export function usePermanentDelete(): PermanentDelete {
+    const { trackMessageChange, refreshFolderCounts } = useMailShell();
+    const [pending, setPending] = useState<Pending | null>(null);
+    const [running, setRunning] = useState(false);
+    // Set at once (state is a render later), so a key pressed twice does not open two dialogs.
+    const pendingRef = useRef<Pending | null>(null);
+
+    function ask<T>(request: Request): Promise<T | null> {
+        if (pendingRef.current) {
+            return Promise.resolve(null);
+        }
+        return new Promise<T | null>((resolve) => {
+            const next: Pending = { request, resolve };
+            pendingRef.current = next;
+            setPending(next);
+        });
+    }
+
+    function requestPermanentDelete(messages: Message[]): Promise<PurgeOutcome | null> {
+        return messages.length === 0 ? Promise.resolve(null) : ask<PurgeOutcome>({ kind: "messages", messages });
+    }
+
+    function requestEmptyFolder(folder: EmptiableFolder, count?: number): Promise<EmptyFolderOutcome | null> {
+        return ask<EmptyFolderOutcome>({ kind: "folder", folder, count });
+    }
+
+    /** Closes the dialog and hands the caller what came of it. */
+    function finish(outcome: PurgeOutcome | null) {
+        const current = pendingRef.current!;
+        pendingRef.current = null;
+        setPending(null);
+        setRunning(false);
+        current.resolve(outcome as never);
+    }
+
+    /** What every delete tells the rest of the page: the badges (each message is one fewer in its folder) and the local search index. */
+    function afterDeleted(deleted: Message[]) {
+        for (const message of deleted) {
+            trackMessageChange(message, null).settle();
+            void removeLocalEntity(message.mailboxUid, message.uid);
+        }
+    }
+
+    async function confirm() {
+        const { request } = pendingRef.current!;
+        setRunning(true);
+        if (request.kind === "messages") {
+            const outcome = await purgeMessages(request.messages);
+            afterDeleted(outcome.deleted);
+            notifyPurged(outcome);
+            finish(outcome);
+            return;
+        }
+        let outcome: EmptyFolderOutcome;
+        try {
+            outcome = await purgeFolder(request.folder.uid);
+        } catch (err) {
+            notifyApiError(err, `Couldn't empty ${request.folder.name}`);
+            // Part of it may have gone before the failure: the caller reloads rather than assume nothing did.
+            outcome = { emptied: false, deleted: [], failed: [] };
+        }
+        afterDeleted(outcome.deleted);
+        // The whole-folder request does not say which messages went, so the counts are read back rather than adjusted.
+        refreshFolderCounts();
+        if (outcome.emptied || outcome.deleted.length > 0 || outcome.failed.length > 0) {
+            notifyFolderEmptied(request.folder.name, outcome, request.count);
+        }
+        finish(outcome);
+    }
+
+    function cancel() {
+        finish(null);
+    }
+
+    const request = pending?.request;
+    const folderRequest = request?.kind === "folder" ? request : undefined;
+    const dialog = (
+        <PermanentDeleteDialog
+            open={pending !== null}
+            title={folderRequest ? `Empty ${folderRequest.folder.name}` : "Delete permanently"}
+            message={
+                folderRequest
+                    ? `Permanently delete ${
+                          folderRequest.count === undefined
+                              ? "all items"
+                              : folderRequest.count === 1
+                                ? "the only item"
+                                : `all ${folderRequest.count} items`
+                      } in ${folderRequest.folder.name}? This can't be undone.`
+                    : `Permanently delete ${messageCount(request?.kind === "messages" ? request.messages.length : 0)}? This can't be undone.`
+            }
+            confirmLabel={folderRequest ? "Delete all permanently" : "Delete permanently"}
+            busy={running}
+            onConfirm={() => void confirm()}
+            onCancel={cancel}
+        />
+    );
+
+    return { requestPermanentDelete, requestEmptyFolder, busy: pending !== null, dialog };
+}

package/apps/shared/navigation/frameContext.tsx

@@ -5,7 +5,7 @@
 import React, { PropsWithChildren, createContext, useContext, useLayoutEffect } from "react";
 
 /**
- * What the persistent app frame (`AppRouter`'s one mounted `AppShell` chrome) offers to what is rendered inside it. `null`
+ * What the persistent app frame (the webmail's router shell, `apps/www/_shell.tsx`, whose one mounted `AppChrome` never unmounts) offers to what is rendered inside it. `null`
  * outside a frame - a page not shown by the router (an admin page, a plugin page, a test) renders its own chrome.
  */
 export interface AppFrameContextValue {