@fieldia/core 0.10.0 → 0.11.0

package/src/lib/record/form.d.ts

@@ -1,16 +1,17 @@
+import type { ActionStep } from '../format/actions';
 import type { Option } from '../format/field';
-import type { JsonValue } from '../format/json';
 import type { Page } from '../format/page';
 import { type Messages } from './messages';
 import { type DataSource, type RecordChanges, type SaveProblem } from './data-source';
 import { type Scheduler } from './scheduler';
+import { type ActionHost, type ActionRequest, type ActionResult, type OnAction, type RunContext, type RunResult } from './run';
 import { type RecordId, type RelatedRecord, type Value, type Values } from './values';
 export type FormStatus = 'idle' | 'loading' | 'ready' | 'saving' | 'saved' | 'error';
 export interface FormState {
     readonly status: FormStatus;
     readonly recordId: RecordId | null;
     readonly values: Readonly<Values>;
-    /** Messages by field name; a line's field is `field.lineKey.subfield`. */
+    /** Messages by field name; a line's field is `field.lineKey.subfield`, a saved form's field `name.field`. */
     readonly errors: Readonly<Record<string, string>>;
     /** Fields that differ from the record as loaded or last saved. */
     readonly dirty: readonly string[];
@@ -58,17 +59,47 @@ export interface DraftStore {
     setItem(key: string, value: string): void;
     removeItem(key: string): void;
 }
-export interface ActionRequest {
-    /** The button or stat button pressed. */
-    id: string;
-    action: string;
-    params?: {
-        [key: string]: JsonValue;
+export type { ActionRequest } from './run';
+/** Whose change it was: a person's (in the UI), a step's, or the app's (`setValues`, or `setValue` told so). Only a person's runs the page's `change` steps. */
+export type ChangeBy = 'person' | 'step' | 'app';
+/** What a form tells the app, by event: `form.on(event, listener)`. */
+export interface FormEvents {
+    /** A field was written: by a person, a step or the app. Values worked out from it are not told. */
+    change: {
+        field: string;
+        value: Value;
+        values: Readonly<Values>;
+        by: ChangeBy;
+    };
+    /** A record was saved. */
+    save: {
+        recordId: RecordId | null;
+        values: Readonly<Values>;
+    };
+    /** A page of responses sent its answers: those sent. */
+    send: {
+        values: Values;
+    };
+    /** The app answered a call: with nothing (undefined), or an `ActionResult`. */
+    action: {
+        request: ActionRequest;
+        result: ActionResult | undefined;
+    };
+    /** A run of steps ended — a button's, a moment's, `form.run`'s — and how. */
+    run: {
+        id: string;
+        steps: readonly ActionStep[];
+        result: RunResult;
+    };
+    /** A wizard's step was entered. */
+    step: {
+        step: string;
+    };
+    /** The form has its values: loaded, or new. */
+    open: {
+        recordId: RecordId | null;
+        values: Readonly<Values>;
     };
-    recordId: RecordId | null;
-    values: Values;
-    /** The records chosen in a list, when the button belongs to one. */
-    recordIds?: RecordId[];
 }
 export interface FormOptions {
     page: Page;
@@ -77,8 +108,17 @@ export interface FormOptions {
     recordId?: RecordId | null;
     /** Values to start with, on top of each field's default. */
     values?: Values;
-    /** What a button does. Fieldia hands the press over; the app decides. */
-    onAction?: (request: ActionRequest) => void | Promise<void>;
+    /**
+     * The app's own actions: a button's `action`, and each `call` step. Fieldia
+     * hands the request over and waits; the app may answer (`ActionResult`)
+     * with values to set, words to say, a page to open, or to stop. Nothing
+     * answered means go on.
+     */
+    onAction?: OnAction;
+    /** The UI the core cannot draw — pages opened, words said, questions asked — given by the viewer. */
+    host?: ActionHost;
+    /** How a question is asked when there is no host. Without either, a question goes on as though answered Yes. */
+    confirm?: (message: string) => boolean | Promise<boolean>;
     drafts?: {
         store: DraftStore;
         restore?: 'auto' | 'ask';
@@ -98,7 +138,12 @@ export interface Form {
     getState(): FormState;
     subscribe(listener: (state: FormState) => void): () => void;
     load(): Promise<void>;
-    setValue(name: string, value: Value): void;
+    /** Write a field: a person's change unless told otherwise, and only a person's runs the page's `change` steps. */
+    setValue(name: string, value: Value, how?: {
+        by?: ChangeBy;
+    }): void;
+    /** Write several fields at once, worked out once: the app's change, never a person's. Throws for a field the page lacks. */
+    setValues(values: Values): void;
     node(id: string): NodeState;
     fieldReadonly(name: string): boolean;
     /** What a field would be told if the form were checked now, or null when it passes. Nothing is shown. */
@@ -148,14 +193,37 @@ export interface Form {
      * an optional one instead.
      */
     goTo(step: string): boolean;
-    /** Run a button; a list's button passes the records chosen in it. */
+    /**
+     * Press a button: ask its `confirm` first, run its `steps`, then call its
+     * `action`, when it names one, as a final `call`. A list's button passes
+     * the records chosen in it, and every call of the run carries them.
+     */
     runAction(id: string, chosen?: {
         recordIds: RecordId[];
-    }): Promise<void>;
+    }): Promise<RunResult>;
+    /** Run steps on this form, as a button would: `context.id` is what their calls carry (`run` when left out). */
+    run(steps: readonly ActionStep[], context?: RunContext): Promise<RunResult>;
+    /** A tab was shown: the viewer says so, and the page's `show` steps for it run. */
+    shown(tab: string): void;
+    /** Listen to one of the form's events; returns what stops listening. */
+    on<E extends keyof FormEvents>(event: E, listener: (event: FormEvents[E]) => void): () => void;
     restoreDraft(): void;
     discardDraft(): void;
-    /** Resolves once every onchange, save and autosave started so far has finished. */
+    /** Resolves once every onchange, save, autosave and run of steps started so far has finished — a question still waiting for its answer included. */
     settled(): Promise<void>;
+    /**
+     * Give a saved form placed on this page (a `form` part, by its id) its page,
+     * once the app has found it. From then its answers sit under the part's
+     * name as an object, checked by that page's own rules: this form refuses
+     * to save or send while one of them fails, with the error under
+     * `name.field`, and shows it on the inner form beside its field. Returns the
+     * inner form, which a view draws the part's fields from; giving the page
+     * again returns the same one. A page placed inside itself, directly or
+     * through others, is refused.
+     */
+    embed(id: string, page: Page): Form;
+    /** The inner form of a saved form placed on this page, once it has its page; null until then. */
+    embedded(id: string): Form | null;
     dispose(): void;
 }
 /**