nexus-shared 3.2.0 → 4.1.0

package/dist/Helpers/FormStore.d.ts

@@ -1,4 +1,5 @@
 import type { FormErrors, FormRuleResult, FormValues, InputParams, InputValidationContext } from "../Interfaces/FormInterfaces.ts";
+import { type InputMemoryStorage } from "./InputMemory.ts";
 export interface FormStoreOptions<TValues extends FormValues = FormValues> {
     inputs: readonly InputParams[];
     validate?(values: TValues): FormRuleResult;
@@ -58,6 +59,21 @@ export declare class FormStore<TValues extends FormValues = FormValues> {
     private inputByName;
     private values;
     private initial;
+    /** The values the last load was given, as given: an input they name with a value is the form's own, never remembered. */
+    private given;
+    /** Where remembered inputs (`remember`) are read and kept; set by the form that draws this store, in the browser. */
+    private memory;
+    /** Pickers asked whether they still offer a remembered value; the next opening (a load, a reset) or a submit stops it. */
+    private memoryRound;
+    /** The inputs whose picker is being asked: drawn loading, and a change to one (the person's pick, code) ends its ask. */
+    private asking;
+    /** The values memory opened inputs on: an opening that finds nothing (a reset after the choice went) takes its own back. */
+    private fromMemory;
+    /**
+     * The values a load (or a reset, a draft) is working out, while it works them out: what `get` answers then, so an
+     * input's live `hidden` (`showWhen`) is judged on the values the form opens with, never on the ones it had before.
+     */
+    private reading;
     private isStarted;
     private ruleErrors;
     /** Rows inputs are checked when asked: 10,000 rows on every keystroke would be slow, and the rows check themselves. */
@@ -87,6 +103,8 @@ export declare class FormStore<TValues extends FormValues = FormValues> {
     private draftDropped;
     /** An input reported a value while the values loaded and was refused: it is drawn again from the store when loading ends. */
     private refusedWhileLoading;
+    /** What a choice input reported beside the value the user picked last (`pickedItem`): its item, kept with that value. */
+    private picked;
     /** A load during a render tells nobody; `announce` does, once the form has mounted. */
     private quiet;
     private unannounced;
@@ -100,6 +118,8 @@ export declare class FormStore<TValues extends FormValues = FormValues> {
     /** 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 params of the input of this name, as the form was given them; undefined for a name no input has. */
+    inputParams(name: string): InputParams | undefined;
     /** 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. */
@@ -107,11 +127,23 @@ export declare class FormStore<TValues extends FormValues = FormValues> {
     /** The inputs whose values changed, in form order. */
     changedInputs(): string[];
     isChanged(): boolean;
+    /**
+     * Whether the changes are worth asking about before they are dropped (Cancel, closing a popup, leaving the page): a
+     * changed value of any input but a password or a one-time code (`keepsTyping`). A form where only those were typed is
+     * changed, and Save and its line say so, but nothing asks before it goes.
+     */
+    isWorthKeeping(): 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 item a choice input reported with the value it holds now, when the user picked that value: a dropdown's option
+     * (its options, with `multiple`). `undefined` for a value loaded, set from code, or changed since - so what it answers
+     * always goes with the value. A CRUD names what a save joined from it (`crudJoinedNames`).
+     */
+    pickedItem(name: string): unknown;
     /** 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. */
@@ -152,17 +184,28 @@ export declare class FormStore<TValues extends FormValues = FormValues> {
     /** 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. */
+    /**
+     * Brings back the values the form opened with or saved last, and clears every message. The draft goes too. A
+     * remembered input opens on the choice kept now, so a form reset after a save starts on what was just saved.
+     */
     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.
+     * Values a person set through another input - one worked out from them and typed in (`compute.solve`) - as one change.
+     * Their inputs show them at once, as values from code do, and they are taken as the person's own: the form's
+     * `onFieldChange` runs for them, and inputs narrowed by them lose what they picked. Nothing is taken while the values
+     * load. Answers whether anything changed.
+     */
+    setFromPerson(values: Partial<TValues>): boolean;
+    /**
+     * A value the user typed or picked, from the input rendered with `stamp`, with what a choice input reported beside it
+     * (`item`: a dropdown's option, kept for `pickedItem`). 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;
+    input(name: string, value: unknown, stamp: string, item?: unknown): void;
     /** Marks an input as left by the user: the form's rule messages on it show from now on. */
     touch(name: string): void;
     /**
@@ -199,6 +242,28 @@ export declare class FormStore<TValues extends FormValues = FormValues> {
      * `extra` (from the server, such as a new id) is set on top.
      */
     commit(saved: TValues, extra?: Partial<TValues>): void;
+    /**
+     * @internal Whether the input's picker is being asked whether it still offers a remembered value: the input draws
+     * loading until it answers, the person picks, or the form opens again.
+     */
+    isRemembering(name: string): boolean;
+    /**
+     * @internal The browser storage remembered inputs read and keep (`InputLayoutParams.remember`), set by the form that
+     * draws this store once it is in the browser. Inputs the values left without one open on it at once (as the values
+     * the form opened with), a picker once it answers that it still offers the value; a form drawn on a server opened
+     * without it, so nothing differs while it hydrates.
+     */
+    attachMemory(storage: InputMemoryStorage | null): void;
+    /**
+     * Inputs that follow ones memory opened (`dependsOn`: a `compute.from`, `showWhen`, `spanWhen`, `labelWhen`, or a
+     * `narrowedBy`) draw again with their params read afresh, as after a change: a cell redraws only on its own bump.
+     */
+    private bumpFollowers;
+    /**
+     * @internal A save: each remembered input keeps the value saved (an empty one forgets), for the next form that asks -
+     * under the saved values' `per` value, and only where its `when` holds on them.
+     */
+    rememberSaved(values: TValues): void;
     /** @internal A save after which the form went back to its opening values (`resetOnSuccess`). */
     markSaved(): void;
     /** @internal While the values load, nothing typed is taken (`input`), and a submit waits (`SubmitForm`). */
@@ -210,10 +275,40 @@ export declare class FormStore<TValues extends FormValues = FormValues> {
     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;
+    /** Runs `work` with `get` answering from these values (a load's, a reset's, a draft's), and gives back its answer. */
+    private readingFrom;
+    /**
+     * The values with each remembered input the given values leave without one opened on the company's preferred value
+     * or the person's last choice (`rememberedOpeningNow`), its `when` and `per` read among these values; without storage
+     * (on a server, before the form is drawn) only a preferred value applies. A kept choice no longer offered is forgotten.
+     * A picker that must be asked first opens nothing now: it is asked, and its answer opens the input later
+     * (`askPickers`) - the round any earlier opening started stops here. An input memory opened before (a reset after a
+     * save, the storage arriving) that now opens on nothing takes the value the given values give it back.
+     */
+    private openRemembered;
+    /** Stops asking pickers about remembered values: their answers no longer open anything, and their inputs stop loading. */
+    private stopAskingPickers;
+    /**
+     * Asks each picker whether it still offers the remembered value (`findRememberedOpening`), the input drawn loading
+     * meanwhile. An answer forgets a choice no longer offered, and opens an offered one (`openAsked`) only while the input
+     * is still asked about - no pick, no value from code since - and the values it was judged on (`rememberDependencies`:
+     * the group that narrows it, the one it is kept per, its `when`) are still the form's: a group changed meanwhile opens
+     * nothing.
+     */
+    private askPickers;
+    /**
+     * A picker answered for a remembered value: the input opens on it, as the value the form opened with (not a change) -
+     * only while it is as the form opened it and still on the form. One the person typed in, or a draft gave back, keeps
+     * what it has.
+     */
+    private openAsked;
     /** 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`. */
+    /**
+     * The inputs whose `dependsOn` (or `narrowedBy`) names any of `names`, and the rows inputs whose row inputs are narrowed
+     * by one of them `from: "form"`: their rows draw again with the form's value as it is now.
+     */
     private followersOf;
     private checkRule;
     private checkAllRules;