nexus-shared 3.0.0 → 3.2.0

package/dist/Components/Forms/CrudHistory.d.ts

@@ -0,0 +1,66 @@
+import { type CrudBackend } from "../../Helpers/CrudBackend.ts";
+import type { ApiEndpoint } from "../../Interfaces/ApiInterfaces.ts";
+/** One column of a change, as the backend's history answers it (`AuditChangeResponseContract`). */
+export interface AuditChange {
+    /** The property: `RegionName`. */
+    column: string;
+    /** What a person calls it: "Region name". */
+    label: string;
+    /** How the value reads, as the backend's `EAuditValueTypes`: 0 text, 1 number, 2 yes or no, 3 date, 4 date and time, 5 enum, 6 id. */
+    type: number;
+    /** Before, as text. Absent when this change set it. */
+    oldValue?: string | null;
+    /** After, as text. Absent when this change cleared it. */
+    newValue?: string | null;
+    /** The words for an enum's or an id's value before, when the history kept them: RecordStatus 40 is "Trash". */
+    oldLabel?: string | null;
+    /** The words for the value after. */
+    newLabel?: string | null;
+}
+/** One entry of a record's history (`AuditResponseContract`). Every id in it is a token made for the reader. */
+export interface AuditEntry {
+    /** When, in UTC. Every entry of one mass call shares it. */
+    creationTime: string;
+    /** Who made the change. */
+    creatorUserId?: string;
+    /** The company they made it in. */
+    companyId?: string;
+    /** The branch they made it in. */
+    branchId?: string;
+    /** What the request did, as the backend numbers its commands. */
+    commandType: number;
+    /** The part of the record it was about, as the backend numbers its audit keys. */
+    auditKey: number;
+    /** 0 for one record; else how many records one mass call changed, which every entry of that call shares. */
+    massCount: number;
+    /** What moved, column by column. Empty for a request that found the record already as it asked. */
+    changes?: AuditChange[];
+}
+export interface AuditHistoryProps {
+    /** The model's history endpoint: GET `{Model}/AuditListing/{ownerId}/{skipCount}`, as `apiController(...).audit` builds it. */
+    endpoint: ApiEndpoint;
+    /** The record's key, as the backend handed it out. */
+    id: string | number;
+    /** What one record is, for the words: "region". Default "record". */
+    subject?: string;
+    /** Its plural, when adding "s" is wrong. */
+    subjectPlural?: string;
+    /** The backend whose numbers the entries carry. Default the app's (`getCrudBackend`). */
+    backend?: CrudBackend;
+}
+/**
+ * A record's history, newest first, 50 entries at a time: "Show more" while the last page came back full. Each entry
+ * says what was done, when, by whom and how many records it changed at once, and lists the columns it changed with
+ * their values before and after - the words the backend kept for an enum or an id where it has them.
+ */
+export declare function AuditHistory({ endpoint, id, subject, subjectPlural, backend }: AuditHistoryProps): import("react").JSX.Element;
+/** What `openAuditHistory` takes: the history's own props, and the record's name for the title bar. */
+export interface AuditHistoryPopupOptions extends AuditHistoryProps {
+    /** Names the record beside the title: "Asia". */
+    label?: string;
+}
+/**
+ * Opens a record's history in a popup, "Region history" with the record's name beside it. One popup per record:
+ * opening it again brings back the one that is open, with what it has loaded.
+ */
+export declare function openAuditHistory({ label, ...props }: AuditHistoryPopupOptions): import("../Layouts/PopupHost.tsx").PopupHandle;

package/dist/Components/Forms/CrudHistory.js

@@ -0,0 +1,140 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { iconAlertCircle, iconHistory, iconInfoCircle, iconLoader2, iconRefresh, InlineIcon } from "nexus-icons";
+import { Fragment, useEffect, useMemo, useState } from "react";
+import { getCrudBackend } from "../../Helpers/CrudBackend.js";
+import { useBrowserTimeZone, useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { pluralize } from "../../Helpers/MessageBuilder.js";
+import { formatCellText } from "../../Helpers/TableHelpers.js";
+import { api } from "../../Services/BrowserApi.js";
+import { Button } from "../Documents/Button.js";
+import { openPopup } from "../Layouts/PopupHost.js";
+/** How many entries one call answers (the backend's `AUDIT_PAGE_SIZE`): a page that came back full may have more behind it. */
+const PAGE_SIZE = 50;
+/** What an entry did, in words: "Added", "Updated: basic information", "Flagged", "Moved to the trash". */
+function whatOf(entry, words) {
+    const direction = words.directions[entry.auditKey];
+    if (direction)
+        return direction;
+    const command = words.commands[entry.commandType] ?? `Action ${entry.commandType}`;
+    const part = entry.commandType === words.update ? words.parts[entry.auditKey] : undefined;
+    return part ? `${command}: ${part}` : command;
+}
+/** How each `EAuditValueTypes` is written: as a table column of that format writes it. Text, enums and ids are left as they are. */
+const FORMATS = { 1: "number", 2: "boolean", 3: "date", 4: "date-time" };
+/** `EAuditValueTypes.Id`: a record's key, handed out as a token made for the reader. */
+const ID = 6;
+/** When an entry happened, written as the table writes a date-time column: the user's settings, in their zone. */
+const WHEN = { key: "creationTime", label: "When", format: "date-time" };
+const NEWLINE = String.fromCharCode(10);
+/**
+ * A token, short. It names nobody and only tells two apart, so its first characters are enough. A token is the same
+ * text for one id on every entry this reader is given (the id is encrypted for the reader, not at random).
+ */
+const shortToken = (token) => (token.length > 8 ? `${token.slice(0, 6)}…` : token);
+/** One side of a change, in words; "" when that side has no value. */
+function sideText(change, value, label, options) {
+    if (label)
+        return label;
+    if (value === null || value === undefined || value === "")
+        return "";
+    // An id the history kept no name for: its token, which is all there is to show.
+    if (change.type === ID)
+        return `#${shortToken(value)}`;
+    return formatCellText({ key: change.column, label: change.label, format: FORMATS[change.type] ?? "text" }, value, options);
+}
+/** One side of a change as a cell: its words, a line of text to a line, or what having no value there means. */
+function SideCell({ text, missing }) {
+    if (!text)
+        return (_jsx("td", { children: _jsx("span", { className: "nx-markdown__empty", children: missing }) }));
+    return (_jsx("td", { children: text.split(NEWLINE).map((line, index) => (_jsxs(Fragment, { children: [index > 0 && _jsx("br", {}), line] }, index))) }));
+}
+/** One entry: what was done as a heading, when and by whom under it, and the columns it changed as a small table. */
+function HistoryEntry({ entry, words, subject, plural, options }) {
+    const changes = entry.changes ?? [];
+    const count = entry.massCount;
+    return (_jsxs(_Fragment, { children: [_jsx("h3", { children: whatOf(entry, words) }), _jsxs("p", { children: [_jsx("time", { dateTime: entry.creationTime, children: formatCellText(WHEN, entry.creationTime, options) }), entry.creatorUserId && ` · User ${shortToken(entry.creatorUserId)}`, count > 1 && ` · ${count} ${plural} at once`, count === 1 && " · from a selection"] }), changes.length > 0 ? (_jsx("div", { className: "nx-markdown__table", children: _jsxs("table", { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: "Field" }), _jsx("th", { scope: "col", children: "Before" }), _jsx("th", { scope: "col", children: "After" })] }) }), _jsx("tbody", { children: changes.map((change, index) => (_jsxs("tr", { children: [_jsx("td", { children: change.label || change.column }), _jsx(SideCell, { text: sideText(change, change.oldValue, change.oldLabel, options), missing: "Not set" }), _jsx(SideCell, { text: sideText(change, change.newValue, change.newLabel, options), missing: "Cleared" })] }, `${change.column}:${index}`))) })] }) })) : (_jsxs("p", { className: "nx-markdown__empty", children: ["Nothing changed: the ", subject, " was already as asked."] }))] }));
+}
+/** One page of a record's history, newest first: the entries after the first `skipCount`. */
+function readHistory(endpoint, id, skipCount, options = {}) {
+    // `apiController`'s own `audit` endpoint names the key `{ownerId}`, and one a page writes itself may say `{id}`: both
+    // are given, and the path takes the one it has.
+    return api.get(endpoint, { params: { id, ownerId: id, skipCount }, subject: "the history", ...options });
+}
+/** A status line: an icon and its words, in the form's muted line. */
+function Note({ icon, children, alert }) {
+    return (_jsxs("p", { className: "nx-form-status", role: alert ? "alert" : "status", children: [_jsx(InlineIcon, { icon: icon, className: icon === iconLoader2 ? "nx-spin" : undefined }), _jsx("span", { children: children })] }));
+}
+/**
+ * A record's history, newest first, 50 entries at a time: "Show more" while the last page came back full. Each entry
+ * says what was done, when, by whom and how many records it changed at once, and lists the columns it changed with
+ * their values before and after - the words the backend kept for an enum or an id where it has them.
+ */
+export function AuditHistory({ endpoint, id, subject = "record", subjectPlural, backend }) {
+    const plural = subjectPlural ?? pluralize(subject);
+    const words = (backend ?? getCrudBackend()).auditWords;
+    const preferences = useDatePreferences();
+    const timeZone = useBrowserTimeZone();
+    const options = useMemo(() => ({ preferences, timeZone: timeZone ?? undefined }), [preferences, timeZone]);
+    const [entries, setEntries] = useState([]);
+    const [status, setStatus] = useState("loading");
+    const [problem, setProblem] = useState();
+    const [more, setMore] = useState(false);
+    const [busy, setBusy] = useState(false);
+    const [attempt, setAttempt] = useState(0);
+    // The first page. Its failure is said here, with a way to try again, rather than as a toast over the popup.
+    useEffect(() => {
+        const controller = new AbortController();
+        setStatus("loading");
+        void readHistory(endpoint, id, 0, { signal: controller.signal, toast: false }).then(answer => {
+            if (answer.aborted)
+                return;
+            if (!answer.ok) {
+                setProblem(answer.message);
+                setStatus("failed");
+                return;
+            }
+            const page = Array.isArray(answer.result) ? answer.result : [];
+            setEntries(page);
+            setMore(page.length >= PAGE_SIZE);
+            setStatus("ready");
+        });
+        return () => controller.abort();
+    }, [endpoint, id, attempt]);
+    /** The next page, after the entries already shown. A failure is the api's own toast, and the button stays to try again. */
+    async function showMore() {
+        setBusy(true);
+        const answer = await readHistory(endpoint, id, entries.length);
+        setBusy(false);
+        if (!answer.ok)
+            return;
+        const page = Array.isArray(answer.result) ? answer.result : [];
+        setEntries(current => [...current, ...page]);
+        setMore(page.length >= PAGE_SIZE);
+    }
+    if (status === "loading")
+        return _jsx(Note, { icon: iconLoader2, children: "Loading the history\u2026" });
+    if (status === "failed") {
+        return (_jsxs("div", { className: "nx-crud-details", children: [_jsx(Note, { icon: iconAlertCircle, alert: true, children: problem ?? "The history could not be loaded." }), _jsx("div", { children: _jsx(Button, { size: "sm", icon: _jsx(InlineIcon, { icon: iconRefresh }), onClick: () => setAttempt(count => count + 1), children: "Try again" }) })] }));
+    }
+    if (entries.length === 0)
+        return _jsx(Note, { icon: iconInfoCircle, children: `Nothing has been recorded for this ${subject} yet.` });
+    return (_jsxs("div", { className: "nx-markdown", children: [entries.map((entry, index) => (_jsx(HistoryEntry, { entry: entry, words: words, subject: subject, plural: plural, options: options }, index))), more && (_jsx("p", { children: _jsx(Button, { size: "sm", loading: busy, onClick: () => void showMore(), children: "Show more" }) }))] }));
+}
+/**
+ * Opens a record's history in a popup, "Region history" with the record's name beside it. One popup per record:
+ * opening it again brings back the one that is open, with what it has loaded.
+ */
+export function openAuditHistory({ label, ...props }) {
+    const subject = props.subject ?? "record";
+    return openPopup({
+        key: `${subject}-history-${props.id}`,
+        reopen: "restore",
+        title: `${subject.charAt(0).toUpperCase()}${subject.slice(1)} history`,
+        description: label,
+        icon: _jsx(InlineIcon, { icon: iconHistory }),
+        size: "lg",
+        content: _jsx(AuditHistory, { ...props }),
+        footer: popup => (_jsx(Button, { variant: "primary", onClick: () => popup.close(), children: "Close" })),
+    });
+}

package/dist/Components/Forms/CrudParts.d.ts

@@ -6,7 +6,11 @@ export interface CrudDetailsProps<TRow extends FormValues = FormValues> {
     row: TRow;
     /** The fields, as the table's columns describe them; hidden columns included. */
     columns: readonly TableColumn<TRow>[];
-    /** Loads the full record (fields the list leaves out); its values replace the row's when they come. */
+    /**
+     * Loads the full record (fields the list leaves out); its values replace the row's when they come. Meanwhile a field
+     * the row lacks keeps its line blank, and reads "Not loaded" if the load fails; the details say nothing else about
+     * the load (`aria-busy` while it runs), so the popup around them never changes size for it.
+     */
     load?: (signal: AbortSignal) => Promise<Partial<TRow> | null | undefined>;
     /** Draws the details instead of the list of fields. */
     render?: (row: TRow) => ReactNode;

package/dist/Components/Forms/CrudParts.js

@@ -1,18 +1,31 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { iconInfoCircle, iconLoader2, InlineIcon } from "nexus-icons";
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { motionAllowed } from "../../Helpers/AnimationHelpers.js";
 import { isAbortError } from "../../Helpers/ApiResponses.js";
 import { cx } from "../../Helpers/ClassHelpers.js";
 import { useBrowserTimeZone, useDatePreferences } from "../../Helpers/DatePreferences.js";
+import { readPath } from "../../Helpers/TableHelpers.js";
+import { useNumberLocale } from "../../Helpers/UserPreferences.js";
 import { TableCellValue } from "../Viewers/DataTableParts.js";
+import { MarkdownView } from "../Viewers/MarkdownView.js";
+/**
+ * An element's height as its `height` would set it: unrounded, unlike `offsetHeight`, so an unroll between two of
+ * them starts and ends exactly where the details are and the popup never steps by a fraction of a pixel. NaN while
+ * not drawn.
+ */
+const usedHeight = (element) => parseFloat(getComputedStyle(element).height);
 /** A record's fields as label and value, two to a line where there is room, in the formats of the table's columns. */
 export function CrudDetails({ row, columns, load, render }) {
     const [record, setRecord] = useState(row);
     const [state, setState] = useState(load ? "loading" : "done");
+    const rootRef = useRef(null);
+    // The details' height just before the full record went in, kept only when the change may be animated.
+    const grownFrom = useRef(null);
     const preferences = useDatePreferences();
     const timeZone = useBrowserTimeZone();
-    const options = useMemo(() => ({ preferences, timeZone: timeZone ?? undefined }), [preferences, timeZone]);
+    const locale = useNumberLocale();
+    const options = useMemo(() => ({ preferences, timeZone: timeZone ?? undefined, locale }), [preferences, timeZone, locale]);
     useEffect(() => {
         if (!load)
             return;
@@ -20,8 +33,11 @@ export function CrudDetails({ row, columns, load, render }) {
         load(controller.signal).then(full => {
             if (controller.signal.aborted)
                 return;
-            if (full)
+            if (full) {
+                if (motionAllowed() && rootRef.current)
+                    grownFrom.current = usedHeight(rootRef.current);
                 setRecord(current => ({ ...current, ...full }));
+            }
             setState("done");
         }, error => {
             if (controller.signal.aborted || isAbortError(error))
@@ -32,5 +48,22 @@ export function CrudDetails({ row, columns, load, render }) {
         // The record loads once per popup.
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, []);
-    return (_jsxs("div", { className: "nx-crud-details", "aria-busy": state === "loading" || undefined, children: [state === "loading" && (_jsxs("p", { className: "nx-crud-details__note", role: "status", children: [_jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin" }), "Loading the full record\u2026"] })), state === "failed" && (_jsxs("p", { className: "nx-crud-details__note", role: "status", children: [_jsx(InlineIcon, { icon: iconInfoCircle }), "The full record could not be loaded; these are the values from the list."] })), render ? (render(record)) : (_jsx("dl", { className: "nx-crud-details__list", children: columns.map(column => (_jsxs("div", { className: cx("nx-crud-details__item", column.wrap && "nx-crud-details__item--wide"), children: [_jsx("dt", { className: "nx-crud-details__label", children: column.label }), _jsx("dd", { className: "nx-crud-details__value", children: _jsx(TableCellValue, { column: column, row: record, options: options }) })] }, column.key))) }))] }));
+    // A record that makes the details taller (a long note the list did not have) unrolls to its height when motion is
+    // allowed, as maximize does; without motion it changes at once. Nothing waits on it.
+    useLayoutEffect(() => {
+        const from = grownFrom.current;
+        grownFrom.current = null;
+        const root = rootRef.current;
+        if (!from || !root || typeof root.animate !== "function")
+            return;
+        const to = usedHeight(root);
+        if (!to || Math.abs(to - from) < 1)
+            return;
+        const animation = root.animate([{ height: `${from}px`, overflow: "clip" }, { height: `${to}px`, overflow: "clip" }], { duration: 200, easing: "cubic-bezier(0.2, 0, 0, 1)" });
+        return () => animation.cancel();
+    }, [record]);
+    // A field the list's row does not carry can only be filled by the full record. Columns that draw or work out their
+    // own value (`render`, `value`) draw as always, because only they know what they read.
+    const awaited = (column) => state !== "done" && !column.render && !column.value && readPath(record, column.key) === undefined;
+    return (_jsx("div", { ref: rootRef, className: "nx-crud-details", "aria-busy": state === "loading" || undefined, children: render ? (render(record)) : (_jsx("dl", { className: "nx-crud-details__list", children: columns.map(column => (_jsxs("div", { className: cx("nx-crud-details__item", column.wrap && "nx-crud-details__item--wide"), children: [_jsx("dt", { className: "nx-crud-details__label", children: column.label }), _jsx("dd", { className: "nx-crud-details__value", children: awaited(column) ? (state === "failed" ? _jsx("span", { className: "nx-crud-details__missing", children: "Not loaded" }) : null) : column.markdown && !column.render ? (_jsx(MarkdownView, { value: String(readPath(record, column.key) ?? ""), placeholder: `No ${column.label.toLowerCase()}` })) : (_jsx(TableCellValue, { column: column, row: record, options: options })) })] }, column.key))) })) }));
 }

package/dist/Components/Forms/ExcelImport.d.ts

@@ -1,4 +1,4 @@
-import { type ReactNode } from "react";
+import { type ReactNode, type Ref } from "react";
 import type { ExcelEndpoints, ExcelImportAnswer } from "../../Interfaces/ExcelInterfaces.ts";
 import { type ExcelCallOptions } from "../../Services/ExcelApi.ts";
 import { type PopupHandle } from "../Layouts/PopupHost.tsx";
@@ -18,24 +18,40 @@ export interface ExcelImportProps {
     templateDownload?: false;
     /** The tallest each editor grows before its rows scroll. Default 320. */
     maxHeight?: number;
+    /**
+     * `"file"` (the default): a filled template is sent to be checked, and its rows come back to be gone over.
+     * `"bulk"`: no file - the rows are typed here, from one empty row, and imported with the same checks. A sheet with a
+     * required list cannot be typed in (its key is picked in the spreadsheet), and the panel says so.
+     */
+    mode?: "file" | "bulk";
+    /** What closing the panel would lose, so a window can ask first: `openExcelImport` passes one. */
+    ref?: Ref<ExcelImportHandle>;
     className?: string;
 }
+/** What `ref` gives on an import panel. */
+export interface ExcelImportHandle {
+    /** The rows only this screen has - typed here, or a sheet's row edited here - which closing the panel loses. */
+    unsavedRows: () => number;
+}
 /**
- * The three steps of an import in one panel: the template, the file, and the review.
+ * The three steps of an import in one panel: the template, the file, and the review - or, for a bulk insert, the rows
+ * typed in and the import.
  *
  * @example
  * <ExcelImport endpoints={CITY_SHEET} subject="city" onImported={() => table.reload()} />
+ * <ExcelImport endpoints={REGION_SHEET} subject="region" mode="bulk" onImported={() => table.reload()} />
  */
-export declare function ExcelImport({ endpoints, subject: given, params, onImported, onClose, templateDownload, maxHeight, className }: ExcelImportProps): import("react").JSX.Element;
+export declare function ExcelImport({ endpoints, subject: given, params, onImported, onClose, templateDownload, maxHeight, mode, ref, className }: ExcelImportProps): import("react").JSX.Element;
 /** Options of the import popup: the panel's, plus what the window looks like. */
-export interface OpenExcelImportOptions extends Omit<ExcelImportProps, "onClose"> {
-    /** The window's title. Default: "Import <subjects> from a spreadsheet". */
+export interface OpenExcelImportOptions extends Omit<ExcelImportProps, "onClose" | "ref"> {
+    /** The window's title. Default: "Import <subjects> from a spreadsheet", or "Bulk insert <subjects>". */
     title?: ReactNode;
-    /** One popup per key. Default: the import endpoint's path, so one model opens one. */
+    /** One popup per key. Default: the import endpoint's path and the mode, so one model opens one of each. */
     popupKey?: string;
 }
 /**
- * Opens the import panel as a window. This is the one line a data table's Import entry needs.
+ * Opens the import panel as a window. This is the one line a data table's Import entry needs - and, with
+ * `mode: "bulk"`, its Bulk insert entry.
  *
  * @example onImport={() => openExcelImport({ endpoints: CITY_SHEET, subject: "city", onImported: reload })}
  */