nexus-shared 3.1.0 → 4.0.0

package/dist/Helpers/CrudRowForms.js

@@ -0,0 +1,43 @@
+import { CRUD_ROW_ACTIONS } from "./CrudHelpers.js";
+import { isApiEndpoint } from "./ApiRoutes.js";
+/*
+ * The pure half of a row action that opens a form of its own for the record (`Crud` `rowForms`,
+ * Components/Forms/CrudRowForms.tsx): where it is offered, and what of a save's answer is written back into the record.
+ * Pure, so Node tests run it.
+ */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Whether a row form is offered on a record: on its lists (default the lists that offer Edit), to a person who may call
+ * its `submit` and, when it is an endpoint, its `load`, and by the page's own `when`.
+ */
+export function crudRowFormOffered(form, row, mode, can) {
+    const modes = form.modes ?? Object.keys(CRUD_ROW_ACTIONS).filter(list => CRUD_ROW_ACTIONS[list].includes("edit"));
+    if (!modes.includes(mode))
+        return false;
+    if (!can(form.submit))
+        return false;
+    if (isApiEndpoint(form.load) && !can(form.load))
+        return false;
+    return form.when ? form.when(row, mode) : true;
+}
+/**
+ * What a save changes on the record, as `writes` says: the answer's fields it names (each one the answer carries; an
+ * answer that is not a record changes nothing), or what its function answers. Never the record as the form was opened
+ * on: the CRUD merges this over the record as it holds it when the answer lands, so a change made meanwhile (an Edit
+ * while the popup was minimized) stays.
+ */
+export function crudRowFormWrites(writes, result, row, values) {
+    if (!writes)
+        return null;
+    if (typeof writes === "function") {
+        const patch = writes(result, row, values);
+        return patch && Object.keys(patch).length ? patch : null;
+    }
+    if (!isRecord(result))
+        return null;
+    const patch = {};
+    for (const field of writes)
+        if (result[field] !== undefined)
+            patch[field] = result[field];
+    return Object.keys(patch).length ? patch : null;
+}

package/dist/Helpers/CrudScopes.d.ts

@@ -0,0 +1,32 @@
+import type { CrudProps, CrudScope, CrudScopes } from "../Interfaces/CrudInterfaces.ts";
+import type { FormValues } from "../Interfaces/FormInterfaces.ts";
+/**
+ * The scopes offered now: those whose `when` (the page's own rule) allows them and whose lists the person may call
+ * (`callable`, the CRUD's permission test on the scope's endpoints). None while the permissions are not known.
+ */
+export declare function offeredCrudScopes<TRow extends FormValues>(scopes: CrudScopes<TRow> | undefined, callable: (scope: CrudScope<TRow>) => boolean): CrudScope<TRow>[];
+/** The scope shown: the one chosen while it is offered, else the CRUD's own list (`null`). */
+export declare function shownCrudScope<TRow extends FormValues>(offered: readonly CrudScope<TRow>[], chosen: string | null): CrudScope<TRow> | null;
+/**
+ * The CRUD's props on a scope: its endpoints, and its columns, inputs, forms, table settings and name where it gives its
+ * own (`form` and `table` over the CRUD's, field by field). The CRUD's own list is the props as they are given.
+ */
+export declare function crudScopeProps<TRow extends FormValues>(given: CrudProps<TRow>, scope: CrudScope<TRow> | null): CrudProps<TRow>;
+/**
+ * Where a scope keeps its table's settings: the scope's own `table.stateKey`, else the CRUD's key and the scope's id, so
+ * each list keeps the columns shown, their order and widths, its sort and its page size apart (a Branch column hidden
+ * on one branch's list and shown on every branch's). The CRUD's own list keeps the CRUD's key.
+ */
+export declare function crudScopeStateKey<TRow extends FormValues>(ownKey: string, scope: CrudScope<TRow> | null): string;
+/** Where this browser keeps the choice: `nx-crud-scope:{key}:{viewer}`; nothing without a viewer. */
+export declare function crudScopeStorageKey(remember: {
+    key: string;
+    viewer?: string | null;
+} | undefined): string | null;
+/**
+ * The scope kept: its id, `null` for the CRUD's own list (kept as nothing), `undefined` when nothing could be read (no
+ * storage, no key). A kept scope the CRUD no longer offers stays kept and opens the CRUD's own list until it is offered.
+ */
+export declare function readCrudScope(storage: Pick<Storage, "getItem"> | null, key: string | null): string | null | undefined;
+/** Keeps the choice; the CRUD's own list is kept as nothing. A browser that keeps nothing opens the CRUD's own list. */
+export declare function writeCrudScope(storage: Pick<Storage, "setItem" | "removeItem"> | null, key: string | null, scope: string | null): void;

package/dist/Helpers/CrudScopes.js

@@ -0,0 +1,79 @@
+/*
+ * The pure half of a CRUD whose list can be widened (`Crud` `scopes`, Components/Forms/CrudScopes.tsx): which lists are
+ * offered, which one shows, the props it gives the CRUD, and where this browser keeps the choice. Pure, so Node tests
+ * run it.
+ */
+/**
+ * The scopes offered now: those whose `when` (the page's own rule) allows them and whose lists the person may call
+ * (`callable`, the CRUD's permission test on the scope's endpoints). None while the permissions are not known.
+ */
+export function offeredCrudScopes(scopes, callable) {
+    if (!scopes)
+        return [];
+    return scopes.options.filter(scope => (scope.when ? scope.when() : true) && callable(scope));
+}
+/** The scope shown: the one chosen while it is offered, else the CRUD's own list (`null`). */
+export function shownCrudScope(offered, chosen) {
+    return chosen === null ? null : (offered.find(scope => scope.id === chosen) ?? null);
+}
+/**
+ * The CRUD's props on a scope: its endpoints, and its columns, inputs, forms, table settings and name where it gives its
+ * own (`form` and `table` over the CRUD's, field by field). The CRUD's own list is the props as they are given.
+ */
+export function crudScopeProps(given, scope) {
+    if (!scope)
+        return given;
+    return {
+        ...given,
+        api: scope.api,
+        columns: scope.columns ?? given.columns,
+        inputs: scope.inputs ?? given.inputs,
+        form: scope.form ? { ...given.form, ...scope.form } : given.form,
+        table: scope.table ? { ...given.table, ...scope.table } : given.table,
+        "aria-label": scope["aria-label"] ?? given["aria-label"],
+    };
+}
+/**
+ * Where a scope keeps its table's settings: the scope's own `table.stateKey`, else the CRUD's key and the scope's id, so
+ * each list keeps the columns shown, their order and widths, its sort and its page size apart (a Branch column hidden
+ * on one branch's list and shown on every branch's). The CRUD's own list keeps the CRUD's key.
+ */
+export function crudScopeStateKey(ownKey, scope) {
+    if (!scope)
+        return ownKey;
+    return scope.table?.stateKey ?? `${ownKey}:${scope.id}`;
+}
+/** Where this browser keeps the choice: `nx-crud-scope:{key}:{viewer}`; nothing without a viewer. */
+export function crudScopeStorageKey(remember) {
+    const viewer = remember?.viewer?.trim();
+    return remember?.key && viewer ? `nx-crud-scope:${remember.key}:${viewer}` : null;
+}
+/**
+ * The scope kept: its id, `null` for the CRUD's own list (kept as nothing), `undefined` when nothing could be read (no
+ * storage, no key). A kept scope the CRUD no longer offers stays kept and opens the CRUD's own list until it is offered.
+ */
+export function readCrudScope(storage, key) {
+    if (!storage || !key)
+        return undefined;
+    try {
+        const kept = storage.getItem(key);
+        return kept ? kept : null;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Keeps the choice; the CRUD's own list is kept as nothing. A browser that keeps nothing opens the CRUD's own list. */
+export function writeCrudScope(storage, key, scope) {
+    if (!storage || !key)
+        return;
+    try {
+        if (scope)
+            storage.setItem(key, scope);
+        else
+            storage.removeItem(key);
+    }
+    catch {
+        // Not kept: the CRUD opens its own list next time.
+    }
+}

package/dist/Helpers/DropdownHelpers.d.ts

@@ -45,8 +45,10 @@ export declare function filterItems<TItem extends DropdownItem>(items: readonly
 export declare function defaultSearchKeys(labelKey: string, descriptionKey: string, valueKey: string, columns?: readonly DropdownColumn<never>[]): string[];
 /** Whether a column draws a picture: an avatar, an image, or an icon. The first one also leads the value in the box. */
 export declare function isMediaColumn(column: Pick<DropdownColumn<never>, "type">): boolean;
-/** A column's grid track: its `width`, or `auto` for pictures and codes and `minmax(0, 1fr)` for text. */
+/** A column's grid track: its `width`, or `auto` for pictures, codes and money and `minmax(0, 1fr)` for text. */
 export declare function columnTrack(column: Pick<DropdownColumn<never>, "type" | "width">): string;
+/** Where a column's cells and heading sit: its own `align`, else at the end for money (figures line up), else at the start. */
+export declare function dropdownColumnAlign(column: Pick<DropdownColumn<never>, "type" | "align">): "start" | "center" | "end";
 /**
  * Up to two initials of a name, from its first and last words: "Ram Bahadur Sharma" → "RS", "admin" → "A",
  * "sita.rai" → "SR". Letters keep their script, so "राम शर्मा" → "रश".

package/dist/Helpers/DropdownHelpers.js

@@ -150,11 +150,15 @@ export function defaultSearchKeys(labelKey, descriptionKey, valueKey, columns) {
 export function isMediaColumn(column) {
     return column.type === "avatar" || column.type === "image" || column.type === "icon";
 }
-/** A column's grid track: its `width`, or `auto` for pictures and codes and `minmax(0, 1fr)` for text. */
+/** A column's grid track: its `width`, or `auto` for pictures, codes and money and `minmax(0, 1fr)` for text. */
 export function columnTrack(column) {
     if (column.width)
         return column.width;
-    return isMediaColumn(column) || column.type === "code" ? "auto" : "minmax(0, 1fr)";
+    return isMediaColumn(column) || column.type === "code" || column.type === "money" ? "auto" : "minmax(0, 1fr)";
+}
+/** Where a column's cells and heading sit: its own `align`, else at the end for money (figures line up), else at the start. */
+export function dropdownColumnAlign(column) {
+    return column.align ?? (column.type === "money" ? "end" : "start");
 }
 /**
  * Up to two initials of a name, from its first and last words: "Ram Bahadur Sharma" → "RS", "admin" → "A",

package/dist/Helpers/ExcelHelpers.d.ts

@@ -1,4 +1,4 @@
-import type { InputParams } from "../Interfaces/FormInterfaces.ts";
+import { type InputParams } from "../Interfaces/FormInterfaces.ts";
 import type { ExcelCellProblem, ExcelColumnInfo, ExcelDownload, ExcelReviewRow, ExcelSheetRow } from "../Interfaces/ExcelInterfaces.ts";
 /** What a spreadsheet file is called in a file picker. */
 export declare const EXCEL_FILE_ACCEPT = ".xlsx,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";

package/dist/Helpers/ExcelHelpers.js

@@ -1,3 +1,4 @@
+import { EInputTypes } from "../Interfaces/FormInterfaces.js";
 import { ExcelDataType, ExcelRowKind } from "../Interfaces/ExcelInterfaces.js";
 import { toIsoDate } from "./DateHelpers.js";
 import { toIsoTime } from "./TimeHelpers.js";
@@ -111,28 +112,28 @@ export function excelColumnInput(column) {
         ...(column.maximum === null || column.maximum === undefined ? {} : { max: column.maximum }),
     };
     if (column.isReference)
-        return { ...shared, type: "text", readOnly: true, readOnlyMessage: excelText("referenceLocked") };
+        return { ...shared, type: EInputTypes.Text, readOnly: true, readOnlyMessage: excelText("referenceLocked") };
     if (column.isReadOnly)
-        return { ...shared, type: "text", readOnly: true, readOnlyMessage: excelText("generated") };
+        return { ...shared, type: EInputTypes.Text, readOnly: true, readOnlyMessage: excelText("generated") };
     switch (column.dataType) {
         case ExcelDataType.Note:
-            return { ...shared, type: "textarea", rows: 2, required, ...lengths };
+            return { ...shared, type: EInputTypes.TextArea, rows: 2, required, ...lengths };
         case ExcelDataType.WholeNumber:
-            return { ...shared, type: "number", required, decimals: 0, ...limits };
+            return { ...shared, type: EInputTypes.Number, required, decimals: 0, ...limits };
         case ExcelDataType.Decimal:
-            return { ...shared, type: "number", required, ...limits };
+            return { ...shared, type: EInputTypes.Number, required, ...limits };
         case ExcelDataType.Amount:
-            return { ...shared, type: "number", required, decimals: 2, fixedDecimals: true, grouping: true, ...limits };
+            return { ...shared, type: EInputTypes.Number, required, decimals: 2, fixedDecimals: true, grouping: true, ...limits };
         case ExcelDataType.Date:
-            return { ...shared, type: "date", required };
+            return { ...shared, type: EInputTypes.Date, required };
         case ExcelDataType.DateTime:
-            return { ...shared, type: "text", required, pattern: MOMENT_PATTERN, placeholder: "2026-09-29 14:30" };
+            return { ...shared, type: EInputTypes.Text, required, pattern: MOMENT_PATTERN, placeholder: "2026-09-29 14:30" };
         case ExcelDataType.Time:
-            return { ...shared, type: "time", required };
+            return { ...shared, type: EInputTypes.Time, required };
         case ExcelDataType.YesNo:
-            return { ...shared, type: "dropdown", required, options: YES_NO, searchable: false };
+            return { ...shared, type: EInputTypes.Dropdown, required, options: YES_NO, searchable: false };
         default:
-            return { ...shared, type: "text", required, ...lengths };
+            return { ...shared, type: EInputTypes.Text, required, ...lengths };
     }
 }
 /** Every column of a sheet as the inputs of one editor row, in the order they read. */

package/dist/Helpers/FileAdapter.d.ts

@@ -0,0 +1,78 @@
+import type { ApiModuleValue, ApiResult } from "../Interfaces/ApiInterfaces.ts";
+import type { FileCallOptions, FileCategoryInfo, FileCopy, FileOwner, FileUpload, OwnerFiles, PictureType, StoredFile } from "../Interfaces/FileInterfaces.ts";
+export declare abstract class FileAdapter {
+    /** The owner's files and what their category takes, `canWrite` included. */
+    abstract list(owner: FileOwner<ApiModuleValue>, options?: FileCallOptions): Promise<ApiResult<OwnerFiles>>;
+    /**
+     * Each owner's picture, in the order asked (null where an owner has none): a page's rows in one call. At most
+     * `maxOwners` at a time; `primaryPictures` splits a longer list.
+     */
+    abstract primaries(module: ApiModuleValue, category: string, ownerIds: readonly string[], options?: FileCallOptions): Promise<ApiResult<(StoredFile | null)[]>>;
+    /** Stores one file for the owner and answers it as stored. */
+    abstract upload(owner: FileOwner<ApiModuleValue>, upload: FileUpload, options?: FileCallOptions): Promise<ApiResult<StoredFile>>;
+    /** Makes one of the owner's files its picture, or none (`null`). */
+    abstract setPrimary(owner: FileOwner<ApiModuleValue>, fileId: string | null, options?: FileCallOptions): Promise<ApiResult<unknown>>;
+    /** A new name for one of the owner's files; the backend keeps the extension of what the file really is. */
+    abstract rename(owner: FileOwner<ApiModuleValue>, fileId: string, name: string, options?: FileCallOptions): Promise<ApiResult<unknown>>;
+    /** Deletes one of the owner's files. */
+    abstract remove(owner: FileOwner<ApiModuleValue>, fileId: string, options?: FileCallOptions): Promise<ApiResult<unknown>>;
+    /** The address an `<img>`, a link or the viewer opens the file by. */
+    abstract fileUrl(file: StoredFile, copy: FileCopy): string;
+    /**
+     * The address of the image editor module (`nexus-image-editor`, an ES module) as this backend serves it, versioned,
+     * so `loadImageEditor` can import it. Rejects with an `Error` in plain words when it is not there.
+     */
+    abstract editorModuleUrl(signal?: AbortSignal): Promise<string>;
+    /** The most owners one `primaries` call takes. */
+    get maxOwners(): number;
+}
+/** One owner's key, for caches and listeners: the same module, category and id are the same owner. */
+export declare const fileOwnerKey: (owner: FileOwner<ApiModuleValue>) => string;
+/** Whether a category takes anything that is not a picture: its files are a document list, not a gallery. */
+export declare const takesDocuments: (category: Pick<FileCategoryInfo, "types">) => boolean;
+/** What a file input offers for a category: its MIME types. */
+export declare const acceptOf: (category: Pick<FileCategoryInfo, "types">) => string;
+/** A file's kind in a word, for a list: "JPEG", "PDF". */
+export declare function fileKindName(contentType: string): string;
+/** "JPEG, PNG or WebP" for a category's types, as a sentence names them. */
+export declare function fileKindsSentence(types: readonly string[]): string;
+/** A size in words: "5 MB". */
+export declare const fileSizeText: (bytes: number) => string;
+/**
+ * What a stored picture may be when the backend does not say (Drive's own defaults): its longest side in pixels, the
+ * highest quality in percent, and the most bytes. A company that hosts the site on its own machine raises Drive's
+ * settings, and the browser follows what Drive's List answers.
+ */
+export declare const PICTURE_LIMITS: {
+    readonly maxSide: 1920;
+    readonly quality: 80;
+    readonly maxBytes: number;
+};
+/**
+ * A category's limits for a stored picture: what the backend said, else `PICTURE_LIMITS`; the bytes never above the
+ * category's own `maxBytes`, the quality at most 100.
+ */
+export declare function pictureLimits(category: Pick<FileCategoryInfo, "maxBytes"> & Partial<Pick<FileCategoryInfo, "pictureMaxSide" | "pictureQuality" | "pictureMaxBytes">>): {
+    maxSide: number;
+    quality: number;
+    maxBytes: number;
+};
+/**
+ * Why a chosen file would be refused, before it is sent: a kind the category does not take, or larger than it takes -
+ * for a picture, the category's picture limit (`pictureLimits`). The backend checks the bytes again; this only spares
+ * the person an upload that cannot succeed. Null when it fits.
+ */
+export declare function fileRefusal(category: Pick<FileCategoryInfo, "types" | "maxBytes"> & Partial<Pick<FileCategoryInfo, "pictureMaxSide" | "pictureQuality" | "pictureMaxBytes">>, file: Pick<Blob, "type" | "size">, name: string): string | null;
+/**
+ * A picture's kind read from its first bytes - JPEG, PNG or WebP - for a file the browser could not type (none, or
+ * `application/octet-stream`: a phone's share, a file dragged from another app, a name with no extension), so it still
+ * goes through the editor. Null for anything
+ * else, which is left to the backend (it reads the bytes too).
+ */
+export declare function sniffPictureType(file: Blob): Promise<PictureType | null>;
+/** A chosen file with its kind: the browser's, else a picture's read from its bytes (`sniffPictureType`), else as it was. */
+export declare function typedFile(file: File): Promise<File>;
+/** How many more files the owner keeps: never below 0. */
+export declare const roomLeft: (files: OwnerFiles) => number;
+/** The name a picture made by the editor is kept by: the chosen file's name with the saved kind's extension. */
+export declare function pictureName(name: string | null | undefined, type: string, fallback?: string): string;

package/dist/Helpers/FileAdapter.js

@@ -0,0 +1,102 @@
+import { isPictureType } from "../Interfaces/FileInterfaces.js";
+import { chatFileSize } from "./ChatHelpers.js";
+/*
+ * Where an owner's files are kept. `FileAdapter` is the class an app implements for its own file backend;
+ * `NexusDriveAdapter` (nexus-shared/client) is the Nexus Drive and runs when nothing is registered - the same
+ * arrangement as `ApiModules` / `NexusApiModules` and `ExcelBackend` / `NexusExcelBackend`. The picture input, the
+ * gallery, the document list and the picture column call nothing else, so a page that declares pictures never names
+ * a backend.
+ *
+ * Every call answers an `ApiResult` and never throws for a refused or failed request, like `api`. None shows a toast:
+ * the panel that asked says what happened, once.
+ */
+export class FileAdapter {
+    /** The most owners one `primaries` call takes. */
+    get maxOwners() {
+        return 200;
+    }
+}
+/** One owner's key, for caches and listeners: the same module, category and id are the same owner. */
+export const fileOwnerKey = (owner) => `${String(owner.module)}|${owner.category}|${owner.ownerId}`;
+/** Whether a category takes anything that is not a picture: its files are a document list, not a gallery. */
+export const takesDocuments = (category) => category.types.some(type => !isPictureType(type));
+/** What a file input offers for a category: its MIME types. */
+export const acceptOf = (category) => category.types.join(",");
+/** A file's kind in a word, for a list: "JPEG", "PDF". */
+export function fileKindName(contentType) {
+    const kind = contentType.split("/")[1] ?? contentType;
+    return kind === "jpeg" ? "JPEG" : kind.toUpperCase();
+}
+/** "JPEG, PNG or WebP" for a category's types, as a sentence names them. */
+export function fileKindsSentence(types) {
+    const names = types.map(type => (type === "image/webp" ? "WebP" : fileKindName(type)));
+    if (names.length <= 1)
+        return names[0] ?? "";
+    return `${names.slice(0, -1).join(", ")} or ${names[names.length - 1]}`;
+}
+/** A size in words: "5 MB". */
+export const fileSizeText = (bytes) => chatFileSize(bytes);
+/**
+ * What a stored picture may be when the backend does not say (Drive's own defaults): its longest side in pixels, the
+ * highest quality in percent, and the most bytes. A company that hosts the site on its own machine raises Drive's
+ * settings, and the browser follows what Drive's List answers.
+ */
+export const PICTURE_LIMITS = { maxSide: 1920, quality: 80, maxBytes: 300 * 1024 };
+/**
+ * A category's limits for a stored picture: what the backend said, else `PICTURE_LIMITS`; the bytes never above the
+ * category's own `maxBytes`, the quality at most 100.
+ */
+export function pictureLimits(category) {
+    const positive = (value) => (typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : null);
+    const bytes = positive(category.pictureMaxBytes) ?? PICTURE_LIMITS.maxBytes;
+    return {
+        maxSide: positive(category.pictureMaxSide) ?? PICTURE_LIMITS.maxSide,
+        quality: Math.min(100, positive(category.pictureQuality) ?? PICTURE_LIMITS.quality),
+        maxBytes: category.maxBytes > 0 ? Math.min(bytes, category.maxBytes) : bytes,
+    };
+}
+/**
+ * Why a chosen file would be refused, before it is sent: a kind the category does not take, or larger than it takes -
+ * for a picture, the category's picture limit (`pictureLimits`). The backend checks the bytes again; this only spares
+ * the person an upload that cannot succeed. Null when it fits.
+ */
+export function fileRefusal(category, file, name) {
+    if (file.type && !category.types.includes(file.type))
+        return `"${name}" is not a ${fileKindsSentence(category.types)} file.`;
+    const limit = isPictureType(file.type) ? pictureLimits(category).maxBytes : category.maxBytes;
+    if (limit > 0 && file.size > limit)
+        return `"${name}" is larger than the ${fileSizeText(limit)} this takes.`;
+    return null;
+}
+/**
+ * A picture's kind read from its first bytes - JPEG, PNG or WebP - for a file the browser could not type (none, or
+ * `application/octet-stream`: a phone's share, a file dragged from another app, a name with no extension), so it still
+ * goes through the editor. Null for anything
+ * else, which is left to the backend (it reads the bytes too).
+ */
+export async function sniffPictureType(file) {
+    const head = new Uint8Array(await file.slice(0, 12).arrayBuffer());
+    const text = (from, to) => String.fromCharCode(...head.subarray(from, to));
+    if (head.length >= 3 && head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff)
+        return "image/jpeg";
+    if (head.length >= 8 && [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a].every((byte, at) => head[at] === byte))
+        return "image/png";
+    if (head.length >= 12 && text(0, 4) === "RIFF" && text(8, 12) === "WEBP")
+        return "image/webp";
+    return null;
+}
+/** A chosen file with its kind: the browser's, else a picture's read from its bytes (`sniffPictureType`), else as it was. */
+export async function typedFile(file) {
+    if (file.type && file.type !== "application/octet-stream")
+        return file;
+    const type = await sniffPictureType(file);
+    return type ? new File([file], file.name, { type, lastModified: file.lastModified }) : file;
+}
+/** How many more files the owner keeps: never below 0. */
+export const roomLeft = (files) => Math.max(0, files.category.maxCount - files.files.length);
+/** The name a picture made by the editor is kept by: the chosen file's name with the saved kind's extension. */
+export function pictureName(name, type, fallback = "Picture") {
+    const base = (name ?? "").replace(/\.[A-Za-z][A-Za-z0-9]{0,3}$/, "").trim() || fallback;
+    const extension = type === "image/png" ? "png" : type === "image/webp" ? "webp" : "jpg";
+    return `${base}.${extension}`;
+}

package/dist/Helpers/FilePrimaries.d.ts

@@ -0,0 +1,48 @@
+import type { ApiModuleValue, ApiResult } from "../Interfaces/ApiInterfaces.ts";
+import type { FileOwner, StoredFile } from "../Interfaces/FileInterfaces.ts";
+/** Reads several owners' pictures, in the order asked: `FileAdapter.primaries`. */
+export type PrimariesReader = (module: ApiModuleValue, category: string, ownerIds: readonly string[]) => Promise<ApiResult<(StoredFile | null)[]>>;
+export interface PrimaryPicturesOptions {
+    /** The most owners one call takes, or a function asked when a batch is sent. Default 200, the Nexus Drive's limit. */
+    batchSize?: number | (() => number);
+    /** How long asks are gathered before they are sent, in milliseconds. Default 0: the asks of one render. */
+    delay?: number;
+    /** How long a refused or failed read is kept as "no picture" before an ask reads again, in milliseconds. Default 30000. */
+    retryAfter?: number;
+}
+export declare class PrimaryPictures {
+    private readonly read;
+    private readonly batchSize;
+    private readonly delay;
+    private readonly retryAfter;
+    /** Answers kept: a file, or null for "no picture". A key that is missing has not been read. */
+    private readonly known;
+    /** Reads under way, so two thumbnails of one owner ask once. */
+    private readonly pending;
+    /** Asks gathered per module and category, not sent yet. */
+    private readonly queue;
+    private readonly listeners;
+    /** Owners whose last read failed, with the time an ask may read again. Their `known` answer is null until then. */
+    private readonly failedUntil;
+    /** Bumped by `clear`, so an answer that comes back after it is not kept. */
+    private generation;
+    private timer;
+    constructor(read: PrimariesReader, options?: PrimaryPicturesOptions);
+    /** The owner's picture as kept: a file, `null` for none, `undefined` when it has not been read. */
+    peek(owner: FileOwner<ApiModuleValue>): StoredFile | null | undefined;
+    /** The owner's picture, read with the other asks of this moment unless it is kept already. */
+    get(owner: FileOwner<ApiModuleValue>): Promise<StoredFile | null>;
+    /** Writes in what a change on this page made the owner's picture, and tells its thumbnails. */
+    set(owner: FileOwner<ApiModuleValue>, file: StoredFile | null): void;
+    /** Forgets the owner's picture, so the next ask reads it again. */
+    forget(owner: FileOwner<ApiModuleValue>): void;
+    /** Forgets every kept picture: after a sign-out, or a reload of the whole page's data. */
+    clear(): void;
+    /** Calls `listener` whenever the owner's kept picture changes. Answers the function that stops it. */
+    subscribe(owner: FileOwner<ApiModuleValue>, listener: () => void): () => void;
+    /** Whether the owner's last read failed and its wait is over: the next ask reads again. */
+    private mayRetry;
+    private notify;
+    private flush;
+    private send;
+}

package/dist/Helpers/FilePrimaries.js

@@ -0,0 +1,138 @@
+import { fileOwnerKey } from "./FileAdapter.js";
+export class PrimaryPictures {
+    read;
+    batchSize;
+    delay;
+    retryAfter;
+    /** Answers kept: a file, or null for "no picture". A key that is missing has not been read. */
+    known = new Map();
+    /** Reads under way, so two thumbnails of one owner ask once. */
+    pending = new Map();
+    /** Asks gathered per module and category, not sent yet. */
+    queue = new Map();
+    listeners = new Map();
+    /** Owners whose last read failed, with the time an ask may read again. Their `known` answer is null until then. */
+    failedUntil = new Map();
+    /** Bumped by `clear`, so an answer that comes back after it is not kept. */
+    generation = 0;
+    timer = null;
+    constructor(read, options = {}) {
+        this.read = read;
+        const size = options.batchSize ?? 200;
+        this.batchSize = () => Math.max(1, typeof size === "function" ? size() : size);
+        this.delay = Math.max(0, options.delay ?? 0);
+        this.retryAfter = Math.max(0, options.retryAfter ?? 30_000);
+    }
+    /** The owner's picture as kept: a file, `null` for none, `undefined` when it has not been read. */
+    peek(owner) {
+        const key = fileOwnerKey(owner);
+        if (this.mayRetry(key))
+            return undefined;
+        return this.known.get(key);
+    }
+    /** The owner's picture, read with the other asks of this moment unless it is kept already. */
+    get(owner) {
+        const key = fileOwnerKey(owner);
+        if (this.mayRetry(key)) {
+            this.failedUntil.delete(key);
+            this.known.delete(key);
+        }
+        if (this.known.has(key))
+            return Promise.resolve(this.known.get(key) ?? null);
+        const pending = this.pending.get(key);
+        if (pending)
+            return pending;
+        const waiting = { owner, resolve: () => undefined, generation: this.generation };
+        const asked = new Promise(resolve => {
+            waiting.resolve = resolve;
+        });
+        waiting.asked = asked;
+        const group = `${String(owner.module)}|${owner.category}`;
+        const list = this.queue.get(group) ?? [];
+        list.push(waiting);
+        this.queue.set(group, list);
+        this.timer ??= setTimeout(() => this.flush(), this.delay);
+        this.pending.set(key, asked);
+        return asked;
+    }
+    /** Writes in what a change on this page made the owner's picture, and tells its thumbnails. */
+    set(owner, file) {
+        const key = fileOwnerKey(owner);
+        this.failedUntil.delete(key);
+        this.known.set(key, file);
+        this.notify(key);
+    }
+    /** Forgets the owner's picture, so the next ask reads it again. */
+    forget(owner) {
+        const key = fileOwnerKey(owner);
+        this.failedUntil.delete(key);
+        this.known.delete(key);
+        this.notify(key);
+    }
+    /** Forgets every kept picture: after a sign-out, or a reload of the whole page's data. */
+    clear() {
+        this.generation++;
+        this.known.clear();
+        this.failedUntil.clear();
+        // Reads still under way were asked for the person before; a `get` after this asks again.
+        this.pending.clear();
+        for (const key of this.listeners.keys())
+            this.notify(key);
+    }
+    /** Calls `listener` whenever the owner's kept picture changes. Answers the function that stops it. */
+    subscribe(owner, listener) {
+        const key = fileOwnerKey(owner);
+        const set = this.listeners.get(key) ?? new Set();
+        set.add(listener);
+        this.listeners.set(key, set);
+        return () => {
+            set.delete(listener);
+            if (set.size === 0)
+                this.listeners.delete(key);
+        };
+    }
+    /** Whether the owner's last read failed and its wait is over: the next ask reads again. */
+    mayRetry(key) {
+        const until = this.failedUntil.get(key);
+        return until !== undefined && Date.now() >= until;
+    }
+    notify(key) {
+        for (const listener of [...(this.listeners.get(key) ?? [])])
+            listener();
+    }
+    flush() {
+        this.timer = null;
+        const groups = [...this.queue.values()];
+        this.queue.clear();
+        for (const waiting of groups) {
+            const size = this.batchSize();
+            for (let start = 0; start < waiting.length; start += size)
+                void this.send(waiting.slice(start, start + size));
+        }
+    }
+    async send(batch) {
+        const first = batch[0].owner;
+        const answer = await this.read(first.module, first.category, batch.map(item => item.owner.ownerId)).catch(() => ({ ok: false }));
+        batch.forEach((item, index) => {
+            const key = fileOwnerKey(item.owner);
+            if (this.pending.get(key) === item.asked)
+                this.pending.delete(key);
+            const current = item.generation === this.generation;
+            if (!answer.ok) {
+                // Kept as no picture for a while, so the rows that draw again do not each ask again; then an ask reads again.
+                if (current && !this.known.has(key)) {
+                    this.known.set(key, null);
+                    this.failedUntil.set(key, Date.now() + this.retryAfter);
+                    this.notify(key);
+                }
+                return item.resolve(null);
+            }
+            const file = answer.result?.[index] ?? null;
+            if (current && !this.known.has(key)) {
+                this.known.set(key, file);
+                this.notify(key);
+            }
+            item.resolve(current ? (this.known.get(key) ?? file) : file);
+        });
+    }
+}

package/dist/Helpers/FormConfirm.d.ts

@@ -0,0 +1,32 @@
+import type { ReactNode } from "react";
+import type { PopupSize } from "../Components/Layouts/Popup.tsx";
+import type { FormConfirmDetails, FormConfirmParams, FormValues } from "../Interfaces/FormInterfaces.ts";
+import type { TableColumn, TableRow } from "../Interfaces/TableInterfaces.ts";
+/** A run of neighbouring columns with one `group` (`group` null for columns with none): one section of a record's details. */
+export interface CrudDetailsRun<TRow extends TableRow = TableRow> {
+    group: string | null;
+    columns: TableColumn<TRow>[];
+}
+/**
+ * A record's fields in sections: each run of neighbouring columns that name the same `group` is one section under that
+ * heading, and a run of columns with no group is a section with none. A group named again further on starts a new run,
+ * as a table's band does. An empty group name counts as none.
+ */
+export declare function crudDetailsRuns<TRow extends TableRow>(columns: readonly TableColumn<TRow>[]): CrudDetailsRun<TRow>[];
+/** Whether the form asks before this save: a `confirm` is given, and its `when` holds for the values (or it has none). */
+export declare function formConfirmAsks<TValues extends FormValues>(confirm: FormConfirmParams<TValues> | null | undefined, values: TValues): boolean;
+/** The question a form asks before a save, with every text settled for the values and the body to be sent. */
+export interface FormConfirmQuestion {
+    title: ReactNode;
+    message: ReactNode;
+    details: FormConfirmDetails | null;
+    confirmLabel: ReactNode;
+    cancelLabel: ReactNode;
+    size: PopupSize;
+}
+/**
+ * The question for these values and this body: each text worked out from them, the details drawn when given (a null
+ * answer draws none), "Confirm and save" and "Back to the form" unless given, and the width `lg` with details (two
+ * fields to a line) or `sm` without, unless given. A rule that throws throws here, before anything is shown.
+ */
+export declare function formConfirmQuestion<TValues extends FormValues>(confirm: FormConfirmParams<TValues>, values: TValues, body: unknown): FormConfirmQuestion;