@fieldia/core 0.23.0 → 0.25.0

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

@@ -4,7 +4,8 @@ import type { Page } from '../format/page.mjs';
 import type { JsonValue } from '../format/json.mjs';
 import { type FieldTone, type LineState } from './cells.mjs';
 import { type Messages } from './messages.mjs';
-import { type DataSource, type RecordChanges, type RecordPermissions, type RecordVersion, type SaveProblem, type UploadFile } from './data-source.mjs';
+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.mjs';
+import { type WaitsFor } from './waits.mjs';
 import { type FileUpload, type UploadHow } from './uploads.mjs';
 import { type Scheduler } from './scheduler.mjs';
 import { type ActionHost, type ActionRequest, type ActionResult, type OnAction, type PostedMessage, type RunContext, type RunResult } from './run.mjs';
@@ -61,11 +62,12 @@ export interface FormState {
     /**
      * Fields holding a change of the person's that the last finished save of
      * this record did not send: made while it was on its way, while the run that
-     * saved went on (its afterSave run, a copy being made), or since. Worked out
-     * from the record as that save left it, so a change back to it is none; and
-     * before the record's first save, only a file the store holds and no save
-     * sent. Never a value a step, a rule, a compute or the app set: each change
-     * is told by its origin. The next record starts with none.
+     * saved went on (its afterSave run, a copy being made), or since — and text
+     * they left since in a box of it that does not read (`unread`), which no save
+     * can send. Worked out from the record as that save left it, so a change back
+     * to it is none; and before the record's first save, only a file the store
+     * holds and no save sent. Never a value a step, a rule, a compute or the app
+     * set: each change is told by its origin. The next record starts with none.
      */
     readonly unsent: readonly string[];
     /**
@@ -80,6 +82,15 @@ export interface FormState {
      */
     readonly unread: Readonly<Record<string, UnreadText>>;
 }
+/** How a search for a link's records is asked (`form.search`, `form.searchLine`). */
+export interface SearchOptions {
+    /** The model searched: a reference's, or the model structured data names records of. */
+    model?: string;
+    /** Those records alone, for their names. */
+    ids?: RecordId[];
+    /** Only the records named exactly the query, in any case (`SearchRequest.exact`): a typed name read as a record. */
+    exact?: boolean;
+}
 /** Text left in a box that does not read, and why, as `FormState.unread` keeps it. */
 export interface UnreadText {
     readonly text: string;
@@ -110,12 +121,15 @@ export interface FormConflict {
 export declare function unsavedWork(state: FormState): boolean;
 /**
  * Whether a way out would lose the person's work without their knowing: a
- * change of theirs the last save did not send (`unsent`), files still on
- * their way, changes Reload set aside — and, `how.changes`, any change not
- * saved. What `form.leave()` — the one check every way out goes through —
- * asks about, once the save on its way and the files on theirs settled.
- * Before a record's first save, a change not saved is not at risk: as in
- * 0.20, each way out decides.
+ * change of theirs the last save did not send, or text they left since that
+ * does not read ("12a" counts as "12" does: `unsent`), files still on
+ * their way, changes Reload set aside, the changes of a save refused for a
+ * conflict, waiting for Reload or Keep mine (only a source that keeps
+ * versions has one) — and, `how.changes`, any change not saved. What
+ * `form.leave()` — the one check every way out goes through — asks about,
+ * once the save on its way and the files on theirs settled. Before a
+ * record's first save, a change not saved is not at risk: as in 0.20, each
+ * way out decides.
  */
 export declare function workAtRisk(state: FormState, how?: LeaveHow): boolean;
 /**
@@ -169,14 +183,15 @@ export interface FormEvents {
         values: Readonly<Values>;
         by: ChangeBy;
     };
-    /** A record was saved. */
+    /** A record was saved: its values as the save left it — what it sent and what came back; a change made meanwhile is not among them. */
     save: {
         recordId: RecordId | null;
         values: Readonly<Values>;
     };
-    /** A page of responses sent its answers: those sent. */
+    /** A page of responses sent its answers: those sent, and on a page with a bot check (`botCheck`) what it saw. */
     send: {
         values: Values;
+        bot?: BotReport;
     };
     /** The app answered a call: with nothing (undefined), or an `ActionResult`. */
     action: {
@@ -313,6 +328,14 @@ export interface Form {
     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;
+    /**
+     * What a value worked out from others waits for while one of them holds text that does not read (`unread`): a
+     * total of the page's own (`compute`) over a table whose line says "abc" in its Quantity, or an amount the app
+     * works out as the lines change (read-only, from a source with an onchange) — the line, as people count them, and
+     * its cell. Shown, it is a dash said in words, as the table's own total waits: never an amount worked out from the
+     * value that text replaced. Null when it shows its value.
+     */
+    waitsFor(field: string): WaitsFor | null;
     /**
      * Keep text a person left in a box that does not read (`FormState.unread`), by its path — `field`, or a line's
      * `field.lineKey.subfield` — with why in words; null once it reads, or is let go. Nothing is shown until the box
@@ -341,6 +364,15 @@ export interface Form {
      * Resolves once every reading that waits (a name looked up) has ended.
      */
     settle(): Promise<void>;
+    /**
+     * Tell a public page's bot check (`page.botCheck`) what was seen: its hidden box filled (`honeypot`, the viewer's), or
+     * the captcha's token as the app's widget gives it (`captcha`; null once it expires). Each send carries them, with
+     * the time the answers took, as `bot` (`SubmitRequest`); a token goes once it is sent, as a captcha's is spent.
+     */
+    botCheck(seen: {
+        honeypot?: boolean;
+        captcha?: string | null;
+    }): void;
     /**
      * Whether a box's reading of what was typed still waits (a name being looked up): a check or a step forward made
      * now refuses its text with "still looking", so a caller that can wait for it (`settle`) checks again after.
@@ -390,6 +422,23 @@ export interface Form {
      * first, so a way out with nothing to wait for is not put off.
      */
     leaveNow(how?: LeaveHow): boolean;
+    /**
+     * The record shown now, for an answer asked for it that comes later: the
+     * function returned is true while that record is still the one shown, as it
+     * was — no other opened, it not loaded again, no new one started, the
+     * person's Discard not pressed, the form not closed. What writes on the
+     * form, or acts on its record, once a wait ends — a name looked up, a
+     * record made from a link, a line's dialog, a step's call to the source —
+     * asks it first, so an answer is laid only on the record it was asked for
+     * (docs/plans/wave1-contract.md, section 10, part 2).
+     */
+    recordShown(): () => boolean;
+    /**
+     * What a related list (a `related` part, by its id) asks the data source's `list` for, on the record shown: the
+     * records whose link is this record, and that its own `filter` lets through, each `valueFrom` read from this record.
+     * Null before the record's first save — nothing points at it yet — and for no related list of that id.
+     */
+    relatedFilter(id: string): ResolvedFilter[] | null;
     /**
      * 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
@@ -414,17 +463,12 @@ export interface Form {
      * 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.
+     * finds those records alone, for their names; `options.exact`, those named
+     * exactly the query (`SearchRequest.exact`).
      */
-    search(field: string, query: string, limit?: number, options?: {
-        model?: string;
-        ids?: RecordId[];
-    }): Promise<RelatedRecord[]>;
+    search(field: string, query: string, limit?: number, options?: SearchOptions): 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[]>;
+    searchLine(field: string, key: string, subfield: string, query: string, limit?: number, options?: SearchOptions): 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
@@ -460,7 +504,9 @@ export interface Form {
     /**
      * 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.
+     * the records chosen in it, and every call of the run carries them. What is
+     * typed is read before its first step that reads the form or hands its
+     * values on, as a save reads it: text that does not read stops the run.
      */
     runAction(id: string, chosen?: {
         recordIds: RecordId[];
@@ -485,7 +531,7 @@ export interface Form {
      * 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 on this form, as a button would — what is typed read first: `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;
@@ -499,6 +545,51 @@ export interface Form {
      * travels inside the record as base64, as it always has.
      */
     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;
+    /**
+     * 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
+     * the form does not hold, such as a list's rows (their `rowTones`, `rowBold` and `rowButtons`). Of another model — a
+     * related list's rows — with that model's `fields` (the related list's own).
+     */
+    recordReads(id: RecordId | null, values: Values, fields?: Record<string, Field | LineField>): Record<string, unknown>;
+    /** Whether a date and time drawn as booking slots can ask for its free times: the data source has `slots`. */
+    canFindSlots(): boolean;
+    /**
+     * The free times of a date and time drawn as booking slots, asked of the data source's `slots` for the days `from`
+     * to `to` — in the field's time zone: its own, its page's, or the browser's — with the record, its values and the
+     * zone filled in. Rejects where the source has no `slots`.
+     */
+    findSlots(field: string, ask: {
+        from: string;
+        to: string;
+        schedule?: string;
+        length?: number;
+        between?: number;
+    }): Promise<SlotsResult>;
+    /** Whether the page asks for possible duplicates: a record's page naming fields in `duplicates`, its source with `duplicates`. */
+    canFindDuplicates(): boolean;
+    /**
+     * Records like the one shown, asked of the data source's `duplicates` with the fields the page names that hold a
+     * value now — none, and nothing is asked — and every value of the form: the matches, the likest first where the
+     * source scores them, never the record itself. Rejects where the source has no `duplicates`. Its answer is for the
+     * record shown as it was asked (`recordShown`).
+     */
+    findDuplicates(): Promise<DuplicateMatch[]>;
+    /** 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. */
+    readRecord(id: RecordId): Promise<Values>;
+    /**
+     * Merge records of the page's model into one through the source's `merge`: `keepId` kept with `values`, `mergeIds`
+     * gone. The form is left as it is: show the record kept (`openRecord`, `load`) once it is done.
+     */
+    merge(request: {
+        keepId: RecordId;
+        mergeIds: RecordId[];
+        values: Values;
+    }): Promise<MergeResult | void>;
     /**
      * Store files picked for a file or picture field — or a field on a table's
      * line (`how.line`) — through the data source's `upload`, each as soon as

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

@@ -4,7 +4,8 @@ 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 RecordPermissions, type RecordVersion, type SaveProblem, type UploadFile } 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 } from './data-source';
+import { type WaitsFor } from './waits';
 import { type FileUpload, type UploadHow } from './uploads';
 import { type Scheduler } from './scheduler';
 import { type ActionHost, type ActionRequest, type ActionResult, type OnAction, type PostedMessage, type RunContext, type RunResult } from './run';
@@ -61,11 +62,12 @@ export interface FormState {
     /**
      * Fields holding a change of the person's that the last finished save of
      * this record did not send: made while it was on its way, while the run that
-     * saved went on (its afterSave run, a copy being made), or since. Worked out
-     * from the record as that save left it, so a change back to it is none; and
-     * before the record's first save, only a file the store holds and no save
-     * sent. Never a value a step, a rule, a compute or the app set: each change
-     * is told by its origin. The next record starts with none.
+     * saved went on (its afterSave run, a copy being made), or since — and text
+     * they left since in a box of it that does not read (`unread`), which no save
+     * can send. Worked out from the record as that save left it, so a change back
+     * to it is none; and before the record's first save, only a file the store
+     * holds and no save sent. Never a value a step, a rule, a compute or the app
+     * set: each change is told by its origin. The next record starts with none.
      */
     readonly unsent: readonly string[];
     /**
@@ -80,6 +82,15 @@ export interface FormState {
      */
     readonly unread: Readonly<Record<string, UnreadText>>;
 }
+/** How a search for a link's records is asked (`form.search`, `form.searchLine`). */
+export interface SearchOptions {
+    /** The model searched: a reference's, or the model structured data names records of. */
+    model?: string;
+    /** Those records alone, for their names. */
+    ids?: RecordId[];
+    /** Only the records named exactly the query, in any case (`SearchRequest.exact`): a typed name read as a record. */
+    exact?: boolean;
+}
 /** Text left in a box that does not read, and why, as `FormState.unread` keeps it. */
 export interface UnreadText {
     readonly text: string;
@@ -110,12 +121,15 @@ export interface FormConflict {
 export declare function unsavedWork(state: FormState): boolean;
 /**
  * Whether a way out would lose the person's work without their knowing: a
- * change of theirs the last save did not send (`unsent`), files still on
- * their way, changes Reload set aside — and, `how.changes`, any change not
- * saved. What `form.leave()` — the one check every way out goes through —
- * asks about, once the save on its way and the files on theirs settled.
- * Before a record's first save, a change not saved is not at risk: as in
- * 0.20, each way out decides.
+ * change of theirs the last save did not send, or text they left since that
+ * does not read ("12a" counts as "12" does: `unsent`), files still on
+ * their way, changes Reload set aside, the changes of a save refused for a
+ * conflict, waiting for Reload or Keep mine (only a source that keeps
+ * versions has one) — and, `how.changes`, any change not saved. What
+ * `form.leave()` — the one check every way out goes through — asks about,
+ * once the save on its way and the files on theirs settled. Before a
+ * record's first save, a change not saved is not at risk: as in 0.20, each
+ * way out decides.
  */
 export declare function workAtRisk(state: FormState, how?: LeaveHow): boolean;
 /**
@@ -169,14 +183,15 @@ export interface FormEvents {
         values: Readonly<Values>;
         by: ChangeBy;
     };
-    /** A record was saved. */
+    /** A record was saved: its values as the save left it — what it sent and what came back; a change made meanwhile is not among them. */
     save: {
         recordId: RecordId | null;
         values: Readonly<Values>;
     };
-    /** A page of responses sent its answers: those sent. */
+    /** A page of responses sent its answers: those sent, and on a page with a bot check (`botCheck`) what it saw. */
     send: {
         values: Values;
+        bot?: BotReport;
     };
     /** The app answered a call: with nothing (undefined), or an `ActionResult`. */
     action: {
@@ -313,6 +328,14 @@ export interface Form {
     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;
+    /**
+     * What a value worked out from others waits for while one of them holds text that does not read (`unread`): a
+     * total of the page's own (`compute`) over a table whose line says "abc" in its Quantity, or an amount the app
+     * works out as the lines change (read-only, from a source with an onchange) — the line, as people count them, and
+     * its cell. Shown, it is a dash said in words, as the table's own total waits: never an amount worked out from the
+     * value that text replaced. Null when it shows its value.
+     */
+    waitsFor(field: string): WaitsFor | null;
     /**
      * Keep text a person left in a box that does not read (`FormState.unread`), by its path — `field`, or a line's
      * `field.lineKey.subfield` — with why in words; null once it reads, or is let go. Nothing is shown until the box
@@ -341,6 +364,15 @@ export interface Form {
      * Resolves once every reading that waits (a name looked up) has ended.
      */
     settle(): Promise<void>;
+    /**
+     * Tell a public page's bot check (`page.botCheck`) what was seen: its hidden box filled (`honeypot`, the viewer's), or
+     * the captcha's token as the app's widget gives it (`captcha`; null once it expires). Each send carries them, with
+     * the time the answers took, as `bot` (`SubmitRequest`); a token goes once it is sent, as a captcha's is spent.
+     */
+    botCheck(seen: {
+        honeypot?: boolean;
+        captcha?: string | null;
+    }): void;
     /**
      * Whether a box's reading of what was typed still waits (a name being looked up): a check or a step forward made
      * now refuses its text with "still looking", so a caller that can wait for it (`settle`) checks again after.
@@ -390,6 +422,23 @@ export interface Form {
      * first, so a way out with nothing to wait for is not put off.
      */
     leaveNow(how?: LeaveHow): boolean;
+    /**
+     * The record shown now, for an answer asked for it that comes later: the
+     * function returned is true while that record is still the one shown, as it
+     * was — no other opened, it not loaded again, no new one started, the
+     * person's Discard not pressed, the form not closed. What writes on the
+     * form, or acts on its record, once a wait ends — a name looked up, a
+     * record made from a link, a line's dialog, a step's call to the source —
+     * asks it first, so an answer is laid only on the record it was asked for
+     * (docs/plans/wave1-contract.md, section 10, part 2).
+     */
+    recordShown(): () => boolean;
+    /**
+     * What a related list (a `related` part, by its id) asks the data source's `list` for, on the record shown: the
+     * records whose link is this record, and that its own `filter` lets through, each `valueFrom` read from this record.
+     * Null before the record's first save — nothing points at it yet — and for no related list of that id.
+     */
+    relatedFilter(id: string): ResolvedFilter[] | null;
     /**
      * 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
@@ -414,17 +463,12 @@ export interface Form {
      * 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.
+     * finds those records alone, for their names; `options.exact`, those named
+     * exactly the query (`SearchRequest.exact`).
      */
-    search(field: string, query: string, limit?: number, options?: {
-        model?: string;
-        ids?: RecordId[];
-    }): Promise<RelatedRecord[]>;
+    search(field: string, query: string, limit?: number, options?: SearchOptions): 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[]>;
+    searchLine(field: string, key: string, subfield: string, query: string, limit?: number, options?: SearchOptions): 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
@@ -460,7 +504,9 @@ export interface Form {
     /**
      * 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.
+     * the records chosen in it, and every call of the run carries them. What is
+     * typed is read before its first step that reads the form or hands its
+     * values on, as a save reads it: text that does not read stops the run.
      */
     runAction(id: string, chosen?: {
         recordIds: RecordId[];
@@ -485,7 +531,7 @@ export interface Form {
      * 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 on this form, as a button would — what is typed read first: `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;
@@ -499,6 +545,51 @@ export interface Form {
      * travels inside the record as base64, as it always has.
      */
     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;
+    /**
+     * 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
+     * the form does not hold, such as a list's rows (their `rowTones`, `rowBold` and `rowButtons`). Of another model — a
+     * related list's rows — with that model's `fields` (the related list's own).
+     */
+    recordReads(id: RecordId | null, values: Values, fields?: Record<string, Field | LineField>): Record<string, unknown>;
+    /** Whether a date and time drawn as booking slots can ask for its free times: the data source has `slots`. */
+    canFindSlots(): boolean;
+    /**
+     * The free times of a date and time drawn as booking slots, asked of the data source's `slots` for the days `from`
+     * to `to` — in the field's time zone: its own, its page's, or the browser's — with the record, its values and the
+     * zone filled in. Rejects where the source has no `slots`.
+     */
+    findSlots(field: string, ask: {
+        from: string;
+        to: string;
+        schedule?: string;
+        length?: number;
+        between?: number;
+    }): Promise<SlotsResult>;
+    /** Whether the page asks for possible duplicates: a record's page naming fields in `duplicates`, its source with `duplicates`. */
+    canFindDuplicates(): boolean;
+    /**
+     * Records like the one shown, asked of the data source's `duplicates` with the fields the page names that hold a
+     * value now — none, and nothing is asked — and every value of the form: the matches, the likest first where the
+     * source scores them, never the record itself. Rejects where the source has no `duplicates`. Its answer is for the
+     * record shown as it was asked (`recordShown`).
+     */
+    findDuplicates(): Promise<DuplicateMatch[]>;
+    /** 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. */
+    readRecord(id: RecordId): Promise<Values>;
+    /**
+     * Merge records of the page's model into one through the source's `merge`: `keepId` kept with `values`, `mergeIds`
+     * gone. The form is left as it is: show the record kept (`openRecord`, `load`) once it is done.
+     */
+    merge(request: {
+        keepId: RecordId;
+        mergeIds: RecordId[];
+        values: Values;
+    }): Promise<MergeResult | void>;
     /**
      * Store files picked for a file or picture field — or a field on a table's
      * line (`how.line`) — through the data source's `upload`, each as soon as