nexus-shared 1.1.21 → 3.0.0

package/dist/Client.Index.d.ts

@@ -0,0 +1,55 @@
+export * from "./Components/Chats/Chat.tsx";
+export * from "./Components/Chats/ChatButton.tsx";
+export * from "./Components/Chats/ChatComposer.tsx";
+export * from "./Components/Chats/ChatConversations.tsx";
+export * from "./Components/Chats/ChatPanel.tsx";
+export * from "./Components/Chats/ChatParts.tsx";
+export * from "./Components/Chats/ChatThread.tsx";
+export * from "./Components/Documents/Menu.tsx";
+export * from "./Components/Documents/SplitButton.tsx";
+export * from "./Components/Documents/TabButtons.tsx";
+export * from "./Components/Forms/ApiForm.tsx";
+export * from "./Components/Forms/Crud.tsx";
+export * from "./Components/Forms/CrudParts.tsx";
+export * from "./Components/Forms/ExcelImport.tsx";
+export * from "./Components/Forms/Form.tsx";
+export * from "./Components/Forms/SubmitForm.tsx";
+export * from "./Components/Inputs/Calendar.tsx";
+export * from "./Components/Inputs/CheckBox.tsx";
+export * from "./Components/Inputs/CheckBoxGroup.tsx";
+export * from "./Components/Inputs/DatePicker.tsx";
+export * from "./Components/Inputs/DateRangePicker.tsx";
+export * from "./Components/Inputs/DateTimePicker.tsx";
+export * from "./Components/Inputs/Dropdown.tsx";
+export * from "./Components/Inputs/GroupForm.tsx";
+export * from "./Components/Inputs/InputRenderer.tsx";
+export * from "./Components/Inputs/MarkdownEditor.tsx";
+export * from "./Components/Inputs/NumberBox.tsx";
+export * from "./Components/Inputs/RadioGroup.tsx";
+export * from "./Components/Inputs/ReadOnlyNotice.tsx";
+export * from "./Components/Inputs/RichTextEditor.tsx";
+export * from "./Components/Inputs/Slider.tsx";
+export * from "./Components/Inputs/TabularForm.tsx";
+export * from "./Components/Inputs/TextArea.tsx";
+export * from "./Components/Inputs/TextBox.tsx";
+export * from "./Components/Inputs/TimePanel.tsx";
+export * from "./Components/Inputs/TimePicker.tsx";
+export * from "./Components/Inputs/TreeView.tsx";
+export * from "./Components/Layouts/MessageBox.tsx";
+export * from "./Components/Layouts/Popup.tsx";
+export * from "./Components/Layouts/PopupDock.tsx";
+export * from "./Components/Layouts/PopupHost.tsx";
+export * from "./Components/Layouts/PopupRules.ts";
+export * from "./Components/Layouts/ThemePicker.tsx";
+export * from "./Components/Layouts/ThemeSwitcher.tsx";
+export * from "./Components/Layouts/Toaster.tsx";
+export * from "./Components/Viewers/DataTable.tsx";
+export * from "./Components/Viewers/DataTableParts.tsx";
+export * from "./Helpers/ChatHooks.ts";
+export * from "./Helpers/DatePreferences.ts";
+export * from "./Helpers/DragHelpers.ts";
+export * from "./Helpers/PopoverHelpers.ts";
+export * from "./Services/BrowserApi.ts";
+export * from "./Services/ChatApi.ts";
+export * from "./Services/ExcelApi.ts";
+export * from "./Services/ThemeService.ts";

package/dist/Client.Index.js

@@ -0,0 +1,60 @@
+// Client components and browser services: files here start with "use client" or use browser APIs.
+// Import from "nexus-shared/client".
+// Components
+export * from "./Components/Chats/Chat.js";
+export * from "./Components/Chats/ChatButton.js";
+export * from "./Components/Chats/ChatComposer.js";
+export * from "./Components/Chats/ChatConversations.js";
+export * from "./Components/Chats/ChatPanel.js";
+export * from "./Components/Chats/ChatParts.js";
+export * from "./Components/Chats/ChatThread.js";
+export * from "./Components/Documents/Menu.js";
+export * from "./Components/Documents/SplitButton.js";
+export * from "./Components/Documents/TabButtons.js";
+export * from "./Components/Forms/ApiForm.js";
+export * from "./Components/Forms/Crud.js";
+export * from "./Components/Forms/CrudParts.js";
+export * from "./Components/Forms/ExcelImport.js";
+export * from "./Components/Forms/Form.js";
+export * from "./Components/Forms/SubmitForm.js";
+export * from "./Components/Inputs/Calendar.js";
+export * from "./Components/Inputs/CheckBox.js";
+export * from "./Components/Inputs/CheckBoxGroup.js";
+export * from "./Components/Inputs/DatePicker.js";
+export * from "./Components/Inputs/DateRangePicker.js";
+export * from "./Components/Inputs/DateTimePicker.js";
+export * from "./Components/Inputs/Dropdown.js";
+export * from "./Components/Inputs/GroupForm.js";
+export * from "./Components/Inputs/InputRenderer.js";
+export * from "./Components/Inputs/MarkdownEditor.js";
+export * from "./Components/Inputs/NumberBox.js";
+export * from "./Components/Inputs/RadioGroup.js";
+export * from "./Components/Inputs/ReadOnlyNotice.js";
+export * from "./Components/Inputs/RichTextEditor.js";
+export * from "./Components/Inputs/Slider.js";
+export * from "./Components/Inputs/TabularForm.js";
+export * from "./Components/Inputs/TextArea.js";
+export * from "./Components/Inputs/TextBox.js";
+export * from "./Components/Inputs/TimePanel.js";
+export * from "./Components/Inputs/TimePicker.js";
+export * from "./Components/Inputs/TreeView.js";
+export * from "./Components/Layouts/MessageBox.js";
+export * from "./Components/Layouts/Popup.js";
+export * from "./Components/Layouts/PopupDock.js";
+export * from "./Components/Layouts/PopupHost.js";
+export * from "./Components/Layouts/PopupRules.js";
+export * from "./Components/Layouts/ThemePicker.js";
+export * from "./Components/Layouts/ThemeSwitcher.js";
+export * from "./Components/Layouts/Toaster.js";
+export * from "./Components/Viewers/DataTable.js";
+export * from "./Components/Viewers/DataTableParts.js";
+// Helpers
+export * from "./Helpers/ChatHooks.js";
+export * from "./Helpers/DatePreferences.js";
+export * from "./Helpers/DragHelpers.js";
+export * from "./Helpers/PopoverHelpers.js";
+// Services
+export * from "./Services/BrowserApi.js";
+export * from "./Services/ChatApi.js";
+export * from "./Services/ExcelApi.js";
+export * from "./Services/ThemeService.js";

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

@@ -0,0 +1,28 @@
+import { type ReactNode } from "react";
+import type { ChatDomainValue } from "../../Interfaces/ChatInterfaces.ts";
+import { type PopupSize } from "../Layouts/Popup.tsx";
+import { type ChatPanelProps } from "./ChatPanel.tsx";
+export interface ChatProps<TDomain extends ChatDomainValue = ChatDomainValue> extends Omit<ChatPanelProps<TDomain>, "scope" | "header" | "enabled" | "height"> {
+    /** Which kind of record: `EDomainTypes.Leave`. */
+    domain: TDomain;
+    /** The record's own id. */
+    parentId: string | number;
+    /** Who is reading and writing. */
+    userId: string | number;
+    /** What the icon is called, in its tooltip and for a screen reader. Default: the domain's name, else "Discussion". */
+    label?: string;
+    /** Default `md`, as the other controls in a row; `sm` for a dense table. */
+    buttonSize?: "sm" | "md";
+    /** How wide the popup is. Default `md` (560px). */
+    popupSize?: PopupSize;
+    /** How tall the conversation is inside the popup. Default `min(60vh, 520px)`. */
+    height?: number | string;
+    /** The popup's title bar. Default: the panel's `title`, else the domain's name and the record's id. */
+    popupTitle?: ReactNode;
+    /** Opened or closed. */
+    onOpenChange?: (open: boolean) => void;
+    /** Class of the trigger icon. */
+    className?: string;
+}
+/** The chat icon for a record, and the conversation in a popup. */
+export declare function Chat<TDomain extends ChatDomainValue = ChatDomainValue>({ domain, parentId, userId, label, buttonSize, popupSize, height, popupTitle, onOpenChange, className, summary, title, description, ...panel }: ChatProps<TDomain>): import("react").JSX.Element;

package/dist/Components/Chats/Chat.js

@@ -0,0 +1,19 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconMessageCircle, InlineIcon } from "nexus-icons";
+import { useState } from "react";
+import { chatDomainLabel } from "../../Helpers/ChatBackend.js";
+import { Popup } from "../Layouts/Popup.js";
+import { ChatButton } from "./ChatButton.js";
+import { ChatPanel } from "./ChatPanel.js";
+/** The chat icon for a record, and the conversation in a popup. */
+export function Chat({ domain, parentId, userId, label, buttonSize = "md", popupSize = "md", height, popupTitle, onOpenChange, className, summary, title, description, ...panel }) {
+    const [open, setOpen] = useState(false);
+    const scope = { domain, parentId, userId };
+    const named = title ?? (chatDomainLabel(domain) ? `${chatDomainLabel(domain)} · #${String(parentId)}` : `Discussion · #${String(parentId)}`);
+    const change = (next) => {
+        setOpen(next);
+        onOpenChange?.(next);
+    };
+    return (_jsxs(_Fragment, { children: [_jsx(ChatButton, { scope: scope, summary: summary, label: label ?? chatDomainLabel(domain) ?? "Discussion", size: buttonSize, className: className, onClick: () => change(true) }), _jsx(Popup, { open: open, onClose: () => change(false), title: popupTitle ?? named, description: description, icon: _jsx(InlineIcon, { icon: iconMessageCircle }), variant: "window", size: popupSize, reopen: "restore", flush: true, closeOnBackdrop: false, children: _jsx(ChatPanel, { ...panel, scope: scope, summary: summary, title: named, header: false, enabled: open, height: height ?? "100%" }) })] }));
+}

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;