@rapidmx/web-client 0.15.1 → 0.17.0

package/apps/shared/keyboard/targets.ts

@@ -1,79 +1,79 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-
-/** `<input>` types that take no typed text, so a letter pressed on one is a shortcut, not input. (Radios and ranges use the arrows.) */
-const NON_TEXT_INPUT_TYPES = new Set(["button", "checkbox", "submit", "reset", "image", "file", "color"]);
-
-/** Roles whose members have keys of their own (arrows, Enter, Escape, type-ahead): a bare key pressed inside one belongs to the widget. */
-const WIDGET_SELECTOR = [
-    "menu",
-    "menubar",
-    "listbox",
-    "tablist",
-    "tree",
-    "grid",
-    "radiogroup",
-    "slider",
-    "spinbutton",
-    "combobox",
-]
-    .map((role) => `[role="${role}"]`)
-    .join(",");
-
-/** Elements Enter (and Space) already does something on. */
-const ACTIVATABLE_SELECTOR = 'a[href], button, summary, [role="button"], [role="link"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="tab"], [role="option"]';
-
-/** An open popup's trigger: Escape closes the popup, so it is not a shortcut then. */
-const OPEN_POPUP_TRIGGER = '[aria-haspopup][aria-expanded="true"], [role="combobox"][aria-expanded="true"]';
-
-function elementOf(target: EventTarget | null): Element | null {
-    return target instanceof Element ? target : null;
-}
-
-/** Whether the event target takes typed text: a text field, a select, a textarea, or anything contenteditable (the rich-text editor). */
-export function isTextEntry(target: EventTarget | null): boolean {
-    const element = elementOf(target);
-    if (!element) {
-        return false;
-    }
-    const tag = element.tagName;
-    if (tag === "TEXTAREA" || tag === "SELECT") {
-        return true;
-    }
-    if (tag === "INPUT") {
-        return !NON_TEXT_INPUT_TYPES.has((element as HTMLInputElement).type);
-    }
-    return !!element.closest('[contenteditable]:not([contenteditable="false"]), [role="textbox"], [role="searchbox"]');
-}
-
-/** Whether the target is inside a widget that reads bare keys itself (an open menu, a listbox, a tab list, ...). */
-export function isInWidget(target: EventTarget | null): boolean {
-    return !!elementOf(target)?.closest(WIDGET_SELECTOR);
-}
-
-/** Whether Enter/Space on the target already activates it (a button, a link, a menu item). */
-export function isActivatable(target: EventTarget | null): boolean {
-    return !!elementOf(target)?.closest(ACTIVATABLE_SELECTOR);
-}
-
-/** Whether the target is the trigger of a popup that is open right now (or the combobox that owns an open list). */
-export function isPopupOpenAt(target: EventTarget | null): boolean {
-    return !!elementOf(target)?.closest(OPEN_POPUP_TRIGGER);
-}
-
-/** Whether a modal dialog (`aria-modal="true"`: react-shared's `Modal` and `Drawer`, the unlock prompts, ...) is on screen. */
-export function isModalOpen(doc: Document): boolean {
-    return doc.querySelector('[aria-modal="true"]') !== null;
-}
-
-/** Whether the target is inside a popover that is a dialog of its own (the emoji and GIF pickers, the send-later picker): Escape is theirs, not a view's. A region that declares a shortcut scope (a compose window) is not one. */
-export function isInPopoverDialog(target: EventTarget | null): boolean {
-    return !!elementOf(target)?.closest('[role="dialog"]:not([data-shortcut-scope])');
-}
-
-/** The `data-shortcut-scope` of the region the target is in (a compose window), if any. */
-export function regionScopeOf(target: EventTarget | null): string | undefined {
-    return elementOf(target)?.closest("[data-shortcut-scope]")?.getAttribute("data-shortcut-scope") ?? undefined;
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/** `<input>` types that take no typed text, so a letter pressed on one is a shortcut, not input. (Radios and ranges use the arrows.) */
+const NON_TEXT_INPUT_TYPES = new Set(["button", "checkbox", "submit", "reset", "image", "file", "color"]);
+
+/** Roles whose members have keys of their own (arrows, Enter, Escape, type-ahead): a bare key pressed inside one belongs to the widget. */
+const WIDGET_SELECTOR = [
+    "menu",
+    "menubar",
+    "listbox",
+    "tablist",
+    "tree",
+    "grid",
+    "radiogroup",
+    "slider",
+    "spinbutton",
+    "combobox",
+]
+    .map((role) => `[role="${role}"]`)
+    .join(",");
+
+/** Elements Enter (and Space) already does something on. */
+const ACTIVATABLE_SELECTOR = 'a[href], button, summary, [role="button"], [role="link"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="tab"], [role="option"]';
+
+/** An open popup's trigger: Escape closes the popup, so it is not a shortcut then. */
+const OPEN_POPUP_TRIGGER = '[aria-haspopup][aria-expanded="true"], [role="combobox"][aria-expanded="true"]';
+
+function elementOf(target: EventTarget | null): Element | null {
+    return target instanceof Element ? target : null;
+}
+
+/** Whether the event target takes typed text: a text field, a select, a textarea, or anything contenteditable (the rich-text editor). */
+export function isTextEntry(target: EventTarget | null): boolean {
+    const element = elementOf(target);
+    if (!element) {
+        return false;
+    }
+    const tag = element.tagName;
+    if (tag === "TEXTAREA" || tag === "SELECT") {
+        return true;
+    }
+    if (tag === "INPUT") {
+        return !NON_TEXT_INPUT_TYPES.has((element as HTMLInputElement).type);
+    }
+    return !!element.closest('[contenteditable]:not([contenteditable="false"]), [role="textbox"], [role="searchbox"]');
+}
+
+/** Whether the target is inside a widget that reads bare keys itself (an open menu, a listbox, a tab list, ...). */
+export function isInWidget(target: EventTarget | null): boolean {
+    return !!elementOf(target)?.closest(WIDGET_SELECTOR);
+}
+
+/** Whether Enter/Space on the target already activates it (a button, a link, a menu item). */
+export function isActivatable(target: EventTarget | null): boolean {
+    return !!elementOf(target)?.closest(ACTIVATABLE_SELECTOR);
+}
+
+/** Whether the target is the trigger of a popup that is open right now (or the combobox that owns an open list). */
+export function isPopupOpenAt(target: EventTarget | null): boolean {
+    return !!elementOf(target)?.closest(OPEN_POPUP_TRIGGER);
+}
+
+/** Whether a modal dialog (`aria-modal="true"`: react-shared's `Modal` and `Drawer`, the unlock prompts, ...) is on screen. */
+export function isModalOpen(doc: Document): boolean {
+    return doc.querySelector('[aria-modal="true"]') !== null;
+}
+
+/** Whether the target is inside a popover that is a dialog of its own (the emoji and GIF pickers, the send-later picker): Escape is theirs, not a view's. A region that declares a shortcut scope (a compose window) is not one. */
+export function isInPopoverDialog(target: EventTarget | null): boolean {
+    return !!elementOf(target)?.closest('[role="dialog"]:not([data-shortcut-scope])');
+}
+
+/** The `data-shortcut-scope` of the region the target is in (a compose window), if any. */
+export function regionScopeOf(target: EventTarget | null): string | undefined {
+    return elementOf(target)?.closest("[data-shortcut-scope]")?.getAttribute("data-shortcut-scope") ?? undefined;
+}

package/apps/shared/mail/folderCounts.ts

@@ -96,6 +96,23 @@ export function inboxUnreadTotal(mailboxFolders: { folders: Folder[] }[], counts
     );
 }
 
+/**
+ * The folder types whose unread count is left out of a collapsed sidebar section's heading badge: Drafts and Outbox (their badges
+ * count messages held, not unread mail), and Sent Items, Deleted Items and Junk Email (an unread count there is noise, not mail
+ * to notice). It matches the folders `badgeFor()` shows no unread badge for; every other type - Inbox, Archive, the user's own
+ * folders - counts, so mail that a rule filed out of the Inbox is not overlooked in a hidden section. Change it here to change that.
+ */
+export const UNREAD_BADGE_EXCLUDED_FOLDER_TYPES: readonly FolderType[] = ["drafts", "outbox", "sent_items", "deleted_items", "junk"];
+
+/** The unread messages in the `folders` that carry an unread count (all but `UNREAD_BADGE_EXCLUDED_FOLDER_TYPES`) - what a collapsed
+ * sidebar section shows on its heading, so new mail in a hidden section is still noticed. */
+export function unreadBadgeTotal(folders: readonly Folder[], counts: Record<string, FolderCount>): number {
+    return folders.reduce(
+        (total, folder) => (UNREAD_BADGE_EXCLUDED_FOLDER_TYPES.includes(folder.type) ? total : total + countOfFolder(folder, counts).unread),
+        0,
+    );
+}
+
 /** How long after the last change of this page's own has finished a server-published count is trusted again: one published
  * about an earlier state of the folder could otherwise arrive late and put back what the change just took away. */
 export const COUNT_QUIET_MS = 1_500;

package/apps/shared/mail/folderOfType.ts

@@ -0,0 +1,49 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { Folder, createFolder, listFolders } from "@rapidmx/react-shared/mail/mailApi.js";
+
+/** The folders this page load has had to look up or make for a mailbox, so a second Report junk does not ask again. */
+const resolved = new Map<string, string>();
+
+/** Forgets every remembered folder - for the tests. */
+export function clearResolvedFolders(): void {
+    resolved.clear();
+}
+
+/**
+ * A mailbox's own folder of `type` (Junk Email, Deleted Items, Inbox) - the reading pane's counterpart of the mail page's bulk
+ * `resolveFolderOfType()`, so Report junk and Delete on one message go where the selection bar's go.
+ *
+ * Folders belong to a mailbox: only those of `mailboxUid` in `known` count (a message opened from a shared mailbox, or from a search
+ * over several, is filed in ITS mailbox's Junk, never the open one's). The server makes every well-known folder itself, so one the tree
+ * lacks is asked for - the tree may only be out of date - and used, never created twice; only a server that really has none is asked to
+ * make it. `onFound` is told about a folder the tree did not have, so the sidebar picks it up.
+ */
+export async function resolveFolderOfType(
+    mailboxUid: string,
+    type: Folder["type"],
+    name: string,
+    known: Folder[] = [],
+    onFound?: (folder: Folder) => void,
+): Promise<string> {
+    const inTree = known.find((folder) => folder.mailboxUid === mailboxUid && folder.type === type);
+    if (inTree) {
+        return inTree.uid;
+    }
+    const key = `${mailboxUid}:${type}`;
+    const remembered = resolved.get(key);
+    if (remembered) {
+        return remembered;
+    }
+    const listed = (await listFolders(mailboxUid)).find((folder) => folder.type === type);
+    if (listed) {
+        onFound?.(listed);
+        resolved.set(key, listed.uid);
+        return listed.uid;
+    }
+    const created = await createFolder({ mailboxUid, name, type });
+    resolved.set(key, created.uid);
+    return created.uid;
+}

package/apps/shared/mail/folderTree.ts

@@ -1,143 +1,143 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import type { Folder } from "@rapidmx/react-shared/mail/mailApi.js";
-import type { MailboxFolders } from "../components/mail/layout/MailShell.js";
-
-/**
- * The sidebar's order of a mailbox's well-known folders; anything else (`user`) follows, alphabetically. Also the order push channels are asked
- * for (`pushChannelsFor()`), so when the server's channel cap bites it is the folders lowest in this list that go without live updates.
- */
-export const FOLDER_ORDER = ["inbox", "drafts", "outbox", "sent_items", "deleted_items", "junk", "archive"];
-
-/**
- * A mailbox's `calendar`/`contacts`/`tasks`/`notes` folders back their own dedicated apps (see `CalendarShell`/`ContactsShell`/`TasksShell`), not
- * Mail - `listFolders()` returns every well-known folder for the mailbox regardless of which app owns it, so Mail's own folder tree filters down
- * to just the mail ones itself, or those other apps' folders leak into its sidebar.
- */
-export const MAIL_FOLDER_TYPES = new Set([...FOLDER_ORDER, "user"]);
-
-/** The well-known folders the server creates lazily around a first send: what the sidebar shows a placeholder for while a message is on its way. */
-export const SEND_FOLDER_TYPES = ["outbox", "sent_items"] as const;
-
-export function isMailFolder(folder: { type: string }): boolean {
-    return MAIL_FOLDER_TYPES.has(folder.type);
-}
-
-function sortKey(type: string): number {
-    const index = FOLDER_ORDER.indexOf(type);
-    return index === -1 ? FOLDER_ORDER.length : index;
-}
-
-/** Well-known folders in `FOLDER_ORDER`, then the rest by name. A new array; the input is left alone. */
-export function sortFolders(folders: Folder[]): Folder[] {
-    return [...folders].sort((a, b) => sortKey(a.type) - sortKey(b.type) || a.name.localeCompare(b.name));
-}
-
-/** What a sidebar row is: a folder that exists, or (`placeholder`) one that is expected to but has not arrived yet. */
-export type FolderRow = { kind: "folder"; folder: Folder } | { kind: "placeholder"; type: string };
-
-/**
- * The rows of one mailbox's sidebar section, in order: every folder that exists, and - while `sending` messages are on their way and the
- * server has not made the folder yet - a placeholder for each of the Outbox and Sent Items that is missing. The one place a folder that has not
- * arrived is drawn, so it can never appear twice: the moment the real folder is in `folders` its placeholder is not built.
- */
-export function folderRows(folders: Folder[], sending: number): FolderRow[] {
-    const rows: FolderRow[] = sortFolders(folders).map((folder) => ({ kind: "folder", folder }));
-    if (sending > 0) {
-        for (const type of SEND_FOLDER_TYPES) {
-            if (!folders.some((folder) => folder.type === type)) {
-                rows.push({ kind: "placeholder", type });
-            }
-        }
-        rows.sort((a, b) => sortKey(rowType(a)) - sortKey(rowType(b)));
-    }
-    return rows;
-}
-
-function rowType(row: FolderRow): string {
-    return row.kind === "folder" ? row.folder.type : row.type;
-}
-
-/** What a folder can be changed to by an event or a refetch: everything about it except the counts, which the counts overlay owns. */
-export type FolderChange = Partial<Pick<Folder, "name" | "type" | "parentFolderUid" | "color">> & { uid: string; mailboxUid?: string };
-
-const CHANGEABLE = ["name", "type", "parentFolderUid", "color"] as const;
-
-/**
- * Files `folder` in the tree: added under its mailbox when unknown (a type Mail does not list is ignored), else its name, type, parent and
- * colour brought up to date (a folder that became a type Mail does not list leaves the tree). Returns `entries` itself - the same array - when
- * nothing changed, because everything on screen that depends on the tree starts over when it is a new one.
- */
-export function upsertFolder(entries: MailboxFolders[], folder: Folder | FolderChange): MailboxFolders[] {
-    let changed = false;
-    const next = entries.map((entry) => {
-        const existing = entry.folders.find((f) => f.uid === folder.uid);
-        if (!existing) {
-            // Only a whole folder can be added: an update for one that is not known has nothing to add it with (the refetch it causes will).
-            if (entry.mailbox.uid !== folder.mailboxUid || !isFullFolder(folder) || !isMailFolder(folder)) {
-                return entry;
-            }
-            // A well-known folder is one per mailbox - the server treats the oldest as the real one - so a second of the same type (made by a client that did
-            // not know it existed) is not a second row: the older of the two is the one shown.
-            const sameType = folder.type === "user" ? undefined : entry.folders.find((f) => f.type === folder.type);
-            if (sameType) {
-                if (!isOlder(folder, sameType)) {
-                    return entry;
-                }
-                changed = true;
-                return { ...entry, folders: entry.folders.map((f) => (f === sameType ? folder : f)) };
-            }
-            changed = true;
-            return { ...entry, folders: [...entry.folders, folder] };
-        }
-        const patch: Partial<Folder> = {};
-        for (const key of CHANGEABLE) {
-            if (key in folder && folder[key] !== undefined && folder[key] !== existing[key]) {
-                (patch as Record<string, unknown>)[key] = folder[key];
-            }
-        }
-        if (Object.keys(patch).length === 0) {
-            return entry;
-        }
-        changed = true;
-        const updated = { ...existing, ...patch };
-        return { ...entry, folders: isMailFolder(updated) ? entry.folders.map((f) => (f === existing ? updated : f)) : entry.folders.filter((f) => f !== existing) };
-    });
-    return changed ? next : entries;
-}
-
-function isFullFolder(folder: Folder | FolderChange): folder is Folder {
-    return typeof folder.name === "string" && typeof folder.type === "string";
-}
-
-/** Whether `a` was created before `b`: only when both say when. */
-function isOlder(a: Folder, b: Folder): boolean {
-    // (A folder from the network may lack the date: `Date.parse(undefined)` is NaN, which is "cannot tell".)
-    const first = Date.parse(a.dateCreated);
-    const second = Date.parse(b.dateCreated);
-    return Number.isFinite(first) && Number.isFinite(second) && first < second;
-}
-
-/** Takes a deleted folder out of the tree. The same array when it was not in it. */
-export function removeFolder(entries: MailboxFolders[], folderUid: string): MailboxFolders[] {
-    if (!entries.some((entry) => entry.folders.some((folder) => folder.uid === folderUid))) {
-        return entries;
-    }
-    return entries.map((entry) => (entry.folders.some((folder) => folder.uid === folderUid) ? { ...entry, folders: entry.folders.filter((folder) => folder.uid !== folderUid) } : entry));
-}
-
-/**
- * Brings one mailbox's part of the tree up to date with a listing the server just gave (`listFolders()`): folders it has that the tree lacks
- * are added, changed names and types are taken. Nothing is removed - a listing that began before a folder was created here would take it out
- * again, and deletions arrive as events - and the counts are not touched (see `useFolderCounts()`). The same array when there is nothing to do.
- */
-export function reconcileFolders(entries: MailboxFolders[], listed: Folder[]): MailboxFolders[] {
-    return listed.reduce((tree, folder) => upsertFolder(tree, folder), entries);
-}
-
-/** Every folder uid in the tree. */
-export function knownFolderUids(entries: MailboxFolders[]): Set<string> {
-    return new Set(entries.flatMap((entry) => entry.folders.map((folder) => folder.uid)));
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { Folder } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { MailboxFolders } from "../components/mail/layout/MailShell.js";
+
+/**
+ * The sidebar's order of a mailbox's well-known folders; anything else (`user`) follows, alphabetically. Also the order push channels are asked
+ * for (`pushChannelsFor()`), so when the server's channel cap bites it is the folders lowest in this list that go without live updates.
+ */
+export const FOLDER_ORDER = ["inbox", "drafts", "outbox", "sent_items", "deleted_items", "junk", "archive"];
+
+/**
+ * A mailbox's `calendar`/`contacts`/`tasks`/`notes` folders back their own dedicated apps (see `CalendarShell`/`ContactsShell`/`TasksShell`), not
+ * Mail - `listFolders()` returns every well-known folder for the mailbox regardless of which app owns it, so Mail's own folder tree filters down
+ * to just the mail ones itself, or those other apps' folders leak into its sidebar.
+ */
+export const MAIL_FOLDER_TYPES = new Set([...FOLDER_ORDER, "user"]);
+
+/** The well-known folders the server creates lazily around a first send: what the sidebar shows a placeholder for while a message is on its way. */
+export const SEND_FOLDER_TYPES = ["outbox", "sent_items"] as const;
+
+export function isMailFolder(folder: { type: string }): boolean {
+    return MAIL_FOLDER_TYPES.has(folder.type);
+}
+
+function sortKey(type: string): number {
+    const index = FOLDER_ORDER.indexOf(type);
+    return index === -1 ? FOLDER_ORDER.length : index;
+}
+
+/** Well-known folders in `FOLDER_ORDER`, then the rest by name. A new array; the input is left alone. */
+export function sortFolders(folders: Folder[]): Folder[] {
+    return [...folders].sort((a, b) => sortKey(a.type) - sortKey(b.type) || a.name.localeCompare(b.name));
+}
+
+/** What a sidebar row is: a folder that exists, or (`placeholder`) one that is expected to but has not arrived yet. */
+export type FolderRow = { kind: "folder"; folder: Folder } | { kind: "placeholder"; type: string };
+
+/**
+ * The rows of one mailbox's sidebar section, in order: every folder that exists, and - while `sending` messages are on their way and the
+ * server has not made the folder yet - a placeholder for each of the Outbox and Sent Items that is missing. The one place a folder that has not
+ * arrived is drawn, so it can never appear twice: the moment the real folder is in `folders` its placeholder is not built.
+ */
+export function folderRows(folders: Folder[], sending: number): FolderRow[] {
+    const rows: FolderRow[] = sortFolders(folders).map((folder) => ({ kind: "folder", folder }));
+    if (sending > 0) {
+        for (const type of SEND_FOLDER_TYPES) {
+            if (!folders.some((folder) => folder.type === type)) {
+                rows.push({ kind: "placeholder", type });
+            }
+        }
+        rows.sort((a, b) => sortKey(rowType(a)) - sortKey(rowType(b)));
+    }
+    return rows;
+}
+
+function rowType(row: FolderRow): string {
+    return row.kind === "folder" ? row.folder.type : row.type;
+}
+
+/** What a folder can be changed to by an event or a refetch: everything about it except the counts, which the counts overlay owns. */
+export type FolderChange = Partial<Pick<Folder, "name" | "type" | "parentFolderUid" | "color">> & { uid: string; mailboxUid?: string };
+
+const CHANGEABLE = ["name", "type", "parentFolderUid", "color"] as const;
+
+/**
+ * Files `folder` in the tree: added under its mailbox when unknown (a type Mail does not list is ignored), else its name, type, parent and
+ * colour brought up to date (a folder that became a type Mail does not list leaves the tree). Returns `entries` itself - the same array - when
+ * nothing changed, because everything on screen that depends on the tree starts over when it is a new one.
+ */
+export function upsertFolder(entries: MailboxFolders[], folder: Folder | FolderChange): MailboxFolders[] {
+    let changed = false;
+    const next = entries.map((entry) => {
+        const existing = entry.folders.find((f) => f.uid === folder.uid);
+        if (!existing) {
+            // Only a whole folder can be added: an update for one that is not known has nothing to add it with (the refetch it causes will).
+            if (entry.mailbox.uid !== folder.mailboxUid || !isFullFolder(folder) || !isMailFolder(folder)) {
+                return entry;
+            }
+            // A well-known folder is one per mailbox - the server treats the oldest as the real one - so a second of the same type (made by a client that did
+            // not know it existed) is not a second row: the older of the two is the one shown.
+            const sameType = folder.type === "user" ? undefined : entry.folders.find((f) => f.type === folder.type);
+            if (sameType) {
+                if (!isOlder(folder, sameType)) {
+                    return entry;
+                }
+                changed = true;
+                return { ...entry, folders: entry.folders.map((f) => (f === sameType ? folder : f)) };
+            }
+            changed = true;
+            return { ...entry, folders: [...entry.folders, folder] };
+        }
+        const patch: Partial<Folder> = {};
+        for (const key of CHANGEABLE) {
+            if (key in folder && folder[key] !== undefined && folder[key] !== existing[key]) {
+                (patch as Record<string, unknown>)[key] = folder[key];
+            }
+        }
+        if (Object.keys(patch).length === 0) {
+            return entry;
+        }
+        changed = true;
+        const updated = { ...existing, ...patch };
+        return { ...entry, folders: isMailFolder(updated) ? entry.folders.map((f) => (f === existing ? updated : f)) : entry.folders.filter((f) => f !== existing) };
+    });
+    return changed ? next : entries;
+}
+
+function isFullFolder(folder: Folder | FolderChange): folder is Folder {
+    return typeof folder.name === "string" && typeof folder.type === "string";
+}
+
+/** Whether `a` was created before `b`: only when both say when. */
+function isOlder(a: Folder, b: Folder): boolean {
+    // (A folder from the network may lack the date: `Date.parse(undefined)` is NaN, which is "cannot tell".)
+    const first = Date.parse(a.dateCreated);
+    const second = Date.parse(b.dateCreated);
+    return Number.isFinite(first) && Number.isFinite(second) && first < second;
+}
+
+/** Takes a deleted folder out of the tree. The same array when it was not in it. */
+export function removeFolder(entries: MailboxFolders[], folderUid: string): MailboxFolders[] {
+    if (!entries.some((entry) => entry.folders.some((folder) => folder.uid === folderUid))) {
+        return entries;
+    }
+    return entries.map((entry) => (entry.folders.some((folder) => folder.uid === folderUid) ? { ...entry, folders: entry.folders.filter((folder) => folder.uid !== folderUid) } : entry));
+}
+
+/**
+ * Brings one mailbox's part of the tree up to date with a listing the server just gave (`listFolders()`): folders it has that the tree lacks
+ * are added, changed names and types are taken. Nothing is removed - a listing that began before a folder was created here would take it out
+ * again, and deletions arrive as events - and the counts are not touched (see `useFolderCounts()`). The same array when there is nothing to do.
+ */
+export function reconcileFolders(entries: MailboxFolders[], listed: Folder[]): MailboxFolders[] {
+    return listed.reduce((tree, folder) => upsertFolder(tree, folder), entries);
+}
+
+/** Every folder uid in the tree. */
+export function knownFolderUids(entries: MailboxFolders[]): Set<string> {
+    return new Set(entries.flatMap((entry) => entry.folders.map((folder) => folder.uid)));
+}

package/apps/shared/mail/listAllPages.ts

@@ -1,39 +1,39 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-
-/** Page size the list pages (Contacts, Tasks) request per call - restapi caps `limit` at 500. */
-export const LIST_PAGE_SIZE = 500;
-
-/** Safety cap on pages fetched - stops a server that ignores `page` (and keeps returning a full first
- * page) from looping forever. 40 pages x 500 = 20,000 items. */
-export const MAX_LIST_PAGES = 40;
-
-export interface ListAllPagesResult<T> {
-    items: T[];
-    /** `true` when fetching stopped at `maxPages` with the last page still full - there may be more items
-     * the caller isn't showing, so it should say so rather than presenting `items` as the whole list. */
-    truncated: boolean;
-}
-
-/**
- * Fetches every page of a zero-based `limit`/`page` list endpoint, stopping at the first short page
- * (fewer than `pageSize` items) - so a folder with more items than one page holds is shown in full
- * rather than silently cut off at the first page. Stops at `maxPages` regardless, reporting `truncated`.
- */
-export async function listAllPages<T>(
-    fetchPage: (page: number) => Promise<T[]>,
-    pageSize: number = LIST_PAGE_SIZE,
-    maxPages: number = MAX_LIST_PAGES,
-): Promise<ListAllPagesResult<T>> {
-    const items: T[] = [];
-    for (let page = 0; page < maxPages; page++) {
-        const batch = await fetchPage(page);
-        items.push(...batch);
-        if (batch.length < pageSize) {
-            return { items, truncated: false };
-        }
-    }
-    return { items, truncated: true };
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/** Page size the list pages (Contacts, Tasks) request per call - restapi caps `limit` at 500. */
+export const LIST_PAGE_SIZE = 500;
+
+/** Safety cap on pages fetched - stops a server that ignores `page` (and keeps returning a full first
+ * page) from looping forever. 40 pages x 500 = 20,000 items. */
+export const MAX_LIST_PAGES = 40;
+
+export interface ListAllPagesResult<T> {
+    items: T[];
+    /** `true` when fetching stopped at `maxPages` with the last page still full - there may be more items
+     * the caller isn't showing, so it should say so rather than presenting `items` as the whole list. */
+    truncated: boolean;
+}
+
+/**
+ * Fetches every page of a zero-based `limit`/`page` list endpoint, stopping at the first short page
+ * (fewer than `pageSize` items) - so a folder with more items than one page holds is shown in full
+ * rather than silently cut off at the first page. Stops at `maxPages` regardless, reporting `truncated`.
+ */
+export async function listAllPages<T>(
+    fetchPage: (page: number) => Promise<T[]>,
+    pageSize: number = LIST_PAGE_SIZE,
+    maxPages: number = MAX_LIST_PAGES,
+): Promise<ListAllPagesResult<T>> {
+    const items: T[] = [];
+    for (let page = 0; page < maxPages; page++) {
+        const batch = await fetchPage(page);
+        items.push(...batch);
+        if (batch.length < pageSize) {
+            return { items, truncated: false };
+        }
+    }
+    return { items, truncated: true };
+}