nexus-shared 4.0.0 → 4.1.0

package/dist/Components/Messages/MailThread.js

@@ -0,0 +1,185 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { iconArchive, InlineIcon } from "nexus-icons";
+import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { flushSync } from "react-dom";
+import { chatDomainLabel } from "../../Helpers/ChatBackend.js";
+import { chatDayLabel, chatLocalDate, chatTimeLabel, sameChatId } from "../../Helpers/ChatHelpers.js";
+import { useChat } from "../../Helpers/ChatHooks.js";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { useBrowserTimeZone, useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { formatDateTime } from "../../Helpers/DateTimeHelpers.js";
+import { mailBccNote, mailPeopleLine, MAIL_ROLE_LABELS } from "../../Helpers/MessageHelpers.js";
+import { ChatComposer } from "../Chats/ChatComposer.js";
+import { ChatFailure } from "../Chats/ChatParts.js";
+import { ChatThread } from "../Chats/ChatThread.js";
+import { DomainCard, DomainLine } from "../Domains/DomainCard.js";
+/** Under this width (px) a record's card opens folded to its title and figures, the details a press away. */
+const NARROW_THREAD = 480;
+/** The words of a thread the reader may not open: a stranger learns nothing more. */
+const REFUSED = "This message is not available to you.";
+const errorStatus = (error) => {
+    const status = error?.status;
+    return typeof status === "number" ? status : undefined;
+};
+const isAbort = (error) => error?.name === "AbortError";
+/** A mail thread: the head with its people and record, the lines, and the reply box. */
+export function MailThread({ source, threadId, userId, head: givenHead, renderDomain, actions, headingLevel = 2, peopleShown = 3, onChanged, onHead, onSummary, pageSize, pollInterval, height, className, }) {
+    const [head, setHead] = useState(givenHead && sameChatId(givenHead.id, threadId) ? givenHead : null);
+    const [headState, setHeadState] = useState({ status: head ? "ready" : "loading" });
+    const [attempt, setAttempt] = useState(0);
+    const [revision, setRevision] = useState(0);
+    const [replyTo, setReplyTo] = useState(null);
+    const latest = useRef({ onChanged, onHead, onSummary, head });
+    // How wide the thread is, followed as it changes. A window still laying out reads 0 (its dialog is not open yet), so the
+    // record's card waits for a real width before it is drawn - the first one drawn before the browser paints - and then
+    // folds or unfolds with the width, until the reader folds or unfolds it themselves.
+    const frame = useRef(null);
+    const [narrow, setNarrow] = useState(null);
+    const [folded, setFolded] = useState(null);
+    useLayoutEffect(() => {
+        const element = frame.current;
+        if (!element)
+            return;
+        let known = false;
+        const read = () => {
+            const width = element.clientWidth;
+            if (width <= 0)
+                return;
+            const next = width < NARROW_THREAD;
+            if (known)
+                setNarrow(next);
+            else
+                flushSync(() => setNarrow(next));
+            known = true;
+        };
+        const width = element.clientWidth;
+        if (width > 0) {
+            setNarrow(width < NARROW_THREAD);
+            known = true;
+        }
+        const observer = new ResizeObserver(read);
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, []);
+    latest.current = { onChanged, onHead, onSummary, head };
+    const chatSource = useMemo(() => source.threadSource(threadId), [source, threadId]);
+    // A mail thread is not a record's place: the scope only keys the store, and the conversation id keeps the page's
+    // count cache (the chat icons' counts) out of it.
+    const scope = useMemo(() => ({ domain: "mail", parentId: threadId, userId }), [threadId, userId]);
+    const refused = headState.status === "refused";
+    const { store, state } = useChat({ scope, conversationId: threadId, source: chatSource, pageSize, pollInterval, enabled: !refused });
+    const take = useCallback((next) => {
+        setHead(next);
+        setHeadState({ status: "ready" });
+        latest.current.onHead?.(next);
+    }, []);
+    // The head, read whenever the thread changes, and again on Retry.
+    useEffect(() => {
+        const controller = new AbortController();
+        if (!latest.current.head || !sameChatId(latest.current.head.id, threadId)) {
+            setHead(null);
+            setHeadState({ status: "loading" });
+        }
+        source.thread(threadId, controller.signal).then(take, error => {
+            if (controller.signal.aborted || isAbort(error))
+                return;
+            const status = errorStatus(error);
+            if (status === 403 || status === 404)
+                setHeadState({ status: "refused", message: REFUSED });
+            else
+                setHeadState({ status: "failed", message: error instanceof Error && error.message ? error.message : "The message could not be loaded." });
+        });
+        return () => controller.abort();
+    }, [source, threadId, attempt, take]);
+    // Read again quietly when the people may have changed: the head on screen stays until the new one lands.
+    const refreshHead = useCallback(() => {
+        source.thread(threadId).then(take, () => {
+            // A refresh that failed leaves the head as it was; the next line tries again.
+        });
+    }, [source, threadId, take]);
+    // What arrived since the last look: someone else's lines read the head again and tell the page; a reply of this
+    // reader's while copied unseen reads it again too, since it made them a Cc.
+    const primed = useRef(false);
+    const newest = useRef(null);
+    useEffect(() => {
+        // Another thread starts its own count: its first page is what it holds, not what arrived.
+        primed.current = false;
+        newest.current = null;
+    }, [threadId]);
+    useEffect(() => {
+        if (!state.loaded)
+            return;
+        const saved = state.messages.filter(message => message.status !== "sending" && message.status !== "failed");
+        const last = saved[saved.length - 1];
+        const key = last ? String(last.id) : null;
+        const before = newest.current;
+        newest.current = key;
+        if (!primed.current) {
+            primed.current = true;
+            return;
+        }
+        if (key === before)
+            return;
+        const from = before === null ? -1 : saved.findIndex(message => String(message.id) === before);
+        const fresh = saved.slice(from + 1);
+        const theirs = fresh.filter(message => !sameChatId(message.authorId, userId));
+        const mineAsBcc = latest.current.head?.myRole === "bcc" && fresh.some(message => sameChatId(message.authorId, userId));
+        if (theirs.length > 0 || mineAsBcc)
+            refreshHead();
+        if (theirs.length === 0)
+            return;
+        const notification = theirs.some(message => message.kind === "notification");
+        if (notification)
+            setRevision(count => count + 1);
+        latest.current.onChanged?.({ reason: notification ? "notification" : "reply", messages: theirs });
+    }, [state.loaded, state.messages, userId, refreshHead]);
+    useEffect(() => {
+        latest.current.onSummary?.(state.summary);
+    }, [state.summary]);
+    const preferences = useDatePreferences();
+    const zone = useBrowserTimeZone();
+    const time = useMemo(() => ({ ...preferences, ...(zone && { timeZone: zone }) }), [preferences, zone]);
+    const style = height === undefined ? undefined : { "--nx-chat-height": typeof height === "number" ? `${height}px` : height };
+    const Heading = `h${headingLevel}`;
+    const note = mailBccNote(head);
+    if (refused) {
+        return (_jsx("div", { className: cx("nx-chat-panel", "nx-mail", className), style: style, children: _jsx("div", { className: "nx-mail__refused", role: "alert", children: _jsx("p", { children: headState.message }) }) }));
+    }
+    // The head opens the thread's one scroll (its lead): a tall record's card is read by scrolling the thread, not in a box.
+    const headBand = (_jsx("header", { className: "nx-mail__head", "aria-busy": headState.status === "loading" || undefined, children: headState.status === "failed" && !head ? (_jsx(ChatFailure, { message: headState.message, onRetry: () => setAttempt(count => count + 1) })) : (_jsxs(_Fragment, { children: [_jsxs("div", { className: "nx-mail__title", children: [_jsx(Heading, { className: "nx-mail__subject", tabIndex: -1, "data-nx-focus": "", children: head ? head.subject : _jsx("span", { className: "nx-table__bone nx-record__bone nx-mail__bone", style: { width: "16rem" } }) }), head?.archived && (_jsxs("span", { className: "nx-table__tag nx-table__tag--plain nx-mail__archived", children: [_jsx(InlineIcon, { icon: iconArchive }), " Archived"] })), head && _jsx(MailTime, { value: head.createdTime, time: time }), actions && _jsx("span", { className: "nx-mail__actions", children: actions })] }), _jsx("dl", { className: "nx-mail__people", children: head ? (_jsxs(_Fragment, { children: [_jsx(MailPeopleRow, { role: "from", people: [head.from], userId: userId, shown: peopleShown }), _jsx(MailPeopleRow, { role: "to", people: head.to, userId: userId, shown: peopleShown }), head.cc.length > 0 && _jsx(MailPeopleRow, { role: "cc", people: head.cc, userId: userId, shown: peopleShown }), head.bcc.length > 0 && _jsx(MailPeopleRow, { role: "bcc", people: head.bcc, userId: userId, shown: peopleShown })] })) : (_jsxs(_Fragment, { children: [_jsx(MailBoneRow, { label: MAIL_ROLE_LABELS.from, width: "9rem" }), _jsx(MailBoneRow, { label: MAIL_ROLE_LABELS.to, width: "13rem" })] })) }), head?.domain &&
+                    (renderDomain ? (renderDomain(head.domain, { head, revision })) : (narrow !== null && (_jsx(DomainCard, { domain: head.domain.domainType, id: head.domain.id, label: head.domain.label, revision: revision, viewer: userId, headingLevel: (headingLevel + 1), collapsed: folded ?? narrow, onCollapsedChange: setFolded })))), headState.status === "failed" && head && _jsx(ChatFailure, { message: headState.message, onRetry: () => setAttempt(count => count + 1) })] })) }));
+    return (_jsxs("div", { ref: frame, className: cx("nx-chat-panel", "nx-mail", className), style: style, children: [_jsx("div", { className: "nx-chat-panel__body", children: _jsx(ChatThread, { store: store, state: state, userId: userId, onReply: setReplyTo, emptyMessage: "Nothing in this thread yet.", lead: headBand }) }), _jsx(ChatComposer, { store: store, state: state, draftKey: `mail:${String(threadId)}:${String(userId)}`, placeholder: "Write a reply\u2026", replyTo: replyTo, onCancelReply: () => setReplyTo(null), notice: note, readOnlyMessage: "This thread is closed: it can be read, not answered." })] }));
+}
+/** When the thread was started: the day and the time in the reader's settings, the full moment on hover. */
+function MailTime({ value, time }) {
+    if (!value)
+        return null;
+    const day = chatLocalDate(value, time.timeZone);
+    return (_jsx("time", { className: "nx-mail__time", dateTime: value, title: formatDateTime(value, time), children: day ? `${chatDayLabel(day, time)} · ${chatTimeLabel(value, time)}` : chatTimeLabel(value, time) }));
+}
+/** A line of the head held while it loads: the role's word and a bone where the names go. */
+function MailBoneRow({ label, width }) {
+    return (_jsxs("div", { className: "nx-mail__row", children: [_jsx("dt", { children: label }), _jsx("dd", { children: _jsx("span", { className: "nx-table__bone nx-record__bone nx-mail__bone", style: { width } }) })] }));
+}
+/** One line of the head: a role and its people, folded to a few names and "+2" until it is opened. */
+function MailPeopleRow({ role, people, userId, shown }) {
+    return (_jsxs("div", { className: "nx-mail__row", "data-role": role, children: [_jsx("dt", { children: MAIL_ROLE_LABELS[role] }), _jsx("dd", { children: _jsx(MailPeople, { people: people, userId: userId, shown: shown }) })] }));
+}
+/**
+ * A list of people on one line, folded to its first names and a "+2" button that opens the rest in place: a thread sent
+ * to fifty people keeps a head of a few lines. Someone who has left keeps their name, muted.
+ */
+export function MailPeople({ people, userId, shown = 3, empty = "Nobody" }) {
+    const [open, setOpen] = useState(false);
+    const listId = useId();
+    const line = mailPeopleLine(people, shown);
+    if (people.length === 0)
+        return _jsx("span", { className: "nx-mail__nobody", children: empty });
+    const visible = open ? people : line.shown;
+    return (_jsxs("span", { id: listId, children: [visible.map((person, index) => (_jsxs("span", { className: cx("nx-mail__name", person.isActive === false && "nx-mail__name--inactive"), title: person.isActive === false ? `${person.name} has left` : undefined, children: [person.name, userId !== undefined && sameChatId(person.id, userId) && _jsx("span", { className: "nx-mail__you", children: "you" }), index < visible.length - 1 && ","] }, `${String(person.id)}-${index}`))), line.more > 0 && (_jsx("button", { type: "button", className: "nx-mail__more", "aria-expanded": open, "aria-controls": listId, "aria-label": open ? "Show fewer" : `Show ${line.more} more: ${people.slice(line.shown.length).map(person => person.name).join(", ")}`, onClick: () => setOpen(was => !was), children: open ? "Fewer" : `+${line.more}` }))] }));
+}
+/** The record a thread is about, as its words alone: the kind's name as the app gave it, and the record's own words. */
+export function MailDomainLine({ domain }) {
+    return _jsx(DomainLine, { kind: chatDomainLabel(domain.domainType), label: domain.label });
+}

package/dist/Components/Messages/MessageBell.d.ts

@@ -0,0 +1,41 @@
+import { type IconNode } from "nexus-icons";
+import { type ChatTimeOptions } from "../../Helpers/ChatHelpers.ts";
+import { type MessageUnreadSnapshot } from "../../Helpers/MessageUnread.ts";
+import type { MailInboxRow, MessageSource } from "../../Interfaces/MailInterfaces.ts";
+export interface UseMessageUnreadOptions {
+    /** Milliseconds between reads while the page is in front. Default a minute. */
+    interval?: number;
+    /** Joins the page's reads. False shows what is known without reading. Default true. */
+    enabled?: boolean;
+}
+/** What `useMessageUnread` gives: the count and the newest, `refresh()`, and whether this one speaks for the page. */
+export interface MessageUnreadHandle extends MessageUnreadSnapshot {
+    refresh: () => void;
+    /** The first drawn of the page's bells on this source: the one with the live region. */
+    speaks: boolean;
+}
+/** The page's unread count for a mailbox, shared by every component that asks: one read however many there are. */
+export declare function useMessageUnread(source: Pick<MessageSource, "unread">, { interval, enabled }?: UseMessageUnreadOptions): MessageUnreadHandle;
+export interface MessageBellProps {
+    /** The mailbox: `apiMessageSource()`, or anything with `unread()`. One source object per page shares one poller. */
+    source: Pick<MessageSource, "unread">;
+    /** The inbox. A thread opens at `href?thread=<id>`. */
+    href: string;
+    /** A thread's address, instead of `href?thread=<id>`. */
+    threadHref?: (row: MailInboxRow) => string;
+    /** What the button is called, before its count. Default "Messages". */
+    label?: string;
+    /** Milliseconds between reads while the page is in front. Default a minute. */
+    interval?: number;
+    /** Default `md`, the bar's size. */
+    size?: "sm" | "md";
+    /** Default a bell. */
+    icon?: IconNode;
+    /** The largest count the badge writes before "99+". Default 99. */
+    maxBadge?: number;
+    /** The reader's date settings, for "14 min ago". Default their own. */
+    time?: ChatTimeOptions;
+    className?: string;
+}
+/** The unread count on a top bar's button, and the newest unread a click away. See the notes at the top of this file. */
+export declare function MessageBell({ source, href, threadHref, label, interval, size, icon, maxBadge, time, className }: MessageBellProps): import("react").JSX.Element;

package/dist/Components/Messages/MessageBell.js

@@ -0,0 +1,76 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconBell, InlineIcon } from "nexus-icons";
+import { useEffect, useMemo, useRef, useSyncExternalStore } from "react";
+import { chatTimeAgo } from "../../Helpers/ChatHelpers.js";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { useBrowserTimeZone, useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { MESSAGE_UNREAD_INTERVAL, mailThreadHref, mailUnreadBadge, mailUnreadWords, messageUnreadPoller, } from "../../Helpers/MessageUnread.js";
+import { Button } from "../Documents/Button.js";
+import { Menu } from "../Documents/Menu.js";
+/** The page's unread count for a mailbox, shared by every component that asks: one read however many there are. */
+export function useMessageUnread(source, { interval = MESSAGE_UNREAD_INTERVAL, enabled = true } = {}) {
+    const poller = messageUnreadPoller(source);
+    const snapshot = useSyncExternalStore(poller.subscribe, poller.getSnapshot, poller.getSnapshot);
+    const member = useRef(null);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const joined = poller.join(interval);
+        member.current = joined;
+        return () => {
+            joined.leave();
+            if (member.current === joined)
+                member.current = null;
+        };
+    }, [poller, interval, enabled]);
+    return { ...snapshot, refresh: () => poller.refresh(), speaks: member.current?.speaks() ?? false };
+}
+/** What the button says it holds: its label and the count in words, or why there is none. */
+function describe(label, unread, max) {
+    if (unread.status === "idle" || unread.status === "loading")
+        return `${label}: not checked yet`;
+    if (unread.status === "failed")
+        return `${label}: could not be checked`;
+    return `${label}: ${mailUnreadWords(unread.count, max).toLowerCase()}`;
+}
+/** The unread count on a top bar's button, and the newest unread a click away. See the notes at the top of this file. */
+export function MessageBell({ source, href, threadHref, label = "Messages", interval, size = "md", icon = iconBell, maxBadge = 99, time, className }) {
+    const unread = useMessageUnread(source, { interval });
+    const preferences = useDatePreferences();
+    const zone = useBrowserTimeZone();
+    const settings = useMemo(() => ({ ...preferences, ...(zone && { timeZone: zone }), ...time }), [preferences, zone, time]);
+    const words = describe(label, unread, maxBadge);
+    const badge = unread.status === "ready" ? mailUnreadBadge(unread.count, maxBadge) : "";
+    const shown = unread.newest.reduce((total, row) => total + Math.max(0, row.unreadCount), 0);
+    const heading = unread.status === "idle" || unread.status === "loading"
+        ? "Checking for messages"
+        : unread.status === "failed"
+            ? "Could not check for messages"
+            : unread.count > 0
+                ? "Unread"
+                : "Nothing unread";
+    const items = [
+        { heading },
+        ...unread.newest.map(row => ({
+            value: `thread:${String(row.id)}`,
+            label: row.subject,
+            // Who wrote the newest line and when: the line that made it unread (the thread's sender wrote the first).
+            description: [row.lastAuthorName || row.fromName, row.domainLabel, chatTimeAgo(row.lastMessageTime, settings)].filter(Boolean).join(" · "),
+            href: threadHref ? threadHref(row) : mailThreadHref(href, row.id),
+            title: row.subject,
+        })),
+        ...(unread.failed ? [{ value: "retry", label: "Try again", description: unread.status === "ready" ? "The count shown is from before." : undefined }] : []),
+        { separator: true },
+        {
+            value: "inbox",
+            label: "Open inbox",
+            // What the list leaves out: the threads past the newest eight.
+            description: unread.count > shown && shown > 0 ? `${mailUnreadWords(unread.count, maxBadge)} in all` : undefined,
+            href,
+        },
+    ];
+    // Said once when the count goes up, by the first bell of the page; an invisible space tells two same words apart.
+    const spoken = unread.spoken ? `${unread.spoken.text}${unread.spoken.seq % 2 ? String.fromCharCode(160) : ""}` : "";
+    return (_jsxs(_Fragment, { children: [_jsx(Menu, { items: items, align: "end", "aria-label": unread.status === "ready" ? `${label}: ${mailUnreadWords(unread.count, maxBadge).toLowerCase()}` : label, className: "nx-message-bell__menu", onOpenChange: open => open && unread.refresh(), onSelect: value => value === "retry" && unread.refresh(), children: _jsx(Button, { variant: "ghost", size: size, className: cx("nx-message-bell", className), icon: _jsx(InlineIcon, { icon: icon }), badge: badge, "aria-label": words, title: words }) }), unread.speaks && (_jsx("span", { className: "nx-visually-hidden", "aria-live": "polite", children: spoken }))] }));
+}

package/dist/Components/Viewers/DataTable.js

@@ -10,7 +10,7 @@ import { fitColumnWidth, headLeafCells, startColumnDrag, startColumnResize } fro
 import { exportTableCsv, printTable } from "../../Helpers/TableExport.js";
 import { asFilterInput, filterNames, filterRequest } from "../../Helpers/TableFilters.js";
 import { joinKeys, joinSourceName, tableJoins } from "../../Helpers/TableJoins.js";
-import { canPinColumn, columnAlign, columnValue, cssLength, DEFAULT_MAX_SELECTION, DEFAULT_PAGE_SIZE, DEFAULT_PAGE_SIZES, formatCellText, headBands, MIN_COLUMN_WIDTH, orderColumns, releasedPins, TABLE_ACTIONS_COLUMN, TABLE_INDEX_COLUMN, viewColumns, } from "../../Helpers/TableHelpers.js";
+import { canPinColumn, columnAlign, columnValue, cssLength, DEFAULT_MAX_SELECTION, DEFAULT_PAGE_SIZE, DEFAULT_PAGE_SIZES, formatCellText, headBands, leadColumns, namingColumn, MIN_COLUMN_WIDTH, orderColumns, releasedPins, TABLE_ACTIONS_COLUMN, TABLE_INDEX_COLUMN, viewColumns, } from "../../Helpers/TableHelpers.js";
 import { TableStore } from "../../Helpers/TableStore.js";
 import { readUserPreferences, useNumberLocale, useUserPreferences } from "../../Helpers/UserPreferences.js";
 import { Button } from "../Documents/Button.js";
@@ -106,7 +106,7 @@ const sameNumbers = (a, b) => {
  * />
  */
 export function DataTable(props) {
-    const { columns, rows: givenRows, load, loadKey, rowKey = "id", rowLabel, table: givenTable, searchable = true, searchPlaceholder = "Search…", caption, toolbar, actions, add, columnsMenu = true, selectable = false, maxSelection = DEFAULT_MAX_SELECTION, onSelectionChange, massActions, selectBy, rowActions, onRowOpen, openOnClick: ownOpenOnClick, onPick, sections: ownSections, rowMarks, pinnedRows, pinnedLoading = false, pinnedLabel = "Pinned", pinnedMax, onReload, reorderable = true, resizable = true, pinnable = true, moreActions, exportable = true, printable = true, exportName, onImport, excel, pageSize: ownPageSize, pageSizes = DEFAULT_PAGE_SIZES, defaultSort = null, stateKey, currency, emptyMessage = "No records yet.", emptyAction, maxHeight, fill = false, size = "md", id, className, style, ref, } = props;
+    const { columns: givenColumns, rows: givenRows, load, loadKey, rowKey = "id", rowLabel, table: givenTable, searchable = true, searchPlaceholder = "Search…", caption, toolbar, actions, add, columnsMenu = true, selectable = false, maxSelection = DEFAULT_MAX_SELECTION, onSelectionChange, massActions, selectBy, rowActions, onRowOpen, openOnClick: ownOpenOnClick, onPick, sections: ownSections, rowMarks, rowStrong, pinnedRows, pinnedLoading = false, pinnedLabel = "Pinned", pinnedMax, onReload, reorderable = true, resizable = true, pinnable = true, moreActions, exportable = true, printable = true, exportName, onImport, excel, pageSize: ownPageSize, pageSizes = DEFAULT_PAGE_SIZES, defaultSort = null, stateKey, currency, emptyMessage = "No records yet.", emptyAction, maxHeight, fill = false, size = "md", id, className, style, ref, } = props;
     const paging = givenRows ? "client" : (props.paging ?? "client");
     // A server's pages cannot all be shown at once: such a table keeps its paging in the footer instead.
     const pager = props.pager === "none" && paging === "server" ? "footer" : (props.pager ?? "bar");
@@ -131,6 +131,8 @@ export function DataTable(props) {
     const table = givenTable ?? own;
     // Prepared once for the store and the panel: the same params without what would make them filter on their own.
     const filterInputs = useMemo(() => props.filterInputs?.map(asFilterInput), [props.filterInputs]);
+    // A picture or a logo (`lead`) first of the page's columns, as every table draws it until the user moves it.
+    const columns = useMemo(() => leadColumns(givenColumns), [givenColumns]);
     table.configure({ columns, rowKey, rows: givenRows, load, paging, maxSelection, onSelectionChange, onPickChange: onPick, filterInputs });
     useImperativeHandle(ref, () => table, [table]);
     const state = useSyncExternalStore(table.subscribe, table.getState, table.getState);
@@ -274,7 +276,7 @@ export function DataTable(props) {
     const labelOf = useCallback((row) => {
         if (rowLabel)
             return rowLabel(row);
-        const first = columns[0];
+        const first = namingColumn(columns);
         const text = first ? formatCellText(first, columnValue(first, row), cellOptions, row) : "";
         return text || `row ${table.keyOf(row)}`;
     }, [rowLabel, columns, cellOptions, table]);
@@ -675,7 +677,7 @@ export function DataTable(props) {
         body = rows.map((row, index) => {
             const key = pageKeys[index];
             const selected = state.selected.has(key);
-            return (_jsx(TableRowView, { row: row, rowKey: key, number: state.offset + index + 1, label: labelOf(row), columns: views, cellOptions: cellOptions, selectable: selectable, selected: selected, selectionFull: selectionFull && !selected, busy: state.busy.has(key), flashed: state.flashed.has(key), numbered: numbered, marks: rowMarks?.(row), frame: frame, sized: sized, actions: hasActions ? (actionsOf(row) ?? []) : null, onToggle: onToggle, onAction: onAction, onOpen: onRowOpen, openOnClick: openOnClick, onPick: pickable ? pickRow : undefined, picked: key === pickedKey, pickName: pickable ? pickName : undefined }, key || index));
+            return (_jsx(TableRowView, { row: row, rowKey: key, number: state.offset + index + 1, label: labelOf(row), columns: views, cellOptions: cellOptions, selectable: selectable, selected: selected, selectionFull: selectionFull && !selected, busy: state.busy.has(key), flashed: state.flashed.has(key), numbered: numbered, marks: rowMarks?.(row), strong: rowStrong?.(row) === true, frame: frame, sized: sized, actions: hasActions ? (actionsOf(row) ?? []) : null, onToggle: onToggle, onAction: onAction, onOpen: onRowOpen, openOnClick: openOnClick, onPick: pickable ? pickRow : undefined, picked: key === pickedKey, pickName: pickable ? pickName : undefined }, key || index));
         });
     }
     /* The sections above the page: the records pinned, the favourites, each folded open or shut, remembered on this device */
@@ -697,7 +699,7 @@ export function DataTable(props) {
             const key = table.keyOf(row);
             const selected = state.selected.has(key);
             const marks = rowMarks?.(row);
-            return (_jsx(TableRowView, { row: row, rowKey: key, number: index + 1, label: labelOf(row), columns: views, cellOptions: cellOptions, selectable: selectable, selected: selected, selectionFull: selectionFull && !selected, busy: state.busy.has(key), flashed: state.flashed.has(key), numbered: numbered, marks: marks?.length ? marks : own, frame: frame, sized: sized, actions: hasActions ? (actionsOf(row) ?? []) : null, onToggle: onToggle, onAction: onAction, onOpen: onRowOpen, openOnClick: openOnClick, 
+            return (_jsx(TableRowView, { row: row, rowKey: key, number: index + 1, label: labelOf(row), columns: views, cellOptions: cellOptions, selectable: selectable, selected: selected, selectionFull: selectionFull && !selected, busy: state.busy.has(key), flashed: state.flashed.has(key), numbered: numbered, marks: marks?.length ? marks : own, strong: rowStrong?.(row) === true, frame: frame, sized: sized, actions: hasActions ? (actionsOf(row) ?? []) : null, onToggle: onToggle, onAction: onAction, onOpen: onRowOpen, openOnClick: openOnClick, 
                 // A click picks a section's row too; its radio button is the one in the list below, where the arrow keys move.
                 onPick: pickable ? pickRow : undefined, picked: key === pickedKey }, key || index));
         });

package/dist/Components/Viewers/DataTableColumns.d.ts

@@ -1,11 +1,11 @@
 import { type Ref, type RefObject } from "react";
 import { type PopoverPanelHandle } from "../../Helpers/PopoverHooks.ts";
-import type { TableColumn, TablePinSide, TableRow } from "../../Interfaces/TableInterfaces.ts";
+import type { TableColumn, TablePins, TableRow } from "../../Interfaces/TableInterfaces.ts";
 export interface TableColumnsPanelProps<TRow extends TableRow> {
     /** Every column the table has, in the order they are in now - hidden ones among them. */
     columns: readonly TableColumn<TRow>[];
     hidden: ReadonlySet<string>;
-    pinned: Readonly<Record<string, TablePinSide>>;
+    pinned: TablePins;
     /** False while the table is not reorderable: the panel then only shows and hides. */
     reorderable?: boolean;
     /** Default `md`. */

package/dist/Components/Viewers/DataTableColumns.js

@@ -5,6 +5,7 @@ import { useEffect, useId, useRef, useState } from "react";
 import { cx } from "../../Helpers/ClassHelpers.js";
 import { isPopoverOpen } from "../../Helpers/PopoverHelpers.js";
 import { usePopoverPanel } from "../../Helpers/PopoverHooks.js";
+import { columnPin } from "../../Helpers/TableHelpers.js";
 import { Button } from "../Documents/Button.js";
 /** The rows of the panel: a band for every run of neighbours that name the same group, as the header draws them. */
 function panelRows(columns, groups) {
@@ -69,7 +70,7 @@ export function TableColumnsPanel({ columns, hidden, pinned, reorderable = true,
         key: column.key,
         label: column.label,
         shown: !hidden.has(column.key),
-        pin: pinned[column.key] ?? column.pinned ?? null,
+        pin: columnPin(column, pinned),
         movable: reorderable && column.movable !== false,
         hideable: column.hideable !== false,
     }));

package/dist/Components/Viewers/DataTableParts.d.ts

@@ -77,6 +77,8 @@ export interface TableRowViewProps<TRow extends TableRow> {
     numbered: boolean;
     /** The row's marks (pinned, a favourite), worn one under the other where a row without any shows its number. */
     marks?: readonly TableRowMark[];
+    /** The row reads strong (`rowStrong`): a thread with unread lines. */
+    strong?: boolean;
     /** Where the table's own columns sit; `null` for the ones it does not have. */
     frame: TableFrameColumns;
     /** The user gave a column a width, so the table lays its columns out from the `<colgroup>`. */
@@ -95,7 +97,7 @@ export interface TableRowViewProps<TRow extends TableRow> {
     pickName?: string;
 }
 /** One row. It renders again only when its row, its state, or the columns change. */
-declare function TableRowViewInner<TRow extends TableRow>({ row, rowKey, number, label, columns, cellOptions, selectable, selected, selectionFull, busy, flashed, numbered, marks, frame, sized, actions, onToggle, onAction, onOpen, openOnClick, onPick, picked, pickName, }: TableRowViewProps<TRow>): import("react").JSX.Element;
+declare function TableRowViewInner<TRow extends TableRow>({ row, rowKey, number, label, columns, cellOptions, selectable, selected, selectionFull, busy, flashed, numbered, marks, strong, frame, sized, actions, onToggle, onAction, onOpen, openOnClick, onPick, picked, pickName, }: TableRowViewProps<TRow>): import("react").JSX.Element;
 export declare const TableRowView: typeof TableRowViewInner;
 /**
  * The head of a section above the page: one row across the table with a button that folds the section's records open

package/dist/Components/Viewers/DataTableParts.js

@@ -129,13 +129,13 @@ function opensRow(event, single) {
     return !(selection && !selection.isCollapsed && event.currentTarget.contains(selection.anchorNode));
 }
 /** One row. It renders again only when its row, its state, or the columns change. */
-function TableRowViewInner({ row, rowKey, number, label, columns, cellOptions, selectable, selected, selectionFull, busy, flashed, numbered, marks, frame, sized, actions, onToggle, onAction, onOpen, openOnClick, onPick, picked = false, pickName, }) {
+function TableRowViewInner({ row, rowKey, number, label, columns, cellOptions, selectable, selected, selectionFull, busy, flashed, numbered, marks, strong = false, frame, sized, actions, onToggle, onAction, onOpen, openOnClick, onPick, picked = false, pickName, }) {
     const inline = actions?.filter(action => action.inline && action.icon) ?? [];
     const inMenu = actions?.filter(action => !(action.inline && action.icon)) ?? [];
     const items = inMenu.map(action => ({ value: action.id, label: action.label, icon: action.icon, description: action.description, tone: action.tone, disabled: action.disabled }));
     // A click picks a row where rows are picked; opening it is then the double-click's.
     const clickOpens = Boolean(onOpen && openOnClick && !onPick);
-    return (_jsxs("tr", { className: "nx-table__row", "data-key": rowKey, "data-selected": selected || undefined, "data-picked": picked || undefined, "data-busy": busy || undefined, "data-flash": flashed || undefined, "aria-busy": busy || undefined, "data-open": clickOpens || undefined, "data-pick": onPick ? "" : undefined, 
+    return (_jsxs("tr", { className: "nx-table__row", "data-key": rowKey, "data-selected": selected || undefined, "data-picked": picked || undefined, "data-strong": strong || undefined, "data-busy": busy || undefined, "data-flash": flashed || undefined, "aria-busy": busy || undefined, "data-open": clickOpens || undefined, "data-pick": onPick ? "" : undefined, 
         // One way in: with a single click the row is already open by the time a double-click would arrive.
         onClick: onPick ? event => opensRow(event, true) && onPick(row) : clickOpens ? event => opensRow(event, true) && onOpen?.(row) : undefined, onDoubleClick: onOpen && !clickOpens ? event => opensRow(event, false) && onOpen(row) : undefined, children: [frame.index && (_jsx(TableIndexCell, { own: frame.index, number: marks?.length ? (_jsx("span", { className: "nx-table__marks", children: marks.map(mark => (_jsx(InlineIcon, { icon: mark.icon, className: "nx-table__mark", label: mark.label }, mark.label))) })) : (formatCount(number)), numbered: numbered || Boolean(marks?.length), selectable: selectable, checkbox: selectable && (_jsx("label", { className: "nx-choice nx-choice--sm nx-table__check", title: selectionFull ? "No more rows can be selected." : undefined, children: _jsx("input", { type: "checkbox", className: "nx-choice__control nx-choice__control--checkbox", checked: selected, disabled: selectionFull && !selected, "aria-label": `Select ${label}`, onClick: event => onToggle(row, event.currentTarget.checked, event), onChange: () => undefined }) })), pick: onPick &&
                     pickName && (_jsx("input", { type: "radio", className: "nx-visually-hidden nx-table__pick", name: pickName, checked: picked, "aria-label": label, onChange: () => onPick(row) })) })), columns.map(view => (_jsx("td", { className: cx("nx-table__cell", `nx-table__cell--${columnAlign(view.column)}`, view.column.wrap && "nx-table__cell--wrap"), "data-col": view.column.key, "data-pin": view.pin ?? undefined, "data-pin-edge": (view.pin && view.edge) || undefined, style: columnStyle(view, sized), children: _jsx("span", { className: "nx-table__value", children: _jsx(TableCellValue, { column: view.column, row: row, options: cellOptions }) }) }, view.column.key))), sized && _jsx("td", { className: "nx-table__cell nx-table__cell--filler" }), frame.actions && (_jsx("td", { className: "nx-table__cell nx-table__cell--actions", "data-col": TABLE_ACTIONS_COLUMN, "data-pin": "right", "data-pin-edge": frame.actions.edge || undefined, style: ownStyle(frame.actions, "right"), children: _jsxs("div", { className: "nx-table__actions", children: [inline.map(action => (_jsx(Button, { variant: "ghost", size: "sm", icon: action.icon, hoverTone: action.tone === "danger" ? "danger" : undefined, "aria-label": `${action.label}: ${label}`, title: action.label, "data-action": action.id, disabled: busy || action.disabled, onClick: () => onAction(row, action) }, action.id))), items.length > 0 && (_jsx(Menu, { items: items, align: "end", "aria-label": `Actions: ${label}`, onSelect: value => onAction(row, inMenu.find(action => action.id === value)), children: _jsx(Button, { variant: "ghost", size: "sm", icon: _jsx(InlineIcon, { icon: iconDotsVertical }), loading: busy, "aria-label": `More actions: ${label}`, title: "More actions" }) })), items.length === 0 && busy && _jsx(Button, { variant: "ghost", size: "sm", loading: true, "aria-label": `Working: ${label}` })] }) }))] }));

package/dist/Components/Viewers/OwnerFiles.d.ts

@@ -1,6 +1,7 @@
 import { type ReactNode, type RefObject } from "react";
+import { type OwnerFileActions } from "../../Helpers/FileAdapter.ts";
 import type { ApiModuleValue, ApiResult, AppModule } from "../../Interfaces/ApiInterfaces.ts";
-import { type FileOwner, type OwnerFiles, type PictureType, type StoredFile } from "../../Interfaces/FileInterfaces.ts";
+import { type FileChange, type FileOwner, type OwnerFiles, type PictureType, type StoredFile } from "../../Interfaces/FileInterfaces.ts";
 import type { TableColumn, TableRow } from "../../Interfaces/TableInterfaces.ts";
 import { type PopupHandle } from "../Layouts/PopupHost.tsx";
 /** What a page declares for an owner's pictures: whose they are, and how a picture is made. */
@@ -31,8 +32,51 @@ export interface OwnerFilesParams<TModule extends ApiModuleValue = AppModule> ex
      * @example lockReason: row?.isClosed ? "The branch is closed: open it again to change its picture." : null
      */
     lockReason?: string | null;
+    /**
+     * The changes a person may make here, from the record's state, within what the backend allows: `["add"]` for a record
+     * whose files may only be added to - a posted goods receipt's documents - keeps Upload and offers no Rename, Delete,
+     * Make main or Remove (nor Replace or an Edit, which delete or mark). Default every change. `readOnly` and `lockReason`
+     * still show the files with none. A change the backend refuses as "only added to now" narrows them the same way for
+     * the rest of the page's life, under the backend's words, so a page read before the record changed stops offering it.
+     *
+     * @example changes: receipt.documentState === POSTED ? ["add"] : undefined
+     */
+    changes?: readonly FileChange[] | null;
+    /**
+     * Why only those changes, said under the files while `changes` leaves some out: "Posted: a document can be added, as a
+     * bill scanned later; none is removed."
+     */
+    changesReason?: string | null;
+    /**
+     * The category's Delete may wait for a review (a company's public gallery), told before the files are read - the
+     * backend says so too (`FileCategoryInfo.holdsRemovals`), and either is enough. The Delete then asks "If the public
+     * sees this picture, it stays until Nexus support approves its removal.", and the answer decides: a file answered
+     * `pendingRemoval` stays, shown "Removal waiting for review" with Keep in place of Delete; any other is gone at once.
+     */
+    holdsRemovals?: boolean;
+    /** Who reviews a held removal, in those sentences. Default `REMOVAL_REVIEWER` ("Nexus support"). */
+    removalReviewer?: string;
     /** After a change on this page: the owner's picture now (null for none). */
     onChange?: (primary: StoredFile | null) => void;
+    /**
+     * After every change made here that the backend took - an upload, an edit saved, a main picture chosen (or none), a
+     * rename, a delete, a delete held for a review, a Keep - with the owner's files as read again after it (as they were,
+     * when that read failed) and what changed. A page whose own record follows its files (a company's profile request,
+     * which a held Delete or a Keep changes on the server) reads it again here.
+     *
+     * @example onFilesChange: (files, change) => { if (change.kind === "hold" || change.kind === "keep") void reloadRequest(); }
+     */
+    onFilesChange?: (files: StoredFile[], change: OwnerFilesChange) => void;
+}
+/** What changed an owner's files, for `onFilesChange`: a delete held for a review is `hold`, its Keep `keep`. */
+export type OwnerFilesChangeKind = "upload" | "edit" | "primary" | "rename" | "delete" | "hold" | "keep";
+/**
+ * One change to an owner's files: what it was, and the file - the stored one (an upload's, an edit's last saved), the one
+ * made main (null for none), renamed, deleted, held or kept.
+ */
+export interface OwnerFilesChange {
+    kind: OwnerFilesChangeKind;
+    file: StoredFile | null;
 }
 /** What a person the backend lets only look at an owner's files is told, when it gave no words of its own. */
 export declare const READ_ONLY_REASON = "You can see these files, but you may not change them.";
@@ -60,10 +104,14 @@ export declare function useOwnerFiles(params: Omit<OwnerFilesParams<ApiModuleVal
     busy: string | null;
     canWrite: boolean;
     readOnlyReason: string | null;
+    changes: readonly FileChange[] | null;
+    changesNote: string | null;
+    offer: (file?: StoredFile | null) => OwnerFileActions;
     pictures: boolean;
+    holdsRemovals: boolean;
     editorProblem: string | null;
     actions: {
-        reload: () => Promise<void | StoredFile | null>;
+        reload: () => Promise<void | OwnerFiles>;
         /**
          * Chooses a picture, edits it, and makes it the owner's picture (the picture input's Upload). In a category that
          * keeps one file, the new picture takes the place of the one kept (Replace).
@@ -76,9 +124,11 @@ export declare function useOwnerFiles(params: Omit<OwnerFilesParams<ApiModuleVal
          * that keeps one file, the edited picture takes its place.
          */
         edit: (file: StoredFile) => Promise<void>;
-        makePrimary: (file: StoredFile | null) => Promise<void> | null;
+        makePrimary: (file: StoredFile | null) => false | Promise<void> | null;
         rename: (file: StoredFile) => Promise<void>;
         remove: (file: StoredFile) => Promise<void>;
+        /** Keeps a file whose removal waits for a review: the removal is cancelled. */
+        keep: (file: StoredFile) => Promise<void>;
         /** Shows the pictures in the editor module's viewer, from `file`. */
         view: (file: StoredFile) => Promise<void>;
     };
@@ -149,7 +199,7 @@ export interface OpenPictureGalleryOptions extends PictureGalleryProps {
  * "Documents".
  */
 export declare function openPictureGallery({ popupTitle, ...props }: OpenPictureGalleryOptions): PopupHandle;
-export interface PictureColumnParams<TRow extends TableRow> extends Omit<OwnerFilesParams<ApiModuleValue>, "ownerId" | "title" | "onChange" | "lockReason">, Partial<Omit<TableColumn<TRow>, "render" | "value">> {
+export interface PictureColumnParams<TRow extends TableRow> extends Omit<OwnerFilesParams<ApiModuleValue>, "ownerId" | "title" | "onChange" | "onFilesChange" | "lockReason">, Partial<Omit<TableColumn<TRow>, "render" | "value">> {
     /** The row's field that holds the owner's id. Default `id`. */
     ownerKey?: string;
     /** Whose the row's pictures are, for the window's title: `row => row.branchName`. */
@@ -167,9 +217,11 @@ export interface PictureColumnParams<TRow extends TableRow> extends Omit<OwnerFi
 /**
  * A column with each row's picture: every visible row's read in one call per page, and a click opens the row's
  * gallery. A change there redraws the row's picture without a reload.
+ * It is a `lead` column: every table draws it first of the page's columns (after the row number), pinned on the left
+ * when the page pins others there, wherever it stands in `columns`, until the user moves, unpins or hides it.
  *
  * @example
  * columns: [pictureColumn({ module: NexusModule.Enterprise, category: "branch-picture", rowTitle: row => row.branchName }), ...]
  */
-export declare function pictureColumn<TRow extends TableRow>({ module, category, ownerKey, rowTitle, nameKey, lockReason, onChange, aspect, shape, maxWidth, maxHeight, type, quality, readOnly, view, ...column }: PictureColumnParams<TRow> & Pick<PictureGalleryProps, "view">): TableColumn<TRow>;
+export declare function pictureColumn<TRow extends TableRow>({ module, category, ownerKey, rowTitle, nameKey, lockReason, onChange, aspect, shape, maxWidth, maxHeight, type, quality, readOnly, changes, changesReason, holdsRemovals, removalReviewer, view, ...column }: PictureColumnParams<TRow> & Pick<PictureGalleryProps, "view">): TableColumn<TRow>;
 export {};