nexus-shared 2.0.0 → 3.0.0

package/dist/Components/Chats/ChatButton.d.ts

@@ -0,0 +1,26 @@
+import { type IconNode } from "nexus-icons";
+import { type ComponentPropsWithRef } from "react";
+import { type ChatTimeOptions } from "../../Helpers/ChatHelpers.ts";
+import type { ChatDomainValue, ChatScope, ChatSummary } from "../../Interfaces/ChatInterfaces.ts";
+export interface ChatButtonProps<TDomain extends ChatDomainValue = ChatDomainValue> extends Omit<ComponentPropsWithRef<"button">, "children" | "title" | "aria-label"> {
+    /** Which conversation: the domain, the record, and the reader. */
+    scope: ChatScope<TDomain>;
+    /** The counts, when the row already carries them. Without them the icon asks the page's cache. */
+    summary?: ChatSummary;
+    /** What the conversation is called, in the tooltip and for a screen reader. Default "Discussion". */
+    label?: string;
+    /** Default `md` (34px), as the other controls in a row. `sm` is 28px, for a dense table. */
+    size?: "sm" | "md";
+    /** The largest number the badge writes before "99+". Default 99. */
+    maxBadge?: number;
+    /** The user's date settings, for "3 h ago" in the tooltip. Default: their own. */
+    time?: ChatTimeOptions;
+    /** The icon. Default: a speech bubble. */
+    icon?: IconNode;
+}
+/**
+ * The chat icon for one record: quiet, highlighted, or highlighted with an unread badge. It does not open anything by
+ * itself — `Chat` is the icon with the popup behind it, and a page that holds the conversation somewhere else gives
+ * this one an `onClick`.
+ */
+export declare function ChatButton<TDomain extends ChatDomainValue = ChatDomainValue>({ scope, summary: given, label, size, maxBadge, time, icon, className, ...rest }: ChatButtonProps<TDomain>): import("react").JSX.Element;

package/dist/Components/Chats/ChatButton.js

@@ -0,0 +1,41 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconMessageCircle, InlineIcon } from "nexus-icons";
+import { useMemo } from "react";
+import { chatBadgeText, chatHighlight, chatPreviewText, chatTimeAgo } from "../../Helpers/ChatHelpers.js";
+import { useChatSummary } from "../../Helpers/ChatHooks.js";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { useBrowserTimeZone, useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { pluralize } from "../../Helpers/MessageBuilder.js";
+/**
+ * The tooltip and the screen reader's text: what the icon is saying, in words. "40 min ago" is left out until the page
+ * is in a browser — it is counted from the clock, and a server that rendered "42 min ago" a moment earlier would not
+ * match what the browser then draws. The zone tells us where we are, as the date-time fields here already have it.
+ */
+function describe(summary, label, time, onBrowser) {
+    if (!summary || summary.messageCount === 0)
+        return `${label}: no messages yet`;
+    const counted = `${summary.messageCount} ${summary.messageCount === 1 ? "message" : pluralize("message")}`;
+    const parts = [summary.unreadCount > 0 ? `${label}: ${summary.unreadCount} unread of ${summary.messageCount}` : `${label}: ${counted}`];
+    const when = onBrowser ? chatTimeAgo(summary.lastMessageAt, time) : "";
+    if (when)
+        parts.push(when);
+    if (summary.lastMessageText)
+        parts.push(`${summary.lastMessageBy ? `${summary.lastMessageBy}: ` : ""}${chatPreviewText(summary.lastMessageText, 80)}`);
+    return parts.join(" · ");
+}
+/**
+ * The chat icon for one record: quiet, highlighted, or highlighted with an unread badge. It does not open anything by
+ * itself — `Chat` is the icon with the popup behind it, and a page that holds the conversation somewhere else gives
+ * this one an `onClick`.
+ */
+export function ChatButton({ scope, summary: given, label = "Discussion", size = "md", maxBadge = 99, time, icon = iconMessageCircle, className, ...rest }) {
+    const { summary } = useChatSummary(scope, given);
+    const preferences = useDatePreferences();
+    const zone = useBrowserTimeZone();
+    const settings = useMemo(() => ({ ...preferences, ...(zone && { timeZone: zone }), ...time }), [preferences, zone, time]);
+    const highlight = chatHighlight(summary);
+    const words = describe(summary, label, settings, zone !== null);
+    const unread = summary?.unreadCount ?? 0;
+    return (_jsxs("button", { type: "button", className: cx("nx-chat-btn", `nx-chat-btn--${size}`, className), "data-chat": highlight, title: words, "aria-label": words, ...rest, children: [_jsx(InlineIcon, { icon: icon }), unread > 0 && (_jsx("span", { className: "nx-chat-btn__badge", "aria-hidden": "true", children: chatBadgeText(unread, maxBadge) }))] }));
+}

package/dist/Components/Chats/ChatComposer.d.ts

@@ -0,0 +1,41 @@
+import type { ChatSnapshot, ChatStore } from "../../Helpers/ChatStore.ts";
+import type { ChatMessage, ChatParticipant } from "../../Interfaces/ChatInterfaces.ts";
+import { type MarkdownToolbarItem } from "../Inputs/MarkdownEditor.tsx";
+/** The tools a chat message needs. The full `MARKDOWN_TOOLBAR` belongs to a document, not to a line or two. */
+export declare const CHAT_TOOLBAR: readonly MarkdownToolbarItem[];
+/** `enter`: Enter sends, Shift+Enter starts a line. `modifier`: Ctrl+Enter sends and Enter is only ever a line. */
+export type ChatSendKey = "enter" | "modifier";
+export interface ChatComposerProps {
+    store: ChatStore;
+    state: ChatSnapshot;
+    /** Keeps the unsent text under this key. Default: none, and the text is lost when the composer unmounts. */
+    draftKey?: string;
+    placeholder?: string;
+    /** Files can be attached. Default false: only a source that takes them should offer it. */
+    files?: boolean;
+    /** The message being answered. */
+    replyTo?: ChatMessage | null;
+    /** The reply was called off. */
+    onCancelReply?: () => void;
+    /** Which key sends. Default `enter`. */
+    sendKey?: ChatSendKey;
+    /**
+     * The people an `@` offers. Left out, `@` is only a letter. The list opens on `@` at the start of a word and
+     * narrows as the name is typed; Enter or Tab puts the name in, and while it is open Enter never sends.
+     */
+    mentions?: readonly ChatParticipant[];
+    /** Where a mention links to, as Markdown: `person => `/people/${person.id}``. Default: plain `@Name`, no link. */
+    mentionHref?: (participant: ChatParticipant) => string | null;
+    /** The toolbar, as `MarkdownEditor` takes it. Default `CHAT_TOOLBAR`; `[]` leaves the writing area bare. */
+    toolbar?: readonly MarkdownToolbarItem[];
+    /** How tall the writing area starts, in pixels. Default 84, about three lines; the handle under it drags, and remembers. */
+    height?: number;
+    /** Why the user may not write here. */
+    readOnlyMessage?: string;
+    /** Most characters in one message. Default 4,000. */
+    maxLength?: number;
+    autoFocus?: boolean;
+    className?: string;
+}
+/** Writes and sends a message, in Markdown. */
+export declare function ChatComposer({ store, state, draftKey, placeholder, files, replyTo, onCancelReply, sendKey, mentions, mentionHref, toolbar, height, readOnlyMessage, maxLength, autoFocus, className, }: ChatComposerProps): import("react").JSX.Element;

package/dist/Components/Chats/ChatComposer.js

@@ -0,0 +1,177 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { iconPaperclip, iconSend, iconX, InlineIcon } from "nexus-icons";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { applyChatMention, chatFileSize, findChatMention, matchChatMentions, readChatMentions } from "../../Helpers/ChatHelpers.js";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { continueMarkdownList } from "../../Helpers/MarkdownEditing.js";
+import { markdownToPlainText } from "../../Helpers/MarkdownHelpers.js";
+import { ChatAvatar } from "./ChatParts.js";
+import { MarkdownEditor } from "../Inputs/MarkdownEditor.js";
+/*
+ * The composer. A message is Markdown, so this is the Markdown editor the rest of the app writes with — the same
+ * toolbar, the same shortcuts, the same preview — kept short, with Write and Preview only and no room for a split view
+ * in a chat panel.
+ *
+ * Enter sends and Shift+Enter starts a line, as a chat does. The one exception is a list: with the caret in one, Enter
+ * belongs to the editor, which carries the list on to the next item, because a half-written list that sends itself is
+ * worse than a message that needs one more key. A page that would rather Enter never sent sets `sendKey="modifier"`.
+ *
+ * What has been typed but not sent is kept under `draftKey`, so closing the panel, opening another record, or reloading
+ * the page does not lose it — the same promise the forms make.
+ */
+/** Where unsent text is kept. */
+const DRAFT_PREFIX = "nx-chat-draft:";
+/** The tools a chat message needs. The full `MARKDOWN_TOOLBAR` belongs to a document, not to a line or two. */
+export const CHAT_TOOLBAR = ["bold", "italic", "strikethrough", "|", "link", "code", "codeBlock", "|", "bulletList", "numberedList", "taskList", "quote"];
+const readDraft = (key) => {
+    if (!key || typeof window === "undefined")
+        return "";
+    try {
+        return window.localStorage.getItem(DRAFT_PREFIX + key) ?? "";
+    }
+    catch {
+        // A private window, or site data turned off: the composer simply starts empty.
+        return "";
+    }
+};
+const writeDraft = (key, text) => {
+    if (!key || typeof window === "undefined")
+        return;
+    try {
+        if (text)
+            window.localStorage.setItem(DRAFT_PREFIX + key, text);
+        else
+            window.localStorage.removeItem(DRAFT_PREFIX + key);
+    }
+    catch {
+        // Nothing to do: losing a draft is better than failing to send.
+    }
+};
+/** Whether the caret sits inside a fenced code block, where Enter is a line and never a send. */
+function insideCodeFence(value, caret) {
+    const before = value.slice(0, caret);
+    return (before.match(/^```/gm) ?? []).length % 2 === 1;
+}
+/** Writes and sends a message, in Markdown. */
+export function ChatComposer({ store, state, draftKey, placeholder = "Write a message…", files = false, replyTo, onCancelReply, sendKey = "enter", mentions, mentionHref, toolbar = CHAT_TOOLBAR, height = 84, readOnlyMessage = "You can read this conversation, but not write in it.", maxLength = 4000, autoFocus = false, className, }) {
+    const boxRef = useRef(null);
+    const fileRef = useRef(null);
+    // The text lives here so Send, the draft, and clearing after a send all read the same thing. A message is short, so
+    // a render per keystroke costs nothing — unlike the long documents the editor is otherwise built for.
+    //
+    // It starts empty rather than from the saved draft: local storage is the browser's, so reading it while rendering
+    // would make the page the server built and the page the browser builds disagree, down to a Send button that is
+    // disabled on one and not the other. The draft arrives just after, in the effect below.
+    const [text, setText] = useState("");
+    const [picked, setPicked] = useState([]);
+    // The `@…` being typed, and which of the people offered is highlighted.
+    const [mention, setMention] = useState(null);
+    const [at, setAt] = useState(0);
+    const offered = mention && mentions ? matchChatMentions(mentions, mention.query) : [];
+    const picking = offered.length > 0;
+    useEffect(() => {
+        setText(readDraft(draftKey));
+    }, [draftKey]);
+    useEffect(() => {
+        if (autoFocus)
+            boxRef.current?.focus();
+    }, [autoFocus]);
+    const change = useCallback((value) => {
+        setText(value);
+        writeDraft(draftKey, value);
+        // The caret is the text area's, since the editor hands back only the text.
+        const caret = boxRef.current?.selectionStart ?? value.length;
+        setMention(mentions ? findChatMention(value, caret) : null);
+        setAt(0);
+    }, [draftKey, mentions]);
+    /** Puts the chosen name in, and leaves the caret after it. */
+    const putMention = useCallback((person) => {
+        if (!mention)
+            return;
+        const next = applyChatMention(text, mention, person, mentionHref?.(person));
+        setText(next.value);
+        writeDraft(draftKey, next.value);
+        setMention(null);
+        const box = boxRef.current;
+        if (box) {
+            // After the editor has drawn the new text, or the caret would be put back by the render.
+            requestAnimationFrame(() => {
+                box.focus();
+                box.setSelectionRange(next.caret, next.caret);
+            });
+        }
+    }, [mention, text, mentionHref, draftKey]);
+    const send = useCallback(() => {
+        const written = text.trim();
+        if (!written && picked.length === 0)
+            return;
+        // The text goes before the call does: the message is on screen at once, and a failure keeps it there with Retry.
+        const named = mentions ? readChatMentions(written, mentions) : [];
+        change("");
+        setPicked([]);
+        setMention(null);
+        onCancelReply?.();
+        void store.send(written, { replyToId: replyTo?.id ?? null, ...(picked.length > 0 && { files: picked }), ...(named.length > 0 && { mentions: named }) });
+        boxRef.current?.focus();
+    }, [text, picked, change, onCancelReply, store, replyTo, mentions]);
+    const keyDown = (event) => {
+        // While the `@` list is open it owns the arrows, Enter, Tab and Esc: a name is being picked, not a message sent.
+        if (picking) {
+            if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+                event.preventDefault();
+                setAt(index => (index + (event.key === "ArrowDown" ? 1 : offered.length - 1)) % offered.length);
+                return;
+            }
+            if (event.key === "Enter" || event.key === "Tab") {
+                event.preventDefault();
+                putMention(offered[at] ?? offered[0]);
+                return;
+            }
+            if (event.key === "Escape") {
+                event.preventDefault();
+                setMention(null);
+                return;
+            }
+        }
+        // While an input method is composing, Enter belongs to the composition, not to sending.
+        if (event.key !== "Enter" || event.nativeEvent.isComposing) {
+            if (event.key === "Escape" && replyTo && onCancelReply) {
+                event.preventDefault();
+                onCancelReply();
+            }
+            return;
+        }
+        const withModifier = event.ctrlKey || event.metaKey;
+        if (sendKey === "modifier") {
+            if (!withModifier)
+                return;
+            event.preventDefault();
+            send();
+            return;
+        }
+        if (event.shiftKey || event.altKey)
+            return;
+        const box = event.currentTarget;
+        // The editor owns Enter inside a list or a code block: it carries the list on, or keeps the block together.
+        if (!withModifier && (continueMarkdownList(box.value, box.selectionStart, box.selectionEnd) !== null || insideCodeFence(box.value, box.selectionStart)))
+            return;
+        event.preventDefault();
+        send();
+    };
+    const addFiles = (event) => {
+        const chosen = Array.from(event.target.files ?? []);
+        if (chosen.length)
+            setPicked(held => [...held, ...chosen]);
+        event.target.value = "";
+    };
+    if (!state.canSend) {
+        return (_jsx("div", { className: cx("nx-chat-composer nx-chat-composer--readonly", className), children: _jsx("p", { children: readOnlyMessage }) }));
+    }
+    const empty = text.trim() === "" && picked.length === 0;
+    return (_jsxs("div", { className: cx("nx-chat-composer", className), children: [replyTo && (_jsxs("div", { className: "nx-chat-composer__reply", children: [_jsxs("span", { className: "nx-chat-composer__reply-text", children: [_jsx("span", { className: "nx-chat-composer__reply-author", children: replyTo.authorName || "Unknown" }), _jsx("span", { children: markdownToPlainText(replyTo.body) })] }), _jsx("button", { type: "button", onClick: onCancelReply, "aria-label": "Stop replying", children: _jsx(InlineIcon, { icon: iconX }) })] })), picked.length > 0 && (_jsx("ul", { className: "nx-chat-composer__files", children: picked.map((file, index) => (_jsxs("li", { children: [_jsx("span", { className: "nx-chat-composer__file-name", children: file.name }), _jsx("span", { className: "nx-chat-composer__file-size", children: chatFileSize(file.size) }), _jsx("button", { type: "button", onClick: () => setPicked(held => held.filter((_, at) => at !== index)), "aria-label": `Remove ${file.name}`, children: _jsx(InlineIcon, { icon: iconX }) })] }, `${file.name}-${index}`))) })), picking && (_jsx("ul", { className: "nx-chat-mentions", role: "listbox", "aria-label": "People", children: offered.map((person, index) => (_jsx("li", { children: _jsxs("button", { type: "button", className: cx("nx-chat-mentions__item", index === at && "is-at"), role: "option", "aria-selected": index === at, 
+                        // The editor must not lose the caret before the name goes in.
+                        onMouseDown: event => event.preventDefault(), onMouseEnter: () => setAt(index), onClick: () => putMention(person), children: [_jsx(ChatAvatar, { name: person.name, src: person.avatar, size: "sm" }), _jsx("span", { className: "nx-chat-mentions__name", children: person.name }), person.role && _jsx("span", { className: "nx-chat-mentions__role", children: person.role })] }) }, String(person.id)))) })), _jsx(MarkdownEditor, { ref: boxRef, className: "nx-chat-composer__editor", "aria-label": "Message", placeholder: placeholder, value: text, onValueChange: change, onKeyDown: keyDown, 
+                // Moving the caret away from an `@…` closes the list, as clicking elsewhere in the text does.
+                onSelect: () => setMention(mentions ? findChatMention(boxRef.current?.value ?? "", boxRef.current?.selectionStart ?? 0) : null), onBlur: () => setMention(null), modes: ["write", "preview"], toolbar: toolbar, height: height, minHeight: 72, maxHeight: 360, heightKey: "nx-chat", showCount: false, maxLength: maxLength }), _jsxs("div", { className: "nx-chat-composer__row", children: [_jsx("span", { className: "nx-chat-composer__hint", children: sendKey === "enter" ? "Enter sends · Shift+Enter for a line" : "Ctrl+Enter sends" }), files && (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "nx-chat-composer__attach", onClick: () => fileRef.current?.click(), "aria-label": "Attach a file", title: "Attach a file", children: _jsx(InlineIcon, { icon: iconPaperclip }) }), _jsx("input", { ref: fileRef, type: "file", multiple: true, hidden: true, onChange: addFiles })] })), _jsxs("button", { type: "button", className: "nx-chat-composer__send", onClick: send, disabled: empty, "aria-label": "Send", title: sendKey === "enter" ? "Send (Enter)" : "Send (Ctrl+Enter)", children: [_jsx(InlineIcon, { icon: iconSend }), _jsx("span", { children: "Send" })] })] })] }));
+}

package/dist/Components/Chats/ChatConversations.d.ts

@@ -0,0 +1,35 @@
+import { type ReactNode } from "react";
+import { type ChatTimeOptions } from "../../Helpers/ChatHelpers.ts";
+import type { ChatPlaceHandle } from "../../Helpers/ChatHooks.ts";
+import type { ChatConversation, ChatId } from "../../Interfaces/ChatInterfaces.ts";
+export interface ChatConversationListProps {
+    conversations: readonly ChatConversation[];
+    /** The one open now. */
+    currentId?: ChatId | null;
+    userId: ChatId;
+    time: ChatTimeOptions;
+    loading?: boolean;
+    error?: string | null;
+    onRetry?: () => void;
+    onPick: (conversation: ChatConversation) => void;
+    /** Starts a new one. Left out when the source cannot. */
+    onNew?: () => void;
+    /** Shown when the record holds none. */
+    empty?: ReactNode;
+}
+/** Every conversation at a record: which is open, which is waiting, and what was said last. */
+export declare function ChatConversationList({ conversations, currentId, userId, time, loading, error, onRetry, onPick, onNew, empty }: ChatConversationListProps): import("react").JSX.Element;
+export interface ChatNewFormProps {
+    place: ChatPlaceHandle;
+    /** Searches people. Default: the place's own search. */
+    searchParticipants?: ChatPlaceHandle["searchParticipants"];
+    /** The conversation that was started, or the one that already existed. */
+    onStarted: (conversation: ChatConversation) => void;
+    onCancel: () => void;
+}
+/**
+ * Starts a conversation. The **type is not asked for**: one person makes a one-to-one, more than one makes a group,
+ * and naming it makes a group of one person too. The form says which it will be, so nothing is a surprise, and the
+ * backend has the last word — asking a one-to-one for somebody who already has one gives that one back.
+ */
+export declare function ChatNewForm({ place, searchParticipants, onStarted, onCancel }: ChatNewFormProps): import("react").JSX.Element;

package/dist/Components/Chats/ChatConversations.js

@@ -0,0 +1,38 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconMessageCircle, iconPlus, iconUsers, InlineIcon } from "nexus-icons";
+import { useState } from "react";
+import { chatBadgeText, chatConversationName, chatPreviewText, chatTimeAgo, chatTypeFor } from "../../Helpers/ChatHelpers.js";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { Button } from "../Documents/Button.js";
+import { Dropdown } from "../Inputs/Dropdown.js";
+import { TextBox } from "../Inputs/TextBox.js";
+import { ChatAvatar, ChatFailure, ChatLoading } from "./ChatParts.js";
+/** Every conversation at a record: which is open, which is waiting, and what was said last. */
+export function ChatConversationList({ conversations, currentId, userId, time, loading, error, onRetry, onPick, onNew, empty }) {
+    return (_jsxs("div", { className: "nx-chat-list", children: [error && _jsx(ChatFailure, { message: error, onRetry: onRetry }), loading && conversations.length === 0 && _jsx(ChatLoading, { label: "Reading the conversations\u2026" }), !loading && conversations.length === 0 && !error && (_jsxs("div", { className: "nx-chat-empty", children: [_jsx("p", { children: empty ?? "No conversations here yet." }), onNew && _jsx("p", { className: "nx-chat-empty__hint", children: "Start one below." })] })), conversations.length > 0 && (_jsx("ul", { className: "nx-chat-list__items", children: conversations.map(conversation => {
+                    const name = chatConversationName(conversation, userId);
+                    const unread = conversation.summary?.unreadCount ?? 0;
+                    const when = chatTimeAgo(conversation.summary?.lastMessageAt, time);
+                    const last = conversation.summary?.lastMessageText;
+                    const current = currentId !== null && currentId !== undefined && String(conversation.id) === String(currentId);
+                    return (_jsx("li", { children: _jsxs("button", { type: "button", className: cx("nx-chat-list__item", current && "is-current"), onClick: () => onPick(conversation), "aria-current": current || undefined, children: [conversation.type === "group" ? (_jsx("span", { className: "nx-chat-list__group", "aria-hidden": "true", children: _jsx(InlineIcon, { icon: iconUsers }) })) : (_jsx(ChatAvatar, { name: name, src: (conversation.participants ?? []).find(person => String(person.id) !== String(userId))?.avatar })), _jsxs("span", { className: "nx-chat-list__text", children: [_jsxs("span", { className: "nx-chat-list__line", children: [_jsx("span", { className: "nx-chat-list__name", children: name }), when && _jsx("span", { className: "nx-chat-list__when", children: when })] }), _jsxs("span", { className: "nx-chat-list__line", children: [_jsx("span", { className: "nx-chat-list__last", children: last ? `${conversation.summary?.lastMessageBy ? `${conversation.summary.lastMessageBy}: ` : ""}${chatPreviewText(last, 60)}` : "No messages yet" }), unread > 0 && _jsx("span", { className: "nx-chat-list__badge", children: chatBadgeText(unread) })] })] })] }) }, String(conversation.id)));
+                }) })), onNew && (_jsx("div", { className: "nx-chat-list__new", children: _jsx(Button, { size: "sm", variant: "secondary", block: true, icon: _jsx(InlineIcon, { icon: iconPlus }), onClick: onNew, children: "New chat" }) }))] }));
+}
+/**
+ * Starts a conversation. The **type is not asked for**: one person makes a one-to-one, more than one makes a group,
+ * and naming it makes a group of one person too. The form says which it will be, so nothing is a surprise, and the
+ * backend has the last word — asking a one-to-one for somebody who already has one gives that one back.
+ */
+export function ChatNewForm({ place, searchParticipants, onStarted, onCancel }) {
+    const [chosen, setChosen] = useState([]);
+    const [title, setTitle] = useState("");
+    const search = searchParticipants ?? place.searchParticipants;
+    const type = chatTypeFor(chosen, title);
+    async function start() {
+        const made = await place.create({ type, userIds: chosen, title: title.trim() || null });
+        if (made)
+            onStarted(made);
+    }
+    return (_jsxs("div", { className: "nx-chat-new", children: [_jsxs("div", { className: "nx-chat-new__fields", children: [_jsx(Dropdown, { multiple: true, name: "nx-chat-new-people", label: "With", placeholder: "Search by name", size: "sm", value: chosen, valueKey: "id", labelKey: "name", descriptionKey: "role", loadOptions: search, isOptionInactive: (person) => person.inactive === true, onValueChange: (values) => setChosen(values), hint: chosen.length === 0 ? "One person makes a direct chat; more make a group." : undefined }), (chosen.length > 1 || title !== "") && (_jsx(TextBox, { name: "nx-chat-new-title", label: "Group name", size: "sm", value: title, onValueChange: setTitle, maxLength: 120, placeholder: "Optional", hint: "Without one, the group is called after the people in it." })), _jsxs("p", { className: "nx-chat-new__kind", children: [_jsx(InlineIcon, { icon: type === "group" ? iconUsers : iconMessageCircle }), chosen.length === 0 ? "Pick who to talk to." : type === "group" ? `A group of ${chosen.length + 1}, you included.` : "A direct chat between the two of you."] }), place.error && _jsx(ChatFailure, { message: place.error })] }), _jsxs("div", { className: "nx-chat-new__actions", children: [_jsx(Button, { size: "sm", variant: "ghost", onClick: onCancel, children: "Cancel" }), _jsx(Button, { size: "sm", variant: "primary", loading: place.creating, disabled: chosen.length === 0, onClick: () => void start(), children: "Start chat" })] }), _jsx("p", { className: "nx-chat-new__note", children: "You are in it either way." })] }));
+}

package/dist/Components/Chats/ChatPanel.d.ts

@@ -0,0 +1,66 @@
+import { type ReactNode } from "react";
+import type { ChatConversation, ChatDomainValue, ChatId, ChatParticipant, ChatParticipantPage, ChatParticipantQuery, ChatPlaceSource, ChatScope, ChatSource, ChatSummary } from "../../Interfaces/ChatInterfaces.ts";
+/** Which of the panel's three views the body is showing. */
+export type ChatPanelView = "thread" | "list" | "new";
+export interface ChatPanelProps<TDomain extends ChatDomainValue = ChatDomainValue> {
+    /** Which record: the domain, the record, and the reader. */
+    scope: ChatScope<TDomain>;
+    /**
+     * Where the messages of **one** conversation come from. Given, the panel shows that conversation alone, with no
+     * switch and no New chat. Left out, the panel asks the place which conversations the record holds.
+     */
+    source?: ChatSource;
+    /**
+     * Where one conversation's messages come from, when the app carries them itself — a socket for each conversation, or
+     * a demo with them in memory. Called with whichever conversation is open. Default: the app's API, by conversation id.
+     */
+    sourceFor?: (conversation: ChatConversation) => ChatSource | undefined;
+    /** The conversations at this record, and how to start another. Default: the app's API, through its `ChatBackend`. */
+    place?: ChatPlaceSource;
+    /** The conversations the page already had, so the panel makes no call for them. */
+    conversations?: readonly ChatConversation[];
+    /** Which conversation to open. Default: the one with unread messages, else the one spoken in most recently. */
+    conversationId?: ChatId | null;
+    /** When another conversation is opened, so a page can remember which. */
+    onConversationChange?: (conversation: ChatConversation | null) => void;
+    /** What the record is: "Leave request #482". Default: the domain's name and the record's id. */
+    title?: ReactNode;
+    /** A line under the title, such as who asked and when. */
+    description?: ReactNode;
+    /** The counts the page already had, so the bar opens filled. */
+    summary?: ChatSummary;
+    /** The people the page already had, so the panel makes no call for them. */
+    participants?: readonly ChatParticipant[];
+    /**
+     * Searches the people in the conversation and the ones who could join. Default: the source's own search (the
+     * backend's participants endpoint). Give one to search somewhere else — a staff list, a project's members.
+     */
+    searchParticipants?: (query: ChatParticipantQuery) => Promise<ChatParticipantPage>;
+    /** The people column and its button. Default true when anyone is known or can be searched. */
+    people?: boolean;
+    /** Files can be attached. Default false. */
+    files?: boolean;
+    /** Messages can be answered. Default true. */
+    replies?: boolean;
+    /** `@` offers the people in the conversation. Default true. */
+    mentions?: boolean;
+    /** Where a mention links to, as Markdown: `person => \`/people/${person.id}\``. Default: plain `@Name`, no link. */
+    mentionHref?: (participant: ChatParticipant) => string | null;
+    /** The bar above the thread. Off inside a popup, whose own title bar says what this is. Default true. */
+    header?: boolean;
+    /** How tall the panel is. Default `min(60vh, 520px)`; `"100%"` fills what holds it. */
+    height?: number | string;
+    /** Loads and watches only while this is true. Default true. */
+    enabled?: boolean;
+    /** Messages per page. Default 30. */
+    pageSize?: number;
+    /** Milliseconds between checks for new messages. 0 turns it off. Default 15,000. */
+    pollInterval?: number;
+    /** Every time the record's counts change, so a list's row can follow them. */
+    onSummary?: (summary: ChatSummary) => void;
+    /** Buttons under the composer. */
+    footer?: ReactNode;
+    className?: string;
+}
+/** A record's conversations, drawn in full. */
+export declare function ChatPanel<TDomain extends ChatDomainValue = ChatDomainValue>({ scope, source, sourceFor, place: placeSource, conversations: givenConversations, conversationId: givenConversationId, onConversationChange, title, description, summary, participants, searchParticipants, people, files, replies, mentions, mentionHref, header, height, enabled, pageSize, pollInterval, onSummary, footer, className, }: ChatPanelProps<TDomain>): import("react").JSX.Element;

package/dist/Components/Chats/ChatPanel.js

@@ -0,0 +1,94 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { iconArrowLeft, iconChevronDown, iconPlus, iconUserPlus, iconUsers, iconX, InlineIcon } from "nexus-icons";
+import { useEffect, useMemo, useState } from "react";
+import { chatConversationName, chatScopeKey, pickChatConversation } from "../../Helpers/ChatHelpers.js";
+import { chatDomainLabel } from "../../Helpers/ChatBackend.js";
+import { useChat, useChatPlace } from "../../Helpers/ChatHooks.js";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { useBrowserTimeZone, useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { Button } from "../Documents/Button.js";
+import { Dropdown } from "../Inputs/Dropdown.js";
+import { ChatConversationList, ChatNewForm } from "./ChatConversations.js";
+import { ChatParticipantList } from "./ChatParts.js";
+import { ChatComposer } from "./ChatComposer.js";
+import { ChatThread } from "./ChatThread.js";
+/** What a record is called when the page does not say: the domain's name, when the app named it, and the record. */
+function defaultTitle(scope) {
+    const label = chatDomainLabel(scope.domain);
+    return label ? `${label} · #${String(scope.parentId)}` : `Discussion · #${String(scope.parentId)}`;
+}
+/** A record's conversations, drawn in full. */
+export function ChatPanel({ scope, source, sourceFor, place: placeSource, conversations: givenConversations, conversationId: givenConversationId, onConversationChange, title, description, summary, participants, searchParticipants, people, files = false, replies = true, mentions = true, mentionHref, header = true, height, enabled = true, pageSize, pollInterval, onSummary, footer, className, }) {
+    // A page that handed over one conversation's source is not asking about any others.
+    const single = source !== undefined;
+    const place = useChatPlace({ scope, place: placeSource, conversations: givenConversations, enabled: enabled && !single });
+    const [view, setView] = useState("thread");
+    const [chosenId, setChosenId] = useState(givenConversationId ?? null);
+    const [replyTo, setReplyTo] = useState(null);
+    const [asideOpen, setAsideOpen] = useState(false);
+    const [adding, setAdding] = useState([]);
+    useEffect(() => {
+        if (givenConversationId !== undefined)
+            setChosenId(givenConversationId);
+    }, [givenConversationId]);
+    // Which conversation is open: the page's, else the one picked out of the list — unread first, then most recent.
+    const current = useMemo(() => {
+        if (single)
+            return undefined;
+        const held = place.conversations;
+        const chosen = chosenId === null ? undefined : held.find(one => String(one.id) === String(chosenId));
+        return chosen ?? pickChatConversation(held);
+    }, [single, place.conversations, chosenId]);
+    // One conversation's messages: the page's own source, else one made for whichever conversation is open.
+    const openSource = current && sourceFor ? sourceFor(current) : undefined;
+    const { store, state } = useChat({
+        scope,
+        source: source ?? openSource,
+        ...(current && { conversationId: current.id }),
+        pageSize,
+        pollInterval,
+        summary,
+        participants: current?.participants ?? participants,
+        enabled: enabled && view === "thread" && (single || current !== undefined),
+    });
+    const preferences = useDatePreferences();
+    const zone = useBrowserTimeZone();
+    const time = useMemo(() => ({ ...preferences, ...(zone && { timeZone: zone }) }), [preferences, zone]);
+    const search = searchParticipants ?? store.searchParticipants;
+    const canAdd = state.features.addParticipants && (current?.type ?? "group") === "group";
+    const showPeople = people ?? (state.participants.length > 0 || state.features.participants || searchParticipants !== undefined);
+    const many = !single && place.conversations.length > 1;
+    // Unsent text belongs to one conversation, so the key holds the record, the reader, and which conversation it is.
+    const draftKey = `${chatScopeKey(scope)}:${String(scope.userId)}${current ? `:${String(current.id)}` : ""}`;
+    const name = current ? chatConversationName(current, scope.userId) : null;
+    // The record's counts reach the page after the render that changed them, never during it.
+    useEffect(() => {
+        onSummary?.(state.summary);
+    }, [onSummary, state.summary]);
+    // Once a conversation is open it stays open. Without this the panel would pick again whenever the list changed, and
+    // reading this one — which clears its unread count — would hand the panel to whichever conversation is unread next.
+    useEffect(() => {
+        if (current && chosenId === null)
+            setChosenId(current.id);
+    }, [current, chosenId]);
+    // A conversation's own counts go back into the list, so the switch shows what is waiting in the others. Only once
+    // its first page has arrived: a store that has loaded nothing yet holds zeros, which would wipe what the list knows.
+    useEffect(() => {
+        if (current && state.loaded)
+            place.apply(current.id, state.summary);
+    }, [current, place, state.loaded, state.summary]);
+    function open(conversation) {
+        setChosenId(conversation.id);
+        setView("thread");
+        setAsideOpen(false);
+        onConversationChange?.(conversation);
+    }
+    const style = height === undefined ? undefined : { "--nx-chat-height": typeof height === "number" ? `${height}px` : height };
+    const empty = !single && !place.loading && place.conversations.length === 0;
+    return (_jsxs("div", { className: cx("nx-chat-panel", asideOpen && "nx-chat-panel--with-aside", className), style: style, children: [header && (_jsxs("header", { className: "nx-chat-panel__bar", children: [view !== "thread" && (_jsx("button", { type: "button", className: "nx-chat-panel__back", onClick: () => setView("thread"), "aria-label": "Back to the conversation", title: "Back to the conversation", children: _jsx(InlineIcon, { icon: iconArrowLeft }) })), _jsxs("div", { className: "nx-chat-panel__heading", children: [view === "list" ? (_jsx("span", { className: "nx-chat-panel__title", children: "Conversations" })) : view === "new" ? (_jsx("span", { className: "nx-chat-panel__title", children: "New chat" })) : many ? (_jsxs("button", { type: "button", className: "nx-chat-panel__switch", onClick: () => setView("list"), "aria-haspopup": "true", children: [_jsx("span", { className: "nx-chat-panel__title", children: name }), _jsx(InlineIcon, { icon: iconChevronDown }), _jsxs("span", { className: "nx-chat-panel__of", children: ["of ", place.conversations.length] })] })) : (_jsx("span", { className: "nx-chat-panel__title", children: name ?? title ?? defaultTitle(scope) })), view === "thread" && description && _jsx("span", { className: "nx-chat-panel__description", children: description })] }), view === "thread" && !single && place.canCreate && !many && (_jsx("button", { type: "button", className: "nx-chat-panel__people", onClick: () => setView("new"), "aria-label": "New chat", title: "New chat", children: _jsx(InlineIcon, { icon: iconPlus }) })), view === "thread" && showPeople && (_jsxs("button", { type: "button", className: cx("nx-chat-panel__people", asideOpen && "is-open"), onClick: () => setAsideOpen(shown => !shown), "aria-pressed": asideOpen, "aria-label": asideOpen ? "Hide the people" : "Show the people", title: asideOpen ? "Hide the people" : "Show the people", children: [_jsx(InlineIcon, { icon: iconUsers }), state.participants.length > 0 && _jsx("span", { children: state.participants.length })] }))] })), _jsxs("div", { className: "nx-chat-panel__body", children: [view === "list" && (_jsx(ChatConversationList, { conversations: place.conversations, currentId: current?.id ?? null, userId: scope.userId, time: time, loading: place.loading, error: place.error, onRetry: () => void place.reload(), onPick: open, onNew: place.canCreate ? () => setView("new") : undefined })), view === "new" && _jsx(ChatNewForm, { place: place, searchParticipants: searchParticipants, onStarted: open, onCancel: () => setView("thread") }), view === "thread" && empty && (_jsx(ChatConversationList, { conversations: [], userId: scope.userId, time: time, loading: place.loading, error: place.error, onRetry: () => void place.reload(), onPick: open, onNew: place.canCreate ? () => setView("new") : undefined, empty: "Nobody has written about this record yet." })), view === "thread" && !empty && (_jsxs(_Fragment, { children: [_jsx(ChatThread, { store: store, state: state, userId: scope.userId, replies: replies, onReply: setReplyTo, marksRead: enabled }), showPeople && asideOpen && (_jsxs("aside", { className: "nx-chat-panel__aside", "aria-label": "People in this conversation", children: [_jsxs("div", { className: "nx-chat-aside__bar", children: [_jsx("span", { children: "People" }), _jsx("button", { type: "button", onClick: () => setAsideOpen(false), "aria-label": "Hide the people", children: _jsx(InlineIcon, { icon: iconX }) })] }), _jsx(ChatParticipantList, { participants: state.participants, userId: scope.userId }), canAdd && (_jsxs("div", { className: "nx-chat-aside__add", children: [_jsx(Dropdown, { multiple: true, name: "nx-chat-add-people", label: "Add people", placeholder: "Search by name", size: "sm", value: adding, valueKey: "id", labelKey: "name", descriptionKey: "role", loadOptions: search, isOptionInactive: (person) => person.inactive === true, onValueChange: (values) => setAdding(values) }), _jsx(Button, { size: "sm", variant: "secondary", icon: _jsx(InlineIcon, { icon: iconUserPlus }), disabled: adding.length === 0, onClick: () => {
+                                                    const chosen = adding;
+                                                    setAdding([]);
+                                                    void store.addParticipants(chosen);
+                                                }, children: "Add" })] }))] }))] }))] }), view === "thread" && !empty && (_jsx(ChatComposer, { store: store, state: state, draftKey: draftKey, files: files, replyTo: replyTo, onCancelReply: () => setReplyTo(null), autoFocus: enabled, mentions: mentions ? state.participants : undefined, mentionHref: mentionHref })), footer && _jsx("div", { className: "nx-chat-panel__footer", children: footer })] }));
+}

package/dist/Components/Chats/ChatParts.d.ts

@@ -0,0 +1,87 @@
+import { type ReactNode } from "react";
+import { type ChatTimeOptions } from "../../Helpers/ChatHelpers.ts";
+import type { ChatAttachment, ChatId, ChatMessage, ChatParticipant } from "../../Interfaces/ChatInterfaces.ts";
+/** A round photo, or the initials of the name on a tone picked from it — the same look and tones as a dropdown's. */
+export declare function ChatAvatar({ name, src, size }: {
+    name: string;
+    src?: string | null;
+    size?: "sm" | "md";
+}): import("react").JSX.Element;
+/** The day a run of messages was written: "Today", "Yesterday", or the date in the user's calendar. */
+export declare function ChatDayDivider({ label }: {
+    label: string;
+}): import("react").JSX.Element;
+/** Where reading stopped last time. It stays where it was put, so it does not slide away as the thread is read. */
+export declare function ChatUnreadLine({ count, label }: {
+    count?: number;
+    label?: string;
+}): import("react").JSX.Element;
+/**
+ * How far a message of this user's has got, in the one place the time sits: a turning spinner while it is on its way,
+ * one tick once the server has it, two once it has reached somebody, and two in the accent once it has been read. The
+ * mark is the same size in every state, so the line under a message does not shift as it settles.
+ */
+export declare function ChatReadMark({ message, participants, userId }: {
+    message: ChatMessage;
+    participants: readonly ChatParticipant[];
+    userId: ChatId;
+}): import("react").JSX.Element;
+/** Files on a message: the name, the size, and a link when the file has a URL. */
+export declare function ChatAttachments({ attachments }: {
+    attachments: readonly ChatAttachment[];
+}): import("react").JSX.Element;
+/** The message a reply answers, above the reply itself. */
+export declare function ChatQuote({ message, onOpen }: {
+    message: ChatMessage | undefined;
+    onOpen?: (id: ChatId) => void;
+}): import("react").JSX.Element;
+/** A note the system wrote, not a person: no side, no avatar, no actions. */
+export declare function ChatSystemNote({ message, time }: {
+    message: ChatMessage;
+    time: ChatTimeOptions;
+}): import("react").JSX.Element;
+export interface ChatMessageProps {
+    message: ChatMessage;
+    /** This user wrote it: it sits on the right. */
+    mine: boolean;
+    /** The first of a run: it carries the author's name. */
+    first: boolean;
+    /** The last of a run: it carries the time and the read mark. */
+    last: boolean;
+    time: ChatTimeOptions;
+    participants: readonly ChatParticipant[];
+    userId: ChatId;
+    /** The message this one answers, when it is held. */
+    quoted?: ChatMessage;
+    onReply?: (message: ChatMessage) => void;
+    onRemove?: (message: ChatMessage) => void;
+    onRetry?: (clientId: string) => void;
+    onDiscard?: (clientId: string) => void;
+    onOpenQuoted?: (id: ChatId) => void;
+}
+/**
+ * One message. Its own messages sit on the right in the primary tint, everyone else's on the left on a surface. The
+ * actions are one row of icon buttons that appear on hover or keyboard focus — and never move the message, so a long
+ * thread does not jump under the pointer.
+ */
+export declare function ChatMessageItem({ message, mine, first, last, time, participants, userId, quoted, onReply, onRemove, onRetry, onDiscard, onOpenQuoted }: ChatMessageProps): import("react").JSX.Element;
+/** Everyone in a conversation, with what each one is here. */
+export declare function ChatParticipantList({ participants, userId, empty }: {
+    participants: readonly ChatParticipant[];
+    userId: ChatId;
+    empty?: string;
+}): import("react").JSX.Element;
+/** A thread with nothing in it yet. */
+export declare function ChatEmpty({ message, hint }: {
+    message?: string;
+    hint?: ReactNode;
+}): import("react").JSX.Element;
+/** Something that did not load, with a way to try again. */
+export declare function ChatFailure({ message, onRetry }: {
+    message: string;
+    onRetry?: () => void;
+}): import("react").JSX.Element;
+/** Messages on their way in. */
+export declare function ChatLoading({ label }: {
+    label?: string;
+}): import("react").JSX.Element;