nexus-shared 1.1.21 → 3.0.0

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;

package/dist/Components/Chats/ChatParts.js

@@ -0,0 +1,100 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconAlertCircle, iconCheck, iconChecks, iconCornerUpLeft, iconFile, iconLoader2, iconRefresh, iconTrash, iconX, InlineIcon } from "nexus-icons";
+import { useState } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { chatDeliveryState, chatFileSize, chatTimeLabel, sameChatId, CHAT_DELIVERY_LABELS } from "../../Helpers/ChatHelpers.js";
+import { avatarTone, initials } from "../../Helpers/DropdownHelpers.js";
+import { markdownToPlainText } from "../../Helpers/MarkdownHelpers.js";
+import { MarkdownView } from "../Viewers/MarkdownView.js";
+/*
+ * The pieces a chat is drawn from: the avatar, one message, the lines that break a thread into days and into read and
+ * unread, and the participants. Each one draws what it is given and nothing else — the state is in `ChatStore` — so
+ * the same pieces serve the panel, a page-wide chat, and a demo with messages in memory.
+ */
+/** 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 function ChatAvatar({ name, src, size = "md" }) {
+    const url = typeof src === "string" ? src.trim() : "";
+    const [failed, setFailed] = useState(null);
+    const photo = url !== "" && failed !== url;
+    return (_jsx("span", { className: cx("nx-chat-avatar", size === "sm" && "nx-chat-avatar--sm"), "data-tone": photo ? undefined : avatarTone(name), "aria-hidden": "true", children: photo ? _jsx("img", { src: url, alt: "", loading: "lazy", decoding: "async", onError: () => setFailed(url) }) : initials(name) }));
+}
+/** The day a run of messages was written: "Today", "Yesterday", or the date in the user's calendar. */
+export function ChatDayDivider({ label }) {
+    return (_jsx("div", { className: "nx-chat-day", role: "separator", children: _jsx("span", { children: label }) }));
+}
+/** Where reading stopped last time. It stays where it was put, so it does not slide away as the thread is read. */
+export function ChatUnreadLine({ count, label = "New messages" }) {
+    return (_jsx("div", { className: "nx-chat-unread-line", role: "separator", children: _jsx("span", { children: count && count > 0 ? `${label} · ${count}` : label }) }));
+}
+/**
+ * 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 function ChatReadMark({ message, participants, userId }) {
+    const state = chatDeliveryState(message, userId, participants);
+    const read = (message.readBy ?? []).filter(id => !sameChatId(id, userId));
+    const label = state === "read" && read.length > 1 ? `Read by ${read.length}` : CHAT_DELIVERY_LABELS[state];
+    const icon = state === "sending" ? iconLoader2 : state === "failed" ? iconAlertCircle : state === "sent" ? iconCheck : iconChecks;
+    // The word is on the wrapper, so it is both the tooltip on hover and the name a screen reader reads for the mark.
+    return (_jsx("span", { className: cx("nx-chat-mark", `nx-chat-mark--${state}`, (state === "read" || state === "read-all") && "nx-chat-mark--seen", state === "sending" && "nx-spin"), role: "img", "aria-label": label, title: label, "data-state": state, children: _jsx(InlineIcon, { icon: icon }) }));
+}
+/** Files on a message: the name, the size, and a link when the file has a URL. */
+export function ChatAttachments({ attachments }) {
+    return (_jsx("ul", { className: "nx-chat-files", children: attachments.map((file, index) => {
+            const size = chatFileSize(file.size);
+            const body = (_jsxs(_Fragment, { children: [_jsx(InlineIcon, { icon: iconFile }), _jsx("span", { className: "nx-chat-file__name", children: file.name }), size && _jsx("span", { className: "nx-chat-file__size", children: size })] }));
+            return (_jsx("li", { className: "nx-chat-file", children: file.url ? (_jsx("a", { href: file.url, target: "_blank", rel: "noreferrer", children: body })) : (_jsx("span", { children: body })) }, `${String(file.id ?? file.name)}-${index}`));
+        }) }));
+}
+/** The message a reply answers, above the reply itself. */
+export function ChatQuote({ message, onOpen }) {
+    if (!message)
+        return _jsx("div", { className: "nx-chat-quote nx-chat-quote--gone", children: "The message this answers is no longer here." });
+    const body = (_jsxs(_Fragment, { children: [_jsx("span", { className: "nx-chat-quote__author", children: message.authorName || "Unknown" }), _jsx("span", { className: "nx-chat-quote__body", children: markdownToPlainText(message.body) })] }));
+    if (!onOpen)
+        return _jsx("div", { className: "nx-chat-quote", children: body });
+    return (_jsx("button", { type: "button", className: "nx-chat-quote", onClick: () => onOpen(message.id), children: body }));
+}
+/** A note the system wrote, not a person: no side, no avatar, no actions. */
+export function ChatSystemNote({ message, time }) {
+    return (_jsxs("div", { className: "nx-chat-note", children: [_jsx("span", { children: markdownToPlainText(message.body) }), _jsx("time", { dateTime: message.createdAt, children: chatTimeLabel(message.createdAt, time) })] }));
+}
+/**
+ * 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 function ChatMessageItem({ message, mine, first, last, time, participants, userId, quoted, onReply, onRemove, onRetry, onDiscard, onOpenQuoted }) {
+    const failed = message.status === "failed";
+    const waiting = message.status === "sending";
+    const actions = [];
+    if (onReply && !failed && !waiting)
+        actions.push(_jsx(ChatAction, { icon: iconCornerUpLeft, label: "Reply", onClick: () => onReply(message) }, "reply"));
+    if (onRemove && mine && !failed && !waiting)
+        actions.push(_jsx(ChatAction, { icon: iconTrash, label: "Delete", tone: "danger", onClick: () => onRemove(message) }, "remove"));
+    return (_jsxs("div", { className: cx("nx-chat-msg", mine ? "nx-chat-msg--mine" : "nx-chat-msg--theirs", first && "nx-chat-msg--first", last && "nx-chat-msg--last", failed && "nx-chat-msg--failed"), children: [_jsxs("div", { className: "nx-chat-msg__bubble", children: [first && !mine && _jsx("span", { className: "nx-chat-msg__author", children: message.authorName || "Unknown" }), message.replyToId !== null && message.replyToId !== undefined && _jsx(ChatQuote, { message: quoted, onOpen: onOpenQuoted }), message.body && _jsx(MarkdownView, { className: "nx-chat-msg__body", value: message.body }), message.attachments && message.attachments.length > 0 && _jsx(ChatAttachments, { attachments: message.attachments }), _jsxs("span", { className: "nx-chat-msg__meta", children: [message.editedAt && _jsx("span", { className: "nx-chat-msg__edited", children: "edited" }), _jsx("time", { dateTime: message.createdAt, children: chatTimeLabel(message.createdAt, time) }), mine && _jsx(ChatReadMark, { message: message, participants: participants, userId: userId })] }), actions.length > 0 && _jsx("span", { className: "nx-chat-msg__actions", children: actions })] }), failed && (_jsxs("div", { className: "nx-chat-msg__failure", children: [_jsx(InlineIcon, { icon: iconAlertCircle }), _jsx("span", { children: message.error || "Not sent." }), message.clientId && onRetry && (_jsxs("button", { type: "button", onClick: () => onRetry(message.clientId), children: [_jsx(InlineIcon, { icon: iconRefresh }), " Retry"] })), message.clientId && onDiscard && (_jsxs("button", { type: "button", onClick: () => onDiscard(message.clientId), children: [_jsx(InlineIcon, { icon: iconX }), " Discard"] }))] }))] }));
+}
+/** One icon button in a message's action row. */
+function ChatAction({ icon, label, tone, onClick }) {
+    return (_jsx("button", { type: "button", className: cx("nx-chat-msg__action", tone === "danger" && "nx-chat-msg__action--danger"), onClick: onClick, "aria-label": label, title: label, children: _jsx(InlineIcon, { icon: icon }) }));
+}
+/** Everyone in a conversation, with what each one is here. */
+export function ChatParticipantList({ participants, userId, empty = "Nobody else yet." }) {
+    if (participants.length === 0)
+        return _jsx("p", { className: "nx-chat-aside__empty", children: empty });
+    return (_jsx("ul", { className: "nx-chat-people", children: participants.map(person => (_jsxs("li", { className: cx("nx-chat-person", person.inactive && "nx-chat-person--inactive"), children: [_jsx(ChatAvatar, { name: person.name, src: person.avatar, size: "sm" }), _jsxs("span", { className: "nx-chat-person__text", children: [_jsxs("span", { className: "nx-chat-person__name", children: [person.name, sameChatId(person.id, userId) && _jsx("span", { className: "nx-chat-person__you", children: "you" })] }), (person.role || person.readOnly) && _jsx("span", { className: "nx-chat-person__role", children: person.readOnly ? [person.role, "reads only"].filter(Boolean).join(" · ") : person.role })] })] }, String(person.id)))) }));
+}
+/** A thread with nothing in it yet. */
+export function ChatEmpty({ message = "No messages yet.", hint }) {
+    return (_jsxs("div", { className: "nx-chat-empty", children: [_jsx("p", { children: message }), hint && _jsx("p", { className: "nx-chat-empty__hint", children: hint })] }));
+}
+/** Something that did not load, with a way to try again. */
+export function ChatFailure({ message, onRetry }) {
+    return (_jsxs("div", { className: "nx-chat-failure", role: "alert", children: [_jsx(InlineIcon, { icon: iconAlertCircle }), _jsx("span", { children: message }), onRetry && (_jsxs("button", { type: "button", onClick: onRetry, children: [_jsx(InlineIcon, { icon: iconRefresh }), " Try again"] }))] }));
+}
+/** Messages on their way in. */
+export function ChatLoading({ label = "Loading…" }) {
+    return (_jsxs("div", { className: "nx-chat-loading", "aria-live": "polite", children: [_jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin" }), _jsx("span", { children: label })] }));
+}

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

@@ -0,0 +1,22 @@
+import { type ChatTimeOptions } from "../../Helpers/ChatHelpers.ts";
+import type { ChatSnapshot, ChatStore } from "../../Helpers/ChatStore.ts";
+import type { ChatId, ChatMessage } from "../../Interfaces/ChatInterfaces.ts";
+export interface ChatThreadProps {
+    store: ChatStore;
+    state: ChatSnapshot;
+    /** Who is reading: their messages sit on the right. */
+    userId: ChatId;
+    /** The user's date settings and zone. Default: their own, from local storage. */
+    time?: ChatTimeOptions;
+    /** A message can be answered. Default true. */
+    replies?: boolean;
+    /** A reply was started: the panel puts the message in the composer. */
+    onReply?: (message: ChatMessage) => void;
+    /** Reading the newest message marks the conversation read. Default true. */
+    marksRead?: boolean;
+    /** Shown when there is not a single message. */
+    emptyMessage?: string;
+    className?: string;
+}
+/** The messages of a conversation, in days and runs, with the lines that break them up. */
+export declare function ChatThread({ store, state, userId, time, replies, onReply, marksRead, emptyMessage, className }: ChatThreadProps): import("react").JSX.Element;

package/dist/Components/Chats/ChatThread.js

@@ -0,0 +1,96 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconArrowDown, iconMessageCircle, InlineIcon } from "nexus-icons";
+import { Fragment, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { chatBadgeText, chatMessageKey, groupChatMessages, sameChatId } from "../../Helpers/ChatHelpers.js";
+import { useBrowserTimeZone, useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { Button } from "../Documents/Button.js";
+import { ChatAvatar, ChatDayDivider, ChatEmpty, ChatFailure, ChatLoading, ChatMessageItem, ChatSystemNote, ChatUnreadLine } from "./ChatParts.js";
+/*
+ * The thread: the conversation itself, scrolling. It opens at the newest message, keeps itself at the bottom while the
+ * reader is already there, and when they are not, it leaves the scroll alone and offers a button down to the newest
+ * with the number of messages that arrived. Reaching the top loads the page above and holds the reader's place.
+ *
+ * Reading marks the conversation read, but only once the newest message is actually on screen: a panel opened and left
+ * scrolled up has not been read.
+ */
+/** How close to an edge counts as being at it. */
+const EDGE = 32;
+/** How near the top loading the page above starts. */
+const TOP_EDGE = 120;
+/** The messages of a conversation, in days and runs, with the lines that break them up. */
+export function ChatThread({ store, state, userId, time, replies = true, onReply, marksRead = true, emptyMessage, className }) {
+    const preferences = useDatePreferences();
+    const zone = useBrowserTimeZone();
+    const settings = useMemo(() => ({ ...preferences, ...(zone && { timeZone: zone }), ...time }), [preferences, zone, time]);
+    const listRef = useRef(null);
+    const [atBottom, setAtBottom] = useState(true);
+    const [missed, setMissed] = useState(0);
+    // What the scroll looked like before a page of older messages arrived, so the reader's place can be given back.
+    const anchor = useRef(null);
+    const lastKey = useRef(null);
+    const count = useRef(0);
+    const days = useMemo(() => groupChatMessages(state.messages, { userId, unreadFrom: state.unreadFrom, ...settings }), [state.messages, state.unreadFrom, userId, settings]);
+    const byId = useMemo(() => new Map(state.messages.map(message => [String(message.id), message])), [state.messages]);
+    const scrollToEnd = useCallback((smooth) => {
+        const list = listRef.current;
+        if (!list)
+            return;
+        // Windows with its animations off reports reduced motion, and a smooth scroll there may never run: jump instead.
+        const reduced = typeof window !== "undefined" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+        list.scrollTo({ top: list.scrollHeight, behavior: smooth && !reduced ? "smooth" : "auto" });
+    }, []);
+    // New messages: stay at the bottom when already there, otherwise hold the place and count what came in.
+    useLayoutEffect(() => {
+        const list = listRef.current;
+        if (!list)
+            return;
+        if (anchor.current) {
+            // A page of older messages: the scroll keeps the message it was on, rather than jumping to the new top.
+            list.scrollTop = anchor.current.top + (list.scrollHeight - anchor.current.height);
+            anchor.current = null;
+            count.current = state.messages.length;
+            return;
+        }
+        const newest = state.messages[state.messages.length - 1];
+        const key = newest ? chatMessageKey(newest) : null;
+        const grew = state.messages.length > count.current;
+        const changed = key !== lastKey.current;
+        count.current = state.messages.length;
+        lastKey.current = key;
+        if (!grew || !changed)
+            return;
+        if (atBottom || sameChatId(newest?.authorId, userId))
+            scrollToEnd(lastKey.current !== null && missed === 0);
+        else
+            setMissed(value => value + 1);
+        // `missed` is read, not depended on: a second message must not re-run the first one's scroll.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [state.messages, atBottom, userId, scrollToEnd]);
+    // The conversation counts as read once its newest message has been on screen.
+    useEffect(() => {
+        if (!marksRead || !atBottom || state.loading || state.summary.unreadCount === 0)
+            return;
+        void store.markRead();
+    }, [marksRead, atBottom, state.loading, state.summary.unreadCount, store]);
+    const onScroll = useCallback(() => {
+        const list = listRef.current;
+        if (!list)
+            return;
+        const bottom = list.scrollHeight - list.scrollTop - list.clientHeight <= EDGE;
+        setAtBottom(bottom);
+        if (bottom)
+            setMissed(0);
+        if (list.scrollTop <= TOP_EDGE && state.hasMore && !state.loadingOlder) {
+            anchor.current = { height: list.scrollHeight, top: list.scrollTop };
+            void store.loadOlder();
+        }
+    }, [state.hasMore, state.loadingOlder, store]);
+    const quiet = !state.loading && state.messages.length === 0;
+    return (_jsxs("div", { className: cx("nx-chat-thread", className), children: [_jsxs("div", { className: "nx-chat-thread__list", ref: listRef, onScroll: onScroll, role: "log", "aria-live": "polite", "aria-relevant": "additions", tabIndex: 0, children: [state.loadingOlder && _jsx(ChatLoading, { label: "Loading earlier messages\u2026" }), !state.loadingOlder && state.hasMore && (_jsx("div", { className: "nx-chat-thread__older", children: _jsx(Button, { size: "sm", variant: "ghost", onClick: () => void store.loadOlder(), children: "Earlier messages" }) })), state.loading && state.messages.length === 0 && _jsx(ChatLoading, { label: "Loading the conversation\u2026" }), state.error && _jsx(ChatFailure, { message: state.error, onRetry: () => void store.refresh() }), quiet && !state.error && _jsx(ChatEmpty, { message: emptyMessage ?? "No messages yet.", hint: _jsxs(_Fragment, { children: [_jsx(InlineIcon, { icon: iconMessageCircle }), " Write the first one below."] }) }), days.map(day => (_jsxs("section", { className: "nx-chat-thread__day", children: [_jsx(ChatDayDivider, { label: day.label }), day.runs.map((run, runIndex) => (_jsxs(Fragment, { children: [run.startsUnread && _jsx(ChatUnreadLine, { count: state.summary.unreadCount }), _jsx("div", { className: cx("nx-chat-run", run.mine && "nx-chat-run--mine", run.system && "nx-chat-run--system"), children: run.system ? (run.messages.map(message => _jsx(ChatSystemNote, { message: message, time: settings }, chatMessageKey(message)))) : (_jsxs(_Fragment, { children: [!run.mine && _jsx(ChatAvatarColumn, { name: run.authorName, src: run.authorAvatar }), _jsx("div", { className: "nx-chat-run__messages", children: run.messages.map((message, index) => (_jsx(ChatMessageItem, { message: message, mine: run.mine, first: index === 0, last: index === run.messages.length - 1, time: settings, participants: state.participants, userId: userId, quoted: message.replyToId ? byId.get(String(message.replyToId)) : undefined, onReply: replies && onReply ? onReply : undefined, onRemove: run.mine && state.features.remove ? message => void store.remove(message.id) : undefined, onRetry: store.retry, onDiscard: store.discard }, chatMessageKey(message)))) })] })) })] }, `${day.date}-${runIndex}`)))] }, day.date)))] }), !atBottom && (_jsxs("button", { type: "button", className: "nx-chat-thread__jump", onClick: () => scrollToEnd(true), "aria-label": missed > 0 ? `${missed} new, go to the newest` : "Go to the newest message", children: [_jsx(InlineIcon, { icon: iconArrowDown }), missed > 0 && _jsx("span", { className: "nx-chat-thread__jump-count", children: chatBadgeText(missed) })] }))] }));
+}
+/** The avatar beside a run of somebody else's messages, kept out of the bubbles so they line up under each other. */
+function ChatAvatarColumn({ name, src }) {
+    return (_jsx("div", { className: "nx-chat-run__avatar", children: _jsx(ChatAvatar, { name: name, src: src }) }));
+}

package/dist/Components/Documents/Button.d.ts

@@ -0,0 +1,29 @@
+import type { ComponentPropsWithRef, ReactNode } from "react";
+import type { Size, Tone } from "../../Interfaces/TypeInterfaces.ts";
+export type ButtonVariant = "primary" | "secondary" | "ghost" | "danger";
+export type ButtonHoverTone = Exclude<Tone, "neutral">;
+export interface ButtonProps extends ComponentPropsWithRef<"button"> {
+    /** Default `secondary`. Use one `primary` per area for the main action. */
+    variant?: ButtonVariant;
+    /** Default `md`. */
+    size?: Size;
+    /**
+     * Keeps a `secondary` or `ghost` button neutral until hover or keyboard focus, then shows this color
+     * on the border, a light background, and the text. For actions that should not shout in a list or table,
+     * e.g. `hoverTone="danger"` on Delete.
+     */
+    hoverTone?: ButtonHoverTone;
+    /** Icon before the label, e.g. `<InlineIcon icon={iconPlus} />` or `<Icon name="wifi" />`. */
+    icon?: ReactNode;
+    /** Icon after the label. */
+    iconEnd?: ReactNode;
+    /** Shows a spinner in place of `icon` and blocks clicks while an action runs. */
+    loading?: boolean;
+    /** Fills the width of its container. */
+    block?: boolean;
+}
+/**
+ * A button. Without children it becomes a square icon button, which then needs an `aria-label`.
+ * Has no client state, so it renders in server and client components alike.
+ */
+export declare function Button({ variant, size, hoverTone, icon, iconEnd, loading, block, type, disabled, className, children, ...rest }: ButtonProps): import("react").JSX.Element;

package/dist/Components/Documents/Button.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { InlineIcon, iconLoader2 } from "nexus-icons";
+import { cx } from "../../Helpers/ClassHelpers.js";
+/**
+ * A button. Without children it becomes a square icon button, which then needs an `aria-label`.
+ * Has no client state, so it renders in server and client components alike.
+ */
+export function Button({ variant = "secondary", size = "md", hoverTone, icon, iconEnd, loading = false, block = false, type = "button", disabled, className, children, ...rest }) {
+    const hasLabel = children !== undefined && children !== null && children !== false;
+    return (_jsxs("button", { type: type, className: cx("nx-btn", `nx-btn--${variant}`, `nx-btn--${size}`, hoverTone && `nx-btn--hover-${hoverTone}`, block && "nx-btn--block", !hasLabel && "nx-btn--icon", className), disabled: disabled || loading, "aria-busy": loading || undefined, ...rest, children: [loading ? _jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin" }) : icon, hasLabel && _jsx("span", { className: "nx-btn__label", children: children }), iconEnd] }));
+}

package/dist/Components/Documents/Menu.d.ts

@@ -0,0 +1,102 @@
+import { type KeyboardEvent, type MouseEvent, type PointerEvent, type ReactElement, type ReactNode, type Ref, type ToggleEvent } from "react";
+import { type PopoverAlign } from "../../Helpers/PopoverHelpers.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+export interface MenuItem<T extends string = string> {
+    value: T;
+    label: ReactNode;
+    /** A second line in muted text: what the action does, or when to use it. */
+    description?: ReactNode;
+    /** Icon before the label, e.g. `<InlineIcon icon={iconPencil} />`. */
+    icon?: ReactNode;
+    /** Shown at the end in muted text, e.g. "Ctrl+C". Display only: the page binds the key itself. */
+    shortcut?: string;
+    /** `danger` draws the item in the danger color, for Delete and the like. */
+    tone?: "danger";
+    disabled?: boolean;
+    /** Renders the item as a link. */
+    href?: string;
+    /** The link's target, e.g. `_blank`. */
+    target?: string;
+    /** In a `radio` or `checkbox` menu: the item shows a check mark. */
+    checked?: boolean;
+    /** Tooltip. */
+    title?: string;
+}
+/** A line between groups of items. */
+export interface MenuSeparator {
+    separator: true;
+}
+/** A small heading above a group of items. */
+export interface MenuHeading {
+    heading: ReactNode;
+}
+export type MenuEntry<T extends string = string> = MenuItem<T> | MenuSeparator | MenuHeading;
+export declare function isMenuItem<T extends string>(entry: MenuEntry<T>): entry is MenuItem<T>;
+/** `menu`: actions. `radio`: one item is checked at a time. `checkbox`: any number of items can be checked. */
+export type MenuKind = "menu" | "radio" | "checkbox";
+export interface MenuPanelProps<T extends string = string> {
+    id: string;
+    items: readonly MenuEntry<T>[];
+    /** Called with the item's value when it is chosen by click, Enter, or Space. */
+    onSelect?: (value: T, item: MenuItem<T>) => void;
+    /** Default `menu`. */
+    kind?: MenuKind;
+    /** Default `md`. */
+    size?: Size;
+    /** Closes the menu once an item is chosen. Default true; `false` suits checkbox menus. */
+    closeOnSelect?: boolean;
+    className?: string;
+    ref: Ref<HTMLDivElement>;
+    onToggle?: (event: ToggleEvent<HTMLDivElement>) => void;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+}
+/**
+ * The list of a menu inside a native popover. Arrow keys move between items, Home and End jump, a letter jumps to
+ * the next item starting with it, Enter or Space chooses, Esc closes, and Tab closes and moves on.
+ */
+export declare function MenuPanel<T extends string>({ id, items, onSelect, kind, size, closeOnSelect, className, ref, onToggle, ...labelling }: MenuPanelProps<T>): import("react").JSX.Element;
+/** What `Menu` adds to its trigger. A component used as the trigger must pass these on to its button. */
+export interface MenuTriggerProps {
+    ref?: Ref<HTMLButtonElement>;
+    id?: string;
+    "aria-haspopup"?: "menu";
+    "aria-expanded"?: boolean;
+    "aria-controls"?: string;
+    onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+    onPointerDown?: (event: PointerEvent<HTMLButtonElement>) => void;
+    onKeyDown?: (event: KeyboardEvent<HTMLButtonElement>) => void;
+}
+export interface MenuProps<T extends string = string> extends Pick<MenuPanelProps<T>, "items" | "onSelect" | "kind" | "size" | "closeOnSelect" | "className"> {
+    /** The button that opens the menu, such as a `Button`. It receives an id, aria attributes, and click and key handlers. */
+    children: ReactElement<MenuTriggerProps>;
+    /** Which edge of the button the menu lines up with. Default `start`. */
+    align?: PopoverAlign;
+    /** Name of the menu for screen readers. Default: the button's text. */
+    "aria-label"?: string;
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * A dropdown menu: a button that opens a list of actions in a native popover under it (above it when there is no
+ * room). Click or Enter opens it, ArrowDown opens it on the first item, Esc closes it and returns focus to the button.
+ *
+ * @example
+ * <Menu items={items} onSelect={value => run(value)}>
+ *   <Button iconEnd={<InlineIcon icon={iconChevronDown} />}>Actions</Button>
+ * </Menu>
+ */
+export declare function Menu<T extends string>({ children, align, "aria-label": ariaLabel, onOpenChange, ...panelProps }: MenuProps<T>): import("react").JSX.Element;
+export interface ContextMenuProps<T extends string = string> extends Pick<MenuPanelProps<T>, "items" | "onSelect" | "kind" | "size" | "closeOnSelect" | "className"> {
+    /** The content the menu belongs to: a row, a card, a list. */
+    children: ReactNode;
+    /** Name of the menu for screen readers. Default "Context menu". */
+    "aria-label"?: string;
+    /** Leaves the browser's own menu in place. */
+    disabled?: boolean;
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * A menu that opens where the user right-clicks (or presses Shift+F10) over its content, kept inside the window.
+ * The wrapper takes no space of its own (`display: contents`), so it can wrap a table row or a grid cell.
+ */
+export declare function ContextMenu<T extends string>({ children, "aria-label": ariaLabel, disabled, onOpenChange, ...panelProps }: ContextMenuProps<T>): import("react").JSX.Element;