nexus-shared 3.2.0 → 4.1.0

package/dist/Helpers/RowsStore.js

@@ -1,4 +1,13 @@
-import { duplicateMessageFor, initialInputValue, inputValuesEqual, normalizeInputValue, rowsItemNames, rowsMessage, uniqueKeyOf, validateInput, } from "./InputParamsHelpers.js";
+import { EInputTypes } from "../Interfaces/FormInterfaces.js";
+import { isComputedInput, withComputeSources } from "./InputConditions.js";
+import { findRememberedOpening, forgetInputMemory, isEmptyInputValue, isPickerInput, lastAddedRowKey, readInputMemory, rememberDependencies, rememberedOpeningNow, writeInputMemory, } from "./InputMemory.js";
+import { isEmptyNarrowed, narrowedFollowers } from "./InputNarrowing.js";
+import { duplicateMessageFor, holdsValue, initialInputValue, inputValuesEqual, normalizeInputValue, rowsItemNames, rowsMessage, uniqueKeyOf, validateInput, } from "./InputParamsHelpers.js";
+/** The options with each worked-out input following the inputs it is worked out from (`compute.from` in `dependsOn`). */
+function withSources(options) {
+    const inputs = withComputeSources(options.inputs);
+    return inputs === options.inputs ? options : { ...options, inputs };
+}
 export class RowsStore {
     options;
     inputByName = new Map();
@@ -17,6 +26,12 @@ export class RowsStore {
     showAll = false;
     touched = new Map();
     removed = null;
+    // Remembered row inputs (`remember`): where they are kept, the rows added since the rows were loaded (in the order they
+    // were added: a save keeps the last one's values), and the cells a picker is still asked about.
+    memory = null;
+    added = [];
+    asking = new Map();
+    memoryRound = null;
     // Rendering: a revision per value set from code (its input mounts again with it), a version per row.
     revisions = new Map();
     versions = new Map();
@@ -30,7 +45,7 @@ export class RowsStore {
     /** The array last given to value listeners. A controlled parent that passes it back changes nothing. */
     lastValue = null;
     constructor(options, rows = []) {
-        this.options = options;
+        this.options = withSources(options);
         this.indexInputs();
         this.load(rows);
         this.initial = this.getValue();
@@ -153,7 +168,7 @@ export class RowsStore {
      * callbacks (`validate`, `onRowChange`, `newRow`) are swapped, which a parent's render does every time.
      */
     configure(options, recheck = true) {
-        this.options = options;
+        this.options = withSources(options);
         if (!recheck)
             return;
         this.indexInputs();
@@ -171,6 +186,30 @@ export class RowsStore {
             return;
         this.settle(changed);
     }
+    /**
+     * Values a person set in a row through another of its inputs - one worked out from them and typed in (`compute.solve`)
+     * - as one change. Their cells show them at once, as values from code do, and they are taken as the person's own:
+     * `onRowChange` runs for each, the row's inputs narrowed by them lose what they picked, and the rows' value listeners
+     * hear of it (a parent form's unsaved-changes state, its Save and its leave guard). A name worked out itself is not
+     * taken. Answers whether anything changed.
+     */
+    setFromPerson(key, values) {
+        const before = this.getValue();
+        const changed = new Set();
+        for (const [name, value] of Object.entries(values))
+            this.write(key, name, value, "person", changed, 0);
+        if (this.getValue() === before)
+            return false;
+        this.settle(changed);
+        return true;
+    }
+    /**
+     * Draws every row again, values untouched: the form around the rows changed a value their cells follow
+     * (`narrowedBy` `from: "form"`), so each cell is narrowed afresh as it draws.
+     */
+    redrawRows() {
+        this.touchAllRows();
+    }
     /** Marks a value as left by the user: a repeated value shows its message from now on. */
     touch(key, name) {
         let names = this.touched.get(key);
@@ -182,18 +221,25 @@ export class RowsStore {
         if (!this.showAll && this.duplicateErrors.get(key)?.has(name))
             this.bump(key);
     }
-    /** 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, index = this.entries.length) {
         const position = Math.max(0, Math.min(index, this.entries.length));
         const wasEmpty = this.entries.length === 0;
         const row = {};
         for (const params of this.options.inputs)
-            row[params.name] = initialInputValue(params);
+            if (holdsValue(params) && !isComputedInput(params))
+                row[params.name] = initialInputValue(params);
         const { newRow } = this.options;
-        Object.assign(row, typeof newRow === "function" ? newRow(position) : newRow, values);
+        const named = { ...(typeof newRow === "function" ? newRow(position) : newRow), ...values };
+        Object.assign(row, named);
+        const asks = this.openRemembered(row, named);
         // The first row of a list has each radio on: the first address added is the primary one.
         for (const params of this.options.inputs) {
-            if (params.type === "radio" && wasEmpty && values?.[params.name] === undefined)
+            if (params.type === EInputTypes.Radio && wasEmpty && values?.[params.name] === undefined)
                 row[params.name] = true;
         }
         const entry = { key: this.newKey(), values: this.normalizeRow(row) };
@@ -203,15 +249,41 @@ export class RowsStore {
         for (const params of this.options.inputs) {
             this.checkCell(entry, params);
             // Only one row keeps a radio on: a new row that has it takes it from the others.
-            if (params.type === "radio" && entry.values[params.name] === true)
+            if (params.type === EInputTypes.Radio && entry.values[params.name] === true)
                 this.radioOn(entry, params.name, changed);
         }
         this.messageShown = true;
         this.removed = null;
+        this.added.push(entry.key);
         this.markUniqueDirty();
         this.settle(changed);
+        this.askPickers(entry.key, asks);
         return entry.key;
     }
+    /**
+     * 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) {
+        this.memory = storage;
+    }
+    /**
+     * 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() {
+        if (!this.memory)
+            return;
+        const key = lastAddedRowKey(this.added, added => this.positions.has(added));
+        const row = key === null ? undefined : this.row(key);
+        if (!row)
+            return;
+        const read = (name) => row[name];
+        for (const params of this.options.inputs)
+            if (params.remember && !params.hidden && !isComputedInput(params))
+                writeInputMemory(this.memory, params, row[params.name], read);
+    }
     /** Adds a copy of a row after it, without its id and with its radios off. Returns the copy's key. */
     duplicate(key) {
         const index = this.positions.get(key);
@@ -222,7 +294,7 @@ export class RowsStore {
         if (this.options.rowKey)
             delete values[this.options.rowKey];
         for (const params of this.options.inputs)
-            if (params.type === "radio")
+            if (params.type === EInputTypes.Radio)
                 values[params.name] = false;
         return this.add(values, index + 1);
     }
@@ -243,7 +315,7 @@ export class RowsStore {
         const moved = [];
         const first = this.entries[0];
         for (const params of this.options.inputs) {
-            if (params.type !== "radio" || entry.values[params.name] !== true || !first)
+            if (params.type !== EInputTypes.Radio || entry.values[params.name] !== true || !first)
                 continue;
             this.write(first.key, params.name, true, "code", changed, 1);
             moved.push({ key: first.key, name: params.name });
@@ -306,6 +378,9 @@ export class RowsStore {
      */
     replace(rows, { asInitial = true, emit = false } = {}) {
         this.load(rows);
+        // Loaded rows: none of them was added here, and no picker's answer is wanted any more.
+        this.added = [];
+        this.stopAskingPickers();
         if (asInitial)
             this.initial = this.getValue();
         this.generation++;
@@ -343,6 +418,11 @@ export class RowsStore {
     normalizeRow(row) {
         const values = { ...row };
         for (const params of this.options.inputs) {
+            // A worked-out input holds no value: a field the row came with under its name is not the row's to send.
+            if (isComputedInput(params)) {
+                delete values[params.name];
+                continue;
+            }
             // A hidden input's value stays in the data as it was.
             if (params.hidden)
                 continue;
@@ -363,7 +443,7 @@ export class RowsStore {
         });
         // Saved data with a radio on in more than one row keeps the first.
         for (const params of this.options.inputs) {
-            if (params.type !== "radio")
+            if (params.type !== EInputTypes.Radio)
                 continue;
             let found = false;
             for (const entry of this.entries) {
@@ -383,6 +463,76 @@ export class RowsStore {
         this.valueCache = null;
         this.keysCache = null;
     }
+    /**
+     * 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.
+     */
+    openRemembered(row, named) {
+        const asks = [];
+        const read = (name) => row[name];
+        for (const params of this.options.inputs) {
+            const { name } = params;
+            if (!params.remember || params.hidden || !holdsValue(params) || isComputedInput(params))
+                continue;
+            if (name in named && !isEmptyInputValue(params, named[name]))
+                continue;
+            if (!this.memory && isPickerInput(params))
+                continue;
+            const stored = this.memory ? readInputMemory(this.memory, params.remember, read) : undefined;
+            const opening = rememberedOpeningNow(params, stored, read);
+            if (opening.forget)
+                forgetInputMemory(this.memory, params.remember, read);
+            if (opening.ask)
+                asks.push({ params, stored });
+            if (opening.value !== undefined)
+                row[name] = opening.value;
+        }
+        return asks;
+    }
+    /** Stops asking pickers about remembered values: their answers no longer open anything. */
+    stopAskingPickers() {
+        this.memoryRound?.abort();
+        this.memoryRound = null;
+        this.asking.clear();
+    }
+    /**
+     * 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.
+     */
+    askPickers(key, asks) {
+        const added = this.row(key);
+        if (!asks.length || !added)
+            return;
+        this.memoryRound ??= new AbortController();
+        const round = this.memoryRound;
+        const memory = this.memory;
+        const names = this.asking.get(key) ?? new Set();
+        this.asking.set(key, names);
+        const opening = { ...added };
+        const read = (name) => opening[name];
+        for (const { params, stored } of asks) {
+            names.add(params.name);
+            const judgedOn = rememberDependencies(params);
+            void findRememberedOpening(params, stored, read, round.signal).then(answer => {
+                if (round.signal.aborted)
+                    return;
+                if (answer.forget)
+                    forgetInputMemory(memory, params.remember, read);
+                const waiting = this.asking.get(key);
+                if (!waiting?.delete(params.name))
+                    return;
+                if (!waiting.size)
+                    this.asking.delete(key);
+                const row = this.row(key);
+                if (answer.value === undefined || !row || !judgedOn.every(name => inputValuesEqual(row[name], opening[name])))
+                    return;
+                this.set(key, params.name, answer.value);
+            });
+        }
+    }
     /** Drops what the store knew about a removed row. */
     forget(key) {
         this.invalidCells -= this.invalidByRow.get(key) ?? 0;
@@ -391,20 +541,33 @@ export class RowsStore {
         this.duplicateErrors.delete(key);
         this.touched.delete(key);
         this.revisions.delete(key);
+        this.asking.delete(key);
     }
+    /**
+     * Writes one value. `input` was typed in its own cell; `code` comes from code (its cell mounts again with it); `person`
+     * is a person's change made through another cell (`setFromPerson`): written as code writes, followed as typing is.
+     */
     write(key, name, value, source, changed, depth) {
         const index = this.positions.get(key);
         const entry = index === undefined ? undefined : this.entries[index];
         if (!entry || index === undefined)
             return;
         const params = this.inputByName.get(name);
-        const next = params && source === "code" ? normalizeInputValue(params, value) : value;
+        // A worked-out input holds no value: one set from code (an `onRowChange` or `deriveRows` patch) is not taken.
+        if (isComputedInput(params))
+            return;
+        const asCode = source !== "input";
+        const byPerson = source !== "code";
+        const next = params && asCode ? normalizeInputValue(params, value) : value;
+        // The person's own pick: a picker's answer about a remembered value no longer replaces it.
+        if (byPerson)
+            this.asking.get(key)?.delete(name);
         if (inputValuesEqual(entry.values[name], next))
             return;
         const shownBefore = this.shownError(key, name);
         entry.values = { ...entry.values, [name]: next };
         this.valueCache = null;
-        if (source === "code") {
+        if (asCode) {
             // The input shows its value from when it mounted; a new revision mounts it again with this one.
             let names = this.revisions.get(key);
             if (!names)
@@ -414,7 +577,7 @@ export class RowsStore {
         }
         if (params) {
             this.checkCell(entry, params);
-            if (params.type === "radio") {
+            if (params.type === EInputTypes.Radio) {
                 // The row shows which radios it has on (a section's "Primary" tag), so it renders again, typed or not.
                 changed.add(key);
                 if (next === true)
@@ -426,7 +589,7 @@ export class RowsStore {
         if (this.shownError(key, name) !== shownBefore)
             changed.add(key);
         // Values the row derives from the one the user changed, such as an amount from a quantity and a rate.
-        if (source === "input" && depth === 0 && this.options.onRowChange) {
+        if (byPerson && depth === 0 && this.options.onRowChange) {
             const patch = this.options.onRowChange(entry.values, name, index);
             if (patch) {
                 for (const [field, fieldValue] of Object.entries(patch)) {
@@ -435,6 +598,30 @@ export class RowsStore {
                 }
             }
         }
+        if (byPerson && depth === 0)
+            this.follow(key, name, changed);
+    }
+    /**
+     * After a person changed a row's value: the row's inputs narrowed by it (`narrowedBy`, a line's Tags by its Item) lose
+     * what they picked among its old options, down the row's chain, and the row draws again so each is narrowed afresh;
+     * a row input that `dependsOn` it (a Tags box whose most picks are the row's quantity, through `cellParams`) draws
+     * again too, its rule asked again.
+     */
+    follow(key, name, changed) {
+        const index = this.positions.get(key);
+        const entry = index === undefined ? undefined : this.entries[index];
+        if (!entry)
+            return;
+        const followers = narrowedFollowers(this.options.inputs, [name], "row");
+        for (const follower of followers) {
+            if (!isEmptyNarrowed(entry.values[follower]))
+                this.write(key, follower, null, "code", changed, 1);
+        }
+        const dependents = this.options.inputs.filter(params => params.dependsOn?.includes(name));
+        for (const params of dependents)
+            this.checkCell(entry, params);
+        if (followers.length || dependents.length)
+            changed.add(key);
     }
     /** Turns a radio off in every row but this one. */
     radioOn(entry, name, changed) {
@@ -445,7 +632,7 @@ export class RowsStore {
     }
     /** Checks one value against its input's rules. */
     checkCell(entry, params) {
-        const message = params.hidden ? null : validateInput(params, entry.values[params.name], this.options.context);
+        const message = params.hidden || isComputedInput(params) ? null : validateInput(params, entry.values[params.name], this.options.context);
         this.setError(this.ruleErrors, entry.key, params.name, message);
     }
     setError(map, key, name, message) {

package/dist/Helpers/ServerPreview.d.ts

@@ -0,0 +1,69 @@
+/** What a preview shows now. A new object after every change. */
+export interface ServerPreviewState<TQuestion, TResult> {
+    /** The last answer, kept while a newer question waits or runs, and after a newer one failed. Null before the first. */
+    result: TResult | null;
+    /** The question `result` answers: compare it with the values a save sends, to save only what was shown. */
+    question: TQuestion | null;
+    /** A question waits for its moment: the pause after the last request (`delay`). */
+    waiting: boolean;
+    /** A question is with the server. A page that says "Working it out…" says it while `waiting || loading`. */
+    loading: boolean;
+    /** Why the last question failed, in words; null once a newer answer came, or while a newer question waits. */
+    error: string | null;
+}
+/** Asks the server: the answer, or a throw whose message says why (an abort is not a failure). */
+export type ServerPreviewAsk<TQuestion, TResult> = (question: TQuestion, signal: AbortSignal) => Promise<TResult>;
+export interface ServerPreviewOptions {
+    /** Milliseconds after the last `request` before the question goes. Default 300. */
+    delay?: number;
+    /** The words of a failure whose error has none. Default "The preview cannot be worked out just now." */
+    failure?: string;
+}
+/** The preview's questions and answers, outside React. */
+export declare class ServerPreviewStore<TQuestion, TResult> {
+    private state;
+    private listeners;
+    private timer;
+    private running;
+    private asked;
+    /** Read on each question, so a page's latest function is the one asked. */
+    private readonly ask;
+    private readonly options;
+    constructor(ask: () => ServerPreviewAsk<TQuestion, TResult>, options?: ServerPreviewOptions);
+    getState: () => ServerPreviewState<TQuestion, TResult>;
+    subscribe: (listener: () => void) => (() => void);
+    private patch;
+    /** Stops the question waiting and the one running; their answers are never shown. */
+    private stop;
+    /** Asks about this question a moment after the last request (the delay), dropping any older one. */
+    request(question: TQuestion): void;
+    private send;
+    /** Drops the question waiting or running; the last answer stays. */
+    cancel(): void;
+    /** Drops every question and the last answer: nothing is shown. */
+    clear(): void;
+}
+/** A page's preview: its state, and `request`, `cancel` and `clear`. */
+export interface ServerPreview<TQuestion, TResult> extends ServerPreviewState<TQuestion, TResult> {
+    /** Asks about these values a moment after the last request; an older question is dropped. */
+    request: (question: TQuestion) => void;
+    /** Drops the question waiting or running (the form lacks what the server needs); the last answer stays. */
+    cancel: () => void;
+    /** Drops every question and the last answer. */
+    clear: () => void;
+}
+/**
+ * A preview the server works out a moment after the last change: `request(values)` on every change, and the page shows
+ * `result` (kept while a newer question runs), `waiting` (the pause), `loading` (with the server) and `error`. An older question is aborted and its late answer
+ * never shown; leaving the page stops what runs. `ask` throws to fail, with the words to show.
+ *
+ * @example
+ * const preview = useServerPreview(async (body: CounterBody, signal) => {
+ *   const answer = await api.send<CounterPreview>(COUNTER_PREVIEW, { body, signal, toast: false });
+ *   if (!answer.ok || !answer.result) throw new Error(answer.message ?? "This cannot be worked out just now.");
+ *   return answer.result;
+ * });
+ * <Form inputs={inputs} onValueChange={values => preview.request(counterBody(values))} />
+ * {preview.waiting || preview.loading ? "Working it out…" : preview.error ?? previewLine(preview.result)}
+ */
+export declare function useServerPreview<TQuestion, TResult>(ask: ServerPreviewAsk<TQuestion, TResult>, options?: ServerPreviewOptions): ServerPreview<TQuestion, TResult>;

package/dist/Helpers/ServerPreview.js

@@ -0,0 +1,99 @@
+"use client";
+import { useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { isAbortError } from "./ApiResponses.js";
+const IDLE = { result: null, question: null, waiting: false, loading: false, error: null };
+/** The preview's questions and answers, outside React. */
+export class ServerPreviewStore {
+    state = IDLE;
+    listeners = new Set();
+    timer;
+    running = null;
+    asked = 0;
+    /** Read on each question, so a page's latest function is the one asked. */
+    ask;
+    options;
+    constructor(ask, options = {}) {
+        this.ask = ask;
+        this.options = options;
+    }
+    getState = () => this.state;
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    };
+    patch(changes) {
+        this.state = { ...this.state, ...changes };
+        for (const listener of [...this.listeners])
+            listener();
+    }
+    /** Stops the question waiting and the one running; their answers are never shown. */
+    stop() {
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        this.running?.abort();
+        this.running = null;
+        this.asked++;
+    }
+    /** Asks about this question a moment after the last request (the delay), dropping any older one. */
+    request(question) {
+        this.stop();
+        const turn = this.asked;
+        this.patch({ waiting: true, loading: false, error: null });
+        this.timer = setTimeout(() => void this.send(question, turn), this.options.delay ?? 300);
+    }
+    async send(question, turn) {
+        this.timer = undefined;
+        const controller = new AbortController();
+        this.running = controller;
+        this.patch({ waiting: false, loading: true });
+        try {
+            const result = await this.ask()(question, controller.signal);
+            if (turn !== this.asked)
+                return;
+            this.running = null;
+            this.patch({ result, question, loading: false, error: null });
+        }
+        catch (error) {
+            if (turn !== this.asked || isAbortError(error) || controller.signal.aborted)
+                return;
+            this.running = null;
+            const message = error instanceof Error && error.message ? error.message : (this.options.failure ?? "The preview cannot be worked out just now.");
+            this.patch({ loading: false, error: message });
+        }
+    }
+    /** Drops the question waiting or running; the last answer stays. */
+    cancel() {
+        this.stop();
+        if (this.state.waiting || this.state.loading)
+            this.patch({ waiting: false, loading: false });
+    }
+    /** Drops every question and the last answer: nothing is shown. */
+    clear() {
+        this.stop();
+        this.patch(IDLE);
+    }
+}
+/**
+ * A preview the server works out a moment after the last change: `request(values)` on every change, and the page shows
+ * `result` (kept while a newer question runs), `waiting` (the pause), `loading` (with the server) and `error`. An older question is aborted and its late answer
+ * never shown; leaving the page stops what runs. `ask` throws to fail, with the words to show.
+ *
+ * @example
+ * const preview = useServerPreview(async (body: CounterBody, signal) => {
+ *   const answer = await api.send<CounterPreview>(COUNTER_PREVIEW, { body, signal, toast: false });
+ *   if (!answer.ok || !answer.result) throw new Error(answer.message ?? "This cannot be worked out just now.");
+ *   return answer.result;
+ * });
+ * <Form inputs={inputs} onValueChange={values => preview.request(counterBody(values))} />
+ * {preview.waiting || preview.loading ? "Working it out…" : preview.error ?? previewLine(preview.result)}
+ */
+export function useServerPreview(ask, options) {
+    const latest = useRef(ask);
+    latest.current = ask;
+    const [store] = useState(() => new ServerPreviewStore(() => latest.current, options));
+    const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+    // The same functions on every draw, so a page can name them in an effect's dependencies.
+    const [actions] = useState(() => ({ request: (question) => store.request(question), cancel: () => store.cancel(), clear: () => store.clear() }));
+    useEffect(() => () => store.cancel(), [store]);
+    return { ...state, ...actions };
+}

package/dist/Helpers/TableColumns.js

@@ -40,12 +40,13 @@ export function headLeafCells(head) {
     return cells;
 }
 /**
- * The headings a dragged one can be dropped between: the ones pinned to the same side, in the order they are drawn.
+ * The headings a dragged one can be dropped between: the ones pinned to the same side, in the order they are drawn -
+ * by the side chosen (`data-pin-side`), so a pinned column scrolling on a narrow table still moves among its side's.
  * They are taken from the whole header, so a column under a band and one beside it are the same list.
  */
 function dropTargets(head, heading) {
-    const pin = heading.getAttribute("data-pin") ?? "";
-    return headLeafCells(head).filter(cell => cell.hasAttribute(KEY) && (cell.getAttribute("data-pin") ?? "") === pin);
+    const side = heading.getAttribute("data-pin-side") ?? "";
+    return headLeafCells(head).filter(cell => cell.hasAttribute(KEY) && (cell.getAttribute("data-pin-side") ?? "") === side);
 }
 function clearDropMarks(head) {
     for (const cell of head?.querySelectorAll(`[${DROP_BEFORE}], [${DROP_AFTER}]`) ?? []) {

package/dist/Helpers/TableExport.d.ts

@@ -17,7 +17,13 @@ export interface TableOutput<TRow extends TableRow = TableRow> {
 export declare function tableToCsv<TRow extends TableRow>({ columns, rows, cellOptions }: TableOutput<TRow>): string;
 /** A file name without characters a file system refuses. */
 export declare function safeFileName(name: string): string;
-/** Hands the user a file to save, from text made in the browser. */
+/**
+ * Hands the user a file to save, from text made in the browser: a table's CSV, a person's recovery codes as a `.txt`.
+ * The text goes into a Blob behind a link put in the page, clicked and taken out again, and the Blob's address is let go
+ * ten seconds later. The file starts with a byte order mark, so Excel and Windows editors read it as UTF-8.
+ *
+ * @example downloadText("nexus-recovery-codes.txt", codes.join("\n"), "text/plain;charset=utf-8");
+ */
 export declare function downloadText(name: string, text: string, type: string): void;
 /** Writes the table as a CSV file the user saves. */
 export declare function exportTableCsv<TRow extends TableRow>(output: TableOutput<TRow>): void;

package/dist/Helpers/TableExport.js

@@ -10,14 +10,20 @@ function csvField(text) {
 export function tableToCsv({ columns, rows, cellOptions = {} }) {
     const lines = [columns.map(column => csvField(column.label)).join(",")];
     for (const row of rows)
-        lines.push(columns.map(column => csvField(formatCellText(column, columnValue(column, row), cellOptions))).join(","));
+        lines.push(columns.map(column => csvField(formatCellText(column, columnValue(column, row), cellOptions, row))).join(","));
     return lines.join(CRLF) + CRLF;
 }
 /** A file name without characters a file system refuses. */
 export function safeFileName(name) {
     return name.replace(/[\/:*?"<>|]+/g, " ").trim().replace(/\s+/g, "-").toLowerCase() || "table";
 }
-/** Hands the user a file to save, from text made in the browser. */
+/**
+ * Hands the user a file to save, from text made in the browser: a table's CSV, a person's recovery codes as a `.txt`.
+ * The text goes into a Blob behind a link put in the page, clicked and taken out again, and the Blob's address is let go
+ * ten seconds later. The file starts with a byte order mark, so Excel and Windows editors read it as UTF-8.
+ *
+ * @example downloadText("nexus-recovery-codes.txt", codes.join("\n"), "text/plain;charset=utf-8");
+ */
 export function downloadText(name, text, type) {
     // A BOM, so Excel reads the file as UTF-8 and shows accents and Devanagari.
     const blob = new Blob([String.fromCharCode(0xfeff) + text], { type });
@@ -57,7 +63,7 @@ export function tableToPrintHtml({ columns, rows, cellOptions = {}, name = "Tabl
     const cellClass = (column) => (align(column) === "end" ? ' class="nx-end"' : align(column) === "center" ? ' class="nx-center"' : "");
     const head = columns.map(column => "<th" + cellClass(column) + ">" + escapeHtml(column.label) + "</th>").join("");
     const body = rows
-        .map(row => "<tr>" + columns.map(column => "<td" + cellClass(column) + ">" + escapeHtml(formatCellText(column, columnValue(column, row), cellOptions)) + "</td>").join("") + "</tr>")
+        .map(row => "<tr>" + columns.map(column => "<td" + cellClass(column) + ">" + escapeHtml(formatCellText(column, columnValue(column, row), cellOptions, row)) + "</td>").join("") + "</tr>")
         .join("");
     return [
         "<!doctype html><html><head><meta charset=\"utf-8\"><title>" + escapeHtml(name) + "</title><style>" + PRINT_STYLE + "</style></head><body>",

package/dist/Helpers/TableFilters.d.ts

@@ -1,4 +1,4 @@
-import type { InputParams } from "../Interfaces/FormInterfaces.ts";
+import { type InputParams } from "../Interfaces/FormInterfaces.ts";
 import type { TableColumn, TableFilters, TableRow } from "../Interfaces/TableInterfaces.ts";
 /** The params as a filter: the same object without `required`, `defaultValue`, `defaultChecked`. */
 export declare function asFilterInput(params: InputParams): InputParams;