nexus-shared 3.1.0 → 4.0.0

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,10 +1,13 @@
 import type { ApiEndpoint } from "../Interfaces/ApiInterfaces.ts";
-import type { CrudActionName, CrudEndpoints, 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. */
+/** 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 +21,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,10 +39,86 @@ 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;
+/**
+ * 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. */
@@ -44,6 +128,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 +143,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. */