nexus-shared 2.0.0 → 3.1.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";
+/** The shared `Avatar`, under the name the chat has always exported it by. */
+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,96 @@
+"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 { cx } from "../../Helpers/ClassHelpers.js";
+import { chatDeliveryState, chatFileSize, chatTimeLabel, sameChatId, CHAT_DELIVERY_LABELS } from "../../Helpers/ChatHelpers.js";
+import { markdownToPlainText } from "../../Helpers/MarkdownHelpers.js";
+import { Avatar } from "../Viewers/Avatar.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.
+ */
+/** The shared `Avatar`, under the name the chat has always exported it by. */
+export function ChatAvatar({ name, src, size = "md" }) {
+    return _jsx(Avatar, { name: name, src: src, size: size });
+}
+/** 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 { smoothScrollAllowed } from "../../Helpers/AnimationHelpers.js";
+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;
+        // Smooth only when the visitor and the system both allow motion; otherwise it jumps.
+        list.scrollTo({ top: list.scrollHeight, behavior: smooth && smoothScrollAllowed() ? "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

@@ -21,9 +21,14 @@ export interface ButtonProps extends ComponentPropsWithRef<"button"> {
     loading?: boolean;
     /** Fills the width of its container. */
     block?: boolean;
+    /**
+     * A small dot on the corner. `true` is the red dot of something new, such as unread notifications; `"primary"` marks
+     * a state that is on, such as filters.
+     */
+    dot?: boolean | "primary";
 }
 /**
  * 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;
+export declare function Button({ variant, size, hoverTone, icon, iconEnd, loading, block, dot, type, disabled, className, children, ...rest }: ButtonProps): import("react").JSX.Element;

package/dist/Components/Documents/Button.js

@@ -5,7 +5,7 @@ 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 }) {
+export function Button({ variant = "secondary", size = "md", hoverTone, icon, iconEnd, loading = false, block = false, dot = 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] }));
+    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, dot && _jsx("span", { className: "nx-btn__dot", "data-tone": dot === true ? undefined : dot, "aria-hidden": "true" })] }));
 }

package/dist/Components/Documents/Menu.js

@@ -3,7 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { iconCheck, InlineIcon } from "nexus-icons";
 import { cloneElement, useId, useLayoutEffect, useRef, useState, } from "react";
 import { cx } from "../../Helpers/ClassHelpers.js";
-import { followAnchor, isPopoverOpen, placeAtPoint, placeUnderAnchor } from "../../Helpers/PopoverHelpers.js";
+import { followAnchor, isPopoverOpen, placeAtPoint, placeUnderAnchor, showPanel } from "../../Helpers/PopoverHelpers.js";
 export function isMenuItem(entry) {
     return "value" in entry;
 }
@@ -12,10 +12,16 @@ const ITEM_ROLE = {
     radio: "menuitemradio",
     checkbox: "menuitemcheckbox",
 };
-const ENABLED_ITEM = '.nx-menu__item:not([aria-disabled="true"])';
+// A row, and a control an app put in a heading (the admin's account card has the picture there). The arrow keys walk
+// both: Tab shuts a menu, so a control inside one is reachable no other way.
+const ENABLED_ITEM = '.nx-menu__item:not([aria-disabled="true"]), .nx-menu__heading [role="menuitem"]:not([aria-disabled="true"])';
 function enabledItems(panel) {
     return Array.from(panel.querySelectorAll(ENABLED_ITEM));
 }
+/** Where a menu opened from the keyboard starts: its first row, never a control in a heading above the rows. */
+function firstRowIndex(panel) {
+    return Math.max(0, enabledItems(panel).findIndex(item => item.classList.contains("nx-menu__item")));
+}
 /** Focuses the item at `index`, counting from the end when negative and wrapping past either end. */
 function focusItemAt(panel, index) {
     const items = enabledItems(panel);
@@ -87,7 +93,8 @@ export function MenuPanel({ id, items, onSelect, kind = "menu", size = "md", clo
         event.preventDefault();
     }
     // Focus follows the pointer, so the arrow keys carry on from the item under it. Only a pointer that moved counts:
-    // a menu opened from the keyboard under a resting pointer keeps the focus on its first item.
+    // a menu opened from the keyboard under a resting pointer keeps the focus on its first item. It never scrolls the
+    // list: an item half under the edge would pull the list up under the pointer, and the heading out of sight with it.
     const pointerRef = useRef({ x: 0, y: 0 });
     function onPointerMove(event) {
         const last = pointerRef.current;
@@ -96,30 +103,37 @@ export function MenuPanel({ id, items, onSelect, kind = "menu", size = "md", clo
         pointerRef.current = { x: event.clientX, y: event.clientY };
         const item = event.currentTarget;
         if (item.getAttribute("aria-disabled") !== "true" && document.activeElement !== item)
-            item.focus();
+            item.focus({ preventScroll: true });
+    }
+    // A control in a heading is chosen like a row, so it closes the menu like one.
+    function onClick(event) {
+        if (closeOnSelect && event.target.closest('.nx-menu__heading [role="menuitem"]'))
+            hide(event.currentTarget);
     }
     const role = ITEM_ROLE[kind];
     // When any item has an icon, every item keeps the icon column, so the labels line up.
     const hasIcons = items.some(entry => isMenuItem(entry) && entry.icon);
-    return (_jsx("div", { ref: ref, id: id, popover: "auto", role: "menu", tabIndex: -1, className: cx("nx-popover", "nx-menu", `nx-menu--${size}`, className), onToggle: onToggle, onKeyDown: onKeyDown, ...labelling, children: items.map((entry, index) => {
-            if (!isMenuItem(entry)) {
-                if ("separator" in entry)
-                    return _jsx("div", { role: "separator", className: "nx-menu__separator" }, index);
-                return (_jsx("div", { role: "presentation", className: "nx-menu__heading", children: entry.heading }, index));
-            }
-            const item = entry;
-            const content = (_jsxs(_Fragment, { children: [kind !== "menu" && _jsx("span", { className: "nx-menu__check", children: item.checked && _jsx(InlineIcon, { icon: iconCheck }) }), hasIcons && _jsx("span", { className: "nx-menu__icon", children: item.icon }), _jsxs("span", { className: "nx-menu__body", children: [_jsx("span", { className: "nx-menu__label", children: item.label }), item.description && _jsx("span", { className: "nx-menu__description", children: item.description })] }), item.shortcut && _jsx("kbd", { className: "nx-menu__shortcut", children: item.shortcut })] }));
-            const shared = {
-                role,
-                className: cx("nx-menu__item", item.tone === "danger" && "nx-menu__item--danger", item.checked && "nx-menu__item--checked"),
-                tabIndex: -1,
-                title: item.title,
-                "aria-disabled": item.disabled || undefined,
-                "aria-checked": kind === "menu" ? undefined : Boolean(item.checked),
-                onPointerMove,
-            };
-            return item.href && !item.disabled ? (_jsx("a", { ...shared, href: item.href, target: item.target, rel: item.target === "_blank" ? "noopener" : undefined, onClick: event => choose(item, event), children: content }, item.value)) : (_jsx("button", { ...shared, type: "button", onClick: event => choose(item, event), children: content }, item.value));
-        }) }));
+    return (_jsx("div", { ref: ref, id: id, popover: "auto", role: "menu", tabIndex: -1, className: cx("nx-popover", "nx-menu", `nx-menu--${size}`, className), onToggle: onToggle, onKeyDown: onKeyDown, onClick: onClick, ...labelling, children: _jsx("div", { role: "none", className: "nx-menu__list nx-popover__scroll", children: items.map((entry, index) => {
+                // Items are keyed by their value, so a separator keyed by its index alone collided with an item whose value
+                // was that number ("5" in a menu of projects). The prefix keeps the two apart.
+                if (!isMenuItem(entry)) {
+                    if ("separator" in entry)
+                        return _jsx("div", { role: "separator", className: "nx-menu__separator" }, `nx-at-${index}`);
+                    return (_jsx("div", { role: "presentation", className: "nx-menu__heading", children: entry.heading }, `nx-at-${index}`));
+                }
+                const item = entry;
+                const content = (_jsxs(_Fragment, { children: [kind !== "menu" && _jsx("span", { className: "nx-menu__check", children: item.checked && _jsx(InlineIcon, { icon: iconCheck }) }), hasIcons && _jsx("span", { className: "nx-menu__icon", children: item.icon }), _jsxs("span", { className: "nx-menu__body", children: [_jsx("span", { className: "nx-menu__label", children: item.label }), item.description && _jsx("span", { className: "nx-menu__description", children: item.description })] }), item.shortcut && _jsx("kbd", { className: "nx-menu__shortcut", children: item.shortcut })] }));
+                const shared = {
+                    role,
+                    className: cx("nx-menu__item", item.tone === "danger" && "nx-menu__item--danger", item.checked && "nx-menu__item--checked"),
+                    tabIndex: -1,
+                    title: item.title,
+                    "aria-disabled": item.disabled || undefined,
+                    "aria-checked": kind === "menu" ? undefined : Boolean(item.checked),
+                    onPointerMove,
+                };
+                return item.href && !item.disabled ? (_jsx("a", { ...shared, href: item.href, target: item.target, rel: item.target === "_blank" ? "noopener" : undefined, onClick: event => choose(item, event), children: content }, item.value)) : (_jsx("button", { ...shared, type: "button", onClick: event => choose(item, event), children: content }, item.value));
+            }) }) }));
 }
 /**
  * A dropdown menu: a button that opens a list of actions in a native popover under it (above it when there is no
@@ -149,12 +163,12 @@ export function Menu({ children, align = "start", "aria-label": ariaLabel, onOpe
         const panel = panelRef.current;
         if (!canShow(panel) || isPopoverOpen(panel))
             return;
-        panel.showPopover();
+        showPanel(panel);
         place();
         if (focus === "panel")
             panel.focus();
         else
-            focusItemAt(panel, focus === "first" ? 0 : -1);
+            focusItemAt(panel, focus === "first" ? firstRowIndex(panel) : -1);
     }
     // The panel is fixed, so it follows the button while the page scrolls or the window changes size.
     useLayoutEffect(() => {
@@ -212,14 +226,16 @@ export function ContextMenu({ children, "aria-label": ariaLabel = "Context menu"
     const panelId = useId();
     const panelRef = useRef(null);
     // When the last press happened: a contextmenu event right after one comes from the mouse or a long touch.
-    const pressedAtRef = useRef(0);
+    // When a pointer was last pressed. Never pressed has to be long ago, not zero: zero is 1.5 seconds after the page
+    // loaded, and a context menu opened from the keyboard in that moment would be placed as a pointer's.
+    const pressedAtRef = useRef(Number.NEGATIVE_INFINITY);
     function onContextMenu(event) {
         const panel = panelRef.current;
         if (disabled || !canShow(panel))
             return;
         event.preventDefault();
         hide(panel);
-        panel.showPopover();
+        showPanel(panel);
         const fromPointer = performance.now() - pressedAtRef.current < 1500;
         if (fromPointer) {
             placeAtPoint(panel, event.clientX, event.clientY);
@@ -229,7 +245,7 @@ export function ContextMenu({ children, "aria-label": ariaLabel = "Context menu"
             // From the keyboard (Shift+F10, the Menu key): browsers report the event at the element or at 0,0, so the
             // menu opens under the focused element like a dropdown (above it when there is no room), on its first item.
             placeUnderAnchor(panel, event.target.getBoundingClientRect());
-            focusItemAt(panel, 0);
+            focusItemAt(panel, firstRowIndex(panel));
         }
     }
     return (_jsxs("div", { className: "nx-context-target", onPointerDown: () => {

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

@@ -29,6 +29,8 @@ export interface SplitButtonProps<T extends string = string> {
     storageKey?: string;
     /** Picking an action in the menu also runs it. Default false: it only becomes the main button, as on GitHub. */
     runOnSelect?: boolean;
+    /** The main button never changes: the menu holds other ways to do it, each run when picked, with no check mark. */
+    fixed?: boolean;
     /** Default `primary`. */
     variant?: ButtonVariant;
     /** Default `md`. */
@@ -61,4 +63,4 @@ export interface SplitButtonProps<T extends string = string> {
  *   { value: "draft", label: "Create draft pull request", description: "Cannot be merged until marked ready" },
  * ]} />
  */
-export declare function SplitButton<T extends string>({ options, onAction, defaultValue, value, onValueChange, storageKey, runOnSelect, variant, size, loading, disabled, block, type, form, name, menuLabel, align, className, style, }: SplitButtonProps<T>): import("react").JSX.Element | null;
+export declare function SplitButton<T extends string>({ options, onAction, defaultValue, value, onValueChange, storageKey, runOnSelect, fixed, variant, size, loading, disabled, block, type, form, name, menuLabel, align, className, style, }: SplitButtonProps<T>): import("react").JSX.Element | null;