@fieldia/core 0.20.0 → 0.22.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 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,89 @@ 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
+     * value it held as the box was entered; validate and save refuse with the words until the text is fixed.
+     */
+    readonly unread: Readonly<Record<string, UnreadText>>;
+}
+/** Text left in a box that does not read, and why, as `FormState.unread` keeps it. */
+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 {
@@ -225,9 +309,43 @@ 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 (`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.
+     */
+    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
+     * Ctrl+Enter, a button's key, a pager or the app's own save keep what the box shows, or refuse it with its words,
+     * and never save a value passed on the way ("1" of "1.5") or the one the box held before. The viewer gives one
+     * for the box that has the focus (a change, which each box reads); a box whose reading waits — a name looked up
+     * among records — gives its own, which keeps the text unread with why at once, and returns the wait: a save
+     * waits for it, while a check or a step forward, which cannot wait, refuses meanwhile. `typing` says whether the
+     * box is still being typed in (typed since it last read): autosave, which nobody pressed, waits while it is, and
+     * never reads text under the person's keys ("12." of "12.5", "Office " of "Office Park"). Returns what stops it.
+     */
+    settling(read: () => void | Promise<unknown>, typing?: () => boolean): () => void;
+    /**
+     * Read what is typed and not yet read in every box (`settling`), as if each were left: a save does it first.
+     * Resolves once every reading that waits (a name looked up) has ended.
+     */
+    settle(): Promise<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.
+     */
+    reading(): boolean;
     validate(): boolean;
     save(): Promise<boolean>;
     reset(): void;
@@ -246,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
@@ -352,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>;
     /**

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 SaveProblem } from './data-source';
+import { type DataSource, type RecordChanges, type RecordPermissions, type RecordVersion, type SaveProblem, 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';
 import { type RecordId, type RelatedRecord, type Value, type Values } from './values';
@@ -42,6 +43,89 @@ 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
+     * value it held as the box was entered; validate and save refuse with the words until the text is fixed.
+     */
+    readonly unread: Readonly<Record<string, UnreadText>>;
+}
+/** Text left in a box that does not read, and why, as `FormState.unread` keeps it. */
+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 {
@@ -225,9 +309,43 @@ 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 (`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.
+     */
+    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
+     * Ctrl+Enter, a button's key, a pager or the app's own save keep what the box shows, or refuse it with its words,
+     * and never save a value passed on the way ("1" of "1.5") or the one the box held before. The viewer gives one
+     * for the box that has the focus (a change, which each box reads); a box whose reading waits — a name looked up
+     * among records — gives its own, which keeps the text unread with why at once, and returns the wait: a save
+     * waits for it, while a check or a step forward, which cannot wait, refuses meanwhile. `typing` says whether the
+     * box is still being typed in (typed since it last read): autosave, which nobody pressed, waits while it is, and
+     * never reads text under the person's keys ("12." of "12.5", "Office " of "Office Park"). Returns what stops it.
+     */
+    settling(read: () => void | Promise<unknown>, typing?: () => boolean): () => void;
+    /**
+     * Read what is typed and not yet read in every box (`settling`), as if each were left: a save does it first.
+     * Resolves once every reading that waits (a name looked up) has ended.
+     */
+    settle(): Promise<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.
+     */
+    reading(): boolean;
     validate(): boolean;
     save(): Promise<boolean>;
     reset(): void;
@@ -246,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
@@ -352,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>;
     /**