nexus-shared 3.0.0 → 3.2.0

package/dist/Helpers/CrudBackend.js

@@ -1,3 +1,5 @@
+import { CRUD_MARK_BITS, hasMark, withMark } from "./CrudHelpers.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 +8,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 +108,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) {
@@ -70,10 +149,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,14 +164,43 @@ 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 `{ searchKeyword, skipCount, maxCount, sorting, sortType }` answered with
+ * 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) {
+    pageRequest(query, sortKey, filters) {
         return {
+            // Flat and first, so a filter never overwrites a paging field.
+            ...filters,
             searchKeyword: query.search,
             skipCount: (query.page - 1) * query.pageSize,
             maxCount: query.pageSize,
@@ -117,17 +225,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) {

package/dist/Helpers/CrudColumns.d.ts

@@ -0,0 +1,51 @@
+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";
+/** The longest description a record keeps: the owner's rule for every model (the column holds 4000). */
+export declare const CRUD_DESCRIPTION_MAX = 1000;
+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. */
+    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.
+     *
+     * @example crudColumns.dbJoin({ key: "regionName", label: "Region", status: "regionRecordStatus" })
+     */
+    dbJoin<TRow extends TableRow>({ status, ...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>;
+};
+/** What `crudColumns.dbJoin` takes: a column, and the row's field that holds the joined record's status. */
+export type DbJoinColumn<TRow extends TableRow> = Partial<TableColumn<TRow>> & Pick<TableColumn<TRow>, "key" | "label"> & {
+    status: 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;
+};

package/dist/Helpers/CrudColumns.js

@@ -0,0 +1,69 @@
+import { getCrudBackend } from "./CrudBackend.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 })`.
+ */
+/** The longest description a record keeps: the owner's rule for every model (the column holds 4000). */
+export const CRUD_DESCRIPTION_MAX = 1000;
+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. */
+    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.
+     *
+     * @example crudColumns.dbJoin({ key: "regionName", label: "Region", status: "regionRecordStatus" })
+     */
+    dbJoin({ status, ...column }, backend) {
+        return { tag: row => (backend ?? getCrudBackend()).unavailableTag(readPath(row, status)), ...column };
+    },
+    /**
+     * 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,
+        };
+    },
+};
+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: "markdown", name: "description", label: "Description", maxLength: CRUD_DESCRIPTION_MAX, height: 160, hint: "Anything worth knowing about it. Markdown.", span: 12, ...changes };
+    },
+};

package/dist/Helpers/CrudHelpers.d.ts

@@ -1,10 +1,10 @@
 import type { ApiEndpoint } from "../Interfaces/ApiInterfaces.ts";
-import type { CrudActionName, CrudEndpoints, CrudMassActionName, CrudMode, CrudRowActionName } from "../Interfaces/CrudInterfaces.ts";
+import type { CrudActionName, CrudEndpoints, CrudMark, CrudMassActionName, CrudMode, CrudRowActionName } from "../Interfaces/CrudInterfaces.ts";
 import type { MessageActionName } from "../Interfaces/MessageInterfaces.ts";
 import type { 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. */
+/** The built-in actions on one record, per list, in their menu order. A record's history is on every list. */
 export declare const CRUD_ROW_ACTIONS: Readonly<Record<CrudMode, readonly CrudRowActionName[]>>;
 /** The built-in actions on selected records, per list. */
 export declare const CRUD_MASS_ACTIONS: Readonly<Record<CrudMode, readonly CrudMassActionName[]>>;
@@ -18,8 +18,13 @@ export declare function crudRowActions(mode: CrudMode, allowed: (action: CrudRow
 export declare function crudMassActions(mode: CrudMode, allowed: (action: CrudMassActionName) => boolean, trashless?: boolean): CrudMassActionName[];
 /** The endpoint of a list: its full list for tables that page in the browser, its pages for server tables. */
 export declare function crudListEndpoint(api: CrudEndpoints, mode: CrudMode, paging: TablePaging): ApiEndpoint | undefined;
-/** The endpoint of a row action. `view` needs none of its own: it shows the row (and calls `details` when there is one). */
+/**
+ * The endpoint of a row action. `view` needs none of its own: it shows the row (and calls `details` when there is one).
+ * Pin and Favourite both set the record's marks through `bookmark`; a backend without it may still pin, through `pin`.
+ */
 export declare function crudRowEndpoint(api: CrudEndpoints, action: CrudRowActionName): ApiEndpoint | undefined;
+/** The endpoint of an action on many records: Pin and Favourite through `mass.bookmark`, or Pin through `mass.pin`. */
+export declare function crudMassEndpoint(api: CrudEndpoints, action: CrudMassActionName): ApiEndpoint | undefined;
 /** The lists a CRUD can offer: asked for, with an endpoint, and allowed. */
 export declare function availableModes(api: CrudEndpoints, paging: TablePaging, wanted: readonly CrudMode[], can: (endpoint: ApiEndpoint) => boolean): CrudMode[];
 /**
@@ -31,8 +36,8 @@ export declare function actionAllowed(action: CrudActionName, api: CrudEndpoints
 export declare function massActionAllowed(action: CrudMassActionName, api: CrudEndpoints, wanted: readonly CrudActionName[], can: (endpoint: ApiEndpoint) => boolean): boolean;
 /**
  * Whether a record leaves the list shown after an action. Trash, recover, delete, and moving back to the trash take it
- * to another list, and unflagging leaves the flagged list. Pinning and unpinning never do: a pinned
- * record stays in the list it is in. `markOn` is the record's new flag.
+ * to another list, and unflagging leaves the flagged list. A pin or a favourite never does: a marked record stays in
+ * the list it is in. `markOn` is the record's new flag.
  */
 export declare function leavesList(action: CrudRowActionName | CrudMassActionName, mode: CrudMode, markOn?: boolean): boolean;
 /** The message builder's action for a built-in action: "Guest recovered.", "Unpin 3 guests?" */
@@ -44,6 +49,8 @@ export interface CrudSettings {
      * pins and can unpin, and may pin again once they are under it.
      */
     maxPins: number;
+    /** Most records a user may make favourites, kept the same way. Default: whatever `maxPins` is. */
+    maxFavorites?: number;
 }
 /**
  * Changes what every CRUD follows, once, where the app registers its API modules: `configureCrud({ maxPins: 50 })`.
@@ -57,6 +64,44 @@ export declare function getCrudSettings(): CrudSettings;
  * when nothing counts the pins (no `pins` endpoint), and then there is no limit to keep.
  */
 export declare function pinRoom(pinned: number | undefined, max?: number): number;
+/** Every mark, in the order their sections show above the list: Pinned, then Favourites. */
+export declare const CRUD_MARKS: readonly CrudMark[];
+/**
+ * Each mark's bit in a record's set of marks, as the Nexus backend's `[Flags] EBookmarkTypes` numbers them. A set may
+ * hold bits this package does not know - a backend's next mark is its next bit - and a change here keeps them.
+ */
+export declare const CRUD_MARK_BITS: Readonly<Record<CrudMark, number>>;
+/** Whether a set of marks holds this mark. */
+export declare function hasMark(marks: number, mark: CrudMark): boolean;
+/** The set of marks with this one put on or taken off, and every other bit as it was. */
+export declare function withMark(marks: number, mark: CrudMark, on: boolean): number;
+/** Most records a user may give a mark: `maxPins`, and for favourites `maxFavorites`, else the same as the pins. */
+export declare function markLimit(mark: CrudMark, settings?: CrudSettings): number;
+/**
+ * Which ways a selection can go for one mark, from each selected record's marks: on, when one of them lacks it, and
+ * off, when one of them has it. A mixed selection can go both ways, and each is offered on its own (the owner,
+ * 2026-10-07): no action that would change nothing.
+ */
+export declare function markDirections(marks: readonly number[], mark: CrudMark): {
+    on: boolean;
+    off: boolean;
+};
+/** This user's marked records, as a CRUD keeps them: every record's marks by key, and the records of each mark's section. */
+export interface CrudMarkedRecords<TRow extends TableRow = TableRow> {
+    marks: ReadonlyMap<string, number>;
+    rows: Readonly<Record<CrudMark, readonly TRow[]>>;
+}
+/** The marked records as one listing answered them, in its order: `marksOf` reads each record's marks. */
+export declare function markedRecords<TRow extends TableRow>(rows: readonly TRow[], marksOf: (row: TRow) => number, keyOf: (row: TRow) => string): CrudMarkedRecords<TRow>;
+/**
+ * The marked records after a change, with no request. `stored` is each changed record's new set of marks (`0` for
+ * none). A record in `joining` - by default every record in `stored` - that now has a mark goes on top of that mark's
+ * section; one that lost a mark leaves it; every copy of a record in `rows` is replaced. With `joining` empty only the
+ * copies change: a flag or a save never moves a record into a section.
+ */
+export declare function patchMarkedRecords<TRow extends TableRow>(current: CrudMarkedRecords<TRow>, rows: readonly TRow[], stored: ReadonlyMap<string, number>, keyOf: (row: TRow) => string, joining?: ReadonlySet<string>): CrudMarkedRecords<TRow>;
+/** The marked records with these records out of every section - they left the active lists - keeping their marks. */
+export declare function dropMarkedRows<TRow extends TableRow>(current: CrudMarkedRecords<TRow>, keys: readonly string[], keyOf: (row: TRow) => string): CrudMarkedRecords<TRow>;
 /** Default time a CRUD keeps a list: 5 minutes. */
 export declare const CRUD_CACHE_LIFETIME: number;
 /** Lists kept while a page is open, by key, each for a lifetime. Plain values; nothing is written to storage. */

package/dist/Helpers/CrudHelpers.js

@@ -1,19 +1,19 @@
 /*
  * The rules of the CRUD component, with no React: which lists and actions a controller offers, which actions each list
- * shows, which records leave a list after an action, the settings every CRUD follows (how many records may be pinned),
- * and the cache of lists kept while the page is open - including how a change is written into the lists kept, so that
- * a record saved or marked costs no request on any list.
+ * shows, which records leave a list after an action, the settings every CRUD follows (how many records may be pinned
+ * or made favourites), a record's marks, and the cache of lists kept while the page is open - including how a change
+ * is written into the lists kept, so that a record saved or marked costs no request on any list.
  */
 /** Every list, in the order the CRUD shows them. */
 export const CRUD_MODES = ["normal", "flag", "trash", "deleted"];
-const ACTIVE_ROW_ACTIONS = ["view", "edit", "flag", "pin", "trash"];
-const ACTIVE_MASS_ACTIONS = ["flag", "pin", "description", "trash"];
-/** The built-in actions on one record, per list, in their menu order. */
+const ACTIVE_ROW_ACTIONS = ["view", "edit", "flag", "pin", "favorite", "history", "trash"];
+const ACTIVE_MASS_ACTIONS = ["flag", "pin", "favorite", "description", "trash"];
+/** The built-in actions on one record, per list, in their menu order. A record's history is on every list. */
 export const CRUD_ROW_ACTIONS = {
     normal: ACTIVE_ROW_ACTIONS,
     flag: ACTIVE_ROW_ACTIONS,
-    trash: ["view", "recover", "delete"],
-    deleted: ["view", "trashFromDelete"],
+    trash: ["view", "history", "recover", "delete"],
+    deleted: ["view", "history", "trashFromDelete"],
 };
 /** The built-in actions on selected records, per list. */
 export const CRUD_MASS_ACTIONS = {
@@ -56,14 +56,31 @@ export function crudMassActions(mode, allowed, trashless = false) {
 export function crudListEndpoint(api, mode, paging) {
     return paging === "server" ? api.pages?.[mode] : api.lists?.[mode];
 }
-/** The endpoint of a row action. `view` needs none of its own: it shows the row (and calls `details` when there is one). */
+/**
+ * The endpoint of a row action. `view` needs none of its own: it shows the row (and calls `details` when there is one).
+ * Pin and Favourite both set the record's marks through `bookmark`; a backend without it may still pin, through `pin`.
+ */
 export function crudRowEndpoint(api, action) {
     if (action === "view")
         return api.details;
     if (action === "edit")
         return api.update;
+    if (action === "favorite")
+        return api.bookmark;
+    if (action === "pin")
+        return api.bookmark ?? api.pin;
+    if (action === "history")
+        return api.audit;
     return api[action];
 }
+/** The endpoint of an action on many records: Pin and Favourite through `mass.bookmark`, or Pin through `mass.pin`. */
+export function crudMassEndpoint(api, action) {
+    if (action === "favorite")
+        return api.mass?.bookmark;
+    if (action === "pin")
+        return api.mass?.bookmark ?? api.mass?.pin;
+    return api.mass?.[action];
+}
 /** The lists a CRUD can offer: asked for, with an endpoint, and allowed. */
 export function availableModes(api, paging, wanted, can) {
     return CRUD_MODES.filter(mode => wanted.includes(mode)).filter(mode => {
@@ -91,13 +108,13 @@ export function actionAllowed(action, api, wanted, can) {
 export function massActionAllowed(action, api, wanted, can) {
     if (!wanted.includes(action))
         return false;
-    const endpoint = api.mass?.[action];
+    const endpoint = crudMassEndpoint(api, action);
     return Boolean(endpoint) && can(endpoint);
 }
 /**
  * Whether a record leaves the list shown after an action. Trash, recover, delete, and moving back to the trash take it
- * to another list, and unflagging leaves the flagged list. Pinning and unpinning never do: a pinned
- * record stays in the list it is in. `markOn` is the record's new flag.
+ * to another list, and unflagging leaves the flagged list. A pin or a favourite never does: a marked record stays in
+ * the list it is in. `markOn` is the record's new flag.
  */
 export function leavesList(action, mode, markOn) {
     switch (action) {
@@ -119,6 +136,8 @@ export function crudMessageAction(action, markOn) {
             return markOn === false ? "unflag" : "flag";
         case "pin":
             return markOn === false ? "unpin" : "pin";
+        case "favorite":
+            return markOn === false ? "unfavorite" : "favorite";
         case "trashFromDelete":
             return "trash";
         case "description":
@@ -126,6 +145,8 @@ export function crudMessageAction(action, markOn) {
         case "edit":
         case "view":
             return "save";
+        case "history":
+            return "load";
         default:
             return action;
     }
@@ -153,6 +174,82 @@ export function pinRoom(pinned, max = getCrudSettings().maxPins) {
         return Number.POSITIVE_INFINITY;
     return Math.max(0, max - pinned);
 }
+/* This user's marks on a record */
+/** Every mark, in the order their sections show above the list: Pinned, then Favourites. */
+export const CRUD_MARKS = ["pin", "favorite"];
+/**
+ * Each mark's bit in a record's set of marks, as the Nexus backend's `[Flags] EBookmarkTypes` numbers them. A set may
+ * hold bits this package does not know - a backend's next mark is its next bit - and a change here keeps them.
+ */
+export const CRUD_MARK_BITS = { pin: 1, favorite: 2 };
+/** Whether a set of marks holds this mark. */
+export function hasMark(marks, mark) {
+    return (marks & CRUD_MARK_BITS[mark]) !== 0;
+}
+/** The set of marks with this one put on or taken off, and every other bit as it was. */
+export function withMark(marks, mark, on) {
+    const bit = CRUD_MARK_BITS[mark];
+    return on ? marks | bit : marks & ~bit;
+}
+/** Most records a user may give a mark: `maxPins`, and for favourites `maxFavorites`, else the same as the pins. */
+export function markLimit(mark, settings = getCrudSettings()) {
+    return mark === "pin" ? settings.maxPins : (settings.maxFavorites ?? settings.maxPins);
+}
+/**
+ * Which ways a selection can go for one mark, from each selected record's marks: on, when one of them lacks it, and
+ * off, when one of them has it. A mixed selection can go both ways, and each is offered on its own (the owner,
+ * 2026-10-07): no action that would change nothing.
+ */
+export function markDirections(marks, mark) {
+    return { on: marks.some(set => !hasMark(set, mark)), off: marks.some(set => hasMark(set, mark)) };
+}
+/** The marked records as one listing answered them, in its order: `marksOf` reads each record's marks. */
+export function markedRecords(rows, marksOf, keyOf) {
+    const marks = new Map();
+    for (const row of rows) {
+        const set = marksOf(row);
+        if (set)
+            marks.set(keyOf(row), set);
+    }
+    const sections = {};
+    for (const mark of CRUD_MARKS)
+        sections[mark] = rows.filter(row => hasMark(marks.get(keyOf(row)) ?? 0, mark));
+    return { marks, rows: sections };
+}
+/**
+ * The marked records after a change, with no request. `stored` is each changed record's new set of marks (`0` for
+ * none). A record in `joining` - by default every record in `stored` - that now has a mark goes on top of that mark's
+ * section; one that lost a mark leaves it; every copy of a record in `rows` is replaced. With `joining` empty only the
+ * copies change: a flag or a save never moves a record into a section.
+ */
+export function patchMarkedRecords(current, rows, stored, keyOf, joining = new Set(stored.keys())) {
+    const marks = new Map(current.marks);
+    for (const [key, set] of stored) {
+        if (set)
+            marks.set(key, set);
+        else
+            marks.delete(key);
+    }
+    const changed = new Map(rows.map(row => [keyOf(row), row]));
+    const has = (row, mark) => hasMark(marks.get(keyOf(row)) ?? 0, mark);
+    const sections = {};
+    for (const mark of CRUD_MARKS) {
+        const kept = current.rows[mark].map(row => changed.get(keyOf(row)) ?? row).filter(row => has(row, mark));
+        const held = new Set(kept.map(keyOf));
+        sections[mark] = [...rows.filter(row => joining.has(keyOf(row)) && has(row, mark) && !held.has(keyOf(row))), ...kept];
+    }
+    return { marks, rows: sections };
+}
+/** The marked records with these records out of every section - they left the active lists - keeping their marks. */
+export function dropMarkedRows(current, keys, keyOf) {
+    const gone = new Set(keys);
+    if (!CRUD_MARKS.some(mark => current.rows[mark].some(row => gone.has(keyOf(row)))))
+        return current;
+    const sections = {};
+    for (const mark of CRUD_MARKS)
+        sections[mark] = current.rows[mark].filter(row => !gone.has(keyOf(row)));
+    return { marks: current.marks, rows: sections };
+}
 /** Default time a CRUD keeps a list: 5 minutes. */
 export const CRUD_CACHE_LIFETIME = 5 * 60 * 1000;
 /** Lists kept while a page is open, by key, each for a lifetime. Plain values; nothing is written to storage. */

package/dist/Helpers/ExcelBackend.d.ts

@@ -43,8 +43,8 @@ export interface ExcelDownloadHeaders {
 export declare abstract class ExcelBackend {
     /** The form field an upload is sent under. */
     abstract get uploadField(): string;
-    /** What an import sends: the rows the verify answered with, as the person left them. */
-    abstract importRequest(rows: readonly ExcelSheetRow[]): unknown;
+    /** What an import sends: the rows the verify answered with, as the person left them, and the status they start in. */
+    abstract importRequest(rows: readonly ExcelSheetRow[], recordStatus?: number): unknown;
     /** What an export sends: the search, the sort and the filters the person has on screen. */
     abstract exportRequest(query: ExcelExportQuery): unknown;
     /** Reads what the settings endpoint answered. */
@@ -67,7 +67,7 @@ export declare abstract class ExcelBackend {
  */
 export declare class NexusExcelBackend extends ExcelBackend {
     get uploadField(): string;
-    importRequest(rows: readonly ExcelSheetRow[]): unknown;
+    importRequest(rows: readonly ExcelSheetRow[], recordStatus?: number): unknown;
     /**
      * The same request a Nexus listing takes, minus `skipCount` and `maxCount`: an export writes every row the search
      * leaves, up to the backend's own limit, not the page the person happens to be on. With nothing sorted it follows