@rapidmx/web-client 0.5.0 → 0.7.0

package/dist/apps/shared/components/mail/ConversationThreadPane.js

@@ -3,56 +3,145 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
-import { getMessage, listAttachments, setMessageRead } from "@rapidmx/react-shared/mail/mailApi.js";
-import MessageDetailPane from "./MessageDetailPane.js";
+import { listAttachments, setMessageRead } from "@rapidmx/react-shared/mail/mailApi.js";
+import { listConversationMessages } from "@rapidmx/react-shared/mail/conversationsApi.js";
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import MessageDetailPane from "./MessageDetailPane.js";
+/** One request's worth of the thread. The server's own default for `listConversationMessages()`. */
+export const THREAD_PAGE_SIZE = 100;
+/**
+ * How many of a conversation's messages this pane will load. The server reads at most
+ * `CONVERSATION_SCAN_LIMIT` (500) messages when it groups conversations, so a `ConversationSummary` never
+ * describes more than this many anyway; the cap is here so a thread that somehow reports more can't turn
+ * into an unbounded run of requests. Past it the pane says so and the rest stay readable from the list.
+ */
+export const THREAD_MESSAGE_LIMIT = 500;
 /**
- * The merged, Gmail-style reading pane for "By conversation" mode — every message in the conversation
- * fetched and stacked oldest-to-newest, all but the most recent collapsed to a one-line summary
- * (sender + subject) until clicked. Reuses `MessageDetailPane` for each *expanded* message's own
- * header/attachments/body-iframe rendering rather than re-implementing it; a collapsed row is its own
- * lightweight summary, since mounting a full `MessageDetailPane` (and its iframe) for every message in
- * a long thread up front would be wasteful.
+ * Every message from `selectedUid` through to the newest - the run the reader is reading. Anything older
+ * stays collapsed to its one-line summary. Selecting the newest message therefore expands just that one.
+ *
+ * The pane lists newest first (see `loadThread()`), so that run is the opened message together with
+ * everything *above* it, and the opened message is the set's **last** entry rather than its first.
  */
-export default function ConversationThreadPane({ conversation, folders, labels }) {
-    const [messages, setMessages] = useState({});
+function expandedFrom(messages, selectedUid) {
+    const index = messages.findIndex((message) => message.uid === selectedUid);
+    // `messages` is never empty here (the callers below check), so -1 means "not in this thread" and the
+    // newest message - the first entry - is the anchor, exactly as a parent row's own click means.
+    const anchor = index === -1 ? 0 : index;
+    return new Set(messages.slice(0, anchor + 1).map((message) => message.uid));
+}
+/**
+ * The element a message of this thread actually scrolls inside. The pane is not itself the scroll
+ * container in the mail shell - `MailShell`'s own `<main>` is - so an adjustment has to be applied where
+ * the scrolling really happens, which is whichever ancestor is both scrollable and overflowing.
+ */
+function scrollingAncestor(node) {
+    for (let el = node.parentElement; el; el = el.parentElement) {
+        const overflowY = getComputedStyle(el).overflowY;
+        if ((overflowY === "auto" || overflowY === "scroll") && el.scrollHeight > el.clientHeight) {
+            return el;
+        }
+    }
+    // Nothing between the row and the root scrolls, so the page itself does - which in standards mode is
+    // `documentElement`, the same element `document.scrollingElement` names there.
+    return document.documentElement;
+}
+/**
+ * The thread's messages, **newest first**, in pages of `THREAD_PAGE_SIZE` up to `THREAD_MESSAGE_LIMIT`.
+ *
+ * `listConversationMessages()` pages oldest first and has no order of its own to ask for, so the pages are
+ * collected in that order - which is also the order the `THREAD_MESSAGE_LIMIT` cap has to apply in, since it
+ * is the oldest messages that are dropped when a thread is too long to load - and reversed once at the end.
+ * The pane reads newest first always, whatever the *list* is sorted by: it is the reading order for mail,
+ * and it means the message a conversation row stands for is the entry at the top.
+ */
+async function loadThread(mailboxUid, conversationId) {
+    const messages = [];
+    let more = true;
+    while (more && messages.length < THREAD_MESSAGE_LIMIT) {
+        const page = await listConversationMessages(mailboxUid, conversationId, {
+            page: messages.length / THREAD_PAGE_SIZE,
+            limit: THREAD_PAGE_SIZE,
+        });
+        messages.push(...page);
+        // A short page is the last one; a full page means asking for another.
+        more = page.length === THREAD_PAGE_SIZE;
+    }
+    messages.reverse();
+    return { messages, truncated: more };
+}
+/**
+ * The reading pane for the conversation list: the whole thread, **newest at the top**, opened at the message
+ * the reader picked. Every message from that one through to the newest is expanded - which in this order is
+ * the opened message and the entries above it - and the older ones, below it, are collapsed to a one-line
+ * summary (sender, date, preview) that expands on click or Enter. So opening the newest message shows just
+ * the top entry expanded, and opening 5 of 10 expands 10 down to 5.
+ *
+ * Newest first regardless of how the *list* is sorted: the list's own order arranges rows to pick from,
+ * while this is one conversation being read, and the entry a conversation row stands for - its latest
+ * message - is the one that should be at the top of the pane every time it is opened.
+ *
+ * Each *expanded* message is a `MessageDetailPane` of its own rather than a reimplementation of it, so the
+ * signature and verification badges, the verification-seal and decryption behaviour, the labels chips and
+ * menu, the attachments and Reply/Reply All/Forward/Archive all behave exactly as they do in the
+ * single-message pane, and each acts on the message it belongs to. A collapsed message mounts none of
+ * that - mounting a body iframe per message up front would be wasteful in a long thread.
+ */
+export default function ConversationThreadPane({ conversation, mailboxUid, selectedUid, folders, labels, onMessagePatched, onMessageRemoved, onLabelCreated, onFolderCreated, }) {
+    const [messages, setMessages] = useState([]);
     const [attachmentsByUid, setAttachmentsByUid] = useState({});
     const [expandedUids, setExpandedUids] = useState(new Set());
+    const [truncated, setTruncated] = useState(false);
     const [loading, setLoading] = useState(false);
     const [error, setError] = useState(null);
-    // Bumped on every conversation switch - any in-flight load/attachments/mark-read response carrying an
+    /** The message to scroll to and focus once it has rendered, or `null` once that has happened. */
+    const [pendingFocusUid, setPendingFocusUid] = useState(null);
+    // Bumped on every conversation switch - an in-flight load/attachments/mark-read response carrying an
     // older generation belongs to a superseded conversation and is dropped rather than applied.
     const generationRef = useRef(0);
-    // Message uids a mark-read / attachments request has already been issued for in the current
-    // generation, so re-running the effect below (every `messages`/`expandedUids` change) while one is
-    // still in flight never fires a duplicate - which for mark-read would also carry a stale `version`.
     const markReadRequestedRef = useRef(new Set());
     const attachmentsRequestedRef = useRef(new Set());
+    /** The `conversationId:selectedUid` the expansion run below has already been applied for, so patching
+     * a message (which changes `messages`) doesn't re-expand what the reader has since collapsed. */
+    const appliedSelectionRef = useRef(null);
+    /** Which conversation the messages currently in state belong to. A render with a new conversation and
+     * the previous one's messages still in state happens before the load effect has cleared them, and the
+     * expansion run below must sit that render out rather than anchor on a message from another thread. */
+    const loadedIdRef = useRef(null);
+    const rowRefs = useRef({});
+    const headerRefs = useRef({});
+    /** Where the toggled message's header sat in the viewport before it expanded, so the run below can put
+     * it back there - expanding a message above the one being read must not shove that one off-screen. */
+    const anchorRef = useRef(null);
+    const conversationId = conversation?.conversationId;
     useEffect(() => {
         const generation = ++generationRef.current;
         markReadRequestedRef.current = new Set();
         attachmentsRequestedRef.current = new Set();
-        setMessages({});
+        appliedSelectionRef.current = null;
+        loadedIdRef.current = null;
+        setMessages([]);
         setAttachmentsByUid({});
         setExpandedUids(new Set());
-        if (!conversation) {
+        setTruncated(false);
+        setError(null);
+        // The message the previous conversation was to be scrolled to went with it; leaving it set would
+        // point the run below at a row that is no longer rendered.
+        setPendingFocusUid(null);
+        if (!conversationId) {
             setLoading(false);
             return;
         }
         setLoading(true);
-        setError(null);
-        Promise.all(conversation.messageUids.map((uid) => getMessage(uid)))
+        loadThread(mailboxUid, conversationId)
             .then((loaded) => {
             if (generation !== generationRef.current)
                 return;
-            setMessages(Object.fromEntries(loaded.map((m) => [m.uid, m])));
-            // `messageUids` always has at least one entry — a `ConversationSummary` only ever
-            // exists because it was grouped from real messages (see
-            // `BaseMessageRoute.conversations()`).
-            const latestUid = conversation.messageUids[conversation.messageUids.length - 1];
-            setExpandedUids(new Set([latestUid]));
+            loadedIdRef.current = conversationId;
+            setMessages(loaded.messages);
+            setTruncated(loaded.truncated);
         })
             .catch((err) => {
             if (generation !== generationRef.current)
@@ -63,16 +152,68 @@ export default function ConversationThreadPane({ conversation, folders, labels }
             if (generation === generationRef.current)
                 setLoading(false);
         });
-    }, [conversation?.conversationId]);
-    // Lazily loads attachments and marks-as-read only for messages the reader has actually expanded —
-    // mirrors `mailDetailHooks.ts`'s `useMessageAttachments`/`useMarkMessageRead`, reimplemented here
-    // (rather than called in a loop, which the rules of hooks don't allow) since a thread can expand
-    // more than one message at once, unlike the single-selected-message case those hooks were built for.
+    }, [conversationId, mailboxUid]);
+    // Opening the thread, and opening a different message of the same thread, both set the run of expanded
+    // messages and ask for that message to be scrolled to. `messages` is a dependency because the thread's
+    // messages arrive after the click that selected one of them; the ref guard keeps a later change to
+    // `messages` (a patched copy) from re-running it.
+    useEffect(() => {
+        if (messages.length === 0 || loadedIdRef.current !== conversationId)
+            return;
+        const key = `${conversationId}:${selectedUid}`;
+        if (appliedSelectionRef.current === key)
+            return;
+        appliedSelectionRef.current = key;
+        const expanded = expandedFrom(messages, selectedUid);
+        setExpandedUids(expanded);
+        // The oldest expanded message is the one that was opened - `expandedFrom()`'s own anchor - which in
+        // this newest-first order is the *last* of the run, not the first.
+        setPendingFocusUid([...expanded][expanded.size - 1]);
+    }, [conversationId, selectedUid, messages]);
+    useLayoutEffect(() => {
+        if (!pendingFocusUid)
+            return;
+        // The row is always rendered by now: this runs after the DOM update that added the message it
+        // names, and that message came out of `messages` in the first place.
+        //
+        // Scrolled inside the thread's own list and nowhere else. `scrollIntoView()` scrolls *every*
+        // scrollable ancestor, the window included, which with a run of full-height messages expanded
+        // took the app header and the folder rail off the screen - so the adjustment goes on whichever
+        // ancestor actually scrolls, exactly as the toggle below already does it. When that is the page
+        // itself, nothing inside the pane scrolls and the row is already in view, so it is left alone.
+        const row = rowRefs.current[pendingFocusUid];
+        const scroller = scrollingAncestor(row);
+        if (scroller !== document.documentElement) {
+            const rect = row.getBoundingClientRect();
+            const top = rect.top - scroller.getBoundingClientRect().top;
+            // "nearest": the least that brings it into view, and nothing at all when it is already there.
+            if (top < 0 || top + rect.height > scroller.clientHeight) {
+                scroller.scrollTop += top;
+            }
+        }
+        // `preventScroll` so focusing doesn't scroll it somewhere else again.
+        headerRefs.current[pendingFocusUid].focus({ preventScroll: true });
+        setPendingFocusUid(null);
+    }, [pendingFocusUid, expandedUids]);
+    // Keeps the message whose header was just clicked where it was on screen. Expanding one above the
+    // message being read otherwise pushes everything below it down by however tall the new body is.
+    useLayoutEffect(() => {
+        const anchor = anchorRef.current;
+        if (!anchor)
+            return;
+        anchorRef.current = null;
+        // The row is still there: the anchor was taken from a rendered row, and toggling never removes one.
+        const row = rowRefs.current[anchor.uid];
+        scrollingAncestor(row).scrollTop += row.getBoundingClientRect().top - anchor.top;
+    }, [expandedUids]);
+    // Attachments and mark-as-read, for expanded messages only - mirrors `mailDetailHooks.ts`'s
+    // `useMessageAttachments`/`useMarkMessageRead`, reimplemented here (rather than called in a loop, which
+    // the rules of hooks don't allow) because a thread expands several messages at once.
     useEffect(() => {
         const generation = generationRef.current;
-        for (const uid of expandedUids) {
-            const message = messages[uid];
-            if (!message)
+        for (const message of messages) {
+            const uid = message.uid;
+            if (!expandedUids.has(uid))
                 continue;
             if (message.hasAttachments && !attachmentsRequestedRef.current.has(uid)) {
                 attachmentsRequestedRef.current.add(uid);
@@ -83,31 +224,43 @@ export default function ConversationThreadPane({ conversation, folders, labels }
                     }
                 })
                     .catch(() => {
-                    // Best-effort, same as the mark-as-read catch below — `attachmentsByUid[uid] ??
-                    // []` already renders no attachments while this stays unset; forgetting the
-                    // request just lets a later re-expand retry it.
+                    // Best-effort, as in `useMessageAttachments`: no attachments render meanwhile, and
+                    // forgetting the request lets a later re-expand retry it.
                     attachmentsRequestedRef.current.delete(uid);
                 });
             }
-            // `message` is this render's latest copy, so the request carries its current `version`.
             if (!message.flags.read && !markReadRequestedRef.current.has(uid)) {
                 markReadRequestedRef.current.add(uid);
+                // `message` is this render's copy, so the request carries its current `version`.
                 setMessageRead(message, true)
                     .then((updated) => {
                     if (generation !== generationRef.current)
                         return;
-                    // Never clobber a newer copy another action (label/classify/...) already patched in.
-                    setMessages((prev) => (prev[uid].version > updated.version ? prev : { ...prev, [uid]: updated }));
+                    // `message` is the unread copy this pane just replaced - what tells the list's own
+                    // conversation row that its unread count has gone down by one.
+                    patchMessage(updated, message);
                 })
                     .catch(() => {
-                    // Best-effort — matches `useMarkMessageRead`'s own doc comment. Forgetting the
-                    // request lets a later effect run (e.g. a re-expand) retry with a fresh copy.
+                    // Best-effort, as in `useMarkMessageRead`.
                     markReadRequestedRef.current.delete(uid);
                 });
             }
         }
     }, [expandedUids, messages]);
+    /** A newer copy of one of the thread's messages, kept here and handed to the list - with the copy it
+     * replaces where the caller was given one, so a conversation row can tell what actually changed. */
+    function patchMessage(updated, previous) {
+        setMessages((prev) => prev.map((message) => (message.uid === updated.uid ? updated : message)));
+        onMessagePatched(updated, previous);
+    }
+    /** A message that left the folder being listed - it leaves the thread too, as it left the list. */
+    function removeMessage(updated) {
+        setMessages((prev) => prev.filter((message) => message.uid !== updated.uid));
+        onMessageRemoved(updated);
+    }
     function toggleExpanded(uid) {
+        // The row this button lives in has rendered, so its ref is set.
+        anchorRef.current = { uid, top: rowRefs.current[uid].getBoundingClientRect().top };
         setExpandedUids((prev) => {
             const next = new Set(prev);
             if (next.has(uid)) {
@@ -119,6 +272,9 @@ export default function ConversationThreadPane({ conversation, folders, labels }
             return next;
         });
     }
+    function folderTypeOf(message) {
+        return folders.find((folder) => folder.uid === message.folderUid)?.type;
+    }
     if (!conversation) {
         return _jsx("p", { className: "p-8 text-sm text-text-muted", children: "Select a conversation to read it." });
     }
@@ -128,23 +284,24 @@ export default function ConversationThreadPane({ conversation, folders, labels }
     if (error) {
         return (_jsx("div", { className: "p-4 flex-1", children: _jsx(Alert, { children: error }) }));
     }
-    return (_jsxs("div", { className: "flex-1 min-w-0 flex flex-col overflow-y-auto", children: [_jsxs("div", { className: "border-b border-border p-4", children: [_jsx("h1", { className: "text-lg font-bold tracking-tight", children: conversation.subject || "(no subject)" }), _jsxs("p", { className: "text-sm text-text-muted mt-1", children: [conversation.messageCount, " message", conversation.messageCount === 1 ? "" : "s"] })] }), conversation.messageUids.map((uid) => {
-                const message = messages[uid];
-                if (!message) {
-                    return null;
-                }
-                const expanded = expandedUids.has(uid);
-                if (!expanded) {
-                    return (_jsxs("button", { type: "button", onClick: () => toggleExpanded(uid), className: [
-                            "w-full text-left px-4 py-3 border-b border-border hover:bg-surface-alt",
-                            message.flags.read ? "" : "font-semibold",
-                        ].join(" "), children: [_jsxs("div", { className: "flex items-center justify-between gap-2 text-sm", children: [_jsx("span", { className: "truncate", children: message.from.displayName || message.from.address }), _jsx("span", { className: "text-xs text-text-muted shrink-0", children: new Date(message.receivedDate).toLocaleString() })] }), _jsx("div", { className: "text-xs text-text-muted truncate font-normal", children: message.bodyPreview })] }, uid));
-                }
-                return (_jsxs("div", { className: "border-b border-border", children: [_jsx("button", { type: "button", onClick: () => toggleExpanded(uid), className: "w-full text-left px-4 pt-2 text-xs text-text-muted hover:text-text", children: "Collapse" }), _jsx(MessageDetailPane, { message: message, attachments: attachmentsByUid[uid] ?? [], isSentItems: folders.find((f) => f.uid === message.folderUid)?.type === "sent_items", onRecalled: (updated) => setMessages((prev) => ({ ...prev, [uid]: updated })), isOutbox: folders.find((f) => f.uid === message.folderUid)?.type === "outbox", draftsFolderUid: folders.find((f) => f.type === "drafts")?.uid, 
-                            // Unlike `apps/www/index.tsx`'s list-removal behavior, this patches the
-                            // message in place (same as `onRecalled` above) rather than removing it from
-                            // the conversation — `conversation.messageUids` is owned by the parent, not
-                            // this component, so there's no membership list here to remove it from.
-                            onScheduledSendCanceled: (updated) => setMessages((prev) => ({ ...prev, [uid]: updated })), isInbox: folders.find((f) => f.uid === message.folderUid)?.type === "inbox", onClassified: (updated) => setMessages((prev) => ({ ...prev, [uid]: updated })), onReceiptHandled: (updated) => setMessages((prev) => ({ ...prev, [uid]: updated })), onArchived: (updated) => setMessages((prev) => ({ ...prev, [uid]: updated })), labels: labels, onLabelsChanged: (updated) => setMessages((prev) => ({ ...prev, [uid]: updated })) })] }, uid));
-            })] }));
+    return (_jsxs("div", { className: "flex-1 min-w-0 min-h-0 flex flex-col", children: [_jsxs("div", { className: "shrink-0 border-b border-border p-4", children: [_jsx("h1", { className: "text-lg font-bold tracking-tight", children: conversation.subject || "(no subject)" }), _jsxs("p", { className: "text-sm text-text-muted mt-1", children: [messages.length, " message", messages.length === 1 ? "" : "s"] }), truncated && (_jsxs("p", { className: "text-xs text-text-muted mt-1", children: ["Only the oldest ", THREAD_MESSAGE_LIMIT, " messages of this conversation are shown here. The rest are still in the message list."] }))] }), _jsx("ul", { className: "flex-1 min-h-0 overflow-y-auto", children: messages.map((message) => {
+                    const uid = message.uid;
+                    const expanded = expandedUids.has(uid);
+                    const bodyId = `thread-message-${uid}`;
+                    const sender = message.from.displayName || message.from.address;
+                    return (_jsxs("li", { ref: (node) => {
+                            rowRefs.current[uid] = node;
+                        }, 
+                        // An expanded message is as tall as the list it scrolls in - `min-h-full`
+                        // against the `<ul>`'s own resolved height - so its `MessageDetailPane` below
+                        // has a full pane of height to fill and its body reaches the bottom of the
+                        // window whatever that window's size is. `min-` rather than `h-`: a message
+                        // whose header alone is taller than the pane still gets the room it needs.
+                        className: ["border-b border-border", expanded ? "flex flex-col min-h-full" : ""].join(" "), children: [_jsx("h2", { className: "shrink-0", children: _jsxs("button", { type: "button", ref: (node) => {
+                                        headerRefs.current[uid] = node;
+                                    }, onClick: () => toggleExpanded(uid), "aria-expanded": expanded, "aria-controls": bodyId, className: [
+                                        "w-full text-left px-4 py-3 hover:bg-surface-alt",
+                                        message.flags.read ? "" : "font-semibold",
+                                    ].join(" "), children: [_jsxs("span", { className: "flex items-center justify-between gap-2 text-sm", children: [_jsx("span", { className: "truncate", children: sender }), _jsx("span", { className: "text-xs text-text-muted shrink-0", children: new Date(message.receivedDate).toLocaleString() })] }), !expanded && (_jsx("span", { className: "block text-xs text-text-muted truncate font-normal", children: message.bodyPreview }))] }) }), _jsx("div", { id: bodyId, hidden: !expanded, className: expanded ? "flex-1 min-h-0 flex" : undefined, children: expanded && (_jsx(MessageDetailPane, { inThread: true, message: message, attachments: attachmentsByUid[uid] ?? [], isSentItems: folderTypeOf(message) === "sent_items", isOutbox: folderTypeOf(message) === "outbox", draftsFolderUid: folders.find((folder) => folder.type === "drafts")?.uid, folders: folders, onMoved: removeMessage, onFolderCreated: onFolderCreated, onRecalled: patchMessage, onReceiptHandled: patchMessage, onScheduledSendCanceled: removeMessage, onArchived: removeMessage, labels: labels, onLabelsChanged: patchMessage, onLabelCreated: onLabelCreated })) })] }, uid));
+                }) })] }));
 }

package/dist/apps/shared/components/mail/MailListToolbar.d.ts

@@ -0,0 +1,55 @@
+import React from "react";
+import { MessageListFilter, MessageListSort, MessageSortOrder } from "@rapidmx/react-shared/mail/mailApi.js";
+import { Label } from "@rapidmx/react-shared/mail/labelsApi.js";
+export interface MailListToolbarProps {
+    sortBy: MessageListSort;
+    sortOrder: MessageSortOrder;
+    filter: MessageListFilter;
+    /** The labels the list is currently narrowed to - any of them, not all. */
+    labelUids: string[];
+    /** Every label this mailbox has, for the Filter menu's own Labels submenu. */
+    labels: Label[];
+    onLabelUidsChange: (labelUids: string[]) => void;
+    /** The mailbox a label created from the Filter menu belongs to. */
+    mailboxUid: string;
+    /** Handed a label just created from the Filter menu, for the caller to add to `labels`. */
+    onLabelCreated: (label: Label) => void;
+    showAsConversations: boolean;
+    onSortChange: (sortBy: MessageListSort, sortOrder: MessageSortOrder) => void;
+    onFilterChange: (filter: MessageListFilter) => void;
+    onShowAsConversationsChange: (showAsConversations: boolean) => void;
+    selectMode: boolean;
+    onSelectModeChange: (selectMode: boolean) => void;
+    /** Offers the Focused/Other half of the filter vocabulary - an Inbox-only concept. */
+    offerClassificationFilters: boolean;
+    /** Search results are ranked by relevance across folders rather than listed from one, so the named
+     * filters don't apply to them. */
+    filterDisabled?: boolean;
+    filterDisabledReason?: string;
+    /** Greys out the sort keys and order while something else decides the order entirely: a search (ranked
+     * by relevance) or an aggregate view (one page merged from each mailbox). The Sort button itself stays
+     * open, since "Show as conversations" lives in it. */
+    sortKeysDisabled?: boolean;
+    /** Says why, under the sort keys. */
+    sortKeysNote?: string;
+    /** Individual sort keys the current arrangement can't order by, each with the reason shown beside it -
+     * the conversation list's own case, where the rows are thread summaries carrying no value for some of
+     * these (see `CONVERSATION_SORT_UNAVAILABLE`). The rest stay pickable. */
+    unavailableSortKeys?: Partial<Record<MessageListSort, string>>;
+    /** Select mode acts on the messages of one mailbox - so it is offered over both the message list and
+     * the conversation list (where a ticked row means every message of that conversation in this folder),
+     * but not over an aggregate view, whose rows come from several mailboxes whose folders a single Move
+     * couldn't name, nor over a list that is still loading or has no rows to tick. */
+    selectDisabled?: boolean;
+    selectDisabledReason?: string;
+}
+/**
+ * The mail list's Outlook-style toolbar: a Filter menu, a Sort menu (which also carries "Show as
+ * conversations", Outlook's own home for it - it arranges the list rather than acting on a message, and
+ * keeping it there leaves the toolbar three controls wide, which is what fits a 400px phone) and a Select
+ * toggle that turns the list into a multi-select with bulk actions.
+ *
+ * Both menus drive server-side parameters (`listMessages()`'s `sortBy`/`sortOrder`/`filter`), so they sort
+ * and filter the whole folder rather than the page that happens to be loaded.
+ */
+export default function MailListToolbar({ sortBy, sortOrder, filter, labelUids, labels, onLabelUidsChange, mailboxUid, onLabelCreated, showAsConversations, onSortChange, onFilterChange, onShowAsConversationsChange, selectMode, onSelectModeChange, offerClassificationFilters, filterDisabled, filterDisabledReason, sortKeysDisabled, sortKeysNote, unavailableSortKeys, selectDisabled, selectDisabledReason, }: MailListToolbarProps): React.JSX.Element;

package/dist/apps/shared/components/mail/MailListToolbar.js

@@ -0,0 +1,149 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useState } from "react";
+import { HiOutlineAdjustmentsHorizontal, HiOutlineBarsArrowDown, HiOutlineStop } from "react-icons/hi2";
+import MenuButton from "./MenuButton.js";
+import { NewLabelDialog, labelSections, useLabelDraft } from "./labelMenu.js";
+import { MAIL_LIST_CLASSIFICATION_FILTERS, MAIL_LIST_FILTERS, MAIL_LIST_SORTS, SORT_ORDER_LABELS, defaultSortOrder, } from "./listPreferences.js";
+/** The label for the filter currently in force, or `undefined` for "All" (which isn't worth naming on the
+ * button). */
+function filterLabel(filter) {
+    return [...MAIL_LIST_FILTERS, ...MAIL_LIST_CLASSIFICATION_FILTERS].find((entry) => entry.value === filter && entry.value !== "all")
+        ?.label;
+}
+function sortLabel(sortBy) {
+    // Every `MessageListSort` has an entry, so this never falls through.
+    return MAIL_LIST_SORTS.find((entry) => entry.value === sortBy).label;
+}
+/**
+ * The mail list's Outlook-style toolbar: a Filter menu, a Sort menu (which also carries "Show as
+ * conversations", Outlook's own home for it - it arranges the list rather than acting on a message, and
+ * keeping it there leaves the toolbar three controls wide, which is what fits a 400px phone) and a Select
+ * toggle that turns the list into a multi-select with bulk actions.
+ *
+ * Both menus drive server-side parameters (`listMessages()`'s `sortBy`/`sortOrder`/`filter`), so they sort
+ * and filter the whole folder rather than the page that happens to be loaded.
+ */
+export default function MailListToolbar({ sortBy, sortOrder, filter, labelUids, labels, onLabelUidsChange, mailboxUid, onLabelCreated, showAsConversations, onSortChange, onFilterChange, onShowAsConversationsChange, selectMode, onSelectModeChange, offerClassificationFilters, filterDisabled, filterDisabledReason, sortKeysDisabled, sortKeysNote, unavailableSortKeys, selectDisabled, selectDisabledReason, }) {
+    const activeFilter = filterLabel(filter);
+    const orderLabels = SORT_ORDER_LABELS[sortBy];
+    // The label picks are drafted while the Filter menu is open and applied in one go, so narrowing to
+    // three labels is one refetch rather than three.
+    const [filterMenuOpen, setFilterMenuOpen] = useState(false);
+    const [creatingLabel, setCreatingLabel] = useState(false);
+    const labelDraft = useLabelDraft(labelUids, [], filterMenuOpen);
+    const chosenLabelName = labels.find((l) => l.uid === labelUids[0])?.name;
+    // What the button says it is set to: the named filter, the labels, or both.
+    const activeParts = [
+        ...(activeFilter ? [activeFilter] : []),
+        ...(labelUids.length === 1 ? [chosenLabelName ?? "1 label"] : labelUids.length > 1 ? [`${labelUids.length} labels`] : []),
+    ];
+    const filterButtonLabel = activeParts.length > 0 ? `Filter: ${activeParts.join(", ")}` : "Filter";
+    const filterSections = [
+        {
+            key: "filter",
+            label: "Filter",
+            items: MAIL_LIST_FILTERS.map((entry) => ({
+                key: entry.value,
+                label: entry.label,
+                role: "menuitemradio",
+                checked: filter === entry.value,
+                onSelect: () => onFilterChange(entry.value),
+            })),
+        },
+    ];
+    if (offerClassificationFilters) {
+        filterSections.push({
+            key: "classification",
+            label: "Focused Inbox",
+            note: "One filter at a time: picking Focused or Other replaces the filter above.",
+            items: MAIL_LIST_CLASSIFICATION_FILTERS.map((entry) => ({
+                key: entry.value,
+                label: entry.label,
+                role: "menuitemradio",
+                checked: filter === entry.value,
+                onSelect: () => onFilterChange(entry.value),
+            })),
+        });
+    }
+    filterSections.push({
+        key: "labels",
+        items: [
+            {
+                key: "labels",
+                label: labelUids.length > 0 ? `Labels (${labelUids.length})` : "Labels",
+                description: "Show only messages with the labels you pick",
+                // A submenu rather than another group: a mailbox can have far more labels than the rest of
+                // this menu has rows, and they are picked several at a time rather than one instead of another.
+                submenu: labelSections({
+                    labels,
+                    state: labelDraft,
+                    note: "Shows messages with any of the ticked labels.",
+                    emptyNote: "This mailbox has no labels yet.",
+                    commit: { label: "Apply labels", onSelect: () => onLabelUidsChange(labelDraft.draft), disabled: !labelDraft.dirty },
+                    onCreate: () => setCreatingLabel(true),
+                    // Clearing the label filter is worth doing in one step, so this applies straight away.
+                    clear: { label: "Clear labels", keepOpen: false, disabled: labelUids.length === 0, onSelect: () => onLabelUidsChange([]) },
+                }),
+            },
+        ],
+    });
+    const sortSections = [
+        {
+            key: "sortBy",
+            label: "Sort by",
+            note: sortKeysNote,
+            items: MAIL_LIST_SORTS.map((entry) => ({
+                key: entry.value,
+                label: entry.label,
+                // The reason a key is unavailable is shown on the row itself rather than folded into the
+                // group's note, so it sits beside the one key it explains.
+                description: unavailableSortKeys?.[entry.value],
+                role: "menuitemradio",
+                checked: sortBy === entry.value,
+                disabled: sortKeysDisabled || entry.value in (unavailableSortKeys ?? {}),
+                // Switching field resets the direction to the one that reads naturally for it, rather than
+                // carrying Date's newest-first over to Subject as a surprising Z-A.
+                onSelect: () => onSortChange(entry.value, defaultSortOrder(entry.value)),
+            })),
+        },
+        {
+            key: "sortOrder",
+            label: "Order",
+            items: ["desc", "asc"].map((order) => ({
+                key: order,
+                label: orderLabels[order],
+                role: "menuitemradio",
+                checked: sortOrder === order,
+                disabled: sortKeysDisabled,
+                onSelect: () => onSortChange(sortBy, order),
+            })),
+        },
+        {
+            key: "arrange",
+            items: [
+                {
+                    key: "conversations",
+                    label: "Show as conversations",
+                    description: "Group replies into one row",
+                    role: "menuitemcheckbox",
+                    checked: showAsConversations,
+                    onSelect: () => onShowAsConversationsChange(!showAsConversations),
+                },
+            ],
+        },
+    ];
+    return (_jsxs("div", { className: "flex items-center gap-0.5 px-1.5 py-1 border-b border-border", children: [_jsx(NewLabelDialog, { open: creatingLabel, onClose: () => setCreatingLabel(false), mailboxUid: mailboxUid, onCreated: onLabelCreated }), _jsx(MenuButton, { "aria-label": filterButtonLabel, label: filterButtonLabel, icon: _jsx(HiOutlineAdjustmentsHorizontal, { size: 16, "aria-hidden": "true", className: "shrink-0 text-text-muted" }), onOpenChange: setFilterMenuOpen, sections: filterSections, disabled: filterDisabled, title: filterDisabled ? filterDisabledReason : undefined }), _jsx(MenuButton, { "aria-label": `Sort: ${sortLabel(sortBy)}`, label: `Sort: ${sortLabel(sortBy)}`, icon: _jsx(HiOutlineBarsArrowDown, { size: 16, "aria-hidden": "true", className: "shrink-0 text-text-muted" }), sections: sortSections }), _jsx("button", { type: "button", "aria-pressed": selectMode, disabled: selectDisabled, 
+                // Icon-only, so the tooltip is the only thing naming it on screen - replaced by the reason
+                // while it is unavailable, which is the more useful thing to read at that moment.
+                title: selectDisabled ? selectDisabledReason : "Select", onClick: () => onSelectModeChange(!selectMode), "aria-label": "Select", className: [
+                    // Icon-only, like Outlook's own "select items" command: the glyph carries it and the
+                    // name lives in `aria-label`/`title`. The pressed state is a filled, outlined box
+                    // rather than only a colour change, so it stays legible next to a disabled one.
+                    "ml-auto shrink-0 inline-flex items-center justify-center p-1.5 rounded-md hover:bg-surface-alt disabled:opacity-50 disabled:hover:bg-transparent",
+                    selectMode ? "bg-primary/10 text-primary-dark" : "text-text-muted",
+                ].join(" "), children: _jsx(HiOutlineStop, { size: 18, "aria-hidden": "true", className: "shrink-0" }) })] }));
+}

package/dist/apps/shared/components/mail/MailSelectionBar.d.ts

@@ -0,0 +1,59 @@
+import React from "react";
+import { Folder, Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import { Label } from "@rapidmx/react-shared/mail/labelsApi.js";
+export interface MailSelectionBarProps {
+    selected: Message[];
+    /** Every message currently listed - what "Select all" selects and what `allSelected` is measured against. */
+    listed: Message[];
+    /** What the bar *counts*, when the rows being ticked aren't messages themselves: the conversation list
+     * ticks conversations, each standing for several messages, so "3 conversations selected" is what the
+     * reader picked while `selected` stays the messages every action below acts on. Left out by the flat
+     * message list, which counts `selected`/`listed` directly. */
+    totals?: {
+        selected: number;
+        listed: number;
+        noun: string;
+    };
+    onSelectAll: () => void;
+    onClearSelection: () => void;
+    /** Leaves select mode entirely (and clears the selection). */
+    onCancel: () => void;
+    folders: Folder[];
+    currentFolderUid?: string;
+    /** Every label this mailbox has, for the Apply label action. */
+    labels: Label[];
+    /** The mailbox a label created from Apply label belongs to. */
+    mailboxUid: string;
+    onLabelCreated: (label: Label) => void;
+    /** A folder created from the Move to prompt, for the caller's own folder list and the sidebar. */
+    onFolderCreated: (folder: Folder) => void;
+    /** Sets the selection's labels: every message ends up with `labelUids`, plus whichever of
+     * `keepPartial` it already had (those rows were left partially applied, so each message keeps what
+     * it has). */
+    onApplyLabels: (labelUids: string[], keepPartial: string[]) => void;
+    onSetRead: (read: boolean) => void;
+    onSetFlagged: (flagged: boolean) => void;
+    onArchive: () => void;
+    /** Moves the selection into `folderUid`, resolving once the bulk update has settled. It resolves
+     * whether or not that update was rejected: a bulk update is applied element by element, so a failure
+     * is explained in this bar (along with the reload it triggers) rather than in the prompt, which would
+     * be claiming the move simply didn't happen. */
+    onMoveTo: (folderUid: string) => Promise<void>;
+    onReportJunk: () => void;
+    onDelete: () => void;
+    /** A bulk action is in flight - every action is held until it settles, since the next one would send
+     * `version`s the first has already superseded. */
+    busy: boolean;
+    error: string | null;
+}
+/**
+ * The header that replaces the list's own toolbar while select mode is on: how many rows are selected,
+ * select-all/clear, and the bulk actions Outlook offers for a multi-selection - mark read/unread, flag,
+ * archive, move, report junk and delete.
+ *
+ * "Delete" means *move to Deleted Items*, never a permanent erase: there is no bulk permanent-delete API,
+ * and the collection-level DELETE truncates the folder rather than removing a selection. An action whose
+ * target folder is the one already being viewed is disabled with a reason rather than hidden, so the set
+ * of actions doesn't shift around between folders.
+ */
+export default function MailSelectionBar({ selected, listed, totals, onSelectAll, onClearSelection, onCancel, folders, currentFolderUid, labels, mailboxUid, onLabelCreated, onFolderCreated, onApplyLabels, onSetRead, onSetFlagged, onArchive, onMoveTo, onReportJunk, onDelete, busy, error, }: MailSelectionBarProps): React.JSX.Element;