@rapidmx/web-client 0.8.0 → 0.10.0

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

@@ -0,0 +1,111 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { useEffect } from "react";
+import { HiOutlineMinus, HiOutlineXMark } from "react-icons/hi2";
+import Skeleton from "@rapidmx/react-shared/components/feedback/Skeleton.js";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+import useIsMobile from "@rapidmx/react-shared/util/useIsMobile.js";
+import type { ComposeSession } from "./ComposeContext.js";
+import { markComposePhase } from "./composePerf.js";
+
+export interface ComposeWindowPlaceholderProps {
+    session: ComposeSession;
+    /** The compose window's code couldn't be downloaded. */
+    failed: boolean;
+    onRetry: () => void;
+    onClose: () => void;
+    onToggleMinimize: () => void;
+}
+
+/**
+ * What stands in for the compose window in the moment between clicking Compose/Reply/Forward and the window's code being
+ * loaded (already there when it was prefetched, so usually not seen at all): the window's own frame at its own size and
+ * place, its title and the recipients and subject the window will open with, all of which are known without the network -
+ * so the click is answered on the same frame. It is deliberately tiny and lives in the page's own chunk.
+ *
+ * Nothing here can be typed into yet, and there is no draft to save or discard, so Close just closes.
+ */
+export default function ComposeWindowPlaceholder({ session, failed, onRetry, onClose, onToggleMinimize }: ComposeWindowPlaceholderProps) {
+    const isMobile = useIsMobile();
+    const title = session.initialSubject?.trim() || "New Message";
+    const titleId = `compose-title-${session.id}`;
+
+    useEffect(() => markComposePhase(session.id, "shell"), [session.id]);
+
+    if (session.minimized) {
+        return (
+            <div role="dialog" aria-label={title} className="w-64 shrink-0 bg-surface border border-border border-b-0 rounded-t-md shadow-modal">
+                <div className="h-10 flex items-center justify-between gap-2 px-3 rounded-t-md bg-primary-darker text-white cursor-pointer" onClick={onToggleMinimize}>
+                    <span className="text-sm font-medium truncate">{title}</span>
+                </div>
+            </div>
+        );
+    }
+
+    return (
+        <div
+            role="dialog"
+            aria-labelledby={titleId}
+            aria-busy={!failed}
+            className={[
+                "relative shrink-0 flex flex-col bg-surface border border-border shadow-modal overflow-hidden",
+                isMobile ? "fixed inset-0 w-full h-full rounded-none border-0" : "border-b-0 rounded-t-md w-[480px] h-[520px]",
+            ].join(" ")}
+        >
+            <div className="h-10 shrink-0 flex items-center justify-between gap-2 px-3 bg-primary-darker text-white cursor-pointer" onClick={onToggleMinimize}>
+                <span id={titleId} className="text-sm font-medium truncate">
+                    {title}
+                </span>
+                <div className="flex items-center gap-0.5" onClick={(e) => e.stopPropagation()}>
+                    <button
+                        type="button"
+                        aria-label="Minimize"
+                        title="Minimize"
+                        onClick={onToggleMinimize}
+                        className="w-6 h-6 flex items-center justify-center rounded-sm text-white/80 hover:bg-white/15 hover:text-white"
+                    >
+                        <HiOutlineMinus size={14} />
+                    </button>
+                    <button
+                        type="button"
+                        aria-label="Close"
+                        title="Close"
+                        onClick={onClose}
+                        className="w-6 h-6 flex items-center justify-center rounded-sm text-white/80 hover:bg-white/15 hover:text-white"
+                    >
+                        <HiOutlineXMark size={14} />
+                    </button>
+                </div>
+            </div>
+            {failed ? (
+                <div className="px-3 pt-2">
+                    <Alert>
+                        <p className="mb-2">The compose window couldn&rsquo;t be loaded. Check your connection and try again.</p>
+                        <Button type="button" variant="secondary" className="!w-auto" onClick={onRetry}>
+                            Retry
+                        </Button>
+                    </Alert>
+                </div>
+            ) : (
+                <div role="status" className="flex-1 min-h-0 flex flex-col">
+                    <span className="sr-only">Opening the compose window</span>
+                    <div className="flex items-center gap-2 px-3 py-1.5 border-b border-border text-sm">
+                        <span className="text-text-muted">To</span>
+                        <span className="truncate">{session.initialTo}</span>
+                    </div>
+                    <div className="flex items-center gap-2 px-3 py-1.5 border-b border-border text-sm">
+                        <span className="truncate">{session.initialSubject || <span className="text-text-muted">Subject</span>}</span>
+                    </div>
+                    <div className="flex-1 p-3 flex flex-col gap-2" aria-hidden="true">
+                        <Skeleton height="h-4" />
+                        <Skeleton height="h-4" />
+                        <Skeleton height="h-4" />
+                    </div>
+                </div>
+            )}
+        </div>
+    );
+}

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

@@ -1,118 +1,147 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-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";
-import TextAlign from "@tiptap/extension-text-align";
-import Highlight from "@tiptap/extension-highlight";
-import Image from "@tiptap/extension-image";
-import { TableKit } from "@tiptap/extension-table";
-import Placeholder from "@tiptap/extension-placeholder";
-import ComposeToolbar from "./ComposeToolbar.js";
-
-export interface RichTextEditorProps {
-    value: string;
-    onChange: (value: string) => void;
-    height?: string;
-    /** When true, the editor fills its parent's height via flexbox instead of a fixed `height` — for
-     * embedding inside a flex-column container of variable height (the floating Compose window) where
-     * a literal pixel height can't be computed up front. `height` is ignored when this is set. */
-    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
- * *source* editor) with a real Outlook-Home-tab-style formatting experience, built on TipTap/ProseMirror.
- * Used by `ComposeWindow` (the floating overlay, not a dedicated page — see `ComposeContext.tsx`'s doc
- * comment).
- *
- * `value` seeds the editor's initial content only — like `MonacoHtmlEditor`, this never re-syncs from a
- * later `value` prop change; TipTap owns its own document once created. Live edits flow out as HTML (via
- * `editor.getHTML()`) through `onChange`.
- *
- * `immediatelyRender: false` is required for this framework's SSR: the page embedding `ComposeWindow` is
- * rendered server-side under plain Node before hydration (see `ReactRoute`), and TipTap's default
- * (`immediatelyRender: true`) tries to mount its ProseMirror view during that very first render, which
- * both can't work without a real DOM and produces a hydration mismatch. With it `false`, `useEditor`
- * returns `null` until the editor actually mounts client-side after hydration — `ComposeToolbar`/
- * `EditorContent` both already handle a `null` editor by rendering their disabled/empty state, so this
- * needs no extra loading-placeholder logic here. Unlike `MonacoHtmlEditor`, no dynamic `import()` is
- * needed to defer loading TipTap's modules off the SSR path — `immediatelyRender: false` alone is
- * 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,
-    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: [
-            StarterKit.configure({ link: { openOnClick: false } }),
-            TextStyleKit.configure({ backgroundColor: false, lineHeight: false }),
-            TextAlign.configure({ types: ["heading", "paragraph"] }),
-            Highlight,
-            Image,
-            TableKit.configure({ table: { resizable: true } }),
-            Placeholder.configure({ placeholder: "Write your message…" }),
-        ],
-        content: value,
-        autofocus,
-        immediatelyRender: false,
-        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 (
-        <div className={["border border-border rounded-sm overflow-hidden", fill ? "h-full flex flex-col" : ""].filter(Boolean).join(" ")}>
-            <ComposeToolbar editor={editor} onUploadImage={onUploadImage} />
-            <EditorContent
-                editor={editor}
-                style={fill ? undefined : { height }}
-                className={[
-                    "overflow-y-auto px-3 py-2 text-sm [&_.tiptap]:outline-none [&_.tiptap]:h-full",
-                    fill ? "flex-1 min-h-0" : "",
-                ]
-                    .filter(Boolean)
-                    .join(" ")}
-            />
-        </div>
-    );
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { useEffect, useRef, useState } from "react";
+import { EditorContent, useEditor } from "@tiptap/react";
+import StarterKit from "@tiptap/starter-kit";
+import { TextStyleKit } from "@tiptap/extension-text-style";
+import TextAlign from "@tiptap/extension-text-align";
+import Highlight from "@tiptap/extension-highlight";
+import Image from "@tiptap/extension-image";
+import { TableKit } from "@tiptap/extension-table";
+import Placeholder from "@tiptap/extension-placeholder";
+import ComposeToolbar from "./ComposeToolbar.js";
+
+export interface RichTextEditorProps {
+    value: string;
+    onChange: (value: string) => void;
+    height?: string;
+    /** When true, the editor fills its parent's height via flexbox instead of a fixed `height` — for
+     * embedding inside a flex-column container of variable height (the floating Compose window) where
+     * a literal pixel height can't be computed up front. `height` is ignored when this is set. */
+    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;
+    /**
+     * HTML to add at the end of the document, once, as soon as there is some (it may be undefined when the editor is created and
+     * defined later). A reply opens its editor before the quoted original has been fetched and hands the quote in through this when
+     * it arrives - so whatever has been typed above stays, and the quote lands where it always did, under the signature.
+     */
+    appendHtml?: string;
+    /** Called with the document as the editor serializes it, right after `appendHtml` was added. */
+    onAppended?: (value: string) => void;
+}
+
+/**
+ * A WYSIWYG rich-text editor for the Compose window's message body — replaces `MonacoHtmlEditor` (an HTML
+ * *source* editor) with a real Outlook-Home-tab-style formatting experience, built on TipTap/ProseMirror.
+ * Used by `ComposeWindow` (the floating overlay, not a dedicated page — see `ComposeContext.tsx`'s doc
+ * comment).
+ *
+ * `value` seeds the editor's initial content only — like `MonacoHtmlEditor`, this never re-syncs from a
+ * later `value` prop change; TipTap owns its own document once created. Live edits flow out as HTML (via
+ * `editor.getHTML()`) through `onChange`.
+ *
+ * `immediatelyRender: false` is required for this framework's SSR: the page embedding `ComposeWindow` is
+ * rendered server-side under plain Node before hydration (see `ReactRoute`), and TipTap's default
+ * (`immediatelyRender: true`) tries to mount its ProseMirror view during that very first render, which
+ * both can't work without a real DOM and produces a hydration mismatch. With it `false`, `useEditor`
+ * returns `null` until the editor actually mounts client-side after hydration — `ComposeToolbar`/
+ * `EditorContent` both already handle a `null` editor by rendering their disabled/empty state, so this
+ * needs no extra loading-placeholder logic here. Unlike `MonacoHtmlEditor`, no dynamic `import()` is
+ * needed to defer loading TipTap's modules off the SSR path — `immediatelyRender: false` alone is
+ * 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,
+    autoFocusStart = false,
+    onInitialized,
+    appendHtml,
+    onAppended,
+}: RichTextEditorProps) {
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
+    const onInitializedRef = useRef(onInitialized);
+    onInitializedRef.current = onInitialized;
+    const onAppendedRef = useRef(onAppended);
+    onAppendedRef.current = onAppended;
+    const appendedRef = useRef<string | undefined>(undefined);
+    // 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: [
+            StarterKit.configure({ link: { openOnClick: false } }),
+            TextStyleKit.configure({ backgroundColor: false, lineHeight: false }),
+            TextAlign.configure({ types: ["heading", "paragraph"] }),
+            Highlight,
+            Image,
+            TableKit.configure({ table: { resizable: true } }),
+            Placeholder.configure({ placeholder: "Write your message…" }),
+        ],
+        content: value,
+        autofocus,
+        immediatelyRender: false,
+        editorProps: {
+            // Ctrl/Cmd+Enter is the compose window's Send. TipTap binds it to a hard break, and a key it handles never reaches the
+            // window's shortcut (which skips what a widget already took), so it inserted a line break and sent nothing. Returning true here
+            // stops ProseMirror handling it without preventing the event, which goes on to the shortcut. Shift+Enter is still the hard break.
+            handleDOMEvents: { keydown: (_view, event) => event.key === "Enter" && (event.ctrlKey || event.metaKey) },
+        },
+        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());
+            }
+        },
+    });
+
+    // Added once, at the end, whatever the reader has typed meanwhile (the caret stays where it is).
+    useEffect(() => {
+        if (!editor || appendHtml === undefined || appendedRef.current === appendHtml) {
+            return;
+        }
+        appendedRef.current = appendHtml;
+        editor.commands.insertContentAt(editor.state.doc.content.size, appendHtml);
+        onAppendedRef.current?.(editor.getHTML());
+    }, [editor, appendHtml]);
+
+    return (
+        <div className={["border border-border rounded-sm overflow-hidden", fill ? "h-full flex flex-col" : ""].filter(Boolean).join(" ")}>
+            <ComposeToolbar editor={editor} onUploadImage={onUploadImage} />
+            <EditorContent
+                editor={editor}
+                style={fill ? undefined : { height }}
+                className={[
+                    "overflow-y-auto px-3 py-2 text-sm [&_.tiptap]:outline-none [&_.tiptap]:h-full",
+                    fill ? "flex-1 min-h-0" : "",
+                ]
+                    .filter(Boolean)
+                    .join(" ")}
+            />
+        </div>
+    );
+}

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

@@ -0,0 +1,48 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import CopyButton from "@rapidmx/react-shared/components/buttons/CopyButton.js";
+
+export interface SendFailureAlertProps {
+    /** The plain, human message - always shown. */
+    message: string;
+    /** The technical facts behind it (`describeSendFailure().lines`): per-recipient SMTP results, a transport error.
+     * With none, only the message is shown. */
+    lines: string[];
+}
+
+/**
+ * The banner a compose window shows when a send (or scheduled send) fails: the plain message, prominent, and - when the
+ * server said more - a collapsed "Technical details" block of monospace lines, one per fact, that can be selected or
+ * copied in one go to send to whoever runs the server. Collapsed, because most people only need the message.
+ */
+export default function SendFailureAlert({ message, lines }: SendFailureAlertProps) {
+    return (
+        <Alert>
+            <div className="flex-1 min-w-0">
+                <p className="font-semibold break-words">{message}</p>
+                {lines.length > 0 && (
+                    <details className="mt-2">
+                        <summary className="cursor-pointer text-xs font-semibold">Technical details</summary>
+                        <ul
+                            aria-label="Technical details"
+                            className="mt-2 max-h-40 overflow-auto rounded-sm border border-border bg-surface p-2 text-xs font-mono text-text select-text"
+                        >
+                            {lines.map((line, index) => (
+                                <li key={index} className="whitespace-pre-wrap break-words">
+                                    {line}
+                                </li>
+                            ))}
+                        </ul>
+                        <div className="mt-2">
+                            <CopyButton value={lines.join("\n")} label="Copy technical details" />
+                        </div>
+                    </details>
+                )}
+            </div>
+        </Alert>
+    );
+}

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

@@ -0,0 +1,46 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * `performance.mark()`/`measure()` around the phases between clicking Compose/Reply/Forward and the window being usable,
+ * for the browser's Performance panel (or `performance.getEntriesByType("measure")`). Marks are named
+ * `compose:<window id>:<phase>`; the measures are named `compose:<from>-><to>` and carry the window id in `detail`.
+ *
+ * Phases, in order: `click` (the handler ran), `shell` (the window's frame is on screen - the placeholder, or the real
+ * window once its chunk has loaded), `chunk` (the window's code has loaded and rendered), `body` (the seeded body -
+ * signature and quoted original - is ready), `editor` (the editor has mounted and can be typed into), `draft` (the server
+ * draft exists).
+ *
+ * On in development builds, and in a production build when `window.__RAPIDMX_PERF__` is set to `true` (from the console:
+ * `window.__RAPIDMX_PERF__ = true`). Off otherwise, when each call is a no-op.
+ */
+
+export type ComposePhase = "click" | "shell" | "chunk" | "body" | "editor" | "draft";
+
+function enabled(): boolean {
+    if (typeof performance === "undefined" || typeof performance.mark !== "function") {
+        return false;
+    }
+    return import.meta.env?.DEV === true || (globalThis as { __RAPIDMX_PERF__?: boolean }).__RAPIDMX_PERF__ === true;
+}
+
+/** The compose sessions a `click` mark was made for, so the first mark of each phase is the only one that counts. */
+const marked = new Set<string>();
+
+/** Marks `phase` of window `id` once (later calls for the same phase are ignored), and measures it from `click`. */
+export function markComposePhase(id: string, phase: ComposePhase): void {
+    if (!enabled()) {
+        return;
+    }
+    const key = `compose:${id}:${phase}`;
+    if (marked.has(key)) {
+        return;
+    }
+    marked.add(key);
+    performance.mark(key);
+    const start = `compose:${id}:click`;
+    if (phase !== "click" && marked.has(start)) {
+        performance.measure(`compose:click->${phase}`, { start, end: key, detail: { id } });
+    }
+}