nexus-shared 3.1.0 → 4.0.0

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

@@ -0,0 +1,136 @@
+import { type IconNode } from "nexus-icons";
+import type { ReactNode } from "react";
+import type { CrudBackend } from "../../Helpers/CrudBackend.ts";
+import { type CrudJoinedRecord } from "../../Helpers/CrudHelpers.ts";
+import type { ApiResult } from "../../Interfaces/ApiInterfaces.ts";
+import type { CrudEndpoints, CrudFormOptions, CrudInputs, CrudMassActionName, CrudRowActionName } from "../../Interfaces/CrudInterfaces.ts";
+import { type FormValues, type InputParams } from "../../Interfaces/FormInterfaces.ts";
+/** The subject the endpoints were given: `apiController(module, "Guest", "guest")` → "guest". */
+export declare function crudSubject(api: CrudEndpoints): string | undefined;
+/** How the built-in actions on one record read wherever they are offered: a table's row, a tree's row, a panel's buttons. */
+export declare const CRUD_ACTION_WORDS: {
+    readonly create: {
+        readonly label: "Add New";
+        readonly icon: IconNode;
+    };
+    readonly edit: {
+        readonly label: "Edit";
+        readonly icon: IconNode;
+    };
+    readonly history: {
+        readonly label: "History";
+        readonly icon: IconNode;
+    };
+    readonly trash: {
+        readonly label: "Move to trash";
+        readonly icon: IconNode;
+        readonly tone: "danger";
+    };
+    readonly recover: {
+        readonly label: "Recover";
+        readonly description: "Back to the active list";
+        readonly icon: IconNode;
+    };
+    readonly delete: {
+        readonly label: "Delete permanently";
+        readonly icon: IconNode;
+        readonly tone: "danger";
+    };
+    readonly trashFromDelete: {
+        readonly label: "Move back to trash";
+        readonly icon: IconNode;
+    };
+};
+/** An action's words as a menu entry or a button takes them: the label, the icon drawn, and its tone and second line. */
+export declare function crudActionEntry(action: keyof typeof CRUD_ACTION_WORDS): {
+    label: string;
+    icon: ReactNode;
+    tone?: "danger";
+    description?: string;
+};
+/** Actions that move a record between the lists are asked about first; flags and pins are undone by a click. */
+export declare const CRUD_ASKED: ReadonlySet<CrudRowActionName | CrudMassActionName>;
+/**
+ * The body of an Add, Edit or details popup. Without an `aside` it is the form (or the details) and nothing else, so
+ * a popup that wants no panel carries no wrapper at all. With one, the two become columns that scroll on their own,
+ * and the form is first in the DOM — which is also the order they stack in when there is no room for two. A details
+ * popup is marked, because there the panel is what the popup is for and takes the larger share.
+ */
+export declare function CrudFormBody({ aside, details, below, children }: {
+    aside: ReactNode;
+    details?: boolean;
+    below?: boolean;
+    children: ReactNode;
+}): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
+/** The inputs of the Add or the Edit form, from one list, a list each, or a function of the action and the record. */
+export declare function crudInputsFor<TRow extends FormValues>(inputs: CrudInputs<TRow>, action: "create" | "edit", row: TRow | null): Promise<readonly InputParams[]>;
+/** What the Add or Edit popup is opened with. */
+export interface CrudFormRequest<TRow extends FormValues = FormValues> {
+    api: CrudEndpoints;
+    action: "create" | "edit";
+    /** The record edited; `null` for a new one. */
+    row: TRow | null;
+    /** Values over the new record's (`form.newValues`): the parent it is added under. */
+    values?: Partial<TRow>;
+    /**
+     * Inputs fixed for this opening, by name, each with why: read-only with the lock and the reason as its note, their
+     * values (from `values`, or the edited record) kept and sent (`lockInputs`), and never rewritten by the form's own
+     * `onFieldChange`. An Add with fixed inputs is a popup and a draft of its own per set of fixed values (`crudFormPlace`),
+     * so an Add started inside one parent never comes back inside another; an Edit stays one popup per record, its draft
+     * per set of fixed values.
+     */
+    locked?: Readonly<Record<string, string>>;
+    /**
+     * Records the caller holds for the values it fixes - the row picked in another list that a new record is added for: a
+     * fixed dropdown names its value from them, with no lookup (`lockInputs`).
+     */
+    known?: readonly FormValues[];
+    inputs: CrudInputs<TRow>;
+    form?: CrudFormOptions<TRow>;
+    /** What one record is: "region". */
+    subject: string;
+    /** Tells the popups of one controller apart from another's. */
+    name: string;
+    /** The field that tells records apart. Default `id`. */
+    rowKey?: string;
+    /** The record's key as text, for the Edit popup's key and its draft. */
+    key?: string;
+    /** Beside the title, and under it on the dock while minimized: the record an Edit is of, where an Add adds ("Inside Bagmati"). */
+    label?: string;
+    /**
+     * After the save: the answer, the values sent, and what the form's dropdowns know of the records their keys name
+     * (`joined`), so the record's joined names are written with no call. The popup closes itself.
+     */
+    onSaved: (result: unknown, saved: TRow, joined: CrudJoinedLookup) => void;
+}
+/**
+ * The record behind a key of a form's dropdown (`name`), as a save names its joins (`crudJoinedNames`): the item the
+ * user picked for that key, else one of the dropdown's `selectedOptions` (given for a saved or a fixed value), else one
+ * the page holds (the dropdown's `peekOption`), else one of `held` (records the caller holds: a tree's parent, a narrowed
+ * list's picked record), else one the page held once and has marked old (`peekOption(key, true)`: an old name beats
+ * none). Its name is the dropdown's `labelKey` field, its status the record's `recordStatus`. `null` when none is known:
+ * nothing is asked for it.
+ */
+export type CrudJoinedLookup = (name: string, key: string, held?: readonly FormValues[]) => CrudJoinedRecord | null;
+/**
+ * Opens the Add or the Edit popup of a controller's record: its inputs in an `ApiForm` that calls `create` or `update`,
+ * a discard question before changes are lost, and `onSaved` with the answer.
+ *
+ * - An Add form with changes comes back as it was - the one of the same place, when inputs are fixed (`locked`). Asking
+ *   for one replaces every untouched Add of the controller, so the dock keeps only forms with work in them.
+ * - A record has one Edit popup wherever it was opened from. Asked for again with the same inputs fixed, it comes back;
+ *   with others (a tree's fixed form, a data table's free one), an untouched one is replaced, and one with changes comes
+ *   back as it is, saying why: an older form's save would undo what the newer one saved.
+ */
+export declare function openCrudForm<TRow extends FormValues>(request: CrudFormRequest<TRow>): Promise<void>;
+/**
+ * Calls the endpoint of a built-in action on one record - asking first for those that move it between the lists - with
+ * the record's key in the path and its name in the messages. A flag carries the way it goes (`markOn`). `null` when the
+ * controller has no such endpoint or the question was answered No.
+ */
+export declare function sendCrudRowAction<TRow extends FormValues>(api: CrudEndpoints, action: CrudRowActionName, row: TRow, options: {
+    rowKey?: string;
+    label?: string;
+    backend: CrudBackend;
+    markOn?: boolean;
+}): Promise<ApiResult | null>;

package/dist/Components/Forms/CrudActions.js

@@ -0,0 +1,184 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconArrowBackUp, iconHistory, iconPencil, iconPlus, iconTrash, iconTrashX, InlineIcon } from "nexus-icons";
+import { unwrapApiResult } from "../../Helpers/ApiResponses.js";
+import { crudFormPlace, crudMessageAction, crudRowEndpoint } from "../../Helpers/CrudHelpers.js";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { FormStore } from "../../Helpers/FormStore.js";
+import { lockedFieldChange, lockInputs } from "../../Helpers/InputParamsHelpers.js";
+import { readPath } from "../../Helpers/TableHelpers.js";
+import { EInputTypes } from "../../Interfaces/FormInterfaces.js";
+import { api as browserApi } from "../../Services/BrowserApi.js";
+import { openPopup } from "../Layouts/PopupHost.js";
+import { popupRuleFor } from "../Layouts/PopupRules.js";
+import { toast } from "../Layouts/Toaster.js";
+import { ApiForm } from "./ApiForm.js";
+import { confirmDiscard, FormButtons } from "./SubmitForm.js";
+/*
+ * What every view of a controller's records does the same way - the data table (`Crud`) and the tree (`CrudTree`): the
+ * Add and Edit popups, the call behind an action on one record, and the words and icons each action shows. One copy, so
+ * a record added from a tree is added through exactly the form the table opens.
+ */
+/** The subject the endpoints were given: `apiController(module, "Guest", "guest")` → "guest". */
+export function crudSubject(api) {
+    const endpoints = [api.create, api.update, api.details, ...Object.values(api.lists ?? {}), ...Object.values(api.pages ?? {})];
+    return endpoints.find(endpoint => endpoint?.subject)?.subject;
+}
+/** How the built-in actions on one record read wherever they are offered: a table's row, a tree's row, a panel's buttons. */
+export const CRUD_ACTION_WORDS = {
+    // One fixed label on every CRUD, whatever its subject (the owner, 2026-10-10); the form it opens says "Add <subject>".
+    create: { label: "Add New", icon: iconPlus },
+    edit: { label: "Edit", icon: iconPencil },
+    history: { label: "History", icon: iconHistory },
+    trash: { label: "Move to trash", icon: iconTrash, tone: "danger" },
+    recover: { label: "Recover", description: "Back to the active list", icon: iconArrowBackUp },
+    delete: { label: "Delete permanently", icon: iconTrashX, tone: "danger" },
+    trashFromDelete: { label: "Move back to trash", icon: iconArrowBackUp },
+};
+/** An action's words as a menu entry or a button takes them: the label, the icon drawn, and its tone and second line. */
+export function crudActionEntry(action) {
+    const words = CRUD_ACTION_WORDS[action];
+    return { label: words.label, icon: _jsx(InlineIcon, { icon: words.icon }), tone: words.tone, description: words.description };
+}
+/** Actions that move a record between the lists are asked about first; flags and pins are undone by a click. */
+export const CRUD_ASKED = new Set(["trash", "recover", "delete", "trashFromDelete"]);
+/**
+ * The body of an Add, Edit or details popup. Without an `aside` it is the form (or the details) and nothing else, so
+ * a popup that wants no panel carries no wrapper at all. With one, the two become columns that scroll on their own,
+ * and the form is first in the DOM — which is also the order they stack in when there is no room for two. A details
+ * popup is marked, because there the panel is what the popup is for and takes the larger share.
+ */
+export function CrudFormBody({ aside, details, below, children }) {
+    if (!aside)
+        return children;
+    return (_jsxs("div", { className: cx("nx-crud-aside", details && "nx-crud-aside--details", below && "nx-crud-aside--below"), children: [_jsx("div", { className: "nx-crud-aside__main", children: children }), _jsx("aside", { className: "nx-crud-aside__side", children: aside })] }));
+}
+/** The inputs of the Add or the Edit form, from one list, a list each, or a function of the action and the record. */
+export async function crudInputsFor(inputs, action, row) {
+    if (typeof inputs === "function")
+        return inputs(action, row);
+    if (Array.isArray(inputs))
+        return inputs;
+    const split = inputs;
+    return (action === "create" ? (split.create ?? split.edit) : (split.edit ?? split.create)) ?? [];
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const capitalize = (text) => (text ? text[0].toUpperCase() + text.slice(1) : text);
+/** `CrudJoinedLookup` over a form's inputs and its store. */
+function joinedLookup(inputs, form) {
+    return (name, key, held = []) => {
+        const params = inputs.find(input => input.name === name);
+        if (!params || params.type !== EInputTypes.Dropdown || params.multiple)
+            return null;
+        const valueKey = params.valueKey ?? "value";
+        const labelKey = params.labelKey ?? "label";
+        const matches = (item) => isRecord(item) && String(item[valueKey]) === key;
+        // The form's own first: what the user picked, then the records the input was given for its saved value.
+        const record = [form.pickedItem(name), ...(params.selectedOptions ?? []), params.peekOption?.(key), ...held].find(matches) ?? [params.peekOption?.(key, true)].find(matches);
+        return record ? { name: record[labelKey], status: record.recordStatus } : null;
+    };
+}
+/** The Add and Edit popups open now, by popup key: the controller's name, the action, the form, and the place it was opened for. */
+const openForms = new Map();
+/** Brings a popup back from the dock; one on screen is left as it is. */
+function bringBack(handle) {
+    if (handle.windowState === "minimized")
+        handle.restore();
+}
+/**
+ * Opens the Add or the Edit popup of a controller's record: its inputs in an `ApiForm` that calls `create` or `update`,
+ * a discard question before changes are lost, and `onSaved` with the answer.
+ *
+ * - An Add form with changes comes back as it was - the one of the same place, when inputs are fixed (`locked`). Asking
+ *   for one replaces every untouched Add of the controller, so the dock keeps only forms with work in them.
+ * - A record has one Edit popup wherever it was opened from. Asked for again with the same inputs fixed, it comes back;
+ *   with others (a tree's fixed form, a data table's free one), an untouched one is replaced, and one with changes comes
+ *   back as it is, saying why: an older form's save would undo what the newer one saved.
+ */
+export async function openCrudForm(request) {
+    const { api, action, row, values, locked, subject, name, rowKey = "id", key = "", label, onSaved } = request;
+    const endpoint = action === "create" ? api.create : api.update;
+    if (!endpoint)
+        return;
+    const options = request.form ?? {};
+    const newValues = typeof options.newValues === "function" ? options.newValues() : options.newValues;
+    // What the form opens with: a new record's values, or the record edited.
+    const opening = (action === "create" ? { ...newValues, ...values } : (row ?? {}));
+    // Fixed inputs make it the form of one place: an Add's popup and every draft carry the values fixed.
+    const place = locked ? crudFormPlace(Object.fromEntries(Object.keys(locked).map(field => [field, opening[field]]))) : "";
+    const popupKey = action === "create" ? `${name}-new${place}` : `${name}-edit-${key}`;
+    const open = openForms.get(popupKey);
+    if (open && (open.form.isChanged() || (action === "edit" && open.place === place))) {
+        bringBack(open.handle);
+        if (open.place !== place)
+            toast.info(`${label ?? capitalize(subject)} is already being edited`, "Its form is open with changes: save or discard them first.");
+        return;
+    }
+    if (action === "create") {
+        for (const [other, entry] of openForms)
+            if (other !== popupKey && entry.name === name && entry.action === "create" && !entry.form.isChanged())
+                entry.handle.close("replaced");
+    }
+    const given = await crudInputsFor(request.inputs, action, row);
+    const inputs = locked ? lockInputs(given, locked, opening, request.known) : given;
+    // The inputs lockInputs fixed - a copy each - are out of reach of the form's own rules too.
+    const onFieldChange = lockedFieldChange(options.onFieldChange, inputs.filter((params, index) => params !== given[index]).map(params => params.name));
+    const form = new FormStore();
+    const loader = options.load;
+    const id = row ? readPath(row, rowKey) : undefined;
+    const loadValue = action === "edit" && row && loader && loader !== "row"
+        ? loader === "details"
+            ? api.details
+                ? (signal) => browserApi.get(api.details, { params: { id, [rowKey]: id }, signal, toast: false }).then(answer => ({ ...row, ...unwrapApiResult(answer) }))
+                : undefined
+            : (signal) => loader(row, signal).then(full => ({ ...row, ...full }))
+        : undefined;
+    const handle = openPopup({
+        key: popupKey,
+        // One still open under this key was untouched, or opened for another place: a fresh form takes its place.
+        reopen: "replace",
+        title: action === "create" ? `Add ${subject}` : `Edit ${subject}`,
+        description: label,
+        icon: _jsx(InlineIcon, { icon: action === "create" ? iconPlus : iconPencil }),
+        size: options.size ?? (inputs.length > 8 ? "lg" : "md"),
+        closeOnBackdrop: false,
+        // A CRUD page's Add and Edit are the popups that can be put aside on the dock; a page's rule for the key may say no.
+        minimizable: popupRuleFor(popupKey)?.minimizable ?? true,
+        beforeClose: async () => {
+            const discard = await confirmDiscard(form);
+            if (discard)
+                form.dropDraft();
+            return discard;
+        },
+        content: popup => (_jsx(CrudFormBody, { aside: typeof options.aside === "function" ? options.aside({ form, action, row }) : options.aside, children: _jsx(ApiForm, { form: form, inputs: inputs, buttons: false, defaultValue: (action === "create" ? opening : (row ?? undefined)), loadValue: loadValue, api: endpoint, transform: options.transform ? formValues => options.transform(formValues, { action, row }) : undefined, confirm: options.confirm, validate: options.validate, onFieldChange: onFieldChange, design: options.design, draftKey: options.draftKey ? `${options.draftKey}:${name}:${action === "create" ? "new" : key}${place}` : undefined, "aria-label": action === "create" ? `Add ${subject}` : `Edit ${label}`, onSuccess: (result, saved) => {
+                    onSaved(result, saved, joinedLookup(inputs, form));
+                    popup.close();
+                } }) })),
+        footer: popup => _jsx(FormButtons, { form: form, submitLabel: action === "create" ? `Add ${subject}` : "Save", onCancel: () => popup.close() }),
+    });
+    const entry = { name, action, handle, form: form, place };
+    openForms.set(popupKey, entry);
+    void handle.closed.then(() => {
+        if (openForms.get(popupKey) === entry)
+            openForms.delete(popupKey);
+    });
+}
+/**
+ * Calls the endpoint of a built-in action on one record - asking first for those that move it between the lists - with
+ * the record's key in the path and its name in the messages. A flag carries the way it goes (`markOn`). `null` when the
+ * controller has no such endpoint or the question was answered No.
+ */
+export async function sendCrudRowAction(api, action, row, options) {
+    const endpoint = crudRowEndpoint(api, action);
+    if (!endpoint)
+        return null;
+    const rowKey = options.rowKey ?? "id";
+    const key = readPath(row, rowKey);
+    const call = {
+        params: { id: key, [rowKey]: key },
+        subject: options.label,
+        action: crudMessageAction(action, options.markOn),
+        ...(options.markOn !== undefined ? options.backend.flagRequest(options.markOn) : {}),
+    };
+    return CRUD_ASKED.has(action) ? browserApi.confirm(endpoint, call) : browserApi.send(endpoint, call);
+}

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/CrudNarrowPicker.d.ts

@@ -0,0 +1,31 @@
+import { type ReactNode } from "react";
+import type { CrudNarrow, CrudNarrowPicker } from "../../Interfaces/CrudInterfaces.ts";
+/** What a narrowed list says while nothing is picked, and on its Add: the box's reason, read with it. */
+export interface CrudNarrowPickerWords {
+    empty: string;
+    add: string;
+}
+/** The narrowing a `narrowPicker` gives its CRUD, the parts it draws, and what the CRUD's Add and list do with it. */
+export interface CrudNarrowPickerParts {
+    /** The CRUD's `narrow`, the picked record in it; nothing without a `narrowPicker`. */
+    narrow: CrudNarrow | undefined;
+    /** The box, for the toolbar. */
+    box: ReactNode;
+    /** The list's button to the box, for its empty message while the box asks for a pick; null otherwise. */
+    pickButton: ReactNode;
+    /** The box is settling as the page opens (a kept pick looked up, its records counted for a lone one): the list waits. */
+    waiting: boolean;
+    /** Nothing is picked and the box has settled: it asks for a pick. */
+    wanted: boolean;
+    /**
+     * Add pressed with nothing picked: the cursor goes to the box, the box is nudged (still, with reduced motion) and a
+     * screen reader hears Add's reason with it. False while the box cannot take it (settling, or not drawn).
+     */
+    askForAdd: () => boolean;
+}
+/**
+ * The narrowing a `narrowPicker` gives its CRUD, and the box it draws in the toolbar. Without one: nothing, and the
+ * CRUD's own `narrow` stands. `words` are the list's: the box's reason while it asks for a pick, and Add's after a press
+ * (default: the box's own words for "records").
+ */
+export declare function useCrudNarrowPicker(options: CrudNarrowPicker | undefined, words?: CrudNarrowPickerWords): CrudNarrowPickerParts;