@wtfalch/email 0.4.0 → 0.5.0

package/dist/mailbox/react/Mail.js

@@ -1,14 +1,16 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Button, Command, Icon, Input, Modal, SplitPane } from '@wtfalch/design';
+import { Button, Command, Icon, Modal, SplitPane } from '@wtfalch/design';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { forwardDraft, replyDraft } from "../drafts.js";
 import { findRole } from "../mailboxes.js";
+import { moveToRole, setFlagged, setRead } from "../mutate.js";
 import { send } from "../submit.js";
 import { Composer } from "./Composer.js";
 import { MailboxTree, flatMailboxes } from "./MailboxTree.js";
 import { ThreadList } from "./ThreadList.js";
 import { ThreadView } from "./ThreadView.js";
 import { useIdentities, useMailboxes, usePush, useThread, useThreads } from "./hooks.js";
+import { usePanes } from "./layout.js";
 /**
  * The whole client: mailboxes, a list, a message, and a way to write one.
  *
@@ -18,13 +20,26 @@ import { useIdentities, useMailboxes, usePush, useThread, useThreads } from "./h
  * having on its own -- an application with its own layout can take the four
  * views and skip this entirely.
  *
+ * **Three panes, two, or one.** `usePanes` decides, and the difference is not
+ * cosmetic: at one column the list and the message occupy the same space, so
+ * which is showing becomes state. See `layout.ts` for where the two
+ * measurements came from.
+ *
  * **Push moves the list, not the message.** A state change refetches the
  * mailbox counts and the current page; it deliberately does not refetch the
  * thread being read, because replacing the message under somebody mid-sentence
  * is worse than showing them a copy that is thirty seconds old.
  *
- * **The palette is the keyboard.** Cmd-K opens it, and it carries the
- * mailboxes as "go to" entries, so moving around never requires the mouse.
+ * **Opening a conversation marks it read**, which is what opening means. Only
+ * when there is something unread in it: an `Email/set` that changes nothing
+ * still moves the account's state string and wakes every other client's push
+ * connection.
+ *
+ * **The keyboard is the point.** Cmd-K opens the palette; the single letters
+ * are the ones every mail client has had since pine, and `?` lists them. They
+ * are bound at the root rather than per pane so they work from inside the
+ * message as well as from the list -- and they are ignored while a field has
+ * focus, or `c` could never be typed into a subject.
  */
 const PAGE = 50;
 export function Mail({ client, location, onNavigate, account, onError, now, className, }) {
@@ -46,6 +61,7 @@ export function Mail({ client, location, onNavigate, account, onError, now, clas
     }, [controlled, onNavigate]);
     const setMailboxId = useCallback((next) => navigate({ mailboxId: next, threadId: null }), [navigate]);
     const setThreadId = useCallback((next) => navigate({ mailboxId, threadId: next }), [navigate, mailboxId]);
+    const panes = usePanes();
     const [position, setPosition] = useState(0);
     const [query, setQuery] = useState('');
     const [text, setText] = useState('');
@@ -53,6 +69,11 @@ export function Mail({ client, location, onNavigate, account, onError, now, clas
     const [sending, setSending] = useState(false);
     const [sendError, setSendError] = useState();
     const [paletteOpen, setPaletteOpen] = useState(false);
+    const [drawerOpen, setDrawerOpen] = useState(false);
+    const [helpOpen, setHelpOpen] = useState(false);
+    const [acting, setActing] = useState(false);
+    const [note, setNote] = useState(null);
+    const searchField = useRef(null);
     const boxes = useMailboxes(client);
     const identities = useIdentities(client);
     /* The inbox, once, when the mailboxes first arrive. Not in an effect that
@@ -83,39 +104,60 @@ export function Mail({ client, location, onNavigate, account, onError, now, clas
         reported.current = failure;
         onError?.(failure);
     }, [failure, onError]);
+    const current = boxes.data?.find((box) => box.id === mailboxId);
+    const summary = threads.data?.items.find((item) => item.id === threadId);
+    /* Stalwart creates five mailboxes and Archive is not among them -- Inbox,
+       Drafts, Sent Items, Junk Mail, Deleted Items. So the button is offered
+       only where there is somewhere for it to move mail to, rather than being
+       a control that fails the same way every time it is pressed on the
+       commonest server this client faces. Somebody who has made an Archive
+       mailbox gets it; somebody who has not never sees it. */
+    const archiveBox = boxes.data ? findRole(boxes.data, 'archive') : undefined;
+    const trashBox = boxes.data ? findRole(boxes.data, 'trash') : undefined;
     const go = useCallback((mailbox) => {
         navigate({ mailboxId: mailbox.id, threadId: null });
         setPosition(0);
         setQuery('');
         setText('');
+        setDrawerOpen(false);
     }, [navigate]);
-    const openThread = useCallback((summary) => setThreadId(summary.id), [setThreadId]);
-    /* Cmd-K, and Escape out of a search. Bound on the window rather than on a
-       container, because the palette has to open from wherever focus is --
-       including from inside the message being read. */
+    const openThread = useCallback((picked) => setThreadId(picked.id), [setThreadId]);
+    /**
+     * Opening a conversation is what marks it read.
+     *
+     * Fired from the thread actually arriving rather than from the click, so a
+     * thread reached by a pasted URL is marked too. The guard is the unread
+     * count, not a ref: a thread re-opened after being marked unread again has
+     * to mark again, which a "have I done this one" set would prevent.
+     */
     useEffect(() => {
-        const onKey = (event) => {
-            if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') {
-                event.preventDefault();
-                setPaletteOpen(true);
-            }
+        if (!threadId || !summary || summary.unreadCount === 0)
+            return;
+        let live = true;
+        setRead(client, threadId, true)
+            .then(() => live && refresh())
+            .catch(() => {
+            /* Left unread rather than announced. The count is still right --
+               nothing was changed -- and a toast for a failure the person did not
+               ask for is noise on top of a mail server that is already unwell. */
+        });
+        return () => {
+            live = false;
         };
-        window.addEventListener('keydown', onKey);
-        return () => window.removeEventListener('keydown', onKey);
-    }, []);
+    }, [client, threadId, summary, refresh]);
     const identity = identities.data?.[0];
-    const startReply = (message, all) => {
+    const startReply = useCallback((message, all) => {
         if (!identity)
             return;
         setSendError(undefined);
         setDraft(replyDraft(message, { identity, all }));
-    };
-    const startForward = (message) => {
+    }, [identity]);
+    const startForward = useCallback((message) => {
         if (!identity)
             return;
         setSendError(undefined);
         setDraft(forwardDraft(message, { identity }));
-    };
+    }, [identity]);
     const startNew = useCallback(() => {
         if (!identity)
             return;
@@ -133,6 +175,7 @@ export function Mail({ client, location, onNavigate, account, onError, now, clas
                 ...(boxes.data ? { mailboxes: boxes.data } : {}),
             });
             setDraft(null);
+            setNote('Message sent.');
             refresh();
         }
         catch (error) {
@@ -142,6 +185,166 @@ export function Mail({ client, location, onNavigate, account, onError, now, clas
             setSending(false);
         }
     };
+    /**
+     * An action on the open conversation.
+     *
+     * Every one of them ends the same way -- the list is stale, and on the
+     * layouts where the message has its own column the selection now points at
+     * a thread that is no longer in the mailbox being shown. So the selection
+     * is cleared and the list refetched, once, here, rather than three times at
+     * three call sites that would each forget a different half of it.
+     */
+    const act = useCallback(async (what, said, clears = true) => {
+        if (!threadId)
+            return;
+        setActing(true);
+        try {
+            await what();
+            if (clears)
+                setThreadId(null);
+            setNote(said);
+            refresh();
+        }
+        catch (error) {
+            setNote(error instanceof Error ? error.message : 'That did not work.');
+        }
+        finally {
+            setActing(false);
+        }
+    }, [threadId, setThreadId, refresh]);
+    const archive = useCallback(() => {
+        if (!threadId)
+            return;
+        void act(() => moveToRole(client, threadId, 'archive', { mailboxes: boxes.data ?? [] }), 'Archived.');
+    }, [act, client, threadId, boxes.data]);
+    const trash = useCallback(() => {
+        if (!threadId)
+            return;
+        void act(() => moveToRole(client, threadId, 'trash', { mailboxes: boxes.data ?? [] }), 'Moved to Deleted Items.');
+    }, [act, client, threadId, boxes.data]);
+    const markUnread = useCallback(() => {
+        if (!threadId)
+            return;
+        void act(() => setRead(client, threadId, false), 'Marked unread.');
+    }, [act, client, threadId]);
+    const flag = useCallback((next) => {
+        if (!threadId)
+            return;
+        void act(() => setFlagged(client, threadId, next), next ? 'Flagged.' : 'Unflagged.', false);
+    }, [act, client, threadId]);
+    /**
+     * The shortcuts.
+     *
+     * Bound on the window rather than on a container, because the palette has
+     * to open from wherever focus is -- including from inside the message being
+     * read.
+     *
+     * **A field swallows everything but Escape and Cmd-K.** `c` for compose and
+     * `c` typed into a subject line are the same keystroke, and a client that
+     * cannot tell them apart is a client you cannot write mail in. The test is
+     * the event's target, not a focus flag, because focus can be inside a
+     * portalled dialog that this component never rendered.
+     */
+    useEffect(() => {
+        const typing = (target) => {
+            const el = target;
+            if (!el?.tagName)
+                return false;
+            return (el.tagName === 'INPUT' ||
+                el.tagName === 'TEXTAREA' ||
+                el.tagName === 'SELECT' ||
+                el.isContentEditable);
+        };
+        const onKey = (event) => {
+            if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') {
+                event.preventDefault();
+                setPaletteOpen(true);
+                return;
+            }
+            if (event.metaKey || event.ctrlKey || event.altKey)
+                return;
+            if (typing(event.target))
+                return;
+            switch (event.key) {
+                case '/':
+                    event.preventDefault();
+                    searchField.current?.focus();
+                    break;
+                case '?':
+                    event.preventDefault();
+                    setHelpOpen(true);
+                    break;
+                case 'c':
+                    event.preventDefault();
+                    startNew();
+                    break;
+                case 'e':
+                    if (!threadId || !archiveBox)
+                        break;
+                    event.preventDefault();
+                    archive();
+                    break;
+                case '#':
+                    if (!threadId || !trashBox)
+                        break;
+                    event.preventDefault();
+                    trash();
+                    break;
+                case 'u':
+                    if (!threadId)
+                        break;
+                    event.preventDefault();
+                    markUnread();
+                    break;
+                case 's':
+                    if (!threadId)
+                        break;
+                    event.preventDefault();
+                    flag(!summary?.isFlagged);
+                    break;
+                case 'r':
+                case 'a': {
+                    const newest = thread.data?.messages[thread.data.messages.length - 1];
+                    if (!newest)
+                        break;
+                    event.preventDefault();
+                    startReply(newest, event.key === 'a');
+                    break;
+                }
+                case 'f': {
+                    const newest = thread.data?.messages[thread.data.messages.length - 1];
+                    if (!newest)
+                        break;
+                    event.preventDefault();
+                    startForward(newest);
+                    break;
+                }
+                case 'Escape':
+                    if (threadId && panes === 'narrow')
+                        setThreadId(null);
+                    break;
+                default:
+                    break;
+            }
+        };
+        window.addEventListener('keydown', onKey);
+        return () => window.removeEventListener('keydown', onKey);
+    }, [
+        threadId,
+        thread.data,
+        summary,
+        panes,
+        archive,
+        trash,
+        markUnread,
+        flag,
+        startNew,
+        startReply,
+        startForward,
+        setThreadId,
+        archiveBox,
+        trashBox,
+    ]);
     const paletteGroups = useMemo(() => [
         {
             title: 'Go to',
@@ -156,20 +359,93 @@ export function Mail({ client, location, onNavigate, account, onError, now, clas
             title: 'Message',
             commands: [
                 { id: 'new', label: 'New message', shortcut: 'C', onRun: startNew },
+                ...(threadId && archiveBox
+                    ? [{ id: 'archive', label: 'Archive', shortcut: 'E', onRun: archive }]
+                    : []),
+                ...(threadId && trashBox
+                    ? [{ id: 'trash', label: 'Delete', shortcut: '#', onRun: trash }]
+                    : []),
+                ...(threadId
+                    ? [{ id: 'unread', label: 'Mark unread', shortcut: 'U', onRun: markUnread }]
+                    : []),
                 { id: 'refresh', label: 'Refresh', shortcut: 'R', onRun: refresh },
+                {
+                    id: 'help',
+                    label: 'Keyboard shortcuts',
+                    shortcut: '?',
+                    onRun: () => setHelpOpen(true),
+                },
             ],
         },
-    ], [boxes.data, go, refresh, startNew]);
-    const current = boxes.data?.find((box) => box.id === mailboxId);
-    return (_jsxs("div", { className: `mail${className ? ` ${className}` : ''}`, children: [_jsxs("header", { className: "mail-bar", children: [_jsxs(Button, { kind: "primary", onClick: startNew, disabled: !identity, children: [_jsx(Icon, { name: "chat" }), " New"] }), _jsx("form", { className: "mail-search", onSubmit: (event) => {
-                            event.preventDefault();
-                            setQuery(text);
-                            setPosition(0);
-                            setThreadId(null);
-                        }, children: _jsx(Input, { block: true, value: text, placeholder: `Search${current ? ` ${current.name}` : ''}…`, "aria-label": "Search mail", onChange: (event) => setText(event.target.value), onKeyDown: (event) => {
-                                if (event.key !== 'Escape')
-                                    return;
-                                setText('');
-                                setQuery('');
-                            } }) }), _jsx(Button, { kind: "ghost", onClick: () => setPaletteOpen(true), "aria-label": "Open the palette", children: _jsx(Icon, { name: "bolt" }) }), account] }), _jsxs(SplitPane, { className: "mail-panes", label: "Mailbox list width", defaultSize: 22, min: 14, max: 40, storageKey: "mail-sidebar", children: [_jsx(MailboxTree, { mailboxes: boxes.data ?? [], selectedId: mailboxId, onSelect: go, loading: boxes.loading }), _jsxs(SplitPane, { label: "Conversation list width", defaultSize: 38, min: 22, max: 60, storageKey: "mail-list", children: [_jsx(ThreadList, { page: threads.data, selectedId: threadId, onSelect: openThread, onPage: setPosition, limit: PAGE, loading: threads.loading, now: now, empty: query ? _jsxs("p", { className: "threads-quiet", children: ["Nothing matches \u201C", query, "\u201D."] }) : undefined }), _jsx(ThreadView, { thread: thread.data, loading: thread.loading, onReply: startReply, onForward: startForward })] })] }), _jsx(Command, { open: paletteOpen, onOpenChange: setPaletteOpen, groups: paletteGroups }), draft && (_jsx(Modal, { title: "New message", width: "46rem", onClose: sending ? undefined : () => setDraft(null), closeDisabled: sending, children: _jsx(Composer, { draft: draft, onChange: setDraft, onSend: doSend, onCancel: () => setDraft(null), identities: identities.data ?? [], sending: sending, error: sendError }) }))] }));
+    ], [boxes.data, go, refresh, startNew, threadId, archive, trash, markUnread, archiveBox, trashBox]);
+    /* On one column the message replaces the list; on two or three they are
+       both up and this is always false. */
+    const reading = panes === 'narrow' && threadId !== null;
+    const searchBox = (_jsxs("form", { className: "mail-search", onSubmit: (event) => {
+            event.preventDefault();
+            setQuery(text);
+            setPosition(0);
+            setThreadId(null);
+        }, 
+        /* biome-ignore lint/a11y/useSemanticElements: `role="search"` on the
+           form is the landmark, and the rule is proposing the field. The input
+           inside this already is `type="search"`; a landmark and a control are
+           different things and only one of them can be a region a screen
+           reader jumps to. */
+        role: "search", children: [_jsx(Icon, { name: "search", size: 15, className: "mail-search-icon" }), _jsx("input", { ref: searchField, className: "mail-search-field", type: "search", value: text, placeholder: `Search${current ? ` ${current.name}` : ' mail'}`, "aria-label": "Search mail", onChange: (event) => setText(event.target.value), onKeyDown: (event) => {
+                    if (event.key !== 'Escape')
+                        return;
+                    setText('');
+                    setQuery('');
+                    event.currentTarget.blur();
+                } }), query ? (_jsx("button", { type: "button", className: "mail-search-clear", onClick: () => {
+                    setText('');
+                    setQuery('');
+                }, "aria-label": "Clear the search", children: _jsx(Icon, { name: "close", size: 13 }) })) : (_jsx("span", { className: "mail-search-key", "aria-hidden": "true", children: "/" }))] }));
+    const list = (_jsx(ThreadList, { page: threads.data, selectedId: threadId, onSelect: openThread, onPage: (threads.data?.total ?? 0) > PAGE ? setPosition : undefined, limit: PAGE, loading: threads.loading, now: now, title: query ? `Results for “${query}”` : current?.name, empty: query ? _jsxs("p", { className: "threads-quiet", children: ["Nothing matches \u201C", query, "\u201D."] }) : undefined }));
+    const reader = (_jsx(ThreadView, { thread: thread.data, loading: thread.loading, onReply: startReply, onForward: startForward, onArchive: archiveBox ? archive : undefined, onTrash: trashBox ? trash : undefined, onMarkUnread: markUnread, onFlag: flag, flagged: summary?.isFlagged ?? false, busy: acting, onBack: panes === 'narrow' ? () => setThreadId(null) : undefined }));
+    return (_jsxs("div", { className: `mail is-${panes}${className ? ` ${className}` : ''}`, children: [_jsxs("header", { className: "mail-bar", children: [_jsxs("div", { className: "mail-bar-start", children: [panes === 'narrow' && (_jsx(Button, { kind: "ghost", iconOnly: true, onClick: () => setDrawerOpen(true), "aria-label": "Mailboxes", children: _jsx(Icon, { name: "menu" }) })), _jsx("span", { className: "mail-wordmark", children: "Mail" })] }), searchBox, _jsxs("div", { className: "mail-bar-end", children: [_jsxs(Button, { kind: "primary", size: "sm", onClick: startNew, disabled: !identity, children: [_jsx(Icon, { name: "pen", size: 15 }), " ", _jsx("span", { className: "mail-compose-word", children: "Compose" })] }), account] })] }), panes === 'wide' && (_jsxs(SplitPane, { className: "mail-panes", label: "Mailbox list width", defaultSize: 15, min: 11, max: 28, storageKey: "mail-sidebar", children: [_jsx(MailboxTree, { mailboxes: boxes.data ?? [], selectedId: mailboxId, onSelect: go, loading: boxes.loading }), _jsxs(SplitPane, { label: "Conversation list width", defaultSize: 36, min: 26, max: 55, storageKey: "mail-list", children: [list, reader] })] })), panes === 'medium' && (_jsxs("div", { className: "mail-panes", children: [_jsx(MailboxTree, { mailboxes: boxes.data ?? [], selectedId: mailboxId, onSelect: go, loading: boxes.loading, rail: true }), _jsxs(SplitPane, { className: "mail-panes-split", label: "Conversation list width", defaultSize: 40, min: 28, max: 60, storageKey: "mail-list", children: [list, reader] })] })), panes === 'narrow' && _jsx("div", { className: "mail-panes", children: reading ? reader : list }), drawerOpen && (_jsx(Modal, { title: "Mailboxes", width: "20rem", onClose: () => setDrawerOpen(false), children: _jsx(MailboxTree, { mailboxes: boxes.data ?? [], selectedId: mailboxId, onSelect: go, loading: boxes.loading }) })), _jsx(Command, { open: paletteOpen, onOpenChange: setPaletteOpen, groups: paletteGroups }), helpOpen && (_jsx(Modal, { title: "Keyboard shortcuts", width: "26rem", onClose: () => setHelpOpen(false), children: _jsx(Shortcuts, {}) })), draft && (_jsx(Modal, { title: draft.subject ? draft.subject : 'New message', width: "46rem", onClose: sending ? undefined : () => setDraft(null), closeDisabled: sending, children: _jsx(Composer, { draft: draft, onChange: setDraft, onSend: doSend, onCancel: () => setDraft(null), identities: identities.data ?? [], sending: sending, error: sendError }) })), _jsx(Note, { said: note, onDone: () => setNote(null) })] }));
+}
+/**
+ * What just happened, said once and then gone.
+ *
+ * A live region rather than the design system's `Toast`, which is a provider
+ * and a hook: `Mail` would have to wrap itself in `ToastHost` to use it, and
+ * an application that already has one would then have two regions announcing
+ * into the same page. This is a strip that this component owns.
+ *
+ * `role="status"` is polite, so it waits for a screen reader to finish the
+ * sentence it is on rather than interrupting -- right for "Archived." and
+ * wrong for anything that needs an answer, which is why nothing here asks
+ * for one.
+ */
+function Note({ said, onDone }) {
+    useEffect(() => {
+        if (!said)
+            return;
+        const timer = window.setTimeout(onDone, 4000);
+        return () => window.clearTimeout(timer);
+    }, [said, onDone]);
+    /* Always rendered, so the region exists in the accessibility tree before
+       the text arrives. A live region created at the same moment as its
+       content is a live region most screen readers do not announce. */
+    return (_jsx("output", { className: `mail-note${said ? ' is-shown' : ''}`, "aria-live": "polite", children: said }));
+}
+/** What the letters do, because a client with shortcuts nobody can discover
+ *  has no shortcuts. Reachable on `?` and from the palette. */
+function Shortcuts() {
+    const rows = [
+        ['⌘K', 'Everything — go to a mailbox, or run a command'],
+        ['/', 'Search this mailbox'],
+        ['↑ ↓ or J K', 'Move through the list'],
+        ['C', 'Write a new message'],
+        ['R / A', 'Reply / reply all'],
+        ['F', 'Forward'],
+        ['E', 'Archive'],
+        ['#', 'Delete'],
+        ['U', 'Mark unread'],
+        ['S', 'Flag'],
+        ['?', 'This list'],
+    ];
+    return (_jsx("dl", { className: "keys", children: rows.map(([key, what]) => (_jsxs("div", { className: "keys-row", children: [_jsx("dt", { children: _jsx("kbd", { children: key }) }), _jsx("dd", { children: what })] }, key))) }));
 }

package/dist/mailbox/react/MailboxTree.d.ts

@@ -6,9 +6,11 @@ export type MailboxTreeProps = {
     onSelect: (mailbox: MailboxNode) => void;
     /** Shown in place of the list while the first fetch is out. */
     loading?: boolean;
+    /** Icons only, for a window too narrow to spend a column on names. */
+    rail?: boolean;
     className?: string;
 };
-export declare function MailboxTree({ mailboxes, selectedId, onSelect, loading, className, }: MailboxTreeProps): import("react").JSX.Element;
+export declare function MailboxTree({ mailboxes, selectedId, onSelect, loading, rail, className, }: MailboxTreeProps): import("react").JSX.Element;
 /** Every mailbox flattened, for a caller that needs the list rather than the
  *  tree -- a command palette's "go to" entries, say. */
 export declare function flatMailboxes(nodes: readonly MailboxNode[]): MailboxNode[];

package/dist/mailbox/react/MailboxTree.js

@@ -1,5 +1,5 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Icon, ScrollArea } from '@wtfalch/design';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Icon, ScrollArea, Skeleton } from '@wtfalch/design';
 import { walk } from "../mailboxes.js";
 /**
  * The mailboxes, down the side.
@@ -12,20 +12,39 @@ import { walk } from "../mailboxes.js";
  * server's order underneath. That reordering belongs here rather than in
  * `mailboxes()`, which reports what the server said.
  *
+ * **The roles and the folders are two lists with a rule between them.** They
+ * were one list, and a mailbox called "Archive 2019" sat in the run of
+ * Inbox/Drafts/Sent looking like part of the furniture. The six roles are
+ * the client's; everything under "Folders" is the person's.
+ *
+ * **A folder gets no icon.** The role icons mean something -- an envelope is
+ * the inbox, a paper plane is what you sent -- and giving every user folder
+ * the same generic folder glyph adds a column of identical marks that carry
+ * no information and cost the names their indentation. Depth is drawn with
+ * space, which is what depth is.
+ *
  * **The unread count is threads, not messages**, to agree with the list beside
  * it: a conversation with four unread replies is one bold row there and should
- * be one in the count.
+ * be one in the count. It sits in a fixed-width slot so a count arriving does
+ * not shorten the name beside it.
+ *
+ * **`rail` is the same list with the names taken away**, for the width where
+ * three columns will not fit and the names are the least valuable of them.
+ * The name becomes the accessible label rather than disappearing.
  */
 /** The order a mail client draws the roles it knows. Anything else sorts
  *  after, in the order the server gave. */
 const ROLE_ORDER = ['inbox', 'drafts', 'sent', 'archive', 'junk', 'trash'];
+/* The set gained these in `@wtfalch/design` 0.5.0. Before that Inbox was a
+   speech bubble, Sent was a download and Deleted Items was a close cross --
+   the right shapes for three different words. */
 const ROLE_ICON = {
-    inbox: 'chat',
-    drafts: 'file',
-    sent: 'download',
+    inbox: 'mail',
+    drafts: 'pen',
+    sent: 'send',
     archive: 'folder',
     junk: 'warning',
-    trash: 'close',
+    trash: 'trash',
 };
 export function orderForReading(nodes) {
     const rank = (node) => {
@@ -34,16 +53,27 @@ export function orderForReading(nodes) {
     };
     return [...nodes].sort((a, b) => rank(a) - rank(b));
 }
-export function MailboxTree({ mailboxes, selectedId, onSelect, loading = false, className, }) {
+/** The client's mailboxes and the person's, split where the rule goes. */
+function partition(nodes) {
+    const ordered = orderForReading(nodes);
+    return {
+        roles: ordered.filter((node) => node.role && ROLE_ICON[node.role]),
+        folders: ordered.filter((node) => !node.role || !ROLE_ICON[node.role]),
+    };
+}
+export function MailboxTree({ mailboxes, selectedId, onSelect, loading = false, rail = false, className, }) {
+    const classes = `mailboxes${rail ? ' is-rail' : ''}${className ? ` ${className}` : ''}`;
     if (loading && mailboxes.length === 0) {
-        return (_jsx("nav", { className: `mailboxes${className ? ` ${className}` : ''}`, "aria-label": "Mailboxes", children: _jsx("p", { className: "mailboxes-quiet", children: "Loading\u2026" }) }));
+        return (_jsx("nav", { className: classes, "aria-label": "Mailboxes", "aria-busy": "true", children: _jsx("ul", { className: "mailboxes-list", children: [0, 1, 2, 3, 4].map((n) => (_jsxs("li", { className: "mailbox is-skeleton", children: [_jsx(Skeleton, { variant: "rounded", width: "1.1rem", height: 4 }), !rail && _jsx(Skeleton, { width: `${45 + n * 8}%`, height: 2.5 })] }, n))) }) }));
     }
-    const ordered = orderForReading(mailboxes);
-    return (_jsx(ScrollArea, { className: `mailboxes${className ? ` ${className}` : ''}`, label: "Mailboxes", children: _jsx("nav", { "aria-label": "Mailboxes", children: _jsx("ul", { className: "mailboxes-list", children: ordered.map((node) => (_jsx(MailboxRow, { node: node, depth: 0, selectedId: selectedId, onSelect: onSelect }, node.id))) }) }) }));
+    const { roles, folders } = partition(mailboxes);
+    return (_jsx(ScrollArea, { className: classes, label: "Mailboxes", children: _jsxs("nav", { "aria-label": "Mailboxes", children: [_jsx("ul", { className: "mailboxes-list", children: roles.map((node) => (_jsx(MailboxRow, { node: node, depth: 0, selectedId: selectedId, onSelect: onSelect, rail: rail }, node.id))) }), folders.length > 0 && (_jsxs(_Fragment, { children: [_jsx("h3", { className: "mailboxes-heading", children: rail ? _jsx("span", { className: "rule" }) : 'Folders' }), _jsx("ul", { className: "mailboxes-list", children: folders.map((node) => (_jsx(MailboxRow, { node: node, depth: 0, selectedId: selectedId, onSelect: onSelect, rail: rail }, node.id))) })] }))] }) }));
 }
-function MailboxRow({ node, depth, selectedId, onSelect, }) {
+function MailboxRow({ node, depth, selectedId, onSelect, rail, }) {
     const unread = node.unreadThreads;
-    return (_jsxs("li", { children: [_jsxs("button", { type: "button", className: `mailbox${node.id === selectedId ? ' on' : ''}${unread > 0 ? ' unread' : ''}`, style: { '--depth': depth }, onClick: () => onSelect(node), "aria-current": node.id === selectedId ? 'true' : undefined, children: [node.role && ROLE_ICON[node.role] && (_jsx(Icon, { name: ROLE_ICON[node.role], className: "mailbox-icon" })), _jsx("span", { className: "mailbox-name", children: node.name }), unread > 0 && (_jsxs("span", { className: "mailbox-count", children: [unread, _jsx("span", { className: "sr-only", children: " unread" })] }))] }), node.children.length > 0 && (_jsx("ul", { className: "mailboxes-list", children: node.children.map((child) => (_jsx(MailboxRow, { node: child, depth: depth + 1, selectedId: selectedId, onSelect: onSelect }, child.id))) }))] }));
+    const icon = node.role ? ROLE_ICON[node.role] : undefined;
+    const selected = node.id === selectedId;
+    return (_jsxs("li", { children: [_jsxs("button", { type: "button", className: `mailbox${selected ? ' on' : ''}${unread > 0 ? ' unread' : ''}`, style: { '--depth': depth }, onClick: () => onSelect(node), "aria-current": selected ? 'true' : undefined, "aria-label": rail ? `${node.name}${unread > 0 ? `, ${unread} unread` : ''}` : undefined, title: rail ? node.name : undefined, children: [_jsx("span", { className: "mailbox-icon", "aria-hidden": "true", children: icon ? _jsx(Icon, { name: icon, size: 17 }) : _jsx("span", { className: "mailbox-pip" }) }), !rail && _jsx("span", { className: "mailbox-name", children: node.name }), !rail && (_jsx("span", { className: "mailbox-count", children: unread > 0 && (_jsxs(_Fragment, { children: [unread, _jsx("span", { className: "sr-only", children: " unread" })] })) })), rail && unread > 0 && _jsx("span", { className: "mailbox-pip is-unread", "aria-hidden": "true" })] }), node.children.length > 0 && (_jsx("ul", { className: "mailboxes-list", children: node.children.map((child) => (_jsx(MailboxRow, { node: child, depth: depth + 1, selectedId: selectedId, onSelect: onSelect, rail: rail }, child.id))) }))] }));
 }
 /** Every mailbox flattened, for a caller that needs the list rather than the
  *  tree -- a command palette's "go to" entries, say. */

package/dist/mailbox/react/ThreadList.d.ts

@@ -2,19 +2,35 @@ import type { ThreadPage, ThreadSummary } from '../types.ts';
 /**
  * The list of conversations, and what a row of it has to say.
  *
- * **Unread is weight, not colour.** A blue dot beside a subject is invisible
- * to a reader who cannot distinguish it and disappears on a projector; the
- * whole row goes to the strong weight instead, which survives both. The dot
- * is there as well, because two signals are better than one, and it carries
- * the accessible text that says which rows they are.
+ * **Two lines, not four.** The row that was here stacked sender, subject,
+ * preview and a row of word-shaped pills, which came to about 140px: four
+ * conversations to a laptop screen, and a mailbox with sixty in it takes
+ * fifteen screens to scan. Sender and time on one line, subject and preview
+ * sharing the second, marks as glyphs rather than words -- that is around
+ * 60px, and the whole point of a list is how much of it you can see at once.
+ *
+ * **Unread is weight and a rail, not colour and not a bullet in the text.**
+ * A blue dot beside a subject is invisible to a reader who cannot distinguish
+ * it and disappears on a projector. The row goes to the strong weight, and a
+ * 3px bar sits in the gutter -- outside the text, so a read row and an unread
+ * row start their subjects at the same x. The bullet that used to be inline
+ * moved every subject two characters to the right and only on unread rows,
+ * which read as a rendering fault.
+ *
+ * **The rows are grouped by day, and the heading sticks.** Scrolling a long
+ * mailbox with no landmarks is how you lose your place; "Yesterday" pinned to
+ * the top of the viewport is the cheapest orientation there is. Groups are
+ * computed from the same `now` the relative times use, so a story and a
+ * screenshot hold still.
  *
  * **The time is relative and titled.** "12m" is what you scan; the full
  * timestamp is in the `title` and the `dateTime`, so hovering and a screen
- * reader both get the real thing. A list of absolute timestamps is a list
- * nobody reads.
+ * reader both get the real thing.
  *
- * **A conversation says how many messages it holds**, because "3" beside a
- * subject is the difference between one mail and a thread you are behind on.
+ * **Arrow keys move, and focus follows.** The list is a single tab stop --
+ * one row is `tabIndex=0` and the rest are `-1` -- so tabbing through the
+ * client does not mean tabbing through sixty conversations. Within it, the
+ * arrows and `j`/`k` move the selection.
  */
 export type ThreadListProps = {
     page: ThreadPage | undefined;
@@ -26,12 +42,28 @@ export type ThreadListProps = {
     loading?: boolean;
     /** Shown when there is nothing, instead of an empty box. */
     empty?: React.ReactNode;
-    /** Now, for the relative times. Passed in so a story and a screenshot are
-     *  stable rather than drifting with the clock. */
+    /** The mailbox being listed, for the heading above the rows. */
+    title?: string;
+    /** Now, for the relative times and the day grouping. Passed in so a story
+     *  and a screenshot are stable rather than drifting with the clock. */
     now?: Date;
     className?: string;
 };
-/** "12m", "3h", "Tue", "14 Mar" -- coarser the further back it is, because
- *  precision stops being useful and starts being noise. */
+/** "12m", "3h", "09:42", "Tue", "14 Mar" -- coarser the further back it is,
+ *  because precision stops being useful and starts being noise.
+ *
+ *  Yesterday is the clock rather than the weekday, and that is not a detail:
+ *  the row sits under a heading that already says "Yesterday", so printing
+ *  "Wed" beside it spends the column on a word the reader has just read. The
+ *  time is the thing they do not know. */
 export declare function shortTime(iso: string, now?: Date): string;
-export declare function ThreadList({ page, selectedId, onSelect, onPage, limit, loading, empty, now, className, }: ThreadListProps): import("react").JSX.Element;
+/**
+ * The heading a row sits under.
+ *
+ * Calendar days apart, not hours apart: a message at 00:30 and one at 23:30
+ * are 23 hours apart and both "today", and a rule written in hours puts them
+ * in different groups, which is the sort of thing nobody reports as a bug and
+ * everybody finds confusing.
+ */
+export declare function dayGroup(iso: string, now?: Date): string;
+export declare function ThreadList({ page, selectedId, onSelect, onPage, limit, loading, empty, title, now, className, }: ThreadListProps): import("react").JSX.Element;