@fieldia/core 0.21.0 → 0.22.0

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

@@ -8,9 +8,18 @@ import type { RunStop } from './run';
  * and every method is optional so a page uses only what it needs.
  */
 export interface DataSource {
-    /** Read a record. Needed to edit an existing record. */
-    load?(request: LoadRequest): Promise<Values>;
-    /** Create (`id: null`) or update a record. Needed to save a record page. */
+    /**
+     * Read a record. Needed to edit an existing record. Its values, or
+     * `loadedRecord(values, { version, can })` to tell also its version — so a
+     * save can tell that someone else changed it since — and what this person
+     * may do with it. `loadedRecordOf` reads either the same way.
+     */
+    load?(request: LoadRequest): Promise<Values | LoadedRecord>;
+    /**
+     * Create (`id: null`) or update a record. Needed to save a record page. A
+     * source that keeps versions compares `request.version` with the record's
+     * and throws a `ConflictError` when someone else saved it since.
+     */
     save?(request: SaveRequest): Promise<SaveResult>;
     /** Recalculate after a value changes, the way a backend's onchange does. */
     onchange?(request: OnchangeRequest): Promise<OnchangeResult>;
@@ -20,7 +29,7 @@ export interface DataSource {
     create?(request: CreateRequest): Promise<RelatedRecord>;
     /** Store one response to a `responses` page, such as a survey. */
     submit?(request: SubmitRequest): Promise<SubmitResult>;
-    /** Records for a list: filtered, sorted and one page of them, with how many there are in all. */
+    /** Records for a list: filtered, sorted and one page of them, with how many there are in all; with `allIds`, the ids of every one that matches. */
     list?(request: ListRequest): Promise<ListResult>;
     /** How many records fall under each value of a field, for a list's Group By. */
     groups?(request: GroupRequest): Promise<Group[]>;
@@ -43,7 +52,76 @@ export interface DataSource {
      * preview: each a file with its `url` (or its `data`) and its media type.
      */
     attachments?(request: RecordRequest): Promise<FileValue[]>;
+    /**
+     * Totals over the records a search finds — each field's sum, average,
+     * least, most or count — over them all and, with `groupBy`, under each
+     * value of a field: the row under a list and the sums on its Group By
+     * headings. Without it, a list shows no totals.
+     */
+    totals?(request: TotalsRequest): Promise<TotalsResult>;
+    /**
+     * Store one file where the app keeps files, as soon as it is picked, for a
+     * file or picture field: the record then keeps only its link. Without it,
+     * a file travels inside the record as base64, as it always has. To fail,
+     * throw: the field offers Retry, except after `saveRefused({ kind: 'rule',
+     * message })`, which says the store refuses this file (its kind, its
+     * size) and is shown as it is.
+     */
+    upload?(file: UploadFile, request: UploadRequest): Promise<UploadedFile>;
+}
+/**
+ * Which state of a record a page opened, as its source keeps it: an etag, a
+ * write date, a revision number — Fieldia only hands `token` back — with who
+ * changed the record last and when, for the words a conflict shows ("Mona
+ * changed this at 10:42").
+ */
+export interface RecordVersion {
+    token: string;
+    /** Who changed it last, by the name people know them by. */
+    by?: string;
+    /** When, as an ISO date and time: `2026-10-13T10:42:00Z`. */
+    at?: string;
+}
+/**
+ * What this person may do with one record. Each is allowed unless it says
+ * `false`, so a source that tells nothing keeps today's behaviour. The page
+ * hides what is not allowed — never shows it disabled — and says why.
+ */
+export interface RecordPermissions {
+    /** False: the form is read-only for this person, and Save is hidden. */
+    edit?: boolean;
+    /** False: Delete is hidden, and the `delete` step's buttons. */
+    delete?: boolean;
+    /** False: Archive and Unarchive are hidden, and those steps' buttons. */
+    archive?: boolean;
+    /** False: Duplicate is hidden, and the `duplicate` step's buttons. */
+    duplicate?: boolean;
+    /** Fields this person may see but not change on this record, by name. */
+    readonlyFields?: string[];
+    /** Fields this person may not see on this record, by name: hidden, and the source leaves their values out. */
+    hiddenFields?: string[];
+    /** Why not everything is allowed, in the person's language, for the page to say: "Only Mona, the lead's agent, can change it." */
+    reason?: string;
 }
+/**
+ * A record as `load` gives it to tell more than its values. A field cannot
+ * be named `$loaded`, so the mark keeps it apart from bare values.
+ */
+export interface LoadedRecord {
+    $loaded: true;
+    values: Values;
+    /** The version it was read at: each save carries it back. */
+    version?: RecordVersion;
+    /** What this person may do with it. */
+    can?: RecordPermissions;
+}
+/** What `load` returns to tell a record's version, or what this person may do with it, beside its values. */
+export declare function loadedRecord(values: Values, more?: {
+    version?: RecordVersion;
+    can?: RecordPermissions;
+}): LoadedRecord;
+/** What a load gave, in one shape: bare values, as every source gave them before, are a record with nothing more to tell. */
+export declare function loadedRecordOf(loaded: Values | LoadedRecord): LoadedRecord;
 /** One stored record, by its model and id. */
 export interface RecordRequest {
     model: string;
@@ -83,11 +161,31 @@ export interface SaveRequest {
     changes: RecordChanges;
     /** Every value, for sources that save whole records. */
     values: Values;
+    /**
+     * True when the save carries some of the record's fields, not all of it:
+     * `values` then holds the fields in `changes` alone and `fields` names
+     * them alone — a save from outside a form, which never had the rest, as a
+     * calendar's move and its Undo. A source that saves whole records writes
+     * these over the record as stored and keeps every other field.
+     */
+    partial?: boolean;
+    /**
+     * The version the record was opened at — from its load, or from the last
+     * save — for a source that refuses a save over someone else's. None for a
+     * new record, nor from a source that tells no versions. "Keep mine" after
+     * a conflict saves again with the conflict's `version`: these changes over
+     * the record as it is now.
+     */
+    version?: RecordVersion;
 }
 export interface SaveResult {
     id: RecordId;
     /** The record as stored, when the source recalculated anything. */
     values?: Values;
+    /** Its version now, for the next save to carry. */
+    version?: RecordVersion;
+    /** What the person may do with it now, when the save changed that (a stage that locks it). */
+    can?: RecordPermissions;
 }
 export interface OnchangeRequest {
     model: string;
@@ -137,14 +235,28 @@ export interface ListRequest {
     sort: SortOrder[];
     offset: number;
     limit: number;
+    /**
+     * Give also the id of every record that matches, in this order, in
+     * `ListResult.allIds`: for "Select all 1,284 that match", export and bulk
+     * edit. A source that leaves it out is paged through instead.
+     */
+    allIds?: boolean;
 }
 export interface ListResult {
-    records: {
-        id: RecordId;
-        values: Values;
-    }[];
+    records: ListedRecord[];
     /** How many records match in all, for the pager. */
     total: number;
+    /** With `allIds`: every matching record's id. Fewer than `total` means the source stopped short, and the page says so. */
+    allIds?: RecordId[];
+}
+/** One row of a list. */
+export interface ListedRecord {
+    id: RecordId;
+    values: Values;
+    /** Its version, for a bulk edit that saves it to carry. */
+    version?: RecordVersion;
+    /** What the person may do with it: its row's buttons and a bulk edit keep to it. */
+    can?: RecordPermissions;
 }
 export interface GroupRequest {
     model: string;
@@ -157,6 +269,82 @@ export interface Group {
     label: string;
     count: number;
 }
+/** 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 {
+    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. */
+    groupBy?: string;
+}
+/**
+ * Each field's totals, by field and then by kind: `totals.amount.sum`. The
+ * sum and the count of nothing are 0, the others null. A total the source
+ * cannot make honestly — amounts in more than one currency — is null, and
+ * the page shows none.
+ */
+export type Totals = Record<string, Partial<Record<TotalKind, number | null>>>;
+export interface TotalsResult {
+    /** How many records match. */
+    count: number;
+    totals: Totals;
+    /** With `groupBy`: each value's totals, in the order `groups` gives them. */
+    groups?: TotalsGroup[];
+}
+export interface TotalsGroup extends Group {
+    totals: Totals;
+}
+/**
+ * A file to store: what an upload reads of a browser's `File`. Core names no
+ * DOM types; an adapter may type its parameter `File` and hand it to `fetch`
+ * or a storage SDK as it is.
+ */
+export interface UploadFile {
+    readonly name: string;
+    readonly size: number;
+    readonly type: string;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/** An `AbortSignal`, as far as an upload listens to it. */
+export interface UploadSignal {
+    readonly aborted: boolean;
+    addEventListener(type: 'abort', listener: () => void): void;
+    removeEventListener(type: 'abort', listener: () => void): void;
+}
+export interface UploadRequest {
+    /** The page's model: for a saved form placed in a record, the record's. */
+    model: string;
+    /**
+     * The file or picture field the file is for. In a saved form placed in a
+     * record, whose answers the record keeps under the part's name, the field's
+     * place in them: `consent.doc`, as a line's table is `consent.items`.
+     */
+    field: string;
+    /** The record it is for; null while that record is new — its first save links the file to it. */
+    recordId: RecordId | null;
+    /** For a field on a line of a table: the table's field, the line's key and, once saved, its id. */
+    line?: {
+        field: string;
+        key: string;
+        id?: RecordId;
+    };
+    /** Aborts when the person takes the file away or leaves before it is stored: stop, and reject with an error named `AbortError`. */
+    signal?: UploadSignal;
+    /** How far it has got, bytes sent of the bytes in all, for its progress bar; without a call the bar moves with no number. */
+    onProgress?: (sent: number, total: number) => void;
+}
+/** A stored file, as the field keeps it — a `FileValue` with its link instead of its bytes. */
+export interface UploadedFile {
+    url: string;
+    name: string;
+    size: number;
+    type: string;
+    /** Its id, where the source keeps files as records of their own (Flectra's attachments): a save links it by this. */
+    fileId?: RecordId;
+}
 /**
  * A filter as a search receives it: each `valueFrom` already replaced by its
  * value. An adapter must keep the groups: `any` is an OR, `all` an AND.
@@ -213,16 +401,42 @@ export type LinkOp = {
 /**
  * Why a save was refused, so each kind is shown where it belongs: `fields`
  * under those fields, a `rule` (a backend's business rule) in a dialog,
- * `network` in a banner with Retry, and `other` beside Save with Retry.
+ * `network` in a banner with Retry, `other` beside Save with Retry, and a
+ * `conflict` with Reload and Keep mine.
  */
 export interface SaveProblem {
     /** `stopped`: a step of the page's `beforeSave` stopped it, with `reason` — no data source was asked. */
-    kind: 'fields' | 'rule' | 'network' | 'other' | 'stopped';
+    kind: 'fields' | 'rule' | 'network' | 'other' | 'stopped' | 'conflict';
     message: string;
     /** For `fields`: a message for each field, by name. */
     fields?: Record<string, string>;
     /** For `stopped`: why the step stopped. */
     reason?: RunStop;
+    /** For `conflict`: who changed the record, when, and what it holds now. */
+    conflict?: SaveConflict;
+}
+/** Someone else saved the record after this page opened it. */
+export interface SaveConflict {
+    /** The version the record has now, with who changed it and when. Saving with it is "Keep mine". */
+    version: RecordVersion;
+    /**
+     * The record as the other person left it, when the source has it: what
+     * Reload shows without asking again, and what a source that saves whole
+     * records keeps of theirs under Keep mine — their values, with this
+     * person's changes over them.
+     */
+    theirs?: Values;
+}
+/**
+ * What a source's save throws when the record changed after the page opened
+ * it: `saveProblemOf` reads it as a `conflict`, and the page names who
+ * changed it and when (`conflict.version.by`, `.at`) and offers Reload or
+ * Keep mine.
+ */
+export declare class ConflictError extends Error {
+    readonly conflict: SaveConflict;
+    readonly problem: SaveProblem;
+    constructor(conflict: SaveConflict, message?: string);
 }
 /** An error for a data source's save to throw when the backend refuses it. */
 export declare function saveRefused(problem: SaveProblem): Error & {

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

@@ -1,7 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConflictError = void 0;
+exports.loadedRecord = loadedRecord;
+exports.loadedRecordOf = loadedRecordOf;
 exports.saveRefused = saveRefused;
 exports.saveProblemOf = saveProblemOf;
+/** What `load` returns to tell a record's version, or what this person may do with it, beside its values. */
+function loadedRecord(values, more = {}) {
+    return { $loaded: true, values, ...(more.version ? { version: more.version } : {}), ...(more.can ? { can: more.can } : {}) };
+}
+/** What a load gave, in one shape: bare values, as every source gave them before, are a record with nothing more to tell. */
+function loadedRecordOf(loaded) {
+    const marked = loaded;
+    return marked.$loaded === true && marked.values !== null && typeof marked.values === 'object' ? loaded : { $loaded: true, values: loaded };
+}
+/**
+ * What a source's save throws when the record changed after the page opened
+ * it: `saveProblemOf` reads it as a `conflict`, and the page names who
+ * changed it and when (`conflict.version.by`, `.at`) and offers Reload or
+ * Keep mine.
+ */
+class ConflictError extends Error {
+    conflict;
+    problem;
+    constructor(conflict, message = 'Someone else changed this record after it was opened') {
+        super(message);
+        this.name = 'ConflictError';
+        this.conflict = conflict;
+        this.problem = { kind: 'conflict', message, conflict };
+    }
+}
+exports.ConflictError = ConflictError;
 /** An error for a data source's save to throw when the backend refuses it. */
 function saveRefused(problem) {
     return Object.assign(new Error(problem.message), { problem });

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":";;AA8NA,kCAEC;AAGD,sCAMC;AAZD,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":";;;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"}

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

@@ -1,3 +1,28 @@
+/** What `load` returns to tell a record's version, or what this person may do with it, beside its values. */
+export function loadedRecord(values, more = {}) {
+    return { $loaded: true, values, ...(more.version ? { version: more.version } : {}), ...(more.can ? { can: more.can } : {}) };
+}
+/** What a load gave, in one shape: bare values, as every source gave them before, are a record with nothing more to tell. */
+export function loadedRecordOf(loaded) {
+    const marked = loaded;
+    return marked.$loaded === true && marked.values !== null && typeof marked.values === 'object' ? loaded : { $loaded: true, values: loaded };
+}
+/**
+ * What a source's save throws when the record changed after the page opened
+ * it: `saveProblemOf` reads it as a `conflict`, and the page names who
+ * changed it and when (`conflict.version.by`, `.at`) and offers Reload or
+ * Keep mine.
+ */
+export class ConflictError extends Error {
+    conflict;
+    problem;
+    constructor(conflict, message = 'Someone else changed this record after it was opened') {
+        super(message);
+        this.name = 'ConflictError';
+        this.conflict = conflict;
+        this.problem = { kind: 'conflict', message, conflict };
+    }
+}
 /** An error for a data source's save to throw when the backend refuses it. */
 export function saveRefused(problem) {
     return Object.assign(new Error(problem.message), { problem });

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":"AA6NA,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":"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"}

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 SaveProblem } from './data-source.mjs';
+import { type DataSource, type RecordChanges, type RecordPermissions, type RecordVersion, type SaveProblem, 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';
 import { type RecordId, type RelatedRecord, type Value, type Values } from './values.mjs';
@@ -42,6 +43,36 @@ export interface FormState {
     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>>;
+    /** Files on their way to the data source's store, in the order picked: each field shows its own (`upload`). */
+    readonly uploads: readonly FileUpload[];
+    /** The record's version, as loaded or last saved, from a source that keeps versions: each save carries it. Null for a new record, or from a source that tells none. */
+    readonly version: RecordVersion | null;
+    /**
+     * What the person may do with the record, as its source told with its load
+     * or its last save: the form keeps to it — fields locked or hidden, Save,
+     * Archive, Duplicate and Delete not offered. Null when it told nothing, and
+     * everything is allowed.
+     */
+    readonly can: Readonly<RecordPermissions> | null;
+    /** Someone else saved the record after this page opened it, and the last save was refused for it: until Reload, Keep mine or another save. */
+    readonly conflict: FormConflict | null;
+    /** The person's changes Reload set aside after a conflict, by field, to put back (`putBack`); null when none are. */
+    readonly setAside: Readonly<Values> | null;
+    /**
+     * 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.
+     */
+    readonly unsent: readonly string[];
+    /**
+     * A way out (`leave()`) waits for the save on its way, or files on theirs,
+     * before it checks: the page says what it waits for.
+     */
+    readonly leaving: boolean;
     /**
      * Text a person left in a box that does not read as its field's value — "12 34" in a number, "31/02/2026" in a
      * date — by its path (`field`, or a line's `field.lineKey.subfield`), with why in words. The field keeps the
@@ -54,6 +85,48 @@ export interface UnreadText {
     readonly text: string;
     readonly message: string;
 }
+/** A save refused because someone else saved the record first: who and when, and what each of them changed. */
+export interface FormConflict {
+    /** The version the record has now, with who saved it (`by`) and when (`at`): Keep mine saves over it. */
+    readonly version: RecordVersion;
+    /** The record as they left it, when the source told it. */
+    readonly theirs?: Readonly<Values>;
+    /** The fields they changed since this page opened the record, in the page's order: none known when the source did not tell the record. */
+    readonly changed: readonly string[];
+    /** Those of them this person changed too, each to something else. */
+    readonly both: readonly string[];
+    /**
+     * Keep mine was pressed, and the record as they left it could not be read:
+     * nothing was saved over their work, and the person may try again or Reload.
+     */
+    readonly unread?: boolean;
+}
+/**
+ * Whether leaving the record now would lose the person's work: changes not
+ * saved, files still on their way to the store, or changes Reload set aside
+ * and not yet put back or let go, or text left in a box that does not read.
+ * Every way out of a record asks this.
+ */
+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.
+ */
+export declare function workAtRisk(state: FormState, how?: LeaveHow): boolean;
+/**
+ * How a way out asks: `changes`, every change not saved counts too, as a
+ * panel's Escape has always asked; `discard`, the person's own Discard: it
+ * waits as any way out does, asks nothing, and lets their work go.
+ */
+export interface LeaveHow {
+    changes?: boolean;
+    discard?: boolean;
+}
 /** 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. */
@@ -236,20 +309,21 @@ 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`). */
     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;
     /**
      * 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
-     * is left (`leave`) or the form is checked.
+     * is left (`boxLeft`) or the form is checked.
      */
     setUnread(path: string, unread: UnreadText | null): void;
     /**
      * A person left a field's box, by its path: its own problem — text that does not read, a format, min or max, a
      * whole number, decimals, a pattern — is shown now, in the words Save would use. That it is required waits for Save.
      */
-    leave(path: string): void;
+    boxLeft(path: string): void;
     /**
      * How a box reads what is typed in it and not yet read — a number, hours, a date, a colour's code, a name looked
      * up — now, as if it were left: every save and send, every check and step forward runs these first (`settle`), so
@@ -290,9 +364,32 @@ export interface Form {
     /**
      * 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.
+     * saved are dropped: save first. The page's `open` steps run for it. It
+     * goes through `leave()` first: false when the person kept their work.
+     */
+    openRecord(id: RecordId | null): Promise<boolean>;
+    /**
+     * The one check every way out of the form goes through — another record,
+     * the record loaded again, the form closed, reset by a step — and the app's
+     * own ways out should too, before it navigates or unmounts the form. It
+     * first waits for a save on its way and files on theirs (`leaving`
+     * meanwhile), then looks at the record as it is now. With the person's
+     * work at risk (`workAtRisk`), it asks "Discard your changes?" through the
+     * host (`ask(message, { discard: true })`), else `confirm`: true on
+     * Discard — files on their way stopped, changes set aside let go — false
+     * on Cancel, the form as it was. Without either to ask with, the work is
+     * kept: false. A way out taken while one waits or asks joins it. Nothing
+     * on its way and nothing at risk: true, as in 0.20.
+     */
+    leave(how?: LeaveHow): Promise<boolean>;
+    /**
+     * Whether a way out goes at once: nothing on its way, no check going, and
+     * nothing of the person's at risk (with `how`) — then it goes in the same
+     * moment, as in 0.20, and `leave()` would answer true. Else take it through
+     * `leave()`. What the viewer's dialogs, pages in place and breadcrumbs ask
+     * first, so a way out with nothing to wait for is not put off.
      */
-    openRecord(id: RecordId | null): Promise<void>;
+    leaveNow(how?: LeaveHow): 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
@@ -396,6 +493,48 @@ export interface Form {
     on<E extends keyof FormEvents>(event: E, listener: (event: FormEvents[E]) => void): () => void;
     restoreDraft(): void;
     discardDraft(): 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
+     * travels inside the record as base64, as it always has.
+     */
+    canUpload(): boolean;
+    /**
+     * 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
+     * it is picked: `uploads` in the state shows each on its way, and once
+     * stored the field holds its link, a field of several in the order they
+     * were picked. Three go at once, the rest wait their turn; `how.prepare`
+     * makes each ready first, one at a time (a photo made smaller). A field of
+     * one file keeps the last one picked. Gives each upload's id. A save waits
+     * for those still going, and stops, under the field, for one that failed.
+     */
+    upload(field: string, files: readonly UploadFile[], how?: UploadHow): string[];
+    /**
+     * A field's files on their way, in the order picked: the uploads in the
+     * state that are its own. A table's cell (`lineForm`) gives its line's.
+     */
+    uploading(field: string): readonly FileUpload[];
+    /** Stop an upload and drop its file, whether it is on its way, waiting, or failed. */
+    cancelUpload(id: string): void;
+    /** Send a file that failed again. */
+    retryUpload(id: string): void;
+    /**
+     * After a conflict: show the record as the other person left it, loaded
+     * again, and set this person's changes aside (`setAside`), to put back.
+     * False when it could not be loaded.
+     */
+    reloadTheirs(): Promise<boolean>;
+    /**
+     * After a conflict: save this person's changes over the record as it is
+     * now — the other person's values kept wherever this one changed nothing.
+     * Refused again as a conflict when a third person saved in between.
+     */
+    keepMine(): Promise<boolean>;
+    /** Write a change set aside by Reload back, as the person's own: one field's, or all when none is named. */
+    putBack(field?: string): void;
+    /** Let go of the changes set aside. */
+    discardSetAside(): void;
     /** 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>;
     /**