@rapidmx/web-client 0.6.0 → 0.7.0

package/dist/apps/shared/components/mail/compose/RecipientInput.js

@@ -0,0 +1,203 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { HiOutlineXMark } from "react-icons/hi2";
+import { fetchRecipientSuggestions, RECIPIENT_SUGGESTION_MIN_QUERY_LENGTH, } from "@rapidmx/react-shared/mail/directoryApi.js";
+import { formatRecipient, isValidRecipientAddress, parseRecipient, splitRecipientList, splitTypedRecipients } from "./recipients.js";
+/** How long typing must pause before suggestions are requested. */
+export const RECIPIENT_SUGGESTION_DEBOUNCE_MS = 150;
+const KIND_LABELS = {
+    contact: "Contact",
+    user: "Person",
+    shared: "Shared mailbox",
+    room: "Room",
+    equipment: "Equipment",
+    list: "Group",
+};
+/** Where the suggestions go: under the field (or above it when there's much more room there), as wide as the field. */
+function dropdownPosition(anchor) {
+    const rect = anchor.getBoundingClientRect();
+    const margin = 8;
+    const width = Math.min(Math.max(rect.width, 260), window.innerWidth - margin * 2);
+    const left = Math.min(Math.max(rect.left, margin), window.innerWidth - width - margin);
+    const below = window.innerHeight - rect.bottom - margin;
+    const above = rect.top - margin;
+    if (below < 160 && above > below) {
+        return { left, width, bottom: window.innerHeight - rect.top + 2, maxHeight: Math.min(320, above) };
+    }
+    return { left, width, top: rect.bottom + 2, maxHeight: Math.max(120, Math.min(320, below)) };
+}
+/**
+ * A To/Cc/Bcc field: committed recipients as removable chips, and a WAI-ARIA combobox for the one being typed that
+ * suggests the caller's contacts and the server directory (contacts first, one entry per address). The field's value is
+ * still plain text (recipients separated by commas), so drafts, autosave and sending read it as before.
+ *
+ * Typing a comma or semicolon (outside a quoted name or angle brackets), pressing Enter, or leaving the field turns the
+ * typed text into a chip; pasted lists split the same way. Suggestions load `debounceMs` after typing pauses, for at
+ * least two characters, and a newer query aborts an older request. Arrow keys move through them, Enter or Tab picks
+ * one (as `Name <address>`), Escape closes them, and Backspace in an empty input removes the last chip.
+ */
+export default function RecipientInput({ id, label, value, onChange, onBlur, onCommit, mailboxUid, fetchSuggestions = fetchRecipientSuggestions, debounceMs = RECIPIENT_SUGGESTION_DEBOUNCE_MS, disabled, autoFocus, }) {
+    const [pending, setPending] = useState("");
+    const [suggestions, setSuggestions] = useState([]);
+    const [open, setOpen] = useState(false);
+    const [activeIndex, setActiveIndex] = useState(0);
+    const [position, setPosition] = useState(null);
+    const anchorRef = useRef(null);
+    const inputRef = useRef(null);
+    const fetchRef = useRef(fetchSuggestions);
+    fetchRef.current = fetchSuggestions;
+    const tokens = splitRecipientList(value);
+    const pendingText = pending.trim();
+    // The typed text is the value's last recipient; a value changed from outside that doesn't end with it drops it.
+    const pendingActive = pendingText !== "" && tokens[tokens.length - 1] === pendingText;
+    const chips = pendingActive ? tokens.slice(0, -1) : tokens;
+    const inputValue = pendingActive ? pending : "";
+    const query = pendingActive ? pendingText : "";
+    const listboxId = `${id}-suggestions`;
+    const optionId = (index) => `${id}-suggestion-${index}`;
+    useEffect(() => {
+        if (pending !== "" && !pendingActive) {
+            setPending("");
+        }
+    }, [pending, pendingActive]);
+    const committedAddresses = new Set(chips.map((chip) => parseRecipient(chip).address.toLowerCase()));
+    const visible = suggestions.filter((suggestion) => !committedAddresses.has(suggestion.address.toLowerCase()));
+    const expanded = open && visible.length > 0 && query.length >= RECIPIENT_SUGGESTION_MIN_QUERY_LENGTH;
+    const active = Math.min(activeIndex, visible.length - 1);
+    useEffect(() => {
+        if (query.length < RECIPIENT_SUGGESTION_MIN_QUERY_LENGTH) {
+            setSuggestions([]);
+            return;
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => {
+            fetchRef.current(query, { mailboxUid, signal: controller.signal }).then((result) => {
+                if (!controller.signal.aborted) {
+                    setSuggestions(result);
+                    setActiveIndex(0);
+                }
+            }, () => {
+                if (!controller.signal.aborted) {
+                    setSuggestions([]);
+                }
+            });
+        }, debounceMs);
+        return () => {
+            clearTimeout(timer);
+            controller.abort();
+        };
+    }, [query, mailboxUid, debounceMs]);
+    useLayoutEffect(() => {
+        if (!expanded) {
+            return;
+        }
+        const anchor = anchorRef.current;
+        const update = () => setPosition(dropdownPosition(anchor));
+        update();
+        window.addEventListener("resize", update);
+        window.addEventListener("scroll", update, true);
+        return () => {
+            window.removeEventListener("resize", update);
+            window.removeEventListener("scroll", update, true);
+        };
+    }, [expanded]);
+    useEffect(() => {
+        if (expanded) {
+            document.getElementById(optionId(active))?.scrollIntoView?.({ block: "nearest" });
+        }
+    });
+    function emit(nextChips, nextPending) {
+        onChange([...nextChips, nextPending.trim()].filter((part) => part.length > 0).join(", "));
+    }
+    function handleInputChange(e) {
+        const { finished, rest } = splitTypedRecipients(e.target.value);
+        const nextPending = rest.replace(/^\s+/, "");
+        setPending(nextPending);
+        setOpen(true);
+        emit([...chips, ...finished], nextPending);
+    }
+    function commitPending() {
+        const next = [...chips, pendingText].filter((part) => part.length > 0).join(", ");
+        setPending("");
+        setOpen(false);
+        return next;
+    }
+    function select(suggestion) {
+        const next = [...chips, formatRecipient({ address: suggestion.address, displayName: suggestion.displayName || undefined })].join(", ");
+        setPending("");
+        setOpen(false);
+        setSuggestions([]);
+        onChange(next);
+        onCommit?.(next);
+    }
+    function removeChip(index) {
+        emit(chips.filter((_, i) => i !== index), inputValue);
+        inputRef.current?.focus();
+    }
+    function handleKeyDown(e) {
+        switch (e.key) {
+            case "ArrowDown":
+            case "ArrowUp": {
+                if (visible.length === 0) {
+                    return;
+                }
+                e.preventDefault();
+                if (!expanded) {
+                    setOpen(true);
+                    setActiveIndex(e.key === "ArrowDown" ? 0 : visible.length - 1);
+                    return;
+                }
+                const step = e.key === "ArrowDown" ? 1 : -1;
+                setActiveIndex((active + step + visible.length) % visible.length);
+                return;
+            }
+            case "Enter":
+                if (expanded) {
+                    e.preventDefault();
+                    select(visible[active]);
+                }
+                else if (pendingText) {
+                    e.preventDefault();
+                    const next = commitPending();
+                    onCommit?.(next);
+                }
+                return;
+            case "Tab":
+                if (expanded && !e.shiftKey) {
+                    e.preventDefault();
+                    select(visible[active]);
+                }
+                return;
+            case "Escape":
+                if (expanded) {
+                    e.preventDefault();
+                    e.stopPropagation();
+                    setOpen(false);
+                }
+                return;
+            case "Backspace":
+                if (inputValue === "" && chips.length > 0) {
+                    e.preventDefault();
+                    emit(chips.slice(0, -1), "");
+                }
+                return;
+        }
+    }
+    function handleBlur() {
+        const next = commitPending();
+        onBlur?.(next);
+    }
+    return (_jsxs("div", { ref: anchorRef, className: "flex-1 min-w-0 flex flex-wrap items-center gap-1", children: [chips.length > 0 && (_jsx("ul", { role: "list", "aria-label": `${label} recipients`, className: "contents", children: chips.map((chip, index) => {
+                    const recipient = parseRecipient(chip);
+                    const valid = isValidRecipientAddress(recipient.address);
+                    const name = recipient.displayName || recipient.address;
+                    return (_jsxs("li", { title: chip, className: `flex items-center gap-1 max-w-full min-w-0 rounded-pill border pl-2 pr-0.5 py-px text-xs ${valid ? "bg-surface-alt border-border text-text" : "bg-danger-bg border-danger text-danger"}`, children: [_jsx("span", { className: "truncate", children: name }), !valid && _jsx("span", { className: "sr-only", children: " (not a valid email address)" }), _jsx("button", { type: "button", tabIndex: -1, "aria-label": `Remove ${recipient.address}`, disabled: disabled, onMouseDown: (e) => e.preventDefault(), onClick: () => removeChip(index), className: "shrink-0 w-4 h-4 flex items-center justify-center rounded-pill text-text-muted hover:bg-border hover:text-text", children: _jsx(HiOutlineXMark, { size: 10 }) })] }, `${index}-${chip}`));
+                }) })), _jsx("input", { ref: inputRef, id: id, type: "text", role: "combobox", autoComplete: "off", "aria-autocomplete": "list", "aria-expanded": expanded, "aria-controls": listboxId, "aria-activedescendant": expanded ? optionId(active) : undefined, disabled: disabled, autoFocus: autoFocus, className: "flex-1 min-w-[6rem] text-sm bg-transparent outline-none py-0.5", value: inputValue, onChange: handleInputChange, onKeyDown: handleKeyDown, onBlur: handleBlur }), _jsx("span", { className: "sr-only", "aria-live": "polite", children: expanded ? `${visible.length} ${visible.length === 1 ? "suggestion" : "suggestions"}` : "" }), expanded &&
+                position &&
+                createPortal(_jsx("ul", { id: listboxId, role: "listbox", "aria-label": `${label} suggestions`, onMouseDown: (e) => e.preventDefault(), style: { position: "fixed", left: position.left, width: position.width, top: position.top, bottom: position.bottom, maxHeight: position.maxHeight }, className: "z-[60] overflow-y-auto bg-surface border border-border rounded-md shadow-modal py-1", children: visible.map((suggestion, index) => (_jsxs("li", { id: optionId(index), role: "option", "aria-selected": index === active, onMouseDown: (e) => e.preventDefault(), onMouseEnter: () => setActiveIndex(index), onClick: () => select(suggestion), className: `flex items-center gap-2 px-3 py-1.5 cursor-pointer ${index === active ? "bg-primary/10" : ""}`, children: [_jsxs("span", { className: "flex-1 min-w-0", children: [_jsx("span", { className: "block truncate text-sm text-text", children: suggestion.displayName || suggestion.address }), suggestion.displayName && _jsx("span", { className: "block truncate text-xs text-text-muted", children: suggestion.address })] }), _jsx("span", { className: "shrink-0 text-[11px] leading-4 px-1.5 rounded-pill bg-surface-alt text-text-muted", children: KIND_LABELS[suggestion.kind] ?? "Directory" })] }, `${index}-${suggestion.address}`))) }), document.body)] }));
+}

package/dist/apps/shared/components/mail/compose/RichTextEditor.d.ts

@@ -9,6 +9,15 @@ export interface RichTextEditorProps {
     fill?: boolean;
     /** Passed straight through to `ComposeToolbar` — see its own doc comment on this prop. */
     onUploadImage: (file: File) => Promise<string | null>;
+    /** Focuses the editor with the caret at the very start of the document once it mounts - a reply or forward, whose
+     * body starts with an empty paragraph above the signature and quote, so typing goes above them. Only read when
+     * the editor is created. */
+    autoFocusStart?: boolean;
+    /** Called once the editor is ready, with `value` as the editor itself serializes it: TipTap drops what its schema
+     * doesn't hold (e.g. a blockquote's `style`) and adds an empty paragraph after a trailing non-paragraph node (a
+     * quote). That normalization happens on the editor's first transaction - even one that only moves the caret -
+     * and isn't reported through `onChange`, so a caller can compare later edits against this instead of `value`. */
+    onInitialized?: (value: string) => void;
 }
 /**
  * A WYSIWYG rich-text editor for the Compose window's message body — replaces `MonacoHtmlEditor` (an HTML
@@ -31,4 +40,4 @@ export interface RichTextEditorProps {
  * sufficient here since TipTap (unlike Monaco) never touches the DOM at module-evaluation time, only when
  * an editor view actually mounts.
  */
-export default function RichTextEditor({ value, onChange, height, fill, onUploadImage }: RichTextEditorProps): React.JSX.Element;
+export default function RichTextEditor({ value, onChange, height, fill, onUploadImage, autoFocusStart, onInitialized, }: RichTextEditorProps): React.JSX.Element;

package/dist/apps/shared/components/mail/compose/RichTextEditor.js

@@ -3,7 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import { useRef } from "react";
+import { useRef, useState } from "react";
 import { EditorContent, useEditor } from "@tiptap/react";
 import StarterKit from "@tiptap/starter-kit";
 import { TextStyleKit } from "@tiptap/extension-text-style";
@@ -34,9 +34,16 @@ import ComposeToolbar from "./ComposeToolbar.js";
  * sufficient here since TipTap (unlike Monaco) never touches the DOM at module-evaluation time, only when
  * an editor view actually mounts.
  */
-export default function RichTextEditor({ value, onChange, height = "360px", fill = false, onUploadImage }) {
+export default function RichTextEditor({ value, onChange, height = "360px", fill = false, onUploadImage, autoFocusStart = false, onInitialized, }) {
     const onChangeRef = useRef(onChange);
     onChangeRef.current = onChange;
+    const onInitializedRef = useRef(onInitialized);
+    onInitializedRef.current = onInitialized;
+    // Transactions before `create` (the autofocus, and the normalizing one below) aren't edits.
+    const initializedRef = useRef(false);
+    // Held for this editor's lifetime: TipTap focuses a tick after creating the editor, and a re-render passing a
+    // different value in between would replace the option (via `setOptions`) before it's read.
+    const [autofocus] = useState(autoFocusStart ? "start" : false);
     const editor = useEditor({
         extensions: [
             StarterKit.configure({ link: { openOnClick: false } }),
@@ -48,8 +55,19 @@ export default function RichTextEditor({ value, onChange, height = "360px", fill
             Placeholder.configure({ placeholder: "Write your message…" }),
         ],
         content: value,
+        autofocus,
         immediatelyRender: false,
-        onUpdate: ({ editor: updated }) => onChangeRef.current(updated.getHTML()),
+        onCreate: ({ editor: created }) => {
+            // An empty transaction runs the schema's append-transaction normalization now, before any edit.
+            created.view.dispatch(created.state.tr);
+            initializedRef.current = true;
+            onInitializedRef.current?.(created.getHTML());
+        },
+        onUpdate: ({ editor: updated }) => {
+            if (initializedRef.current) {
+                onChangeRef.current(updated.getHTML());
+            }
+        },
     });
     return (_jsxs("div", { className: ["border border-border rounded-sm overflow-hidden", fill ? "h-full flex flex-col" : ""].filter(Boolean).join(" "), children: [_jsx(ComposeToolbar, { editor: editor, onUploadImage: onUploadImage }), _jsx(EditorContent, { editor: editor, style: fill ? undefined : { height }, className: [
                     "overflow-y-auto px-3 py-2 text-sm [&_.tiptap]:outline-none [&_.tiptap]:h-full",

package/dist/apps/shared/components/mail/compose/quotedBody.d.ts

@@ -0,0 +1,37 @@
+import { Message, Recipient } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { QuotedBody } from "@rapidmx/react-shared/mail/compose/composeQuoting.js";
+import type { MessageSecurityResult } from "@rapidmx/react-shared/crypto/messageSecurity.js";
+/** What a Reply/Reply All/Forward needs from the message being answered, beyond what its `Message` record holds. */
+export interface OriginalMessage {
+    /** The body to quote. Empty when none could be loaded - the quote builders then fall back to `bodyPreview`. */
+    body: QuotedBody;
+    /** The original To and Cc recipients, recovered from the message's own headers - `undefined` when they couldn't
+     * be. Only asked for by Reply All (see `loadOriginalMessage()`). */
+    recipients?: Recipient[];
+}
+/**
+ * Loads what a Reply/Reply All/Forward needs from `message`: the full body to quote - the same content
+ * `MessageDetailPane` shows, never the truncated `bodyPreview` unless nothing else can be had - and, with
+ * `options.recipients`, who the message was originally addressed to. Never rejects.
+ *
+ * Content the pane recovered client-side (`security.text`/`security.html`: a decrypted or verified body) is used as
+ * is. For an encrypted message that's the plaintext, so the caller must keep the reply encrypted (see
+ * `MessageDetailPane`'s reply handlers).
+ *
+ * An encrypted message without recovered content (locked keys, a failed decrypt, evaluation still running) quotes
+ * nothing: the server only holds ciphertext, which is never fetched or quoted.
+ *
+ * Otherwise the server's sanitized HTML body (`GET /mail/messages/:id/content`) is used. That route falls back to the
+ * preview for a message without an HTML part, so a `text/plain` answer is replaced by the text part of the message's
+ * raw MIME.
+ *
+ * The recipients come from the verified message's protected headers when it has them, else from the raw message's own
+ * `To`/`Cc` headers - restapi records only the envelope recipient of a delivered message (`ScanQueueJob`), so
+ * `message.recipients` alone would reduce every Reply All to a plain reply. Unprotected headers are the sender's own
+ * claim, exactly as in every other mail client's Reply All.
+ *
+ * The quote builders sanitize whatever HTML this returns (`sanitizeQuotedHtml()`), whichever source it came from.
+ */
+export declare function loadOriginalMessage(message: Message, security: MessageSecurityResult | null, options?: {
+    recipients?: boolean;
+}): Promise<OriginalMessage>;

package/dist/apps/shared/components/mail/compose/quotedBody.js

@@ -0,0 +1,85 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { apiUrl } from "@rapidmx/react-shared/util/api.js";
+import { getMessageRawContent } from "@rapidmx/react-shared/mail/mailApi.js";
+import { decodeHeaderText, extractDisplayBody, parseMimeEntity } from "@rapidmx/react-shared/crypto/mime.js";
+import { parseRecipientList } from "./recipients.js";
+/** The recipients one address-list header names, RFC 2047-decoded, with their display names. */
+function headerRecipients(value, type) {
+    if (!value) {
+        return [];
+    }
+    return parseRecipientList(decodeHeaderText(value))
+        .filter((recipient) => recipient.address.includes("@"))
+        .map((recipient) => ({ address: recipient.address, ...(recipient.displayName ? { displayName: recipient.displayName } : {}), type }));
+}
+/**
+ * Loads what a Reply/Reply All/Forward needs from `message`: the full body to quote - the same content
+ * `MessageDetailPane` shows, never the truncated `bodyPreview` unless nothing else can be had - and, with
+ * `options.recipients`, who the message was originally addressed to. Never rejects.
+ *
+ * Content the pane recovered client-side (`security.text`/`security.html`: a decrypted or verified body) is used as
+ * is. For an encrypted message that's the plaintext, so the caller must keep the reply encrypted (see
+ * `MessageDetailPane`'s reply handlers).
+ *
+ * An encrypted message without recovered content (locked keys, a failed decrypt, evaluation still running) quotes
+ * nothing: the server only holds ciphertext, which is never fetched or quoted.
+ *
+ * Otherwise the server's sanitized HTML body (`GET /mail/messages/:id/content`) is used. That route falls back to the
+ * preview for a message without an HTML part, so a `text/plain` answer is replaced by the text part of the message's
+ * raw MIME.
+ *
+ * The recipients come from the verified message's protected headers when it has them, else from the raw message's own
+ * `To`/`Cc` headers - restapi records only the envelope recipient of a delivered message (`ScanQueueJob`), so
+ * `message.recipients` alone would reduce every Reply All to a plain reply. Unprotected headers are the sender's own
+ * claim, exactly as in every other mail client's Reply All.
+ *
+ * The quote builders sanitize whatever HTML this returns (`sanitizeQuotedHtml()`), whichever source it came from.
+ */
+export async function loadOriginalMessage(message, security, options = {}) {
+    const recovered = security?.text !== undefined ? { text: security.text } : security?.html !== undefined ? { html: security.html } : undefined;
+    const protectedHeaders = security?.protectedHeaders;
+    const protectedRecipients = protectedHeaders
+        ? [...headerRecipients(protectedHeaders.to, "to"), ...headerRecipients(protectedHeaders.cc, "cc")]
+        : [];
+    const result = { body: recovered ?? {}, ...(protectedRecipients.length > 0 ? { recipients: protectedRecipients } : {}) };
+    if (message.encrypted) {
+        return result;
+    }
+    let needsRaw = !!options.recipients && result.recipients === undefined;
+    if (!recovered) {
+        try {
+            const res = await fetch(apiUrl(`/mail/messages/${encodeURIComponent(message.uid)}/content`), { credentials: "include" });
+            if (res.ok && (res.headers.get("content-type") ?? "").includes("text/html")) {
+                result.body = { html: await res.text() };
+            }
+            else {
+                needsRaw = true;
+            }
+        }
+        catch {
+            // The raw message below is the other way to the body.
+            needsRaw = true;
+        }
+    }
+    try {
+        if (needsRaw) {
+            const entity = parseMimeEntity(await getMessageRawContent(message.uid));
+            if (!recovered && result.body.html === undefined) {
+                const body = extractDisplayBody(entity);
+                result.body = body.html !== undefined ? { html: body.html } : body.text !== undefined ? { text: body.text } : {};
+            }
+            const headers = [...headerRecipients(entity.headers["to"], "to"), ...headerRecipients(entity.headers["cc"], "cc")];
+            if (options.recipients && result.recipients === undefined && headers.length > 0) {
+                result.recipients = headers;
+            }
+        }
+    }
+    catch {
+        // Whatever was loaded before the failure stands: the quote falls back to the preview, Reply All to the
+        // message's own recipients.
+    }
+    return result;
+}

package/dist/apps/shared/components/mail/compose/recipients.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Parsing and formatting of the To/Cc/Bcc fields' text. A field's value is a list of recipients separated by commas or
+ * semicolons, each either a bare address or `Display Name <address>` (the name optionally quoted, so it can hold a comma
+ * or semicolon itself). Separators inside quotes or angle brackets don't split.
+ */
+import type { ComposeRecipientInput } from "@rapidmx/react-shared/mail/mailApi.js";
+/** Splits a field's text into trimmed, non-empty recipient strings - see `splitRaw()`. */
+export declare function splitRecipientList(value: string): string[];
+/** Splits text typed into a field: the recipients finished by a separator, and the text after the last separator
+ * (untrimmed; the whole text when there is no separator). */
+export declare function splitTypedRecipients(text: string): {
+    finished: string[];
+    rest: string;
+};
+/** Parses one recipient string: `Name <address>`, `"Name" <address>`, `<address>` or a bare address. Anything else is
+ * kept whole as the address (so it's still sent, and flagged as invalid by the field). */
+export declare function parseRecipient(text: string): ComposeRecipientInput;
+/** Every recipient in a field's text. */
+export declare function parseRecipientList(value: string): ComposeRecipientInput[];
+/** Formats a recipient for a field: `Name <address>` (the name quoted when it holds a special character), or the bare
+ * address without a name. */
+export declare function formatRecipient(recipient: ComposeRecipientInput): string;
+/** Whether `address` looks like one plain email address. */
+export declare function isValidRecipientAddress(address: string): boolean;

package/dist/apps/shared/components/mail/compose/recipients.js

@@ -0,0 +1,87 @@
+/** One plain address: something, one `@`, something - no whitespace, brackets, quotes or separators. */
+const ADDRESS_PATTERN = /^[^\s@<>()",;]+@[^\s@<>()",;]+$/;
+/** Characters that make a display name need quoting. */
+const NAME_SPECIALS = /[",;<>@()\\]/;
+/** Splits at commas and semicolons outside quotes and angle brackets, keeping every part as is (empty ones too). An
+ * unterminated quote or bracket runs to the end of the text. */
+function splitRaw(value) {
+    const parts = [];
+    let current = "";
+    let quoted = false;
+    let bracketed = false;
+    for (let i = 0; i < value.length; i++) {
+        const ch = value[i];
+        if (quoted && ch === "\\" && i + 1 < value.length) {
+            current += ch + value[i + 1];
+            i++;
+            continue;
+        }
+        if (ch === '"' && !bracketed) {
+            quoted = !quoted;
+        }
+        else if (ch === "<" && !quoted) {
+            bracketed = true;
+        }
+        else if (ch === ">" && !quoted) {
+            bracketed = false;
+        }
+        else if ((ch === "," || ch === ";") && !quoted && !bracketed) {
+            parts.push(current);
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    parts.push(current);
+    return parts;
+}
+/** Splits a field's text into trimmed, non-empty recipient strings - see `splitRaw()`. */
+export function splitRecipientList(value) {
+    return splitRaw(value)
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+}
+/** Splits text typed into a field: the recipients finished by a separator, and the text after the last separator
+ * (untrimmed; the whole text when there is no separator). */
+export function splitTypedRecipients(text) {
+    const parts = splitRaw(text);
+    const rest = parts.pop();
+    return { finished: parts.map((part) => part.trim()).filter((part) => part.length > 0), rest };
+}
+function unquote(name) {
+    const trimmed = name.trim();
+    if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        return trimmed.slice(1, -1).replace(/\\(.)/g, "$1").trim();
+    }
+    return trimmed;
+}
+/** Parses one recipient string: `Name <address>`, `"Name" <address>`, `<address>` or a bare address. Anything else is
+ * kept whole as the address (so it's still sent, and flagged as invalid by the field). */
+export function parseRecipient(text) {
+    const trimmed = text.trim();
+    const match = /^(.*)<([^<>]*)>\s*$/.exec(trimmed);
+    if (match) {
+        const address = match[2].trim();
+        const displayName = unquote(match[1]);
+        return displayName ? { address, displayName } : { address };
+    }
+    return { address: trimmed };
+}
+/** Every recipient in a field's text. */
+export function parseRecipientList(value) {
+    return splitRecipientList(value).map(parseRecipient);
+}
+/** Formats a recipient for a field: `Name <address>` (the name quoted when it holds a special character), or the bare
+ * address without a name. */
+export function formatRecipient(recipient) {
+    const name = recipient.displayName?.trim();
+    if (!name) {
+        return recipient.address;
+    }
+    const safeName = NAME_SPECIALS.test(name) ? `"${name.replace(/(["\\])/g, "\\$1")}"` : name;
+    return `${safeName} <${recipient.address}>`;
+}
+/** Whether `address` looks like one plain email address. */
+export function isValidRecipientAddress(address) {
+    return ADDRESS_PATTERN.test(address);
+}

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;