@fieldia/core 0.10.0 → 0.12.0

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

@@ -0,0 +1,248 @@
+import type { ActionStep, OpenStep, PanelSide } from '../format/actions';
+import type { Field } from '../format/field';
+import type { JsonValue } from '../format/json';
+import type { Tone } from '../format/layout';
+import { type ExpressionEnv } from '../expression/expression';
+import type { ResolvedFilter } from './data-source';
+import { type RecordId, type Values } from './values';
+/**
+ * The engine that runs steps — a button's, a moment's, or the app's own —
+ * against a form. Steps run in order; one whose `when` does not hold is
+ * passed over; the first that fails or is refused stops the rest, and the
+ * run's result says which and why. What the core cannot draw — a page opened,
+ * words said, a question asked — it asks of the host the viewer gives.
+ */
+/** A button pressed, or a `call` step run: what the app's `onAction` is handed. */
+export interface ActionRequest {
+    /** The button or stat button pressed; for a moment, `on.open`, `on.change.<field>`, `on.beforeSave`, `on.afterSave` or `on.show.<id>`; for `form.run`, the id it was given. */
+    id: string;
+    action: string;
+    params?: {
+        [key: string]: JsonValue;
+    };
+    recordId: RecordId | null;
+    values: Values;
+    /** The records chosen in a list, when the button belongs to one. */
+    recordIds?: RecordId[];
+    /** The line a button on a table's line was pressed on: the table's field, the line's key and values. */
+    line?: {
+        field: string;
+        key: string;
+        values: Values;
+    };
+    /** The lines chosen in a table when a button for them was pressed: the table's field, their keys, the ids of those saved, and their values. */
+    lines?: ChosenLines;
+}
+/** Lines chosen in a table, as a button for them hands them on. */
+export interface ChosenLines {
+    field: string;
+    keys: string[];
+    /** The saved records among them, by id: a new line has none yet. */
+    ids: RecordId[];
+    values: Values[];
+}
+/**
+ * What the app may answer a call with. Nothing at all means go on. `values`
+ * are set as a `set` step sets them (no person's change); `say` is said;
+ * `open` runs as an `open` step would; `stop` stops the steps after it — with
+ * words, said to the person as a warning.
+ */
+export interface ActionResult {
+    values?: Values;
+    /** The app changed the record on its server: it is loaded again before the steps go on. */
+    reload?: boolean;
+    say?: string | {
+        message: string;
+        tone?: Tone;
+    };
+    open?: Omit<OpenStep, 'do' | 'when'>;
+    /**
+     * Show this record in the form's place from now on, as the pager moves to
+     * one — the copy a duplicate made, the record a server action made — or a
+     * new one for null. Changes not saved are dropped.
+     */
+    record?: RecordId | null;
+    /** Post words in the record's conversation, as a `post` step does: a note unless it is a `message`. */
+    post?: string | {
+        message: string;
+        kind?: 'note' | 'message';
+    };
+    stop?: boolean | string;
+}
+/** Words posted in a record's conversation by a `post` step or the app's answer. */
+export interface PostedMessage {
+    kind: 'note' | 'message';
+    /** The words as typed, each `{field}` filled in. */
+    text: string;
+    /** The same as HTML: every character escaped, each line its own. An html field's value comes as it is. */
+    body: string;
+}
+/** What a button does that only the app can: handed over, and awaited. */
+export type OnAction = (request: ActionRequest) => void | ActionResult | Promise<void | ActionResult>;
+/** A page the host is asked to open: in a dialog over the form, a panel beside it, or in its place. */
+export interface OpenRequest {
+    /** The page's id, as the app's `pages` finds it. */
+    page: string;
+    /** One published version; left out, the latest. */
+    version?: number;
+    as: 'dialog' | 'panel' | 'page';
+    /** Where a panel comes from, when its step names a side: the end of the line unless told. */
+    side?: PanelSide;
+    /** The words over it; left out, the page's own title. */
+    title?: string;
+    /** The record to open; null for a new one. */
+    recordId?: RecordId | null;
+    /** What a new one starts with. */
+    values?: Values;
+    /** On a list page, the records it shows: each `valueFrom` already read from the form that opened it. */
+    filter?: ResolvedFilter[];
+}
+/** How an opened page ended: saved (or sent), or closed without. */
+export interface OpenResult {
+    saved: boolean;
+    /** The record it saved. */
+    recordId?: RecordId | null;
+    /** Its values, once saved. */
+    values?: Values;
+    /** The saved record's name, as its page's title field shows it: what a link set to it is labelled. */
+    label?: string;
+}
+/**
+ * The UI the core cannot draw, given by the viewer. Without one, a form says
+ * nothing, asks `FormOptions.confirm` (or goes on as though answered Yes), and
+ * cannot open, close or show a tab: those steps stop with reason `cannot`.
+ */
+export interface ActionHost {
+    open(request: OpenRequest): Promise<OpenResult>;
+    say(message: string, tone: Tone): void;
+    ask(message: string): Promise<boolean>;
+    /** Close the dialog or panel this form was opened in. */
+    close?(): void;
+    /** Show a tab by its id. The viewer then calls `form.shown(id)`, as for a tab a person picks. */
+    show?(target: string): void;
+    /** Open a web address: in a new tab, or in this one. */
+    openUrl?(url: string, newTab: boolean): void;
+    /**
+     * Post words in a record's conversation. Left out, the form tells its own
+     * listeners (`post`): the chatter beside it. A page opened over a record
+     * is given one that posts in that record's. False: nothing heard them.
+     */
+    post?(message: PostedMessage): boolean | void | Promise<boolean | void>;
+}
+/**
+ * Why a run stopped: a check found problems (`check`), a question was
+ * answered No (`no`), a save was refused (`save`), the app said stop or threw
+ * (`app`), an opened page was closed without saving (`closed`), or the step
+ * could not run here — no host to open with, a field the page lacks
+ * (`cannot`).
+ */
+export type RunStop = 'check' | 'no' | 'save' | 'app' | 'closed' | 'cannot';
+/** How a run of steps ended. */
+export interface RunResult {
+    /** Every step ran, or was passed over by its `when`. */
+    done: boolean;
+    /**
+     * The place, among the steps run, of the one that stopped: for a step of
+     * an `open`'s `then`, the open step's place; for a button's `action`, one
+     * past its steps. Absent when a button's `confirm` was answered No.
+     */
+    stoppedAt?: number;
+    /** The step that stopped, wherever it was. */
+    step?: ActionStep;
+    reason?: RunStop;
+    /** Why, in words: the first problem found, the question, the save's or the app's words. */
+    message?: string;
+    /** What the app or the host threw, when that stopped it. */
+    error?: unknown;
+}
+/** What a run is for: the id calls carry, the records chosen in a list. */
+export interface RunContext {
+    id?: string;
+    recordIds?: RecordId[];
+}
+/** A step stopped: why, and which (a step of an `open`'s `then`, the deepest). */
+export interface Stopped {
+    reason: RunStop;
+    message?: string;
+    step?: ActionStep;
+    error?: unknown;
+}
+/** A run as it goes: its id, the records chosen, and the moments it was set off by — a moment one of them sets off again does not run. */
+export interface RunScope {
+    id: string;
+    recordIds?: RecordId[];
+    line?: {
+        field: string;
+        key: string;
+        values: Values;
+    };
+    lines?: ChosenLines;
+    chain: readonly string[];
+}
+/** What a run reaches its form by: the form gives these. */
+export interface RunForm {
+    readonly fields: Readonly<Record<string, Field>>;
+    values(): Readonly<Values>;
+    recordId(): RecordId | null;
+    /** The values as expressions read them, and what else they read. */
+    reading(): {
+        context: Record<string, unknown>;
+        env: ExpressionEnv;
+    };
+    today(): string;
+    /** Write fields as a step does: worked out once, no person's change. Throws for a field the page lacks. */
+    write(values: Values): void;
+    addLine(field: string, values: Values): void;
+    check(fields: readonly string[] | undefined): Stopped | null;
+    save(chain: readonly string[]): Promise<Stopped | null>;
+    /** Load the record again from its data source; a new record cannot be. */
+    reload(): Promise<Stopped | null>;
+    reset(): void;
+    /** Go to a wizard's step; `undefined` when the target is none of its steps (a tab). */
+    goTo(target: string, chain: readonly string[]): Stopped | null | undefined;
+    /** Run `show` of the host while `chain` is the run's, so a tab it shows knows who showed it. */
+    showing(chain: readonly string[], show: () => void): void;
+    host?: ActionHost;
+    confirm?: (message: string) => boolean | Promise<boolean>;
+    onAction?: OnAction;
+    /** The app answered a call. */
+    answered(request: ActionRequest, result: ActionResult | undefined): void;
+    /** Whether something changed since the record was loaded or saved. */
+    changed(): boolean;
+    /**
+     * The record's own operations through the data source, each only when the
+     * data source has it; without, the app's action of the step's name is called.
+     */
+    archive?(archive: boolean): Promise<void>;
+    copy?(): Promise<RecordId>;
+    remove?(): Promise<void>;
+    /** Show another record in this form's place, loaded as a pager loads it; a new one for null. */
+    showRecord(id: RecordId | null): Promise<Stopped | null>;
+    /** The record was archived (or brought back), copied, or deleted: told to the app. Deleted, the form leaves it unless a listener moved it on. */
+    told(event: {
+        archived: boolean;
+    } | {
+        copied: RecordId;
+    } | {
+        deleted: true;
+    }, id: RecordId): void;
+    /** Post words in the record's conversation: false when nothing here can. */
+    post(message: PostedMessage): Promise<boolean>;
+    /** A field's value as words in a posted message: a link's name, a choice's label. */
+    wordsOf(field: string): string;
+}
+export declare const DONE: RunResult;
+/** Steps run against one form. Expressions are read once and kept. */
+export declare function createRunner(form: RunForm): {
+    runSteps: (steps: readonly ActionStep[], scope: RunScope) => Promise<RunResult>;
+    ask: (message: string) => Promise<boolean>;
+};
+/**
+ * One run of each moment at a time. A moment set off by a step of its own
+ * run — or a run it set off — does not run. Set off while a run of it is
+ * going: `again` moments (open, change, show) run once more after it, with
+ * the values as they are then, however many times they were set off
+ * meanwhile; the others (beforeSave, afterSave) do not run — a save made
+ * meanwhile goes ahead without them, so nothing waits on itself.
+ */
+export declare function createMoments(run: (key: string, steps: readonly ActionStep[], chain: readonly string[]) => Promise<RunResult>): (key: string, steps: readonly ActionStep[] | undefined, chain: readonly string[], again: boolean) => Promise<RunResult>;