nexus-shared 1.1.20 → 2.0.0

package/dist/Helpers/RowsStore.d.ts

@@ -0,0 +1,160 @@
+import type { InputParams, InputValidationContext, RowsInputProps, RowValue } from "../Interfaces/FormInterfaces.ts";
+export type RowsStoreOptions<TRow extends RowValue = RowValue> = Pick<RowsInputProps<TRow>, "inputs" | "required" | "min" | "max" | "unique" | "validate" | "itemLabel" | "itemLabelPlural" | "rowKey" | "newRow" | "onRowChange"> & {
+    /** The row's name when there is no `itemLabel`: "Row" in a table, "Item" in sections. */
+    fallbackItem?: string;
+    /** The user's date settings, so messages write dates the way the fields show them. */
+    context?: InputValidationContext;
+};
+/** What a rows input renders from, replaced whenever it changes. */
+export interface RowsSnapshot {
+    /** The rows' keys, in order. */
+    keys: readonly string[];
+    /** Grows when every row is loaded again (`replace`, `reset`): rows render anew with their loaded values. */
+    generation: number;
+    /** The rows' own message, once it shows: after a check, or once a row was added, removed, or moved. */
+    message: string | null;
+    /** Every message shows, after `validateAll` (a submit). */
+    showAll: boolean;
+    /** Rows with a value that fails, once messages show. */
+    invalidRows: number;
+    /** The row `undoRemove` can put back: its position, from 0. */
+    removed: {
+        index: number;
+    } | null;
+}
+/** Where the first problem is: a value in a row, or the rows' own message. */
+export type RowsProblemPlace = {
+    key: string;
+    name: string;
+} | {
+    key: null;
+    name: null;
+};
+export declare class RowsStore<TRow extends RowValue = RowValue> {
+    private options;
+    private inputByName;
+    private entries;
+    private positions;
+    private initial;
+    private seq;
+    private generation;
+    private ruleErrors;
+    private duplicateErrors;
+    private invalidByRow;
+    private invalidCells;
+    private message;
+    private messageShown;
+    private showAll;
+    private touched;
+    private removed;
+    private revisions;
+    private versions;
+    private rowListeners;
+    private listeners;
+    private valueListeners;
+    private snapshot;
+    private valueCache;
+    private keysCache;
+    private dirtyUnique;
+    /** The array last given to value listeners. A controlled parent that passes it back changes nothing. */
+    lastValue: readonly TRow[] | null;
+    constructor(options: RowsStoreOptions<TRow>, rows?: readonly TRow[]);
+    /** Every row as it is now. The same array until something changes; do not change it. */
+    getValue(): TRow[];
+    getSnapshot: () => RowsSnapshot;
+    get count(): number;
+    get inputs(): readonly InputParams[];
+    /** The item's names for titles and messages. */
+    get names(): {
+        title: string;
+        item: string;
+        items: string;
+    };
+    indexOf(key: string): number;
+    keyAt(index: number): string | null;
+    row(key: string): TRow | undefined;
+    get(key: string, name: string): unknown;
+    /** Grows when a value was set from code; an input renders again from the store with a new one. */
+    revision(key: string, name: string): number;
+    /** Grows whenever what a row shows changes: a message, or a value set from code. */
+    version(key: string): number;
+    /** The message a value shows now: every message after `validateAll`; before, a repeated value once its input was left. */
+    shownError(key: string, name: string): string | undefined;
+    /** How many values in a row fail. */
+    rowProblems(key: string): number;
+    /** Whether any value or the rows' own rules fail, shown or not. */
+    hasProblems(): boolean;
+    /** The first problem in row order, then the rows' own message; `null` when all is valid. */
+    firstProblem(): RowsProblemPlace | null;
+    /** The first problem's message, named with its row: "Address 2: City is required." */
+    firstMessage(): string | null;
+    /** Whether the rows differ from the ones loaded last (`replace`) or first. */
+    isChanged(): boolean;
+    /** Structure: the rows, their order, and the rows' own message. */
+    subscribe: (listener: () => void) => (() => void);
+    /** One row: its messages and the values set from code. */
+    subscribeRow(key: string, listener: () => void): () => void;
+    /** Every row, after each change of a value or of the rows. */
+    subscribeValue(listener: (rows: TRow[]) => void): () => void;
+    /**
+     * New rules or inputs. `recheck` checks every value again (after a change of inputs or rules); without it, only the
+     * callbacks (`validate`, `onRowChange`, `newRow`) are swapped, which a parent's render does every time.
+     */
+    configure(options: RowsStoreOptions<TRow>, recheck?: boolean): void;
+    /** Sets a value in a row. `input` is a change the user made in the row's input: it runs `onRowChange`. */
+    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. */
+    add(values?: Partial<TRow>, index?: number): string;
+    /** 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;
+    /** Removes a row. A radio it had on moves to the first row left. `undoRemove` puts it back. */
+    remove(key: string): void;
+    /** Puts the last removed row back where it was. Returns its key, or `null` when there is nothing to undo. */
+    undoRemove(): string | null;
+    /** Moves a row to a new position. */
+    move(key: string, toIndex: number): void;
+    /**
+     * Loads new rows, e.g. fresh data from a server. With `asInitial` (default), they become the rows `reset` and
+     * `isChanged` compare with. `emit` tells value listeners, for a change the parent does not know of yet.
+     */
+    replace(rows: readonly TRow[], { asInitial, emit }?: {
+        asInitial?: boolean;
+        emit?: boolean;
+    }): void;
+    /** Back to the rows loaded last, as a form reset does. */
+    reset(): void;
+    /** Shows every message, as a submit does. Returns the first problem, or `null` when all is valid. */
+    validateAll(): RowsProblemPlace | null;
+    private indexInputs;
+    private newKey;
+    /** Each input's value in the type the input reports, and the other fields of the row as they came. */
+    private normalizeRow;
+    private load;
+    private afterStructure;
+    /** Drops what the store knew about a removed row. */
+    private forget;
+    private write;
+    /** Turns a radio off in every row but this one. */
+    private radioOn;
+    /** Checks one value against its input's rules. */
+    private checkCell;
+    private setError;
+    private isInvalid;
+    private markUniqueDirty;
+    /**
+     * Finds repeated values in one `unique` input. Every row with the value gets a message, so the one just edited says
+     * so: the first row names the second, the others name the first.
+     */
+    private checkUnique;
+    private checkEverything;
+    /** After a change: repeated values, the rows' own message, the rows to render again, and value listeners. */
+    private settle;
+    private bump;
+    private touchAllRows;
+    private emit;
+    private buildSnapshot;
+    /** Replaces the snapshot when what it holds changed, and tells structure listeners. */
+    private refresh;
+}