nexus-shared 3.2.0 → 4.1.0

package/dist/Helpers/FileAdapter.d.ts

@@ -0,0 +1,158 @@
+import type { ApiModuleValue, ApiResult } from "../Interfaces/ApiInterfaces.ts";
+import type { FileCallOptions, FileCategoryInfo, FileChange, 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. In a category that holds removals for a review (`FileCategoryInfo.holdsRemovals`)
+     * the file stays: the answer is the file as it is now, `pendingRemoval: true` (at least `{ pendingRemoval: true }`),
+     * which `removalHeld` reads.
+     */
+    abstract remove(owner: FileOwner<ApiModuleValue>, fileId: string, options?: FileCallOptions): Promise<ApiResult<unknown>>;
+    /**
+     * Keeps a file whose removal waits for a review (`StoredFile.pendingRemoval`): the removal is cancelled and the file
+     * answered as it is now (null when the backend answers nothing). A backend without held removals leaves it out, and no
+     * Keep is offered.
+     */
+    keep?(owner: FileOwner<ApiModuleValue>, fileId: string, options?: FileCallOptions): Promise<ApiResult<StoredFile | null>>;
+    /** 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;
+    /**
+     * The changes still allowed when a refused change says the owner's files may now be changed only some ways - a
+     * receipt posted since the page was read, whose documents are only added to - else `null` (any other refusal). The
+     * panel then offers only those for that owner, under the refusal's own words. Default: no refusal says so.
+     */
+    changesLeft(answer: Pick<ApiResult, "messageCode" | "errorCode" | "status">): readonly FileChange[] | null;
+}
+/** Whether a Delete's answer says the file stays until a review (`FileAdapter.remove` in a category holding removals). */
+export declare const removalHeld: (result: unknown) => boolean;
+/** The words on a file whose removal waits for a review. */
+export declare const PENDING_REMOVAL_TAG = "Removal waiting for review";
+/** Who reviews a held removal when a page does not say (`OwnerFilesParams.removalReviewer`). */
+export declare const REMOVAL_REVIEWER = "Nexus support";
+/** "The picture stays until Nexus support approves its removal.": what a Delete held for a review says once sent. */
+export declare const removalHeldSentence: (noun: string, reviewer?: string | null) => string;
+/**
+ * "If the public sees this picture, it stays until Nexus support approves its removal.": what a Delete asks in a category
+ * that holds removals, where only a file the public sees (approved) is held and the answer says which.
+ */
+export declare const removalHeldQuestion: (noun: string, reviewer?: string | null) => string;
+/** Whether a change is allowed: every change when no list is given, else the ones it names. */
+export declare const allowsFileChange: (changes: readonly FileChange[] | null | undefined, change: FileChange) => boolean;
+/**
+ * The changes allowed when both the page and a refusal narrowed them: those both allow. `null` from both: every change.
+ */
+export declare function narrowFileChanges(page: readonly FileChange[] | null | undefined, learned: readonly FileChange[] | null | undefined): readonly FileChange[] | null;
+/**
+ * What a list says under its files while some changes are left out: the page's reason when its own `changes` leave them
+ * out, else the words of the refusal that narrowed them (`FileAdapter.changesLeft`); nothing while every change is allowed.
+ */
+export declare function fileChangesNote(page: {
+    changes?: readonly FileChange[] | null;
+    reason?: string | null;
+}, learned: {
+    changes: readonly FileChange[];
+    reason: string | null;
+} | null | undefined): string | null;
+/** What an owner's files offer a person: each button a gallery, a document list or the picture input may show. */
+export interface OwnerFileActions {
+    /** Upload (or Replace, in a category that keeps one file and has one: that also deletes the one kept). */
+    upload: boolean;
+    /** Rename a document. */
+    rename: boolean;
+    /** Delete a file. */
+    remove: boolean;
+    /** Make this file the owner's picture (the star); never on the one that already is. */
+    makePrimary: boolean;
+    /** Show no picture, the pictures kept (Remove, beside Upload). */
+    clearPrimary: boolean;
+    /** Edit a picture: saved as a new one - the owner's picture when this one was, in place of it in a one-file category. */
+    edit: boolean;
+    /** Keep a file whose removal waits for a review: the removal cancelled. Offered in place of Delete. */
+    keep: boolean;
+}
+/**
+ * The buttons offered for an owner's files, and for one file when given: none without `canWrite` (the backend's, a page's
+ * `readOnly` or `lockReason`), and each only when the changes allowed hold every change it makes - Replace and Edit in a
+ * one-file category delete the file kept; Edit of the owner's picture makes the new one the picture.
+ *
+ * Held removals (`holdsRemovals`): a file whose removal waits for a review offers only Keep (`keeps`: the backend can), never
+ * Rename, Delete, Make main or Edit; and a one-file category offers no Replace or in-place Edit, since its Delete frees no
+ * room until the review.
+ */
+export declare function ownerFileActions({ canWrite, changes, maxCount, kept, holdsRemovals, keeps }: {
+    canWrite: boolean;
+    changes?: readonly FileChange[] | null;
+    maxCount: number;
+    kept: number;
+    holdsRemovals?: boolean;
+    keeps?: boolean;
+}, file?: Pick<StoredFile, "isPrimary" | "pendingRemoval"> | null): OwnerFileActions;
+/** 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,173 @@
+import { FILE_CHANGES, 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;
+    }
+    /**
+     * The changes still allowed when a refused change says the owner's files may now be changed only some ways - a
+     * receipt posted since the page was read, whose documents are only added to - else `null` (any other refusal). The
+     * panel then offers only those for that owner, under the refusal's own words. Default: no refusal says so.
+     */
+    changesLeft(answer) {
+        void answer;
+        return null;
+    }
+}
+/** Whether a Delete's answer says the file stays until a review (`FileAdapter.remove` in a category holding removals). */
+export const removalHeld = (result) => typeof result === "object" && result !== null && result.pendingRemoval === true;
+/** The words on a file whose removal waits for a review. */
+export const PENDING_REMOVAL_TAG = "Removal waiting for review";
+/** Who reviews a held removal when a page does not say (`OwnerFilesParams.removalReviewer`). */
+export const REMOVAL_REVIEWER = "Nexus support";
+/** "The picture stays until Nexus support approves its removal.": what a Delete held for a review says once sent. */
+export const removalHeldSentence = (noun, reviewer) => `The ${noun} stays until ${reviewer?.trim() || REMOVAL_REVIEWER} approves its removal.`;
+/**
+ * "If the public sees this picture, it stays until Nexus support approves its removal.": what a Delete asks in a category
+ * that holds removals, where only a file the public sees (approved) is held and the answer says which.
+ */
+export const removalHeldQuestion = (noun, reviewer) => `If the public sees this ${noun}, it stays until ${reviewer?.trim() || REMOVAL_REVIEWER} approves its removal.`;
+/** Whether a change is allowed: every change when no list is given, else the ones it names. */
+export const allowsFileChange = (changes, change) => !changes || changes.includes(change);
+/**
+ * The changes allowed when both the page and a refusal narrowed them: those both allow. `null` from both: every change.
+ */
+export function narrowFileChanges(page, learned) {
+    if (!page)
+        return learned ?? null;
+    if (!learned)
+        return page;
+    return page.filter(change => learned.includes(change));
+}
+/** Whether a list of changes leaves any out (none given leaves nothing out). */
+const leavesOut = (changes) => Boolean(changes) && FILE_CHANGES.some(change => !changes.includes(change));
+/**
+ * What a list says under its files while some changes are left out: the page's reason when its own `changes` leave them
+ * out, else the words of the refusal that narrowed them (`FileAdapter.changesLeft`); nothing while every change is allowed.
+ */
+export function fileChangesNote(page, learned) {
+    if (!leavesOut(narrowFileChanges(page.changes, learned?.changes)))
+        return null;
+    const pageReason = leavesOut(page.changes) ? page.reason?.trim() : undefined;
+    return pageReason || learned?.reason?.trim() || null;
+}
+/**
+ * The buttons offered for an owner's files, and for one file when given: none without `canWrite` (the backend's, a page's
+ * `readOnly` or `lockReason`), and each only when the changes allowed hold every change it makes - Replace and Edit in a
+ * one-file category delete the file kept; Edit of the owner's picture makes the new one the picture.
+ *
+ * Held removals (`holdsRemovals`): a file whose removal waits for a review offers only Keep (`keeps`: the backend can), never
+ * Rename, Delete, Make main or Edit; and a one-file category offers no Replace or in-place Edit, since its Delete frees no
+ * room until the review.
+ */
+export function ownerFileActions({ canWrite, changes, maxCount, kept, holdsRemovals = false, keeps = false }, file) {
+    const can = (change) => canWrite && allowsFileChange(changes, change);
+    const single = maxCount === 1;
+    const pending = file?.pendingRemoval === true;
+    // Replace and an in-place Edit delete the file kept first: held, it would still take the one place.
+    const replaces = can("remove") && !holdsRemovals;
+    return {
+        upload: can("add") && (!single || kept === 0 || replaces),
+        rename: can("rename") && !pending,
+        remove: can("remove") && !pending,
+        makePrimary: can("primary") && Boolean(file) && !file.isPrimary && !pending,
+        clearPrimary: can("primary"),
+        edit: can("add") && !pending && (single ? replaces : !file?.isPrimary || can("primary")),
+        keep: pending && keeps && can("remove"),
+    };
+}
+/** 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;

package/dist/Helpers/FormConfirm.js

@@ -0,0 +1,40 @@
+/**
+ * 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 function crudDetailsRuns(columns) {
+    const runs = [];
+    for (const column of columns) {
+        const group = column.group || null;
+        const last = runs[runs.length - 1];
+        if (last && last.group === group)
+            last.columns.push(column);
+        else
+            runs.push({ group, columns: [column] });
+    }
+    return runs;
+}
+/** Whether the form asks before this save: a `confirm` is given, and its `when` holds for the values (or it has none). */
+export function formConfirmAsks(confirm, values) {
+    if (!confirm)
+        return false;
+    return confirm.when ? Boolean(confirm.when(values)) : true;
+}
+const settle = (text, values, body) => typeof text === "function" ? text(values, body) : text;
+/**
+ * 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 function formConfirmQuestion(confirm, values, body) {
+    const details = confirm.details?.(values, body) ?? null;
+    return {
+        title: settle(confirm.title, values, body),
+        message: confirm.message === undefined ? null : settle(confirm.message, values, body),
+        details,
+        confirmLabel: confirm.confirmLabel === undefined ? "Confirm and save" : settle(confirm.confirmLabel, values, body),
+        cancelLabel: confirm.cancelLabel ?? "Back to the form",
+        size: confirm.size ?? (details ? "lg" : "sm"),
+    };
+}