@fieldia/core 0.26.1 → 0.27.0

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

@@ -1,10 +1,15 @@
 import type { ActionStep } from '../format/actions';
 import type { Field, LineField, Option, PropertyDefinition } from '../format/field';
 import type { Page } from '../format/page';
+import type { PageEnding } from '../format/endings';
 import type { JsonValue } from '../format/json';
+import { type FunctionTable } from '../expression/functions';
+import { type AppFunctions } from '../expression/app-functions';
+import { type AskedFor } from './compute';
 import { type FieldTone, type LineState } from './cells';
 import { type Messages } from './messages';
-import { type DataSource, type RecordChanges, type RecordPermissions, type RecordVersion, type ResolvedFilter, type SaveProblem, type BotReport, type SlotsResult, type UploadFile, type DuplicateMatch, type MergeResult } from './data-source';
+import { type DataSource, type RecordChanges, type RecordPermissions, type RecordVersion, type ResolvedFilter, type SaveProblem, type BotReport, type SlotsResult, type UploadFile, type DuplicateMatch, type MergeResult, type SavedDraft } from './data-source';
+import { type FormLimits } from './taking';
 import { type WaitsFor } from './waits';
 import { type FileUpload, type UploadHow } from './uploads';
 import { type Scheduler } from './scheduler';
@@ -40,7 +45,10 @@ export interface FormState {
     readonly skipped: readonly string[];
     /** Why the last save was refused, until the next one starts or the form is reset. */
     readonly saveProblem: SaveProblem | null;
-    /** The choices loaded from the app's lists, by field: those of a selection with `optionsFrom`, once asked for. */
+    /**
+     * The choices loaded from the app's lists: those of a selection with `optionsFrom`, once asked for — by field, and a
+     * table line's by its cell's path (`field.lineKey.subfield`).
+     */
     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>>;
@@ -81,6 +89,47 @@ export interface FormState {
      * value it held as the box was entered; validate and save refuse with the words until the text is fixed.
      */
     readonly unread: Readonly<Record<string, UnreadText>>;
+    /**
+     * A page of responses sent: the answers as they went, with what the app's source answered — the id it gave the
+     * response and the values it added (`SubmitResult`). What its ending reads (`form.ending()`, `{id}`). Null until a
+     * send, and again once the form starts a new response (`reset`).
+     */
+    readonly sent?: SentResponse | null;
+    /**
+     * Values worked out from an app's function that asks its server (`functions`) with no answer yet, by path (a
+     * line's `field.lineKey.subfield`): waiting for it (`{}`) — the value empty meanwhile, a save waiting for it — or
+     * why it did not come (`failed`), which a save asks again and, failing, is stopped by under its field.
+     */
+    readonly asked: Readonly<Record<string, AskedFor>>;
+    /**
+     * Words said under a choice whose chosen options a change of other answers no longer offers — hidden by their
+     * condition, no longer picked where they are carried from, or no longer in the app's list as a field it changes with
+     * changed — by path (a field, or a table line's `field.lineKey.subfield`): they were taken out of its answer. Until
+     * that value is written again, its line goes, or another record is shown.
+     */
+    readonly takenOut: Readonly<Record<string, string>>;
+    /**
+     * When the page takes answers and each choice's places, as its `limits`, its options' `seats`, the form's clock and
+     * the data source's `limits` tell: whether it takes them now (`state`), when it opens and closes, the responses it
+     * takes still, and each choice's places left. Null on a page with neither.
+     */
+    readonly limits?: FormLimits | null;
+    /**
+     * The draft kept on the app's server (`saveDraft`) that these answers continue: its `key`, once the source gave one
+     * (the viewer's `resume`, or the first draft kept); `missing` when the key the form was given named no draft — it
+     * starts empty. Null while none is.
+     */
+    readonly resume?: {
+        readonly key: string;
+        readonly missing?: boolean;
+    } | null;
+}
+/** A response sent, as `FormState.sent` keeps it. */
+export interface SentResponse {
+    /** The id the app's source gave the response ("B-1043"), or null where it gave none. */
+    readonly id: RecordId | null;
+    /** The answers as they were sent, with the values the source added (`SubmitResult.values`) laid over them. */
+    readonly values: Readonly<Values>;
 }
 /** How a search for a link's records is asked (`form.search`, `form.searchLine`). */
 export interface SearchOptions {
@@ -235,6 +284,16 @@ export interface FormEvents {
         recordId: RecordId | null;
         message: PostedMessage;
     };
+    /**
+     * A draft was kept on the app's server (`saveDraft`): its key — what a link to continue from carries — and whether the
+     * person pressed "Continue later" (`later`), with the source's answer.
+     */
+    draft: {
+        key: string;
+        savedAt: string;
+        later: boolean;
+        saved: SavedDraft;
+    };
 }
 export interface FormOptions {
     page: Page;
@@ -254,11 +313,24 @@ export interface FormOptions {
     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>;
+    /**
+     * Keep what is typed as a draft, offered again the next time the page opens: in `store` (the browser's localStorage
+     * fits) — or, on a page with `continueLater` whose data source has `saveDraft` and `loadDraft`, on the app's server,
+     * the store keeping only its key (such a page keeps its drafts there without this too). A draft keeps the wizard's
+     * step and text typed that does not read yet. `restore`: `ask` (the default) offers it, `auto` lays it at once.
+     */
     drafts?: {
         store: DraftStore;
         restore?: 'auto' | 'ask';
         delayMs?: number;
     };
+    /**
+     * The key of a draft kept on the app's server (`saveDraft`) to continue from — what the link the app made after
+     * "Continue later" carries: loaded through the source's `loadDraft` as the form opens, its answers, its wizard step
+     * and its text typed that does not read laid as they were. A key that names none starts the form empty
+     * (`resume.missing`). Without the source's `loadDraft`, it is let be.
+     */
+    resume?: string;
     autosave?: {
         delayMs: number;
     };
@@ -294,6 +366,21 @@ export interface FormOptions {
         fields: Readonly<Record<string, Field | LineField>>;
         id?: RecordId | null;
     };
+    /**
+     * How a field's value reads inside the page's own words — a `{field}` in a label, a help, a choice, a step's title, a
+     * button, an ending — and so inside the form's messages that name a label ("How was your visit to Zamalek? is
+     * required"). The viewer gives its own, as each field shows its value at rest: a choice by its label, money with its
+     * currency, a day in the page's order. Left out, a choice by its label, a link by its name, a yes or no as Yes or No,
+     * anything else as it is held.
+     */
+    valueWords?: (field: Field, value: Value | undefined, values: Readonly<Values>) => string;
+    /**
+     * The app's own functions, which the page's expressions call by name besides Fieldia's: `vatRate(country)`. Each a
+     * plain function, or `{ call, takes, values, gives, tip }`. One that asks the app's server gives a promise: a value
+     * worked out from it waits while it is asked — once for the same values, for the record shown — and a save waits
+     * for it; a condition reading it does not hold meanwhile. A name a page cannot call is refused as the form is made.
+     */
+    functions?: AppFunctions;
 }
 /** The person using a form, as the app knows them. */
 export interface FormUser {
@@ -304,6 +391,16 @@ export interface FormUser {
 }
 export interface Form {
     readonly page: Page;
+    /** The app's own functions as the page's expressions call them (`FormOptions.functions`): for what reads its conditions apart. */
+    readonly functions?: FunctionTable;
+    /**
+     * A table line's cell's form (@fieldia/widgets' `lineForm`): the table and the line it is the form of, whose values,
+     * choices and words taken out of them are the line's own. Left out of a record's own form.
+     */
+    readonly line?: {
+        readonly field: string;
+        readonly key: string;
+    };
     getState(): FormState;
     subscribe(listener: (state: FormState) => void): () => void;
     load(): Promise<void>;
@@ -324,7 +421,10 @@ export interface Form {
     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;
-    /** Whether a field is read-only whatever the conditions say: by its definition, or for this person by what the record's source said (`can`). */
+    /**
+     * Whether a field is read-only whatever the conditions say: by its definition, for this person by what the record's
+     * source said (`can`), or signed by a signature kept (`FileValue.signed`).
+     */
     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;
@@ -381,6 +481,20 @@ export interface Form {
     validate(): boolean;
     save(): Promise<boolean>;
     reset(): void;
+    /**
+     * Words of the page's with each `{field}` showing the value the form holds now, as `valueWords` writes it — a label's,
+     * a help's, a step's title, a button's: "How was your visit to {branch}?" reads "How was your visit to Zamalek?". A
+     * name that is no field of the page shows nothing.
+     */
+    words(text: string): string;
+    /**
+     * The ending a page of responses shows now its answers are sent (`FormState.sent`): the first of the page's
+     * `endings` whose `when` holds on the answers as sent, with what the source added and the response's `id`, else the
+     * first with no `when`; null before a send, on a page with none, or where none holds.
+     */
+    ending(): PageEnding | null;
+    /** An ending's words, its `{field}`s and `{id}` filled in from the response sent (`FormState.sent`), as `words` writes them. */
+    endingWords(text: string): string;
     changes(): RecordChanges;
     addLine(field: string, values?: Values): string;
     updateLine(field: string, key: string, name: string, value: Value): void;
@@ -448,9 +562,32 @@ export interface Form {
     /**
      * 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.
+     * when a field they change with changes; the latest answer wins, and a
+     * choice it no longer offers after the person, a step or the app changed
+     * that field is taken out and said (`FormState.takenOut`). A value a record
+     * comes in with is kept, and its save says why. A table line's, by its
+     * cell's path (`field.lineKey.subfield`), are asked by the line's values and
+     * shared with every line where the columns they change with hold the same,
+     * for the record shown; once loaded, they follow those columns on that line.
      */
     loadChoices(field: string): void;
+    /**
+     * A table line's choices from the app's list, as they are asked for that line, with `values` laid over it — a row
+     * pasted on it, its connection read first. `key` null: a line not added yet, by the values one added now starts with.
+     */
+    lineChoices(field: string, key: string | null, subfield: string, values?: Values): Promise<Option[]>;
+    /**
+     * The options a choice offers now: its own — or those its list gave (`optionsFrom.list`), or those picked in the
+     * question they are carried from (`optionsFrom.field`), its own after them — less those whose condition hides them
+     * (`options[].invisible`). A table line's by its cell's path (`field.lineKey.subfield`), its conditions read on that
+     * line. Null for a field that is no choice.
+     */
+    offered(field: string): readonly Option[] | null;
+    /**
+     * Whether a choice's options change with the record's answers: a condition on one, or carried from another question.
+     * A table line's by its cell's path: a condition on one of its column's options.
+     */
+    offersChange(field: string): boolean;
     /**
      * Load, or load again, the definitions of a properties field whose
      * definitions come from a linked record (`definitionsFrom`). Once loaded,
@@ -543,6 +680,19 @@ export interface Form {
     on<E extends keyof FormEvents>(event: E, listener: (event: FormEvents[E]) => void): () => void;
     restoreDraft(): void;
     discardDraft(): void;
+    /** Whether the page offers "Continue later": it says `continueLater`, and its data source has `saveDraft`. */
+    canContinueLater(): boolean;
+    /**
+     * "Continue later": what is typed read first (`settle`), then the answers so far — their wizard step, text that does
+     * not read kept as typed — kept on the app's server through `saveDraft` (`later: true`): its answer, the key, and the
+     * link the app made to continue from and its words. Rejects where the source refused, or has no `saveDraft`.
+     */
+    continueLater(): Promise<SavedDraft>;
+    /**
+     * Ask the data source's `limits` again — how many responses the page took, this person's, each choice's takers — and
+     * show what it tells (`limits`). The form asks it itself as it opens, before its answers go, and after they went.
+     */
+    refreshLimits(): Promise<void>;
     /**
      * Whether a file picked for a file or picture field is stored at once,
      * through the data source's `upload`. False without one: a file then
@@ -551,6 +701,16 @@ export interface Form {
     canUpload(): boolean;
     /** Today, as 2026-10-15, on the clock of the page's time zone — the browser's own where it names none — by the form's clock (`now`). */
     today(): string;
+    /** Now, by the form's clock (`now`): the computer's own where the app gave none. A signature's when. */
+    now(): Date;
+    /** The person using the form, as the app named them (`user`); null where it named none. */
+    user(): FormUser | null;
+    /**
+     * The answers shown now, by field, in the page's order: a field placed on the page — or a saved form's answers, by its
+     * name — not hidden by its condition, its roles or the record's source, nor in a step passed over with Skip. What a
+     * signature that signs every answer signs.
+     */
+    shownFields(): string[];
     /**
      * A record of the page's model as conditions read it, the form's own way: its values (a link as its id), its `id`,
      * the person using the form (`user`), the app's `context`, and `editing` false — for what reads conditions on records
@@ -581,6 +741,15 @@ export interface Form {
      * record shown as it was asked (`recordShown`).
      */
     findDuplicates(): Promise<DuplicateMatch[]>;
+    /** Whether the source keeps "It's someone new" itself, on the app's server: it has `notDuplicates` and `markNotDuplicate`, both. */
+    keepsNotDuplicates(): boolean;
+    /**
+     * The records said to be someone else for the record shown, asked of the source's `notDuplicates`: none while it is
+     * new. Rejects where the source has no `notDuplicates`. Its answer is for the record shown as it was asked.
+     */
+    notDuplicates(): Promise<RecordId[]>;
+    /** Keep that `matchId` is someone else for the record shown, through the source's `markNotDuplicate`: refused while it is new. */
+    markNotDuplicate(matchId: RecordId): Promise<void>;
     /** Whether records of the page's model can be merged: its source has `merge`, and `load` to read the others. */
     canMerge(): boolean;
     /** Another record of the page's model, as its source loads it, its values alone: the form is left as it is. For a merge's screen. */