@fieldia/core 0.9.2 → 0.10.0

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

@@ -1,3 +1,4 @@
+import type { Option } from '../format/field.mjs';
 import type { JsonValue } from '../format/json.mjs';
 import type { Page } from '../format/page.mjs';
 import { type Messages } from './messages.mjs';
@@ -13,6 +14,11 @@ export interface FormState {
     readonly errors: Readonly<Record<string, string>>;
     /** Fields that differ from the record as loaded or last saved. */
     readonly dirty: readonly string[];
+    /**
+     * Warnings by field name, from answer rules at the warning level: shown,
+     * never blocking. Kept current as values change, for the fields people can see.
+     */
+    readonly warnings: Readonly<Record<string, string>>;
     /** A warning from the data source's onchange, shown without blocking. */
     readonly warning: string | null;
     /** The field whose change brought the warning, so it can be shown beside it. */
@@ -29,6 +35,16 @@ export interface FormState {
     readonly skipped: readonly string[];
     /** Why the last save was refused, until the next one starts or the form is reset. */
     readonly saveProblem: SaveProblem | null;
+    /** The choices loaded from the app's lists, by field: those of a selection with `optionsFrom`, once asked for. */
+    readonly choices: Readonly<Record<string, Choices>>;
+}
+/** A field's choices from one of the app's lists, as they load. */
+export interface Choices {
+    /** The choices last loaded: null until the first load ends well. */
+    readonly options: Option[] | null;
+    readonly loading?: boolean;
+    /** Why the last load failed. */
+    readonly error?: string;
 }
 /** What a layout element looks like right now. */
 export interface NodeState {
@@ -74,6 +90,8 @@ export interface FormOptions {
     scheduler?: Scheduler;
     /** Validation messages in the page's language. English by default. */
     messages?: Messages;
+    /** The clock, for `today()` and for dates that must be past or future. The computer's own when left out. */
+    now?: () => Date;
 }
 export interface Form {
     readonly page: Page;
@@ -100,6 +118,12 @@ export interface Form {
      * written: the record, its changes and its autosave stay as they are.
      */
     previewLine(field: string, key: string, values: Values): Promise<Values>;
+    /**
+     * Load, or load again, the choices of a selection whose options come from
+     * the app's list (`optionsFrom`). Once loaded, they load again by themselves
+     * when a field they change with changes; the latest answer wins.
+     */
+    loadChoices(field: string): void;
     /** Records a many2one, many2many or reference may point to. A reference needs `options.model`. */
     search(field: string, query: string, limit?: number, options?: {
         model?: string;

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

@@ -1,3 +1,4 @@
+import type { Option } from '../format/field';
 import type { JsonValue } from '../format/json';
 import type { Page } from '../format/page';
 import { type Messages } from './messages';
@@ -13,6 +14,11 @@ export interface FormState {
     readonly errors: Readonly<Record<string, string>>;
     /** Fields that differ from the record as loaded or last saved. */
     readonly dirty: readonly string[];
+    /**
+     * Warnings by field name, from answer rules at the warning level: shown,
+     * never blocking. Kept current as values change, for the fields people can see.
+     */
+    readonly warnings: Readonly<Record<string, string>>;
     /** A warning from the data source's onchange, shown without blocking. */
     readonly warning: string | null;
     /** The field whose change brought the warning, so it can be shown beside it. */
@@ -29,6 +35,16 @@ export interface FormState {
     readonly skipped: readonly string[];
     /** Why the last save was refused, until the next one starts or the form is reset. */
     readonly saveProblem: SaveProblem | null;
+    /** The choices loaded from the app's lists, by field: those of a selection with `optionsFrom`, once asked for. */
+    readonly choices: Readonly<Record<string, Choices>>;
+}
+/** A field's choices from one of the app's lists, as they load. */
+export interface Choices {
+    /** The choices last loaded: null until the first load ends well. */
+    readonly options: Option[] | null;
+    readonly loading?: boolean;
+    /** Why the last load failed. */
+    readonly error?: string;
 }
 /** What a layout element looks like right now. */
 export interface NodeState {
@@ -74,6 +90,8 @@ export interface FormOptions {
     scheduler?: Scheduler;
     /** Validation messages in the page's language. English by default. */
     messages?: Messages;
+    /** The clock, for `today()` and for dates that must be past or future. The computer's own when left out. */
+    now?: () => Date;
 }
 export interface Form {
     readonly page: Page;
@@ -100,6 +118,12 @@ export interface Form {
      * written: the record, its changes and its autosave stay as they are.
      */
     previewLine(field: string, key: string, values: Values): Promise<Values>;
+    /**
+     * Load, or load again, the choices of a selection whose options come from
+     * the app's list (`optionsFrom`). Once loaded, they load again by themselves
+     * when a field they change with changes; the latest answer wins.
+     */
+    loadChoices(field: string): void;
     /** Records a many2one, many2many or reference may point to. A reference needs `options.model`. */
     search(field: string, query: string, limit?: number, options?: {
         model?: string;

package/src/lib/record/form.js

@@ -2,7 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createForm = createForm;
 const modifier_1 = require("../expression/modifier");
+const functions_1 = require("../expression/functions");
 const check_1 = require("./check");
+const inputs_1 = require("./inputs");
+const compute_1 = require("./compute");
+const set_when_1 = require("./set-when");
+const rules_1 = require("./rules");
+const env_1 = require("./env");
 const messages_1 = require("./messages");
 const data_source_1 = require("./data-source");
 const scheduler_1 = require("./scheduler");
@@ -17,15 +23,30 @@ function createForm(options) {
     const scheduler = options.scheduler ?? scheduler_1.hostScheduler;
     const messages = options.messages ?? messages_1.MESSAGES.en;
     const index = indexLayout(page.layout);
+    /** Each field node's answer rules, read once. */
+    const nodeRules = new Map();
+    for (const node of index.values()) {
+        const rules = node.source.validate;
+        if (node.kind === 'field' && rules)
+            nodeRules.set(node.id, (0, rules_1.compileRules)(rules));
+    }
+    /** Whether any rule only warns: without one, there are never warnings to look for. */
+    const warns = [...nodeRules.values()].some((rules) => rules.some((compiled) => compiled.rule.level === 'warning'));
     const steps = page.layout.type === 'wizard' ? page.layout.children.map((step) => step.id) : [];
     const draftKey = () => `fieldia:draft:${page.id}:${state.recordId ?? 'new'}`;
-    let baseline = { ...(0, values_1.initialValues)(page.fields), ...(0, values_1.structuredCopy)(options.values ?? {}) };
+    const today = () => (0, functions_1.localDay)(options.now?.() ?? new Date());
+    const computed = (0, compute_1.compileComputed)(page, today);
+    const setWhen = (0, set_when_1.compileSetWhen)(page, today);
+    let baseline = computed.apply({ ...(0, values_1.initialValues)(page.fields, today()), ...(0, values_1.structuredCopy)(options.values ?? {}) });
+    /** The setWhen conditions holding for the values as they last settled: one starts to hold only against these. */
+    let holding = setWhen.holding(baseline);
     let state = {
         status: options.recordId != null ? 'idle' : 'ready',
         recordId: options.recordId ?? null,
         values: (0, values_1.structuredCopy)(baseline),
         errors: {},
         dirty: [],
+        warnings: {},
         warning: null,
         warningField: null,
         error: null,
@@ -33,6 +54,7 @@ function createForm(options) {
         step: steps[0] ?? null,
         skipped: [],
         saveProblem: null,
+        choices: {},
     };
     /** Field errors a refused save brought, each kept until its field changes from the value it was refused with. */
     let serverErrors = {};
@@ -43,10 +65,36 @@ function createForm(options) {
     const pending = new Set();
     const listeners = new Set();
     let contextCache = null;
+    /** The latest load of each field's choices: an answer to an older one is let go. */
+    const choiceLoads = {};
     function set(patch) {
+        const was = state.values;
         state = { ...state, ...patch };
         for (const listener of [...listeners])
             listener(state);
+        // Choices that change with a value that just changed are asked for again.
+        if (state.values !== was) {
+            for (const name in state.choices)
+                if (fromList(name).dependsOn?.some((other) => was[other] !== state.values[other]))
+                    loadChoices(name);
+        }
+    }
+    const fromList = (name) => page.fields[name].optionsFrom;
+    function loadChoices(name) {
+        const { list } = fromList(name);
+        const load = (choiceLoads[name] = (choiceLoads[name] ?? 0) + 1);
+        const put = (choices) => load === choiceLoads[name] && set({ choices: { ...state.choices, [name]: choices } });
+        // What was shown stays while the next ones load, so the list does not flash empty.
+        const shown = state.choices[name]?.options ?? null;
+        put({ options: shown, loading: true });
+        const source = options.dataSource;
+        void track((source?.options ? source.options({ list, values: (0, values_1.structuredCopy)(state.values) }) : Promise.reject(new Error(`No list "${list}"`))).then((loaded) => put({ options: loaded }), (error) => put({ options: shown, error: error.message ?? String(error) })));
+    }
+    /** A field as its value is checked: a list's choices are those loaded, and until they are, any choice may be one. */
+    function checked(name) {
+        const def = page.fields[name];
+        const loaded = state.choices[name]?.options;
+        return def.type === 'selection' && def.optionsFrom && loaded ? { ...def, options: loaded, optionsFrom: undefined } : def;
     }
     function track(promise) {
         pending.add(promise);
@@ -54,12 +102,15 @@ function createForm(options) {
         promise.then(done, done);
         return promise;
     }
-    function context() {
+    /** The values as expressions read them, and what else they read: the lines' rows, today. */
+    function reading() {
         if (contextCache?.values !== state.values) {
-            contextCache = { values: state.values, context: (0, values_1.expressionContext)(state.values, page.fields) };
+            const values = state.values;
+            contextCache = { values, context: (0, values_1.expressionContext)(values, page.fields), env: (0, env_1.expressionEnv)(values, page.fields, today) };
         }
-        return contextCache.context;
+        return contextCache;
     }
+    const context = () => reading().context;
     function fieldDef(name) {
         const def = page.fields[name];
         if (!def)
@@ -73,21 +124,21 @@ function createForm(options) {
         const node = index.get(id);
         if (!node)
             throw new Error(`The page has no element "${id}"`);
-        const ctx = context();
-        let invisible = node.invisible.evaluate(ctx);
+        const { context: ctx, env } = reading();
+        let invisible = node.invisible.evaluate(ctx, env);
         for (let parent = node.parent; !invisible && parent; parent = index.get(parent)?.parent ?? null) {
-            invisible = index.get(parent)?.invisible.evaluate(ctx) ?? false;
+            invisible = index.get(parent)?.invisible.evaluate(ctx, env) ?? false;
         }
         // A section read-only right now makes everything inside it read-only too.
-        let readonly = node.readonly.evaluate(ctx);
+        let readonly = node.readonly.evaluate(ctx, env);
         for (let parent = node.parent; !readonly && parent; parent = index.get(parent)?.parent ?? null) {
-            readonly = index.get(parent)?.readonly.evaluate(ctx) ?? false;
+            readonly = index.get(parent)?.readonly.evaluate(ctx, env) ?? false;
         }
         const def = node.field ? page.fields[node.field] : undefined;
         return {
             invisible,
-            readonly: readonly || def?.readonly === true,
-            required: node.required.evaluate(ctx) || def?.required === true,
+            readonly: readonly || (def !== undefined && lockedField(def)),
+            required: node.required.evaluate(ctx, env) || def?.required === true,
         };
     }
     /** Field nodes inside `root` (or the whole page), visible right now. */
@@ -111,6 +162,51 @@ function createForm(options) {
         };
         return [...index.values()].filter((node) => node.kind === 'field' && inside(node) && !skipped(node) && !nodeState(node.id).invisible);
     }
+    /** What a field node's answer rules say of its value now: the first error and the first warning. */
+    function ruleCheck(node) {
+        const rules = nodeRules.get(node.id);
+        if (!rules)
+            return {};
+        const name = node.field;
+        const def = page.fields[name];
+        const label = node.source.label ?? def.label;
+        const { context: ctx, env } = reading();
+        return (0, rules_1.checkRules)(def, label, state.values[name], rules, { context: ctx, env, now: options.now?.() ?? new Date(), messages });
+    }
+    /** A tick box required and not ticked, as an "I agree" box: "no" answers a yes or no, never a box to tick. */
+    function unticked(node) {
+        const name = node.field;
+        const ticks = node.source.widget === 'tick' && page.fields[name].type === 'boolean';
+        return ticks && state.values[name] !== true && nodeState(node.id).required ? messages.tick : undefined;
+    }
+    /** A field node's error now: its field's own rules first, then its answer rules. */
+    function nodeError(node) {
+        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()) ?? ruleCheck(node).error;
+    }
+    /** Warnings for the visible fields of the page, without publishing them. */
+    function collectWarnings() {
+        const warnings = {};
+        if (!warns)
+            return warnings;
+        for (const node of visibleFieldNodes()) {
+            const warning = nodeRules.has(node.id) ? ruleCheck(node).warning : undefined;
+            if (warning)
+                warnings[node.field] ??= warning;
+        }
+        return warnings;
+    }
+    /** What would be found for these values, without publishing them or touching the form. */
+    function withValues(values, find) {
+        const previous = state;
+        state = { ...state, values };
+        try {
+            return find();
+        }
+        finally {
+            state = previous;
+        }
+    }
     /** Errors for the visible fields under `root`, without publishing them. */
     function collectErrors(root) {
         const errors = {};
@@ -119,7 +215,7 @@ function createForm(options) {
             if (errors[name])
                 continue;
             const def = page.fields[name];
-            const message = (0, check_1.checkValue)(def, state.values[name], nodeState(node.id).required, messages);
+            const message = nodeError(node);
             if (message)
                 errors[name] = message;
             if (def.type === 'one2many') {
@@ -129,7 +225,7 @@ function createForm(options) {
                     for (const [sub, subDef] of Object.entries(def.fields)) {
                         if (kind && sub !== def.lineKinds?.text)
                             continue;
-                        const lineMessage = (0, check_1.checkValue)(subDef, line.values[sub], subDef.required === true, messages);
+                        const lineMessage = (0, check_1.checkValue)(subDef, line.values[sub], subDef.required === true, messages, today());
                         if (lineMessage)
                             errors[`${name}.${line.key}.${sub}`] = lineMessage;
                     }
@@ -138,16 +234,37 @@ function createForm(options) {
         }
         return errors;
     }
-    function writeValues(values, extra = {}) {
+    /**
+     * Values as they settle after a change: worked out, then set where a
+     * condition started to hold, then worked out again from what was set — a
+     * few rounds at most, so rules that set each other cannot run forever.
+     */
+    function settle(written) {
+        let values = computed.apply(written);
+        for (let round = 0; round < 8; round++) {
+            const result = setWhen.apply(values, holding);
+            holding = result.holding;
+            if (result.values === values)
+                break;
+            values = computed.apply(result.values);
+        }
+        return values;
+    }
+    /** Values to start again from, as loaded or restored: conditions holding in them hold already, and set nothing. */
+    function startFrom(values) {
+        const worked = computed.apply(values);
+        holding = setWhen.holding(worked);
+        return worked;
+    }
+    /** Write values someone or something changed. `fresh` values are a starting point instead (a restored draft). */
+    function writeValues(written, extra = {}, fresh = false) {
+        const values = fresh ? startFrom(written) : settle(written);
         const errors = Object.keys(state.errors).length ? revalidateShown(values) : state.errors;
-        set({ values, dirty: dirtyFields(values), errors, ...extra });
+        set({ values, dirty: dirtyFields(values), errors, warnings: withValues(values, collectWarnings), ...extra });
     }
     /** Once errors are on screen, keep them current as the person fixes things. */
     function revalidateShown(values) {
-        const previous = state;
-        state = { ...state, values };
-        const fresh = collectErrors(state.step ?? undefined);
-        state = previous;
+        const fresh = withValues(values, () => collectErrors(state.step ?? undefined));
         const kept = {};
         for (const key of Object.keys(state.errors))
             if (fresh[key])
@@ -193,7 +310,7 @@ function createForm(options) {
             return;
         }
         if (drafts.restore === 'auto')
-            writeValues({ ...state.values, ...draft.values }, { draft: null });
+            writeValues({ ...state.values, ...draft.values }, { draft: null }, true);
         else
             set({ draft: { savedAt: draft.savedAt } });
     }
@@ -285,9 +402,9 @@ function createForm(options) {
                 values: (0, values_1.structuredCopy)(state.values),
             });
             forgetDraft();
-            const values = result.values ? { ...state.values, ...result.values } : state.values;
+            const values = startFrom(result.values ? { ...state.values, ...result.values } : state.values);
             baseline = (0, values_1.structuredCopy)(values);
-            set({ status: 'saved', recordId: result.id, values, dirty: [] });
+            set({ status: 'saved', recordId: result.id, values, dirty: [], warnings: withValues(values, collectWarnings) });
             return true;
         }
         catch (error) {
@@ -354,8 +471,8 @@ function createForm(options) {
         set({ status: 'loading', error: null });
         try {
             const loaded = await source.load({ model: page.data.model, id: state.recordId, fields: page.fields });
-            baseline = { ...(0, values_1.initialValues)(page.fields), ...loaded };
-            set({ status: 'ready', values: (0, values_1.structuredCopy)(baseline), dirty: [], errors: {} });
+            baseline = startFrom({ ...(0, values_1.initialValues)(page.fields, today()), ...loaded });
+            set({ status: 'ready', values: (0, values_1.structuredCopy)(baseline), dirty: [], errors: {}, warnings: withValues(baseline, collectWarnings) });
             offerDraft();
         }
         catch (error) {
@@ -376,14 +493,18 @@ function createForm(options) {
             afterEdit(name);
         },
         node: nodeState,
-        fieldReadonly: (name) => fieldDef(name).readonly === true,
+        fieldReadonly: (name) => lockedField(fieldDef(name)),
+        loadChoices,
         problem(name) {
-            const def = fieldDef(name);
+            fieldDef(name);
             // Only a field someone can see is asked anything, and required wherever it is shown so.
             const shown = visibleFieldNodes().filter((node) => node.field === name);
             if (!shown.length)
                 return null;
-            return (0, check_1.checkValue)(def, state.values[name], shown.some((node) => nodeState(node.id).required), messages) ?? null;
+            const own = shown.map(unticked).find(Boolean) ??
+                shown.map((node) => (0, inputs_1.checkInput)(page.fields[name], node.source, state.values[name], messages)).find(Boolean) ??
+                (0, check_1.checkValue)(checked(name), state.values[name], shown.some((node) => nodeState(node.id).required), messages, today());
+            return own ?? shown.map((node) => ruleCheck(node).error).find((error) => error !== undefined) ?? null;
         },
         validate() {
             const errors = collectErrors();
@@ -394,14 +515,15 @@ function createForm(options) {
         reset() {
             forgetDraft();
             serverErrors = {};
-            set({ values: (0, values_1.structuredCopy)(baseline), dirty: [], errors: {}, warning: null, warningField: null, draft: null, step: steps[0] ?? null, skipped: [], saveProblem: null });
+            holding = setWhen.holding(baseline);
+            set({ values: (0, values_1.structuredCopy)(baseline), dirty: [], errors: {}, warnings: withValues(baseline, collectWarnings), warning: null, warningField: null, draft: null, step: steps[0] ?? null, skipped: [], saveProblem: null });
         },
         changes,
         addLine(field, values = {}) {
             const def = lineField(field);
             const key = `new-${++lineKeys}`;
             const current = state.values[field] ?? [];
-            const line = { key, values: { ...(0, values_1.initialValues)(def.fields), ...(0, values_1.structuredCopy)(values) } };
+            const line = { key, values: { ...(0, values_1.initialValues)(def.fields, today()), ...(0, values_1.structuredCopy)(values) } };
             // A new line comes last, so it is numbered after the last.
             if (def.sequenceField && line.values[def.sequenceField] == null) {
                 const numbers = current.map((l) => l.values[def.sequenceField]).filter((n) => typeof n === 'number');
@@ -464,14 +586,14 @@ function createForm(options) {
             const line = lines.find((l) => l.key === key);
             if (!line)
                 throw new Error(`"${field}" has no line "${key}"`);
-            const merged = { ...line.values, ...values };
+            const merged = computed.line(field, { ...line.values, ...values });
             const source = options.dataSource;
             if (!source?.onchange || page.data.kind !== 'record')
                 return merged;
             const changed = lines.map((l) => (l.key === key ? { ...l, values: merged } : l));
             const result = await source.onchange({ model: page.data.model, id: state.recordId, changed: field, values: (0, values_1.structuredCopy)({ ...state.values, [field]: changed }) });
             const after = (result.values?.[field] ?? []).find((l) => l.key === key);
-            return after ? { ...merged, ...after.values } : merged;
+            return after ? computed.line(field, { ...merged, ...after.values }) : merged;
         },
         async searchLine(field, key, subfield, query, limit = 8) {
             const def = lineField(field);
@@ -575,7 +697,7 @@ function createForm(options) {
             if (!raw)
                 return;
             const draft = JSON.parse(raw);
-            writeValues({ ...state.values, ...draft.values }, { draft: null });
+            writeValues({ ...state.values, ...draft.values }, { draft: null }, true);
         },
         discardDraft() {
             forgetDraft();
@@ -593,10 +715,16 @@ function createForm(options) {
             listeners.clear();
         },
     };
+    // A record's starting values may already break a warning rule; nothing listens yet.
+    state = { ...state, warnings: collectWarnings() };
     if (state.recordId == null)
         offerDraft();
     return form;
 }
+/** A field no one types in: read-only by its definition, or worked out from others. */
+function lockedField(def) {
+    return def.readonly === true || def.compute !== undefined;
+}
 function lineOps(before, now) {
     const ops = [];
     const old = new Map(before.filter((line) => line.id !== undefined).map((line) => [line.key, line]));