@rapidmx/web-client 0.5.0 → 0.7.0

package/apps/shared/components/mail/labelMenu.tsx

@@ -0,0 +1,278 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { useState } from "react";
+import { HiOutlineTag } from "react-icons/hi2";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { Label, 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, { 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;
+}
+
+/** `a` and `b` hold the same uids, order ignored. */
+function sameUids(a: string[], b: string[]): boolean {
+    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: string[], partial: string[], open: boolean): LabelDraft {
+    const [state, setState] = useState<{ draft: string[]; mixed: string[] } | null>(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),
+    };
+}
+
+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 function labelSections({
+    labels,
+    state,
+    commit,
+    clear,
+    emptyNote,
+    note,
+    busy,
+    onCreate,
+    managePath = "/settings/labels",
+}: LabelSectionsOptions): MenuSectionSpec[] {
+    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" as const,
+                checked: state.mixed.includes(label.uid) ? ("mixed" as const) : 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,
+            ],
+        },
+    ];
+}
+
+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 function NewLabelDialog({ open, onClose, mailboxUid, onCreated }: NewLabelDialogProps) {
+    const [name, setName] = useState("");
+    const [saving, setSaving] = useState(false);
+    const [error, setError] = useState<string | null>(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 (
+        <Modal open={open} onClose={onClose} title="New label">
+            {error && <Alert>{error}</Alert>}
+            <FormField label="Name" htmlFor="new-label-name">
+                <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"
+                />
+            </FormField>
+            <div className="flex justify-end gap-2 mt-2">
+                <Button type="button" variant="secondary" className="!w-auto" onClick={onClose}>
+                    Cancel
+                </Button>
+                <Button type="button" className="!w-auto" loading={saving} disabled={saving || !name.trim()} onClick={() => void save()}>
+                    Create
+                </Button>
+            </div>
+        </Modal>
+    );
+}
+
+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) {
+    const [open, setOpen] = useState(false);
+    const [creating, setCreating] = useState(false);
+    const state = useLabelDraft(applied, partial, open);
+    return (
+        <>
+        <MenuButton
+            aria-label={ariaLabel}
+            label={label}
+            icon={<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 && (
+            <NewLabelDialog
+                open={creating}
+                onClose={() => setCreating(false)}
+                mailboxUid={mailboxUid}
+                onCreated={onLabelCreated}
+            />
+        )}
+        </>
+    );
+}

package/apps/shared/components/mail/layout/MailShell.tsx

@@ -2,7 +2,7 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import React, { createContext, PropsWithChildren, ReactNode, useContext, useEffect, useMemo, useState } from "react";
+import React, { createContext, PropsWithChildren, ReactNode, 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";
@@ -54,9 +54,21 @@ export interface MailShellContextValue {
     /** 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;
 }
 
-const MailShellContext = createContext<MailShellContextValue>({ mailboxes: [], mailboxFolders: [] });
+const MailShellContext = createContext<MailShellContextValue>({
+    mailboxes: [],
+    mailboxFolders: [],
+    onFolderCreated: () => undefined,
+});
 
 /** Reads the mailbox/folder a page is currently showing, as resolved by the enclosing `MailShell`. */
 export function useMailShell(): MailShellContextValue {
@@ -148,6 +160,7 @@ export default function MailShell({
     impersonating,
     impersonationBaseUrl,
     trusted,
+    pluginNav,
     children,
 }: PropsWithChildren<MailShellProps>) {
     const [status, setStatus] = useState<Status>("checking");
@@ -235,9 +248,22 @@ export default function MailShell({
     const defaultMailboxUid = mailboxes.find((mb) => mb.ownerUserUid === userUid)?.uid ?? mailboxes[0]?.uid;
     const activeMailboxUid = mailboxUid ?? defaultMailboxUid;
 
+    /** 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: 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<MailShellContextValue>(
-        () => ({ mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders }),
-        [mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders],
+        () => ({ 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
@@ -410,6 +436,7 @@ export default function MailShell({
                 impersonating={impersonating}
                 impersonationBaseUrl={impersonationBaseUrl}
                 trusted={trusted}
+                pluginNav={pluginNav}
             >
                 {inner}
             </AppShell>

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

@@ -0,0 +1,228 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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,
+    MessageListFilter,
+    MessageListSort,
+    MessageSortOrder,
+} from "@rapidmx/react-shared/mail/mailApi.js";
+import { ConversationSummary } from "@rapidmx/react-shared/mail/conversationsApi.js";
+
+const STORAGE_KEY_PREFIX = "rapidmx:mail-list-preferences:";
+
+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 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: MailListPreferences = {
+    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: MessageListSort; label: string }[] = [
+    { 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: MessageListFilter; label: string }[] = [
+    { 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: MessageListFilter; label: string }[] = [
+    { 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: Record<MessageListSort, { desc: string; asc: string }> = {
+    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: Partial<Record<MessageListSort, string>> = {
+    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: MessageListSort[] = 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: ConversationSummary): string {
+    return conversation.latestFrom.displayName || conversation.latestFrom.address;
+}
+
+/** One conversation row against another on `sortBy`, ascending. */
+function compareConversations(a: ConversationSummary, b: ConversationSummary, sortBy: MessageListSort): number {
+    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: ConversationSummary[],
+    sortBy: MessageListSort,
+    sortOrder: MessageSortOrder,
+): ConversationSummary[] {
+    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: MessageListSort): MessageSortOrder {
+    return sortBy === "from" || sortBy === "subject" ? "asc" : "desc";
+}
+
+function isKnown<T extends string>(value: unknown, known: readonly { value: T }[]): value is T {
+    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: string): MailListPreferences {
+    let stored: unknown;
+    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 as Record<string, unknown>;
+    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): uid is string => 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: string, preferences: MailListPreferences): void {
+    try {
+        localStorage.setItem(`${STORAGE_KEY_PREFIX}${mailboxUid}`, JSON.stringify(preferences));
+    } catch {
+        // Best-effort - see this module's own doc comment.
+    }
+}

package/apps/shared/components/settings/layout/SettingsShell.tsx

@@ -11,6 +11,7 @@ import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import Skeleton, { SkeletonList } from "@rapidmx/react-shared/components/feedback/Skeleton.js";
 import AppShell, { AppShellProps } from "../../layout/AppShell.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
+import { mergePluginNavItems, PluginNav } from "../../../plugins/pluginNav.js";
 
 export interface SettingsSectionDef {
     id: string;
@@ -24,18 +25,27 @@ export const SETTINGS_SECTIONS: SettingsSectionDef[] = [
     { id: "filters", href: "/settings/filters", label: "Mail Filters" },
     { id: "signatures", href: "/settings/signatures", label: "Signatures" },
     { id: "labels", href: "/settings/labels", label: "Labels" },
-    { id: "focused-inbox", href: "/settings/focused-inbox", label: "Focused Inbox" },
     { id: "read-receipts", href: "/settings/read-receipts", label: "Read Receipts" },
-    { id: "booking-types", href: "/settings/booking-types", label: "Booking Links" },
     { id: "encryption", href: "/settings/encryption", label: "Encryption" },
     { id: "sharing", href: "/settings/sharing", label: "Sharing" },
     { id: "privacy", href: "/settings/privacy", label: "Privacy & Data" },
 ];
 
-export type SettingsSectionId = (typeof SETTINGS_SECTIONS)[number]["id"];
+/** A `SETTINGS_SECTIONS` id, or a plugin's `settingsSections` item id (see `PluginNav`). */
+export type SettingsSectionId = string;
+
+/** `SETTINGS_SECTIONS` followed by the plugins' `settingsSections` items, core ids winning - see
+ * `mergePluginNavItems`. */
+export function settingsSections(pluginNav?: PluginNav): SettingsSectionDef[] {
+    return mergePluginNavItems<SettingsSectionDef>(SETTINGS_SECTIONS, pluginNav?.settingsSections, ({ id, href, label }) => ({
+        id,
+        href,
+        label,
+    }));
+}
 
 export interface SettingsShellProps extends Omit<AppShellProps, "active"> {
-    /** Which entry in `SETTINGS_SECTIONS` is highlighted in this shell's own sidebar — distinct from
+    /** Which entry in `SETTINGS_SECTIONS` (or plugin `settingsSections` item) is highlighted in this shell's own sidebar — distinct from
      * `AppShell`'s own `active` (always hardcoded to `"settings"` below), since Settings isn't a rail
      * icon (see `AppShell.tsx`'s `AppShellApp` doc comment) but still needs its own section
      * highlighting. Each settings page passes its own section id explicitly, the same "gotcha" this
@@ -74,6 +84,7 @@ export default function SettingsShell({
     impersonating,
     impersonationBaseUrl,
     trusted,
+    pluginNav,
     children,
 }: PropsWithChildren<SettingsShellProps>) {
     const [status, setStatus] = useState<Status>("checking");
@@ -130,6 +141,7 @@ export default function SettingsShell({
             </div>
         );
     } else if (userUid && status === "ready") {
+        const sections = settingsSections(pluginNav);
         // A function, not a plain JSX constant — same reasoning as ContactsShell's identical comment:
         // rendered twice (desktop `<aside>` + mobile `Drawer`), possibly simultaneously mounted, so the
         // `<select>`'s `id`/its `<label>`'s `htmlFor` need a distinct value per instance.
@@ -148,11 +160,11 @@ export default function SettingsShell({
                             className="w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface"
                             value={mailboxUid}
                             onChange={(e) => {
-                                // `active` always names a real entry in `SETTINGS_SECTIONS` — every settings
-                                // page passes its own section id explicitly (see `SettingsShellProps.active`'s
-                                // own doc comment), so this lookup can't miss.
-                                const section = SETTINGS_SECTIONS.find((s) => s.id === active)!;
-                                window.location.href = `${section.href}?mailboxUid=${encodeURIComponent(e.target.value)}`;
+                                // Every core settings page passes its own section id (see
+                                // `SettingsShellProps.active`), but a plugin page's section is missing when the
+                                // server didn't send its nav item, so that falls back to the current path.
+                                const href = sections.find((s) => s.id === active)?.href ?? window.location.pathname;
+                                window.location.href = `${href}?mailboxUid=${encodeURIComponent(e.target.value)}`;
                             }}
                         >
                             {mailboxes.map((mb) => (
@@ -165,7 +177,7 @@ export default function SettingsShell({
                     </div>
                 )}
                 <nav aria-label="Settings sections" className="flex flex-col gap-0.5">
-                    {SETTINGS_SECTIONS.map((section) => (
+                    {sections.map((section) => (
                         <a
                             key={section.id}
                             // `inner` (this whole branch) is only ever computed once `status === "ready"`
@@ -220,6 +232,7 @@ export default function SettingsShell({
             impersonating={impersonating}
             impersonationBaseUrl={impersonationBaseUrl}
             trusted={trusted}
+            pluginNav={pluginNav}
         >
             {inner}
         </AppShell>