@rapidmx/web-client 0.9.0 → 0.11.0

package/dist/apps/shared/keyboard/registry.js

@@ -0,0 +1,33 @@
+/**
+ * The shortcuts that are mounted right now. Components add and remove their claims as they mount and unmount, so a page switch changes
+ * what a key does with nothing to re-wire; the dispatcher (`dispatchKeyEvent()`) looks handlers up here at the time of the key press,
+ * and the help dialog lists what is here.
+ */
+export class ShortcutRegistry {
+    constructor() {
+        this.registrations = [];
+        this.counter = 0;
+        this.listeners = new Set();
+        /** The current claims, oldest first. A new array whenever they change (so it can be a `useSyncExternalStore()` snapshot). */
+        this.getSnapshot = () => this.registrations;
+        this.subscribe = (listener) => {
+            this.listeners.add(listener);
+            return () => {
+                this.listeners.delete(listener);
+            };
+        };
+    }
+    /** Adds a claim; returns what removes it. */
+    add(claim) {
+        const registration = { ...claim, id: ++this.counter, order: this.counter };
+        this.registrations = [...this.registrations, registration];
+        this.publish();
+        return () => {
+            this.registrations = this.registrations.filter((existing) => existing.id !== registration.id);
+            this.publish();
+        };
+    }
+    publish() {
+        this.listeners.forEach((listener) => listener());
+    }
+}

package/dist/apps/shared/keyboard/targets.d.ts

@@ -0,0 +1,14 @@
+/** Whether the event target takes typed text: a text field, a select, a textarea, or anything contenteditable (the rich-text editor). */
+export declare function isTextEntry(target: EventTarget | null): boolean;
+/** Whether the target is inside a widget that reads bare keys itself (an open menu, a listbox, a tab list, ...). */
+export declare function isInWidget(target: EventTarget | null): boolean;
+/** Whether Enter/Space on the target already activates it (a button, a link, a menu item). */
+export declare function isActivatable(target: EventTarget | null): boolean;
+/** Whether the target is the trigger of a popup that is open right now (or the combobox that owns an open list). */
+export declare function isPopupOpenAt(target: EventTarget | null): boolean;
+/** Whether a modal dialog (`aria-modal="true"`: react-shared's `Modal` and `Drawer`, the unlock prompts, ...) is on screen. */
+export declare function isModalOpen(doc: Document): boolean;
+/** 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 declare function isInPopoverDialog(target: EventTarget | null): boolean;
+/** The `data-shortcut-scope` of the region the target is in (a compose window), if any. */
+export declare function regionScopeOf(target: EventTarget | null): string | undefined;

package/dist/apps/shared/keyboard/targets.js

@@ -0,0 +1,67 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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) {
+    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) {
+    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.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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    return elementOf(target)?.closest("[data-shortcut-scope]")?.getAttribute("data-shortcut-scope") ?? undefined;
+}

package/dist/apps/shared/keyboard/useShortcut.d.ts

@@ -0,0 +1,19 @@
+import { RefObject } from "react";
+import type { ShortcutDef, ShortcutScope } from "./keymap.js";
+import type { ShortcutHandler } from "./registry.js";
+export interface UseShortcutOptions {
+    /** Overrides the scope the shortcut is defined with - required for a bare spec string, which has none. Default `global`. */
+    scope?: ShortcutScope;
+    /** Registers only while true: a view offers a shortcut only when it can really do the thing. Default true. */
+    enabled?: boolean;
+    /** Restricts it to events whose target is inside this element (a compose window). */
+    container?: RefObject<Element | null>;
+}
+/**
+ * Claims a shortcut for as long as the calling component is mounted (and `enabled`). `shortcut` is an entry of `SHORTCUTS` - which is what
+ * the help dialog and tooltips describe - or a bare spec such as `"alt+n"` for a one-off. The handler is read at the time of the key press,
+ * so it always sees the component's current state without the registration being redone; return `false` from it to decline the key.
+ *
+ * Does nothing outside a `ShortcutProvider`.
+ */
+export declare function useShortcut(shortcut: ShortcutDef | string, handler: ShortcutHandler, options?: UseShortcutOptions): void;

package/dist/apps/shared/keyboard/useShortcut.js

@@ -0,0 +1,35 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useMemo, useRef } from "react";
+import { parseSpec } from "./parse.js";
+import { useShortcutRegistry } from "./ShortcutProvider.js";
+/**
+ * Claims a shortcut for as long as the calling component is mounted (and `enabled`). `shortcut` is an entry of `SHORTCUTS` - which is what
+ * the help dialog and tooltips describe - or a bare spec such as `"alt+n"` for a one-off. The handler is read at the time of the key press,
+ * so it always sees the component's current state without the registration being redone; return `false` from it to decline the key.
+ *
+ * Does nothing outside a `ShortcutProvider`.
+ */
+export function useShortcut(shortcut, handler, options = {}) {
+    const { scope, enabled = true, container } = options;
+    const registry = useShortcutRegistry();
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    const def = useMemo(() => (typeof shortcut === "string" ? { id: `custom:${shortcut}`, keys: [shortcut], label: shortcut, scope: "global" } : shortcut), [shortcut]);
+    const resolvedScope = scope ?? def.scope;
+    useEffect(() => {
+        if (!registry || !enabled) {
+            return;
+        }
+        return registry.add({
+            shortcut: def,
+            scope: resolvedScope,
+            run: (event) => handlerRef.current(event),
+            container,
+            keys: def.keys.map(parseSpec),
+            electronKeys: (def.electronKeys ?? []).map(parseSpec),
+        });
+    }, [registry, enabled, def, resolvedScope, container]);
+}

package/dist/apps/shared/keyboard/useShortcutProps.d.ts

@@ -0,0 +1,10 @@
+import type { ShortcutDef } from "./keymap.js";
+/**
+ * What a control that a keyboard shortcut also triggers gets: a tooltip naming the key - `Reply (Ctrl+R)`, in this platform's own key names -
+ * and `aria-keyshortcuts` for assistive technology. The accessible name is left alone (the control keeps its own label), so a tooltip suffix never
+ * changes what a screen reader or a test finds it by. With `active` false - the shortcut isn't registered right now - it is just the plain label.
+ */
+export declare function useShortcutProps(label: string, shortcut: ShortcutDef, active?: boolean): {
+    title: string;
+    "aria-keyshortcuts"?: string;
+};

package/dist/apps/shared/keyboard/useShortcutProps.js

@@ -0,0 +1,15 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ariaKeyShortcuts, withHint } from "./format.js";
+import { useKeyEnvironment } from "./ShortcutProvider.js";
+/**
+ * What a control that a keyboard shortcut also triggers gets: a tooltip naming the key - `Reply (Ctrl+R)`, in this platform's own key names -
+ * and `aria-keyshortcuts` for assistive technology. The accessible name is left alone (the control keeps its own label), so a tooltip suffix never
+ * changes what a screen reader or a test finds it by. With `active` false - the shortcut isn't registered right now - it is just the plain label.
+ */
+export function useShortcutProps(label, shortcut, active = true) {
+    const env = useKeyEnvironment();
+    return active ? { title: withHint(label, shortcut, env), "aria-keyshortcuts": ariaKeyShortcuts(shortcut, env) } : { title: label };
+}

package/dist/apps/shared/mail/folderCounts.d.ts

@@ -0,0 +1,78 @@
+import { Folder, FolderType, Mailbox, Message } from "@rapidmx/react-shared/mail/mailApi.js";
+/**
+ * The folder badges' numbers, kept right without a reload.
+ *
+ * A folder's `unreadCount`/`totalCount` come from the server (`GET /mail/folders`, the server-published `Folder` update
+ * event, and the poll), but waiting for a round trip to see a badge move after reading a message feels broken, so a change
+ * made here is applied to the badge at once - **optimistically** - and then *reconciled*: every so often, and after every
+ * change, the real counts are read back and replace whatever this page worked out. So the page can be wrong for a moment,
+ * never for good.
+ *
+ * What the server sends (`@rapidmx/restapi`): `GET /mail/folders` returns each folder with a derived `unreadCount`/`totalCount`
+ * (unread messages, all messages), and after any change to a folder's messages it publishes
+ * `{ type: /^Folder/, action: "update", data: { uid, mailboxUid, unreadCount, totalCount } }` on the folder's push channel *and* its
+ * mailbox's, so each is heard twice - the values are absolute and applying one again changes nothing. Nothing here fails without
+ * that event, or for a write that publishes none (ActiveSync/MAPI, erasure jobs): the read-back after each change and the poll do
+ * the same job a little later, and overlapping writes to one folder are unordered, so they always have the last word.
+ */
+export interface FolderCount {
+    unread: number;
+    total: number;
+}
+/** A change to one folder's counts. */
+export interface CountDelta {
+    folderUid: string;
+    unread: number;
+    total: number;
+}
+/** What one message change - a new message (`previous` absent), a deletion (`next` absent), a read/unread flip, a move - does to the folders' counts. */
+export declare function countDeltas(previous: Message | null | undefined, next: Message | null | undefined): CountDelta[];
+/** A folder's count as it should be shown: what this page last worked out or was told, else what the folder was listed with. */
+export declare function countOfFolder(folder: Folder, counts: Record<string, FolderCount>): FolderCount;
+/** What a folder's badge shows: how many unread, or (Drafts and Outbox, Outlook-style) how many messages are in it. */
+export interface FolderBadge {
+    kind: "unread" | "total";
+    value: number;
+}
+/**
+ * The badge a folder gets, if any. Inbox, Archive and the user's own folders show their unread count when it is above
+ * zero; Drafts and Outbox show how many messages they hold (an unread count means nothing there); Sent Items, Deleted
+ * Items and Junk Email show nothing.
+ */
+export declare function badgeFor(type: FolderType, count: FolderCount): FolderBadge | undefined;
+/** The badge's text for assistive technology: "3 unread", "2 messages". */
+export declare function badgeLabel(badge: FolderBadge): string;
+/** The unread messages in every mailbox's Inbox - what the tab title counts. */
+export declare function inboxUnreadTotal(mailboxFolders: {
+    folders: Folder[];
+}[], counts: Record<string, FolderCount>): number;
+/** 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 declare const COUNT_QUIET_MS = 1500;
+/** How long after a change the counts are read back from the server. */
+export declare const COUNT_REFRESH_DELAY_MS = 600;
+/** An optimistic change in flight: call exactly one of these once the server has answered. */
+export interface CountTracker {
+    /** The server accepted the change: keep what was applied, and read the real counts back. */
+    settle(): void;
+    /** The server refused it (or it failed): put the counts back as they were, and read the real ones back. */
+    revert(): void;
+}
+export interface FolderCounts {
+    /** The counts this page has worked out or been told since load, by folder uid - see `countOfFolder()`. */
+    counts: Record<string, FolderCount>;
+    /** Applies the effect of changing `previous` into `next` now, before the server has answered - see `CountTracker`. */
+    track(previous: Message | null | undefined, next: Message | null | undefined): CountTracker;
+    /** A new message arrived over the push connection: counts it (once per message) until the real counts are read back.
+     * `false` when this one was already counted - a duplicate event. */
+    noteCreated(message: Message): boolean;
+    /** The server's `Folder` update event's `data`: the folder's real counts - when this page has nothing of its own in flight. */
+    applyFolderEvent(data: unknown): void;
+    /** Reads every mailbox's real counts back and shows them, after `delayMs` (at once for 0). A later call replaces one still waiting. */
+    refresh(delayMs?: number): void;
+}
+/**
+ * Holds the folder counts overlay for `MailShell`. `folders` is every folder the sidebar lists (the overlay starts from what
+ * each was loaded with); `mailboxes` is whose folders to read back. The overlay starts again whenever `mailboxes` does.
+ */
+export declare function useFolderCounts(mailboxes: Mailbox[], folders: Folder[], onFoldersListed?: (folders: Folder[]) => void): FolderCounts;

package/dist/apps/shared/mail/folderCounts.js

@@ -0,0 +1,218 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useCallback, useEffect, useRef, useState } from "react";
+import { listFolders } from "@rapidmx/react-shared/mail/mailApi.js";
+/** What one message change - a new message (`previous` absent), a deletion (`next` absent), a read/unread flip, a move - does to the folders' counts. */
+export function countDeltas(previous, next) {
+    const byFolder = new Map();
+    function add(message, sign) {
+        const entry = byFolder.get(message.folderUid) ?? { folderUid: message.folderUid, unread: 0, total: 0 };
+        entry.total += sign;
+        entry.unread += message.flags.read === true ? 0 : sign;
+        byFolder.set(message.folderUid, entry);
+    }
+    if (previous) {
+        add(previous, -1);
+    }
+    if (next) {
+        add(next, 1);
+    }
+    return [...byFolder.values()].filter((delta) => delta.unread !== 0 || delta.total !== 0);
+}
+/** A folder's count as it should be shown: what this page last worked out or was told, else what the folder was listed with. */
+export function countOfFolder(folder, counts) {
+    return counts[folder.uid] ?? { unread: folder.unreadCount, total: folder.totalCount };
+}
+/**
+ * The badge a folder gets, if any. Inbox, Archive and the user's own folders show their unread count when it is above
+ * zero; Drafts and Outbox show how many messages they hold (an unread count means nothing there); Sent Items, Deleted
+ * Items and Junk Email show nothing.
+ */
+export function badgeFor(type, count) {
+    switch (type) {
+        case "sent_items":
+        case "deleted_items":
+        case "junk":
+            return undefined;
+        case "drafts":
+        case "outbox":
+            return count.total > 0 ? { kind: "total", value: count.total } : undefined;
+        default:
+            return count.unread > 0 ? { kind: "unread", value: count.unread } : undefined;
+    }
+}
+/** The badge's text for assistive technology: "3 unread", "2 messages". */
+export function badgeLabel(badge) {
+    return badge.kind === "unread" ? `${badge.value} unread` : `${badge.value} ${badge.value === 1 ? "message" : "messages"}`;
+}
+/** The unread messages in every mailbox's Inbox - what the tab title counts. */
+export function inboxUnreadTotal(mailboxFolders, counts) {
+    return mailboxFolders.reduce((total, entry) => total + entry.folders.filter((folder) => folder.type === "inbox").reduce((sum, folder) => sum + countOfFolder(folder, counts).unread, 0), 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 = 1500;
+/** How long after a change the counts are read back from the server. */
+export const COUNT_REFRESH_DELAY_MS = 600;
+/** How many message uids the "already counted this new message" memory holds. */
+const SEEN_LIMIT = 500;
+/**
+ * Holds the folder counts overlay for `MailShell`. `folders` is every folder the sidebar lists (the overlay starts from what
+ * each was loaded with); `mailboxes` is whose folders to read back. The overlay starts again whenever `mailboxes` does.
+ */
+export function useFolderCounts(mailboxes, folders, onFoldersListed) {
+    const [counts, setCounts] = useState({});
+    const latestRef = useRef({ mailboxes, folders, onFoldersListed });
+    latestRef.current = { mailboxes, folders, onFoldersListed };
+    // Bumped by every change of the overlay this page makes, so a read that started before one can tell it is out of date.
+    const changesRef = useRef(0);
+    const inFlightRef = useRef(0);
+    const lastDoneRef = useRef(0);
+    const runRef = useRef(0);
+    // Assigned during every render, before anything can call it.
+    const readBackRef = useRef(undefined);
+    const timerRef = useRef(undefined);
+    const stoppedRef = useRef(false);
+    const seenRef = useRef(new Set());
+    const adjust = useCallback((deltas) => {
+        const known = deltas.filter((delta) => latestRef.current.folders.some((folder) => folder.uid === delta.folderUid));
+        if (known.length === 0) {
+            return;
+        }
+        changesRef.current++;
+        setCounts((previous) => {
+            const next = { ...previous };
+            for (const delta of known) {
+                const folder = latestRef.current.folders.find((f) => f.uid === delta.folderUid);
+                const base = next[delta.folderUid] ?? { unread: folder.unreadCount, total: folder.totalCount };
+                next[delta.folderUid] = {
+                    unread: Math.max(0, base.unread + delta.unread),
+                    total: Math.max(0, base.total + delta.total),
+                };
+            }
+            return next;
+        });
+    }, []);
+    const refresh = useCallback((delayMs = COUNT_REFRESH_DELAY_MS) => {
+        if (stoppedRef.current) {
+            return;
+        }
+        clearTimeout(timerRef.current);
+        if (delayMs <= 0) {
+            timerRef.current = undefined;
+            void readBackRef.current();
+            return;
+        }
+        timerRef.current = setTimeout(() => void readBackRef.current(), delayMs);
+    }, []);
+    // Re-assigned on every render so it reads the latest mailboxes; `refresh` (stable) calls whichever is current.
+    readBackRef.current = async () => {
+        timerRef.current = undefined;
+        const run = ++runRef.current;
+        const startedAt = changesRef.current;
+        const results = await Promise.all(latestRef.current.mailboxes.map((mailbox) => listFolders(mailbox.uid).catch(() => undefined)));
+        if (stoppedRef.current || run !== runRef.current) {
+            return;
+        }
+        // Whatever the counts' fate below, these are the mailboxes' folders as they are: a folder the sidebar does not have yet is filed now.
+        for (const list of results) {
+            if (list) {
+                latestRef.current.onFoldersListed?.(list);
+            }
+        }
+        if (inFlightRef.current > 0 || changesRef.current !== startedAt) {
+            // A change of this page's own began or ended while that was being read, so it may predate it: read again.
+            refresh();
+            return;
+        }
+        const fresh = {};
+        for (const list of results) {
+            for (const folder of list ?? []) {
+                fresh[folder.uid] = { unread: folder.unreadCount, total: folder.totalCount };
+            }
+        }
+        setCounts((previous) => {
+            const changed = Object.entries(fresh).some(([uid, count]) => previous[uid]?.unread !== count.unread || previous[uid]?.total !== count.total);
+            return changed ? { ...previous, ...fresh } : previous;
+        });
+    };
+    const track = useCallback((previous, next) => {
+        const deltas = countDeltas(previous, next);
+        inFlightRef.current++;
+        adjust(deltas);
+        let finished = false;
+        /** Whether this call was the one that ended it (a tracker ends once). */
+        function finish() {
+            if (finished) {
+                return false;
+            }
+            finished = true;
+            inFlightRef.current--;
+            lastDoneRef.current = Date.now();
+            changesRef.current++;
+            return true;
+        }
+        return {
+            settle() {
+                if (finish()) {
+                    refresh();
+                }
+            },
+            revert() {
+                if (finish()) {
+                    adjust(deltas.map((delta) => ({ folderUid: delta.folderUid, unread: -delta.unread, total: -delta.total })));
+                    refresh();
+                }
+            },
+        };
+    }, [adjust, refresh]);
+    const noteCreated = useCallback((message) => {
+        const seen = seenRef.current;
+        if (seen.has(message.uid)) {
+            return false;
+        }
+        seen.add(message.uid);
+        if (seen.size > SEEN_LIMIT) {
+            seen.delete(seen.values().next().value);
+        }
+        adjust(countDeltas(null, message));
+        refresh();
+        return true;
+    }, [adjust, refresh]);
+    const applyFolderEvent = useCallback((data) => {
+        const event = data;
+        const uid = event?.uid;
+        const folder = typeof uid === "string" ? latestRef.current.folders.find((f) => f.uid === uid) : undefined;
+        if (!folder) {
+            return;
+        }
+        if (inFlightRef.current > 0 || Date.now() - lastDoneRef.current < COUNT_QUIET_MS) {
+            // Its number may be about a state older than this page's own change: let a fresh read settle it.
+            refresh();
+            return;
+        }
+        const valid = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0;
+        setCounts((previous) => {
+            const current = previous[folder.uid] ?? { unread: folder.unreadCount, total: folder.totalCount };
+            const unread = valid(event.unreadCount) ? event.unreadCount : current.unread;
+            const total = valid(event.totalCount) ? event.totalCount : current.total;
+            return unread === current.unread && total === current.total && previous[folder.uid] ? previous : { ...previous, [folder.uid]: { unread, total } };
+        });
+    }, [refresh]);
+    // A fresh load of the mailboxes is a fresh start: the folders come with counts of their own. (Keyed on the uids, not the array.)
+    const mailboxKey = mailboxes.map((mailbox) => mailbox.uid).join("|");
+    useEffect(() => {
+        changesRef.current++;
+        setCounts((previous) => (Object.keys(previous).length > 0 ? {} : previous));
+    }, [mailboxKey]);
+    useEffect(() => {
+        stoppedRef.current = false;
+        return () => {
+            stoppedRef.current = true;
+            clearTimeout(timerRef.current);
+        };
+    }, []);
+    return { counts, track, noteCreated, applyFolderEvent, refresh };
+}

package/dist/apps/shared/mail/folderTree.d.ts

@@ -0,0 +1,55 @@
+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 declare const FOLDER_ORDER: string[];
+/**
+ * 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 declare const MAIL_FOLDER_TYPES: Set<string>;
+/** 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 declare const SEND_FOLDER_TYPES: readonly ["outbox", "sent_items"];
+export declare function isMailFolder(folder: {
+    type: string;
+}): boolean;
+/** Well-known folders in `FOLDER_ORDER`, then the rest by name. A new array; the input is left alone. */
+export declare function sortFolders(folders: Folder[]): Folder[];
+/** 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 declare function folderRows(folders: Folder[], sending: number): FolderRow[];
+/** 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;
+};
+/**
+ * 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 declare function upsertFolder(entries: MailboxFolders[], folder: Folder | FolderChange): MailboxFolders[];
+/** Takes a deleted folder out of the tree. The same array when it was not in it. */
+export declare function removeFolder(entries: MailboxFolders[], folderUid: string): MailboxFolders[];
+/**
+ * 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 declare function reconcileFolders(entries: MailboxFolders[], listed: Folder[]): MailboxFolders[];
+/** Every folder uid in the tree. */
+export declare function knownFolderUids(entries: MailboxFolders[]): Set<string>;