nexus-shared 3.2.0 → 4.1.0

package/dist/Components/Messages/MailThread.js

@@ -0,0 +1,185 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { iconArchive, InlineIcon } from "nexus-icons";
+import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { flushSync } from "react-dom";
+import { chatDomainLabel } from "../../Helpers/ChatBackend.js";
+import { chatDayLabel, chatLocalDate, chatTimeLabel, sameChatId } from "../../Helpers/ChatHelpers.js";
+import { useChat } from "../../Helpers/ChatHooks.js";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { useBrowserTimeZone, useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { formatDateTime } from "../../Helpers/DateTimeHelpers.js";
+import { mailBccNote, mailPeopleLine, MAIL_ROLE_LABELS } from "../../Helpers/MessageHelpers.js";
+import { ChatComposer } from "../Chats/ChatComposer.js";
+import { ChatFailure } from "../Chats/ChatParts.js";
+import { ChatThread } from "../Chats/ChatThread.js";
+import { DomainCard, DomainLine } from "../Domains/DomainCard.js";
+/** Under this width (px) a record's card opens folded to its title and figures, the details a press away. */
+const NARROW_THREAD = 480;
+/** The words of a thread the reader may not open: a stranger learns nothing more. */
+const REFUSED = "This message is not available to you.";
+const errorStatus = (error) => {
+    const status = error?.status;
+    return typeof status === "number" ? status : undefined;
+};
+const isAbort = (error) => error?.name === "AbortError";
+/** A mail thread: the head with its people and record, the lines, and the reply box. */
+export function MailThread({ source, threadId, userId, head: givenHead, renderDomain, actions, headingLevel = 2, peopleShown = 3, onChanged, onHead, onSummary, pageSize, pollInterval, height, className, }) {
+    const [head, setHead] = useState(givenHead && sameChatId(givenHead.id, threadId) ? givenHead : null);
+    const [headState, setHeadState] = useState({ status: head ? "ready" : "loading" });
+    const [attempt, setAttempt] = useState(0);
+    const [revision, setRevision] = useState(0);
+    const [replyTo, setReplyTo] = useState(null);
+    const latest = useRef({ onChanged, onHead, onSummary, head });
+    // How wide the thread is, followed as it changes. A window still laying out reads 0 (its dialog is not open yet), so the
+    // record's card waits for a real width before it is drawn - the first one drawn before the browser paints - and then
+    // folds or unfolds with the width, until the reader folds or unfolds it themselves.
+    const frame = useRef(null);
+    const [narrow, setNarrow] = useState(null);
+    const [folded, setFolded] = useState(null);
+    useLayoutEffect(() => {
+        const element = frame.current;
+        if (!element)
+            return;
+        let known = false;
+        const read = () => {
+            const width = element.clientWidth;
+            if (width <= 0)
+                return;
+            const next = width < NARROW_THREAD;
+            if (known)
+                setNarrow(next);
+            else
+                flushSync(() => setNarrow(next));
+            known = true;
+        };
+        const width = element.clientWidth;
+        if (width > 0) {
+            setNarrow(width < NARROW_THREAD);
+            known = true;
+        }
+        const observer = new ResizeObserver(read);
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, []);
+    latest.current = { onChanged, onHead, onSummary, head };
+    const chatSource = useMemo(() => source.threadSource(threadId), [source, threadId]);
+    // A mail thread is not a record's place: the scope only keys the store, and the conversation id keeps the page's
+    // count cache (the chat icons' counts) out of it.
+    const scope = useMemo(() => ({ domain: "mail", parentId: threadId, userId }), [threadId, userId]);
+    const refused = headState.status === "refused";
+    const { store, state } = useChat({ scope, conversationId: threadId, source: chatSource, pageSize, pollInterval, enabled: !refused });
+    const take = useCallback((next) => {
+        setHead(next);
+        setHeadState({ status: "ready" });
+        latest.current.onHead?.(next);
+    }, []);
+    // The head, read whenever the thread changes, and again on Retry.
+    useEffect(() => {
+        const controller = new AbortController();
+        if (!latest.current.head || !sameChatId(latest.current.head.id, threadId)) {
+            setHead(null);
+            setHeadState({ status: "loading" });
+        }
+        source.thread(threadId, controller.signal).then(take, error => {
+            if (controller.signal.aborted || isAbort(error))
+                return;
+            const status = errorStatus(error);
+            if (status === 403 || status === 404)
+                setHeadState({ status: "refused", message: REFUSED });
+            else
+                setHeadState({ status: "failed", message: error instanceof Error && error.message ? error.message : "The message could not be loaded." });
+        });
+        return () => controller.abort();
+    }, [source, threadId, attempt, take]);
+    // Read again quietly when the people may have changed: the head on screen stays until the new one lands.
+    const refreshHead = useCallback(() => {
+        source.thread(threadId).then(take, () => {
+            // A refresh that failed leaves the head as it was; the next line tries again.
+        });
+    }, [source, threadId, take]);
+    // What arrived since the last look: someone else's lines read the head again and tell the page; a reply of this
+    // reader's while copied unseen reads it again too, since it made them a Cc.
+    const primed = useRef(false);
+    const newest = useRef(null);
+    useEffect(() => {
+        // Another thread starts its own count: its first page is what it holds, not what arrived.
+        primed.current = false;
+        newest.current = null;
+    }, [threadId]);
+    useEffect(() => {
+        if (!state.loaded)
+            return;
+        const saved = state.messages.filter(message => message.status !== "sending" && message.status !== "failed");
+        const last = saved[saved.length - 1];
+        const key = last ? String(last.id) : null;
+        const before = newest.current;
+        newest.current = key;
+        if (!primed.current) {
+            primed.current = true;
+            return;
+        }
+        if (key === before)
+            return;
+        const from = before === null ? -1 : saved.findIndex(message => String(message.id) === before);
+        const fresh = saved.slice(from + 1);
+        const theirs = fresh.filter(message => !sameChatId(message.authorId, userId));
+        const mineAsBcc = latest.current.head?.myRole === "bcc" && fresh.some(message => sameChatId(message.authorId, userId));
+        if (theirs.length > 0 || mineAsBcc)
+            refreshHead();
+        if (theirs.length === 0)
+            return;
+        const notification = theirs.some(message => message.kind === "notification");
+        if (notification)
+            setRevision(count => count + 1);
+        latest.current.onChanged?.({ reason: notification ? "notification" : "reply", messages: theirs });
+    }, [state.loaded, state.messages, userId, refreshHead]);
+    useEffect(() => {
+        latest.current.onSummary?.(state.summary);
+    }, [state.summary]);
+    const preferences = useDatePreferences();
+    const zone = useBrowserTimeZone();
+    const time = useMemo(() => ({ ...preferences, ...(zone && { timeZone: zone }) }), [preferences, zone]);
+    const style = height === undefined ? undefined : { "--nx-chat-height": typeof height === "number" ? `${height}px` : height };
+    const Heading = `h${headingLevel}`;
+    const note = mailBccNote(head);
+    if (refused) {
+        return (_jsx("div", { className: cx("nx-chat-panel", "nx-mail", className), style: style, children: _jsx("div", { className: "nx-mail__refused", role: "alert", children: _jsx("p", { children: headState.message }) }) }));
+    }
+    // The head opens the thread's one scroll (its lead): a tall record's card is read by scrolling the thread, not in a box.
+    const headBand = (_jsx("header", { className: "nx-mail__head", "aria-busy": headState.status === "loading" || undefined, children: headState.status === "failed" && !head ? (_jsx(ChatFailure, { message: headState.message, onRetry: () => setAttempt(count => count + 1) })) : (_jsxs(_Fragment, { children: [_jsxs("div", { className: "nx-mail__title", children: [_jsx(Heading, { className: "nx-mail__subject", tabIndex: -1, "data-nx-focus": "", children: head ? head.subject : _jsx("span", { className: "nx-table__bone nx-record__bone nx-mail__bone", style: { width: "16rem" } }) }), head?.archived && (_jsxs("span", { className: "nx-table__tag nx-table__tag--plain nx-mail__archived", children: [_jsx(InlineIcon, { icon: iconArchive }), " Archived"] })), head && _jsx(MailTime, { value: head.createdTime, time: time }), actions && _jsx("span", { className: "nx-mail__actions", children: actions })] }), _jsx("dl", { className: "nx-mail__people", children: head ? (_jsxs(_Fragment, { children: [_jsx(MailPeopleRow, { role: "from", people: [head.from], userId: userId, shown: peopleShown }), _jsx(MailPeopleRow, { role: "to", people: head.to, userId: userId, shown: peopleShown }), head.cc.length > 0 && _jsx(MailPeopleRow, { role: "cc", people: head.cc, userId: userId, shown: peopleShown }), head.bcc.length > 0 && _jsx(MailPeopleRow, { role: "bcc", people: head.bcc, userId: userId, shown: peopleShown })] })) : (_jsxs(_Fragment, { children: [_jsx(MailBoneRow, { label: MAIL_ROLE_LABELS.from, width: "9rem" }), _jsx(MailBoneRow, { label: MAIL_ROLE_LABELS.to, width: "13rem" })] })) }), head?.domain &&
+                    (renderDomain ? (renderDomain(head.domain, { head, revision })) : (narrow !== null && (_jsx(DomainCard, { domain: head.domain.domainType, id: head.domain.id, label: head.domain.label, revision: revision, viewer: userId, headingLevel: (headingLevel + 1), collapsed: folded ?? narrow, onCollapsedChange: setFolded })))), headState.status === "failed" && head && _jsx(ChatFailure, { message: headState.message, onRetry: () => setAttempt(count => count + 1) })] })) }));
+    return (_jsxs("div", { ref: frame, className: cx("nx-chat-panel", "nx-mail", className), style: style, children: [_jsx("div", { className: "nx-chat-panel__body", children: _jsx(ChatThread, { store: store, state: state, userId: userId, onReply: setReplyTo, emptyMessage: "Nothing in this thread yet.", lead: headBand }) }), _jsx(ChatComposer, { store: store, state: state, draftKey: `mail:${String(threadId)}:${String(userId)}`, placeholder: "Write a reply\u2026", replyTo: replyTo, onCancelReply: () => setReplyTo(null), notice: note, readOnlyMessage: "This thread is closed: it can be read, not answered." })] }));
+}
+/** When the thread was started: the day and the time in the reader's settings, the full moment on hover. */
+function MailTime({ value, time }) {
+    if (!value)
+        return null;
+    const day = chatLocalDate(value, time.timeZone);
+    return (_jsx("time", { className: "nx-mail__time", dateTime: value, title: formatDateTime(value, time), children: day ? `${chatDayLabel(day, time)} · ${chatTimeLabel(value, time)}` : chatTimeLabel(value, time) }));
+}
+/** A line of the head held while it loads: the role's word and a bone where the names go. */
+function MailBoneRow({ label, width }) {
+    return (_jsxs("div", { className: "nx-mail__row", children: [_jsx("dt", { children: label }), _jsx("dd", { children: _jsx("span", { className: "nx-table__bone nx-record__bone nx-mail__bone", style: { width } }) })] }));
+}
+/** One line of the head: a role and its people, folded to a few names and "+2" until it is opened. */
+function MailPeopleRow({ role, people, userId, shown }) {
+    return (_jsxs("div", { className: "nx-mail__row", "data-role": role, children: [_jsx("dt", { children: MAIL_ROLE_LABELS[role] }), _jsx("dd", { children: _jsx(MailPeople, { people: people, userId: userId, shown: shown }) })] }));
+}
+/**
+ * A list of people on one line, folded to its first names and a "+2" button that opens the rest in place: a thread sent
+ * to fifty people keeps a head of a few lines. Someone who has left keeps their name, muted.
+ */
+export function MailPeople({ people, userId, shown = 3, empty = "Nobody" }) {
+    const [open, setOpen] = useState(false);
+    const listId = useId();
+    const line = mailPeopleLine(people, shown);
+    if (people.length === 0)
+        return _jsx("span", { className: "nx-mail__nobody", children: empty });
+    const visible = open ? people : line.shown;
+    return (_jsxs("span", { id: listId, children: [visible.map((person, index) => (_jsxs("span", { className: cx("nx-mail__name", person.isActive === false && "nx-mail__name--inactive"), title: person.isActive === false ? `${person.name} has left` : undefined, children: [person.name, userId !== undefined && sameChatId(person.id, userId) && _jsx("span", { className: "nx-mail__you", children: "you" }), index < visible.length - 1 && ","] }, `${String(person.id)}-${index}`))), line.more > 0 && (_jsx("button", { type: "button", className: "nx-mail__more", "aria-expanded": open, "aria-controls": listId, "aria-label": open ? "Show fewer" : `Show ${line.more} more: ${people.slice(line.shown.length).map(person => person.name).join(", ")}`, onClick: () => setOpen(was => !was), children: open ? "Fewer" : `+${line.more}` }))] }));
+}
+/** The record a thread is about, as its words alone: the kind's name as the app gave it, and the record's own words. */
+export function MailDomainLine({ domain }) {
+    return _jsx(DomainLine, { kind: chatDomainLabel(domain.domainType), label: domain.label });
+}

package/dist/Components/Messages/MessageBell.d.ts

@@ -0,0 +1,41 @@
+import { type IconNode } from "nexus-icons";
+import { type ChatTimeOptions } from "../../Helpers/ChatHelpers.ts";
+import { type MessageUnreadSnapshot } from "../../Helpers/MessageUnread.ts";
+import type { MailInboxRow, MessageSource } from "../../Interfaces/MailInterfaces.ts";
+export interface UseMessageUnreadOptions {
+    /** Milliseconds between reads while the page is in front. Default a minute. */
+    interval?: number;
+    /** Joins the page's reads. False shows what is known without reading. Default true. */
+    enabled?: boolean;
+}
+/** What `useMessageUnread` gives: the count and the newest, `refresh()`, and whether this one speaks for the page. */
+export interface MessageUnreadHandle extends MessageUnreadSnapshot {
+    refresh: () => void;
+    /** The first drawn of the page's bells on this source: the one with the live region. */
+    speaks: boolean;
+}
+/** The page's unread count for a mailbox, shared by every component that asks: one read however many there are. */
+export declare function useMessageUnread(source: Pick<MessageSource, "unread">, { interval, enabled }?: UseMessageUnreadOptions): MessageUnreadHandle;
+export interface MessageBellProps {
+    /** The mailbox: `apiMessageSource()`, or anything with `unread()`. One source object per page shares one poller. */
+    source: Pick<MessageSource, "unread">;
+    /** The inbox. A thread opens at `href?thread=<id>`. */
+    href: string;
+    /** A thread's address, instead of `href?thread=<id>`. */
+    threadHref?: (row: MailInboxRow) => string;
+    /** What the button is called, before its count. Default "Messages". */
+    label?: string;
+    /** Milliseconds between reads while the page is in front. Default a minute. */
+    interval?: number;
+    /** Default `md`, the bar's size. */
+    size?: "sm" | "md";
+    /** Default a bell. */
+    icon?: IconNode;
+    /** The largest count the badge writes before "99+". Default 99. */
+    maxBadge?: number;
+    /** The reader's date settings, for "14 min ago". Default their own. */
+    time?: ChatTimeOptions;
+    className?: string;
+}
+/** The unread count on a top bar's button, and the newest unread a click away. See the notes at the top of this file. */
+export declare function MessageBell({ source, href, threadHref, label, interval, size, icon, maxBadge, time, className }: MessageBellProps): import("react").JSX.Element;

package/dist/Components/Messages/MessageBell.js

@@ -0,0 +1,76 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconBell, InlineIcon } from "nexus-icons";
+import { useEffect, useMemo, useRef, useSyncExternalStore } from "react";
+import { chatTimeAgo } from "../../Helpers/ChatHelpers.js";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { useBrowserTimeZone, useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { MESSAGE_UNREAD_INTERVAL, mailThreadHref, mailUnreadBadge, mailUnreadWords, messageUnreadPoller, } from "../../Helpers/MessageUnread.js";
+import { Button } from "../Documents/Button.js";
+import { Menu } from "../Documents/Menu.js";
+/** The page's unread count for a mailbox, shared by every component that asks: one read however many there are. */
+export function useMessageUnread(source, { interval = MESSAGE_UNREAD_INTERVAL, enabled = true } = {}) {
+    const poller = messageUnreadPoller(source);
+    const snapshot = useSyncExternalStore(poller.subscribe, poller.getSnapshot, poller.getSnapshot);
+    const member = useRef(null);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const joined = poller.join(interval);
+        member.current = joined;
+        return () => {
+            joined.leave();
+            if (member.current === joined)
+                member.current = null;
+        };
+    }, [poller, interval, enabled]);
+    return { ...snapshot, refresh: () => poller.refresh(), speaks: member.current?.speaks() ?? false };
+}
+/** What the button says it holds: its label and the count in words, or why there is none. */
+function describe(label, unread, max) {
+    if (unread.status === "idle" || unread.status === "loading")
+        return `${label}: not checked yet`;
+    if (unread.status === "failed")
+        return `${label}: could not be checked`;
+    return `${label}: ${mailUnreadWords(unread.count, max).toLowerCase()}`;
+}
+/** The unread count on a top bar's button, and the newest unread a click away. See the notes at the top of this file. */
+export function MessageBell({ source, href, threadHref, label = "Messages", interval, size = "md", icon = iconBell, maxBadge = 99, time, className }) {
+    const unread = useMessageUnread(source, { interval });
+    const preferences = useDatePreferences();
+    const zone = useBrowserTimeZone();
+    const settings = useMemo(() => ({ ...preferences, ...(zone && { timeZone: zone }), ...time }), [preferences, zone, time]);
+    const words = describe(label, unread, maxBadge);
+    const badge = unread.status === "ready" ? mailUnreadBadge(unread.count, maxBadge) : "";
+    const shown = unread.newest.reduce((total, row) => total + Math.max(0, row.unreadCount), 0);
+    const heading = unread.status === "idle" || unread.status === "loading"
+        ? "Checking for messages"
+        : unread.status === "failed"
+            ? "Could not check for messages"
+            : unread.count > 0
+                ? "Unread"
+                : "Nothing unread";
+    const items = [
+        { heading },
+        ...unread.newest.map(row => ({
+            value: `thread:${String(row.id)}`,
+            label: row.subject,
+            // Who wrote the newest line and when: the line that made it unread (the thread's sender wrote the first).
+            description: [row.lastAuthorName || row.fromName, row.domainLabel, chatTimeAgo(row.lastMessageTime, settings)].filter(Boolean).join(" · "),
+            href: threadHref ? threadHref(row) : mailThreadHref(href, row.id),
+            title: row.subject,
+        })),
+        ...(unread.failed ? [{ value: "retry", label: "Try again", description: unread.status === "ready" ? "The count shown is from before." : undefined }] : []),
+        { separator: true },
+        {
+            value: "inbox",
+            label: "Open inbox",
+            // What the list leaves out: the threads past the newest eight.
+            description: unread.count > shown && shown > 0 ? `${mailUnreadWords(unread.count, maxBadge)} in all` : undefined,
+            href,
+        },
+    ];
+    // Said once when the count goes up, by the first bell of the page; an invisible space tells two same words apart.
+    const spoken = unread.spoken ? `${unread.spoken.text}${unread.spoken.seq % 2 ? String.fromCharCode(160) : ""}` : "";
+    return (_jsxs(_Fragment, { children: [_jsx(Menu, { items: items, align: "end", "aria-label": unread.status === "ready" ? `${label}: ${mailUnreadWords(unread.count, maxBadge).toLowerCase()}` : label, className: "nx-message-bell__menu", onOpenChange: open => open && unread.refresh(), onSelect: value => value === "retry" && unread.refresh(), children: _jsx(Button, { variant: "ghost", size: size, className: cx("nx-message-bell", className), icon: _jsx(InlineIcon, { icon: icon }), badge: badge, "aria-label": words, title: words }) }), unread.speaks && (_jsx("span", { className: "nx-visually-hidden", "aria-live": "polite", children: spoken }))] }));
+}