@fieldia/core 0.22.0 → 0.24.0

package/src/lib/record/data-source.d.ts

@@ -2,6 +2,7 @@ import type { FilterCondition, Fields, Option, PropertyDefinition } from '../for
 import type { JsonValue } from '../format/json';
 import type { FileValue, RecordId, RelatedRecord, Values } from './values';
 import type { RunStop } from './run';
+import type { DateInterval } from './periods';
 /**
  * How Fieldia reaches data. Fieldia knows no backend: an app implements this
  * interface for its own (a Flectra adapter, a REST client, a survey store),
@@ -68,6 +69,93 @@ export interface DataSource {
      * size) and is shown as it is.
      */
     upload?(file: UploadFile, request: UploadRequest): Promise<UploadedFile>;
+    /**
+     * The times free to book, for a date and time drawn as booking slots
+     * (`"widget": "slots"`): each day asked — the days of a month, in the
+     * field's time zone — with its state (open, full, closed, a holiday) and
+     * the times a booking may start on it; asked again for the day of a time
+     * picked, so a time someone else took meanwhile is said, never booked.
+     * Without it, such a field is the plain date and time box.
+     */
+    slots?(request: SlotsRequest): Promise<SlotsResult>;
+    /**
+     * Change many records at once, the same value in each field given: a
+     * list's bulk edit, of the rows ticked or of every record the search
+     * finds. Answer with those not changed and why; every other one is taken
+     * as changed. Without it, the list saves each in turn (`save`, `partial`).
+     * Refuse a record this person may not change, or one changed since the
+     * version it was listed at (`versions`), as a save would.
+     */
+    writeMany?(request: WriteManyRequest): Promise<WriteManyResult>;
+    /**
+     * Write a list's export on the server, in place of the browser: for
+     * exports too big for a browser, or files the server words its own way.
+     * Answer with the file — its bytes (`data`: a Blob fits) or its address
+     * (`url`) — for the browser to save; with `{ message }` when the server
+     * hands it over its own way (an email on its way), the list saying it; or
+     * with `false` to let the list write it in the browser after all, as it
+     * does without this (a small export, say).
+     */
+    exportRecords?(request: ExportRequest): Promise<ExportedFile | {
+        message: string;
+    } | false>;
+}
+/** The same value written in a field of each record: a list's bulk edit. */
+export interface WriteManyRequest {
+    model: string;
+    ids: RecordId[];
+    /** The fields written and their value, the same in each record: `{ state: 'active' }`. */
+    values: Values;
+    /** Those fields' definitions, as a save gets them. */
+    fields: Fields;
+    /** The version each record was listed at, by its id, where the list knew it: one changed since is refused, as a save over someone else's. */
+    versions?: Record<string, RecordVersion>;
+}
+export interface WriteManyResult {
+    /** Each record not changed, with why in the person's words — and, where the source has it, the problem as a save would throw it (a conflict's who and when). */
+    failed: {
+        id: RecordId;
+        message: string;
+        problem?: SaveProblem;
+    }[];
+}
+/** A list's records to put in a file: those ticked, or every one its search finds. */
+export interface ExportRequest {
+    model: string;
+    format: 'xlsx' | 'csv';
+    /** The list's columns, in its order, each with its header's words. */
+    columns: {
+        field: string;
+        label: string;
+    }[];
+    /** The records ticked, by id; left out, every record `filter` finds. */
+    ids?: RecordId[];
+    /** The list's search, as `list` gets it. */
+    filter: ResolvedFilter[];
+    /** The list's order now. */
+    sort: SortOrder[];
+    /** How many records go. */
+    count: number;
+    /** The file's name, as the list would give it: "Customers 2026-10-16.xlsx". */
+    name: string;
+    /** The page's language, for values written as people there read them. */
+    locale: string;
+}
+/** A file for the browser to save: its bytes, or where to fetch them. */
+export interface ExportedFile {
+    name: string;
+    /** Its media type, when `data` does not say it. */
+    type?: string;
+    /** Its bytes: a Blob, an ArrayBuffer, a typed array, or text. */
+    data?: ExportBytes | ArrayBuffer | ArrayBufferView | string;
+    /** Where the browser fetches it, in place of `data`. */
+    url?: string;
+}
+/** A Blob, as far as an export reads one: core names no DOM types. */
+export interface ExportBytes {
+    readonly size: number;
+    readonly type: string;
+    arrayBuffer(): Promise<ArrayBuffer>;
 }
 /**
  * Which state of a record a page opened, as its source keeps it: an etag, a
@@ -207,6 +295,15 @@ export interface SearchRequest {
     /** The field's filter, with every `valueFrom` already replaced by its value. */
     filter?: ResolvedFilter[];
     limit?: number;
+    /**
+     * Only the records named exactly `query`, in any case — not every one whose
+     * name holds it. A box asks so for a name typed when a search's first
+     * answers, cut at their limit, did not hold it ("Nile" after ten "Blue
+     * Nile"s), and to tell whether more than one record has that name. A source
+     * that does not know it searches as ever: the box looks for the name among
+     * what comes.
+     */
+    exact?: boolean;
 }
 export type ResolvedFilterCondition = Omit<FilterCondition, 'valueFrom' | 'value'> & {
     value: JsonValue;
@@ -258,7 +355,23 @@ export interface ListedRecord {
     /** What the person may do with it: its row's buttons and a bulk edit keep to it. */
     can?: RecordPermissions;
 }
-export interface GroupRequest {
+/**
+ * How a date's records are grouped: by the day, week, month, quarter or year
+ * each falls in rather than by its exact value. Each group's `value` is then
+ * the first day of its span — "2026-03-01" for March 2026, "2026-03-09" for
+ * the week from 9 March — the page writing its words ("March 2026", "Week 11,
+ * 2026"); the groups in time order, those with no date last. `spanStart`
+ * counts a value's span as a source should.
+ */
+export interface GroupInterval {
+    /** For a date or a date and time field: group by the span each record falls in. */
+    interval?: DateInterval;
+    /** With `interval: "week"`: the day a week starts on, 0 Sunday to 6 Saturday — the page's language's. */
+    weekStart?: number;
+    /** With `interval`, for a date and time field: the time zone its days are told in (IANA: "Africa/Cairo") — the page's. */
+    timeZone?: string;
+}
+export interface GroupRequest extends GroupInterval {
     model: string;
     field: string;
     filter: ResolvedFilter[];
@@ -271,14 +384,22 @@ export interface Group {
 }
 /** How a field is totalled: added up, averaged, its least or its most, or how many records hold a value in it. */
 export type TotalKind = 'sum' | 'avg' | 'min' | 'max' | 'count';
-export interface TotalsRequest {
+export interface TotalsRequest extends GroupInterval {
     model: string;
     /** The list's search, as `list` gets it. For the ticked rows alone, add `{ field: 'id', op: 'in', value: ids }`. */
     filter: ResolvedFilter[];
     /** What to total, by field: `{ amount: ['sum'], hours: ['sum', 'avg'] }`. */
     totals: Record<string, TotalKind[]>;
-    /** Total under each value of this field as well, grouped as `groups` groups it: a Group By heading's sums. */
+    /** Total under each value of this field as well, grouped as `groups` groups it (by `interval`, for a date): a Group By heading's sums. */
     groupBy?: string;
+    /**
+     * The field holding each amount's currency, by the money field, where each
+     * record keeps its own: `{ amount: 'currency_id' }`. Such an amount is
+     * totalled within one currency only: over records in more than one, its
+     * sum, average, least and most are null — no honest number — and the
+     * result names the currency of those it could total (`currencies`).
+     */
+    currencies?: Record<string, string>;
 }
 /**
  * Each field's totals, by field and then by kind: `totals.amount.sum`. The
@@ -293,9 +414,19 @@ export interface TotalsResult {
     totals: Totals;
     /** With `groupBy`: each value's totals, in the order `groups` gives them. */
     groups?: TotalsGroup[];
+    /**
+     * With `currencies` asked: the currency each money field's totals are in,
+     * by field, as its currency field holds it (a link as `{ id, label }`, a
+     * code as "EGP"); null where its records hold more than one, or none. A
+     * page writes an amount's total only in a currency it knows: the field's
+     * own, or the one named here.
+     */
+    currencies?: Record<string, JsonValue>;
 }
 export interface TotalsGroup extends Group {
     totals: Totals;
+    /** The currency of each money field's totals under this value, as `TotalsResult.currencies` says it. */
+    currencies?: Record<string, JsonValue>;
 }
 /**
  * A file to store: what an upload reads of a browser's `File`. Core names no
@@ -358,6 +489,23 @@ export interface SubmitRequest {
     pageId: string;
     /** The answers to the questions that were shown. Skipped steps are left out. */
     values: Values;
+    /** On a page with a bot check (`botCheck`): what it saw, for the app to decide on. The page never refuses a send for it. */
+    bot?: BotReport;
+}
+/**
+ * What a page's bot check saw as its answers were sent. A person never fills the hidden box and takes longer than a
+ * few seconds; a send that is either is likely a bot's — or a person's whose browser filled every box at once, which is
+ * why the app decides: keep it aside, ask the captcha's service, or refuse it.
+ */
+export interface BotReport {
+    /** The hidden box was filled: no person sees it, reaches it with Tab or hears it read out. */
+    honeypot: boolean;
+    /** Sent sooner than the page's `minSeconds` after it was shown, or started again. */
+    tooFast: boolean;
+    /** Seconds from the page shown (or started again) to this send, to a tenth. */
+    seconds: number;
+    /** The captcha's token, on a page with one (`botCheck.captcha`), for the app to check with its service: null when none came. */
+    captcha?: string | null;
 }
 export interface SubmitResult {
     id?: RecordId;
@@ -444,3 +592,40 @@ export declare function saveRefused(problem: SaveProblem): Error & {
 };
 /** What a failed save tells: its own problem, a failed fetch as the network, anything else as it is. */
 export declare function saveProblemOf(error: unknown): SaveProblem;
+/** What a booking's free times are asked with: the days, the zone they are in, and what the page knows of the booking. */
+export interface SlotsRequest {
+    /** The page's model, for a record page; empty for a responses page. */
+    model: string;
+    /** The date and time field booked. */
+    field: string;
+    /** The record booked, so its own booking counts as free for it; null for a new one. */
+    recordId: RecordId | null;
+    /** The schedule the field's node names (`options.schedule`): a doctor's, a showroom's. The field's name unless it names one. */
+    schedule: string;
+    /** The first and the last day asked, both included, as 2026-10-01: days in `timeZone`. */
+    from: string;
+    to: string;
+    /** The zone the days are in, by its IANA name: the field's, its page's, or the browser's. */
+    timeZone: string;
+    /** The minutes a booking lasts, and those kept free between two, as the page says (`options.length`, `options.between`). */
+    length?: number;
+    between?: number;
+    /** Every value of the form: the doctor, the service, the car to drive. */
+    values: Values;
+}
+/** What a day is for booking: times free on it, all taken, not open, or a holiday. */
+export type SlotDayState = 'open' | 'full' | 'closed' | 'holiday';
+/** One day of a booking's: its state and the times a booking may start on it. */
+export interface SlotDay {
+    state: SlotDayState;
+    /** The times free, as instants (ISO 8601, in UTC or with their offset: 2026-10-15T09:30:00+03:00), earliest first. */
+    free?: string[];
+    /** Words for the day, in the person's language: a holiday's name, why it is closed. */
+    note?: string;
+}
+/** The days asked, each by its date (2026-10-15): a day left out is closed. */
+export interface SlotsResult {
+    days: Record<string, SlotDay>;
+    /** The minutes a booking lasts, when the source knows better than the page: the service's own length. */
+    length?: number;
+}

package/src/lib/record/data-source.js.map

@@ -1 +1 @@
-{"version":3,"file":"data-source.js","sourceRoot":"","sources":["../../../../../../libs/core/src/lib/record/data-source.ts"],"names":[],"mappings":";;;AAyHA,oCAEC;AAGD,wCAGC;AA0UD,kCAEC;AAGD,sCAMC;AA9VD,6GAA6G;AAC7G,SAAgB,YAAY,CAAC,MAAc,EAAE,OAA6D,EAAE;IAC1G,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC/H,CAAC;AAED,6HAA6H;AAC7H,SAAgB,cAAc,CAAC,MAA6B;IAC1D,MAAM,MAAM,GAAG,MAA+B,CAAC;IAC/C,OAAO,MAAM,CAAC,OAAO,KAAK,IAAI,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAuB,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAgB,EAAE,CAAC;AACzK,CAAC;AAwTD;;;;;GAKG;AACH,MAAa,aAAc,SAAQ,KAAK;IAC7B,QAAQ,CAAe;IACvB,OAAO,CAAc;IAC9B,YAAY,QAAsB,EAAE,OAAO,GAAG,sDAAsD;QAClG,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IACzD,CAAC;CACF;AATD,sCASC;AAED,8EAA8E;AAC9E,SAAgB,WAAW,CAAC,OAAoB;IAC9C,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;AAChE,CAAC;AAED,wGAAwG;AACxG,SAAgB,aAAa,CAAC,KAAc;IAC1C,MAAM,OAAO,GAAI,KAA0C,EAAE,OAAO,CAAC;IACrE,IAAI,OAAO,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAChE,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,IAAI,KAAK,YAAY,SAAS,IAAI,4BAA4B,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IAClH,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AACpC,CAAC"}
+{"version":3,"file":"data-source.js","sourceRoot":"","sources":["../../../../../../libs/core/src/lib/record/data-source.ts"],"names":[],"mappings":";;;AA6MA,oCAEC;AAGD,wCAGC;AAwYD,kCAEC;AAGD,sCAMC;AA5ZD,6GAA6G;AAC7G,SAAgB,YAAY,CAAC,MAAc,EAAE,OAA6D,EAAE;IAC1G,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC/H,CAAC;AAED,6HAA6H;AAC7H,SAAgB,cAAc,CAAC,MAA6B;IAC1D,MAAM,MAAM,GAAG,MAA+B,CAAC;IAC/C,OAAO,MAAM,CAAC,OAAO,KAAK,IAAI,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAuB,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAgB,EAAE,CAAC;AACzK,CAAC;AAsXD;;;;;GAKG;AACH,MAAa,aAAc,SAAQ,KAAK;IAC7B,QAAQ,CAAe;IACvB,OAAO,CAAc;IAC9B,YAAY,QAAsB,EAAE,OAAO,GAAG,sDAAsD;QAClG,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IACzD,CAAC;CACF;AATD,sCASC;AAED,8EAA8E;AAC9E,SAAgB,WAAW,CAAC,OAAoB;IAC9C,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;AAChE,CAAC;AAED,wGAAwG;AACxG,SAAgB,aAAa,CAAC,KAAc;IAC1C,MAAM,OAAO,GAAI,KAA0C,EAAE,OAAO,CAAC;IACrE,IAAI,OAAO,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAChE,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,IAAI,KAAK,YAAY,SAAS,IAAI,4BAA4B,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IAClH,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AACpC,CAAC"}

package/src/lib/record/data-source.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"data-source.mjs","sourceRoot":"","sources":["../../../../../../libs/core/src/lib/record/data-source.ts"],"names":[],"mappings":"AAwHA,6GAA6G;AAC7G,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,OAA6D,EAAE;IAC1G,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC/H,CAAC;AAED,6HAA6H;AAC7H,MAAM,UAAU,cAAc,CAAC,MAA6B;IAC1D,MAAM,MAAM,GAAG,MAA+B,CAAC;IAC/C,OAAO,MAAM,CAAC,OAAO,KAAK,IAAI,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAuB,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAgB,EAAE,CAAC;AACzK,CAAC;AAwTD;;;;;GAKG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,QAAQ,CAAe;IACvB,OAAO,CAAc;IAC9B,YAAY,QAAsB,EAAE,OAAO,GAAG,sDAAsD;QAClG,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IACzD,CAAC;CACF;AAED,8EAA8E;AAC9E,MAAM,UAAU,WAAW,CAAC,OAAoB;IAC9C,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;AAChE,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,MAAM,OAAO,GAAI,KAA0C,EAAE,OAAO,CAAC;IACrE,IAAI,OAAO,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAChE,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,IAAI,KAAK,YAAY,SAAS,IAAI,4BAA4B,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IAClH,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AACpC,CAAC"}
+{"version":3,"file":"data-source.mjs","sourceRoot":"","sources":["../../../../../../libs/core/src/lib/record/data-source.ts"],"names":[],"mappings":"AA4MA,6GAA6G;AAC7G,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,OAA6D,EAAE;IAC1G,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC/H,CAAC;AAED,6HAA6H;AAC7H,MAAM,UAAU,cAAc,CAAC,MAA6B;IAC1D,MAAM,MAAM,GAAG,MAA+B,CAAC;IAC/C,OAAO,MAAM,CAAC,OAAO,KAAK,IAAI,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAuB,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAgB,EAAE,CAAC;AACzK,CAAC;AAsXD;;;;;GAKG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,QAAQ,CAAe;IACvB,OAAO,CAAc;IAC9B,YAAY,QAAsB,EAAE,OAAO,GAAG,sDAAsD;QAClG,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IACzD,CAAC;CACF;AAED,8EAA8E;AAC9E,MAAM,UAAU,WAAW,CAAC,OAAoB;IAC9C,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;AAChE,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,MAAM,OAAO,GAAI,KAA0C,EAAE,OAAO,CAAC;IACrE,IAAI,OAAO,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAChE,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,IAAI,KAAK,YAAY,SAAS,IAAI,4BAA4B,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IAClH,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AACpC,CAAC"}

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

@@ -4,7 +4,7 @@ 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 SaveProblem, type BotReport, type SlotsResult, type UploadFile } from './data-source.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 +61,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 +81,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 +120,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 +182,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: {
@@ -341,6 +355,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 +413,17 @@ 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;
     /**
      * 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 +448,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 +489,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 +516,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 +530,22 @@ 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;
+    /** 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>;
     /**
      * 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,7 @@ 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 SaveProblem, type BotReport, type SlotsResult, type UploadFile } from './data-source';
 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 +61,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 +81,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 +120,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 +182,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: {
@@ -341,6 +355,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 +413,17 @@ 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;
     /**
      * 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 +448,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 +489,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 +516,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 +530,22 @@ 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;
+    /** 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>;
     /**
      * 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