nexus-shared 3.2.0 → 4.0.0

package/dist/Helpers/CrudBackend.js

@@ -1,4 +1,5 @@
 import { CRUD_MARK_BITS, hasMark, withMark } from "./CrudHelpers.js";
+import { nowUtcDateTime } from "./DateTimeHelpers.js";
 const NO_AUDIT_WORDS = { commands: {}, directions: {}, parts: {} };
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 export class CrudBackend {
@@ -117,13 +118,26 @@ export class CrudBackend {
     }
     /**
      * The key an answer gives in place of the record: `Create` answering the new record's id. `null` when the answer
-     * is the record itself, or says nothing. With a key the new record goes straight into the list, and where there is
-     * a `details` endpoint it is read back on its own - one small request, never the whole list again.
+     * is the record itself, or says nothing. With a key the new record goes straight into the list, finished by `savedRow`;
+     * only a record whose list still cannot be told is read back on its own through `details` - never the whole list again.
      */
     answeredKey(result) {
         void result;
         return null;
     }
+    /**
+     * A record a save wrote - what the form sent, under what the answer said - with the fields only the server keeps
+     * filled in as this backend writes them, so nothing has to be read back: a status, the times, the marks. `before` is
+     * the record as the page holds it now (an edit; `undefined` for a new one): an edit's form carries its own copy of those
+     * fields from when it opened, which a flag or a mark made since has left behind. Default: the record as it is - and a
+     * record whose list still cannot be told from it (`listMembership`) is read back once through `details`, where there is
+     * one.
+     */
+    savedRow(action, record, before) {
+        void action;
+        void before;
+        return record;
+    }
     /**
      * Whether a record belongs in a list, read from the record itself. It is what lets one answer be written into the
      * lists that are **not** on screen: a flagged record joins the flagged list, a trashed one leaves the active list
@@ -328,6 +342,36 @@ export class NexusCrudBackend extends CrudBackend {
     answeredKey(result) {
         return typeof result === "string" && result !== "" ? result : null;
     }
+    /**
+     * What a Nexus save leaves to the server, written as the server writes it, so nothing is read back (the owner,
+     * 2026-10-10: "the creationTime, recordStatus we will provide fake or just right now"). A new record lacking them is
+     * Active (every Create writes `NEXUS_ACTIVE_STATUS`), has no marks, was added now and never changed; what its answer
+     * said stays. An Update writes none of the status, the marks and the time added, so an edited record has the ones the
+     * page holds (`before`) - over its form's older copies - and was changed now. Times are UTC ISO strings, as a date-time
+     * column reads them.
+     */
+    savedRow(action, record, before) {
+        const row = { ...record };
+        const now = nowUtcDateTime();
+        const fill = (field, value) => {
+            if (value !== undefined && (row[field] === undefined || row[field] === null))
+                row[field] = value;
+        };
+        if (action === "create") {
+            fill("recordStatus", NEXUS_ACTIVE_STATUS);
+            fill("bookmarkTypes", 0);
+            fill("creationTime", now);
+            fill("modificationTime", null);
+            return row;
+        }
+        const held = (before ?? {});
+        for (const field of ["recordStatus", "bookmarkTypes", "creationTime"]) {
+            if (held[field] !== undefined)
+                row[field] = held[field];
+        }
+        row.modificationTime = now;
+        return row;
+    }
     /**
      * The bands the owner settled on: under 40 is live, 25–29 of that is flagged, 40–59 is the trash, and 60 and up is
      * deleted. A row without a `recordStatus` says nothing, and the lists it cannot answer for load again.

package/dist/Helpers/CrudColumns.d.ts

@@ -1,11 +1,22 @@
 import type { ApiEndpoint } from "../Interfaces/ApiInterfaces.ts";
-import type { InputParams } from "../Interfaces/FormInterfaces.ts";
+import { type InputParams } from "../Interfaces/FormInterfaces.ts";
 import type { TableColumn, TableJoin, TableRow } from "../Interfaces/TableInterfaces.ts";
 import { type CrudBackend } from "./CrudBackend.ts";
+import { type PriceLadderOptions } from "./NumberHelpers.ts";
 /** The longest description a record keeps: the owner's rule for every model (the column holds 4000). */
 export declare const CRUD_DESCRIPTION_MAX = 1000;
+/**
+ * The fields a record keeps its price's figures in (`crudInputs.netAmount`, `crudColumns.amounts`). Defaults: `price`,
+ * `discountPercentage` and `vatPercentage`, and no quantity (one of it).
+ */
+export type PriceKeys = {
+    price?: string;
+    quantity?: string;
+    discount?: string;
+    vat?: string;
+};
 export declare const crudColumns: {
-    /** The record's status in words ("Active", "Flagged", "Trashed"), from the backend's own numbers; blank until a new record is read back. */
+    /** The record's status in words ("Active", "Flagged", "Trashed"), from the backend's own numbers; blank for a record that says none. */
     status<TRow extends TableRow>(changes?: Partial<TableColumn<TRow>>, backend?: CrudBackend): TableColumn<TRow>;
     /** The description, as Markdown: text in the table, formatted in the details. */
     description<TRow extends TableRow>(changes?: Partial<TableColumn<TRow>>): TableColumn<TRow>;
@@ -16,11 +27,14 @@ export declare const crudColumns: {
     /**
      * Another record's name the **database** joined into the row: the row carries the name (`key`) and that record's own
      * status (`status`), and the cell shows the name with a short tag when the record is no longer available ("Trashed",
-     * "Deleted": `CrudBackend.unavailableTag`). One call, nothing looked up.
+     * "Deleted": `CrudBackend.unavailableTag`). One call, nothing looked up. Give it `from` - the field holding that
+     * record's key, an input of the form: a save answers what was sent, not the names the database joins, so a CRUD names
+     * it again from the record picked for the key, with no call (`crudJoinedNames`). Without `from` a CRUD reads a new
+     * record back once (`details`) to name it.
      *
-     * @example crudColumns.dbJoin({ key: "regionName", label: "Region", status: "regionRecordStatus" })
+     * @example crudColumns.dbJoin({ key: "regionName", label: "Region", status: "regionRecordStatus", from: "regionId" })
      */
-    dbJoin<TRow extends TableRow>({ status, ...column }: DbJoinColumn<TRow>, backend?: CrudBackend): TableColumn<TRow>;
+    dbJoin<TRow extends TableRow>({ status, from, ...column }: DbJoinColumn<TRow>, backend?: CrudBackend): TableColumn<TRow>;
     /**
      * Another record's name the **table** joins: the row carries only that record's key (`from`), and the table names it
      * from the other controller's `findListing` - every key the rows hold in one call, kept for every table and form on the
@@ -30,10 +44,33 @@ export declare const crudColumns: {
      * @example crudColumns.clientJoin(SUB_REGIONS, { key: "subRegionName", label: "Sub-region", from: "subRegionId" })
      */
     clientJoin<TRow extends TableRow>(api: JoinController, { from, field, ...column }: ClientJoinColumn<TRow>, backend?: CrudBackend): TableColumn<TRow>;
+    /**
+     * A price's figures under one band, "Amount details" (2026-06-20's): **Price** (money), **Discount** and **VAT**
+     * (percents), and the **Calculated amount** - the price less the discount, plus VAT on the rest, worked out from the
+     * row's own figures by the server's rule (`priceAmounts`), so a row a save just answered shows it at once. A page
+     * spreads them where its price columns go: `...crudColumns.amounts()`. The Calculated amount's key is `netAmount`.
+     *
+     * @example const COLUMNS = [crudColumns.dbJoin({ ... }), ...crudColumns.amounts(), crudColumns.status()];
+     */
+    amounts<TRow extends TableRow>(keys?: PriceKeys, changes?: {
+        group?: string;
+    }): TableColumn<TRow>[];
+    /**
+     * A receipt's money ladder as columns for a record's details (`CrudDetails`), in one section (`group`, default
+     * "Money"): Rate, Amount, Discount (5%), VAT (13%) - each left out when it is none - and the Calculated amount, money
+     * with 2 places, each read from the row's own field (`priceLadder`, on the server's `CounterAmounts` names unless
+     * `keys` says otherwise). Pass the person's number locale, so the percentages are written as they read numbers.
+     *
+     * @example ...crudColumns.priceLadder(line, { locale: useNumberLocale() })
+     */
+    priceLadder<TRow extends TableRow>(row: Readonly<Record<string, unknown>>, options?: PriceLadderOptions & {
+        group?: string;
+    }): TableColumn<TRow>[];
 };
-/** What `crudColumns.dbJoin` takes: a column, and the row's field that holds the joined record's status. */
+/** What `crudColumns.dbJoin` takes: a column, the row's field that holds the joined record's status, and the one with its key. */
 export type DbJoinColumn<TRow extends TableRow> = Partial<TableColumn<TRow>> & Pick<TableColumn<TRow>, "key" | "label"> & {
     status: string;
+    from?: string;
 };
 /** What `crudColumns.clientJoin` takes: a column, the row's field that holds the other record's key, and its own field. */
 export type ClientJoinColumn<TRow extends TableRow> = Partial<TableColumn<TRow>> & Pick<TableColumn<TRow>, "key" | "label"> & Pick<TableJoin, "from" | "field">;
@@ -48,4 +85,14 @@ export declare const crudInputs: {
      * in a form, such as `span`.
      */
     description(changes?: Partial<InputParams>): InputParams;
+    /**
+     * The **Calculated amount** in a price's form: a box after Price, Discount and VAT that follows them as they are typed
+     * (`compute`), by the server's rule (`priceAmounts`) - never typed, never sent, never a change. Blank while the price
+     * is empty, so a cleared price never reads 0.00. Span 3, so Price | Discount | VAT | Calculated amount fill a row (two
+     * pairs on a narrow form). `changes` may replace any key, `compute` included: a counter's box shows the server's
+     * preview instead (`compute: { from: [], value: (_values, line) => line?.netAmount }` with the form's `computeWith`).
+     *
+     * @example INPUTS = [..., price, discountPercentage, vatPercentage, crudInputs.netAmount()]
+     */
+    netAmount(keys?: PriceKeys, changes?: Partial<InputParams>): InputParams;
 };

package/dist/Helpers/CrudColumns.js

@@ -1,15 +1,50 @@
+import { EInputTypes } from "../Interfaces/FormInterfaces.js";
 import { getCrudBackend } from "./CrudBackend.js";
+import { priceAmounts, priceLadder } from "./NumberHelpers.js";
 import { readPath } from "./TableHelpers.js";
 /*
  * The columns and inputs every Nexus record has, so a page names them instead of writing them again: its status in
  * words, its Markdown description, and when it was added and changed - and the two ways a page shows another record's
  * name, joined by the database (`dbJoin`) or by the table (`clientJoin`). Each takes changes over its defaults, as a
- * column or an input of the page's own would: `crudColumns.added({ hidden: false })`.
+ * column or an input of the page's own would: `crudColumns.added({ hidden: false })`. A record with a price has its
+ * money the same way: its figures and the Calculated amount (`amounts`, `netAmount`), and a receipt's ladder
+ * (`priceLadder`), each in one wording for every page.
  */
 /** The longest description a record keeps: the owner's rule for every model (the column holds 4000). */
 export const CRUD_DESCRIPTION_MAX = 1000;
+/** The words of the worked-out figure, wherever it is a label: the owner's "calculate value", 2026-06-20's "Calculated Amount". */
+const NET_AMOUNT_LABEL = "Calculated amount";
+/** The price's fields, with the defaults. */
+function priceKeysOf(keys = {}) {
+    return { price: keys.price ?? "price", quantity: keys.quantity, discount: keys.discount ?? "discountPercentage", vat: keys.vat ?? "vatPercentage" };
+}
+/** A figure among a record's (or a form's) values: a number, or the text of one; anything else is missing. */
+function figureAt(values, key) {
+    if (key === undefined)
+        return null;
+    const value = readPath(values, key);
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === "string" && value.trim() !== "") {
+        const number = Number(value);
+        return Number.isFinite(number) ? number : null;
+    }
+    return null;
+}
+/** The Calculated amount of a record's (or a form's) values by the server's rule (`priceAmounts`); null while the price is empty. */
+function netAmountAt(values, keys) {
+    const price = readPath(values, keys.price);
+    if (price === null || price === undefined || price === "")
+        return null;
+    return priceAmounts({
+        price: figureAt(values, keys.price),
+        quantity: keys.quantity === undefined ? 1 : figureAt(values, keys.quantity),
+        discountPercentage: figureAt(values, keys.discount),
+        vatPercentage: figureAt(values, keys.vat),
+    }).netAmount;
+}
 export const crudColumns = {
-    /** The record's status in words ("Active", "Flagged", "Trashed"), from the backend's own numbers; blank until a new record is read back. */
+    /** The record's status in words ("Active", "Flagged", "Trashed"), from the backend's own numbers; blank for a record that says none. */
     status(changes = {}, backend) {
         return {
             key: "recordStatus",
@@ -34,12 +69,15 @@ export const crudColumns = {
     /**
      * Another record's name the **database** joined into the row: the row carries the name (`key`) and that record's own
      * status (`status`), and the cell shows the name with a short tag when the record is no longer available ("Trashed",
-     * "Deleted": `CrudBackend.unavailableTag`). One call, nothing looked up.
+     * "Deleted": `CrudBackend.unavailableTag`). One call, nothing looked up. Give it `from` - the field holding that
+     * record's key, an input of the form: a save answers what was sent, not the names the database joins, so a CRUD names
+     * it again from the record picked for the key, with no call (`crudJoinedNames`). Without `from` a CRUD reads a new
+     * record back once (`details`) to name it.
      *
-     * @example crudColumns.dbJoin({ key: "regionName", label: "Region", status: "regionRecordStatus" })
+     * @example crudColumns.dbJoin({ key: "regionName", label: "Region", status: "regionRecordStatus", from: "regionId" })
      */
-    dbJoin({ status, ...column }, backend) {
-        return { tag: row => (backend ?? getCrudBackend()).unavailableTag(readPath(row, status)), ...column };
+    dbJoin({ status, from, ...column }, backend) {
+        return { tag: row => (backend ?? getCrudBackend()).unavailableTag(readPath(row, status)), ...column, dbJoin: from ? { from, status } : { status } };
     },
     /**
      * Another record's name the **table** joins: the row carries only that record's key (`from`), and the table names it
@@ -56,6 +94,36 @@ export const crudColumns = {
             ...column,
         };
     },
+    /**
+     * A price's figures under one band, "Amount details" (2026-06-20's): **Price** (money), **Discount** and **VAT**
+     * (percents), and the **Calculated amount** - the price less the discount, plus VAT on the rest, worked out from the
+     * row's own figures by the server's rule (`priceAmounts`), so a row a save just answered shows it at once. A page
+     * spreads them where its price columns go: `...crudColumns.amounts()`. The Calculated amount's key is `netAmount`.
+     *
+     * @example const COLUMNS = [crudColumns.dbJoin({ ... }), ...crudColumns.amounts(), crudColumns.status()];
+     */
+    amounts(keys, changes = {}) {
+        const k = priceKeysOf(keys);
+        const group = changes.group ?? "Amount details";
+        return [
+            { key: k.price, label: "Price", format: "money", decimals: 2, width: "8rem", group },
+            { key: k.discount, label: "Discount", format: "percent", decimals: 2, width: "7rem", group },
+            { key: k.vat, label: "VAT", format: "percent", decimals: 2, width: "6rem", group },
+            { key: "netAmount", label: NET_AMOUNT_LABEL, format: "money", decimals: 2, width: "9rem", group, value: row => netAmountAt(row, k) },
+        ];
+    },
+    /**
+     * A receipt's money ladder as columns for a record's details (`CrudDetails`), in one section (`group`, default
+     * "Money"): Rate, Amount, Discount (5%), VAT (13%) - each left out when it is none - and the Calculated amount, money
+     * with 2 places, each read from the row's own field (`priceLadder`, on the server's `CounterAmounts` names unless
+     * `keys` says otherwise). Pass the person's number locale, so the percentages are written as they read numbers.
+     *
+     * @example ...crudColumns.priceLadder(line, { locale: useNumberLocale() })
+     */
+    priceLadder(row, options = {}) {
+        const { group = "Money", ...ladder } = options;
+        return priceLadder(row, ladder).map(line => ({ key: line.key, label: line.label, format: "money", decimals: 2, group }));
+    },
 };
 export const crudInputs = {
     /**
@@ -64,6 +132,29 @@ export const crudInputs = {
      * in a form, such as `span`.
      */
     description(changes = {}) {
-        return { type: "markdown", name: "description", label: "Description", maxLength: CRUD_DESCRIPTION_MAX, height: 160, hint: "Anything worth knowing about it. Markdown.", span: 12, ...changes };
+        return { type: EInputTypes.Markdown, name: "description", label: "Description", maxLength: CRUD_DESCRIPTION_MAX, height: 160, hint: "Anything worth knowing about it. Markdown.", span: 12, ...changes };
+    },
+    /**
+     * The **Calculated amount** in a price's form: a box after Price, Discount and VAT that follows them as they are typed
+     * (`compute`), by the server's rule (`priceAmounts`) - never typed, never sent, never a change. Blank while the price
+     * is empty, so a cleared price never reads 0.00. Span 3, so Price | Discount | VAT | Calculated amount fill a row (two
+     * pairs on a narrow form). `changes` may replace any key, `compute` included: a counter's box shows the server's
+     * preview instead (`compute: { from: [], value: (_values, line) => line?.netAmount }` with the form's `computeWith`).
+     *
+     * @example INPUTS = [..., price, discountPercentage, vatPercentage, crudInputs.netAmount()]
+     */
+    netAmount(keys, changes = {}) {
+        const k = priceKeysOf(keys);
+        const from = [k.price, k.quantity, k.discount, k.vat].filter((key) => key !== undefined);
+        return {
+            type: EInputTypes.Number,
+            name: "netAmount",
+            label: NET_AMOUNT_LABEL,
+            decimals: 2,
+            span: 3,
+            hint: "Price less the discount, plus VAT on the rest.",
+            compute: { from, value: values => netAmountAt(values, k) },
+            ...changes,
+        };
     },
 };

package/dist/Helpers/CrudDetailsTabs.d.ts

@@ -0,0 +1,58 @@
+import type { ApiEndpoint } from "../Interfaces/ApiInterfaces.ts";
+import type { CrudDetailsPicture, CrudDetailsProfile, CrudDetailsTab } from "../Interfaces/CrudInterfaces.ts";
+import type { FormValues } from "../Interfaces/FormInterfaces.ts";
+import type { TableColumn } from "../Interfaces/TableInterfaces.ts";
+/** The built-in tab: the record's fields, with the details' `aside` beside them. */
+export declare const CRUD_DETAILS_TAB = "details";
+/** A tab as offered: its label settled and its badge worked out for the record. */
+export interface OfferedCrudTab<TRow extends FormValues = FormValues> extends CrudDetailsTab<TRow> {
+    label: string;
+    /** Whether it is the built-in fields (a `details` entry without a `render`). */
+    builtIn: boolean;
+}
+/**
+ * The tabs offered for a record, in the page's order: the built-in `details` first unless the page lists it, each tab
+ * whose `endpoint` the person may not call left out (`can`, the rule every action follows), and each the page hides
+ * for this record. A tab id listed twice is offered once, where it is first listed.
+ */
+export declare function offeredCrudTabs<TRow extends FormValues>(tabs: readonly CrudDetailsTab<TRow>[] | undefined, row: TRow, can: (endpoint: ApiEndpoint) => boolean): OfferedCrudTab<TRow>[];
+/** The tab a popup opens on: the one asked for, else the one kept, while offered; otherwise the first. */
+export declare function openingCrudTab(offered: readonly {
+    id: string;
+}[], ...wanted: (string | null | undefined)[]): string | undefined;
+/** Where this browser keeps the last tab: `nx-crud-tab:{key}:{viewer}`; nothing without a viewer. */
+export declare function crudTabStorageKey(remember: {
+    key: string;
+    viewer?: string | null;
+} | undefined): string | null;
+/** The kept tab's id, or null. */
+export declare function readCrudTab(storage: Pick<Storage, "getItem"> | null, key: string | null): string | null;
+/** Keeps the tab's id; a browser that will not keep it (storage off, full) is left as it is. */
+export declare function writeCrudTab(storage: Pick<Storage, "setItem"> | null, key: string | null, tab: string): void;
+/** Whether a profile is given as its parts (a `title`), rather than drawn by the page. */
+export declare function isCrudProfile<TRow extends FormValues = FormValues>(value: unknown): value is CrudDetailsProfile<TRow>;
+/** How a details popup's full record (its details endpoint) is coming along: being read, read, or not read (it failed). */
+export type CrudRecordRead = "loading" | "done" | "failed";
+/**
+ * Whether a field waits on the full record: it is still being read (or its read failed) and the row has no value under
+ * the field's key at all - the list left it out. A column that draws or works out its own value (`render`, `value`)
+ * never waits: only it knows what it reads. The Details tab and the profile draw such a field blank while it is read,
+ * and "Not loaded" when the read failed.
+ */
+export declare function isAwaitedCrudField<TRow extends FormValues>(column: TableColumn<TRow>, row: TRow, read: CrudRecordRead): boolean;
+/**
+ * The fields a record's profile shows (`CrudDetailsProfile.fields`), in the page's order: a column given whole, or the
+ * details' column of the key given (a key no column has is left out); a key named twice is shown once, where first
+ * named; and a field with no value for the record - its own `value`, a join's or the field's: null, undefined, blank
+ * text, an empty list, NaN - is left out. `false` and `0` are values. A field the row lacks while the full record is
+ * read, or after its read failed (`isAwaitedCrudField`), is kept: the profile holds its line, then says "Not loaded".
+ */
+export declare function crudProfileFields<TRow extends FormValues>(fields: readonly (TableColumn<TRow> | string)[] | undefined, columns: readonly TableColumn<TRow>[], row: TRow, read?: CrudRecordRead): TableColumn<TRow>[];
+/**
+ * The details' columns less every key a profile's `fields` names, so the Details tab never shows a field the profile
+ * does. A key the profile leaves out for having no value stays out of the Details too: it has nothing to show there. A
+ * field still being read, or whose read failed, is in the profile (`crudProfileFields`), held or "Not loaded".
+ */
+export declare function crudDetailsWithoutProfile<TRow extends FormValues>(columns: readonly TableColumn<TRow>[], fields: readonly (TableColumn<TRow> | string)[] | undefined): readonly TableColumn<TRow>[];
+/** Whether a profile's picture is given by the owner's Drive params, rather than drawn by the page. */
+export declare function isCrudPicture(value: unknown): value is CrudDetailsPicture;

package/dist/Helpers/CrudDetailsTabs.js

@@ -0,0 +1,126 @@
+import { isEmptyValue } from "./InputConditions.js";
+import { columnValue, readPath } from "./TableHelpers.js";
+/*
+ * The rules of a details popup's tabs (`CrudDetailsOptions.tabs`), apart from drawing them, so they are tested without
+ * a browser: which tabs a person is offered for a record, which one opens, and where this browser keeps the last one;
+ * and which fields its profile shows (`profile.fields`), which the Details tab then leaves out.
+ */
+/** The built-in tab: the record's fields, with the details' `aside` beside them. */
+export const CRUD_DETAILS_TAB = "details";
+/**
+ * The tabs offered for a record, in the page's order: the built-in `details` first unless the page lists it, each tab
+ * whose `endpoint` the person may not call left out (`can`, the rule every action follows), and each the page hides
+ * for this record. A tab id listed twice is offered once, where it is first listed.
+ */
+export function offeredCrudTabs(tabs, row, can) {
+    const listed = tabs ?? [];
+    const all = listed.some(tab => tab.id === CRUD_DETAILS_TAB) ? listed : [{ id: CRUD_DETAILS_TAB }, ...listed];
+    const seen = new Set();
+    const offered = [];
+    for (const tab of all) {
+        if (seen.has(tab.id))
+            continue;
+        seen.add(tab.id);
+        if (tab.endpoint && !can(tab.endpoint))
+            continue;
+        if (tab.hidden?.(row))
+            continue;
+        const builtIn = tab.id === CRUD_DETAILS_TAB && !tab.render;
+        offered.push({ ...tab, label: tab.label ?? (tab.id === CRUD_DETAILS_TAB ? "Details" : tab.id), builtIn });
+    }
+    return offered;
+}
+/** The tab a popup opens on: the one asked for, else the one kept, while offered; otherwise the first. */
+export function openingCrudTab(offered, ...wanted) {
+    for (const id of wanted)
+        if (id && offered.some(tab => tab.id === id))
+            return id;
+    return offered[0]?.id;
+}
+/** Where this browser keeps the last tab: `nx-crud-tab:{key}:{viewer}`; nothing without a viewer. */
+export function crudTabStorageKey(remember) {
+    const viewer = remember?.viewer?.trim();
+    return remember?.key && viewer ? `nx-crud-tab:${remember.key}:${viewer}` : null;
+}
+/** The kept tab's id, or null. */
+export function readCrudTab(storage, key) {
+    if (!storage || !key)
+        return null;
+    try {
+        const kept = storage.getItem(key);
+        return kept ? kept : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Keeps the tab's id; a browser that will not keep it (storage off, full) is left as it is. */
+export function writeCrudTab(storage, key, tab) {
+    if (!storage || !key)
+        return;
+    try {
+        storage.setItem(key, tab);
+    }
+    catch {
+        // Not kept: the popup opens on the first tab next time.
+    }
+}
+/** Whether a profile is given as its parts (a `title`), rather than drawn by the page. */
+export function isCrudProfile(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && "title" in value && !("$$typeof" in value);
+}
+/** The key a profile's field names: a column's own, or the key given. */
+const profileFieldKey = (field) => (typeof field === "string" ? field : field.key);
+/**
+ * Whether a field waits on the full record: it is still being read (or its read failed) and the row has no value under
+ * the field's key at all - the list left it out. A column that draws or works out its own value (`render`, `value`)
+ * never waits: only it knows what it reads. The Details tab and the profile draw such a field blank while it is read,
+ * and "Not loaded" when the read failed.
+ */
+export function isAwaitedCrudField(column, row, read) {
+    return read !== "done" && !column.render && !column.value && readPath(row, column.key) === undefined;
+}
+/**
+ * The fields a record's profile shows (`CrudDetailsProfile.fields`), in the page's order: a column given whole, or the
+ * details' column of the key given (a key no column has is left out); a key named twice is shown once, where first
+ * named; and a field with no value for the record - its own `value`, a join's or the field's: null, undefined, blank
+ * text, an empty list, NaN - is left out. `false` and `0` are values. A field the row lacks while the full record is
+ * read, or after its read failed (`isAwaitedCrudField`), is kept: the profile holds its line, then says "Not loaded".
+ */
+export function crudProfileFields(fields, columns, row, read = "done") {
+    const seen = new Set();
+    const shown = [];
+    for (const field of fields ?? []) {
+        const key = profileFieldKey(field);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const column = typeof field === "string" ? columns.find(one => one.key === field) : field;
+        if (!column)
+            continue;
+        if (isAwaitedCrudField(column, row, read)) {
+            shown.push(column);
+            continue;
+        }
+        const value = columnValue(column, row);
+        if (isEmptyValue(value) || (typeof value === "number" && Number.isNaN(value)))
+            continue;
+        shown.push(column);
+    }
+    return shown;
+}
+/**
+ * The details' columns less every key a profile's `fields` names, so the Details tab never shows a field the profile
+ * does. A key the profile leaves out for having no value stays out of the Details too: it has nothing to show there. A
+ * field still being read, or whose read failed, is in the profile (`crudProfileFields`), held or "Not loaded".
+ */
+export function crudDetailsWithoutProfile(columns, fields) {
+    if (!fields?.length)
+        return columns;
+    const taken = new Set(fields.map(profileFieldKey));
+    return columns.filter(column => !taken.has(column.key));
+}
+/** Whether a profile's picture is given by the owner's Drive params, rather than drawn by the page. */
+export function isCrudPicture(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && "category" in value && "ownerId" in value && !("$$typeof" in value);
+}

package/dist/Helpers/CrudHelpers.d.ts

@@ -1,7 +1,10 @@
 import type { ApiEndpoint } from "../Interfaces/ApiInterfaces.ts";
-import type { CrudActionName, CrudEndpoints, CrudMark, CrudMassActionName, CrudMode, CrudRowActionName } from "../Interfaces/CrudInterfaces.ts";
+import type { CrudActionName, CrudChange, CrudEndpoints, CrudMark, CrudMassActionName, CrudMode, CrudNarrow, CrudRowActionName, CrudTreePlacement } from "../Interfaces/CrudInterfaces.ts";
+import type { FormValues } from "../Interfaces/FormInterfaces.ts";
+import type { CrudBackend } from "./CrudBackend.ts";
+import type { TreeItemChange } from "./TreeStore.ts";
 import type { MessageActionName } from "../Interfaces/MessageInterfaces.ts";
-import type { TablePage, TablePaging, TableRow } from "../Interfaces/TableInterfaces.ts";
+import type { TableColumn, TablePage, TablePaging, TableRow } from "../Interfaces/TableInterfaces.ts";
 /** Every list, in the order the CRUD shows them. */
 export declare const CRUD_MODES: readonly CrudMode[];
 /** The built-in actions on one record, per list, in their menu order. A record's history is on every list. */
@@ -40,6 +43,82 @@ export declare function massActionAllowed(action: CrudMassActionName, api: CrudE
  * the list it is in. `markOn` is the record's new flag.
  */
 export declare function leavesList(action: CrudRowActionName | CrudMassActionName, mode: CrudMode, markOn?: boolean): boolean;
+/**
+ * A CRUD change as changes to a tree that shows the same records (`CrudTreePlacement`): a record in the active list is
+ * put under its parent - added, changed or moved - and one out of it (in the trash, deleted) leaves the tree. Where it
+ * was comes from `before`: under its parent while it was active, out of the tree when it was not or is new, and not
+ * known otherwise (the tree then looks for it). A record without a status counts as active. Pins and favourites are a
+ * user's own and change no tree.
+ */
+export declare function crudTreeChanges<TRow extends FormValues, TItem extends object>(change: CrudChange<TRow>, place: CrudTreePlacement<TRow, TItem>, backend: CrudBackend): TreeItemChange<TItem>[];
+/**
+ * The records whose child count a change moved, among `rows` (a list's rows), through a tree placement: what the tree's
+ * parents follow (`crudTreeChanges`) written into the parents' own rows. A record added or back under a parent counts one
+ * more there; one moved counts one fewer where it was and one more where it went; one trashed or deleted one fewer. Each
+ * parent row comes back with what `recordOf` reads from its item with the count moved written over it (so `recordOf`
+ * must carry the item's count back into the record); a row whose count did not move, or a count that is not a number, is
+ * left out.
+ */
+export declare function crudParentCounts<TRow extends FormValues, TItem extends object>(treeChanges: readonly TreeItemChange<TItem>[], rows: readonly TRow[], place: CrudTreePlacement<TRow, TItem>): TRow[];
+/**
+ * A saved record with the child count a tree placement keeps for it (`rules.hasChildrenKey`): a new record's own, as
+ * `itemOf` gives it (none yet), and an edited one's from the row the page holds (`held`) - its form's copy is as old as
+ * the form, and a child added since counts. Written over the record through `recordOf`, which carries an item's count
+ * back; a placement without a count leaves the record as it is.
+ */
+export declare function crudSavedCount<TRow extends FormValues, TItem extends object>(record: TRow, held: TRow | undefined, place: CrudTreePlacement<TRow, TItem>): TRow;
+/** What a save knows of the record a joined key names (`crudJoinedNames`): its name, and its status when it says. */
+export interface CrudJoinedRecord {
+    name: unknown;
+    status?: unknown;
+}
+/**
+ * The names the database joins into a record (`crudColumns.dbJoin` columns with `from`), written again after a save that
+ * answered only what was sent - with no call. For each such column: a key the save kept as `before` had it keeps
+ * `before`'s name and status; an emptied key empties both; a new or changed key takes the name and the status of the
+ * record `find(from, key)` gives - the one picked in the form, or one the page holds. Where it gives none, a new record
+ * keeps the name its save answered, if any, and an edited one drops the old record's name and status rather than show
+ * them for the new key: either way the record is then read back once (`crudJoinsMissing`). Names and statuses are written
+ * as top-level fields of the record.
+ */
+export declare function crudJoinedNames<TRow extends TableRow>(record: TRow, before: TRow | undefined, columns: readonly TableColumn<TRow>[], find: (from: string, key: string) => CrudJoinedRecord | null | undefined): TRow;
+/**
+ * Whether a saved record still lacks a name the database joins into it, which is the one case a CRUD reads it back
+ * (`details`, once): a `crudColumns.dbJoin` column whose name the record does not hold while its key is set - no record
+ * was known for a new key (`crudJoinedNames`) - or one that names no key field (`from`) on a new record, whose save
+ * answered no name. An edited record keeps the name it had on a column without `from`: whether its key changed cannot
+ * be told.
+ */
+export declare function crudJoinsMissing<TRow extends TableRow>(record: TRow, before: TRow | undefined, columns: readonly TableColumn<TRow>[]): boolean;
+/**
+ * Where an Add or Edit form with fixed fields stands, as text for its popup's key and its draft's: the fixed fields'
+ * names and values, in name order (`"@countryId=7&parentId="`), or "" when nothing is fixed. So a form opened inside one
+ * parent never comes back inside another, a fixed form never stands in for a free one, and a draft written before the
+ * record moved is not brought back over its new place.
+ */
+export declare function crudFormPlace(fixed: Readonly<Record<string, unknown>> | null | undefined): string;
+/** What a narrowed list shows and fixes, read once from its `narrow`. */
+export interface CrudNarrowing {
+    /** The field of the list's records that names the picked record. */
+    key: string;
+    /** The picked record's value as text, which a record's field must equal; `null` while none is picked: the list is empty. */
+    value: string | null;
+    /** The same value as the picked record holds it (a number stays a number): what a new record and a server's filter get. */
+    raw: unknown;
+    /** The picked record's name: its `labelKey` field, else the value. */
+    label: string;
+}
+/**
+ * A `Crud` `narrow` read once: the field, the picked record's value (its `valueKey` field, else its `key` field) and its
+ * name (its `labelKey` field, else the value). `null` without a narrowing; a value of `null` while nothing is picked, or
+ * the picked record holds no value.
+ */
+export declare function crudNarrowing(narrow: CrudNarrow | null | undefined): CrudNarrowing | null;
+/**
+ * Whether a record belongs in a narrowed list: its field holds the picked record's value (compared as text, so 7 and "7"
+ * are one). Every record does without a narrowing, and none while nothing is picked.
+ */
+export declare function crudInNarrowing(row: TableRow, narrowing: CrudNarrowing | null): boolean;
 /** The message builder's action for a built-in action: "Guest recovered.", "Unpin 3 guests?" */
 export declare function crudMessageAction(action: CrudRowActionName | CrudMassActionName, markOn?: boolean): MessageActionName;
 /** What every CRUD follows, whatever module it shows. `configureCrud` changes it once, for the whole app. */