nexus-shared 1.1.20 → 2.0.0

package/dist/Helpers/FormStore.d.ts

@@ -0,0 +1,231 @@
+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;
+    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;
+}