@rapidmx/web-client 0.5.0 → 0.7.0

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

@@ -0,0 +1,97 @@
+import React from "react";
+import { Label } from "@rapidmx/react-shared/mail/labelsApi.js";
+import { MenuSectionSpec } from "./MenuButton.js";
+/**
+ * The one multi-select label list this app uses everywhere labels are picked: the Filter menu's "Labels"
+ * submenu, the bulk Apply label action in select mode, and the reading pane's own Labels button. All three
+ * tick several labels with the menu staying open and commit them with one command, so the keyboard
+ * handling, the checkmarks and the partially-applied state behave identically wherever they appear.
+ */
+/** What the reader has ticked so far, before committing. */
+export interface LabelDraft {
+    /** Labels currently ticked. */
+    draft: string[];
+    /** Labels still showing as partially applied - some of the messages being acted on carry them and some
+     * don't, and the reader hasn't touched the row, so committing leaves each message as it is. */
+    mixed: string[];
+    toggle: (labelUid: string) => void;
+    /** Unticks everything, including anything still partially applied. */
+    clear: () => void;
+    /** `true` once the draft differs from what it started as - what the commit row is enabled by. */
+    dirty: boolean;
+}
+/**
+ * Holds the ticked/partially-applied state of a label list while its menu is open, starting again from
+ * `applied`/`partial` every time the menu is reopened - so dismissing a menu (Escape, a click outside)
+ * discards the draft rather than silently keeping half a change.
+ */
+export declare function useLabelDraft(applied: string[], partial: string[], open: boolean): LabelDraft;
+export interface LabelSectionsOptions {
+    labels: Label[];
+    state: LabelDraft;
+    /** The row that commits the draft. */
+    commit: {
+        label: string;
+        onSelect: () => void;
+        disabled?: boolean;
+    };
+    /** The row that unticks everything. `keepOpen` false lets a caller (the filter) apply it straight away. */
+    clear: {
+        label: string;
+        disabled?: boolean;
+        keepOpen?: boolean;
+        onSelect?: () => void;
+    };
+    /** What to say instead of the list when this mailbox has no labels. */
+    emptyNote: string;
+    /** Adds a "New label" row. A `role="menu"` can't hold the text field that needs, so the row closes the
+     * menu and opens `NewLabelDialog` - see `LabelMenuButton` and the Filter menu's own use of it. */
+    onCreate?: () => void;
+    /** Where labels are renamed, recoloured and deleted. */
+    managePath?: string;
+    /** A line under the list explaining what committing will do. */
+    note?: string;
+    /** Holds every row while a request is in flight. */
+    busy?: boolean;
+}
+/**
+ * The label rows plus their commit/clear rows, as `MenuButton` sections - so the same list can be a menu of
+ * its own (`LabelMenuButton` below) or a submenu of another menu (the Filter menu's "Labels" row).
+ */
+export declare function labelSections({ labels, state, commit, clear, emptyNote, note, busy, onCreate, managePath, }: LabelSectionsOptions): MenuSectionSpec[];
+export interface NewLabelDialogProps {
+    open: boolean;
+    onClose: () => void;
+    mailboxUid: string;
+    /** Handed the label the server created, for the caller to add to its own list. */
+    onCreated: (label: Label) => void;
+}
+/** The "New label" form the menus open - a dialog rather than more menu rows, because a `role="menu"`
+ * has no place for a text field. Colour is left to Settings > Labels; this is the quick path from a
+ * message, so it only asks for the name. */
+export declare function NewLabelDialog({ open, onClose, mailboxUid, onCreated }: NewLabelDialogProps): React.JSX.Element;
+export interface LabelMenuButtonProps extends Omit<LabelSectionsOptions, "state" | "commit"> {
+    /** The commit row - this component supplies its action (`onCommit` below) and disables it until the
+     * draft actually differs from what it started as. */
+    commit: {
+        label: string;
+        disabled?: boolean;
+    };
+    /** The labels every target already carries. */
+    applied: string[];
+    /** The labels only some of them carry. */
+    partial?: string[];
+    /** Called with the labels to end up with, and the ones left partially applied (each target keeps those
+     * exactly as they are). */
+    onCommit: (labelUids: string[], keepPartial: string[]) => void;
+    label: string;
+    "aria-label": string;
+    disabled?: boolean;
+    title?: string;
+    className?: string;
+    /** With `onLabelCreated`, adds a "New label" row that opens this component's own dialog. */
+    mailboxUid?: string;
+    onLabelCreated?: (label: Label) => void;
+}
+/** The label list as a menu button of its own - the bulk Apply label action and the reading pane's Labels. */
+export default function LabelMenuButton({ applied, partial, onCommit, labels, commit, clear, emptyNote, note, busy, label, "aria-label": ariaLabel, disabled, title, className, mailboxUid, onLabelCreated, }: LabelMenuButtonProps): React.JSX.Element;

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

@@ -0,0 +1,134 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useState } from "react";
+import { HiOutlineTag } from "react-icons/hi2";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { createLabel } from "@rapidmx/react-shared/mail/labelsApi.js";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+import FormField from "@rapidmx/react-shared/components/forms/FormField.js";
+import Modal from "@rapidmx/react-shared/components/overlays/Modal.js";
+import MenuButton from "./MenuButton.js";
+/** `a` and `b` hold the same uids, order ignored. */
+function sameUids(a, b) {
+    return a.length === b.length && a.every((uid) => b.includes(uid));
+}
+/**
+ * Holds the ticked/partially-applied state of a label list while its menu is open, starting again from
+ * `applied`/`partial` every time the menu is reopened - so dismissing a menu (Escape, a click outside)
+ * discards the draft rather than silently keeping half a change.
+ */
+export function useLabelDraft(applied, partial, open) {
+    const [state, setState] = useState(null);
+    const [wasOpen, setWasOpen] = useState(open);
+    if (wasOpen !== open) {
+        setWasOpen(open);
+        setState(open ? { draft: applied, mixed: partial } : null);
+    }
+    const current = state ?? { draft: applied, mixed: partial };
+    return {
+        draft: current.draft,
+        mixed: current.mixed,
+        toggle: (labelUid) => setState({
+            // Touching a partially-applied row settles it: it becomes a plain tick (apply to all).
+            draft: current.draft.includes(labelUid)
+                ? current.draft.filter((uid) => uid !== labelUid)
+                : [...current.draft, labelUid],
+            mixed: current.mixed.filter((uid) => uid !== labelUid),
+        }),
+        clear: () => setState({ draft: [], mixed: [] }),
+        dirty: !sameUids(current.draft, applied) || !sameUids(current.mixed, partial),
+    };
+}
+/**
+ * The label rows plus their commit/clear rows, as `MenuButton` sections - so the same list can be a menu of
+ * its own (`LabelMenuButton` below) or a submenu of another menu (the Filter menu's "Labels" row).
+ */
+export function labelSections({ labels, state, commit, clear, emptyNote, note, busy, onCreate, managePath = "/settings/labels", }) {
+    const manageItem = {
+        key: "manage",
+        label: "Manage labels…",
+        onSelect: () => {
+            window.location.href = managePath;
+        },
+    };
+    const tailItems = [...(onCreate ? [{ key: "create", label: "New label…", onSelect: onCreate }] : []), manageItem];
+    if (labels.length === 0) {
+        return [{ key: "labels", label: "Labels", note: emptyNote, items: tailItems }];
+    }
+    return [
+        {
+            key: "labels",
+            label: "Labels",
+            note,
+            items: labels.map((label) => ({
+                key: label.uid,
+                label: label.name,
+                role: "menuitemcheckbox",
+                checked: state.mixed.includes(label.uid) ? "mixed" : state.draft.includes(label.uid),
+                swatchColor: label.color ?? "#6366f1",
+                disabled: busy,
+                // Several labels are ticked before anything is committed, so a tick never closes the menu.
+                keepOpen: true,
+                onSelect: () => state.toggle(label.uid),
+            })),
+        },
+        {
+            key: "commands",
+            items: [
+                {
+                    key: "clear",
+                    label: clear.label,
+                    disabled: busy || clear.disabled || (state.draft.length === 0 && state.mixed.length === 0),
+                    keepOpen: clear.keepOpen ?? true,
+                    onSelect: () => (clear.onSelect ?? state.clear)(),
+                },
+                { key: "commit", label: commit.label, disabled: busy || commit.disabled, onSelect: commit.onSelect },
+                ...tailItems,
+            ],
+        },
+    ];
+}
+/** The "New label" form the menus open - a dialog rather than more menu rows, because a `role="menu"`
+ * has no place for a text field. Colour is left to Settings > Labels; this is the quick path from a
+ * message, so it only asks for the name. */
+export function NewLabelDialog({ open, onClose, mailboxUid, onCreated }) {
+    const [name, setName] = useState("");
+    const [saving, setSaving] = useState(false);
+    const [error, setError] = useState(null);
+    async function save() {
+        setSaving(true);
+        setError(null);
+        try {
+            onCreated(await createLabel({ mailboxUid, name: name.trim() }));
+            setName("");
+            onClose();
+        }
+        catch (err) {
+            setError(err instanceof ApiRequestError ? err.message : "Could not create this label.");
+        }
+        finally {
+            setSaving(false);
+        }
+    }
+    return (_jsxs(Modal, { open: open, onClose: onClose, title: "New label", children: [error && _jsx(Alert, { children: error }), _jsx(FormField, { label: "Name", htmlFor: "new-label-name", children: _jsx("input", { id: "new-label-name", type: "text", value: name, onChange: (e) => setName(e.target.value), className: "w-full text-sm px-3 py-1.5 rounded-md border border-border bg-surface" }) }), _jsxs("div", { className: "flex justify-end gap-2 mt-2", children: [_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: onClose, children: "Cancel" }), _jsx(Button, { type: "button", className: "!w-auto", loading: saving, disabled: saving || !name.trim(), onClick: () => void save(), children: "Create" })] })] }));
+}
+/** The label list as a menu button of its own - the bulk Apply label action and the reading pane's Labels. */
+export default function LabelMenuButton({ applied, partial = [], onCommit, labels, commit, clear, emptyNote, note, busy, label, "aria-label": ariaLabel, disabled, title, className, mailboxUid, onLabelCreated, }) {
+    const [open, setOpen] = useState(false);
+    const [creating, setCreating] = useState(false);
+    const state = useLabelDraft(applied, partial, open);
+    return (_jsxs(_Fragment, { children: [_jsx(MenuButton, { "aria-label": ariaLabel, label: label, icon: _jsx(HiOutlineTag, { size: 16, "aria-hidden": "true", className: "shrink-0 text-text-muted" }), disabled: disabled, title: title, className: className, onOpenChange: setOpen, sections: labelSections({
+                    labels,
+                    state,
+                    commit: { ...commit, disabled: commit.disabled || !state.dirty, onSelect: () => onCommit(state.draft, state.mixed) },
+                    clear,
+                    emptyNote,
+                    note,
+                    busy,
+                    onCreate: mailboxUid && onLabelCreated ? () => setCreating(true) : undefined,
+                }) }), mailboxUid && onLabelCreated && (_jsx(NewLabelDialog, { open: creating, onClose: () => setCreating(false), mailboxUid: mailboxUid, onCreated: onLabelCreated }))] }));
+}

package/dist/apps/shared/components/mail/layout/MailShell.d.ts

@@ -0,0 +1,65 @@
+import React, { PropsWithChildren } from "react";
+import { Folder, Mailbox } from "@rapidmx/react-shared/mail/mailApi.js";
+import { AppShellProps } from "../../layout/AppShell.js";
+export type MailShellProps = Omit<AppShellProps, "active">;
+/** One mailbox's own mail folders (already filtered to `MAIL_FOLDER_TYPES` and unsorted) - one entry per
+ * mailbox in `mailboxes`, fetched in parallel so every accessible mailbox's folder tree can render
+ * simultaneously (see `MailShell`'s own doc comment on why this replaced the old single-mailbox `folders`
+ * field). `error` is set (and `folders` left empty) for a mailbox whose own `listFolders()` call failed -
+ * one mailbox's fetch failure must never blank out every other mailbox's section. */
+export interface MailboxFolders {
+    mailbox: Mailbox;
+    folders: Folder[];
+    error?: string;
+}
+/** The well-known mail folder types an "aggregate" pseudo-folder can merge across every accessible
+ * mailbox - a fixed, small set: `outbox` is deliberately excluded (transient per-mailbox send-queue
+ * state, not a "merge across mailboxes" concept), and there's no aggregate concept for `calendar`/
+ * `contacts`/`tasks`/`notes`/`user` folders (Mail's own sidebar already excludes those - see
+ * `MAIL_FOLDER_TYPES`). */
+export declare const AGGREGATE_FOLDER_TYPES: readonly ["inbox", "sent_items", "drafts", "deleted_items", "junk"];
+export type AggregateFolderType = (typeof AGGREGATE_FOLDER_TYPES)[number];
+export interface MailShellContextValue {
+    /** The mailbox currently selected (`?mailboxUid=`) - `undefined` while an aggregate pseudo-folder is
+     * active instead (`aggregateFolderType` set), since there's no single mailbox to speak of then. */
+    mailboxUid?: string;
+    /** The folder currently selected (`?folderUid=`, or the selected mailbox's Inbox) - `undefined` in
+     * aggregate mode, for the same reason. */
+    folderUid?: string;
+    /** Set only when an aggregate pseudo-folder (`?aggregate=inbox` etc.) is selected instead of a real,
+     * single mailbox+folder - mutually exclusive with `mailboxUid`/`folderUid` above. */
+    aggregateFolderType?: AggregateFolderType;
+    mailboxes: Mailbox[];
+    /** Every accessible mailbox's own mail folders - replaces the old single-mailbox `folders: Folder[]`
+     * now that every mailbox's tree renders at once (see `MailboxFolders`'s own doc comment). */
+    mailboxFolders: MailboxFolders[];
+    /**
+     * Adds a folder a page has just created (the Move to prompt's "New folder") to the tree this shell
+     * already fetched, so it appears in the sidebar and in every folder picker without a reload - this
+     * framework has no client-side router, so a reload is a whole page load.
+     *
+     * A no-op on the default context value, which is only ever read outside a real shell.
+     */
+    onFolderCreated: (folder: Folder) => void;
+}
+/** Reads the mailbox/folder a page is currently showing, as resolved by the enclosing `MailShell`. */
+export declare function useMailShell(): MailShellContextValue;
+/** Page size of the one `listMailboxes()` call this shell makes. */
+export declare const MAILBOX_LIST_LIMIT = 100;
+/**
+ * Mail's own contextual sidebar (every accessible mailbox's own folder tree, plus a merged "All Mailboxes"
+ * aggregate section) + content area, rendered inside the shared `AppShell` chrome (icon rail, header,
+ * impersonation banner — see that component). There is no client-side router in this framework (see
+ * `ReactRoute`'s file-convention resolver) — the selected mailbox/folder (or aggregate pseudo-folder) live
+ * in the URL's `?mailboxUid=`/`?folderUid=`/`?aggregate=` query params, read once on mount (never during
+ * the initial render itself, matching every other query-param reader in this codebase — e.g.
+ * `apps/admin/quarantine`'s `readMailboxUid()` — so the server-rendered and just-hydrated client markup
+ * match).
+ *
+ * Every accessible mailbox's folder tree renders at once - there is no "switch mailbox" affordance
+ * anymore (the mailbox `<select>` this shell used to have is gone) - so a single-mailbox user sees zero
+ * behavior change from before this, and a multi-mailbox user sees every mailbox's folders (and the new
+ * aggregate section) simultaneously, matching the shared-mailbox feature's own "display as a separate set
+ * of folders" requirement.
+ */
+export default function MailShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, pluginNav, children, }: PropsWithChildren<MailShellProps>): React.JSX.Element;

package/dist/apps/shared/components/mail/layout/MailShell.js

@@ -3,7 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import { createContext, useContext, useEffect, useMemo, useState } from "react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
 import { HiOutlineBars3 } from "react-icons/hi2";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import Drawer from "@rapidmx/react-shared/components/overlays/Drawer.js";
@@ -24,7 +24,11 @@ export const AGGREGATE_FOLDER_TYPES = ["inbox", "sent_items", "drafts", "deleted
 function isAggregateFolderType(value) {
     return !!value && AGGREGATE_FOLDER_TYPES.includes(value);
 }
-const MailShellContext = createContext({ mailboxes: [], mailboxFolders: [] });
+const MailShellContext = createContext({
+    mailboxes: [],
+    mailboxFolders: [],
+    onFolderCreated: () => undefined,
+});
 /** Reads the mailbox/folder a page is currently showing, as resolved by the enclosing `MailShell`. */
 export function useMailShell() {
     return useContext(MailShellContext);
@@ -90,7 +94,7 @@ function ComposeButton() {
  * aggregate section) simultaneously, matching the shared-mailbox feature's own "display as a separate set
  * of folders" requirement.
  */
-export default function MailShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, children, }) {
+export default function MailShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, pluginNav, children, }) {
     const [status, setStatus] = useState("checking");
     const [error, setError] = useState(null);
     const [mailboxes, setMailboxes] = useState([]);
@@ -162,7 +166,15 @@ export default function MailShell({ userUid, authServerUrl, impersonating, imper
     // mailbox may still need that mailbox's own folder view opened directly to unlock/decrypt it.
     const defaultMailboxUid = mailboxes.find((mb) => mb.ownerUserUid === userUid)?.uid ?? mailboxes[0]?.uid;
     const activeMailboxUid = mailboxUid ?? defaultMailboxUid;
-    const contextValue = useMemo(() => ({ mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders }), [mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders]);
+    /** Files a newly created folder under its own mailbox, leaving every other mailbox's list untouched -
+     * and ignoring a type this sidebar doesn't list at all, the same filter the fetch above applies. */
+    const onFolderCreated = useCallback((folder) => {
+        if (!MAIL_FOLDER_TYPES.has(folder.type)) {
+            return;
+        }
+        setMailboxFolders((prev) => prev.map((entry) => entry.mailbox.uid === folder.mailboxUid ? { ...entry, folders: [...entry.folders, folder] } : entry));
+    }, []);
+    const contextValue = useMemo(() => ({ mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated }), [mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated]);
     // A full-screen takeover, not nested inside the rest of the app's chrome — there's nothing else for a
     // mailbox-less caller to do here yet, so the icon rail/header/folder tree don't render at all. Checks
     // `mailboxes.length` directly (not `!mailboxUid`) since `mailboxUid` is legitimately undefined in
@@ -219,5 +231,5 @@ export default function MailShell({ userUid, authServerUrl, impersonating, imper
         canProvision: !impersonating && activeMailbox?.ownerUserUid === userUid, children: [_jsx(LocalIndexLifecycle, { mailboxUid: activeMailboxUid, mailboxKeys: activeMailbox?.keys, folders: mailboxFolders.find((mf) => mf.mailbox.uid === activeMailboxUid)?.folders ?? [], 
                 // A full page may be truncated - pruning against it would delete indexes of accessible mailboxes
                 // beyond the limit, so it's only trusted as the complete list when it came back short.
-                accessibleMailboxUids: status === "ready" && mailboxes.length < MAILBOX_LIST_LIMIT ? mailboxes.map((mb) => mb.uid) : undefined }), _jsx(AppShell, { active: "mail", userUid: userUid, authServerUrl: authServerUrl, impersonating: impersonating, impersonationBaseUrl: impersonationBaseUrl, trusted: trusted, children: inner })] }));
+                accessibleMailboxUids: status === "ready" && mailboxes.length < MAILBOX_LIST_LIMIT ? mailboxes.map((mb) => mb.uid) : undefined }), _jsx(AppShell, { active: "mail", userUid: userUid, authServerUrl: authServerUrl, impersonating: impersonating, impersonationBaseUrl: impersonationBaseUrl, trusted: trusted, pluginNav: pluginNav, children: inner })] }));
 }

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

@@ -0,0 +1,101 @@
+/**
+ * The mail list's own per-mailbox view preferences - what the Sort and Filter menus and the "Show as
+ * conversations" toggle are currently set to - persisted in `localStorage` so reopening the app lands on
+ * the arrangement the reader left it in, the way Outlook remembers its own per-folder arrangement.
+ *
+ * Per device, not synced to the server: this is the same posture `localIndexSizePreference.ts` and
+ * react-shared's `idleTimeout.ts` already take, and there is no server-side "mail view settings" record to
+ * write to. Keyed by mailbox because a shared mailbox someone triages ("unread only, oldest on top") is a
+ * genuinely different working set from their own inbox.
+ *
+ * Every read falls back to `DEFAULT_MAIL_LIST_PREFERENCES` for a never-configured mailbox, a corrupted or
+ * partially-unknown stored value, or a `localStorage` access that throws (private-browsing/storage-blocked
+ * contexts) - and every write swallows its own failure, so a blocked store only means the preference
+ * doesn't survive a reload.
+ */
+import { MessageListFilter, MessageListSort, MessageSortOrder } from "@rapidmx/react-shared/mail/mailApi.js";
+import { ConversationSummary } from "@rapidmx/react-shared/mail/conversationsApi.js";
+export interface MailListPreferences {
+    sortBy: MessageListSort;
+    sortOrder: MessageSortOrder;
+    filter: MessageListFilter;
+    /** Labels the list is narrowed to, applied *alongside* `filter` with OR semantics between them: a
+     * message is listed when it carries any one of these. Empty means no label filter at all. Kept per
+     * mailbox because a label uid only means anything inside its own mailbox. */
+    labelUids: string[];
+    /** Outlook's "Show as conversations" - the nested conversation list rather than the flat message list. */
+    showAsConversations: boolean;
+}
+/** How many labels the list may be narrowed to at once. `@rapidmx/restapi` refuses a longer `?labelUids=`
+ * with a 400, so a stored selection is trimmed to the cap rather than sent. */
+export declare const MAX_LABEL_FILTER_UIDS = 20;
+/**
+ * What a mailbox nobody has configured yet opens on: newest received first, no label filter, and - like
+ * Outlook's own out-of-the-box arrangement - the Focused half of the Inbox, shown as conversations.
+ *
+ * Neither of those last two is `listMessages()`'s own default (`all`, and the flat list): they are this
+ * client's opinion about what a first-time reader should see, applied only where nothing has been stored
+ * (see `getMailListPreferences()`, which keeps a stored `false`/`all` exactly as it was). `focused` also
+ * only ever applies in an Inbox - every other folder falls back to `all` in `apps/www/index.tsx`, which is
+ * what `MessageListFilter`'s own "Inbox-only concept" note requires.
+ */
+export declare const DEFAULT_MAIL_LIST_PREFERENCES: MailListPreferences;
+/** Every sort key the server accepts, with the label the Sort menu shows for it - the order here is the
+ * order the menu lists them in. */
+export declare const MAIL_LIST_SORTS: {
+    value: MessageListSort;
+    label: string;
+}[];
+/** Every named filter the server accepts, minus the Focused/Other pair (which the menu groups separately,
+ * and only offers in an Inbox - see `MessageListFilter`'s own doc comment). */
+export declare const MAIL_LIST_FILTERS: {
+    value: MessageListFilter;
+    label: string;
+}[];
+/** The Focused Inbox half of the filter vocabulary, which the list also surfaces as its own tab row. */
+export declare const MAIL_LIST_CLASSIFICATION_FILTERS: {
+    value: MessageListFilter;
+    label: string;
+}[];
+/** What "ascending"/"descending" actually mean for each sort key, since "Newest on top" and "A to Z" are
+ * the same `desc`/`asc` pair wearing different words - mirrors Outlook's own per-field order labels. */
+export declare const SORT_ORDER_LABELS: Record<MessageListSort, {
+    desc: string;
+    asc: string;
+}>;
+/**
+ * The sort keys a *conversation* row can't be ordered by, and the reason the Sort menu shows beside each of
+ * them while the list is grouped into conversations.
+ *
+ * `GET /mail/messages/conversations` takes no `sortBy`/`sortOrder` at all - it returns one summary per
+ * thread, newest activity first - so every key here is applied to the rows this client has actually fetched
+ * (see `sortConversations()`). These two can't be applied even that far: a `ConversationSummary` describes
+ * a thread, and a thread has neither a sent date nor an importance - those belong to one message of it.
+ */
+export declare const CONVERSATION_SORT_UNAVAILABLE: Partial<Record<MessageListSort, string>>;
+/** The keys `sortConversations()` can actually order conversation rows by - `MAIL_LIST_SORTS` minus
+ * `CONVERSATION_SORT_UNAVAILABLE`'s. */
+export declare const CONVERSATION_SORTS: MessageListSort[];
+/** What the Sort menu says under its keys while conversations are shown - the honest scope of the ordering
+ * below, since the endpoint pages by latest activity and only the rows already fetched can be reordered. */
+export declare const CONVERSATION_SORT_NOTE = "Conversations are ordered within the rows loaded so far - the server pages them by latest activity.";
+/**
+ * Orders conversation rows by the arrangement the reader picked, as far as a `ConversationSummary` allows:
+ * the endpoint itself takes no sort parameters, so this reorders the rows already fetched rather than the
+ * folder (see `CONVERSATION_SORT_NOTE`, which says so on screen).
+ *
+ * A key the summaries carry no value for (see `CONVERSATION_SORT_UNAVAILABLE`, greyed out in the menu) is
+ * left alone, so the rows keep the server's own latest-activity order rather than being shuffled into an
+ * order that would mean nothing. Ties break newest first whichever direction is in force, so two rows the
+ * key can't tell apart still read in a stable, familiar order.
+ */
+export declare function sortConversations(conversations: ConversationSummary[], sortBy: MessageListSort, sortOrder: MessageSortOrder): ConversationSummary[];
+/** The direction the server itself would pick for a key if none were sent (see `MessageSortOrder`) - what
+ * this list switches to when the reader picks a different field, so changing "Date" to "Subject" reads A-Z
+ * rather than inheriting Date's newest-first as a surprising Z-A. */
+export declare function defaultSortOrder(sortBy: MessageListSort): MessageSortOrder;
+/** Reads one mailbox's stored preferences, merging them over the defaults field by field so an unknown or
+ * missing field falls back on its own rather than discarding the whole record. */
+export declare function getMailListPreferences(mailboxUid: string): MailListPreferences;
+/** Persists one mailbox's preferences. Best-effort - see this module's own doc comment. */
+export declare function setMailListPreferences(mailboxUid: string, preferences: MailListPreferences): void;

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

@@ -0,0 +1,186 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The mail list's own per-mailbox view preferences - what the Sort and Filter menus and the "Show as
+ * conversations" toggle are currently set to - persisted in `localStorage` so reopening the app lands on
+ * the arrangement the reader left it in, the way Outlook remembers its own per-folder arrangement.
+ *
+ * Per device, not synced to the server: this is the same posture `localIndexSizePreference.ts` and
+ * react-shared's `idleTimeout.ts` already take, and there is no server-side "mail view settings" record to
+ * write to. Keyed by mailbox because a shared mailbox someone triages ("unread only, oldest on top") is a
+ * genuinely different working set from their own inbox.
+ *
+ * Every read falls back to `DEFAULT_MAIL_LIST_PREFERENCES` for a never-configured mailbox, a corrupted or
+ * partially-unknown stored value, or a `localStorage` access that throws (private-browsing/storage-blocked
+ * contexts) - and every write swallows its own failure, so a blocked store only means the preference
+ * doesn't survive a reload.
+ */
+import { MAX_MESSAGE_LABEL_FILTER, } from "@rapidmx/react-shared/mail/mailApi.js";
+const STORAGE_KEY_PREFIX = "rapidmx:mail-list-preferences:";
+/** How many labels the list may be narrowed to at once. `@rapidmx/restapi` refuses a longer `?labelUids=`
+ * with a 400, so a stored selection is trimmed to the cap rather than sent. */
+export const MAX_LABEL_FILTER_UIDS = MAX_MESSAGE_LABEL_FILTER;
+/**
+ * What a mailbox nobody has configured yet opens on: newest received first, no label filter, and - like
+ * Outlook's own out-of-the-box arrangement - the Focused half of the Inbox, shown as conversations.
+ *
+ * Neither of those last two is `listMessages()`'s own default (`all`, and the flat list): they are this
+ * client's opinion about what a first-time reader should see, applied only where nothing has been stored
+ * (see `getMailListPreferences()`, which keeps a stored `false`/`all` exactly as it was). `focused` also
+ * only ever applies in an Inbox - every other folder falls back to `all` in `apps/www/index.tsx`, which is
+ * what `MessageListFilter`'s own "Inbox-only concept" note requires.
+ */
+export const DEFAULT_MAIL_LIST_PREFERENCES = {
+    sortBy: "date",
+    sortOrder: "desc",
+    filter: "focused",
+    labelUids: [],
+    showAsConversations: true,
+};
+/** Every sort key the server accepts, with the label the Sort menu shows for it - the order here is the
+ * order the menu lists them in. */
+export const MAIL_LIST_SORTS = [
+    { value: "date", label: "Date" },
+    { value: "sentDate", label: "Date sent" },
+    { value: "from", label: "From" },
+    { value: "subject", label: "Subject" },
+    { value: "importance", label: "Importance" },
+    { value: "flagged", label: "Flag status" },
+];
+/** Every named filter the server accepts, minus the Focused/Other pair (which the menu groups separately,
+ * and only offers in an Inbox - see `MessageListFilter`'s own doc comment). */
+export const MAIL_LIST_FILTERS = [
+    { value: "all", label: "All" },
+    { value: "unread", label: "Unread" },
+    { value: "read", label: "Read" },
+    { value: "flagged", label: "Flagged" },
+    { value: "hasAttachments", label: "Has attachments" },
+];
+/** The Focused Inbox half of the filter vocabulary, which the list also surfaces as its own tab row. */
+export const MAIL_LIST_CLASSIFICATION_FILTERS = [
+    { value: "focused", label: "Focused" },
+    { value: "other", label: "Other" },
+];
+/** What "ascending"/"descending" actually mean for each sort key, since "Newest on top" and "A to Z" are
+ * the same `desc`/`asc` pair wearing different words - mirrors Outlook's own per-field order labels. */
+export const SORT_ORDER_LABELS = {
+    date: { desc: "Newest on top", asc: "Oldest on top" },
+    sentDate: { desc: "Newest on top", asc: "Oldest on top" },
+    from: { asc: "A to Z", desc: "Z to A" },
+    subject: { asc: "A to Z", desc: "Z to A" },
+    importance: { desc: "Highest on top", asc: "Lowest on top" },
+    flagged: { desc: "Flagged on top", asc: "Unflagged on top" },
+};
+/**
+ * The sort keys a *conversation* row can't be ordered by, and the reason the Sort menu shows beside each of
+ * them while the list is grouped into conversations.
+ *
+ * `GET /mail/messages/conversations` takes no `sortBy`/`sortOrder` at all - it returns one summary per
+ * thread, newest activity first - so every key here is applied to the rows this client has actually fetched
+ * (see `sortConversations()`). These two can't be applied even that far: a `ConversationSummary` describes
+ * a thread, and a thread has neither a sent date nor an importance - those belong to one message of it.
+ */
+export const CONVERSATION_SORT_UNAVAILABLE = {
+    sentDate: "A thread has no sent date",
+    importance: "A thread has no importance",
+};
+/** The keys `sortConversations()` can actually order conversation rows by - `MAIL_LIST_SORTS` minus
+ * `CONVERSATION_SORT_UNAVAILABLE`'s. */
+export const CONVERSATION_SORTS = MAIL_LIST_SORTS.map((entry) => entry.value).filter((value) => !(value in CONVERSATION_SORT_UNAVAILABLE));
+/** What the Sort menu says under its keys while conversations are shown - the honest scope of the ordering
+ * below, since the endpoint pages by latest activity and only the rows already fetched can be reordered. */
+export const CONVERSATION_SORT_NOTE = "Conversations are ordered within the rows loaded so far - the server pages them by latest activity.";
+/** The name a conversation row is ordered by for "From": the latest message's sender, which is also the one
+ * whose subject, preview and date the row shows. */
+function latestSenderName(conversation) {
+    return conversation.latestFrom.displayName || conversation.latestFrom.address;
+}
+/** One conversation row against another on `sortBy`, ascending. */
+function compareConversations(a, b, sortBy) {
+    switch (sortBy) {
+        case "from":
+            return latestSenderName(a).localeCompare(latestSenderName(b), undefined, { sensitivity: "base" });
+        case "subject":
+            return a.subject.localeCompare(b.subject, undefined, { sensitivity: "base" });
+        case "flagged":
+            return Number(a.flagged) - Number(b.flagged);
+        default:
+            // `date` - the thread's latest activity, which is what the row itself shows.
+            return Date.parse(a.latestDate) - Date.parse(b.latestDate);
+    }
+}
+/**
+ * Orders conversation rows by the arrangement the reader picked, as far as a `ConversationSummary` allows:
+ * the endpoint itself takes no sort parameters, so this reorders the rows already fetched rather than the
+ * folder (see `CONVERSATION_SORT_NOTE`, which says so on screen).
+ *
+ * A key the summaries carry no value for (see `CONVERSATION_SORT_UNAVAILABLE`, greyed out in the menu) is
+ * left alone, so the rows keep the server's own latest-activity order rather than being shuffled into an
+ * order that would mean nothing. Ties break newest first whichever direction is in force, so two rows the
+ * key can't tell apart still read in a stable, familiar order.
+ */
+export function sortConversations(conversations, sortBy, sortOrder) {
+    if (!CONVERSATION_SORTS.includes(sortBy)) {
+        return conversations;
+    }
+    const direction = sortOrder === "asc" ? 1 : -1;
+    return [...conversations].sort((a, b) => {
+        const primary = direction * compareConversations(a, b, sortBy);
+        return primary !== 0 ? primary : Date.parse(b.latestDate) - Date.parse(a.latestDate);
+    });
+}
+/** The direction the server itself would pick for a key if none were sent (see `MessageSortOrder`) - what
+ * this list switches to when the reader picks a different field, so changing "Date" to "Subject" reads A-Z
+ * rather than inheriting Date's newest-first as a surprising Z-A. */
+export function defaultSortOrder(sortBy) {
+    return sortBy === "from" || sortBy === "subject" ? "asc" : "desc";
+}
+function isKnown(value, known) {
+    return known.some((entry) => entry.value === value);
+}
+/** Reads one mailbox's stored preferences, merging them over the defaults field by field so an unknown or
+ * missing field falls back on its own rather than discarding the whole record. */
+export function getMailListPreferences(mailboxUid) {
+    let stored;
+    try {
+        const raw = localStorage.getItem(`${STORAGE_KEY_PREFIX}${mailboxUid}`);
+        stored = raw === null ? null : JSON.parse(raw);
+    }
+    catch {
+        return DEFAULT_MAIL_LIST_PREFERENCES;
+    }
+    if (!stored || typeof stored !== "object") {
+        return DEFAULT_MAIL_LIST_PREFERENCES;
+    }
+    const record = stored;
+    const sortBy = isKnown(record.sortBy, MAIL_LIST_SORTS) ? record.sortBy : DEFAULT_MAIL_LIST_PREFERENCES.sortBy;
+    const filter = isKnown(record.filter, MAIL_LIST_FILTERS) || isKnown(record.filter, MAIL_LIST_CLASSIFICATION_FILTERS)
+        ? record.filter
+        : DEFAULT_MAIL_LIST_PREFERENCES.filter;
+    return {
+        sortBy,
+        sortOrder: record.sortOrder === "asc" || record.sortOrder === "desc" ? record.sortOrder : defaultSortOrder(sortBy),
+        filter,
+        labelUids: Array.isArray(record.labelUids)
+            ? record.labelUids.filter((uid) => typeof uid === "string").slice(0, MAX_LABEL_FILTER_UIDS)
+            : [],
+        // A stored `false` is a choice this reader made and is honoured; anything else (a record written
+        // before this field existed, or a corrupted value) falls back to the default like every other
+        // field here - which is what makes "Show as conversations" on by default only for a mailbox that
+        // has never been arranged.
+        showAsConversations: typeof record.showAsConversations === "boolean"
+            ? record.showAsConversations
+            : DEFAULT_MAIL_LIST_PREFERENCES.showAsConversations,
+    };
+}
+/** Persists one mailbox's preferences. Best-effort - see this module's own doc comment. */
+export function setMailListPreferences(mailboxUid, preferences) {
+    try {
+        localStorage.setItem(`${STORAGE_KEY_PREFIX}${mailboxUid}`, JSON.stringify(preferences));
+    }
+    catch {
+        // Best-effort - see this module's own doc comment.
+    }
+}