nexus-shared 4.0.0 → 4.1.0

package/dist/Helpers/DomainCards.js

@@ -0,0 +1,370 @@
+import { getChatDomains } from "./ChatBackend.js";
+import { formatDate } from "./DateHelpers.js";
+import { formatDateTime } from "./DateTimeHelpers.js";
+import { formatDays, formatMoney, formatNumber } from "./NumberHelpers.js";
+/*
+ * A record's card outside React: which card a kind of record has, the reads every card on the page shares, one card's
+ * read from its first answer through reading it again, and the words and values it is drawn with. `DomainCard` draws
+ * a `DomainCardRun`'s snapshot; nothing here touches the DOM, so it is checked without a browser.
+ *
+ * The reads keep the owner's caching rules (as `RequestCache` does): one read of a record at a time however many cards
+ * draw it, an answer kept for a short life (30 seconds: a card is live, so less than the lists' five minutes), a
+ * failure never kept. A card read again because the record changed takes only a read started after the change.
+ */
+/** How long a card's answer is kept for every card of the page that draws the same record, in milliseconds. */
+export const DOMAIN_CARD_LIFETIME = 30_000;
+/**
+ * A kind's card, with `view` typed by what `load` answers.
+ *
+ * @example
+ * defineChatDomains([{ domain: EDomainTypes.LeaveRequest, key: "leave-request", label: "Leave request", card: domainCard({
+ *   load: (id, signal) => api.get<LeaveRequestCard>(REQUEST_CARD.leave(id), { signal }),
+ *   view: leave => ({ title: `${leave.leaveTypeName} · ${formatDays(leave.days)}`, code: leave.requestCode, ... }),
+ * }) }]);
+ */
+export function domainCard(definition) {
+    return definition;
+}
+/** A kind's registered row and its card, or `undefined` when the app gave it none. */
+export function domainCardOf(domainType) {
+    const info = getChatDomains().find(row => String(row.domain) === String(domainType));
+    return info?.card ? { info, card: info.card } : undefined;
+}
+/** The key a record's answer is kept under: its kind, its id, and who reads it (the same record reads otherwise for another). */
+export function domainCardKey(domainType, id, viewer) {
+    return [domainType, id, viewer ?? ""].map(part => encodeURIComponent(String(part))).join("|");
+}
+/** The start of every key of one record (every reader's), or of every record of a kind without an id. */
+export function domainCardRecordPrefix(domainType, id) {
+    const kind = `${encodeURIComponent(String(domainType))}|`;
+    return id === undefined ? kind : `${kind}${encodeURIComponent(String(id))}|`;
+}
+/**
+ * Reads shared by every card on the page: one read of a record at a time, its answer kept for a lifetime, a failure not
+ * kept. A read nobody waits for any more is aborted.
+ */
+export class DomainCardReads {
+    entries = new Map();
+    now;
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    /** The answer kept under `key` while it is younger than `lifetime` and was read from a read started at or after `since`. */
+    peek(key, lifetime = DOMAIN_CARD_LIFETIME, since = 0) {
+        const entry = this.entries.get(key);
+        if (entry?.state !== "ready")
+            return undefined;
+        if (this.now() - entry.at >= lifetime) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        return entry.startedAt >= since ? entry.value : undefined;
+    }
+    /**
+     * The answer under `key`: a read on its way that started at or after `since`, else a kept fresh one, else a new read by
+     * `load`. `since` is the moment the record was seen to change: what was read before it does not answer.
+     */
+    read(key, load, options = {}) {
+        const { lifetime = DOMAIN_CARD_LIFETIME, since = 0 } = options;
+        const entry = this.entries.get(key);
+        if (entry?.state === "loading" && entry.startedAt >= since)
+            return this.wait(key, entry);
+        const kept = this.peek(key, lifetime, since);
+        if (kept !== undefined)
+            return { promise: Promise.resolve(kept), leave: () => { } };
+        const controller = new AbortController();
+        const startedAt = this.now();
+        let answer;
+        try {
+            answer = Promise.resolve(load(controller.signal));
+        }
+        catch (error) {
+            answer = Promise.reject(error);
+        }
+        const loading = { state: "loading", startedAt, controller, waiters: 0, promise: answer };
+        loading.promise = answer.then(value => {
+            // A read dropped or overtaken on its way answers whoever waits for it, and is not kept.
+            if (this.entries.get(key) === loading) {
+                if (lifetime > 0)
+                    this.entries.set(key, { state: "ready", value, startedAt, at: this.now() });
+                else
+                    this.entries.delete(key);
+            }
+            return value;
+        }, (error) => {
+            if (this.entries.get(key) === loading)
+                this.entries.delete(key);
+            throw error;
+        });
+        // Nobody may be waiting when it fails (every card left): that is not an unhandled rejection.
+        loading.promise.catch(() => { });
+        this.entries.set(key, loading);
+        return this.wait(key, loading);
+    }
+    wait(key, loading) {
+        loading.waiters++;
+        let waiting = true;
+        return {
+            promise: loading.promise,
+            leave: () => {
+                if (!waiting)
+                    return;
+                waiting = false;
+                loading.waiters--;
+                // A card that leaves and comes straight back (a remount) keeps the read: the abort waits a turn.
+                setTimeout(() => {
+                    if (loading.waiters > 0)
+                        return;
+                    if (this.entries.get(key) === loading)
+                        this.entries.delete(key);
+                    loading.controller.abort();
+                }, 0);
+            },
+        };
+    }
+    /**
+     * Drops what is kept or on its way under keys that start with `prefix` (every key when none); a read on its way still
+     * answers its waiters. `keptOnly` leaves the reads on their way, so cards reading again for the same change still share one.
+     */
+    drop(prefix = "", keptOnly = false) {
+        let dropped = 0;
+        for (const [key, entry] of [...this.entries]) {
+            if (!key.startsWith(prefix) || (keptOnly && entry.state !== "ready"))
+                continue;
+            this.entries.delete(key);
+            dropped++;
+        }
+        return dropped;
+    }
+    /** Answers kept and reads on their way. */
+    get size() {
+        return this.entries.size;
+    }
+}
+/** The reads every card of the page shares. */
+export const domainCardReads = new DomainCardReads();
+// Failures
+const statusOf = (error) => {
+    const status = error?.status;
+    return typeof status === "number" ? status : undefined;
+};
+/** A read the page called off (the card closed): not a failure to show. */
+export function isDomainCardAbort(error) {
+    return error?.name === "AbortError";
+}
+/** Whether a failure means the reader may not open the record, or it is not there for them: 403 and 404 alike. */
+export function isDomainCardRefusal(error) {
+    const status = statusOf(error);
+    return status === 403 || status === 404;
+}
+/** Every run that is drawn, for `refreshDomainCards`. */
+const drawn = new Set();
+/** Two answers of the same record: the same when their JSON is. */
+const sameData = (a, b) => {
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return a === b;
+    }
+};
+/**
+ * One card's read: loading, then the record, a refusal or a failure; read again when the record changes (the card stays
+ * on screen meanwhile, and says so when the record turned out different); tried again on Retry. Subscribe to draw it.
+ */
+export class DomainCardRun {
+    domainType;
+    id;
+    key;
+    options;
+    reads;
+    now;
+    snapshot;
+    listeners = new Set();
+    reading = null;
+    round = 0;
+    constructor(options) {
+        this.options = options;
+        this.domainType = options.domainType;
+        this.id = options.id;
+        this.key = domainCardKey(options.domainType, options.id, options.viewer);
+        this.reads = options.reads ?? domainCardReads;
+        this.now = options.now ?? Date.now;
+        // A record read a moment ago by another card is drawn at once, without a placeholder.
+        const kept = this.reads.peek(this.key, this.lifetime);
+        this.snapshot = kept === undefined ? { status: "loading", refreshing: false, refreshFailed: false } : { status: "ready", data: kept, refreshing: false, refreshFailed: false };
+    }
+    get lifetime() {
+        return this.options.lifetime ?? DOMAIN_CARD_LIFETIME;
+    }
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    };
+    getSnapshot = () => this.snapshot;
+    set(next) {
+        this.snapshot = { ...this.snapshot, ...next };
+        for (const listener of this.listeners)
+            listener();
+    }
+    /** The card is drawn: reads, unless it already shows a kept answer. */
+    start() {
+        drawn.add(this);
+        if (this.snapshot.status === "ready" || this.reading)
+            return;
+        this.read(0);
+    }
+    /** The card is gone: stops waiting (the read is aborted when no other card waits for it). */
+    stop() {
+        drawn.delete(this);
+        this.round++;
+        this.reading?.leave();
+        this.reading = null;
+    }
+    /**
+     * The record changed: reads it again, from a read started now. The card on screen stays until the answer lands, and
+     * what other readers kept of the record is forgotten, since it changed for them too.
+     */
+    reload() {
+        this.reads.drop(domainCardRecordPrefix(this.domainType, this.id), true);
+        this.read(this.now());
+    }
+    /** After a failure: reads once more. */
+    retry() {
+        this.read(this.now());
+    }
+    read(since) {
+        const round = ++this.round;
+        this.reading?.leave();
+        const shown = this.snapshot.status === "ready" || this.snapshot.status === "refused";
+        if (shown)
+            this.set({ refreshing: true });
+        else
+            this.set({ status: "loading", refreshing: false, refreshFailed: false, error: undefined });
+        const reading = this.reads.read(this.key, this.options.load, { lifetime: this.lifetime, since });
+        this.reading = reading;
+        reading.promise.then(data => {
+            if (round !== this.round)
+                return;
+            this.reading = null;
+            const before = this.snapshot;
+            const changed = before.status === "ready" && before.data !== undefined && !sameData(before.data, data);
+            this.set({ status: "ready", data, refreshing: false, refreshFailed: false, error: undefined, ...(changed && { changedAt: this.now() }) });
+        }, (error) => {
+            if (round !== this.round)
+                return;
+            this.reading = null;
+            if (isDomainCardAbort(error)) {
+                this.set({ refreshing: false });
+                return;
+            }
+            if (isDomainCardRefusal(error)) {
+                // The reader lost the record, or it is gone: nothing of it stays on screen.
+                this.set({ status: "refused", data: undefined, refreshing: false, refreshFailed: false, changedAt: undefined, error });
+                return;
+            }
+            if (this.snapshot.status === "ready")
+                this.set({ refreshing: false, refreshFailed: true, error });
+            else
+                this.set({ status: "failed", refreshing: false, error });
+        });
+    }
+}
+/**
+ * A record changed (the page approved it, a message said so): every card drawing it reads it again, and no answer kept
+ * from before is handed out. Without an id, every record of the kind.
+ */
+export function refreshDomainCards(domainType, id, reads = domainCardReads) {
+    reads.drop(domainCardRecordPrefix(domainType, id));
+    let count = 0;
+    for (const run of drawn) {
+        if (String(run.domainType) !== String(domainType) || (id !== undefined && String(run.id) !== String(id)))
+            continue;
+        run.reload();
+        count++;
+    }
+    return count;
+}
+// Words
+/** The kind's name inside a sentence: "Leave request" reads "leave request"; "HR letter" keeps its capitals. */
+export function domainCardNoun(kind) {
+    const name = kind?.trim();
+    if (!name)
+        return "record";
+    return /^[A-Z][a-z]/.test(name) ? name[0].toLowerCase() + name.slice(1) : name;
+}
+/** What a reader the record's module refused reads: the same for "not yours" and "not there", so a stranger learns nothing. */
+export function domainCardRefusedText(kind) {
+    return `You cannot open this ${domainCardNoun(kind)}.`;
+}
+/** What a failed read says, beside Try again. */
+export function domainCardFailedText(kind) {
+    return `Could not load this ${domainCardNoun(kind)}.`;
+}
+const isMissing = (value) => value === null || value === undefined || (typeof value === "string" && value.trim() === "") || (typeof value === "number" && Number.isNaN(value));
+const numberOf = (value) => {
+    const number = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(number) ? number : null;
+};
+/** A value written by its kind, or "" when it is missing. A value its kind cannot read is written as it is. */
+export function domainCardValueText(value, kind = "text", options = {}) {
+    if (isMissing(value))
+        return "";
+    const held = value;
+    const { preferences, timeZone, locale, currency } = options;
+    switch (kind) {
+        case "number": {
+            const number = numberOf(held);
+            return number === null ? String(held) : formatNumber(number, { decimals: 2, grouping: true, locale });
+        }
+        case "days": {
+            const number = numberOf(held);
+            return number === null ? String(held) : formatDays(number, { locale });
+        }
+        case "money": {
+            const number = numberOf(held);
+            return number === null ? String(held) : formatMoney(number, { currency, locale });
+        }
+        case "date":
+            return formatDate(String(held), preferences) || String(held);
+        case "datetime":
+            return formatDateTime(String(held), { ...preferences, ...(timeZone && { timeZone }) }) || String(held);
+        default:
+            return String(held);
+    }
+}
+/** The fields a card draws: the ones with a value, and the ones that say what stands in for a missing one. */
+export function domainCardFields(params) {
+    return (params.fields ?? []).filter(field => !isMissing(field.value) || Boolean(field.empty));
+}
+// Shapes
+/** What a placeholder holds when a kind gave nothing and none of its cards has loaded yet: a title, a state, four fields. */
+export const DEFAULT_DOMAIN_CARD_SHAPE = { subtitle: false, state: true, fields: 4, figures: 0, hints: [], lines: 0, columns: 0, more: false, link: false };
+/** How many of each part a card drew. */
+export function domainCardShape(params) {
+    const lines = params.lines;
+    return {
+        subtitle: Boolean(params.subtitle || params.code || params.link),
+        state: Boolean(params.state),
+        fields: domainCardFields(params).length,
+        figures: params.figures?.length ?? 0,
+        hints: (params.figures ?? []).flatMap((figure, index) => (figure.hint ? [index] : [])),
+        lines: lines ? lines.rows.length : 0,
+        columns: lines && lines.rows.length > 0 ? lines.columns.length : 0,
+        more: Boolean(lines && (lines.more ?? 0) > 0),
+        link: Boolean(params.link),
+    };
+}
+const learned = new Map();
+/** Keeps a kind's last drawn shape, so its next placeholder holds the same parts. */
+export function rememberDomainCardShape(domainType, shape) {
+    learned.set(String(domainType), shape);
+}
+/** The shape a kind's placeholder holds: its last card's, else what its card says, else the default. */
+export function heldDomainCardShape(domainType, card) {
+    return learned.get(String(domainType)) ?? { ...DEFAULT_DOMAIN_CARD_SHAPE, ...card?.held };
+}
+/** What `load`, `view` and `extra` are told about a record. */
+export function domainCardContext(domainType, id, extra = {}) {
+    return { domainType, id, ...extra };
+}

package/dist/Helpers/FileAdapter.d.ts

@@ -1,5 +1,5 @@
 import type { ApiModuleValue, ApiResult } from "../Interfaces/ApiInterfaces.ts";
-import type { FileCallOptions, FileCategoryInfo, FileCopy, FileOwner, FileUpload, OwnerFiles, PictureType, StoredFile } from "../Interfaces/FileInterfaces.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>>;
@@ -14,8 +14,18 @@ export declare abstract class FileAdapter {
     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. */
+    /**
+     * 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;
     /**
@@ -25,7 +35,77 @@ export declare abstract class FileAdapter {
     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. */

package/dist/Helpers/FileAdapter.js

@@ -1,4 +1,4 @@
-import { isPictureType } from "../Interfaces/FileInterfaces.js";
+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;
@@ -15,6 +15,77 @@ export class FileAdapter {
     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}`;

package/dist/Helpers/FormStore.d.ts

@@ -193,6 +193,13 @@ export declare class FormStore<TValues extends FormValues = FormValues> {
     set(name: string, value: unknown): void;
     /** Sets several values from code, as one change. */
     setValues(values: Partial<TValues>): void;
+    /**
+     * Values a person set through another input - one worked out from them and typed in (`compute.solve`) - as one change.
+     * Their inputs show them at once, as values from code do, and they are taken as the person's own: the form's
+     * `onFieldChange` runs for them, and inputs narrowed by them lose what they picked. Nothing is taken while the values
+     * load. Answers whether anything changed.
+     */
+    setFromPerson(values: Partial<TValues>): boolean;
     /**
      * A value the user typed or picked, from the input rendered with `stamp`, with what a choice input reported beside it
      * (`item`: a dropdown's option, kept for `pickedItem`). An input that was replaced since (by a value from code, a load,
@@ -298,7 +305,10 @@ export declare class FormStore<TValues extends FormValues = FormValues> {
     /** Inputs that were not there, or were hidden, get their value in the input's type, as a load gives it. */
     private adoptNewInputs;
     private change;
-    /** The inputs whose `dependsOn` (or `narrowedBy`) names any of `names`. */
+    /**
+     * The inputs whose `dependsOn` (or `narrowedBy`) names any of `names`, and the rows inputs whose row inputs are narrowed
+     * by one of them `from: "form"`: their rows draw again with the form's value as it is now.
+     */
     private followersOf;
     private checkRule;
     private checkAllRules;