@rapidmx/web-client 0.6.0 → 0.7.0

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;

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

@@ -0,0 +1,48 @@
+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 Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import LabelMenuButton from "./labelMenu.js";
+import MoveToFolderDialog, { MOVE_TARGET_TYPES } from "./MoveToFolderDialog.js";
+function actionClassName() {
+    return "px-2 py-1 rounded-md text-sm text-text hover:bg-surface-alt disabled:opacity-50 disabled:hover:bg-transparent";
+}
+/**
+ * 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, }) {
+    const selectedCount = totals?.selected ?? selected.length;
+    const listedCount = totals?.listed ?? listed.length;
+    // Counted on the rows that were ticked, but *emptied* on the messages: a ticked conversation whose
+    // messages are still being fetched has nothing for an action to act on yet.
+    const none = selectedCount === 0 || selected.length === 0;
+    const allSelected = listedCount > 0 && selectedCount === listedCount;
+    const currentType = folders.find((folder) => folder.uid === currentFolderUid)?.type;
+    const moveTargets = folders.filter((folder) => MOVE_TARGET_TYPES.has(folder.type) && folder.uid !== currentFolderUid);
+    // The same prompt the reading pane's own Move to opens, so one list of destinations and one way to
+    // create a folder serve both.
+    const [movePrompt, setMovePrompt] = useState(false);
+    // None of the three needs its folder to exist first - the caller creates or lazily provisions it (see
+    // `resolveFolderOfType()` and `bulkArchive()` in `apps/www/index.tsx`) - so the only thing that disables
+    // them is already being in the folder they would move to.
+    const archiveReason = currentType === "archive" ? "These messages are already in Archive" : undefined;
+    const junkReason = currentType === "junk" ? "These messages are already in Junk" : undefined;
+    const deleteReason = currentType === "deleted_items" ? "These messages are already in Deleted Items" : undefined;
+    // A label every selected message already carries starts ticked; one only some of them carry starts
+    // partially applied, and is left exactly as it is unless the reader touches that row.
+    const appliedToAll = labels.filter((label) => !none && selected.every((m) => m.labelUids?.includes(label.uid)));
+    const appliedToSome = labels.filter((label) => selected.some((m) => m.labelUids?.includes(label.uid)) && !appliedToAll.includes(label));
+    return (_jsxs("div", { className: "border-b border-border", children: [_jsx(MoveToFolderDialog, { open: movePrompt, onClose: () => setMovePrompt(false), mailboxUid: mailboxUid, folders: folders, currentFolderUid: currentFolderUid, count: selected.length, onMove: onMoveTo, onFolderCreated: onFolderCreated }), _jsxs("div", { className: "flex items-center gap-2 px-3 py-1.5 bg-surface-alt", children: [_jsxs("span", { "aria-live": "polite", className: "text-sm font-semibold text-text", children: [selectedCount, totals ? ` ${totals.noun}${selectedCount === 1 ? "" : "s"}` : "", " selected"] }), _jsx("button", { type: "button", onClick: onSelectAll, disabled: allSelected || listedCount === 0, className: actionClassName(), children: "Select all" }), _jsx("button", { type: "button", onClick: onClearSelection, disabled: selectedCount === 0, className: actionClassName(), children: "Clear" }), _jsx("button", { type: "button", onClick: onCancel, className: `${actionClassName()} ml-auto`, children: "Cancel" })] }), _jsxs("div", { className: "flex flex-wrap items-center gap-0.5 px-1.5 py-1", children: [_jsx("button", { type: "button", onClick: () => onSetRead(true), disabled: none || busy, className: actionClassName(), children: "Mark read" }), _jsx("button", { type: "button", onClick: () => onSetRead(false), disabled: none || busy, className: actionClassName(), children: "Mark unread" }), _jsx("button", { type: "button", onClick: () => onSetFlagged(true), disabled: none || busy, className: actionClassName(), children: "Flag" }), _jsx("button", { type: "button", onClick: () => onSetFlagged(false), disabled: none || busy, className: actionClassName(), children: "Unflag" }), _jsx("button", { type: "button", onClick: onArchive, disabled: none || busy || !!archiveReason, title: archiveReason, className: actionClassName(), children: "Archive" }), _jsx(LabelMenuButton, { "aria-label": "Apply label", label: "Apply label", className: "text-sm", labels: labels, mailboxUid: mailboxUid, onLabelCreated: onLabelCreated, applied: appliedToAll.map((label) => label.uid), partial: appliedToSome.map((label) => label.uid), onCommit: onApplyLabels, busy: busy, disabled: none || busy, note: selected.length === 1
+                            ? "Ticked labels are applied, unticked ones removed."
+                            : "Ticked labels are applied to every selected message and unticked ones removed from all of them; a dash means only some have that label, and leaving it alone keeps it that way.", emptyNote: "This mailbox has no labels yet.", commit: { label: "Apply" }, clear: { label: "Remove all labels" } }), _jsx("button", { type: "button", onClick: () => setMovePrompt(true), disabled: none || busy, className: actionClassName(), children: "Move to" }), _jsx("button", { type: "button", onClick: onReportJunk, disabled: none || busy || !!junkReason, title: junkReason, className: actionClassName(), children: "Report junk" }), _jsx("button", { type: "button", onClick: onDelete, disabled: none || busy || !!deleteReason, title: deleteReason, className: actionClassName(), children: "Delete" })] }), error && (_jsx("div", { className: "px-3 pb-2", children: _jsx(Alert, { children: error }) }))] }));
+}

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

@@ -0,0 +1,71 @@
+import React, { ReactNode } from "react";
+/** What every row has. `checked` turns it into a radio/checkbox item (the caller says which via `role`) and
+ * draws the checkmark column; without it the row is a plain command. */
+interface MenuItemBase {
+    key: string;
+    label: string;
+    /** A one-line explanation under the label, for an item whose effect isn't obvious from its name. */
+    description?: string;
+    role?: "menuitem" | "menuitemradio" | "menuitemcheckbox";
+    /** `"mixed"` is ARIA's third checkbox state - some of the things this row acts on have it and some
+     * don't, which is what a label applied to only part of a multi-message selection looks like. */
+    checked?: boolean | "mixed";
+    /** A colour swatch before the label - a label's own colour. */
+    swatchColor?: string;
+    disabled?: boolean;
+    /** Leaves the menu open after choosing this row, for a multi-select list where several rows are ticked
+     * before one command commits them all. */
+    keepOpen?: boolean;
+}
+/** A row that does something when chosen. */
+export interface MenuCommandSpec extends MenuItemBase {
+    onSelect: () => void;
+    submenu?: never;
+}
+/** A row that opens a submenu instead: choosing it replaces the menu's contents with these sections, under
+ * a Back row. One level deep, which is all any menu here needs - so it has nothing of its own to do. */
+export interface MenuSubmenuSpec extends MenuItemBase {
+    submenu: MenuSectionSpec[];
+    onSelect?: never;
+}
+export type MenuItemSpec = MenuCommandSpec | MenuSubmenuSpec;
+/** A labelled group of items. Groups after the first are drawn with a separator above them. */
+export interface MenuSectionSpec {
+    key: string;
+    label?: string;
+    /** A short note under the group's items - e.g. why some of them are unavailable right now. */
+    note?: string;
+    items: MenuItemSpec[];
+}
+/** The height `PopoverPortal` is asked for - exact for a short menu, capped (the list scrolls) for a long one. */
+export declare function menuHeight(sections: MenuSectionSpec[], width?: number): number;
+export interface MenuButtonProps {
+    /** The trigger's visible label. */
+    label: ReactNode;
+    /** The trigger's accessible name, which also names the menu itself - includes the current selection
+     * where there is one ("Filter: Unread"), so the button says what it's set to, not just what it does. */
+    "aria-label": string;
+    icon?: ReactNode;
+    disabled?: boolean;
+    title?: string;
+    sections: MenuSectionSpec[];
+    width?: number;
+    /** Extra classes for the trigger, on top of the shared toolbar-button styling. */
+    className?: string;
+    /** Told whenever the menu opens or closes - how a caller resets a draft it keeps for the menu's own
+     * multi-select rows (see `useLabelDraft()`). */
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * A toolbar button that opens an ARIA menu: `role="menu"` rows with checkmarks for the current choice,
+ * full keyboard support (Enter/Space or Arrow Down to open, arrows/Home/End to move with wrap, Enter/Space
+ * to choose, Escape or Tab to close with focus returning to the trigger) and a click outside to dismiss.
+ *
+ * Rendered through `PopoverPortal` rather than as an absolutely-positioned child: the mail list toolbar
+ * lives inside the list's own `overflow-y-auto` scroll container, which clips an absolute popup however
+ * high its `z-index` - the same reason Compose's own pickers portal out (see `PopoverPortal`'s own doc
+ * comment). The portal supplies the positioning, the outside-click dismissal and the box; the menu
+ * semantics, roving focus and keyboard handling are this component's own.
+ */
+export default function MenuButton({ label, icon, disabled, title, sections, width, className, "aria-label": ariaLabel, onOpenChange, }: MenuButtonProps): React.JSX.Element;
+export {};

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

@@ -0,0 +1,211 @@
+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 { useEffect, useRef, useState } from "react";
+import { HiCheck, HiChevronDown, HiChevronLeft, HiChevronRight, HiMinus } from "react-icons/hi2";
+import PopoverPortal from "@rapidmx/react-shared/components/overlays/PopoverPortal.js";
+// `PopoverPortal` positions a fixed-size box (it has no auto-height mode), so the menu's height is
+// computed from its own contents rather than measured - from whichever level is *shown*, so a submenu
+// isn't left standing in the parent menu's taller box. These are the exact heights the classes below
+// render at, so the box is never short enough to clip its last row: an item is `h-9`, a group label
+// `h-6`, a note as many `leading-4` lines as it wraps to, a separator a 1px rule inside `my-1`, and the
+// list itself `py-1`.
+const ITEM_HEIGHT = 36;
+const ITEM_DESCRIPTION_HEIGHT = 16;
+const GROUP_LABEL_HEIGHT = 24;
+const NOTE_LINE_HEIGHT = 16;
+const NOTE_PADDING = 4;
+/** A note wraps, so its height depends on how much of it fits a line: `text-xs` averages a little over 6px
+ * a character, and the note sits inside the list's `px-3`. Rounded so the estimate is never *under* the
+ * lines the browser actually draws - a box a few pixels too tall shows blank space, one too short clips. */
+const NOTE_CHAR_WIDTH = 6.4;
+const NOTE_PADDING_X = 24;
+const SEPARATOR_HEIGHT = 9;
+const LIST_PADDING = 8;
+const MENU_MAX_HEIGHT = 460;
+const DEFAULT_MENU_WIDTH = 248;
+/** How tall `note` renders at `width`, wrapped. */
+function noteHeight(note, width) {
+    const charsPerLine = Math.max(1, Math.floor((width - NOTE_PADDING_X) / NOTE_CHAR_WIDTH));
+    return Math.ceil(note.length / charsPerLine) * NOTE_LINE_HEIGHT + NOTE_PADDING;
+}
+/** The height `PopoverPortal` is asked for - exact for a short menu, capped (the list scrolls) for a long one. */
+export function menuHeight(sections, width = DEFAULT_MENU_WIDTH) {
+    let height = LIST_PADDING;
+    sections.forEach((section, index) => {
+        if (index > 0) {
+            height += SEPARATOR_HEIGHT;
+        }
+        if (section.label) {
+            height += GROUP_LABEL_HEIGHT;
+        }
+        for (const item of section.items) {
+            height += ITEM_HEIGHT + (item.description ? ITEM_DESCRIPTION_HEIGHT : 0);
+        }
+        if (section.note) {
+            height += noteHeight(section.note, width);
+        }
+    });
+    return Math.min(height, MENU_MAX_HEIGHT);
+}
+/**
+ * A toolbar button that opens an ARIA menu: `role="menu"` rows with checkmarks for the current choice,
+ * full keyboard support (Enter/Space or Arrow Down to open, arrows/Home/End to move with wrap, Enter/Space
+ * to choose, Escape or Tab to close with focus returning to the trigger) and a click outside to dismiss.
+ *
+ * Rendered through `PopoverPortal` rather than as an absolutely-positioned child: the mail list toolbar
+ * lives inside the list's own `overflow-y-auto` scroll container, which clips an absolute popup however
+ * high its `z-index` - the same reason Compose's own pickers portal out (see `PopoverPortal`'s own doc
+ * comment). The portal supplies the positioning, the outside-click dismissal and the box; the menu
+ * semantics, roving focus and keyboard handling are this component's own.
+ */
+export default function MenuButton({ label, icon, disabled, title, sections, width = DEFAULT_MENU_WIDTH, className = "", "aria-label": ariaLabel, onOpenChange, }) {
+    const [open, setOpen] = useState(false);
+    const [activeIndex, setActiveIndex] = useState(0);
+    // The key of the item whose submenu is showing, or `null` at the top level. Held as a key, not as the
+    // item itself, because `sections` is rebuilt on every render.
+    const [submenuKey, setSubmenuKey] = useState(null);
+    const triggerRef = useRef(null);
+    const itemRefs = useRef([]);
+    // State, not a ref: `PopoverPortal` renders nothing at all until its own positioning effect has run, so
+    // the rows don't exist yet when this component's effects first fire. Keying the focus effect on the
+    // menu node itself makes it run again once they do.
+    const [menuNode, setMenuNode] = useState(null);
+    const openSubmenu = sections
+        .flatMap((section) => section.items)
+        .find((item) => item.key === submenuKey && !!item.submenu);
+    /** The row that leaves a submenu again - synthesized rather than asked of the caller, so every submenu
+     * has the same way back however it was built. */
+    const backItem = {
+        key: "__back",
+        label: `Back to ${ariaLabel}`,
+        keepOpen: true,
+        onSelect: () => leaveSubmenu(),
+    };
+    const shownSections = openSubmenu
+        ? [{ key: "__back", items: [backItem] }, ...openSubmenu.submenu]
+        : sections;
+    const items = shownSections.flatMap((section) => section.items);
+    const enabledIndexes = items.map((item, index) => (item.disabled ? -1 : index)).filter((index) => index !== -1);
+    /** The row focus starts on: the current choice where there is one, else the first row that can take focus. */
+    function initialActiveIndex(within) {
+        const checked = within.findIndex((item) => item.checked === true && !item.disabled);
+        const enabled = within.map((item, index) => (item.disabled ? -1 : index)).filter((index) => index !== -1);
+        return checked === -1 ? (enabled[0] ?? 0) : checked;
+    }
+    function openMenu() {
+        setSubmenuKey(null);
+        setActiveIndex(initialActiveIndex(sections.flatMap((section) => section.items)));
+        setOpen(true);
+        onOpenChange?.(true);
+    }
+    function closeMenu(returnFocus) {
+        setOpen(false);
+        setSubmenuKey(null);
+        onOpenChange?.(false);
+        if (returnFocus) {
+            triggerRef.current?.focus();
+        }
+    }
+    function enterSubmenu(item) {
+        setSubmenuKey(item.key);
+        // Past the Back row, onto the first row of the submenu itself.
+        setActiveIndex(1 + initialActiveIndex(item.submenu.flatMap((section) => section.items)));
+    }
+    function leaveSubmenu() {
+        // Back on the row the submenu was opened from.
+        const parentIndex = sections.flatMap((section) => section.items).findIndex((item) => item.key === submenuKey);
+        setSubmenuKey(null);
+        setActiveIndex(parentIndex);
+    }
+    /** What a row does when it is chosen: open its submenu, or run it and close unless it asked to stay. */
+    function selectItem(item) {
+        if (item.submenu) {
+            enterSubmenu(item);
+            return;
+        }
+        item.onSelect();
+        if (!item.keepOpen) {
+            closeMenu(true);
+        }
+    }
+    // Roving focus: only the active row is tabbable, and it takes DOM focus whenever it changes, so the
+    // arrow keys move the screen reader's cursor too rather than only a visual highlight.
+    useEffect(() => {
+        if (open && menuNode) {
+            // A disabled row can't take focus, so a menu with nothing enabled focuses its own container -
+            // otherwise the keys it handles would go to whatever had focus before it opened.
+            if (enabledIndexes.length === 0) {
+                menuNode.focus();
+            }
+            else {
+                itemRefs.current[activeIndex]?.focus();
+            }
+        }
+        // `submenuKey` too: drilling in or out can land on the same index in the other level's list, and
+        // the row that index *means* is a different button, which the effect must move focus to.
+    }, [open, activeIndex, submenuKey, menuNode]);
+    function moveActive(delta) {
+        if (enabledIndexes.length === 0) {
+            return;
+        }
+        const position = enabledIndexes.indexOf(activeIndex);
+        setActiveIndex(enabledIndexes[(position + delta + enabledIndexes.length) % enabledIndexes.length]);
+    }
+    function handleMenuKeyDown(e) {
+        if (e.key === "ArrowDown") {
+            e.preventDefault();
+            moveActive(1);
+        }
+        else if (e.key === "ArrowUp") {
+            e.preventDefault();
+            moveActive(-1);
+        }
+        else if (e.key === "Home") {
+            e.preventDefault();
+            setActiveIndex(enabledIndexes[0] ?? 0);
+        }
+        else if (e.key === "End") {
+            e.preventDefault();
+            setActiveIndex(enabledIndexes[enabledIndexes.length - 1] ?? 0);
+        }
+        else if (e.key === "ArrowRight" && items[activeIndex]?.submenu) {
+            e.preventDefault();
+            enterSubmenu(items[activeIndex]);
+        }
+        else if ((e.key === "ArrowLeft" || e.key === "Escape") && openSubmenu) {
+            // ARIA's own submenu behaviour: Escape leaves the submenu for its parent menu rather than
+            // dismissing the whole thing.
+            e.preventDefault();
+            leaveSubmenu();
+        }
+        else if (e.key === "Escape" || e.key === "Tab") {
+            e.preventDefault();
+            closeMenu(true);
+        }
+    }
+    function handleTriggerKeyDown(e) {
+        if (!open && (e.key === "ArrowDown" || e.key === "ArrowUp")) {
+            e.preventDefault();
+            openMenu();
+        }
+    }
+    let itemIndex = -1;
+    return (_jsxs(_Fragment, { children: [_jsxs("button", { ref: triggerRef, type: "button", "aria-haspopup": "menu", "aria-expanded": open, "aria-label": ariaLabel, title: title, disabled: disabled, onClick: () => (open ? closeMenu(false) : openMenu()), onKeyDown: handleTriggerKeyDown, className: [
+                    // `min-w-0` so a long label ("Filter: Has attachments") truncates instead of pushing
+                    // whatever sits beside it in the toolbar off the edge of a 384px list column.
+                    "inline-flex min-w-0 items-center gap-1 px-2 py-1 rounded-md text-sm text-text hover:bg-surface-alt disabled:opacity-50 disabled:hover:bg-transparent",
+                    className,
+                ].join(" "), children: [icon, _jsx("span", { className: "truncate", children: label }), _jsx(HiChevronDown, { size: 14, "aria-hidden": "true", className: "shrink-0 text-text-muted" })] }), open && (_jsx(PopoverPortal, { anchorRef: triggerRef, onClose: () => closeMenu(false), width: width, height: menuHeight(shownSections, width), "aria-label": ariaLabel, children: _jsx("div", { ref: setMenuNode, role: "menu", tabIndex: -1, "aria-label": ariaLabel, onKeyDown: handleMenuKeyDown, className: "flex-1 overflow-y-auto py-1", children: shownSections.map((section, sectionIndex) => (_jsxs("div", { role: "group", "aria-label": section.label, className: sectionIndex > 0 ? "border-t border-border mt-1 pt-1" : "", children: [section.label && (_jsx("div", { "aria-hidden": "true", className: "h-6 flex items-center px-3 text-xs font-semibold uppercase tracking-wide text-text-muted", children: section.label })), section.items.map((item) => {
+                                itemIndex += 1;
+                                const index = itemIndex;
+                                const role = item.role ?? "menuitem";
+                                return (_jsxs("button", { ref: (node) => {
+                                        itemRefs.current[index] = node;
+                                    }, type: "button", role: role, disabled: item.disabled, tabIndex: index === activeIndex ? 0 : -1, ...(role === "menuitem"
+                                        ? {}
+                                        : { "aria-checked": item.checked === "mixed" ? "mixed" : !!item.checked }), ...(item.submenu ? { "aria-haspopup": "menu", "aria-expanded": false } : {}), onClick: () => selectItem(item), className: "w-full flex items-start gap-2 px-3 py-2 text-left text-sm text-text hover:bg-surface-alt disabled:opacity-50 disabled:hover:bg-transparent", children: [_jsxs("span", { className: "w-4 shrink-0 flex justify-center pt-0.5", children: [item.key === "__back" && (_jsx(HiChevronLeft, { size: 14, "aria-hidden": "true", className: "text-text-muted" })), item.checked === "mixed" ? (_jsx(HiMinus, { size: 14, "aria-hidden": "true", className: "text-primary-dark" })) : (item.checked && _jsx(HiCheck, { size: 14, "aria-hidden": "true", className: "text-primary-dark" }))] }), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsxs("span", { className: "flex h-5 items-center gap-1.5", children: [item.swatchColor && (_jsx("span", { "aria-hidden": "true", className: "w-2.5 h-2.5 rounded-full shrink-0", style: { backgroundColor: item.swatchColor } })), _jsx("span", { className: "truncate", children: item.label })] }), item.description && (_jsx("span", { className: "block h-4 text-xs leading-4 text-text-muted truncate font-normal", children: item.description }))] }), item.submenu && (_jsx(HiChevronRight, { size: 14, "aria-hidden": "true", className: "shrink-0 mt-0.5 text-text-muted" }))] }, item.key));
+                            }), section.note && _jsx("p", { className: "px-3 py-1 text-xs leading-4 text-text-muted", children: section.note })] }, section.key))) }) }))] }));
+}