@rapidmx/web-client 0.9.0 → 0.11.0

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

@@ -4,12 +4,16 @@
 ///////////////////////////////////////////////////////////////////////////////
 import React, { useEffect, useLayoutEffect, useRef, useState } from "react";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
-import { Attachment, Folder, Message, listAttachments, setMessageRead } from "@rapidmx/react-shared/mail/mailApi.js";
+import { Attachment, Folder, Message, listAttachments } from "@rapidmx/react-shared/mail/mailApi.js";
 import { ConversationSummary, listConversationMessages } from "@rapidmx/react-shared/mail/conversationsApi.js";
 import { Label } from "@rapidmx/react-shared/mail/labelsApi.js";
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
-import MailAddress from "./MailAddress.js";
 import MessageDetailPane from "./MessageDetailPane.js";
+import { EncryptedPreview, displaySubject } from "./reading/EncryptedPreview.js";
+import { CollapsedCard, SkeletonCards, SubjectCard } from "./reading/MessageCard.js";
+import { useMailShell } from "./layout/MailShell.js";
+import { setReadState } from "../../mail/messageReadState.js";
+import { dateClass, isUnread, senderClass } from "./unreadStyle.js";
 
 /** One request's worth of the thread. The server's own default for `listConversationMessages()`. */
 export const THREAD_PAGE_SIZE = 100;
@@ -51,6 +55,9 @@ export interface ConversationThreadPaneProps {
     onLabelCreated?: (label: Label) => void;
     /** A folder created from a message's own Move to prompt, for the folder sidebar to pick up. */
     onFolderCreated?: (folder: Folder) => void;
+    /** Registers the keyboard shortcuts (Reply, Reply all, Forward, Archive, Move to) of the message that was opened - see `MessageDetailPane`'s
+     * `shortcuts`. The caller turns it off while it is doing something else with the keyboard (select mode). */
+    shortcuts?: boolean;
 }
 
 /**
@@ -110,8 +117,18 @@ async function loadThread(mailboxUid: string, conversationId: string): Promise<{
     return { messages, truncated: more };
 }
 
+/** Whether the browser is showing a focus ring on `element` - it was focused from the keyboard (or by a key press's handler), not by a click. */
+function hasFocusRing(element: HTMLElement): boolean {
+    try {
+        return element.matches(":focus-visible");
+    } catch {
+        return false;
+    }
+}
+
 /**
- * The reading pane for the conversation list: the whole thread, **newest at the top**, opened at the message
+ * The reading pane for the conversation list: the conversation's subject in a card of its own, pinned at the top, and under it the whole thread as
+ * a stack of message cards (each exactly as tall as its message; the list scrolls as a whole), **newest at the top**, opened at the message
  * the reader picked. Every message from that one through to the newest is expanded - which in this order is
  * the opened message and the entries above it - and the older ones, below it, are collapsed to a one-line
  * summary (sender, date, preview) that expands on click or Enter. So opening the newest message shows just
@@ -137,7 +154,9 @@ export default function ConversationThreadPane({
     onMessageRemoved,
     onLabelCreated,
     onFolderCreated,
+    shortcuts,
 }: ConversationThreadPaneProps) {
+    const { trackMessageChange } = useMailShell();
     const [messages, setMessages] = useState<Message[]>([]);
     const [attachmentsByUid, setAttachmentsByUid] = useState<Record<string, Attachment[]>>({});
     const [expandedUids, setExpandedUids] = useState<Set<string>>(new Set());
@@ -164,6 +183,9 @@ export default function ConversationThreadPane({
     /** Where the toggled message's header sat in the viewport before it expanded, so the run below can put
      * it back there - expanding a message above the one being read must not shove that one off-screen. */
     const anchorRef = useRef<{ uid: string; top: number } | null>(null);
+    /** The message whose header button had the focus when it was toggled: expanding or collapsing swaps that button for the other state's, so the
+     * focus is put back on the new one. */
+    const refocusRef = useRef<string | null>(null);
 
     const conversationId = conversation?.conversationId;
 
@@ -238,8 +260,15 @@ export default function ConversationThreadPane({
                 scroller.scrollTop += top;
             }
         }
-        // `preventScroll` so focusing doesn't scroll it somewhere else again.
-        headerRefs.current[pendingFocusUid]!.focus({ preventScroll: true });
+        // A key press (j, k, the arrows) that opened this thread left the focus on its list row on purpose, so Enter goes on to open the
+        // message's page; taking the focus here would make Enter toggle this header instead. A click leaves no focus ring, and hands
+        // the focus to the thread as before.
+        const active = document.activeElement;
+        if (!(active instanceof HTMLElement && active.hasAttribute("data-row-open") && hasFocusRing(active))) {
+            // `preventScroll` so focusing doesn't scroll it somewhere else again.
+            // (A card's header button is drawn by the message pane, which registers it; a stand-in pane that doesn't has none to focus.)
+            headerRefs.current[pendingFocusUid]?.focus({ preventScroll: true });
+        }
         setPendingFocusUid(null);
     }, [pendingFocusUid, expandedUids]);
 
@@ -252,6 +281,11 @@ export default function ConversationThreadPane({
         // The row is still there: the anchor was taken from a rendered row, and toggling never removes one.
         const row = rowRefs.current[anchor.uid]!;
         scrollingAncestor(row).scrollTop += row.getBoundingClientRect().top - anchor.top;
+        // The button the reader had focused is gone (a collapsed card and an expanded one each draw their own): keep them where they were.
+        if (refocusRef.current === anchor.uid) {
+            headerRefs.current[anchor.uid]?.focus({ preventScroll: true });
+        }
+        refocusRef.current = null;
     }, [expandedUids]);
 
     // Attachments and mark-as-read, for expanded messages only - mirrors `mailDetailHooks.ts`'s
@@ -276,20 +310,26 @@ export default function ConversationThreadPane({
                         attachmentsRequestedRef.current.delete(uid);
                     });
             }
-            if (!message.flags.read && !markReadRequestedRef.current.has(uid)) {
+            if (!markReadRequestedRef.current.has(uid)) {
+                // Asked once per opened conversation and per expanding of the message: a failure is not retried from here, because
+                // undoing the optimistic change changes `messages`, which would run this effect again and ask again, for ever. A message
+                // that is already read is asked about too (there is nothing to send), so marking it unread while it is open - the
+                // keyboard's Ctrl+U - doesn't make this run again and read it straight back.
                 markReadRequestedRef.current.add(uid);
-                // `message` is this render's copy, so the request carries its current `version`.
-                setMessageRead(message, true)
-                    .then((updated) => {
-                        if (generation !== generationRef.current) return;
-                        // `message` is the unread copy this pane just replaced - what tells the list's own
-                        // conversation row that its unread count has gone down by one.
-                        patchMessage(updated, message);
-                    })
-                    .catch(() => {
-                        // Best-effort, as in `useMarkMessageRead`.
-                        markReadRequestedRef.current.delete(uid);
-                    });
+                if (message.flags.read === true) {
+                    continue;
+                }
+                // `message` is this render's copy, so the request carries its current `version`. The row, the conversation row's
+                // unread count and the folder badge all change at once; `previous` is what tells the list's conversation row
+                // that its count moved (see `setReadState()`).
+                void setReadState(message, true, {
+                    patch: (updated, previous) => {
+                        if (generation === generationRef.current) {
+                            patchMessage(updated, previous);
+                        }
+                    },
+                    track: trackMessageChange,
+                });
             }
         }
     }, [expandedUids, messages]);
@@ -308,8 +348,11 @@ export default function ConversationThreadPane({
     }
 
     function toggleExpanded(uid: string) {
+        // Opening a message again asks to mark it read again - that is how one whose request failed is retried.
+        markReadRequestedRef.current.delete(uid);
         // The row this button lives in has rendered, so its ref is set.
         anchorRef.current = { uid, top: rowRefs.current[uid]!.getBoundingClientRect().top };
+        refocusRef.current = document.activeElement === headerRefs.current[uid] ? uid : null;
         setExpandedUids((prev) => {
             const next = new Set(prev);
             if (next.has(uid)) {
@@ -321,6 +364,10 @@ export default function ConversationThreadPane({
         });
     }
 
+    // The keyboard acts on the message that was opened - or the newest, when the opened one isn't in this thread - never on all the expanded
+    // ones at once (each is a `MessageDetailPane`, and two of them must not both answer Ctrl+R).
+    const keyboardUid = messages.some((message) => message.uid === selectedUid) ? selectedUid : messages[0]?.uid;
+
     function folderTypeOf(message: Message): string | undefined {
         return folders.find((folder) => folder.uid === message.folderUid)?.type;
     }
@@ -328,107 +375,113 @@ export default function ConversationThreadPane({
     if (!conversation) {
         return <p className="p-8 text-sm text-text-muted">Select a conversation to read it.</p>;
     }
-    if (loading) {
-        return <p className="p-8 text-sm text-text-muted">Loading&hellip;</p>;
-    }
-    if (error) {
-        return (
-            <div className="p-4 flex-1">
-                <Alert>{error}</Alert>
-            </div>
-        );
-    }
+    const subject = displaySubject(conversation.subject) || "(no subject)";
+    // The newest message that is open carries the Reply / Forward buttons at the foot of its card.
+    const footerUid = messages.find((message) => expandedUids.has(message.uid))?.uid;
 
     return (
-        // The pane is the window's height, not the thread's: a full-height flex column whose heading is
-        // fixed and whose list of messages is the one scrolling, growing child (`min-h-0`, or the list
-        // would stretch the column past the pane instead of scrolling inside it). That is what gives an
-        // expanded message's own `min-h-full` row - and therefore its body iframe, which can't measure
-        // itself - a real height to resolve against at any window size.
+        // The pane is the window's height, not the thread's: a full-height flex column whose header card is fixed and whose list of
+        // message cards is the one scrolling, growing child (`min-h-0`, or the list would stretch the column past the pane instead of
+        // scrolling inside it). Each card is exactly as tall as its message.
+        // The subject card is the same element while the messages load and once they are here (the subject and the count are known from the
+        // list's row), so nothing shifts or is drawn again when they arrive: a skeleton card per message (up to three) stands where they will be.
         <div className="flex-1 min-w-0 min-h-0 flex flex-col">
-            <div className="shrink-0 border-b border-border p-4">
-                <h1 className="text-lg font-bold tracking-tight">{conversation.subject || "(no subject)"}</h1>
-                <p className="text-sm text-text-muted mt-1">
-                    {messages.length} message{messages.length === 1 ? "" : "s"}
-                </p>
-                {truncated && (
+            <SubjectCard
+                subject={subject}
+                meta={
+                    loading
+                        ? conversation.messageCount > 1
+                            ? `${conversation.messageCount} messages`
+                            : undefined
+                        : error
+                          ? undefined
+                          : `${messages.length} message${messages.length === 1 ? "" : "s"}`
+                }
+            >
+                {truncated && !loading && !error && (
                     <p className="text-xs text-text-muted mt-1">
                         Only the oldest {THREAD_MESSAGE_LIMIT} messages of this conversation are shown here. The rest
                         are still in the message list.
                     </p>
                 )}
-            </div>
-            <ul className="flex-1 min-h-0 overflow-y-auto">
+            </SubjectCard>
+            {loading ? (
+                <SkeletonCards messageCount={conversation.messageCount} />
+            ) : error ? (
+                <div className="p-2 sm:p-3">
+                    <Alert>{error}</Alert>
+                </div>
+            ) : (
+            <ul className="flex-1 min-h-0 overflow-y-auto p-2 sm:p-3 flex flex-col gap-3">
                 {messages.map((message) => {
                     const uid = message.uid;
                     const expanded = expandedUids.has(uid);
                     const bodyId = `thread-message-${uid}`;
+                    const messageUnread = isUnread(message);
                     return (
                         <li
                             key={uid}
                             ref={(node) => {
                                 rowRefs.current[uid] = node;
                             }}
-                            // An expanded message is as tall as the list it scrolls in - `min-h-full`
-                            // against the `<ul>`'s own resolved height - so its `MessageDetailPane` below
-                            // has a full pane of height to fill and its body reaches the bottom of the
-                            // window whatever that window's size is. `min-` rather than `h-`: a message
-                            // whose header alone is taller than the pane still gets the room it needs.
-                            className={["border-b border-border", expanded ? "flex flex-col min-h-full" : ""].join(" ")}
+                            data-unread={messageUnread ? "true" : undefined}
                         >
-                            <h2 className="shrink-0">
-                                <button
-                                    type="button"
-                                    ref={(node) => {
-                                        headerRefs.current[uid] = node;
+                            {expanded ? (
+                                <MessageDetailPane
+                                    inThread
+                                    threadSubject={subject}
+                                    threadHeader={{
+                                        bodyId,
+                                        unread: messageUnread,
+                                        onToggle: () => toggleExpanded(uid),
+                                        buttonRef: (node) => {
+                                            headerRefs.current[uid] = node;
+                                        },
                                     }}
-                                    onClick={() => toggleExpanded(uid)}
-                                    aria-expanded={expanded}
-                                    aria-controls={bodyId}
-                                    className={[
-                                        "w-full text-left px-4 py-3 hover:bg-surface-alt",
-                                        message.flags.read ? "" : "font-semibold",
-                                    ].join(" ")}
-                                >
-                                    <span className="flex items-center justify-between gap-2 text-sm">
-                                        <MailAddress recipient={message.from} />
-                                        <span className="text-xs text-text-muted shrink-0">
-                                            {new Date(message.receivedDate).toLocaleString()}
-                                        </span>
-                                    </span>
-                                    {!expanded && (
-                                        <span className="block text-xs text-text-muted truncate font-normal">
-                                            {message.bodyPreview}
-                                        </span>
-                                    )}
-                                </button>
-                            </h2>
-                            <div id={bodyId} hidden={!expanded} className={expanded ? "flex-1 min-h-0 flex" : undefined}>
-                                {expanded && (
-                                    <MessageDetailPane
-                                        inThread
-                                        message={message}
-                                        attachments={attachmentsByUid[uid] ?? []}
-                                        isSentItems={folderTypeOf(message) === "sent_items"}
-                                        isOutbox={folderTypeOf(message) === "outbox"}
-                                        draftsFolderUid={folders.find((folder) => folder.type === "drafts")?.uid}
-                                        folders={folders}
-                                        onMoved={removeMessage}
-                                        onFolderCreated={onFolderCreated}
-                                        onRecalled={patchMessage}
-                                        onReceiptHandled={patchMessage}
-                                        onScheduledSendCanceled={removeMessage}
-                                        onArchived={removeMessage}
-                                        labels={labels}
-                                        onLabelsChanged={patchMessage}
-                                        onLabelCreated={onLabelCreated}
+                                    footer={uid === footerUid}
+                                    shortcuts={!!shortcuts && uid === keyboardUid}
+                                    message={message}
+                                    attachments={attachmentsByUid[uid] ?? []}
+                                    isSentItems={folderTypeOf(message) === "sent_items"}
+                                    isOutbox={folderTypeOf(message) === "outbox"}
+                                    draftsFolderUid={folders.find((folder) => folder.type === "drafts")?.uid}
+                                    folders={folders}
+                                    onMoved={removeMessage}
+                                    onFolderCreated={onFolderCreated}
+                                    onRecalled={patchMessage}
+                                    onReceiptHandled={patchMessage}
+                                    onScheduledSendCanceled={removeMessage}
+                                    onArchived={removeMessage}
+                                    labels={labels}
+                                    onLabelsChanged={patchMessage}
+                                    onLabelCreated={onLabelCreated}
+                                />
+                            ) : (
+                                <>
+                                    <CollapsedCard
+                                        from={message.from}
+                                        date={new Date(message.receivedDate).toLocaleString()}
+                                        preview={message.bodyPreview || (message.encrypted ? <EncryptedPreview /> : "")}
+                                        unread={messageUnread}
+                                        senderClassName={senderClass(messageUnread)}
+                                        dateClassName={dateClass(messageUnread)}
+                                        buttonRef={(node) => {
+                                            headerRefs.current[uid] = node;
+                                        }}
+                                        buttonProps={{
+                                            onClick: () => toggleExpanded(uid),
+                                            "aria-expanded": false,
+                                            "aria-controls": bodyId,
+                                        }}
                                     />
-                                )}
-                            </div>
+                                    <div id={bodyId} hidden />
+                                </>
+                            )}
                         </li>
                     );
                 })}
             </ul>
+            )}
         </div>
     );
 }

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

@@ -0,0 +1,113 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { ComponentType, useEffect, useState } from "react";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+import { ReadingPaneSkeleton } from "./reading/MessageCard.js";
+import type MessageDetailPaneType from "./MessageDetailPane.js";
+import type ConversationThreadPaneType from "./ConversationThreadPane.js";
+
+/**
+ * The reading pane (`MessageDetailPane`, and the thread pane that stacks it) is only rendered once a message is selected, and
+ * it is the heaviest piece of the inbox after the compose window - message security, the body sanitizer, the labels and move
+ * menus - so it is a chunk of its own, downloaded when the browser is idle after the list has loaded (`prefetchReadingPane()`)
+ * and, at the latest, on the first selection. Nothing about the pane changes: these wrap the same components, with a skeleton
+ * while the chunk loads and a reload prompt if it can't.
+ *
+ * Deliberately not `React.lazy()` + `<Suspense>`: a boundary that has shown its fallback holds the content back for up to 300 ms
+ * after the code arrives (React's fallback throttle), which would put a fifth of a second between a click and a pane whose
+ * code was already fetched. This reads the loaded component synchronously when there is one, so an already-loaded pane renders
+ * on the click's own frame, and it can retry a failed download.
+ */
+function lazyComponent<P extends object>(load: () => Promise<{ default: ComponentType<P> }>, skeleton: (props: P) => React.ReactNode) {
+    let loaded: ComponentType<P> | undefined;
+    let loading: Promise<ComponentType<P>> | undefined;
+
+    /** Starts (once) loading the component's code. Rejects if it can't be downloaded - and then a later call tries again. */
+    function start(): Promise<ComponentType<P>> {
+        loading ??= load().then(
+            (module) => (loaded = module.default),
+            (err) => {
+                loading = undefined;
+                throw err;
+            },
+        );
+        return loading;
+    }
+
+    function Lazy(props: P) {
+        const [, setLoadedNow] = useState(0);
+        const [failed, setFailed] = useState(false);
+        useEffect(() => {
+            if (loaded) {
+                return;
+            }
+            let cancelled = false;
+            start().then(
+                () => !cancelled && setLoadedNow((n) => n + 1),
+                () => !cancelled && setFailed(true),
+            );
+            return () => {
+                cancelled = true;
+            };
+        }, []);
+        if (loaded) {
+            const Component = loaded;
+            return <Component {...props} />;
+        }
+        return failed ? <ChunkFailed /> : skeleton(props);
+    }
+
+    return { Lazy, start };
+}
+
+/** A chunk that can't be downloaded (offline, or replaced by a deploy since this page loaded) is the one failure a reading
+ * pane can't recover from by itself: say so, with the fix, rather than leaving a blank pane. */
+function ChunkFailed() {
+    return (
+        <div className="flex-1 p-6">
+            <Alert>
+                <p className="mb-2">This part of the page couldn&rsquo;t be loaded. Check your connection, then reload.</p>
+                <Button type="button" variant="secondary" className="!w-auto" onClick={() => window.location.reload()}>
+                    Reload
+                </Button>
+            </Alert>
+        </div>
+    );
+}
+
+// While the code loads the pane already draws its frame - the header card with the subject the list row knows, and a card of placeholder lines - so
+// the click is answered on its own frame and the messages only fill in.
+const messageDetailPane = lazyComponent<React.ComponentProps<typeof MessageDetailPaneType>>(
+    () => import("./MessageDetailPane.js"),
+    // `LazyMessageDetailPane` renders the empty state, not this, for no message.
+    (props) => <ReadingPaneSkeleton subject={props.message!.subject} />,
+);
+const conversationThreadPane = lazyComponent<React.ComponentProps<typeof ConversationThreadPaneType>>(
+    () => import("./ConversationThreadPane.js"),
+    (props) => <ReadingPaneSkeleton subject={props.conversation!.subject} messageCount={props.conversation!.messageCount} />,
+);
+
+/** Starts downloading the reading pane's code, for the page to call when it has nothing better to do. Never rejects. */
+export function prefetchReadingPane(): void {
+    messageDetailPane.start().catch(() => undefined);
+    conversationThreadPane.start().catch(() => undefined);
+}
+
+/** With nothing selected the pane is only its empty-state line, which needs none of the pane's code - so the chunk isn't
+ * requested until something is (or the page prefetches it). */
+export function LazyMessageDetailPane(props: React.ComponentProps<typeof MessageDetailPaneType>) {
+    if (!props.message) {
+        return <p className="p-8 text-sm text-text-muted">Select a message to read it.</p>;
+    }
+    return <messageDetailPane.Lazy {...props} />;
+}
+
+export function LazyConversationThreadPane(props: React.ComponentProps<typeof ConversationThreadPaneType>) {
+    if (!props.conversation) {
+        return <p className="p-8 text-sm text-text-muted">Select a conversation to read it.</p>;
+    }
+    return <conversationThreadPane.Lazy {...props} />;
+}