@wtfalch/email 0.1.1 → 0.3.0

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

@@ -1,8 +1,52 @@
 import type { MailClient } from '../client.ts';
+import type { MailError } from '../errors.ts';
+/**
+ * Where the reader is: which mailbox, which conversation.
+ *
+ * Its own type because an application that puts this in the URL has to be
+ * able to name it.
+ */
+export type MailLocation = {
+    mailboxId: string | null;
+    threadId: string | null;
+};
 export type MailProps = {
     client: MailClient;
+    /**
+     * Drive the selection from outside — from the URL, almost always.
+     *
+     * Omit it and the component keeps its own, which is right for a gallery or
+     * an embed. Supply it with `onNavigate` and the two selections become the
+     * application's: `/inbox` and `/thread/abc` can be real addresses that
+     * survive a reload, appear in history and can be sent to someone.
+     *
+     * A partially controlled component is a trap, so this is all or nothing:
+     * pass `location` and you own both fields.
+     */
+    location?: MailLocation;
+    /** Called when something in here wants to move. Required with `location`,
+     *  because without it the controlled selection could never change. */
+    onNavigate?: (to: MailLocation) => void;
+    /**
+     * The right-hand end of the header: who is signed in, and the way out.
+     *
+     * A slot rather than anything this component builds, because `Mail` does
+     * not know how the person got here. It has no idea whether there is a
+     * session, a token, an issuer or a sign-out — and a mail view that grew
+     * opinions about authentication would be a mail view nobody could embed.
+     */
+    account?: React.ReactNode;
+    /**
+     * Called when any of the fetches behind this view fails.
+     *
+     * The views already say "could not load" for themselves; this is for the
+     * application to act on a *class* of failure it alone can answer. The one
+     * that matters is 401: the token expired mid-session, and only the thing
+     * that obtained it can get another.
+     */
+    onError?: (error: MailError) => void;
     /** Now, for the list's relative times. Passed in so stories hold still. */
     now?: Date;
     className?: string;
 };
-export declare function Mail({ client, now, className }: MailProps): import("react").JSX.Element;
+export declare function Mail({ client, location, onNavigate, account, onError, now, className, }: MailProps): import("react").JSX.Element;

package/dist/mailbox/react/Mail.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Button, Command, Icon, Input, Modal, SplitPane } from '@wtfalch/design';
-import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { forwardDraft, replyDraft } from "../drafts.js";
 import { findRole } from "../mailboxes.js";
 import { send } from "../submit.js";
@@ -27,9 +27,25 @@ import { useIdentities, useMailboxes, usePush, useThread, useThreads } from "./h
  * mailboxes as "go to" entries, so moving around never requires the mouse.
  */
 const PAGE = 50;
-export function Mail({ client, now, className }) {
-    const [mailboxId, setMailboxId] = useState(null);
-    const [threadId, setThreadId] = useState(null);
+export function Mail({ client, location, onNavigate, account, onError, now, className, }) {
+    const [ownMailboxId, setOwnMailboxId] = useState(null);
+    const [ownThreadId, setOwnThreadId] = useState(null);
+    /* Controlled when a location was given, and then entirely: reading one
+       field from the caller and the other from here is how a component ends up
+       with two disagreeing ideas of where it is. */
+    const controlled = location !== undefined;
+    const mailboxId = controlled ? location.mailboxId : ownMailboxId;
+    const threadId = controlled ? location.threadId : ownThreadId;
+    const navigate = useCallback((to) => {
+        if (controlled)
+            onNavigate?.(to);
+        else {
+            setOwnMailboxId(to.mailboxId);
+            setOwnThreadId(to.threadId);
+        }
+    }, [controlled, onNavigate]);
+    const setMailboxId = useCallback((next) => navigate({ mailboxId: next, threadId: null }), [navigate]);
+    const setThreadId = useCallback((next) => navigate({ mailboxId, threadId: next }), [navigate, mailboxId]);
     const [position, setPosition] = useState(0);
     const [query, setQuery] = useState('');
     const [text, setText] = useState('');
@@ -48,7 +64,7 @@ export function Mail({ client, now, className }) {
         const inbox = findRole(boxes.data, 'inbox') ?? boxes.data[0];
         if (inbox)
             setMailboxId(inbox.id);
-    }, [boxes.data, mailboxId]);
+    }, [boxes.data, mailboxId, setMailboxId]);
     const threads = useThreads({ mailboxId: mailboxId ?? undefined, text: query, position, limit: PAGE, calculateTotal: true }, client);
     const thread = useThread(threadId, client);
     const refresh = useCallback(() => {
@@ -56,14 +72,24 @@ export function Mail({ client, now, className }) {
         threads.reload();
     }, [boxes.reload, threads.reload]);
     usePush(refresh, client);
+    /* Errors reach the application, but only when they change: these hooks hold
+       their last error while a retry is in flight, so forwarding on every
+       render would call `onError` sixty times for one dead token. */
+    const failure = boxes.error ?? threads.error ?? thread.error ?? identities.error;
+    const reported = useRef(undefined);
+    useEffect(() => {
+        if (!failure || reported.current === failure)
+            return;
+        reported.current = failure;
+        onError?.(failure);
+    }, [failure, onError]);
     const go = useCallback((mailbox) => {
-        setMailboxId(mailbox.id);
-        setThreadId(null);
+        navigate({ mailboxId: mailbox.id, threadId: null });
         setPosition(0);
         setQuery('');
         setText('');
-    }, []);
-    const openThread = useCallback((summary) => setThreadId(summary.id), []);
+    }, [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. */
@@ -145,5 +171,5 @@ export function Mail({ client, now, className }) {
                                     return;
                                 setText('');
                                 setQuery('');
-                            } }) }), _jsx(Button, { kind: "ghost", onClick: () => setPaletteOpen(true), "aria-label": "Open the palette", children: _jsx(Icon, { name: "bolt" }) })] }), _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 }) }))] }));
+                            } }) }), _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 }) }))] }));
 }

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

@@ -21,4 +21,4 @@ export type { ThreadViewProps } from './ThreadView.tsx';
 export { Composer, parseAddresses } from './Composer.tsx';
 export type { ComposerProps } from './Composer.tsx';
 export { Mail } from './Mail.tsx';
-export type { MailProps } from './Mail.tsx';
+export type { MailLocation, MailProps } from './Mail.tsx';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/email",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "The wtfalch estate: reading a mailbox over JMAP, and administering the Stalwart server it lives on. Two entries with no code in common.",
   "license": "MIT",
   "type": "module",