@rapidmx/web-client 0.15.1 → 0.17.0

package/apps/shared/mail/useMarkMessageRead.ts

@@ -1,47 +1,47 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import { useEffect, useRef } from "react";
-import type { Message } from "@rapidmx/react-shared/mail/mailApi.js";
-import { useMailShell } from "../components/mail/layout/MailShell.js";
-import { setReadState } from "./messageReadState.js";
-
-/**
- * Marks a message read when it is opened in a reading pane, through `setReadState()`: the row and the folder badge change at
- * once. `onPatched` is handed each copy of the message as it changes (the optimistic one, then the server's, or the original
- * again if the server refused).
- *
- * Replaces `@rapidmx/react-shared`'s `useMarkMessageRead`, which waits for the server before telling anyone and drops that
- * answer if the message changes meanwhile - which the optimistic copy itself does. A message is asked for once each time it is
- * opened: one the reader then marks unread stays unread while it is open, and one whose request failed is not retried in a loop
- * (its own revert changes it again), only when it is opened again.
- */
-export function useMarkMessageRead(message: Message | null, onPatched: (updated: Message, previous?: Message) => void): void {
-    const { trackMessageChange } = useMailShell();
-    const openUidRef = useRef<string | undefined>(undefined);
-    const requestedRef = useRef<Set<string>>(new Set());
-    const latestRef = useRef({ onPatched, trackMessageChange });
-    latestRef.current = { onPatched, trackMessageChange };
-
-    useEffect(() => {
-        if (message?.uid !== openUidRef.current) {
-            // Another message (or none) is open now: whatever was asked about the last one is over.
-            openUidRef.current = message?.uid;
-            requestedRef.current.clear();
-        }
-        if (!message || requestedRef.current.has(message.uid)) {
-            return;
-        }
-        // Every opening is asked about once - a message that is already read included, so that marking it unread while it is open (the
-        // keyboard's Ctrl+U) doesn't make this run again and read it straight back.
-        requestedRef.current.add(message.uid);
-        if (message.flags.read === true) {
-            return;
-        }
-        void setReadState(message, true, {
-            patch: (updated, previous) => latestRef.current.onPatched(updated, previous),
-            track: (previous, next) => latestRef.current.trackMessageChange(previous, next),
-        });
-    }, [message]);
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useRef } from "react";
+import type { Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import { useMailShell } from "../components/mail/layout/MailShell.js";
+import { setReadState } from "./messageReadState.js";
+
+/**
+ * Marks a message read when it is opened in a reading pane, through `setReadState()`: the row and the folder badge change at
+ * once. `onPatched` is handed each copy of the message as it changes (the optimistic one, then the server's, or the original
+ * again if the server refused).
+ *
+ * Replaces `@rapidmx/react-shared`'s `useMarkMessageRead`, which waits for the server before telling anyone and drops that
+ * answer if the message changes meanwhile - which the optimistic copy itself does. A message is asked for once each time it is
+ * opened: one the reader then marks unread stays unread while it is open, and one whose request failed is not retried in a loop
+ * (its own revert changes it again), only when it is opened again.
+ */
+export function useMarkMessageRead(message: Message | null, onPatched: (updated: Message, previous?: Message) => void): void {
+    const { trackMessageChange } = useMailShell();
+    const openUidRef = useRef<string | undefined>(undefined);
+    const requestedRef = useRef<Set<string>>(new Set());
+    const latestRef = useRef({ onPatched, trackMessageChange });
+    latestRef.current = { onPatched, trackMessageChange };
+
+    useEffect(() => {
+        if (message?.uid !== openUidRef.current) {
+            // Another message (or none) is open now: whatever was asked about the last one is over.
+            openUidRef.current = message?.uid;
+            requestedRef.current.clear();
+        }
+        if (!message || requestedRef.current.has(message.uid)) {
+            return;
+        }
+        // Every opening is asked about once - a message that is already read included, so that marking it unread while it is open (the
+        // keyboard's Ctrl+U) doesn't make this run again and read it straight back.
+        requestedRef.current.add(message.uid);
+        if (message.flags.read === true) {
+            return;
+        }
+        void setReadState(message, true, {
+            patch: (updated, previous) => latestRef.current.onPatched(updated, previous),
+            track: (previous, next) => latestRef.current.trackMessageChange(previous, next),
+        });
+    }, [message]);
+}

package/apps/shared/mail/useNewMailNotifications.ts

@@ -1,178 +1,178 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import type { Mailbox, Message } from "@rapidmx/react-shared/mail/mailApi.js";
-import type { MailboxFolders } from "../components/mail/layout/MailShell.js";
-import {
-    DesktopPermission,
-    NewMailNotice,
-    desktopPermission,
-    getDesktopOfferDismissed,
-    noticeFor,
-    noticeSender,
-    ownAddressesOf,
-    requestDesktopPermission,
-    setDesktopOfferDismissed,
-    shouldAnnounce,
-} from "./newMailNotifications.js";
-import { getNotificationsEnabled } from "../notifications/preferences.js";
-import { getNotificationsSnapshot, notify } from "../notifications/store.js";
-
-/** How long a new-mail pop-up stays before it goes by itself (while it is neither hovered nor focused, and the tab is in view). */
-export const TOAST_DURATION_MS = 8_000;
-
-/** At most this many desktop notifications in `DESKTOP_BURST_WINDOW_MS`: a flood of mail is a few notifications, not a hundred. */
-export const DESKTOP_BURST_LIMIT = 5;
-export const DESKTOP_BURST_WINDOW_MS = 30_000;
-
-/** How many announced message uids are remembered, so an event delivered twice is announced once. */
-const ANNOUNCED_LIMIT = 500;
-
-export interface NewMailNotifications {
-    /** Whether the next pop-up should also offer to turn on desktop notifications: the browser can, has not been asked,
-     * and the user has not said "Not now". */
-    offerDesktop: boolean;
-    /** The offer's "Turn on desktop notifications": asks the browser. Must be called from a click. */
-    enableDesktop(): Promise<void>;
-    /** The offer's "Not now": remembered, so it is not made again. */
-    declineDesktop(): void;
-    /** Announces a message that just arrived - if it is worth it (see `shouldAnnounce()`) and pop-ups are on. Stable. */
-    announce(message: Message): void;
-}
-
-/** Whether the user is not looking at this tab: it is hidden, or another window has the focus. */
-function tabIsInBackground(): boolean {
-    return document.visibilityState === "hidden" || !document.hasFocus();
-}
-
-export interface UseNewMailNotificationsOptions {
-    mailboxes: Mailbox[];
-    mailboxFolders: MailboxFolders[];
-    /** Opens a message from a desktop notification's click. Defaults to a plain navigation. */
-    open?: (href: string) => void;
-}
-
-function defaultOpen(href: string): void {
-    window.location.href = href;
-}
-
-/**
- * New-mail announcements: an in-app pop-up for each message that arrives (a `mail` notification - see `notifications/store.ts`, which owns the
- * stack, its limit of three and the clock), and - while the tab
- * is in the background and the user has allowed it - a desktop notification with the same content, one per message however
- * many events name it. `announce()` is what `useMailLiveUpdates()`'s `onMessageCreated` calls; nothing else feeds it, so a
- * page load, a list refetch and a reconnect never announce anything.
- *
- * Nothing is ever asked of the browser on load: permission is requested only by `enableDesktop()`, from the offer in the
- * first pop-up, or from Settings. What the user answered is remembered in `localStorage` (see `newMailNotifications.ts`).
- */
-export function useNewMailNotifications({ mailboxes, mailboxFolders, open = defaultOpen }: UseNewMailNotificationsOptions): NewMailNotifications {
-    const [permission, setPermission] = useState<DesktopPermission>("unsupported");
-    const [offerDismissed, setOfferDismissed] = useState(true);
-    const folders = useMemo(() => mailboxFolders.flatMap((entry) => entry.folders), [mailboxFolders]);
-    const ownAddresses = useMemo(() => ownAddressesOf(mailboxes), [mailboxes]);
-    const latestRef = useRef({ folders, ownAddresses, open });
-    latestRef.current = { folders, ownAddresses, open };
-    const announcedRef = useRef<Set<string>>(new Set());
-    const desktopShownRef = useRef<number[]>([]);
-
-    // The browser's own state is only read on the client, after hydration, so the server and first client render agree.
-    useEffect(() => {
-        setPermission(desktopPermission());
-        setOfferDismissed(getDesktopOfferDismissed());
-    }, []);
-
-    const showDesktop = useCallback((notice: NewMailNotice) => {
-        const now = Date.now();
-        desktopShownRef.current = desktopShownRef.current.filter((at) => now - at < DESKTOP_BURST_WINDOW_MS);
-        if (desktopShownRef.current.length >= DESKTOP_BURST_LIMIT) {
-            return;
-        }
-        try {
-            const notification = new Notification(noticeSender(notice), {
-                body: [notice.subject, notice.preview].filter(Boolean).join("\n"),
-                // One per message: a duplicate (another tab of this app, a re-delivered event) replaces instead of stacking.
-                tag: notice.uid,
-            });
-            desktopShownRef.current.push(now);
-            notification.onclick = () => {
-                window.focus();
-                notification.close();
-                latestRef.current.open(notice.href);
-            };
-        } catch {
-            // Some browsers refuse `new Notification()` outright (a mobile one wanting a service worker): the pop-up is enough.
-        }
-    }, []);
-
-    const enableDesktop = useCallback(async () => {
-        const answer = await requestDesktopPermission();
-        setPermission(answer);
-        // Answered either way, so the offer goes: on granted it has done its job, on denied it can't be made again.
-        setDesktopOfferDismissed(true);
-        setOfferDismissed(true);
-    }, []);
-
-    const declineDesktop = useCallback(() => {
-        setDesktopOfferDismissed(true);
-        setOfferDismissed(true);
-    }, []);
-
-    // The offer's current state and answers, for the stable `announce` below.
-    const offerDesktop = permission === "default" && !offerDismissed;
-    const offerRef = useRef({ offered: offerDesktop, enable: enableDesktop, decline: declineDesktop });
-    offerRef.current = { offered: offerDesktop, enable: enableDesktop, decline: declineDesktop };
-
-    const announce = useCallback(
-        (message: Message) => {
-            if (!getNotificationsEnabled() || announcedRef.current.has(message.uid)) {
-                return;
-            }
-            const { folders: knownFolders, ownAddresses: own } = latestRef.current;
-            if (!shouldAnnounce(message, { folders: knownFolders, ownAddresses: own })) {
-                return;
-            }
-            announcedRef.current.add(message.uid);
-            if (announcedRef.current.size > ANNOUNCED_LIMIT) {
-                announcedRef.current.delete(announcedRef.current.values().next().value!);
-            }
-            const notice = noticeFor(message);
-            const offer = offerRef.current;
-            notify({
-                id: `mail:${notice.uid}`,
-                kind: "mail",
-                title: notice.senderName || notice.senderAddress,
-                subtitle: notice.senderName ? `<${notice.senderAddress}>` : undefined,
-                message: notice.subject,
-                preview: notice.preview || undefined,
-                href: notice.href,
-                timeoutMs: TOAST_DURATION_MS,
-                // Actions make a notification sticky; a new-mail pop-up with the offer still goes by itself.
-                sticky: false,
-                // The offer is made once at a time: on a pop-up only while none of the pop-ups still showing carries it.
-                ...(offer.offered && !getNotificationsSnapshot().visible.some((item) => item.kind === "mail" && item.actions.length > 0)
-                    ? {
-                          hint: "Get a desktop notification when mail arrives while this tab is in the background.",
-                          actions: [
-                              { label: "Turn on desktop notifications", onClick: () => void offer.enable() },
-                              { label: "Not now", onClick: offer.decline },
-                          ],
-                      }
-                    : {}),
-            });
-            if (desktopPermission() === "granted" && tabIsInBackground()) {
-                showDesktop(notice);
-            }
-        },
-        [showDesktop],
-    );
-
-    return {
-        offerDesktop,
-        enableDesktop,
-        declineDesktop,
-        announce,
-    };
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { Mailbox, Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { MailboxFolders } from "../components/mail/layout/MailShell.js";
+import {
+    DesktopPermission,
+    NewMailNotice,
+    desktopPermission,
+    getDesktopOfferDismissed,
+    noticeFor,
+    noticeSender,
+    ownAddressesOf,
+    requestDesktopPermission,
+    setDesktopOfferDismissed,
+    shouldAnnounce,
+} from "./newMailNotifications.js";
+import { getNotificationsEnabled } from "../notifications/preferences.js";
+import { getNotificationsSnapshot, notify } from "../notifications/store.js";
+
+/** How long a new-mail pop-up stays before it goes by itself (while it is neither hovered nor focused, and the tab is in view). */
+export const TOAST_DURATION_MS = 8_000;
+
+/** At most this many desktop notifications in `DESKTOP_BURST_WINDOW_MS`: a flood of mail is a few notifications, not a hundred. */
+export const DESKTOP_BURST_LIMIT = 5;
+export const DESKTOP_BURST_WINDOW_MS = 30_000;
+
+/** How many announced message uids are remembered, so an event delivered twice is announced once. */
+const ANNOUNCED_LIMIT = 500;
+
+export interface NewMailNotifications {
+    /** Whether the next pop-up should also offer to turn on desktop notifications: the browser can, has not been asked,
+     * and the user has not said "Not now". */
+    offerDesktop: boolean;
+    /** The offer's "Turn on desktop notifications": asks the browser. Must be called from a click. */
+    enableDesktop(): Promise<void>;
+    /** The offer's "Not now": remembered, so it is not made again. */
+    declineDesktop(): void;
+    /** Announces a message that just arrived - if it is worth it (see `shouldAnnounce()`) and pop-ups are on. Stable. */
+    announce(message: Message): void;
+}
+
+/** Whether the user is not looking at this tab: it is hidden, or another window has the focus. */
+function tabIsInBackground(): boolean {
+    return document.visibilityState === "hidden" || !document.hasFocus();
+}
+
+export interface UseNewMailNotificationsOptions {
+    mailboxes: Mailbox[];
+    mailboxFolders: MailboxFolders[];
+    /** Opens a message from a desktop notification's click. Defaults to a plain navigation. */
+    open?: (href: string) => void;
+}
+
+function defaultOpen(href: string): void {
+    window.location.href = href;
+}
+
+/**
+ * New-mail announcements: an in-app pop-up for each message that arrives (a `mail` notification - see `notifications/store.ts`, which owns the
+ * stack, its limit of three and the clock), and - while the tab
+ * is in the background and the user has allowed it - a desktop notification with the same content, one per message however
+ * many events name it. `announce()` is what `useMailLiveUpdates()`'s `onMessageCreated` calls; nothing else feeds it, so a
+ * page load, a list refetch and a reconnect never announce anything.
+ *
+ * Nothing is ever asked of the browser on load: permission is requested only by `enableDesktop()`, from the offer in the
+ * first pop-up, or from Settings. What the user answered is remembered in `localStorage` (see `newMailNotifications.ts`).
+ */
+export function useNewMailNotifications({ mailboxes, mailboxFolders, open = defaultOpen }: UseNewMailNotificationsOptions): NewMailNotifications {
+    const [permission, setPermission] = useState<DesktopPermission>("unsupported");
+    const [offerDismissed, setOfferDismissed] = useState(true);
+    const folders = useMemo(() => mailboxFolders.flatMap((entry) => entry.folders), [mailboxFolders]);
+    const ownAddresses = useMemo(() => ownAddressesOf(mailboxes), [mailboxes]);
+    const latestRef = useRef({ folders, ownAddresses, open });
+    latestRef.current = { folders, ownAddresses, open };
+    const announcedRef = useRef<Set<string>>(new Set());
+    const desktopShownRef = useRef<number[]>([]);
+
+    // The browser's own state is only read on the client, after hydration, so the server and first client render agree.
+    useEffect(() => {
+        setPermission(desktopPermission());
+        setOfferDismissed(getDesktopOfferDismissed());
+    }, []);
+
+    const showDesktop = useCallback((notice: NewMailNotice) => {
+        const now = Date.now();
+        desktopShownRef.current = desktopShownRef.current.filter((at) => now - at < DESKTOP_BURST_WINDOW_MS);
+        if (desktopShownRef.current.length >= DESKTOP_BURST_LIMIT) {
+            return;
+        }
+        try {
+            const notification = new Notification(noticeSender(notice), {
+                body: [notice.subject, notice.preview].filter(Boolean).join("\n"),
+                // One per message: a duplicate (another tab of this app, a re-delivered event) replaces instead of stacking.
+                tag: notice.uid,
+            });
+            desktopShownRef.current.push(now);
+            notification.onclick = () => {
+                window.focus();
+                notification.close();
+                latestRef.current.open(notice.href);
+            };
+        } catch {
+            // Some browsers refuse `new Notification()` outright (a mobile one wanting a service worker): the pop-up is enough.
+        }
+    }, []);
+
+    const enableDesktop = useCallback(async () => {
+        const answer = await requestDesktopPermission();
+        setPermission(answer);
+        // Answered either way, so the offer goes: on granted it has done its job, on denied it can't be made again.
+        setDesktopOfferDismissed(true);
+        setOfferDismissed(true);
+    }, []);
+
+    const declineDesktop = useCallback(() => {
+        setDesktopOfferDismissed(true);
+        setOfferDismissed(true);
+    }, []);
+
+    // The offer's current state and answers, for the stable `announce` below.
+    const offerDesktop = permission === "default" && !offerDismissed;
+    const offerRef = useRef({ offered: offerDesktop, enable: enableDesktop, decline: declineDesktop });
+    offerRef.current = { offered: offerDesktop, enable: enableDesktop, decline: declineDesktop };
+
+    const announce = useCallback(
+        (message: Message) => {
+            if (!getNotificationsEnabled() || announcedRef.current.has(message.uid)) {
+                return;
+            }
+            const { folders: knownFolders, ownAddresses: own } = latestRef.current;
+            if (!shouldAnnounce(message, { folders: knownFolders, ownAddresses: own })) {
+                return;
+            }
+            announcedRef.current.add(message.uid);
+            if (announcedRef.current.size > ANNOUNCED_LIMIT) {
+                announcedRef.current.delete(announcedRef.current.values().next().value!);
+            }
+            const notice = noticeFor(message);
+            const offer = offerRef.current;
+            notify({
+                id: `mail:${notice.uid}`,
+                kind: "mail",
+                title: notice.senderName || notice.senderAddress,
+                subtitle: notice.senderName ? `<${notice.senderAddress}>` : undefined,
+                message: notice.subject,
+                preview: notice.preview || undefined,
+                href: notice.href,
+                timeoutMs: TOAST_DURATION_MS,
+                // Actions make a notification sticky; a new-mail pop-up with the offer still goes by itself.
+                sticky: false,
+                // The offer is made once at a time: on a pop-up only while none of the pop-ups still showing carries it.
+                ...(offer.offered && !getNotificationsSnapshot().visible.some((item) => item.kind === "mail" && item.actions.length > 0)
+                    ? {
+                          hint: "Get a desktop notification when mail arrives while this tab is in the background.",
+                          actions: [
+                              { label: "Turn on desktop notifications", onClick: () => void offer.enable() },
+                              { label: "Not now", onClick: offer.decline },
+                          ],
+                      }
+                    : {}),
+            });
+            if (desktopPermission() === "granted" && tabIsInBackground()) {
+                showDesktop(notice);
+            }
+        },
+        [showDesktop],
+    );
+
+    return {
+        offerDesktop,
+        enableDesktop,
+        declineDesktop,
+        announce,
+    };
+}

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 {