@fieldia/core 0.10.0 → 0.12.0

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

@@ -1,16 +1,19 @@
-import type { Option } from '../format/field';
-import type { JsonValue } from '../format/json';
+import type { ActionStep } from '../format/actions';
+import type { Field, LineField, Option, PropertyDefinition } from '../format/field';
 import type { Page } from '../format/page';
+import type { JsonValue } from '../format/json';
+import { type FieldTone, type LineState } from './cells';
 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 PostedMessage, 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[];
@@ -37,6 +40,16 @@ export interface FormState {
     readonly saveProblem: SaveProblem | null;
     /** The choices loaded from the app's lists, by field: those of a selection with `optionsFrom`, once asked for. */
     readonly choices: Readonly<Record<string, Choices>>;
+    /** The definitions loaded for a properties field with `definitionsFrom`, by field, once asked for. */
+    readonly definitions: Readonly<Record<string, Definitions>>;
+}
+/** A properties field's definitions from the app, as they load. */
+export interface Definitions {
+    /** The definitions last loaded: null until the first load ends well. */
+    readonly definitions: PropertyDefinition[] | null;
+    readonly loading?: boolean;
+    /** Why the last load failed. */
+    readonly error?: string;
 }
 /** A field's choices from one of the app's lists, as they load. */
 export interface Choices {
@@ -58,17 +71,69 @@ 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>;
+    };
+    /** The record was archived (`archived` true) or brought back, by a step. */
+    archive: {
+        recordId: RecordId;
+        archived: boolean;
+    };
+    /** The record was copied, by a step: the form shows the copy now. */
+    duplicate: {
+        from: RecordId;
+        recordId: RecordId;
+    };
+    /**
+     * The record was deleted, by a step. A listener may show another record
+     * (`openRecord`), as a pager moves on; else the form starts a new one.
+     */
+    delete: {
+        recordId: RecordId;
+    };
+    /** Words to post in the record's conversation, from a `post` step or the app's answer: the chatter beside it listens. */
+    post: {
+        recordId: RecordId | null;
+        message: PostedMessage;
     };
-    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 +142,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';
@@ -92,14 +166,55 @@ export interface FormOptions {
     messages?: Messages;
     /** The clock, for `today()` and for dates that must be past or future. The computer's own when left out. */
     now?: () => Date;
+    /**
+     * The person using the form: conditions read it as `user` (`user.id`,
+     * `user.name`, `user.roles`), and a part with `roles` shows only to people
+     * in them. Left out, the person has no id and no roles.
+     */
+    user?: FormUser;
+    /** Whether the record starts being edited, as conditions read `editing`; true unless said. A view locking it says so with `setEditing`. */
+    editing?: boolean;
+    /**
+     * Values the app passes in, as Flectra's context: read by conditions and
+     * expressions as `context.name`, and by a filter's `valueFrom:
+     * "context.name"` — a transfer opened from Receipts restricting its
+     * operation types. They are the app's, never the page's: nothing saves
+     * them, and a page's field of that name comes first.
+     */
+    context?: Readonly<Record<string, JsonValue>>;
+    /**
+     * The record this form's values are a line of, when the form edits one
+     * table's line in a form of its own (a node's `lineForm`): its values and
+     * fields, read by conditions and filters as `parent`, as a line's are —
+     * `parent.state`, a filter's `valueFrom: "parent.company_id"`.
+     */
+    parent?: {
+        values: Readonly<Values>;
+        fields: Readonly<Record<string, Field | LineField>>;
+        id?: RecordId | null;
+    };
+}
+/** The person using a form, as the app knows them. */
+export interface FormUser {
+    id: RecordId | null;
+    name?: string;
+    /** The roles they hold, by the names the page's `roles` use: Flectra's groups, such as `sales_team.group_sale_manager`. */
+    roles?: readonly string[];
 }
 export interface Form {
     readonly page: Page;
     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;
+    /** Whether the record is being edited, as conditions read `editing`: a view that locks it to be read says false, and parts follow. */
+    setEditing(editing: boolean): void;
     fieldReadonly(name: string): boolean;
     /** What a field would be told if the form were checked now, or null when it passes. Nothing is shown. */
     problem(field: string): string | null;
@@ -118,25 +233,68 @@ export interface Form {
      * written: the record, its changes and its autosave stay as they are.
      */
     previewLine(field: string, key: string, values: Values): Promise<Values>;
+    /**
+     * Show another record of the page's model in this form, loaded from the
+     * data source as a pager moves to it, or a new one for null. Changes not
+     * saved are dropped: save first. The page's `open` steps run for it.
+     */
+    openRecord(id: RecordId | null): Promise<void>;
+    /**
+     * Post words in the record's conversation, as a `post` step does: through
+     * the form's host when it has a way to, else told to the form's own
+     * listeners (`post`). False when nothing heard them.
+     */
+    post(message: PostedMessage): Promise<boolean>;
     /**
      * Load, or load again, the choices of a selection whose options come from
      * the app's list (`optionsFrom`). Once loaded, they load again by themselves
      * when a field they change with changes; the latest answer wins.
      */
     loadChoices(field: string): void;
-    /** Records a many2one, many2many or reference may point to. A reference needs `options.model`. */
+    /**
+     * Load, or load again, the definitions of a properties field whose
+     * definitions come from a linked record (`definitionsFrom`). Once loaded,
+     * they load again by themselves when a field they change with changes.
+     */
+    loadDefinitions(field: string): void;
+    /** A property added in place to such a field: kept in its definitions, and handed to the data source's `saveDefinitions`. */
+    addDefinition(field: string, definition: PropertyDefinition): Promise<void>;
+    /**
+     * Records a many2one, many2many or reference may point to. A reference needs
+     * `options.model`, and so does structured data naming records of a model (a
+     * json field, such as an analytic distribution's accounts); `options.ids`
+     * finds those records alone, for their names.
+     */
     search(field: string, query: string, limit?: number, options?: {
         model?: string;
+        ids?: RecordId[];
     }): Promise<RelatedRecord[]>;
-    /** The same, for a relation inside a one2many line, filtered by that line's values. */
-    searchLine(field: string, key: string, subfield: string, query: string, limit?: number): Promise<RelatedRecord[]>;
+    /** The same, for a relation inside a one2many line, filtered by that line's values — or structured data of a line naming records of a model (`options.model`). */
+    searchLine(field: string, key: string, subfield: string, query: string, limit?: number, options?: {
+        model?: string;
+        ids?: RecordId[];
+    }): Promise<RelatedRecord[]>;
+    /**
+     * The values of records a many2many links to, for a table of them: `fields`
+     * of the records with these ids, in the order asked, read with the data
+     * source's `list`. None without one.
+     */
+    linkedValues(field: string, ids: readonly RecordId[], fields: readonly string[]): Promise<{
+        id: RecordId;
+        values: Values;
+    }[]>;
     /** Whether a link field can make a record from a typed name: the data source must be able to. */
     canCreate(field: string): boolean;
-    /** Make a record from a typed name, for the link field to point to. */
+    /** Make a record from a typed name, for the link field to point to, with what its `createValues` hand on. */
     quickCreate(field: string, name: string): Promise<RelatedRecord>;
-    /** The same, for a link inside a one2many's lines. */
+    /** The same, for a link inside a one2many's lines; with the line's key, its `createValues` are read on that line. */
     canCreateLine(field: string, subfield: string): boolean;
-    quickCreateLine(field: string, subfield: string, name: string): Promise<RelatedRecord>;
+    quickCreateLine(field: string, subfield: string, name: string, key?: string): Promise<RelatedRecord>;
+    /** What a record made from a link starts with besides its name: its `createValues`, read now — on a line, on that line. */
+    createValues(field: string, line?: {
+        lines: string;
+        key: string;
+    }): Values;
     steps(): string[];
     next(): boolean;
     back(): boolean;
@@ -148,14 +306,57 @@ 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>;
+    /** A field's own value as its tones have it now: its tone and whether it is bold, read on the record. */
+    fieldTone(nodeId: string): FieldTone;
+    /** A table's line as its rules have it now — its tone, each ruled column's cells, which of its buttons show — by the table's field node. */
+    lineState(nodeId: string, key: string): LineState;
+    /** Whether a table's column is hidden now by its `hidden` rule, read on the record. */
+    columnHidden(nodeId: string, column: string): boolean;
+    /**
+     * The words a field's empty box shows now, by its node (`#title` for a
+     * sheet's title): its first `placeholderWhen` that holds, else its
+     * `placeholder`; undefined when it has neither.
+     */
+    placeholder(nodeId: string): string | undefined;
+    /** Press a button on a table's line: its confirmation, its steps, then its action, each call carrying the line. Hidden on that line, it does not run. */
+    runRowAction(nodeId: string, buttonId: string, key: string): Promise<RunResult>;
+    /**
+     * Press a button for the lines chosen in a table (its `selectedButtons`),
+     * by their keys: its confirmation, its steps, then its action, each call
+     * carrying the lines. Hidden, or with no line chosen, it does not run.
+     */
+    runLinesAction(nodeId: string, buttonId: string, keys: readonly string[]): 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;
 }
 /**