nexus-shared 3.2.0 → 4.0.0

package/dist/Helpers/RecordCards.js

@@ -0,0 +1,378 @@
+import { EInputTypes } from "../Interfaces/FormInterfaces.js";
+import { isApiEndpoint } from "./ApiRoutes.js";
+import { formatInputValue, holdsValue, isBooleanInput, isEmptyInputValue, isRowsInput } from "./InputParamsHelpers.js";
+/*
+ * The pure half of a record's page of cards (`RecordCards`, Components/Viewers/RecordCards.tsx): how a value reads in a
+ * card, what an answer writes into the data, where a card's items are, its limit, an action's state, a popup's steps,
+ * and the sources the page reads. Pure, so Node tests run it.
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A fields card with its data's type: `fieldsCard<Profile>({ ... })`. */
+export const fieldsCard = (card) => card;
+/** An items card with its data's and its items' types: `itemsCard<ContactList, Contact>({ ... })`. */
+export const itemsCard = (card) => card;
+/** A card of the page's own, with its data's type. */
+export const contentCard = (card) => card;
+/** Which of the three a card is. */
+export function recordCardKind(card) {
+    if ("fields" in card && Array.isArray(card.fields))
+        return "fields";
+    if ("render" in card && typeof card.render === "function")
+        return "content";
+    return "items";
+}
+/* Values */
+/** A field given as its input alone, or with its own label and look: always the second. */
+export function recordField(entry) {
+    return "input" in entry && isRecord(entry.input) && "type" in entry.input ? entry : { input: entry };
+}
+const isPlain = (value) => value === null || ["string", "number", "boolean"].includes(typeof value);
+/**
+ * What a popup's form opens on, of the record or the item it works on: the values its inputs name that an input can hold
+ * (text, a number, a yes or no, a list of those; rows for a rows input - Tabular, Group). A field of another shape - the
+ * code record of a contact, when the step's box is also called `code` - is left out, so the box opens empty rather than
+ * on "[object Object]". Rows are kept whole: an Edit that opened with no rows would send none and wipe them.
+ */
+export function recordOpenedValues(given, inputs) {
+    const opened = {};
+    if (!isRecord(given))
+        return opened;
+    for (const input of inputs) {
+        const value = given[input.name];
+        if (value === undefined)
+            continue;
+        if (isPlain(value) || (Array.isArray(value) && value.every(isPlain)))
+            opened[input.name] = value;
+        else if (isRowsInput(input) && Array.isArray(value) && value.every(row => isRecord(row)))
+            opened[input.name] = value;
+    }
+    return opened;
+}
+/** A fields card's Edit inputs: the fields' own, without those only shown (`edit: false`) or that hold no value. */
+export function recordFieldInputs(card) {
+    return card.fields
+        .map(recordField)
+        .filter(field => field.edit !== false && holdsValue(field.input))
+        .map(field => field.input);
+}
+const LONG_TEXT = new Set([EInputTypes.TextArea]);
+const TEXT_TYPES = new Set([EInputTypes.Text, EInputTypes.Email, EInputTypes.Search, EInputTypes.Tel, EInputTypes.Url, EInputTypes.TextArea]);
+/** Whether a field takes the card's whole width when it does not say: long text, chips and editors do. */
+export function recordFieldWide(field) {
+    if (field.wide !== undefined)
+        return field.wide;
+    const type = field.input.type;
+    return field.look === "lines" || field.look === "chips" || LONG_TEXT.has(type) || type === EInputTypes.Markdown || type === EInputTypes.RichText || type === EInputTypes.CheckBoxGroup;
+}
+/** What a field holds while its source loads, so the card is as tall as it will be: a line, two lines, or a chip's row. */
+export function recordFieldHeld(field) {
+    const type = field.input.type;
+    const multiple = field.input.multiple === true;
+    if (field.look === "chips" || type === EInputTypes.CheckBoxGroup || (type === EInputTypes.Dropdown && multiple))
+        return "chips";
+    if (field.look === "lines" || (field.look !== "text" && (LONG_TEXT.has(type) || type === EInputTypes.Markdown || type === EInputTypes.RichText)))
+        return "lines";
+    return "line";
+}
+/** How many lines a value held as lines holds while its source loads: the field's `heldLines`, else two. */
+export function recordHeldLines(field) {
+    const lines = field.heldLines;
+    return typeof lines === "number" && Number.isFinite(lines) && lines >= 1 ? Math.min(Math.floor(lines), 12) : 2;
+}
+/**
+ * A value as a card draws it, from the input that edits it: a choice by its label, a date in the person's format, a
+ * number with its format, a yes or a no, a list as chips (`look: "chips"`, a multiple choice, a group of checkboxes), long
+ * text on its own lines, Markdown and rich text as such, a password never. Empty when there is nothing to say.
+ */
+export function recordValueView(params, value, options = {}) {
+    const { look, preferences } = options;
+    if (!holdsValue(params))
+        return { kind: "empty" };
+    if (isBooleanInput(params))
+        return value === true ? { kind: "text", text: "Yes" } : value === false ? { kind: "text", text: "No" } : { kind: "empty" };
+    if (isEmptyInputValue(value))
+        return { kind: "empty" };
+    if (params.type === EInputTypes.Password)
+        return { kind: "text", text: "••••••••" };
+    const multiple = params.type === EInputTypes.CheckBoxGroup || (params.type === EInputTypes.Dropdown && Array.isArray(value));
+    if (multiple) {
+        const items = (Array.isArray(value) ? value : [value]).map(item => formatInputValue(params, [item], { preferences })).filter(Boolean);
+        return items.length ? { kind: "chips", items } : { kind: "empty" };
+    }
+    if (look === "chips") {
+        const items = (Array.isArray(value) ? value.map(String) : String(value).split(","))
+            .map(item => item.trim())
+            .filter(Boolean);
+        return items.length ? { kind: "chips", items } : { kind: "empty" };
+    }
+    if (params.type === EInputTypes.Markdown)
+        return { kind: "markdown", text: String(value) };
+    if (params.type === EInputTypes.RichText)
+        return { kind: "rich", html: String(value) };
+    if (TEXT_TYPES.has(params.type)) {
+        const text = String(value).trim();
+        return look === "lines" || (look !== "text" && LONG_TEXT.has(params.type)) ? { kind: "lines", text } : { kind: "text", text };
+    }
+    const text = formatInputValue(params, value, { preferences });
+    return text ? { kind: look === "lines" ? "lines" : "text", text } : { kind: "empty" };
+}
+/* Items */
+/** A card's items: the field it names, what its function answers, or the data itself when that is the list. */
+export function recordItems(data, items) {
+    if (typeof items === "function")
+        return items(data) ?? [];
+    const list = typeof items === "string" ? (isRecord(data) ? data[items] : undefined) : data;
+    return Array.isArray(list) ? list : [];
+}
+/** An item's key, as text. */
+export function recordItemKey(item, itemKey) {
+    const key = typeof itemKey === "function" ? itemKey(item) : isRecord(item) ? item[itemKey] : undefined;
+    return key === undefined || key === null ? "" : String(key);
+}
+/** The data with these items in place of its own, or `null` when the items come from a function (which cannot be set). */
+export function recordWithItems(data, items, next) {
+    if (typeof items === "function")
+        return null;
+    if (typeof items === "string")
+        return { ...(isRecord(data) ? data : {}), [items]: next };
+    return [...next];
+}
+/** The most a card's list may hold, by its `limit`: a number, a field of the data, or a function. `null` for no limit. */
+export function recordLimit(data, limit) {
+    const value = typeof limit === "function" ? limit(data) : typeof limit === "string" ? (isRecord(data) ? data[limit] : undefined) : limit;
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+/** "3 of 5", or "3" with no limit. */
+export const recordCount = (count, limit) => (limit === null ? String(count) : `${count} of ${limit}`);
+/** Why Add is held at the limit. */
+export function recordLimitReason(limit, reason) {
+    if (typeof reason === "function")
+        return reason(limit);
+    return reason ?? `The most there may be is ${limit}. Remove one first.`;
+}
+const merged = (data, patch) => (isRecord(data) && isRecord(patch) ? { ...data, ...patch } : patch);
+/**
+ * What an answer writes into the card's data, as `writes` says (`RecordWrites`). Everything merges over the data as held
+ * now; a list (`"item"`, `"remove"`) is written back only where the card names its field or the data is the list, else
+ * the source is read again.
+ */
+export function recordWrite(request) {
+    const { writes = "answer", result, data, values, fallback, items, itemKey, item } = request;
+    if (typeof writes === "function") {
+        const patch = writes(result, data, values);
+        return patch === null || patch === undefined ? { kind: "none" } : { kind: "write", data: merged(data, patch) };
+    }
+    if (Array.isArray(writes)) {
+        if (!isRecord(result))
+            return { kind: "none" };
+        const patch = {};
+        for (const field of writes)
+            if (result[field] !== undefined)
+                patch[field] = result[field];
+        return Object.keys(patch).length ? { kind: "write", data: merged(data, patch) } : { kind: "none" };
+    }
+    switch (writes) {
+        case "none":
+            return { kind: "none" };
+        case "reload":
+            return { kind: "reload" };
+        case "values":
+            return isRecord(values) ? { kind: "write", data: merged(data, values) } : { kind: "none" };
+        case "item":
+        case "remove": {
+            if (!itemKey)
+                return { kind: "reload" };
+            const list = recordItems(data, items);
+            const key = recordItemKey(writes === "item" ? result : item, itemKey);
+            if (!key)
+                return { kind: "reload" };
+            const next = writes === "remove"
+                ? list.filter(one => recordItemKey(one, itemKey) !== key)
+                : list.some(one => recordItemKey(one, itemKey) === key)
+                    ? list.map(one => (recordItemKey(one, itemKey) === key ? result : one))
+                    : [...list, result];
+            const written = recordWithItems(data, items, next);
+            return written === null ? { kind: "reload" } : { kind: "write", data: written };
+        }
+        default: {
+            if (isRecord(result))
+                return { kind: "write", data: merged(data, result) };
+            if (Array.isArray(result) && Array.isArray(data))
+                return { kind: "write", data: result };
+            if (fallback === "values" && isRecord(values))
+                return { kind: "write", data: merged(data, values) };
+            return { kind: "reload" };
+        }
+    }
+}
+/** The endpoint an action calls first, when it is one: the action shows only to a person who may call it. */
+export function recordActionEndpoint(action) {
+    const submit = action.flow ? (recordSteps(action.flow)[0]?.submit ?? action.flow.submit) : action.confirm?.submit;
+    return isApiEndpoint(submit) ? submit : undefined;
+}
+/** What a heading's button says while its card's data is read. */
+export const RECORD_STILL_READ = "Still being read.";
+/**
+ * An action's state: hidden on a read-only card, by its own rule, or to a person who may not call its endpoint; held with
+ * its reason; else ready. `args` is `null` while the data is still read: the rules typed on the data are not asked then,
+ * and the action is held ("Still being read.") or, with `loading: "hidden"`, not drawn yet.
+ */
+export function recordActionState(action, args, { readOnly, can }) {
+    if (readOnly)
+        return { kind: "hidden" };
+    const endpoint = recordActionEndpoint(action);
+    if (args === null) {
+        if (endpoint && !can(endpoint))
+            return { kind: "hidden" };
+        return action.loading === "hidden" ? { kind: "hidden" } : { kind: "held", reason: RECORD_STILL_READ };
+    }
+    if (action.hidden?.(...args))
+        return { kind: "hidden" };
+    if (endpoint && !can(endpoint))
+        return { kind: "hidden" };
+    const reason = action.held?.(...args);
+    return reason ? { kind: "held", reason } : { kind: "ready" };
+}
+/**
+ * A card's calls on their way, by what each works on (an item's key, or "card"): one added as it starts, that one alone
+ * taken away as it ends, so a call that ends first never frees a row whose own call still runs.
+ */
+export function recordBusyKeys(keys, key, on) {
+    const now = keys ?? [];
+    if (on)
+        return [...now, key];
+    const at = now.indexOf(key);
+    return at < 0 ? now : [...now.slice(0, at), ...now.slice(at + 1)];
+}
+/** An action's accessible name with what it acts on: "Edit: Personal details", "Verify: ram@example.com". */
+export const recordActionName = (label, of) => (of ? `${label}: ${of}` : label);
+/** A popup's steps, each with its id (its place, "1", when it names none): the flow itself when it has no `steps`. */
+export function recordSteps(flow) {
+    const steps = flow.steps?.length ? flow.steps : [flow];
+    return steps.map((step, index) => ({ ...step, id: step.id ?? String(index + 1) }));
+}
+/** The step a popup opens on: `start` when it names a step there is, else the first. */
+export function recordStartStep(flow, context) {
+    const steps = recordSteps(flow);
+    const asked = typeof flow.start === "function" ? flow.start(context) : flow.start;
+    return steps.find(step => step.id === asked)?.id ?? steps[0]?.id ?? "1";
+}
+/** The status line a step's bar keeps: the full one for a form of several inputs, the quiet one for a step of one or two. */
+export const recordStatusLine = (inputs) => (inputs > 2 ? "full" : "errors");
+/** The default rule for a session that ended: a 401 that names no input (a wrong password names its box). */
+export const recordSessionEnded = (answer) => answer.status === 401 && Object.keys(answer.errors ?? {}).length === 0;
+/** Whole seconds until a moment (an ISO text or ms), never below zero. */
+export function secondsUntil(moment, now = Date.now()) {
+    if (moment === null || moment === undefined || moment === "")
+        return 0;
+    const at = typeof moment === "number" ? moment : Date.parse(moment);
+    return Number.isFinite(at) ? Math.max(0, Math.ceil((at - now) / 1000)) : 0;
+}
+const isSourceParams = (source) => isRecord(source) && "read" in source;
+/**
+ * The page's sources: each read once (and again on Try again or a step's `reload`), written by the answers. A read that
+ * fails before anything was read leaves the source failed; one that fails while its data shows keeps the data and only
+ * answers the failure. A newer read wins over an older one still on its way. `end` marks the session ended: the page
+ * shows its words in place of the cards and nothing more is read.
+ */
+export class RecordSources {
+    states;
+    controllers = new Map();
+    listeners = new Set();
+    endedAnswer = null;
+    sources;
+    reader;
+    constructor(sources, reader) {
+        this.sources = sources;
+        this.reader = reader;
+        const states = {};
+        for (const [name, source] of Object.entries(sources))
+            states[name] = { status: "loading", data: isSourceParams(source) ? (source.held ?? null) : null };
+        this.states = states;
+    }
+    /** The names, in the page's order: the first is every card's default. */
+    get names() {
+        return Object.keys(this.sources);
+    }
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+    /** Every source's state; a new object after each change, for `useSyncExternalStore`. */
+    snapshot = () => this.states;
+    get(name) {
+        return this.states[name] ?? { status: "ready", data: null };
+    }
+    /** The answer that found the session ended, once one has. */
+    get ended() {
+        return this.endedAnswer;
+    }
+    set(name, state) {
+        this.states = { ...this.states, [name]: state };
+        for (const listener of this.listeners)
+            listener();
+    }
+    /** Reads every source not read yet (none read, or stopped on its way). */
+    start() {
+        for (const name of this.names) {
+            const state = this.get(name);
+            if (state.status === "loading" && !this.controllers.has(name))
+                void this.read(name);
+        }
+    }
+    /** Stops every read on its way; `start` reads them again. */
+    stop() {
+        for (const controller of this.controllers.values())
+            controller.abort();
+        this.controllers.clear();
+    }
+    /**
+     * Reads a source (again): resolves with the answer. A failed source goes back to loading while it runs; one that shows
+     * its data keeps it. An answer that a newer read or `stop` overtook changes nothing and resolves aborted.
+     */
+    async read(name) {
+        const source = this.sources[name];
+        if (!source || this.endedAnswer)
+            return { ok: false, aborted: true };
+        this.controllers.get(name)?.abort();
+        const controller = new AbortController();
+        this.controllers.set(name, controller);
+        const before = this.get(name);
+        if (before.status === "failed")
+            this.set(name, { status: "loading", data: before.data });
+        // A read overtaken or stopped settles at once, even when the page's own function never looks at its signal.
+        const stopped = new Promise(resolve => controller.signal.addEventListener("abort", () => resolve({ ok: false, aborted: true }), { once: true }));
+        const reading = this.reader(isSourceParams(source) ? source.read : source, controller.signal).catch((error) => (controller.signal.aborted ? { ok: false, aborted: true } : { ok: false, message: error instanceof Error ? error.message : "The server did not answer." }));
+        const answer = await Promise.race([reading, stopped]);
+        if (controller.signal.aborted || this.controllers.get(name) !== controller)
+            return { ...answer, ok: false, aborted: true };
+        this.controllers.delete(name);
+        if (this.endedAnswer)
+            return answer;
+        const now = this.get(name);
+        if (answer.ok)
+            this.set(name, { status: "ready", data: answer.result ?? null });
+        else if (now.status !== "ready")
+            this.set(name, { status: "failed", data: now.data, answer });
+        return answer;
+    }
+    /** Writes a source's data: every card on it follows. */
+    write(name, data) {
+        if (!(name in this.sources) || this.endedAnswer)
+            return;
+        this.set(name, { status: "ready", data });
+    }
+    /** The session ended: nothing more is read, and the page shows its words. */
+    end(answer) {
+        if (this.endedAnswer)
+            return;
+        this.endedAnswer = answer;
+        this.stop();
+        this.states = { ...this.states };
+        for (const listener of this.listeners)
+            listener();
+    }
+}

package/dist/Helpers/RequestCache.d.ts

@@ -20,8 +20,20 @@ export declare class RequestCache<T> {
      * const page = cache.get(`regions|${parentId}|0`, signal => api.post(children, { parentId, skipCount: 0, maxCount: 50 }, { signal }));
      */
     get(key: string, load: (signal: AbortSignal) => T | PromiseLike<T>, lifetime?: number): T | Promise<T>;
-    /** Keeps an answer under `key`, as if it had just been loaded. */
-    set(key: string, value: T): void;
+    /**
+     * Keeps an answer under `key`, as if it had just been loaded - or as if loaded at `at`, for an answer written over
+     * one that was kept: a change written in does not make what was kept any newer.
+     */
+    set(key: string, value: T, at?: number): void;
+    /**
+     * The fresh answers kept under keys that start with `prefix`, with their keys and when they were loaded. A request
+     * on its way is not an answer yet, and an aged answer is not handed out.
+     */
+    entries(prefix?: string, lifetime?: number): {
+        key: string;
+        value: T;
+        at: number;
+    }[];
     private keep;
     /**
      * Drops the answers - kept or on their way - under every key that starts with `prefix`, or that `test` passes, or

package/dist/Helpers/RequestCache.js

@@ -77,9 +77,28 @@ export class RequestCache {
         this.kept.set(key, loading);
         return loading.promise;
     }
-    /** Keeps an answer under `key`, as if it had just been loaded. */
-    set(key, value) {
-        this.keep(key, value, this.lifetime);
+    /**
+     * Keeps an answer under `key`, as if it had just been loaded - or as if loaded at `at`, for an answer written over
+     * one that was kept: a change written in does not make what was kept any newer.
+     */
+    set(key, value, at) {
+        if (at === undefined)
+            this.keep(key, value, this.lifetime);
+        else if (this.lifetime > 0)
+            this.kept.set(key, { state: "ready", value, at });
+    }
+    /**
+     * The fresh answers kept under keys that start with `prefix`, with their keys and when they were loaded. A request
+     * on its way is not an answer yet, and an aged answer is not handed out.
+     */
+    entries(prefix = "", lifetime = this.lifetime) {
+        const list = [];
+        const now = this.now();
+        for (const [key, entry] of this.kept) {
+            if (entry.state === "ready" && key.startsWith(prefix) && now - entry.at < lifetime)
+                list.push({ key, value: entry.value, at: entry.at });
+        }
+        return list;
     }
     keep(key, value, lifetime) {
         if (lifetime > 0)

package/dist/Helpers/RowsStore.d.ts

@@ -1,4 +1,5 @@
-import type { InputParams, InputValidationContext, RowsInputProps, RowValue } from "../Interfaces/FormInterfaces.ts";
+import { type InputParams, type InputValidationContext, type RowsInputProps, type RowValue } from "../Interfaces/FormInterfaces.ts";
+import { type InputMemoryStorage } from "./InputMemory.ts";
 export type RowsStoreOptions<TRow extends RowValue = RowValue> = Pick<RowsInputProps<TRow>, "inputs" | "required" | "min" | "max" | "unique" | "validate" | "itemLabel" | "itemLabelPlural" | "rowKey" | "newRow" | "onRowChange" | "deriveRows"> & {
     /** The row's name when there is no `itemLabel`: "Row" in a table, "Item" in sections. */
     fallbackItem?: string;
@@ -47,6 +48,10 @@ export declare class RowsStore<TRow extends RowValue = RowValue> {
     private showAll;
     private touched;
     private removed;
+    private memory;
+    private added;
+    private asking;
+    private memoryRound;
     private revisions;
     private versions;
     private rowListeners;
@@ -105,8 +110,23 @@ export declare class RowsStore<TRow extends RowValue = RowValue> {
     set(key: string, name: string, value: unknown, source?: "input" | "code"): void;
     /** Marks a value as left by the user: a repeated value shows its message from now on. */
     touch(key: string, name: string): void;
-    /** Adds a row with the inputs' defaults, `newRow`, and `values`, at `index` or at the end. Returns its key. */
+    /**
+     * Adds a row with the inputs' defaults, `newRow`, and `values`, at `index` or at the end. Returns its key. A remembered
+     * input (`remember`) that neither `newRow` nor `values` names with a value opens on the value kept for it, while its
+     * input offers it; a picker's opens once the picker answers, unless the person picked one first.
+     */
     add(values?: Partial<TRow>, index?: number): string;
+    /**
+     * The storage remembered row inputs read and keep (`InputLayoutParams.remember`), given once the rows are drawn in the
+     * browser: rows added from then on open on the kept values. The rows already there keep theirs.
+     */
+    attachMemory(storage: InputMemoryStorage | null): void;
+    /**
+     * A save of the form holding the rows: each remembered input keeps its value in the row added last that is still there
+     * (an empty value forgets), under that row's `per` value and where its `when` holds on that row. No row added since the
+     * rows were loaded: nothing is kept, since no new choice was made.
+     */
+    rememberAdded(): void;
     /** Adds a copy of a row after it, without its id and with its radios off. Returns the copy's key. */
     duplicate(key: string): string | null;
     /**
@@ -138,6 +158,21 @@ export declare class RowsStore<TRow extends RowValue = RowValue> {
     private normalizeRow;
     private load;
     private afterStructure;
+    /**
+     * Opens a new row's remembered inputs on their kept values, where the row is not added with one: the company's
+     * `preferred`, else the person's last choice, while the input offers it (`rememberedOpeningNow`, `when` and `per` read
+     * in the row). A kept choice no longer offered is forgotten. Answers the pickers that must be asked first.
+     */
+    private openRemembered;
+    /** Stops asking pickers about remembered values: their answers no longer open anything. */
+    private stopAskingPickers;
+    /**
+     * Asks each picker whether it still offers the remembered value of a new row's input (`findRememberedOpening`), judged
+     * on the row as it was added: an answer forgets a choice no longer offered (under that row's `per` value), and opens an
+     * offered one while the row is there, the person has not picked in that cell since, and the row's values it was judged
+     * on (`rememberDependencies`) are unchanged.
+     */
+    private askPickers;
     /** Drops what the store knew about a removed row. */
     private forget;
     private write;