@wtfalch/email 0.1.0 → 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/dist/postmaster/apply.d.ts

@@ -1,4 +1,3 @@
-import 'server-only';
 import type { Instance } from './instance.js';
 export interface Applied {
     /** For the audit row's `targetType`. */

package/dist/postmaster/apply.js

@@ -1,4 +1,3 @@
-import 'server-only';
 import { MailWriteRefused, newAccount, withAlias, withoutAlias, withoutAppPassword, } from './writes.js';
 /**
  * The four writes `/email` makes, each as one round trip against the mail

package/dist/postmaster/browser-refusal.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * What a browser bundle gets instead of the administration client.
+ *
+ * This entry reaches a mail server with an administrator credential that, on
+ * Stalwart 0.16, cannot be scoped and is as powerful as the whole account. It
+ * must never end up in something a browser downloads.
+ *
+ * **Why the `browser` condition and not `server-only`.** `server-only` throws
+ * in any environment without React's `react-server` condition, which includes
+ * plain Node — and this entry exists partly so a provisioning CLI can use it,
+ * so that guard broke the legitimate caller while blocking the illegitimate
+ * one. The `browser` condition in the exports map is the tool that tells them
+ * apart: a bundler targeting a browser resolves here, while Node and a React
+ * Server Components build resolve the real module.
+ *
+ * It throws at import rather than exporting stubs, so the failure is at build
+ * or first load with a sentence saying what to do, not a runtime mystery
+ * about a client that never answers.
+ */
+throw new Error('@wtfalch/email/postmaster is server-side only: it holds an administrator credential for a mail server and must not be bundled for a browser. Call it from a Server Component, a Server Action, a route handler or a Node script, and render the results with @wtfalch/email/postmaster/react.');

package/dist/postmaster/index.d.ts

@@ -1,12 +1,3 @@
-/**
- * `server-only`, and it is load-bearing rather than decorative. This module
- * reaches a mail server with an administrator credential that, on Stalwart
- * 0.16, cannot be scoped and is as powerful as the whole account. Nothing
- * about living in its own entry stops a client component importing it —
- * bundlers follow imports, not entry names — so the guard that actually
- * fails such a build is this line.
- */
-import 'server-only';
 /**
  * Administer a Stalwart mail server over its JMAP management API: the
  * domain, the mailboxes, their aliases, their app passwords and their

package/dist/postmaster/index.js

@@ -1,12 +1,3 @@
-/**
- * `server-only`, and it is load-bearing rather than decorative. This module
- * reaches a mail server with an administrator credential that, on Stalwart
- * 0.16, cannot be scoped and is as powerful as the whole account. Nothing
- * about living in its own entry stops a client component importing it —
- * bundlers follow imports, not entry names — so the guard that actually
- * fails such a build is this line.
- */
-import 'server-only';
 /**
  * Administer a Stalwart mail server over its JMAP management API: the
  * domain, the mailboxes, their aliases, their app passwords and their

package/dist/postmaster/instance.d.ts

@@ -1,4 +1,3 @@
-import 'server-only';
 import { StalwartClient } from './client.js';
 /**
  * A mail instance and the credential this program acts on it with.

package/dist/postmaster/instance.js

@@ -1,4 +1,3 @@
-import 'server-only';
 import { StalwartClient, authFor } from './client.js';
 /**
  * An instance from a URL and one opaque secret, with the scheme chosen from

package/dist/postmaster/load.d.ts

@@ -1,4 +1,3 @@
-import 'server-only';
 import type { Instance } from './instance.js';
 import { type Overview, type Person } from './overview.js';
 /**

package/dist/postmaster/load.js

@@ -1,4 +1,3 @@
-import 'server-only';
 import { resolveMx } from 'node:dns/promises';
 import { overview, } from './overview.js';
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/email",
-  "version": "0.1.0",
+  "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",
@@ -23,6 +23,7 @@
     },
     "./mailbox/mail.css": "./dist/mailbox/mail.css",
     "./postmaster": {
+      "browser": "./dist/postmaster/browser-refusal.js",
       "types": "./dist/postmaster/index.d.ts",
       "default": "./dist/postmaster/index.js"
     },
@@ -64,10 +65,6 @@
     "typescript": "^5.9.0",
     "vitest": "^4.1.6"
   },
-  "dependencies": {
-    "jmap-jam": "^0.13.6",
-    "server-only": "^0.0.1"
-  },
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
@@ -82,6 +79,9 @@
     "stalwart",
     "rfc8621"
   ],
+  "dependencies": {
+    "jmap-jam": "^0.13.6"
+  },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json && cp src/mailbox/react/mail.css dist/mailbox/mail.css",
     "typecheck": "tsc --noEmit",