nexus-shared 1.1.21 → 3.0.0

package/dist/Helpers/ExcelHelpers.js

@@ -0,0 +1,302 @@
+import { ExcelDataType, ExcelRowKind } from "../Interfaces/ExcelInterfaces.js";
+/*
+ * Turning a sheet's columns into inputs, a verify's rows into editable rows and back, and handing the person a file.
+ * Nothing here calls anything: the calls are in Services/ExcelApi.ts.
+ *
+ * Two rules decide every reading below, and both come from the backend:
+ *   - every value travels as **text**, the way it reads in the sheet, because one wire shape serves a verify and an
+ *     import and the import reads it with the same parser that read the file;
+ *   - a choice travels as its **key** and never as an id, so a reference cell is shown as the words the person picked
+ *     and the key beside it is carried through untouched.
+ */
+/** What a spreadsheet file is called in a file picker. */
+export const EXCEL_FILE_ACCEPT = ".xlsx,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+/** The field of an editor row that holds the sheet row it came from. Not a column, so no input is drawn for it. */
+export const EXCEL_ROW_NUMBER = "__excelRow";
+/** The field of an editor row that holds each reference column's key, which the person never sees or types. */
+export const EXCEL_ROW_KEYS = "__excelKeys";
+/** The field of an editor row that holds what the verify answered for it, so an edit can be told from an untouched row. */
+export const EXCEL_ROW_SENT = "__excelSent";
+/* Texts of the spreadsheet side. One table, so a word is changed or translated in one place. */
+const DEFAULT_TEXT = {
+    template: "Download template",
+    templateHint: "The file to fill in: every list is a dropdown, and the ids beside a choice fill themselves.",
+    choose: "Choose file",
+    change: "Choose another file",
+    checking: "Checking",
+    nothingPicked: "No file picked yet.",
+    verifyFailed: "The file could not be read.",
+    newRows: "New rows",
+    duplicates: "Already there",
+    duplicateHint: "Nothing here is updated. Edit a row to add it as a new record instead.",
+    toFix: "What needs fixing",
+    whyDuplicate: "Why these are already there",
+    referenceLocked: "Picked in the spreadsheet: this list belongs to the server.",
+    generated: "The file fills this in.",
+    importLabel: "Import",
+    importNothing: "There is no row to import.",
+    importedNone: "Nothing was written.",
+    refused: "Not written",
+    exportWarning: "Export is cut short",
+    close: "Close",
+    startOver: "Start over",
+};
+let texts = { ...DEFAULT_TEXT };
+/** Rewords or translates the spreadsheet side's own texts. Names only what changes. */
+export function configureExcelText(changes) {
+    texts = { ...texts, ...changes };
+}
+/** One of the spreadsheet side's texts. */
+export function excelText(key) {
+    return texts[key];
+}
+/* Columns as inputs */
+/** How wide a column is drawn, by what it holds. The template sizes its own columns the same way. */
+const COLUMN_WIDTH = {
+    [ExcelDataType.Text]: "12rem",
+    [ExcelDataType.Note]: "20rem",
+    [ExcelDataType.WholeNumber]: "8rem",
+    [ExcelDataType.Decimal]: "8rem",
+    [ExcelDataType.Amount]: "9rem",
+    [ExcelDataType.Date]: "9.5rem",
+    [ExcelDataType.DateTime]: "12rem",
+    [ExcelDataType.Time]: "7.5rem",
+    [ExcelDataType.YesNo]: "7rem",
+    [ExcelDataType.List]: "16rem",
+};
+/** The shapes a zone-less moment may be written in, as the backend reads them. */
+const MOMENT_PATTERN = {
+    source: "[0-9]{4}[-/][0-9]{2}[-/][0-9]{2}([ T][0-9]{2}:[0-9]{2}(:[0-9]{2})?)?",
+    message: "Write a date and time as 2026-09-29 14:30.",
+};
+const YES_NO = [
+    { value: "Yes", label: "Yes" },
+    { value: "No", label: "No" },
+];
+/**
+ * One column of a sheet as an input of the review editors. The rules are the ones the sheet told the person about and
+ * no others, so a fix made here is checked the way the file was.
+ *
+ * Three columns are read-only on purpose:
+ * - a **reference**, because its list is the backend's and is picked in the spreadsheet; the cell shows the words the
+ *   person picked and the key travels back untouched (a key read out of an answer is never typed, and never an id);
+ * - a column the **file** fills;
+ * - and a **date and time** is a text box rather than a picker, because the sheet's moment is a zone-less wall clock
+ *   while the picker's value is a UTC moment: a picker here would shift every value by the person's own offset.
+ */
+export function excelColumnInput(column) {
+    const shared = {
+        name: column.field,
+        label: column.header,
+        width: COLUMN_WIDTH[column.dataType] ?? "12rem",
+        ...(column.note ? { hint: column.note } : {}),
+    };
+    const required = column.isRequired === true;
+    const lengths = {
+        ...(column.minLength && column.minLength > 0 ? { minLength: column.minLength } : {}),
+        ...(column.maxLength && column.maxLength > 0 ? { maxLength: column.maxLength } : {}),
+    };
+    const limits = {
+        ...(column.minimum === null || column.minimum === undefined ? {} : { min: column.minimum }),
+        ...(column.maximum === null || column.maximum === undefined ? {} : { max: column.maximum }),
+    };
+    if (column.isReference)
+        return { ...shared, type: "text", readOnly: true, readOnlyMessage: excelText("referenceLocked") };
+    if (column.isReadOnly)
+        return { ...shared, type: "text", readOnly: true, readOnlyMessage: excelText("generated") };
+    switch (column.dataType) {
+        case ExcelDataType.Note:
+            return { ...shared, type: "textarea", rows: 2, required, ...lengths };
+        case ExcelDataType.WholeNumber:
+            return { ...shared, type: "number", required, decimals: 0, ...limits };
+        case ExcelDataType.Decimal:
+            return { ...shared, type: "number", required, ...limits };
+        case ExcelDataType.Amount:
+            return { ...shared, type: "number", required, decimals: 2, fixedDecimals: true, grouping: true, ...limits };
+        case ExcelDataType.Date:
+            return { ...shared, type: "date", required };
+        case ExcelDataType.DateTime:
+            return { ...shared, type: "text", required, pattern: MOMENT_PATTERN, placeholder: "2026-09-29 14:30" };
+        case ExcelDataType.Time:
+            return { ...shared, type: "time", required };
+        case ExcelDataType.YesNo:
+            return { ...shared, type: "dropdown", required, options: YES_NO, searchable: false };
+        default:
+            return { ...shared, type: "text", required, ...lengths };
+    }
+}
+/** Every column of a sheet as the inputs of one editor row, in the order they read. */
+export function excelColumnInputs(columns) {
+    return columns.map(excelColumnInput);
+}
+/* Rows, both ways */
+/** Whether the person edits this column's cell at all, or only reads it. */
+export function isExcelColumnEditable(column) {
+    return column.isReference !== true && column.isReadOnly !== true;
+}
+/**
+ * A verify's rows as the editors' rows: a value per column, the sheet's row number, and - held beside them, never
+ * drawn - each reference column's key and the values the verify answered with.
+ *
+ * A reference cell shows the **words** the person picked, because its key is not something anybody reads or types.
+ */
+export function excelEditorRows(rows, columns) {
+    return rows.map(row => {
+        const keys = {};
+        const editor = { [EXCEL_ROW_NUMBER]: row.number, [EXCEL_ROW_KEYS]: keys, [EXCEL_ROW_SENT]: { ...row.values } };
+        for (const column of columns) {
+            const value = row.values[column.field] ?? null;
+            if (column.isReference) {
+                keys[column.field] = value;
+                editor[column.field] = row.labels?.[column.field] ?? "";
+                continue;
+            }
+            editor[column.field] = toInputValue(column, value);
+        }
+        return editor;
+    });
+}
+/** Which types are drawn by a number box, whose empty value is `null`. */
+const NUMBER_TYPES = new Set([ExcelDataType.WholeNumber, ExcelDataType.Decimal, ExcelDataType.Amount]);
+/**
+ * A cell's text as the input that draws it wants it: a number as a number, a choice unset rather than empty, and
+ * everything else as it reads.
+ *
+ * The three empties are not interchangeable. A number box is empty at `null`; a **dropdown** given `""` treats it as a
+ * value and reports it as one its list no longer offers ("Not found"), so an empty choice has to be left unset; a text
+ * or date box is empty at `""`.
+ */
+function toInputValue(column, value) {
+    if (value === null || value === "")
+        return NUMBER_TYPES.has(column.dataType) ? null : column.dataType === ExcelDataType.YesNo ? undefined : "";
+    switch (column.dataType) {
+        case ExcelDataType.WholeNumber:
+        case ExcelDataType.Decimal:
+        case ExcelDataType.Amount: {
+            const number = Number(value.replace(/,/g, ""));
+            return Number.isFinite(number) ? number : null;
+        }
+        case ExcelDataType.YesNo: {
+            const upper = value.trim().toUpperCase();
+            if (upper === "YES" || upper === "Y" || upper === "TRUE" || upper === "1")
+                return "Yes";
+            if (upper === "NO" || upper === "N" || upper === "FALSE" || upper === "0")
+                return "No";
+            return value;
+        }
+        default:
+            return value;
+    }
+}
+/** A cell as it travels: text, the way it reads in the sheet. A value the editors could not hold is sent back as it came. */
+function toSheetValue(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value === "boolean")
+        return value ? "Yes" : "No";
+    const written = String(value).trim();
+    return written.length ? written : null;
+}
+/**
+ * Whether a cell still holds what the verify answered for it.
+ *
+ * It is not a comparison of texts, because a cell goes through an input on the way: a sheet that read `38450.50` comes
+ * back from a number box as `38450.5`, and `TRUE` comes back from the Yes/No choice as `Yes`. Both are the same value
+ * and neither is an edit, so the two are compared the way the input holds them.
+ */
+function isSameCell(column, current, sent) {
+    const asSheet = toSheetValue(current);
+    if (asSheet === (sent ?? null))
+        return true;
+    return toInputValue(column, asSheet) === toInputValue(column, sent ?? null);
+}
+/**
+ * The editors' rows as rows to send: every value as text, every reference as the key it came with, and the sheet's own
+ * row number kept so a problem can still name where it is.
+ *
+ * A cell the person did not touch goes back **exactly** as it came, which is what makes the round trip faithful: the
+ * backend reads its own text again, not a number an input rewrote on the way through.
+ */
+export function excelSheetRows(rows, columns) {
+    return rows.map((row, index) => {
+        const keys = (row[EXCEL_ROW_KEYS] ?? {});
+        const sent = (row[EXCEL_ROW_SENT] ?? {});
+        const values = {};
+        const labels = {};
+        for (const column of columns) {
+            if (column.isReference) {
+                values[column.field] = keys[column.field] ?? null;
+                labels[column.field] = toSheetValue(row[column.field]);
+                continue;
+            }
+            values[column.field] = isSameCell(column, row[column.field], sent[column.field]) ? (sent[column.field] ?? null) : toSheetValue(row[column.field]);
+        }
+        const number = Number(row[EXCEL_ROW_NUMBER]);
+        return { number: Number.isFinite(number) && number > 0 ? number : index + 1, values, labels };
+    });
+}
+/** Whether the person changed anything in a row since the verify answered it. */
+export function isExcelRowEdited(row, columns) {
+    const sent = (row[EXCEL_ROW_SENT] ?? {});
+    for (const column of columns) {
+        if (!isExcelColumnEditable(column))
+            continue;
+        if (!isSameCell(column, row[column.field], sent[column.field]))
+            return true;
+    }
+    return false;
+}
+/* What is wrong, in the person's words */
+/** Where a problem is, as the person reads it: the cell, a middle dot, and the column's heading ("B7 - City name"). */
+export function excelProblemPlace(problem) {
+    return problem.cell ? `${problem.cell} ${String.fromCharCode(183)} ${problem.header}` : problem.header;
+}
+/** Every problem of these rows, in the order the rows read. */
+export function excelProblems(rows) {
+    return rows.flatMap(row => row.problems ?? []);
+}
+/** The rows of one kind. */
+export function excelRowsOfKind(rows, ...kinds) {
+    return rows.filter(row => kinds.includes(row.kind));
+}
+/** The rows an import would try to write: the new ones, and the ones still waiting on a fix. */
+export function excelWritableRows(rows) {
+    return excelRowsOfKind(rows, ExcelRowKind.New, ExcelRowKind.Invalid);
+}
+/** More than one of the subject: "cities", "boxes", "rows". An English ending, which a text change can replace. */
+export function excelPlural(subject, plural) {
+    if (plural)
+        return plural;
+    if (/(s|x|z|ch|sh)$/i.test(subject))
+        return `${subject}es`;
+    if (/[^aeiou]y$/i.test(subject))
+        return `${subject.slice(0, -1)}ies`;
+    return `${subject}s`;
+}
+/** A count said in the subject's own words: "1 city", "12 cities". */
+export function excelCount(rows, subject, plural) {
+    if (rows === 1)
+        return `1 ${subject}`;
+    return `${rows.toLocaleString("en-US")} ${excelPlural(subject, plural)}`;
+}
+/**
+ * What to tell the person before an export that will be cut short, as the owner asked: what is on screen, what will be
+ * written, and that filtering is how they get the rest.
+ */
+export function excelExportWarning(rows, limit, subject) {
+    return `The search on screen leaves ${excelCount(rows, subject)}, and one export writes at most ${limit.toLocaleString("en-US")}. The first ${limit.toLocaleString("en-US")} are written and the rest are left out. Search or filter for the rows you need to get them all.`;
+}
+/* The file itself */
+/** Hands the person a file to save, under the name the answer gave it. */
+export function saveExcelFile(download) {
+    const url = URL.createObjectURL(download.blob);
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = download.fileName;
+    link.rel = "noopener";
+    document.body.append(link);
+    link.click();
+    link.remove();
+    // Firefox needs the object URL a moment longer than the click.
+    setTimeout(() => URL.revokeObjectURL(url), 10_000);
+}

package/dist/Helpers/FormDrafts.d.ts

@@ -0,0 +1,18 @@
+import type { FormValues } from "../Interfaces/FormInterfaces.ts";
+/** A form's unsaved changes. */
+export interface FormDraft {
+    /** The changed values, by input name. */
+    values: FormValues;
+    /** The same inputs' values when the changes were made, to tell whether someone else saved them since. */
+    base: FormValues;
+    /** When the draft was saved (milliseconds since 1970). */
+    savedAt: number;
+}
+/** Drafts older than this are dropped when read: 30 days. */
+export declare const FORM_DRAFT_MAX_AGE: number;
+/** The draft kept under `key`, or `null`. A draft older than `maxAge` is dropped. */
+export declare function readFormDraft(key: string, maxAge?: number): Promise<FormDraft | null>;
+/** Keeps a draft under `key`. Resolves `true` once it is stored. */
+export declare function writeFormDraft(key: string, draft: FormDraft): Promise<boolean>;
+/** Removes the draft kept under `key`, if any. */
+export declare function deleteFormDraft(key: string): Promise<void>;

package/dist/Helpers/FormDrafts.js

@@ -0,0 +1,76 @@
+const DB_NAME = "nexus-forms";
+const STORE_NAME = "drafts";
+/** Drafts older than this are dropped when read: 30 days. */
+export const FORM_DRAFT_MAX_AGE = 30 * 24 * 60 * 60 * 1000;
+let database = null;
+function openDatabase() {
+    if (typeof indexedDB === "undefined")
+        return Promise.resolve(null);
+    database ??= new Promise(resolve => {
+        try {
+            const request = indexedDB.open(DB_NAME, 1);
+            request.onupgradeneeded = () => request.result.createObjectStore(STORE_NAME);
+            request.onsuccess = () => {
+                const db = request.result;
+                // Another tab upgrading the database closes this connection; the next call opens a new one.
+                db.onversionchange = () => {
+                    db.close();
+                    database = null;
+                };
+                resolve(db);
+            };
+            request.onerror = () => resolve(null);
+            request.onblocked = () => resolve(null);
+        }
+        catch {
+            resolve(null);
+        }
+    });
+    return database;
+}
+function run(mode, work) {
+    return openDatabase().then(db => new Promise(resolve => {
+        if (!db)
+            return resolve(null);
+        try {
+            const transaction = db.transaction(STORE_NAME, mode);
+            const request = work(transaction.objectStore(STORE_NAME));
+            transaction.oncomplete = () => resolve(request.result ?? null);
+            transaction.onerror = () => resolve(null);
+            transaction.onabort = () => resolve(null);
+        }
+        catch {
+            resolve(null);
+        }
+    }));
+}
+function isDraft(value) {
+    const draft = value;
+    return Boolean(draft && typeof draft === "object" && draft.values && typeof draft.values === "object" && typeof draft.savedAt === "number");
+}
+/** The draft kept under `key`, or `null`. A draft older than `maxAge` is dropped. */
+export async function readFormDraft(key, maxAge = FORM_DRAFT_MAX_AGE) {
+    const found = await run("readonly", store => store.get(key));
+    if (!isDraft(found))
+        return null;
+    if (Date.now() - found.savedAt > maxAge) {
+        void deleteFormDraft(key);
+        return null;
+    }
+    return { values: found.values, base: found.base ?? {}, savedAt: found.savedAt };
+}
+/** Keeps a draft under `key`. Resolves `true` once it is stored. */
+export async function writeFormDraft(key, draft) {
+    try {
+        const done = await run("readwrite", store => store.put(draft, key));
+        return done !== null;
+    }
+    catch {
+        // Values the browser cannot store (a function in a value) keep no draft.
+        return false;
+    }
+}
+/** Removes the draft kept under `key`, if any. */
+export async function deleteFormDraft(key) {
+    await run("readwrite", store => store.delete(key));
+}

package/dist/Helpers/FormStore.d.ts

@@ -0,0 +1,233 @@
+import type { FormErrors, FormRuleResult, FormValues, InputParams, InputValidationContext } from "../Interfaces/FormInterfaces.ts";
+export interface FormStoreOptions<TValues extends FormValues = FormValues> {
+    inputs: readonly InputParams[];
+    validate?(values: TValues): FormRuleResult;
+    onFieldChange?(name: string, value: unknown, values: TValues): Partial<TValues> | null | undefined | void;
+    /** The user's date settings, so messages write dates the way the fields show them. */
+    context?: InputValidationContext;
+    /** The whole form is read-only or disabled: nothing is checked. */
+    locked?: boolean;
+    /** Unsaved changes are kept on this device under this key. */
+    draftKey?: string;
+}
+/** A draft brought back when the form opened. */
+export interface FormRestoredDraft {
+    /** When the draft was saved (milliseconds since 1970). */
+    savedAt: number;
+    /** The inputs it brought back, in form order. */
+    names: readonly string[];
+    /** Of those, the ones whose saved value changed since the draft was made: someone else saved them. */
+    conflicts: readonly string[];
+}
+/** What the form's frame shows: the status line, the buttons, and the restored-draft notice. */
+export interface FormStatus {
+    /** Some value differs from the ones the form opened with or saved last. */
+    changed: boolean;
+    /** A submit is running. */
+    submitting: boolean;
+    /** The values are loading: the inputs show placeholders. */
+    loading: boolean;
+    /** A submit ran and found problems: every message shows. */
+    showAll: boolean;
+    /** Inputs that need attention after a submit or a server's answer, in form order. */
+    problems: readonly string[];
+    /** A message about the whole form: the form's own rule after a submit, or a server's. */
+    message: string | null;
+    /** When the values were saved last. */
+    savedAt: number | null;
+    /** When the unsaved changes were last kept as a draft on this device. */
+    draftSavedAt: number | null;
+    /** A draft brought back when the form opened, until it is discarded, dismissed, or saved. */
+    restored: FormRestoredDraft | null;
+    /** The id of the `<form>` element, for Save buttons outside it. */
+    formId: string | null;
+    /** How many `FormButtons` show this form's status. Without any, the form shows its own message. */
+    buttons: number;
+}
+/** The form on the page, attached by the `Form` component. */
+export interface FormView {
+    /** Checks the inputs on the page as a submit does: every message shows, and the first problem takes focus. Returns the inputs with problems. */
+    validate: () => string[];
+    /** Focuses an input by name, or the first one. */
+    focus: (name?: string) => void;
+}
+/** A store of any values, for code that works with every form (a hook, a bar of buttons). */
+export type AnyFormStore = FormStore<any>;
+export declare class FormStore<TValues extends FormValues = FormValues> {
+    private options;
+    private inputByName;
+    private values;
+    private initial;
+    private isStarted;
+    private ruleErrors;
+    /** Rows inputs are checked when asked: 10,000 rows on every keystroke would be slow, and the rows check themselves. */
+    private staleRules;
+    private crossErrors;
+    private crossMessage;
+    private serverErrors;
+    private serverMessage;
+    private forced;
+    private touched;
+    private showAll;
+    /** Inputs the page found problems in on the last submit. */
+    private attention;
+    private changedNames;
+    private revisions;
+    private generation;
+    private versions;
+    private fieldListeners;
+    private statusListeners;
+    private valueListeners;
+    private status;
+    private draftTimer;
+    /** The draft key already looked up. Drafts are written only after, so an old draft is never overwritten unread. */
+    private draftChecked;
+    private draftSeq;
+    /** The user cancelled: no draft is written until they change a value again. */
+    private draftDropped;
+    /** A load during a render tells nobody; `announce` does, once the form has mounted. */
+    private quiet;
+    private unannounced;
+    /** The form on the page. Set by `Form`. */
+    view: FormView | null;
+    /** Submits the `<form>`, as its Save button does. Set by `SubmitForm`. */
+    submitter: (() => void) | null;
+    /** Whether the form has loaded its first values. */
+    get started(): boolean;
+    get inputs(): readonly InputParams[];
+    /** Every value, plus the fields the record came with. The same object until something changes; do not change it. */
+    getValue(): TValues;
+    get(name: string): unknown;
+    /** The values the form opened with, or saved last. */
+    getInitial(): TValues;
+    /** Only the values that differ from the ones the form opened with or saved last. */
+    getChanges(): Partial<TValues>;
+    /** The inputs whose values changed, in form order. */
+    changedInputs(): string[];
+    isChanged(): boolean;
+    getStatus: () => FormStatus;
+    /** The message an input shows for the form: a server's, the form's rule once the input was left or a submit ran, or its own rule after a submit its input missed. */
+    shownError(name: string): string | undefined;
+    /** The shown message, with the form's rule messages given, such as the ones before a change. */
+    private shownWith;
+    /** The input's own rule message for its value, whether it shows or not. */
+    ruleError(name: string): string | null;
+    /** The form's own rule message for an input, whether it shows or not. */
+    formRuleError(name: string): string | null;
+    /** The form's own rule message about the whole form. */
+    get formRuleMessage(): string | null;
+    /** Inputs whose values break a rule, their own or the form's, in form order. Inputs on the page may find more, such as text that is not a date yet. */
+    problems(): string[];
+    /** Whether every value passes, as far as the values tell. `validate()` also asks the inputs on the page. */
+    isValid(): boolean;
+    /** Changes whenever the input must render again: a new value from code, or a message it shows. */
+    fieldVersion(name: string): number;
+    /** The input's render stamp: it mounts again when this changes, to show a value that did not come from typing. */
+    stamp(name: string): string;
+    subscribeField(name: string, listener: () => void): () => void;
+    subscribeStatus: (listener: () => void) => (() => void);
+    /** Every value after each change. `name` is the input the user changed, or `null` for a load, a reset, or several at once. */
+    subscribeValue: (listener: (values: TValues, name: string | null) => void) => (() => void);
+    /**
+     * New inputs or rules. `recheck` checks every value again (the form does after a change of inputs or settings);
+     * without it, only the callbacks are swapped, which a parent's render does every time.
+     */
+    configure(options: FormStoreOptions<TValues>, recheck?: boolean): void;
+    /**
+     * Loads values, such as a record from a server. They become the values the form compares with, and every input shows
+     * them. With `keepChanged`, the values the user changed stay (a refresh that merges): only the others change, and the
+     * names returned are the changed values whose loaded ones also changed, so the page can say so. `draft: false` leaves
+     * a saved draft for a later load (the form's placeholders show while the real values load). `quiet` tells no listener
+     * until `announce()`, for a load during a render.
+     */
+    load(values?: Partial<TValues>, { keepChanged, draft, quiet }?: {
+        keepChanged?: boolean;
+        draft?: boolean;
+        quiet?: boolean;
+    }): string[];
+    /** Tells listeners about a quiet load. */
+    announce(): void;
+    private loadValues;
+    /** Brings back the values the form opened with or saved last, and clears every message. The draft goes too. */
+    reset(): void;
+    /** Sets a value from code. Its input shows it at once, and it counts as a change. */
+    set(name: string, value: unknown): void;
+    /** Sets several values from code, as one change. */
+    setValues(values: Partial<TValues>): void;
+    /**
+     * A value the user typed or picked, from the input rendered with `stamp`. An input that was replaced since (by a value
+     * from code, a load, or a reset) can still report its last value as it leaves; that value is ignored.
+     */
+    input(name: string, value: unknown, stamp: string): void;
+    /** Marks an input as left by the user: the form's rule messages on it show from now on. */
+    touch(name: string): void;
+    /**
+     * Shows messages from outside, such as a server's, on their inputs, with a message for the whole form. They replace
+     * the ones shown before; an input's message clears once its value changes. Names that are not inputs join the form's message.
+     */
+    setErrors(errors?: FormErrors, message?: string | null): void;
+    /** Clears the messages set with `setErrors`. */
+    clearErrors(): void;
+    /** Checks every value as a submit does: every message shows, and the first problem takes focus. Returns whether all is valid. */
+    validate(): boolean;
+    /** Focuses an input by name, or the form's first input. */
+    focus(name?: string): void;
+    /** Submits the form as its Save button does. Only a `SubmitForm` or an `ApiForm` can. */
+    submit(): void;
+    /** Writes the draft now, e.g. when the page is hidden. With nothing changed, the draft is removed. */
+    flushDraft(): void;
+    /** Puts back the values of the draft brought back when the form opened, and removes the draft. */
+    discardDraft(): void;
+    /** Hides the notice of a restored draft and keeps its values. */
+    dismissDraft(): void;
+    /** Removes the draft and leaves the values as they are, e.g. when the user cancels. Drafts start again with the next change. */
+    dropDraft(): void;
+    /** @internal Shows every message, as a submit does. `forced` are inputs whose own messages missed a problem their values have. */
+    reveal(problems: string[], forced?: readonly string[]): string[];
+    /** @internal The inputs the page finds problems in, as values change after a submit. */
+    setAttention(names: string[]): void;
+    /** @internal A submit starts: messages from the last answer go. */
+    beginSubmit(): void;
+    /** @internal A submit ended without a save. */
+    endSubmit(): void;
+    /**
+     * @internal A save: the values sent become the ones the form compares with; values typed while it ran stay changes.
+     * `extra` (from the server, such as a new id) is set on top.
+     */
+    commit(saved: TValues, extra?: Partial<TValues>): void;
+    /** @internal A save after which the form went back to its opening values (`resetOnSuccess`). */
+    markSaved(): void;
+    /** @internal */
+    setLoading(loading: boolean): void;
+    /** @internal */
+    setFormId(formId: string | null): void;
+    /** @internal A `FormButtons` shows the status; returns its removal. */
+    addButtons(): () => void;
+    private indexInputs;
+    /** Each input's value in the type the input reports; a missing one is the input's default. Other fields stay as they came. */
+    private normalize;
+    /** 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` names any of `names`. */
+    private followersOf;
+    private checkRule;
+    private checkAllRules;
+    /** Runs the form's own rule; returns the inputs whose message from it changed. */
+    private checkCross;
+    private clearMessages;
+    /** The form's message: a server's, or the form's own rule once a submit ran. */
+    private formMessage;
+    /** Inputs to point at: the ones the page found on the last submit, and those with a server's message, in form order. */
+    private problemList;
+    private nextRevision;
+    private bump;
+    private bumpAll;
+    private shownSnapshot;
+    private bumpShownChanges;
+    private patchStatus;
+    private emit;
+    private scheduleDraft;
+    /** Looks for a draft under the form's key and brings back its values, except those the user changed since the form opened. */
+    private restoreDraft;
+}