nexus-shared 4.0.0 → 4.1.0

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

@@ -0,0 +1,46 @@
+import { type ReactNode } from "react";
+import type { ChatId, ChatMessage, ChatSource, ChatSummary } from "../../Interfaces/ChatInterfaces.ts";
+import { type PopupSize, type PopupWindowState } from "../Layouts/Popup.tsx";
+export interface ChatPopupProps {
+    open: boolean;
+    /** Asked to close: its close button, Esc inside it, or its bar on the dock. */
+    onClose: () => void;
+    /** Where the lines come from: a thread's discussion (`mailDiscussionSource(mail.threadSource(id))`), a chat's source. */
+    source: ChatSource;
+    /** The conversation: keys its lines, so two popups on one conversation never share a store by accident. */
+    conversationId: ChatId;
+    /** Who is reading: their lines sit on the right. */
+    userId: ChatId;
+    /** The title bar: the chat's name, "Discussion: Cable stock". */
+    title: ReactNode;
+    /** Muted after the title, and under it on the dock's bar: the thread it belongs to, the people. */
+    description?: ReactNode;
+    /** Its icon. Default the chat's. */
+    icon?: ReactNode;
+    /** What an empty conversation says. Default "No messages yet." */
+    emptyMessage?: string;
+    /** The reply box's placeholder. Default "Write a message…". */
+    placeholder?: string;
+    /** Where the unsent text is kept. Default `chat-popup:<conversation>:<reader>`. */
+    draftKey?: string;
+    /** Width: `xs` 360, `sm` 440 (default), `md` 560. */
+    size?: Extract<PopupSize, "xs" | "sm" | "md">;
+    /** Height, a CSS length. Default `30rem`, never taller than the window. */
+    height?: string;
+    /** The minimise button. Default true. */
+    minimizable?: boolean;
+    /** The window state, when the page controls it. */
+    windowState?: PopupWindowState;
+    onWindowStateChange?: (state: PopupWindowState) => void;
+    /** Every time the counts change, a read included: a list's row follows it. */
+    onSummary?: (summary: ChatSummary) => void;
+    /** After a line of the reader's own is saved. */
+    onSent?: (message: ChatMessage) => void;
+    /** Lines per page. Default 30. */
+    pageSize?: number;
+    /** Milliseconds between checks for new lines. 0 turns it off. Default 15,000. */
+    pollInterval?: number;
+    className?: string;
+}
+/** A conversation in a docked, minimisable window. */
+export declare function ChatPopup({ open, onClose, source, conversationId, userId, title, description, icon, emptyMessage, placeholder, draftKey, size, height, minimizable, windowState, onWindowStateChange, onSummary, onSent, pageSize, pollInterval, className, }: ChatPopupProps): import("react").JSX.Element;

package/dist/Components/Chats/ChatPopup.js

@@ -0,0 +1,34 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconMessageCircle, InlineIcon } from "nexus-icons";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useChat } from "../../Helpers/ChatHooks.js";
+import { Popup } from "../Layouts/Popup.js";
+import { ChatComposer } from "./ChatComposer.js";
+import { ChatThread } from "./ChatThread.js";
+/** A conversation in a docked, minimisable window. */
+export function ChatPopup({ open, onClose, source, conversationId, userId, title, description, icon, emptyMessage, placeholder = "Write a message…", draftKey, size = "sm", height = "30rem", minimizable = true, windowState, onWindowStateChange, onSummary, onSent, pageSize, pollInterval, className, }) {
+    const [replyTo, setReplyTo] = useState(null);
+    // Its own place for the store: the thread drawn as mail behind it reads every line, the popup its discussion.
+    const scope = useMemo(() => ({ domain: "chat-popup", parentId: conversationId, userId }), [conversationId, userId]);
+    const { store, state } = useChat({ scope, conversationId, source, pageSize, pollInterval, enabled: open });
+    const latest = useRef({ onSummary, onSent });
+    latest.current = { onSummary, onSent };
+    useEffect(() => {
+        if (state.loaded)
+            latest.current.onSummary?.(state.summary);
+    }, [state.loaded, state.summary]);
+    // A line of the reader's own, saved: the page may count it (a Discuss button's number).
+    const known = useRef(new Set());
+    useEffect(() => {
+        for (const message of state.messages) {
+            const key = String(message.clientId ?? message.id);
+            if (message.status !== "sent" || known.current.has(key))
+                continue;
+            known.current.add(key);
+            if (message.clientId && String(message.authorId) === String(userId))
+                latest.current.onSent?.(message);
+        }
+    }, [state.messages, userId]);
+    return (_jsx(Popup, { open: open, onClose: onClose, title: title, description: description, icon: icon ?? _jsx(InlineIcon, { icon: iconMessageCircle }), size: size, height: height, docked: true, minimizable: minimizable, movable: false, reopen: "restore", flush: true, windowState: windowState, onWindowStateChange: onWindowStateChange, className: className, children: _jsxs("div", { className: "nx-chat-panel nx-chat-popup", children: [_jsx("div", { className: "nx-chat-panel__body", children: _jsx(ChatThread, { store: store, state: state, userId: userId, onReply: setReplyTo, emptyMessage: emptyMessage }) }), _jsx(ChatComposer, { store: store, state: state, draftKey: draftKey ?? `chat-popup:${String(conversationId)}:${String(userId)}`, placeholder: placeholder, replyTo: replyTo, onCancelReply: () => setReplyTo(null), autoFocus: true })] }) }));
+}

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

@@ -1,3 +1,4 @@
+import { type ReactNode } from "react";
 import { type ChatTimeOptions } from "../../Helpers/ChatHelpers.ts";
 import type { ChatSnapshot, ChatStore } from "../../Helpers/ChatStore.ts";
 import type { ChatId, ChatMessage } from "../../Interfaces/ChatInterfaces.ts";
@@ -16,7 +17,14 @@ export interface ChatThreadProps {
     marksRead?: boolean;
     /** Shown when there is not a single message. */
     emptyMessage?: string;
+    /**
+     * What the conversation opens with, above its first message and scrolling with it - a mail thread's subject, people
+     * and record - so a tall head is read in the thread's one scroll, never in a box of its own. With one, the thread opens
+     * at its top, or at the first unread line when that would be out of view, and older pages load from the "Earlier
+     * messages" button only, so the lead stays where the reader scrolled it.
+     */
+    lead?: ReactNode;
     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;
+export declare function ChatThread({ store, state, userId, time, replies, onReply, marksRead, emptyMessage, lead, className }: ChatThreadProps): import("react").JSX.Element;

package/dist/Components/Chats/ChatThread.js

@@ -7,7 +7,7 @@ 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";
+import { ChatAvatar, ChatDayDivider, ChatEmpty, ChatEventNote, 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
@@ -21,7 +21,7 @@ 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 }) {
+export function ChatThread({ store, state, userId, time, replies = true, onReply, marksRead = true, emptyMessage, lead, className }) {
     const preferences = useDatePreferences();
     const zone = useBrowserTimeZone();
     const settings = useMemo(() => ({ ...preferences, ...(zone && { timeZone: zone }), ...time }), [preferences, zone, time]);
@@ -32,6 +32,8 @@ export function ChatThread({ store, state, userId, time, replies = true, onReply
     const anchor = useRef(null);
     const lastKey = useRef(null);
     const count = useRef(0);
+    // With a lead, the first messages place the thread once: at its top, or at the first unread line.
+    const placed = useRef(false);
     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) => {
@@ -41,11 +43,44 @@ export function ChatThread({ store, state, userId, time, replies = true, onReply
         // Smooth only when the visitor and the system both allow motion; otherwise it jumps.
         list.scrollTo({ top: list.scrollHeight, behavior: smooth && smoothScrollAllowed() ? "smooth" : "auto" });
     }, []);
+    /** Whether the newest message is on screen: the reader is at the bottom. */
+    const measureBottom = useCallback(() => {
+        const list = listRef.current;
+        if (!list)
+            return;
+        const bottom = list.scrollHeight - list.scrollTop - list.clientHeight <= EDGE;
+        setAtBottom(bottom);
+        if (bottom)
+            setMissed(0);
+    }, []);
+    /**
+     * A thread with a lead opens at its top - the lead and the first messages - unless its first unread line would be out of
+     * view there; then that line opens at the top. The reader is at the bottom only if the newest message shows.
+     */
+    const placeFirst = useCallback(() => {
+        const list = listRef.current;
+        if (!list)
+            return;
+        const unread = list.querySelector(".nx-chat-unread-line");
+        const top = list.getBoundingClientRect().top;
+        const within = (element) => element.getBoundingClientRect().bottom - top + list.scrollTop;
+        const run = unread?.nextElementSibling instanceof HTMLElement ? unread.nextElementSibling : null;
+        list.scrollTop = unread && run && within(run) > list.clientHeight ? Math.max(0, within(unread) - unread.offsetHeight - 8) : 0;
+        measureBottom();
+    }, [measureBottom]);
     // 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 (lead && !placed.current && state.messages.length > 0 && !state.loading) {
+            placed.current = true;
+            count.current = state.messages.length;
+            const newest = state.messages[state.messages.length - 1];
+            lastKey.current = newest ? chatMessageKey(newest) : null;
+            placeFirst();
+            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);
@@ -67,7 +102,18 @@ export function ChatThread({ store, state, userId, time, replies = true, onReply
             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]);
+    }, [state.messages, state.loading, atBottom, userId, scrollToEnd, lead, placeFirst]);
+    // A lead that grows (a record's card landing, its details unfolded) moves the newest message down: whether the reader is
+    // at the bottom is worked out again, so a line that arrives next does not pull the lead out of view.
+    const leadRef = useRef(null);
+    useLayoutEffect(() => {
+        const element = leadRef.current;
+        if (!element)
+            return;
+        const observer = new ResizeObserver(() => measureBottom());
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [lead !== undefined, measureBottom]); // eslint-disable-line react-hooks/exhaustive-deps
     // The conversation counts as read once its newest message has been on screen.
     useEffect(() => {
         if (!marksRead || !atBottom || state.loading || state.summary.unreadCount === 0)
@@ -82,13 +128,15 @@ export function ChatThread({ store, state, userId, time, replies = true, onReply
         setAtBottom(bottom);
         if (bottom)
             setMissed(0);
-        if (list.scrollTop <= TOP_EDGE && state.hasMore && !state.loadingOlder) {
+        // Under a lead the top is the lead's: earlier pages come from their button, so the lead is not pushed away.
+        if (!lead && list.scrollTop <= TOP_EDGE && state.hasMore && !state.loadingOlder) {
             anchor.current = { height: list.scrollHeight, top: list.scrollTop };
             void store.loadOlder();
         }
-    }, [state.hasMore, state.loadingOlder, store]);
+    }, [state.hasMore, state.loadingOlder, store, lead]);
     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) })] }))] }));
+    const lines = (_jsxs(_Fragment, { 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 || run.notification) && "nx-chat-run--system"), children: run.system ? (run.messages.map(message => _jsx(ChatSystemNote, { message: message, time: settings }, chatMessageKey(message)))) : run.notification ? (run.messages.map(message => _jsx(ChatEventNote, { 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)))] }));
+    return (_jsxs("div", { className: cx("nx-chat-thread", className), children: [lead ? (_jsxs("div", { className: "nx-chat-thread__list", ref: listRef, onScroll: onScroll, tabIndex: 0, role: "region", "aria-label": "Thread", children: [_jsx("div", { ref: leadRef, className: "nx-chat-thread__lead", children: lead }), _jsx("div", { className: "nx-chat-thread__log", role: "log", "aria-live": "polite", "aria-relevant": "additions", children: lines })] })) : (_jsx("div", { className: "nx-chat-thread__list", ref: listRef, onScroll: onScroll, role: "log", "aria-live": "polite", "aria-relevant": "additions", tabIndex: 0, children: lines })), !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 }) {

package/dist/Components/Dashboards/DashboardBoard.d.ts

@@ -0,0 +1,62 @@
+import { type ReactNode } from "react";
+import type { DashboardLayout, DashboardLayoutItem, DashboardSaveResult, DashboardVersion, WidgetDefinition, WidgetModuleLoader } from "../../Interfaces/DashboardInterfaces.ts";
+export interface DashboardBoardProps {
+    /** The place this board is: `home`, or a module's dashboard (`message`, `staffing`). */
+    place: string;
+    /** The module whose `own` widgets may go here. Default: `place` (the Home has no module of that name, so none). */
+    placeModule?: string | null;
+    /** Every widget the app declares; the board draws those allowed here that the person may see. */
+    widgets: readonly WidgetDefinition<any>[];
+    /** Whether the person may see a widget now: the company holds its module, the person its key. Default: every widget. */
+    canSee?: (widget: WidgetDefinition<any>) => boolean;
+    /** The person's saved layout for this place, or `null` when they saved none (the default is drawn). */
+    layout?: DashboardLayout | null;
+    /** The saved layout's version, given back with a save so a stale one is refused. */
+    version?: DashboardVersion;
+    /** The layout drawn when the person has none, and what Reset goes back to: the company's for this place, else the code's. */
+    defaultLayout: DashboardLayout;
+    /**
+     * Saves the person's layout (the whole of it: widgets they cannot see now keep their places), with the version it was
+     * edited from. Answer `stale` with the saved layout when the version is old (the server's 409). Without it the board's
+     * edits last as long as the page.
+     */
+    onSave?: (layout: DashboardLayoutItem[], version: DashboardVersion) => Promise<DashboardSaveResult>;
+    /** Forgets the person's layout: Reset then Save. Without it, Reset saves the default as theirs through `onSave`. */
+    onReset?: (version: DashboardVersion) => Promise<DashboardSaveResult>;
+    /** Shows Customise. Default true. */
+    canCustomise?: boolean;
+    /** Offers "Save as the company's default" beside Save, with `onSaveCompanyDefault`. */
+    canSaveCompanyDefault?: boolean;
+    onSaveCompanyDefault?: (layout: DashboardLayoutItem[]) => Promise<DashboardSaveResult | void>;
+    /** The one call per module per draw, for widgets with `batch`. */
+    loadModule?: WidgetModuleLoader;
+    /** Data read with the page (on the server), by widget code: drawn at once, kept as if asked now. */
+    initialData?: Readonly<Record<string, unknown>>;
+    /** A module's name in the Add list. Default: the module's code with a capital. */
+    moduleLabel?: (module: string) => ReactNode;
+    /** Moves a link inside the board through the app's router (`router.push`). Default: the browser follows it. */
+    onNavigate?: (href: string) => void;
+    /** The board's heading. */
+    title?: ReactNode;
+    /** More controls in the board's bar, before Refresh and Customise. */
+    actions?: ReactNode;
+    /** How near the screen a widget starts to load, as a margin. Default `200px`. */
+    loadMargin?: string;
+    className?: string;
+}
+/**
+ * A dashboard of widgets on a 12-column grid, for one place (the Home, a module's dashboard). Each widget takes a size
+ * preset (S 3×1, M 6×2, L 6×4, W 12×2, T 12×4), the grid fills every gap (`grid-auto-flow: dense`), and a layout is
+ * an ordered list of `{ code, size }`; on a phone every widget is the full width, in order. Widgets load only when near
+ * the screen, each module asked once per draw (`loadModule`), kept for the page's life or their `refresh` seconds.
+ *
+ * Customise turns on edit mode: move by dragging a widget's handle or with the arrow keys on a focused widget, Enter or
+ * Space for its size menu (only its sizes), Delete to remove it; Add widget opens a drawer of the widgets this place
+ * may hold, by module; Save, Cancel, Reset to default. A save another window beat (`stale`) shows the layout saved
+ * there and says so.
+ *
+ * @example
+ * <DashboardBoard place="home" widgets={WIDGETS} canSee={canSee} layout={saved?.items} version={saved?.version}
+ *   defaultLayout={HOME_DEFAULT} loadModule={loadWidgets} onSave={saveLayout} onReset={resetLayout} />
+ */
+export declare function DashboardBoard({ place, placeModule, widgets, canSee, layout, version, defaultLayout, onSave, onReset, canCustomise, canSaveCompanyDefault, onSaveCompanyDefault, loadModule, initialData, moduleLabel, onNavigate, title, actions, loadMargin, className, }: DashboardBoardProps): import("react").JSX.Element;