@rapidmx/web-client 0.6.0 → 0.7.0

package/apps/shared/components/mail/compose/RecipientInput.tsx

@@ -0,0 +1,356 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { ChangeEvent, KeyboardEvent, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { HiOutlineXMark } from "react-icons/hi2";
+import {
+    fetchRecipientSuggestions,
+    RECIPIENT_SUGGESTION_MIN_QUERY_LENGTH,
+    type ContactSuggestionOptions,
+    type RecipientSuggestion,
+    type RecipientSuggestionKind,
+} 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: Record<RecipientSuggestionKind, string> = {
+    contact: "Contact",
+    user: "Person",
+    shared: "Shared mailbox",
+    room: "Room",
+    equipment: "Equipment",
+    list: "Group",
+};
+
+export interface RecipientInputProps {
+    /** The input's id, which the field's `<label htmlFor>` names. Also prefixes the listbox and option ids. */
+    id: string;
+    /** The field's name ("To", "Cc", "Bcc"), used in the recipient list's and suggestions' accessible names. */
+    label: string;
+    /** The field's text: recipients separated by commas, as `parseRecipientList()` reads it. */
+    value: string;
+    onChange: (value: string) => void;
+    /** Called with the field's text when focus leaves the input. */
+    onBlur?: (value: string) => void;
+    /** Called with the field's text after a suggestion is picked (focus stays in the input). */
+    onCommit?: (value: string) => void;
+    /** The mailbox being composed from, whose contacts are suggested too. */
+    mailboxUid?: string;
+    /** Loads suggestions; defaults to react-shared's `fetchRecipientSuggestions()`. */
+    fetchSuggestions?: (query: string, options: ContactSuggestionOptions) => Promise<RecipientSuggestion[]>;
+    debounceMs?: number;
+    disabled?: boolean;
+    /** Focuses the input when it mounts - a new message starts in To. */
+    autoFocus?: boolean;
+}
+
+interface DropdownPosition {
+    left: number;
+    width: number;
+    top?: number;
+    bottom?: number;
+    maxHeight: number;
+}
+
+/** 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: HTMLElement): DropdownPosition {
+    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,
+}: RecipientInputProps) {
+    const [pending, setPending] = useState("");
+    const [suggestions, setSuggestions] = useState<RecipientSuggestion[]>([]);
+    const [open, setOpen] = useState(false);
+    const [activeIndex, setActiveIndex] = useState(0);
+    const [position, setPosition] = useState<DropdownPosition | null>(null);
+    const anchorRef = useRef<HTMLDivElement>(null);
+    const inputRef = useRef<HTMLInputElement>(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: number) => `${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: string[], nextPending: string) {
+        onChange([...nextChips, nextPending.trim()].filter((part) => part.length > 0).join(", "));
+    }
+
+    function handleInputChange(e: ChangeEvent<HTMLInputElement>) {
+        const { finished, rest } = splitTypedRecipients(e.target.value);
+        const nextPending = rest.replace(/^\s+/, "");
+        setPending(nextPending);
+        setOpen(true);
+        emit([...chips, ...finished], nextPending);
+    }
+
+    function commitPending(): string {
+        const next = [...chips, pendingText].filter((part) => part.length > 0).join(", ");
+        setPending("");
+        setOpen(false);
+        return next;
+    }
+
+    function select(suggestion: RecipientSuggestion) {
+        const next = [...chips, formatRecipient({ address: suggestion.address, displayName: suggestion.displayName || undefined })].join(", ");
+        setPending("");
+        setOpen(false);
+        setSuggestions([]);
+        onChange(next);
+        onCommit?.(next);
+    }
+
+    function removeChip(index: number) {
+        emit(
+            chips.filter((_, i) => i !== index),
+            inputValue,
+        );
+        inputRef.current?.focus();
+    }
+
+    function handleKeyDown(e: KeyboardEvent<HTMLInputElement>) {
+        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 (
+        <div ref={anchorRef} className="flex-1 min-w-0 flex flex-wrap items-center gap-1">
+            {chips.length > 0 && (
+                <ul role="list" aria-label={`${label} recipients`} className="contents">
+                    {chips.map((chip, index) => {
+                        const recipient = parseRecipient(chip);
+                        const valid = isValidRecipientAddress(recipient.address);
+                        const name = recipient.displayName || recipient.address;
+                        return (
+                            <li
+                                key={`${index}-${chip}`}
+                                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"
+                                }`}
+                            >
+                                <span className="truncate">{name}</span>
+                                {!valid && <span className="sr-only"> (not a valid email address)</span>}
+                                <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"
+                                >
+                                    <HiOutlineXMark size={10} />
+                                </button>
+                            </li>
+                        );
+                    })}
+                </ul>
+            )}
+            <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}
+            />
+            <span className="sr-only" aria-live="polite">
+                {expanded ? `${visible.length} ${visible.length === 1 ? "suggestion" : "suggestions"}` : ""}
+            </span>
+            {expanded &&
+                position &&
+                createPortal(
+                    <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"
+                    >
+                        {visible.map((suggestion, index) => (
+                            <li
+                                key={`${index}-${suggestion.address}`}
+                                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" : ""}`}
+                            >
+                                <span className="flex-1 min-w-0">
+                                    <span className="block truncate text-sm text-text">{suggestion.displayName || suggestion.address}</span>
+                                    {suggestion.displayName && <span className="block truncate text-xs text-text-muted">{suggestion.address}</span>}
+                                </span>
+                                <span className="shrink-0 text-[11px] leading-4 px-1.5 rounded-pill bg-surface-alt text-text-muted">
+                                    {KIND_LABELS[suggestion.kind] ?? "Directory"}
+                                </span>
+                            </li>
+                        ))}
+                    </ul>,
+                    document.body,
+                )}
+        </div>
+    );
+}

package/apps/shared/components/mail/compose/RichTextEditor.tsx

@@ -2,7 +2,7 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import React, { useRef } from "react";
+import React, { useRef, useState } from "react";
 import { EditorContent, useEditor } from "@tiptap/react";
 import StarterKit from "@tiptap/starter-kit";
 import { TextStyleKit } from "@tiptap/extension-text-style";
@@ -23,6 +23,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;
 }
 
 /**
@@ -46,9 +55,24 @@ 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 = "360px", fill = false, onUploadImage }: RichTextEditorProps) {
+export default function RichTextEditor({
+    value,
+    onChange,
+    height = "360px",
+    fill = false,
+    onUploadImage,
+    autoFocusStart = false,
+    onInitialized,
+}: RichTextEditorProps) {
     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<"start" | false>(autoFocusStart ? "start" : false);
 
     const editor = useEditor({
         extensions: [
@@ -61,8 +85,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 (

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

@@ -0,0 +1,100 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { apiUrl } from "@rapidmx/react-shared/util/api.js";
+import { Message, Recipient, getMessageRawContent } 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";
+import { decodeHeaderText, extractDisplayBody, parseMimeEntity } from "@rapidmx/react-shared/crypto/mime.js";
+import { parseRecipientList } from "./recipients.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[];
+}
+
+/** The recipients one address-list header names, RFC 2047-decoded, with their display names. */
+function headerRecipients(value: string | undefined, type: "to" | "cc"): Recipient[] {
+    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: Message,
+    security: MessageSecurityResult | null,
+    options: { recipients?: boolean } = {},
+): Promise<OriginalMessage> {
+    const recovered: QuotedBody | undefined =
+        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: OriginalMessage = { 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/apps/shared/components/mail/compose/recipients.ts

@@ -0,0 +1,104 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * 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";
+
+/** 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: string): string[] {
+    const parts: string[] = [];
+    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: string): string[] {
+    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: string): { finished: string[]; rest: string } {
+    const parts = splitRaw(text);
+    const rest = parts.pop()!;
+    return { finished: parts.map((part) => part.trim()).filter((part) => part.length > 0), rest };
+}
+
+function unquote(name: string): string {
+    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: string): ComposeRecipientInput {
+    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: string): ComposeRecipientInput[] {
+    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: ComposeRecipientInput): string {
+    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: string): boolean {
+    return ADDRESS_PATTERN.test(address);
+}