nexus-shared 3.1.0 → 4.0.0

package/dist/Helpers/CrudBackend.js

@@ -1,3 +1,6 @@
+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 {
     /** Reads a whole list: an array, or the rows of a page. */
@@ -6,6 +9,83 @@ export class CrudBackend {
             return result;
         return [...this.readPage(result).rows];
     }
+    /** Whether a record can be flagged or unflagged at all. Default yes. */
+    canFlag(row) {
+        void row;
+        return true;
+    }
+    /**
+     * What flagging one record or many sends beside the key(s): the state wanted, never a toggle. Default the Nexus
+     * backend's `?isFlagged=true`. A backend that toggles ignores it, and a CRUD sends only the records a change is for.
+     */
+    flagRequest(on) {
+        return { query: { isFlagged: on } };
+    }
+    /**
+     * This user's marks on a record as a set of bits (`CRUD_MARK_BITS`: pinned 1, favourite 2), as a bookmark listing
+     * answers them on each record. Bits the package does not know are kept as they are. Default: the pin alone, through
+     * `isPinned`.
+     */
+    marksOf(row) {
+        return this.isPinned(row) ? CRUD_MARK_BITS.pin : 0;
+    }
+    /** The row carrying this set of marks. Default: the pin alone, through `withPin`. */
+    withMarks(row, marks) {
+        return this.withPin(row, hasMark(marks, "pin"));
+    }
+    /**
+     * What setting one record's marks sends beside its key: the **whole set** it is to have, never a toggle. Default the
+     * Nexus backend's: `?bookmarkTypes=3`.
+     */
+    marksRequest(marks) {
+        return { query: { bookmarkTypes: marks } };
+    }
+    /**
+     * What putting one mark on many records, or taking it off, sends: the keys, the mark and which way. Each record keeps
+     * its other marks. Default the Nexus backend's: the keys as the body, `?bookmarkTypes=2&isAdding=true`.
+     */
+    massMarksRequest(keys, mark, on) {
+        return { body: keys, query: { bookmarkTypes: CRUD_MARK_BITS[mark], isAdding: on } };
+    }
+    /** The marks a write left on the record, read from its answer. `null` when it does not say, and the set sent stands. */
+    answeredMarks(result) {
+        void result;
+        return null;
+    }
+    /** What an export sends to name the list on screen, beside the table's own filters. Default nothing. */
+    exportFilters(mode) {
+        void mode;
+        return {};
+    }
+    /** A record status in words, for a status column and the history: "Active", "Flagged", "Trashed". Default the number. */
+    statusText(status) {
+        return String(status);
+    }
+    /**
+     * The short tag a reference to a record carries when that record is no longer available - "Trashed" beside a parent in
+     * the trash, "Deleted" beside one deleted - read from its status. `null` for a live record, and for no status at all.
+     * A joined column (`crudColumns.dbJoin`, `crudColumns.clientJoin`) draws it after the name. Default: none.
+     */
+    unavailableTag(status) {
+        void status;
+        return null;
+    }
+    /**
+     * Whether a record may be picked in a form: what a picker offers, and what it shows tagged and will not offer again when
+     * a form already holds it. Read from the record. Default: every record.
+     */
+    isPickable(record) {
+        void record;
+        return true;
+    }
+    /**
+     * The words of a record's history: what each command did (`commands`), the audit keys that are the whole story of a
+     * switch (`directions`), and the parts of the record an update names (`parts`, with `update` the command that names
+     * one). Numbers an audit row keeps for good, so each backend's own. Default none: "Action 3".
+     */
+    get auditWords() {
+        return NO_AUDIT_WORDS;
+    }
     /**
      * Changes an action's answer makes to rows, by key: a mass flag that answers each record's new status. Rows without
      * an entry take the change the action stands for (a toggled flag). Default: none.
@@ -29,7 +109,7 @@ export class CrudBackend {
      * `null` when it says nothing about it - a bare key, an empty body - and then the caller keeps what it has.
      *
      * **This is what spares a page its reload.** A save or a mark whose answer carries the record is written into the
-     * table, the pinned band and every list kept in the cache, and nothing is loaded again. Only answers of actions on
+     * table, the sections above it and every list kept in the cache, and nothing is loaded again. Only answers of actions on
      * **one** record are read here; a mass answer goes through `answeredChanges`, record by record.
      */
     answeredRow(result) {
@@ -38,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
@@ -70,10 +163,10 @@ export class CrudBackend {
  *   40–59  trash
  *   60+    delete
  *
- * The flag is a **range**, 25–29, and this file checks a single value: the seeded `ERecordStatus.Flagged` is 25, and
- * nothing yet defines what 26–29 would mean. A range-aware check belongs with the per-project bands being built on
- * `/v2/core-config`, so it is deliberately not here — and this note is here so the single value is not mistaken for
- * the final answer.
+ * The flag is a **range**, 25–29, and so is every test here (`isFlagged`, `listMembership`), since 2026-10-08: the
+ * Regions page already read it as a range, and a list that reads 26 as flagged where the table reads it as not would
+ * disagree with itself. A flag written is still 25, the seeded `ERecordStatus.Flagged`. Per-project bands from
+ * `/v2/core-config` would change the numbers here, never the shape of the test.
  */
 /** The Nexus record status of a flagged record (`ERecordStatus.Flagged`), the bottom of the 25–29 flag band. */
 export const NEXUS_FLAGGED_STATUS = 25;
@@ -85,10 +178,37 @@ export const NEXUS_TRASH_STATUS = 40;
 export const NEXUS_DELETED_STATUS = 60;
 /** Just past the flag band: a flagged record is 25–29, so 30 and up is live but not flagged. */
 const NEXUS_FLAG_BAND_END = 30;
+/** Each list as the Nexus backend's `ECommandTypes` numbers its listing: what an export names the list on screen by. */
+const NEXUS_LIST_COMMANDS = { normal: 50, flag: 52, trash: 54, deleted: 55 };
+/** The statuses `ERecordStatus` names. Imported (1) is what a spreadsheet import writes unless the person picks another. */
+const NEXUS_STATUS_WORDS = { 0: "Active", 1: "Imported", 25: "Flagged", 30: "Pending", 31: "Unverified", 32: "In review", 33: "Approval required", 40: "Trashed", 60: "Deleted" };
+/** A record's history in words, by the Nexus backend's `ECommandTypes` and `EAuditKeys`. An audit row keeps the numbers for good. */
+const NEXUS_AUDIT_WORDS = {
+    commands: {
+        0: "Added",
+        1: "Updated",
+        3: "Marks changed",
+        4: "Flag changed",
+        10: "Moved to the trash",
+        11: "Recovered from the trash",
+        12: "Deleted permanently",
+        13: "Moved back to the trash",
+        20: "Basic information updated",
+        21: "Billing information updated",
+        22: "Address updated",
+        23: "References updated",
+        24: "Contact information updated",
+        25: "Email updated",
+    },
+    directions: { 7: "Flagged", 8: "Unflagged", 9: "Made a favourite", 10: "Taken out of the favourites" },
+    parts: { 1: "basic information", 2: "contact information", 3: "email", 4: "address", 5: "profile picture", 6: "password", 11: "permissions", 12: "billing information", 13: "references" },
+    update: 1,
+};
 /**
  * The Nexus backend: pages as `{ ...filters, searchKeyword, skipCount, maxCount, sorting, sortType }` answered with
  * `{ results, totalCount, filterCount }`, newest first unless a column is sorted; mass actions send the ids
- * (`{ description, accountIds }` for descriptions); a flagged record has `recordStatus` 25, a pinned one `isPinned`.
+ * (`{ description, accountIds }` for descriptions); a flagged record has `recordStatus` 25, and this user's marks are
+ * its `bookmarkTypes` (`[Flags] EBookmarkTypes`: 1 pinned, 2 favourite), or `isPinned` from a backend before them.
  */
 export class NexusCrudBackend extends CrudBackend {
     pageRequest(query, sortKey, filters) {
@@ -119,17 +239,70 @@ export class NexusCrudBackend extends CrudBackend {
     massRequest(action, keys, values) {
         return action === "description" ? { description: values?.description ?? null, accountIds: keys } : keys;
     }
+    /** The whole flag band, 25-29: every status comparison is a range test. */
     isFlagged(row) {
-        return Number(row.recordStatus) === NEXUS_FLAGGED_STATUS;
+        const status = Number(row.recordStatus);
+        return status >= NEXUS_FLAGGED_STATUS && status < NEXUS_FLAG_BAND_END;
+    }
+    /**
+     * A live record that is not pending (0-29): the backend flags 0-24 and unflags 25-29, and never touches a pending
+     * record (30-39), which would lose that status for good. A record with no status yet is not refused here.
+     */
+    canFlag(row) {
+        const status = row.recordStatus;
+        return typeof status !== "number" || status < NEXUS_FLAG_BAND_END;
     }
     withFlag(row, on) {
         return { ...row, recordStatus: on ? NEXUS_FLAGGED_STATUS : NEXUS_ACTIVE_STATUS };
     }
     isPinned(row) {
-        return row.isPinned === true;
+        return hasMark(this.marksOf(row), "pin");
     }
     withPin(row, on) {
-        return { ...row, isPinned: on };
+        return this.withMarks(row, withMark(this.marksOf(row), "pin", on));
+    }
+    marksOf(row) {
+        const marks = row.bookmarkTypes;
+        if (typeof marks === "number" && Number.isInteger(marks) && marks >= 0)
+            return marks;
+        return row.isPinned === true ? CRUD_MARK_BITS.pin : 0;
+    }
+    /** `bookmarkTypes`, and `isPinned` too on a record that has one, so neither says something the other does not. */
+    withMarks(row, marks) {
+        const next = { ...row, bookmarkTypes: marks };
+        if ("isPinned" in row)
+            next.isPinned = hasMark(marks, "pin");
+        return next;
+    }
+    /** `SwitchBookmarks` answers the marks it stored, as a number. */
+    answeredMarks(result) {
+        return typeof result === "number" && Number.isInteger(result) && result >= 0 ? result : null;
+    }
+    /** An export names the list on screen as `flag`, by the number `ECommandTypes` gives its listing. */
+    exportFilters(mode) {
+        return { flag: NEXUS_LIST_COMMANDS[mode] };
+    }
+    /** The members `ERecordStatus` names, then the band of any other number in it. */
+    statusText(status) {
+        return NEXUS_STATUS_WORDS[status] ?? (status < NEXUS_FLAGGED_STATUS ? "Active" : status < NEXUS_FLAG_BAND_END ? "Flagged" : status < NEXUS_TRASH_STATUS ? "Pending" : status < NEXUS_DELETED_STATUS ? "Trashed" : "Deleted");
+    }
+    /**
+     * Out of the live band, 40 and up (the owner, 2026-10-08: "if status is not active range, like trash or deleted, show a
+     * very short tag"): "Trashed" in the warning color, "Deleted" in the danger color. A flagged or pending record is still
+     * live, and carries none.
+     */
+    unavailableTag(status) {
+        if (typeof status !== "number" || !Number.isFinite(status) || status < NEXUS_TRASH_STATUS)
+            return null;
+        return { label: this.statusText(status), tone: status < NEXUS_DELETED_STATUS ? "warning" : "danger" };
+    }
+    /** Usable, under 30, as a Nexus `ActiveListing` answers: a pending record is live but not one to pick. No status reads as usable. */
+    isPickable(record) {
+        const status = record.recordStatus;
+        return typeof status !== "number" || status < NEXUS_FLAG_BAND_END;
+    }
+    get auditWords() {
+        return NEXUS_AUDIT_WORDS;
     }
     /** Mass answers list the records they changed, with their new `recordStatus` and `isPinned`. */
     answeredChanges(result, rowKey) {
@@ -169,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

@@ -0,0 +1,98 @@
+import type { ApiEndpoint } from "../Interfaces/ApiInterfaces.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 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>;
+    /** When the record was added. Hidden until the user shows it. */
+    added<TRow extends TableRow>(changes?: Partial<TableColumn<TRow>>): TableColumn<TRow>;
+    /** When it was changed last. Hidden until the user shows it. */
+    changed<TRow extends TableRow>(changes?: Partial<TableColumn<TRow>>): TableColumn<TRow>;
+    /**
+     * 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. 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", from: "regionId" })
+     */
+    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
+     * page, searched and sorted like any column - with the same short tag when the record is no longer available, and
+     * "Not found" for a key with no record. `field` is the looked-up record's field, when it is not the column's `key`.
+     *
+     * @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, 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">;
+/** The controller a client join names its records from: any with a `findListing` (`MODULES.controller(...)`). */
+export interface JoinController {
+    findListing: ApiEndpoint;
+}
+export declare const crudInputs: {
+    /**
+     * The record's description: Markdown, at most `CRUD_DESCRIPTION_MAX` characters, across the form. One definition for
+     * every model, its hint included (the owner, 2026-10-08): a page gives none of its own. `changes` is for its place
+     * 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

@@ -0,0 +1,160 @@
+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 })`. 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 for a record that says none. */
+    status(changes = {}, backend) {
+        return {
+            key: "recordStatus",
+            label: "Status",
+            width: "9rem",
+            render: (_row, value) => (typeof value === "number" ? (backend ?? getCrudBackend()).statusText(value) : ""),
+            ...changes,
+        };
+    },
+    /** The description, as Markdown: text in the table, formatted in the details. */
+    description(changes = {}) {
+        return { key: "description", label: "Description", wrap: true, sortable: false, markdown: true, ...changes };
+    },
+    /** When the record was added. Hidden until the user shows it. */
+    added(changes = {}) {
+        return { key: "creationTime", label: "Added", format: "date-time", hidden: true, ...changes };
+    },
+    /** When it was changed last. Hidden until the user shows it. */
+    changed(changes = {}) {
+        return { key: "modificationTime", label: "Changed", format: "date-time", hidden: true, ...changes };
+    },
+    /**
+     * 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. 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", from: "regionId" })
+     */
+    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
+     * from the other controller's `findListing` - every key the rows hold in one call, kept for every table and form on the
+     * page, searched and sorted like any column - with the same short tag when the record is no longer available, and
+     * "Not found" for a key with no record. `field` is the looked-up record's field, when it is not the column's `key`.
+     *
+     * @example crudColumns.clientJoin(SUB_REGIONS, { key: "subRegionName", label: "Sub-region", from: "subRegionId" })
+     */
+    clientJoin(api, { from, field, ...column }, backend) {
+        return {
+            join: { from, field, source: api.findListing },
+            tag: (_row, joined) => (joined ? (backend ?? getCrudBackend()).unavailableTag(joined.recordStatus) : null),
+            ...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 = {
+    /**
+     * The record's description: Markdown, at most `CRUD_DESCRIPTION_MAX` characters, across the form. One definition for
+     * every model, its hint included (the owner, 2026-10-08): a page gives none of its own. `changes` is for its place
+     * in a form, such as `span`.
+     */
+    description(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;