@fieldia/core 0.27.0 → 0.29.0

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

@@ -8,8 +8,9 @@ import { type AppFunctions } from '../expression/app-functions';
 import { type AskedFor } from './compute';
 import { type FieldTone, type LineState } from './cells';
 import { type Messages } from './messages';
-import { type DataSource, type RecordChanges, type RecordPermissions, type RecordVersion, type ResolvedFilter, type SaveProblem, type BotReport, type SlotsResult, type UploadFile, type DuplicateMatch, type MergeResult, type SavedDraft } from './data-source';
+import { type DataSource, type RecordChanges, type RecordPermissions, type RecordVersion, type ResolvedFilter, type SaveProblem, type BotReport, type SlotsResult, type UploadFile, type DuplicateMatch, type MergeResult, type SavedDraft, type ApprovalDecision } from './data-source';
 import { type FormLimits } from './taking';
+import { type FormApproval } from './approving';
 import { type WaitsFor } from './waits';
 import { type FileUpload, type UploadHow } from './uploads';
 import { type Scheduler } from './scheduler';
@@ -123,6 +124,12 @@ export interface FormState {
         readonly key: string;
         readonly missing?: boolean;
     } | null;
+    /**
+     * The record's approvals, on a page with `approval` whose data source tells them (`approvals`): its levels and where
+     * each stands, what was decided, the levels this person may decide, and whether it waits — when its fields lock but
+     * for those the page leaves open. Null for a new record, or a page without them.
+     */
+    readonly approval?: FormApproval | null;
 }
 /** A response sent, as `FormState.sent` keeps it. */
 export interface SentResponse {
@@ -139,6 +146,11 @@ export interface SearchOptions {
     ids?: RecordId[];
     /** Only the records named exactly the query, in any case (`SearchRequest.exact`): a typed name read as a record. */
     exact?: boolean;
+    /**
+     * Only the records whose `field` holds the query exactly — a code read by a scanner, by the field holding the linked
+     * records' codes ("barcode") — asked through the search's filter, whatever their names.
+     */
+    field?: string;
 }
 /** Text left in a box that does not read, and why, as `FormState.unread` keeps it. */
 export interface UnreadText {
@@ -368,8 +380,8 @@ export interface FormOptions {
     };
     /**
      * How a field's value reads inside the page's own words — a `{field}` in a label, a help, a choice, a step's title, a
-     * button, an ending — and so inside the form's messages that name a label ("How was your visit to Zamalek? is
-     * required"). The viewer gives its own, as each field shows its value at rest: a choice by its label, money with its
+     * button, an ending — and so inside the form's messages that name a label ("Please answer “How was your visit to
+     * Zamalek?”"). The viewer gives its own, as each field shows its value at rest: a choice by its label, money with its
      * currency, a day in the page's order. Left out, a choice by its label, a link by its name, a yes or no as Yes or No,
      * anything else as it is held.
      */
@@ -429,11 +441,13 @@ export interface Form {
     /** What a field would be told if the form were checked now, or null when it passes. Nothing is shown. */
     problem(field: string): string | null;
     /**
-     * What a value worked out from others waits for while one of them holds text that does not read (`unread`): a
-     * total of the page's own (`compute`) over a table whose line says "abc" in its Quantity, or an amount the app
-     * works out as the lines change (read-only, from a source with an onchange) — the line, as people count them, and
-     * its cell. Shown, it is a dash said in words, as the table's own total waits: never an amount worked out from the
-     * value that text replaced. Null when it shows its value.
+     * What a value worked out from others waits for while one of them holds text that does not read (`unread`), or an
+     * answer the form refuses (shown, not empty, and refused by its checks: an area under its least, a day past today):
+     * a total of the page's own (`compute`) over a table whose line says "abc" in its Quantity, a price per m² over an
+     * area of −50, or an amount the app works out as the lines change (read-only, from a source with an onchange) — the
+     * line, as people count them, and its cell. Shown, it is a dash said in words, as the table's own total waits: never
+     * an amount worked out from the value that text replaced, or from one refused. Then what is asked of the app's
+     * server for it (`asking`). Null when it shows its value.
      */
     waitsFor(field: string): WaitsFor | null;
     /**
@@ -693,6 +707,23 @@ export interface Form {
      * show what it tells (`limits`). The form asks it itself as it opens, before its answers go, and after they went.
      */
     refreshLimits(): Promise<void>;
+    /**
+     * Ask the data source's `approvals` again for the record shown, and keep what it tells (`approval`). The form asks it
+     * itself as a saved record is shown, after each save, and after a decision.
+     */
+    refreshApprovals(): Promise<void>;
+    /**
+     * Decide at a level of the record's approvals this person may decide now (`approval.mine`): approved, or rejected
+     * with why — a rejection always says why. What is typed is read and the person's changes saved first; the source's
+     * `decide` takes it; the record is loaded again after, its approvals with it. Rejects in words where the level is not
+     * theirs to decide now, a rejection gives no reason, the save is refused, or the source refused the decision.
+     */
+    decide(level: string, decision: ApprovalDecision, reason?: string): Promise<void>;
+    /**
+     * What a field's lock says while the record waits for approval — locked but for the fields the page leaves open
+     * (`approval.open`) — or null where no approval locks it.
+     */
+    approvalLock(name: string): string | null;
     /**
      * 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
@@ -772,6 +803,8 @@ export interface Form {
      * 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.
+     * `how.replaces`: the file is stored for bytes the field holds (a photo
+     * cropped), its link taking their place once stored, as a save's would.
      */
     upload(field: string, files: readonly UploadFile[], how?: UploadHow): string[];
     /**

package/src/lib/record/form.js

@@ -27,6 +27,8 @@ const record_words_1 = require("./record-words");
 const line_choices_1 = require("./line-choices");
 const data_source_1 = require("./data-source");
 const taking_1 = require("./taking");
+const languages_1 = require("./languages");
+const approving_1 = require("./approving");
 const drafts_1 = require("./drafts");
 const waits_1 = require("./waits");
 const uploads_1 = require("./uploads");
@@ -91,7 +93,9 @@ function innerForm(options, within, place, outer) {
     const page = (0, zoned_1.zonedPage)(options.page);
     const scheduler = options.scheduler ?? scheduler_1.hostScheduler;
     // A field's label small inside a message's sentence where the page asks (`lowerLabels`).
-    const messages = page.lowerLabels ? { ...(options.messages ?? messages_1.MESSAGES.en), lowerLabels: true } : (options.messages ?? messages_1.MESSAGES.en);
+    // …and a day written in the page's order where it says one (`look.dateOrder`): "can't be after Oct 20, 2026".
+    const dateOrder = page.look?.dateOrder;
+    const messages = page.lowerLabels || dateOrder ? { ...(options.messages ?? messages_1.MESSAGES.en), lowerLabels: page.lowerLabels, dateOrder } : (options.messages ?? messages_1.MESSAGES.en);
     /** One of the form's sentences in the words the page names its records by (`records`), else as the language says it plainly. */
     const named = (noun, plain) => (0, record_words_1.recordSentence)(page.records, noun, plain, messages.locale);
     /** The app's functions the page's expressions call: a name none may call is refused now. */
@@ -365,6 +369,7 @@ function innerForm(options, within, place, outer) {
         // Worked out once the form has its state, as the limits part comes (`limitsCode`).
         limits: null,
         resume: null,
+        approval: null,
     };
     started = true;
     /**
@@ -556,6 +561,7 @@ function innerForm(options, within, place, outer) {
     let edit = false;
     function set(patch) {
         const was = state.values;
+        const choicesWas = state.choices;
         const shown = state.errors;
         const edited = edit;
         edit = false;
@@ -564,6 +570,12 @@ function innerForm(options, within, place, outer) {
         // A line's choices go with their line.
         if (state.values !== was)
             state = { ...state, choices: choicesNow(state.choices) };
+        // What was said taken out is said while it is true: an option offered again, or picked again, is said no more.
+        if ((state.values !== was || state.choices !== choicesWas) && Object.keys(state.takenOut).length) {
+            const takenOut = takenOutTrue();
+            if (takenOut !== state.takenOut)
+                state = { ...state, takenOut };
+        }
         // What waits for an app's answer, as the values shown last settled.
         if (patch.values !== undefined && patch.asked === undefined && !sameAsked(state.asked, askedNow))
             state = { ...state, asked: Object.fromEntries(askedNow) };
@@ -864,7 +876,9 @@ function innerForm(options, within, place, outer) {
         const written = line
             ? (values[field] ?? []).map((l) => (l.key === line.key ? { ...l, values: { ...l.values, [line.column]: without(l.values[line.column]) } } : l))
             : without(values[field]);
-        writeValues({ ...values, [field]: written }, {}, false, { [line ? `${field}.${line.key}.${line.column}` : field]: takenOutWords(labels) });
+        const path = line ? `${field}.${line.key}.${line.column}` : field;
+        takenOutOf.set(path, lost.map((value, i) => ({ value, label: labels[i] })));
+        writeValues({ ...values, [field]: written }, {}, false, { [path]: takenOutWords(labels) });
         afterEdit(field);
         changed(field, 'step', { keep: true });
     }
@@ -952,6 +966,10 @@ function innerForm(options, within, place, outer) {
     }
     if ((0, choice_options_1.hasOptionRules)(page))
         void track(optionsCode());
+    // A text in several languages is checked by the languages part: asked for at once, a save waiting for it.
+    const languagesCode = () => languages_1.formLanguagesPart.load().then(() => undefined, () => undefined);
+    if ((0, languages_1.hasLanguages)(page))
+        void track(languagesCode());
     /** A table line's choice's options as they are offered on that line: its list's once loaded, or its own, by their conditions once they came. */
     function lineOffered(lines, line, column, record) {
         if (optionKit)
@@ -973,6 +991,38 @@ function innerForm(options, within, place, outer) {
      * "Garden is no longer offered, so it was taken out".
      */
     const takenOutWords = (labels) => (0, messages_1.fillMessage)(messages, labels.length > 1 ? messages.notOfferedNowMany : messages.notOfferedNow, { name: listedLabels(labels.map((label) => (label.includes('{') ? wordsNow(label) : label))) });
+    /** The options each note of `takenOut` names, by its path: a note goes once none of them is still out. */
+    const takenOutOf = new Map();
+    /**
+     * The notes of options taken out (`FormState.takenOut`) that are still true for the values and the choices now: one
+     * whose options are all offered again — the type that offers them picked again, the treatment ticked again above, the
+     * app's list asked again offering it — or picked again goes; one with some still out names those. A list being asked
+     * again says nothing yet. The same notes, when none changed.
+     */
+    function takenOutTrue() {
+        let kept = null;
+        for (const path of Object.keys(state.takenOut)) {
+            const options = takenOutOf.get(path);
+            const held = valueAt(state.values, path);
+            if (!options || held === gone || state.choices[path]?.loading)
+                continue;
+            const offered = form.offered(path);
+            if (!offered)
+                continue;
+            const chosen = [held].flat();
+            const left = options.filter((option) => !chosen.includes(option.value) && !offered.some((one) => one.value === option.value));
+            if (left.length === options.length)
+                continue;
+            kept ??= { ...state.takenOut };
+            if (left.length) {
+                takenOutOf.set(path, left);
+                kept[path] = takenOutWords(left.map((option) => option.label));
+            }
+            else
+                delete kept[path];
+        }
+        return kept ?? state.takenOut;
+    }
     /** A line's field as its value is checked: its choices from the app's list, those loaded for its line. */
     function checkedLine(path, def) {
         const loaded = def.type === 'selection' && (0, choice_options_1.optionsList)(def.optionsFrom) ? state.choices[path]?.options : null;
@@ -1087,6 +1137,9 @@ function innerForm(options, within, place, outer) {
         const answer = answerOf(node);
         if (answer !== undefined && signedNow().has(answer))
             readonly = true;
+        // A record waiting for approval: locked but for the fields the page leaves open (the approvals part).
+        if (answer !== undefined && approvalKit?.locks(answer))
+            readonly = true;
         return {
             invisible,
             readonly: readonly || (def !== undefined && lockedField(def)),
@@ -1158,6 +1211,23 @@ function innerForm(options, within, place, outer) {
         const name = node.field;
         return unticked(node) ?? (0, inputs_1.checkInput)(page.fields[name], node.source, state.values[name], messages) ?? (0, check_1.checkValue)(checked(name), state.values[name], nodeState(node.id).required, messages, today(), node.source.widget) ?? ruleCheck(node).error;
     }
+    /** What a check would refuse now (`collectErrors`), for the state it was found for. */
+    let refusals = null;
+    /**
+     * Whether the form refuses the answer at a path — a field's, or a table line's cell (`field.lineKey.subfield`) — as a
+     * check would now: one it shows that holds a value its rules do not take (under its least, past today, a pattern not
+     * met, an answer rule's error). An empty answer is none, required or not: there is nothing worked out from it to wait.
+     */
+    function refusedAt(path) {
+        if (refusals?.state !== state)
+            refusals = { state, errors: collectErrors() };
+        if (!refusals.errors[path])
+            return false;
+        const parts = path.split('.');
+        const def = page.fields[parts[0]];
+        const held = valueAt(state.values, path);
+        return held !== gone && !(0, values_1.isEmpty)((parts.length > 2 && def?.type === 'one2many' ? def.fields[parts[parts.length - 1]] : def), held);
+    }
     /** Warnings for the visible fields of the page, without publishing them. */
     function collectWarnings() {
         const warnings = {};
@@ -1426,6 +1496,8 @@ function innerForm(options, within, place, outer) {
         if (out) {
             settled = out.values;
             takenOut = { ...takenOut, ...out.said };
+            for (const [path, gone] of Object.entries(out.gone))
+                takenOutOf.set(path, gone);
         }
         if (Object.keys(takenOut).length || Object.keys(state.takenOut).length)
             extra = { takenOut, ...extra };
@@ -1706,6 +1778,15 @@ function innerForm(options, within, place, outer) {
     }
     /** A choice of a full option, picked by the person, refused under its field: the field keeps what it held. */
     const refusedFull = (name, value) => !!limitsKit?.refusedFull(name, value);
+    // ---- a record's approvals (the approvals part: form-approvals.ts) ---------------------------------------------------
+    /** The approvals made for this form from the approvals part, once it came: none before, nor on a page without them. */
+    let approvalKit = null;
+    /** Whether the form asks for approvals: a page with `approval` (a record's own, as its check says), its source telling them. */
+    const keepsApprovals = !outer && !!page.approval && !!options.dataSource?.approvals;
+    /** The approvals, made from their part once it came; null without them, or where it could not come. */
+    const approvalsCode = () => keepsApprovals ? approving_1.formApprovalsPart.load().then((part) => (approvalKit ??= part.formApprovals({ form, dataSource: options.dataSource, messages, set, reload: () => load(true) })), () => null) : Promise.resolve(null);
+    /** Ask the record shown's approvals, once their part came; nothing on a page without them. */
+    const askApprovals = () => approvalsCode().then((kit) => kit?.ask());
     function scheduleAutosave() {
         const autosave = options.autosave;
         // A record the person may not change is never saved unasked: it would only be refused.
@@ -1852,6 +1933,12 @@ function innerForm(options, within, place, outer) {
             if (asked !== generation)
                 return elsewhere();
         }
+        // A text in several languages, checked in each once its part has come.
+        if (!languages_1.formLanguagesPart.loaded && (0, languages_1.hasLanguages)(page)) {
+            await languagesCode();
+            if (asked !== generation)
+                return elsewhere();
+        }
         // Values the app's functions are asked for are waited for — those that failed asked again — so what is saved is worked out.
         if (asking.size || Object.values(state.asked).some((found) => found.failed !== undefined)) {
             set({ status: 'saving', error: null, saveProblem: null });
@@ -1975,6 +2062,9 @@ function innerForm(options, within, place, outer) {
                 scheduleDraft();
                 scheduleAutosave();
             }
+            // A save may have sent it for approval, or moved it on: its approvals asked again.
+            if (keepsApprovals)
+                void track(askApprovals());
             // The record as this save left it: a change made while it was on its way is no value of it.
             emit('save', { recordId: state.recordId, values: baseline });
             void track(moment('on.afterSave', page.on?.afterSave, chain, false));
@@ -2181,7 +2271,7 @@ function innerForm(options, within, place, outer) {
             throw new Error(`"${name}" cannot make records: its data source has no create, or it is not a link`);
         return track(source.create({ model, name: typed.trim(), ...(Object.keys(values).length ? { values } : {}) }));
     }
-    async function runSearch(def, name, ctx, query, limit, { model, ids, exact } = {}) {
+    async function runSearch(def, name, ctx, query, limit, { model, ids, exact, field } = {}) {
         // Formatted text names people and records in place (@mention, #4127): searched by the model they are of.
         const byModel = def.type === 'reference' || def.type === 'json' || def.type === 'html';
         if (def.type !== 'many2one' && def.type !== 'many2many' && !byModel) {
@@ -2194,9 +2284,11 @@ function innerForm(options, within, place, outer) {
             return [];
         // Every valueFrom, in groups too, becomes the value it names before the search goes out.
         const own = byModel || !def.filter ? undefined : (0, filter_1.resolveFilter)(def.filter, ctx);
-        const filter = ids ? [...(own ?? []), { field: 'id', op: 'in', value: ids }] : own;
+        const kept = ids ? [...(own ?? []), { field: 'id', op: 'in', value: ids }] : own;
+        // A code read by a scanner: the records whose field holds it, whatever their names.
+        const filter = field ? [...(kept ?? []), { field, op: '=', value: query }] : kept;
         const relation = byModel ? model : def.relation;
-        return track(source.search({ model: relation, query, ...(filter ? { filter } : {}), limit, ...(exact ? { exact: true } : {}) }));
+        return track(source.search({ model: relation, query: field ? '' : query, ...(filter ? { filter } : {}), limit, ...(exact ? { exact: true } : {}) }));
     }
     function lineField(field) {
         const def = fieldDef(field);
@@ -2237,6 +2329,9 @@ function innerForm(options, within, place, outer) {
             loadedOnce = true;
             if (asksLimits())
                 void track(askLimits());
+            // Its approvals: where it stands, what was decided, what this person may decide — its fields locked while it waits.
+            if (keepsApprovals)
+                void track(askApprovals());
             if (again)
                 return;
             offerDraft();
@@ -2269,7 +2364,7 @@ function innerForm(options, within, place, outer) {
         found = null;
         serverKey = null;
         draftEpoch++;
-        const fresh = { dirty: [], errors: {}, warning: null, warningField: null, error: null, draft: null, step: steps[0] ?? null, skipped: [], saveProblem: null, version: null, can: null, conflict: null, setAside: null, unsent: [], unread: {}, takenOut: {}, resume: null };
+        const fresh = { dirty: [], errors: {}, warning: null, warningField: null, error: null, draft: null, step: steps[0] ?? null, skipped: [], saveProblem: null, version: null, can: null, conflict: null, setAside: null, unsent: [], unread: {}, takenOut: {}, resume: null, approval: null };
         if (id != null) {
             set({ ...fresh, recordId: id, status: 'idle' });
             await load();
@@ -2688,7 +2783,7 @@ function innerForm(options, within, place, outer) {
             // Nothing of the record changed; what shows of it may have.
             set({});
         },
-        fieldReadonly: (name) => lockedField(fieldDef(name)) || state.can?.edit === false || state.can?.readonlyFields?.includes(name) === true || signedNow().has(name),
+        fieldReadonly: (name) => lockedField(fieldDef(name)) || state.can?.edit === false || state.can?.readonlyFields?.includes(name) === true || signedNow().has(name) || !!approvalKit?.locks(name),
         loadChoices: (field) => loadChoices(field),
         loadDefinitions,
         addDefinition,
@@ -2713,11 +2808,13 @@ function innerForm(options, within, place, outer) {
             return (0, choice_options_1.changesOptions)(cell ? (lines?.type === 'one2many' ? lines.fields[cell.column] : undefined) : page.fields[name]);
         },
         waitsFor(name) {
-            const found = state.asked[name];
-            if (found)
-                return { field: name, asking: true, ...(found.failed !== undefined ? { failed: found.failed } : {}) };
+            // What it is worked out from first: an answer that does not read, or that the form refuses, is never asked about.
             const from = workedOut.get(name);
-            return from ? (0, waits_1.waitingOn)(page, from, state.values, state.unread) : null;
+            const waits = from ? (0, waits_1.waitingOn)(page, from, state.values, state.unread, refusedAt) : null;
+            if (waits)
+                return waits;
+            const found = state.asked[name];
+            return found ? { field: name, asking: true, ...(found.failed !== undefined ? { failed: found.failed } : {}) } : null;
         },
         problem(name) {
             fieldDef(name);
@@ -3184,6 +3281,14 @@ function innerForm(options, within, place, outer) {
             return saved;
         },
         refreshLimits: () => askLimits(),
+        refreshApprovals: askApprovals,
+        async decide(level, decision, reason) {
+            const kit = await approvalsCode();
+            if (!kit)
+                throw new Error('No approvals on this page');
+            return track(kit.decide(level, decision, reason));
+        },
+        approvalLock: (name) => approvalKit?.lockWords(name) ?? null,
         async reloadTheirs() {
             // A save on its way first: its answer is not dropped by the load.
             const asked = shownNow();
@@ -3368,6 +3473,9 @@ function innerForm(options, within, place, outer) {
     // choice's places as the source tells them: a record's own once it is loaded, its own choices not counted against it.
     if (keepsLimits())
         void track(limitsCode());
+    // A record's approvals: their part asked for as the form is made, ready by the time its record is loaded.
+    if (keepsApprovals)
+        void track(approvalsCode());
     // A new form has its values now — a draft continued from its key once it is laid — and opens once whoever made it
     // has had the chance to listen.
     if (state.recordId == null) {