@qoretechnologies/reqraft 0.10.62 → 0.10.63-pr.142.g0b675cd

package/dist/components/form/engine/FormEngine.js

@@ -97,10 +97,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FormEngine = exports.getTypeAndCanBeNull = exports.flattenOptions = exports.shouldEmitLocalValue = exports.agreementFromRebuild = exports.isMirrorOfValue = exports.fixOptions = exports.OptionsContext = exports.hasRequiredOptions = exports.getOptionFieldStorageType = exports.fixOperatorValue = exports.getType = exports.inheritedScopeFor = void 0;
+exports.FormEngine = exports.getTypeAndCanBeNull = exports.flattenOptions = exports.shouldEmitLocalValue = exports.mergeOwnEdits = exports.takeHostsAttributes = exports.agreementFromRebuild = exports.isMirrorOfValue = exports.fixOptions = exports.OptionsContext = exports.hasRequiredOptions = exports.getOptionFieldStorageType = exports.fixOperatorValue = exports.getType = exports.inheritedScopeFor = void 0;
 var react_1 = require("react");
 var jsx_runtime_1 = require("react/jsx-runtime");
 var reqore_1 = require("@qoretechnologies/reqore");
+var readFirstColors_1 = require("./readFirstColors");
+var readableColors_1 = require("../../../helpers/readableColors");
 var colors_1 = require("@qoretechnologies/reqore/dist/helpers/colors");
 var argumentPresence_1 = require("../expressions/argumentPresence");
 var typeChoices_1 = require("./typeChoices");
@@ -132,10 +134,12 @@ var compactRowContext_1 = require("./compactRowContext");
 var compactRowStyles_1 = require("./compactRowStyles");
 var CompactToolbar_1 = require("./CompactToolbar");
 var compactToolbarContext_1 = require("./compactToolbarContext");
+var HiddenFieldsNote_1 = require("./HiddenFieldsNote");
 var OptionFieldMessages_1 = require("./OptionFieldMessages");
 var optionsContext_1 = require("./optionsContext");
 var markdownRendererContext_1 = require("../../Description/markdownRendererContext");
 var OptionsHelpDialog_1 = require("./OptionsHelpDialog");
+var rowFocus_1 = require("./rowFocus");
 var optionUiTypes_1 = require("../../../helpers/optionUiTypes");
 var readFirst_1 = require("./readFirst");
 /**
@@ -228,7 +232,7 @@ var PositiveColorEffect = {
     glow: 'success',
 };
 // Compact (read-first) layout: flat label | value | action rows in collapsible
-// group panels; colours come in as props so the layout follows the Reqore theme.
+// group panels; colors come in as props so the layout follows the Reqore theme.
 var StyledCompactWrap = styled_components_1.default.div(templateObject_3 || (templateObject_3 = __makeTemplateObject(["\n  display: flex;\n  flex-flow: column;\n  gap: 10px;\n  width: 100%;\n  /* Allow the wrap to shrink inside flex/grid parents so its rows' ellipsis can\n     engage instead of overflowing the container horizontally. */\n  min-width: 0;\n  max-width: 100%;\n\n  /* Scroll ownership \u2014 see `compactScroll`.\n\n     'host' (the default): the page or panel around us already scrolls, so we\n     must not cap our height and scroll our own body, or the reader gets two\n     scrollbars in two styles and cannot tell which moves what.\n\n     `overflow-x: clip`, NOT `hidden`: CSS coerces an `overflow-y: visible`\n     to `auto` whenever the other axis is neither visible nor clip, which would\n     leave this box a scroll container \u2014 the element stops scrolling only\n     because `max-height: none` means nothing overflows, while `position:\n     sticky` inside it still resolves against US instead of the host, so the\n     toolbar silently stops pinning. `clip` keeps the horizontal guard without\n     that coercion. */\n  ", "\n\n  /* Option logos (e.g. language images) render as <img> inside ReqoreIcon's\n     square box; constrain them so portrait PNGs don't overflow the row. */\n  .reqore-icon img {\n    width: 100%;\n    height: 100%;\n    object-fit: contain;\n  }\n"], ["\n  display: flex;\n  flex-flow: column;\n  gap: 10px;\n  width: 100%;\n  /* Allow the wrap to shrink inside flex/grid parents so its rows' ellipsis can\n     engage instead of overflowing the container horizontally. */\n  min-width: 0;\n  max-width: 100%;\n\n  /* Scroll ownership \u2014 see \\`compactScroll\\`.\n\n     'host' (the default): the page or panel around us already scrolls, so we\n     must not cap our height and scroll our own body, or the reader gets two\n     scrollbars in two styles and cannot tell which moves what.\n\n     \\`overflow-x: clip\\`, NOT \\`hidden\\`: CSS coerces an \\`overflow-y: visible\\`\n     to \\`auto\\` whenever the other axis is neither visible nor clip, which would\n     leave this box a scroll container \u2014 the element stops scrolling only\n     because \\`max-height: none\\` means nothing overflows, while \\`position:\n     sticky\\` inside it still resolves against US instead of the host, so the\n     toolbar silently stops pinning. \\`clip\\` keeps the horizontal guard without\n     that coercion. */\n  ", "\n\n  /* Option logos (e.g. language images) render as <img> inside ReqoreIcon's\n     square box; constrain them so portrait PNGs don't overflow the row. */\n  .reqore-icon img {\n    width: 100%;\n    height: 100%;\n    object-fit: contain;\n  }\n"])), function (_a) {
     var $ownScroll = _a.$ownScroll;
     return $ownScroll ? (0, styled_components_1.css)(templateObject_1 || (templateObject_1 = __makeTemplateObject(["\n        /* 'own': we are the scroller. The sticky toolbar pins to whatever\n             scrolls, so a host whose scrollport carries top padding would\n             resolve sticky `top: 0` against its padding box and leave an\n             unblurred strip above the toolbar. Scrolling in this unpadded box\n             pins it flush. Cap at the host's available height, but do not grow\n             to fill it \u2014 short forms still hug their content.\n\n             `min-height: 0` is what lets a flex item shrink below its content\n             so there is something to scroll; it belongs to this branch only. */\n        min-height: 0;\n        max-height: 100%;\n        overflow-y: auto;\n        overflow-x: hidden;\n      "], ["\n        /* 'own': we are the scroller. The sticky toolbar pins to whatever\n             scrolls, so a host whose scrollport carries top padding would\n             resolve sticky \\`top: 0\\` against its padding box and leave an\n             unblurred strip above the toolbar. Scrolling in this unpadded box\n             pins it flush. Cap at the host's available height, but do not grow\n             to fill it \u2014 short forms still hug their content.\n\n             \\`min-height: 0\\` is what lets a flex item shrink below its content\n             so there is something to scroll; it belongs to this branch only. */\n        min-height: 0;\n        max-height: 100%;\n        overflow-y: auto;\n        overflow-x: hidden;\n      "]))) : (0, styled_components_1.css)(templateObject_2 || (templateObject_2 = __makeTemplateObject(["\n        /* `min-height: auto` is load-bearing, not a default: inside a column\n             flex parent the shrink allowance above collapses this box to zero\n             height while its rows paint outside it, so the form looks right but\n             contributes nothing to layout \u2014 the host cannot size or scroll to\n             it and anything below it stacks against nothing. */\n        min-height: auto;\n        max-height: none;\n        overflow-y: visible;\n        overflow-x: clip;\n      "], ["\n        /* \\`min-height: auto\\` is load-bearing, not a default: inside a column\n             flex parent the shrink allowance above collapses this box to zero\n             height while its rows paint outside it, so the form looks right but\n             contributes nothing to layout \u2014 the host cannot size or scroll to\n             it and anything below it stacks against nothing. */\n        min-height: auto;\n        max-height: none;\n        overflow-y: visible;\n        overflow-x: clip;\n      "])));
@@ -431,6 +435,34 @@ var normalizeEmptyFieldValues = function (fields) {
         return acc;
     }, {});
 };
+/**
+ * The value as a host can hand it back: each field as its value, and the fields that hold nothing left out.
+ *
+ * A report of the form's is recognised by what it says, not by how the host writes it back. A host that
+ * stores only the fields holding a value (the Qorus IDE's editors) hands a report back without its empty
+ * fields; one that stores a field under its own type (the IDE stores what an `int` field reported as a
+ * `string`) hands it back with that type. Compared field for field, type and all, the report never came
+ * back as itself:
+ * - the form took it for the host's own change and went back to it, losing what had been typed since, and
+ *   the two chased each other's reports on every echo;
+ * - an edit back to a value reported before (A, then B, then A again), made as the echo of B arrived, was
+ *   held back as made before the host's change, and the field went back to B (qorus#646: a template
+ *   field's text, deleted back to its reference, kept the text in the IDE).
+ *
+ * For recognising a value only. Whether a rebuild adds anything is still read with the empty fields in
+ * (`isMirrorOfValue`): a new schema's empty required field is a row the form has to add.
+ */
+var reportedValues = function (fields) {
+    return (0, reduce_1.default)(fields || {}, function (acc, field, name) {
+        var fieldValue = comparableField(field);
+        if (fieldValue !== undefined) {
+            acc[name] = fieldValue;
+        }
+        return acc;
+    }, {});
+};
+/** The same value, as a report coming back from a host is recognised. */
+var sameReportedValue = function (a, b) { return (0, lodash_1.isEqual)(reportedValues(a), reportedValues(b)); };
 /**
  * Does this rebuild say anything the parent does not already hold?
  *
@@ -460,6 +492,118 @@ var agreementFromRebuild = function (fixedValue, value) {
     return (0, exports.isMirrorOfValue)(fixedValue, value) ? fixedValue : undefined;
 };
 exports.agreementFromRebuild = agreementFromRebuild;
+/**
+ * A field as the form compares one host value with another: an empty field ('' or none, whatever its type) is
+ * the same as no field, and a field is its value, however it is written (`{ type, value }` or the bare value).
+ */
+var comparableField = function (field) {
+    var fieldValue = field !== null && typeof field === 'object' && !Array.isArray(field) && 'value' in field ?
+        field.value
+        : field !== null && typeof field === 'object' && !Array.isArray(field) && 'type' in field ?
+            undefined
+            : field;
+    return fieldValue === '' ? undefined : fieldValue;
+};
+var sameField = function (a, b) {
+    return (0, lodash_1.isEqual)(comparableField(a), comparableField(b));
+};
+/** A field written as `{ type, value }`, not a bare value. */
+var isTypedField = function (field) {
+    return field !== null &&
+        typeof field === 'object' &&
+        !Array.isArray(field) &&
+        typeof field.type === 'string';
+};
+/**
+ * The form's copy of a field, with everything the host changed beside its value since `base`: its type, whether
+ * it is an expression, its operator, or anything else it says. `own` itself where the host changed nothing.
+ *
+ * A report of the form's is recognised by its values, and a field's value is merged by its value (see
+ * `reportedValues`, `mergeOwnEdits`), so a change the host made to a field's type alone said nothing: the form
+ * kept its own type. The Qorus IDE makes an added field's whole number true or false, holding the same field
+ * `pos`; the form kept the `int` and drew `pos` as text on the Value tab, where a true or false field shows it on
+ * its Expression tab (qorus#646).
+ *
+ * Every key but `value` is compared, not a list of the ones known today: whatever a host writes into a field
+ * beside its value, a change of it is the host's. A key the host writes as it always has is not a change, so a
+ * host that stores a field under its own type does not change the form's (that is why the value alone is what
+ * recognises a report).
+ */
+var withHostsAttributes = function (own, host, base) {
+    if (!isTypedField(own) || !isTypedField(host)) {
+        return own;
+    }
+    var hostField = host;
+    var baseField = isTypedField(base) ? base : {};
+    var ownField = own;
+    var taken;
+    new Set(__spreadArray(__spreadArray([], Object.keys(hostField), true), Object.keys(baseField), true)).forEach(function (key) {
+        var hosts = hostField[key];
+        if (key === 'value' || (0, lodash_1.isEqual)(hosts, baseField[key]) || (0, lodash_1.isEqual)(ownField[key], hosts)) {
+            return;
+        }
+        taken = taken !== null && taken !== void 0 ? taken : __assign({}, ownField);
+        if (hosts === undefined) {
+            delete taken[key];
+        }
+        else {
+            taken[key] = hosts;
+        }
+    });
+    return taken !== null && taken !== void 0 ? taken : own;
+};
+/**
+ * The form's copy with what the host changed beside each field's value since `base` taken (see
+ * `withHostsAttributes`). Returns `ours` itself when there is nothing the form's copy does not have already.
+ */
+var takeHostsAttributes = function (theirs, ours, base) {
+    var _a;
+    var typed;
+    (0, lodash_1.forEach)(theirs || {}, function (host, name) {
+        var own = ours === null || ours === void 0 ? void 0 : ours[name];
+        var taken = withHostsAttributes(own, host, base === null || base === void 0 ? void 0 : base[name]);
+        if (taken !== own) {
+            typed = typed !== null && typed !== void 0 ? typed : __assign({}, (ours || {}));
+            typed[name] = taken;
+        }
+    });
+    return (_a = typed) !== null && _a !== void 0 ? _a : ours;
+};
+exports.takeHostsAttributes = takeHostsAttributes;
+/**
+ * The host's change, with the form's own edits kept: a three-way merge of `theirs` (the `value` the host
+ * hands down now) and `ours` (the form's copy) against `base` (the `value` the form last saw).
+ *
+ * A field the form changed and the host did not keeps the form's value; every other field takes the host's,
+ * a field both changed included. The host and the form can change the value in the same commit - a host
+ * renaming something as the user's edit reaches the form - and taking either side whole lost the other's
+ * change; sending the form's copy over the host's change made the two trade places forever (qorus#646).
+ *
+ * Returns `theirs` itself when the form has nothing of its own to keep.
+ */
+var mergeOwnEdits = function (theirs, ours, base) {
+    var _a;
+    var merged;
+    var names = new Set(__spreadArray(__spreadArray([], Object.keys(ours || {}), true), Object.keys(base || {}), true));
+    names.forEach(function (name) {
+        var own = ours === null || ours === void 0 ? void 0 : ours[name];
+        var before = base === null || base === void 0 ? void 0 : base[name];
+        var host = theirs === null || theirs === void 0 ? void 0 : theirs[name];
+        if (sameField(own, before) || !sameField(host, before) || sameField(host, own)) {
+            return;
+        }
+        merged = merged !== null && merged !== void 0 ? merged : __assign({}, (theirs || {}));
+        if (own === undefined) {
+            delete merged[name];
+        }
+        else {
+            // the form's value, with what the host changed beside it (its type, say)
+            merged[name] = withHostsAttributes(own, host, before);
+        }
+    });
+    return (_a = merged) !== null && _a !== void 0 ? _a : theirs;
+};
+exports.mergeOwnEdits = mergeOwnEdits;
 /**
  * Should the form report `localValue` to its parent as an answer?
  *
@@ -516,6 +660,8 @@ var getTypeAndCanBeNull = function (type, allowed_values, operatorData, operator
 exports.getTypeAndCanBeNull = getTypeAndCanBeNull;
 // Option types rendered full-width (IDE Options parity, commit 8e6b7781).
 var STRECHABLE_TYPES = new Set(['tool-catalog']);
+/** How faded reqore draws a panel's title icon. */
+var PANEL_TITLE_ICON_ALPHA = 0.7;
 var FormEngineImpl = function (_a) {
     var _b, _c, _d, _f, _g;
     var name = _a.name, uniqueName = _a.uniqueName, value = _a.value, onChange = _a.onChange, onSingleOptionsChange = _a.onSingleOptionsChange, onDependableOptionChange = _a.onDependableOptionChange, placeholder = _a.placeholder, noValueString = _a.noValueString, // eslint-disable-line @typescript-eslint/no-unused-vars
@@ -534,12 +680,14 @@ var FormEngineImpl = function (_a) {
     // been a no-op. Removing it from the API is a separate, breaking change —
     // every consumer passing it today already gets the flush layout by default.
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    compactFlush = _k === void 0 ? false : _k, _l = _a.compactNested, compactNested = _l === void 0 ? false : _l, _m = _a.compactScroll, compactScroll = _m === void 0 ? 'host' : _m, compactPanelProps = _a.compactPanelProps, compactCollapsedGroupsProp = _a.compactCollapsedGroups, compactBoxLabels = _a.compactBoxLabels, _o = _a.compactStickyBoxHeaders, compactStickyBoxHeaders = _o === void 0 ? true : _o, _p = _a.compactStickyOffset, compactStickyOffset = _p === void 0 ? 0 : _p, _q = _a.compactToolbar, compactToolbar = _q === void 0 ? true : _q, _r = _a.commitMode, commitMode = _r === void 0 ? 'immediate' : _r, _s = _a.expandMode, expandMode = _s === void 0 ? 'single' : _s, onCommit = _a.onCommit, operatorsProp = _a.operators, groups = _a.groups, optionsLoader = _a.optionsLoader, onValidityChange = _a.onValidityChange, optionActions = _a.optionActions, _t = _a.optionActionsCollapse, optionActionsCollapse = _t === void 0 ? 'auto' : _t, componentOverrides = _a.componentOverrides, codePreviewRenderer = _a.codePreviewRenderer, 
+    compactFlush = _k === void 0 ? false : _k, _l = _a.compactNested, compactNested = _l === void 0 ? false : _l, _m = _a.compactScroll, compactScroll = _m === void 0 ? 'host' : _m, compactPanelProps = _a.compactPanelProps, compactCollapsedGroupsProp = _a.compactCollapsedGroups, compactBoxLabels = _a.compactBoxLabels, _o = _a.compactStickyBoxHeaders, compactStickyBoxHeaders = _o === void 0 ? true : _o, _p = _a.compactStickyOffset, compactStickyOffset = _p === void 0 ? 0 : _p, _q = _a.compactToolbar, compactToolbar = _q === void 0 ? true : _q, _r = _a.commitMode, commitMode = _r === void 0 ? 'immediate' : _r, _s = _a.expandMode, expandMode = _s === void 0 ? 'single' : _s, onCommit = _a.onCommit, operatorsProp = _a.operators, groups = _a.groups, optionsLoader = _a.optionsLoader, onValidityChange = _a.onValidityChange, optionActions = _a.optionActions, _t = _a.optionActionsCollapse, optionActionsCollapse = _t === void 0 ? 'auto' : _t, componentOverrides = _a.componentOverrides, codePreviewRenderer = _a.codePreviewRenderer, readSummaries = _a.readSummaries, 
     // consumed by the wrapper below, which publishes it to every description this
     // form draws; destructured here only so it cannot reach `rest` and be spread
     // onto a DOM node
     _markdownRenderer = _a.markdownRenderer, // eslint-disable-line @typescript-eslint/no-unused-vars
-    rendererOnlyUiTypes = _a.rendererOnlyUiTypes, templateAwareUiTypes = _a.templateAwareUiTypes, anyLikeUiTypes = _a.anyLikeUiTypes, inheritedFromParent = _a.inheritedFromParent, autoFocusFirstRequired = _a.autoFocusFirstRequired, expandFirstRequired = _a.expandFirstRequired, initialExpandedOptions = _a.initialExpandedOptions, maxFieldsShown = _a.maxFieldsShown, rest = __rest(_a, ["name", "uniqueName", "value", "onChange", "onSingleOptionsChange", "onDependableOptionChange", "placeholder", "noValueString", "isValid", "url", "customUrl", "operatorsUrl", "onOptionsLoaded", "recordRequiresSearchOptions", "readOnly", "onReadOnlyActivate", "allowTemplates", "interfaceContext", "templateFieldProps", "forceDropdown", "showTypeToggle", "compact", "compactFlush", "compactNested", "compactScroll", "compactPanelProps", "compactCollapsedGroups", "compactBoxLabels", "compactStickyBoxHeaders", "compactStickyOffset", "compactToolbar", "commitMode", "expandMode", "onCommit", "operators", "groups", "optionsLoader", "onValidityChange", "optionActions", "optionActionsCollapse", "componentOverrides", "codePreviewRenderer", "markdownRenderer", "rendererOnlyUiTypes", "templateAwareUiTypes", "anyLikeUiTypes", "inheritedFromParent", "autoFocusFirstRequired", "expandFirstRequired", "initialExpandedOptions", "maxFieldsShown"]);
+    rendererOnlyUiTypes = _a.rendererOnlyUiTypes, templateAwareUiTypes = _a.templateAwareUiTypes, anyLikeUiTypes = _a.anyLikeUiTypes, inheritedFromParent = _a.inheritedFromParent, autoFocusFirstRequired = _a.autoFocusFirstRequired, expandFirstRequired = _a.expandFirstRequired, initialExpandedOptions = _a.initialExpandedOptions, valueKey = _a.valueKey, maxFieldsShown = _a.maxFieldsShown, 
+    // The form's own props, read here and never handed on to the collection drawn below (`{...rest}`).
+    optionsSchema = _a.options, stringTemplates = _a.stringTemplates, skeletonReason = _a.skeletonReason, rest = __rest(_a, ["name", "uniqueName", "value", "onChange", "onSingleOptionsChange", "onDependableOptionChange", "placeholder", "noValueString", "isValid", "url", "customUrl", "operatorsUrl", "onOptionsLoaded", "recordRequiresSearchOptions", "readOnly", "onReadOnlyActivate", "allowTemplates", "interfaceContext", "templateFieldProps", "forceDropdown", "showTypeToggle", "compact", "compactFlush", "compactNested", "compactScroll", "compactPanelProps", "compactCollapsedGroups", "compactBoxLabels", "compactStickyBoxHeaders", "compactStickyOffset", "compactToolbar", "commitMode", "expandMode", "onCommit", "operators", "groups", "optionsLoader", "onValidityChange", "optionActions", "optionActionsCollapse", "componentOverrides", "codePreviewRenderer", "readSummaries", "markdownRenderer", "rendererOnlyUiTypes", "templateAwareUiTypes", "anyLikeUiTypes", "inheritedFromParent", "autoFocusFirstRequired", "expandFirstRequired", "initialExpandedOptions", "valueKey", "maxFieldsShown", "options", "stringTemplates", "skeletonReason"]);
     // Built-ins + whatever the consumer declared for its own injected editors.
     var isRendererOnly = (0, react_2.useMemo)(function () { return (0, rendererTypes_1.createRendererOnlyUiTypeCheck)(rendererOnlyUiTypes); }, [JSON.stringify(rendererOnlyUiTypes)]);
     // Pointer CAPABILITY and viewport WIDTH are different questions and both
@@ -564,10 +712,22 @@ var FormEngineImpl = function (_a) {
        enters the component, so the header, the chips, the messages, the meter and
        the read-first summary cannot disagree about it: every one of them reads
        `options`, and none of them has to know the rule. */
-    var _u = (0, react_2.useState)((rest === null || rest === void 0 ? void 0 : rest.options) || undefined), servedOptions = _u[0], setOptions = _u[1];
+    var _u = (0, react_2.useState)(optionsSchema || undefined), servedOptions = _u[0], setOptions = _u[1];
     var options = (0, react_2.useMemo)(function () { return (0, options_1.resolveDegenerateRequiredGroups)(servedOptions); }, [servedOptions]);
+    /* Whether the schema the form holds is the one in force: its host is not waiting behind the skeleton, and a
+       schema the host hands down has been taken in (`servedOptions` follows the `options` prop a render later).
+       Until then the value is neither pruned against the schema nor emitted. A host loading the schema hands an
+       empty or an earlier one meanwhile; read against that, every stored field was "not on this instance" and
+       was removed, so a Qog state opened before its options had loaded showed them empty and, once emitted,
+       lost them (qorus#646). */
+    var hostSchemaPending = !optionsLoader &&
+        !url &&
+        !customUrl &&
+        optionsSchema !== servedOptions &&
+        JSON.stringify(optionsSchema || undefined) !== JSON.stringify(servedOptions);
+    var schemaInForce = !rest.skeleton && !hostSchemaPending;
     // optionsLoader lifecycle: loading feeds the skeleton gate, error the banner.
-    var _v = (0, react_2.useState)(!!optionsLoader && !(rest === null || rest === void 0 ? void 0 : rest.options)), optionsLoading = _v[0], setOptionsLoading = _v[1];
+    var _v = (0, react_2.useState)(!!optionsLoader && !optionsSchema), optionsLoading = _v[0], setOptionsLoading = _v[1];
     var _w = (0, react_2.useState)(), optionsError = _w[0], setOptionsError = _w[1];
     // Operators: prop-provided (compact) or fetched via operatorsUrl (dpql,
     // ported from IDE Options) — the fetch overrides the seeded prop value.
@@ -636,6 +796,8 @@ var FormEngineImpl = function (_a) {
     // stays put when its status flips (e.g. becomes valid) instead of jumping to
     // another box mid-edit and stealing focus. Keyed by option name.
     var settledBucket = (0, react_2.useRef)({});
+    // the one field that says where it moves when it is closed: see `heldOptions`
+    var movesToNoteFor = (0, react_2.useRef)(undefined);
     // Measured form width (not viewport — the form lives in drawers/panels of
     // arbitrary width) drives the stacked narrow layout.
     var _7 = (0, react_use_1.useMeasure)(), compactWrapRef = _7[0], compactWrapWidth = _7[1].width;
@@ -857,16 +1019,50 @@ var FormEngineImpl = function (_a) {
      * reset the form to it: the field under the cursor went back a step and the keys typed since were lost
      * ("I have value" came out as "I he value" in a story under load).
      */
-    var inFlight = (0, emittedValues_1.useEmittedValues)(function (a, b) {
-        return (0, lodash_1.isEqual)(normalizeEmptyFieldValues(a), normalizeEmptyFieldValues(b));
-    });
+    var inFlight = (0, emittedValues_1.useEmittedValues)(sameReportedValue);
+    /**
+     * The `value` (and `valueKey`) as of the last commit: what a new `value` is a change from. The sync-down
+     * merges the host's change against it, and the emit effect tells by it that the host changed the value in
+     * the very commit it runs in. Updated by the last effect of each commit (below the sync-down).
+     */
+    var seenValue = (0, react_2.useRef)(value);
+    var seenValueKey = (0, react_2.useRef)(valueKey);
+    /** Whether `value` is the host's own change, made since the last commit: neither seen before nor a report of
+     *  this form's coming back. */
+    var isHostsOwnChange = function () {
+        return valueKey !== seenValueKey.current ||
+            (!sameReportedValue(value, seenValue.current) &&
+                !inFlight.includes(value) &&
+                !sameReportedValue(value, lastEmittedValue.current));
+    };
     if (originalValue.current === undefined && (0, size_1.default)(value)) {
         originalValue.current = localValue.fields;
     }
     var unavailableOptionsCount = (0, react_2.useRef)(0);
     var _17 = (0, useQorusTypes_1.useQorusTypes)(), compactValue = _17.compactValue, typesLoading = _17.loading;
-    var templates = (0, useTemplates_1.useTemplates)(allowTemplates, rest.stringTemplates, interfaceContext);
+    var templates = (0, useTemplates_1.useTemplates)(allowTemplates, stringTemplates, interfaceContext);
     (0, react_2.useEffect)(function () {
+        /* Nothing is emitted until the schema is in force (`schemaInForce`): read against the empty or earlier
+           schema a host hands down while it loads its own, the value is no answer, and emitted it wiped a Qog
+           state's stored options the moment the state was opened (qorus#646).
+    
+           When it comes into force this check runs (it is a dependency). A host also shows the skeleton for other
+           waits: qorus-ide shows it while the templates load, with the schema already there. The form completes the
+           value meanwhile (a required field's default, e.g. the server's `created_by_user`), and nothing read it
+           again when the skeleton cleared: the default was shown and never emitted, so never saved. A value that
+           adds nothing still emits nothing. */
+        if (!schemaInForce) {
+            return;
+        }
+        /* The host changed the value in this same commit (effects run in order, and this one runs before the
+           sync-down that takes the change in). The form's copy was made before that change: sent, it overwrote
+           the host's change, the sync-down then took the host's value in, and the next commit sent that back -
+           the form and the host traded places on every commit, forever (qorus#646: the Qorus IDE's OPC UA node
+           editor, its namespace flipping between the old and the renamed one). The sync-down below merges the
+           change with the form's own edits, and the next commit reports the result. */
+        if (isHostsOwnChange()) {
+            return;
+        }
         if (!(0, exports.shouldEmitLocalValue)({
             localValue: localValue.fields,
             value: value,
@@ -881,15 +1077,15 @@ var FormEngineImpl = function (_a) {
         // Batched mode still emits every staged change (consumers may want to
         // live-validate), but flags it as a draft — persistence waits for Save.
         onChange === null || onChange === void 0 ? void 0 : onChange(name, toEmit, commitMode === 'batched' ? __assign(__assign({}, (meta || {})), { draft: true }) : meta);
-    }, [JSON.stringify(localValue)]);
+    }, [JSON.stringify(localValue), schemaInForce]);
     (0, react_use_1.useUpdateEffect)(function () {
         // When a loader owns the schema, ignore controlled `options` syncs so a
         // late/undefined `options` prop can't clobber the loaded schema.
         if (optionsLoader) {
             return;
         }
-        setOptions(rest.options);
-    }, [JSON.stringify(rest.options)]);
+        setOptions(optionsSchema);
+    }, [JSON.stringify(optionsSchema)]);
     // Fetch the schema on mount and on loader identity change.
     (0, react_2.useEffect)(function () {
         if (!optionsLoader) {
@@ -1076,14 +1272,32 @@ var FormEngineImpl = function (_a) {
         // change and re-fixes forever (e.g. byte-size / expression / ruled string fields).
         // Note: compare fixedValue against value, not localValue.fields — localValue may have been
         // updated by nested FormEngine emissions, so comparing against it would never skip.
-        var normalizedValue = normalizeEmptyFieldValues(value);
         /* What this rebuild lets us agree with the parent on — `undefined` when it
            contributed something the parent has yet to learn. */
         var agreed = (0, exports.agreementFromRebuild)(fixedValue, value);
+        // a different record: nothing of the previous one is carried into it (see `valueKey`)
+        var sameRecord = valueKey === seenValueKey.current;
         // the echo of an emit still in flight - the last or an older one - is not the parent's change
         var echo = inFlight.isEcho(value);
-        if ((echo || (0, lodash_1.isEqual)(normalizedValue, normalizeEmptyFieldValues(lastEmittedValue.current))) &&
-            agreed !== undefined) {
+        if (sameRecord && (echo || sameReportedValue(value, lastEmittedValue.current))) {
+            /* The form's own report coming back. Whatever the rebuild adds - a schema that changed in the same
+               commit, a field the host does not store - is added to the form's copy, never by going back to the
+               report: the report may be older than edits made since (an echo of "a" arriving after "ab" was
+               reported lost the "b"). Nothing changes when the form's copy has it all already. */
+            var rebuild_1 = function (fields) {
+                return (0, exports.fixOptions)(fields, options || {}, undefined, isRendererOnly);
+            };
+            if (!(0, lodash_1.isEqual)(rebuild_1(localValue.fields), localValue.fields)) {
+                // the parent has to learn what the rebuild added
+                mirroredValue.current = undefined;
+            }
+            /* What the host changed beside a field's value is taken (its type, say): the report is recognised by its
+               values (see `takeHostsAttributes`). */
+            var base_1 = seenValue.current;
+            setLocalValue(function (current) {
+                var rebuilt = rebuild_1((0, exports.takeHostsAttributes)(value, current.fields, base_1));
+                return (0, lodash_1.isEqual)(rebuilt, current.fields) ? current : { fields: rebuilt, meta: current.meta };
+            });
             return;
         }
         if (!originalValue.current && (0, size_1.default)(fixedValue)) {
@@ -1096,8 +1310,25 @@ var FormEngineImpl = function (_a) {
         if (agreed !== undefined) {
             lastEmittedValue.current = agreed;
         }
-        setLocalValue === null || setLocalValue === void 0 ? void 0 : setLocalValue({ fields: fixedValue, meta: undefined });
-    }, [JSON.stringify(options), JSON.stringify(value), isRendererOnly]);
+        if (!sameRecord) {
+            setLocalValue({ fields: fixedValue, meta: undefined });
+            return;
+        }
+        // The host's change, with the form's own edits it did not touch kept (see `mergeOwnEdits`).
+        var base = seenValue.current;
+        setLocalValue(function (current) {
+            var merged = (0, exports.mergeOwnEdits)(value, current.fields, base);
+            return {
+                fields: merged === value ? fixedValue : ((0, exports.fixOptions)(merged, options || {}, undefined, isRendererOnly)),
+                meta: undefined,
+            };
+        });
+    }, [JSON.stringify(options), JSON.stringify(value), isRendererOnly, valueKey]);
+    // Last of the value effects: what the next commit's `value` is a change from.
+    (0, react_2.useEffect)(function () {
+        seenValue.current = value;
+        seenValueKey.current = valueKey;
+    });
     var handleValueChange = (0, react_2.useCallback)(function (optionName, val, _type, isFunction) {
         setLocalValue(function (_a) {
             var _b, _c;
@@ -1294,8 +1525,11 @@ var FormEngineImpl = function (_a) {
             var _a, _b;
             var option = fixedValue[optionName];
             if (!(options === null || options === void 0 ? void 0 : options[optionName])) {
-                unavailableOptionsCount.current += 1;
-                removeSelectedOption(optionName);
+                // not on this instance - unless the schema is not yet the one in force (see `schemaInForce`)
+                if (schemaInForce) {
+                    unavailableOptionsCount.current += 1;
+                    removeSelectedOption(optionName);
+                }
                 return newValue;
             }
             var rendererType = (0, exports.getType)((options[optionName].ui_type || options[optionName].type), operators, option === null || option === void 0 ? void 0 : option.op);
@@ -1315,6 +1549,7 @@ var FormEngineImpl = function (_a) {
         unavailableOptionsCount.current,
         JSON.stringify(operators),
         showInvalidOptionsOnly,
+        schemaInForce,
     ]);
     // Per required-group: its member options, and which member (if any) already
     // satisfies it — drives the "One of" chips and the "covered by" notes.
@@ -1445,12 +1680,15 @@ var FormEngineImpl = function (_a) {
     }, [JSON.stringify(options), JSON.stringify(fixedValue), JSON.stringify(availableOptions)]);
     var isOptionValid = (0, react_2.useCallback)(function (optionName, type, optionValue) {
         var _a, _b, _c, _d;
-        var isEmpty = optionValue === undefined || optionValue === '';
-        // An empty field locked by an unmet `depends_on` does not apply, so it is
-        // not missing — the same rule the read-first status follows.
-        if (isEmpty &&
-            ((!((_a = options === null || options === void 0 ? void 0 : options[optionName]) === null || _a === void 0 ? void 0 : _a.required) && !((_b = options === null || options === void 0 ? void 0 : options[optionName]) === null || _b === void 0 ? void 0 : _b.required_groups)) ||
-                dependencyLockedNames.includes(optionName))) {
+        // the same "not set" the row's status reads: an empty list is no value
+        var isEmpty = (0, readFirst_1.isOptionValueEmpty)(optionValue);
+        // A field whose `depends_on` does not hold does not apply: it is hidden, and nothing in it can make the
+        // form invalid - a value it holds is kept, and said in the form's note, valid or not (qorus#646).
+        if (dependencyLockedNames.includes(optionName)) {
+            return true;
+        }
+        // An empty field that is not required is not missing.
+        if (isEmpty && !((_a = options === null || options === void 0 ? void 0 : options[optionName]) === null || _a === void 0 ? void 0 : _a.required) && !((_b = options === null || options === void 0 ? void 0 : options[optionName]) === null || _b === void 0 ? void 0 : _b.required_groups)) {
             return true;
         }
         return (0, validations_1.validateField)((0, exports.getType)(type), optionValue, __assign(__assign({ has_to_have_value: true, optionSchema: options, options: availableOptions }, options === null || options === void 0 ? void 0 : options[optionName]), { 
@@ -1469,28 +1707,41 @@ var FormEngineImpl = function (_a) {
     ]);
     var getValidityData = (0, react_2.useCallback)(function () {
         var fields = (0, reduce_1.default)(availableOptions, function (result, option, optionName) {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             var type = (0, exports.getOptionFieldStorageType)(optionName, option.type, options, operators, option.op, isRendererOnly, optionHoldsExpression(option));
             var optionValue = option.value;
             var isRequired = (_a = options === null || options === void 0 ? void 0 : options[optionName]) === null || _a === void 0 ? void 0 : _a.required;
             var hasRequiredGroups = !!((_b = options === null || options === void 0 ? void 0 : options[optionName]) === null || _b === void 0 ? void 0 : _b.required_groups);
-            var isEmpty = optionValue === undefined || optionValue === '';
+            // the same "not set" the row's status reads: an empty list is no value
+            var isEmpty = (0, readFirst_1.isOptionValueEmpty)(optionValue);
             var validation;
-            /* A required field locked by an unmet `depends_on` does not apply
-               while it is locked: it is not in "Needs attention", and an empty one
-               does not make the form incomplete either. Otherwise a check whose
-               kind is Equals could never be saved, because Minimum — required for
-               Between alone — is empty; and a form whose only gaps are fields
-               nobody can fill in would say Incomplete with nothing to act on. A
-               locked field that still HOLDS a value is validated as before. */
-            if (isEmpty &&
-                ((!isRequired && !hasRequiredGroups) || dependencyLockedNames.includes(optionName))) {
-                validation = { isValid: true, reasons: [] };
+            /* A field whose host gives its own reason (`invalid_reason`) is invalid while it does, whatever the
+               field makes of its value: the host knows something the field cannot - that a field it names
+               is not in the record, that text around a field is not a whole number - and says it in the field,
+               in place of the field's own message (`getOptionFieldMessages`). */
+            var hostReason = (_c = options === null || options === void 0 ? void 0 : options[optionName]) === null || _c === void 0 ? void 0 : _c.invalid_reason;
+            if (hostReason) {
+                validation = { isValid: false, reason: hostReason, reasons: [hostReason] };
             }
             else {
-                validation = (0, validations_1.validateFieldWithResult)((0, exports.getType)(type), optionValue, __assign(__assign({ has_to_have_value: true, optionSchema: options, options: availableOptions }, options === null || options === void 0 ? void 0 : options[optionName]), { 
-                    // The expression flag lives on the field value, not the schema.
-                    isFunction: option.is_expression, hasOwnEditor: isRendererOnly((_c = options === null || options === void 0 ? void 0 : options[optionName]) === null || _c === void 0 ? void 0 : _c.ui_type) }));
+                /* A required field locked by an unmet `depends_on` does not apply
+                 while it is locked: it is not in "Needs attention", and an empty one
+                 does not make the form incomplete either. Otherwise a check whose
+                 kind is Equals could never be saved, because Minimum — required for
+                 Between alone — is empty; and a form whose only gaps are fields
+                 nobody can fill in would say Incomplete with nothing to act on. A
+                 locked field that still HOLDS a value is validated as before. */
+                if (dependencyLockedNames.includes(optionName) ||
+                    (isEmpty && !isRequired && !hasRequiredGroups)) {
+                    /* A field whose `depends_on` does not hold is hidden and does not apply: nothing in it makes the
+                       form invalid, empty or holding a value (kept, and said in the form's note - qorus#646). */
+                    validation = { isValid: true, reasons: [] };
+                }
+                else {
+                    validation = (0, validations_1.validateFieldWithResult)((0, exports.getType)(type), optionValue, __assign(__assign({ has_to_have_value: true, optionSchema: options, options: availableOptions }, options === null || options === void 0 ? void 0 : options[optionName]), { 
+                        // The expression flag lives on the field value, not the schema.
+                        isFunction: option.is_expression, hasOwnEditor: isRendererOnly((_d = options === null || options === void 0 ? void 0 : options[optionName]) === null || _d === void 0 ? void 0 : _d.ui_type) }));
+                }
             }
             result.push({
                 fieldName: optionName,
@@ -1519,9 +1770,16 @@ var FormEngineImpl = function (_a) {
     (0, react_2.useEffect)(function () {
         onValidityChange === null || onValidityChange === void 0 ? void 0 : onValidityChange(optionsAreValid, validityData);
     }, [JSON.stringify(validityData)]);
+    /* A field whose `depends_on` does not hold is not shown (qorus#646, David): it is not of use until it applies,
+       so it is left out of the form - not shown waiting, locked - and appears once its dependency holds (and
+       flashes - see `dependencyLockedNames`). Its value is kept; one it holds meanwhile is said in the form's
+       note (`hiddenFieldsWithValues`). */
     var shownOptions = (0, react_2.useMemo)(function () {
         return (0, reduce_1.default)(availableOptions, function (newValue, option, optionName) {
             var _a;
+            if (dependencyLockedNames.includes(optionName)) {
+                return newValue;
+            }
             if (showInvalidOptionsOnly &&
                 isOptionValid(optionName, (0, exports.getOptionFieldStorageType)(optionName, option.type, options, operators, option.op, isRendererOnly, optionHoldsExpression(option)), option.value)) {
                 return newValue;
@@ -1529,6 +1787,7 @@ var FormEngineImpl = function (_a) {
             return __assign(__assign({}, newValue), (_a = {}, _a[optionName] = option, _a));
         }, {});
     }, [
+        dependencyLockedNames,
         showInvalidOptionsOnly,
         isRendererOnly,
         JSON.stringify(availableOptions),
@@ -1542,7 +1801,7 @@ var FormEngineImpl = function (_a) {
     var schemaMsgIntent = (0, react_2.useCallback)(function (name) {
         var _a;
         // Filtered, not raw: a message hidden by its own `when`/`unless` must not
-        // colour the row or push the field into "Needs attention" — the whole point
+        // color the row or push the field into "Needs attention" — the whole point
         // of a conditional warning is that it is absent while it does not apply.
         var msgs = (0, OptionFieldMessages_1.getShownSchemaMessages)((_a = options === null || options === void 0 ? void 0 : options[name]) === null || _a === void 0 ? void 0 : _a.messages, availableOptions, options);
         if (msgs.some(function (m) { return m.intent === 'danger'; }))
@@ -1612,9 +1871,10 @@ var FormEngineImpl = function (_a) {
     }, [JSON.stringify(options), requiredGroupsInfo, getOptionStatus, dependencyLockedNames]);
     // How many fields are in the "Needs attention" box — drives the header link.
     var readFirstAttentionCount = (0, react_2.useMemo)(function () {
-        return Object.keys(availableOptions || {}).filter(function (name) { return getOptionBucket(name) === 'attention'; })
-            .length;
-    }, [JSON.stringify(availableOptions), getOptionBucket]);
+        return Object.keys(availableOptions || {}).filter(
+        // a hidden field (its `depends_on` does not hold) is not in the form, nor in its counts
+        function (name) { return !dependencyLockedNames.includes(name) && getOptionBucket(name) === 'attention'; }).length;
+    }, [JSON.stringify(availableOptions), getOptionBucket, dependencyLockedNames]);
     var getIntent = (0, react_2.useCallback)(
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     function (optName, type, optValue, _op) {
@@ -1663,7 +1923,12 @@ var FormEngineImpl = function (_a) {
     var handleOptionLabelClick = (0, react_2.useCallback)(function (optionName) {
         setShowHelpForOption(optionName);
     }, []);
+    /** Whether the first-required scan below has run, or is spent (see it). Only a remount arms it again. */
+    var hasAutoFocusedRef = (0, react_2.useRef)(false);
     var toggleExpandedOption = (0, react_2.useCallback)(function (optionName) {
+        // A row the user opens or closes is where they have chosen to work: the first-required scan, if it is
+        // still waiting for the focus to be free, does not run after it (qorus#646).
+        hasAutoFocusedRef.current = true;
         setExpandedOptions(function (prev) {
             return prev.includes(optionName) ? prev.filter(function (name) { return name !== optionName; })
                 // single (default): opening a row collapses any other open one.
@@ -1702,6 +1967,39 @@ var FormEngineImpl = function (_a) {
         setExpandedOptions(function (prev) { return __spreadArray(__spreadArray([], prev, true), toExpand.filter(function (name) { return !prev.includes(name); }), true); });
     }, [initialExpandedOptions, compact, availableOptions]);
     // --- First-attention-field autofocus (opt-in) -----------------------------
+    /** The first row that needs an answer and can take one, if any: what the first-required scan opens. */
+    var firstAttentionRow = function () {
+        return (0, readFirst_1.getFirstAttentionOptionName)(Object.keys(availableOptions), function (fieldName) {
+            var schema = options === null || options === void 0 ? void 0 : options[fieldName];
+            if (!schema) {
+                return undefined;
+            }
+            return {
+                focusable: !readOnly &&
+                    !schema.disabled &&
+                    !schema.readonly &&
+                    !dependencyLockedNames.includes(fieldName),
+                // Single source of truth: the same bucket the read-first status boxes
+                // show, so a filled-but-invalid required row is a target too.
+                needsAttention: getOptionBucket(fieldName) === 'attention',
+            };
+        });
+    };
+    var openFirstAttentionRow = function (target) {
+        if (target) {
+            setExpandedOptions(function (prev) {
+                return prev.includes(target) ? prev
+                    : expandMode === 'multi' ? __spreadArray(__spreadArray([], prev, true), [target], false) 
+                    // `expandMode: 'single'` is a rule about what a CLICK does: opening a
+                    // row closes the one the reader last opened. It is not a licence to
+                    // close a row the HOST named through `initialExpandedOptions`. That
+                    // is an address — a statement about what the page is FOR, made before
+                    // the reader did anything — and this scan is a convenience layered on
+                    // top of it. Keep the named rows; replace only what a click could.
+                    : __spreadArray(__spreadArray([], prev.filter(function (name) { return initialExpandedOptions === null || initialExpandedOptions === void 0 ? void 0 : initialExpandedOptions.includes(name); }), true), [target], false);
+            });
+        }
+    };
     // With `autoFocusFirstRequired`, drop the user straight into the first field
     // they must fix. We reuse the engine's own ordering (`availableOptions`), the
     // very same `getOptionBucket` the status boxes use to decide "needs attention"
@@ -1717,7 +2015,12 @@ var FormEngineImpl = function (_a) {
     // field update or an in-place schema reload will NOT re-grab focus; only a
     // genuine remount (a fresh instance) auto-focuses again, which is the intended
     // on-mount behaviour.
-    var hasAutoFocusedRef = (0, react_2.useRef)(false);
+    //
+    // It waits only for the user's first move. A form opened from a button mounts while that button holds the
+    // focus, and the scan waits for it to be free - but the user does not wait: they open a row (which spends
+    // the scan, `toggleExpandedOption`) or come into the form from the keyboard (which runs it, below). Waiting
+    // past that, the scan ran the first time the focus rested on nothing, which is the Done that closes the
+    // user's row, and opened the next row that needed an answer by itself in the middle of their work.
     (0, react_2.useEffect)(function () {
         // Two decisions, one scan. Both open the row that needs attention;
         // `autoFocusFirstRequired` additionally promises the caret lands in it, and
@@ -1752,38 +2055,11 @@ var FormEngineImpl = function (_a) {
         if (wantsFocus && active && active !== document.body) {
             return;
         }
-        var target = (0, readFirst_1.getFirstAttentionOptionName)(orderedNames, function (fieldName) {
-            var schema = options[fieldName];
-            if (!schema) {
-                return undefined;
-            }
-            return {
-                focusable: !readOnly &&
-                    !schema.disabled &&
-                    !schema.readonly &&
-                    !dependencyLockedNames.includes(fieldName),
-                // Single source of truth: the same bucket the read-first status boxes
-                // show, so a filled-but-invalid required row is a target too.
-                needsAttention: getOptionBucket(fieldName) === 'attention',
-            };
-        });
         // Mark done even when nothing needs attention, so later value edits or an
         // in-place schema reload never re-scan or re-focus. Only a remount arms it
         // again.
         hasAutoFocusedRef.current = true;
-        if (target) {
-            setExpandedOptions(function (prev) {
-                return prev.includes(target) ? prev
-                    : expandMode === 'multi' ? __spreadArray(__spreadArray([], prev, true), [target], false) 
-                    // `expandMode: 'single'` is a rule about what a CLICK does: opening a
-                    // row closes the one the reader last opened. It is not a licence to
-                    // close a row the HOST named through `initialExpandedOptions`. That
-                    // is an address — a statement about what the page is FOR, made before
-                    // the reader did anything — and this scan is a convenience layered on
-                    // top of it. Keep the named rows; replace only what a click could.
-                    : __spreadArray(__spreadArray([], prev.filter(function (name) { return initialExpandedOptions === null || initialExpandedOptions === void 0 ? void 0 : initialExpandedOptions.includes(name); }), true), [target], false);
-            });
-        }
+        openFirstAttentionRow(firstAttentionRow());
     }, [
         autoFocusFirstRequired,
         expandFirstRequired,
@@ -1796,11 +2072,84 @@ var FormEngineImpl = function (_a) {
         expandMode,
         initialExpandedOptions,
     ]);
+    /* The two first moves a user makes in a form opened from a button, while the scan above waits for the
+       focus to be free:
+       - pointing into the form (a click on a row, a field, the toolbar) is choosing where to work, and spends
+         the scan, as opening a row does (`toggleExpandedOption`);
+       - coming into it from the keyboard (Tab from the button) chooses nothing, and runs the scan now: the user
+         is put in the first row that needs an answer, once. Coming straight into a control they can type in
+         (a field already open, the search box) is theirs, and spends the scan without moving them.
+       Only while the scan still waits; it never runs twice. */
+    var keyboardEntry = (0, react_2.useRef)();
+    keyboardEntry.current = function (event) {
+        if (hasAutoFocusedRef.current || !options || !Object.keys(availableOptions).length) {
+            return;
+        }
+        var from = event.relatedTarget;
+        if (from && (compactWrapNode === null || compactWrapNode === void 0 ? void 0 : compactWrapNode.contains(from))) {
+            return;
+        }
+        hasAutoFocusedRef.current = true;
+        var entered = event.target;
+        if ((0, rowFocus_1.isTypingControl)(entered)) {
+            return;
+        }
+        var target = firstAttentionRow();
+        if (!target) {
+            return;
+        }
+        // A row takes the caret only from nothing - never from an element the reader is on (see CompactRow) - so
+        // the element the Tab landed on lets it go: the scan is what the reader came in for.
+        entered.blur();
+        openFirstAttentionRow(target);
+    };
+    (0, react_2.useEffect)(function () {
+        if (!autoFocusFirstRequired || !compact || !compactWrapNode) {
+            return undefined;
+        }
+        var onPointerDown = function () {
+            hasAutoFocusedRef.current = true;
+        };
+        var onFocusIn = function (event) { var _a; return (_a = keyboardEntry.current) === null || _a === void 0 ? void 0 : _a.call(keyboardEntry, event); };
+        // capture: the pointer is the user's choice before anything in the form answers it
+        compactWrapNode.addEventListener('pointerdown', onPointerDown, true);
+        compactWrapNode.addEventListener('focusin', onFocusIn);
+        return function () {
+            compactWrapNode.removeEventListener('pointerdown', onPointerDown, true);
+            compactWrapNode.removeEventListener('focusin', onFocusIn);
+        };
+    }, [autoFocusFirstRequired, compact, compactWrapNode]);
     // Read-first completion summary (how many shown options have a value set),
     // surfaced as a progress meter at the top of the compact form.
     var readFirstCompletion = (0, react_2.useMemo)(function () {
-        return (0, readFirst_1.getReadFirstCompletion)(availableOptions, function (name) { return getOptionBucket(name) === 'attention'; });
-    }, [JSON.stringify(availableOptions), getOptionBucket]);
+        return (0, readFirst_1.getReadFirstCompletion)(
+        // a hidden field (its `depends_on` does not hold) is not in the form, nor in its meter
+        (0, lodash_1.omit)(availableOptions, dependencyLockedNames), function (name) { return getOptionBucket(name) === 'attention'; });
+    }, [JSON.stringify(availableOptions), getOptionBucket, dependencyLockedNames]);
+    /* The hidden fields (their `depends_on` does not hold) that hold a value: kept, not dropped silently, so the form
+       says so in a note - and whether the value is valid, as no field shows it (qorus#646, David). */
+    var hiddenFieldsWithValues = (0, react_2.useMemo)(function () {
+        return dependencyLockedNames
+            .filter(function (name) { var _a; return !(0, readFirst_1.isOptionValueEmpty)((_a = availableOptions === null || availableOptions === void 0 ? void 0 : availableOptions[name]) === null || _a === void 0 ? void 0 : _a.value); })
+            .map(function (name) {
+            var field = availableOptions[name];
+            var schema = options === null || options === void 0 ? void 0 : options[name];
+            var type = (0, exports.getOptionFieldStorageType)(name, field.type, options, operators, field.op, isRendererOnly, optionHoldsExpression(field));
+            var validation = (0, validations_1.validateFieldWithResult)((0, exports.getType)(type), field.value, __assign(__assign({ has_to_have_value: true, optionSchema: options, options: availableOptions }, schema), { isFunction: field.is_expression, hasOwnEditor: isRendererOnly(schema === null || schema === void 0 ? void 0 : schema.ui_type) }));
+            return {
+                name: name,
+                label: (schema === null || schema === void 0 ? void 0 : schema.display_name) || name,
+                conditions: (0, OptionFieldMessages_1.describeDependencies)(((schema === null || schema === void 0 ? void 0 : schema.depends_on) || []), options || {}),
+                invalidReason: validation.isValid ? undefined : validation.reason,
+            };
+        });
+    }, [
+        dependencyLockedNames,
+        JSON.stringify(availableOptions),
+        JSON.stringify(options),
+        JSON.stringify(operators),
+        isRendererOnly,
+    ]);
     var optionalFields = (0, react_2.useMemo)(function () {
         return Object.keys(filteredOptions).map(function (option) {
             var _a, _b, _c, _d, _f, _g;
@@ -1999,6 +2348,9 @@ var FormEngineImpl = function (_a) {
                     // reqraft: form-level expression fields get the Visual/Text shell
                     // (DPQL text mode); opt out per-form via `templateFieldProps`.
                     allowTextExpressions: true, 
+                    // a form's options enter their value on tabs: Value · Expression · Visual, or Value · Template
+                    // where only templates are taken (qorus#646); opt out per-form via `templateFieldProps`
+                    valueTabs: true, 
                     // A fixed allowed-value field still needs its selector even when
                     // arbitrary custom values are forbidden. TemplateField uses this
                     // flag to decide whether to mount AutoFormField at all; treating
@@ -2064,7 +2416,7 @@ var FormEngineImpl = function (_a) {
         fixedValue,
         // Depend on the specific `rest` values used, not the whole `rest` object
         // (which is a fresh `{...rest}` every render and would defeat the memo).
-        rest === null || rest === void 0 ? void 0 : rest.options,
+        optionsSchema,
         rest === null || rest === void 0 ? void 0 : rest.size,
         handleValueChange,
         handleOperatorChange,
@@ -2076,11 +2428,11 @@ var FormEngineImpl = function (_a) {
         inheritedFromParent,
     ]);
     // Compact (read-first) rendering.
-    // Theme-derived colours so the flat-row layout adapts to light/dark/custom themes.
+    // Theme-derived colors so the flat-row layout adapts to light/dark/custom themes.
     var cText = ((_b = theme === null || theme === void 0 ? void 0 : theme.text) === null || _b === void 0 ? void 0 : _b.color) || '#f1f0ee';
-    // Text emphasis tiers via reqore's readable-colour helper (key = full readable
+    // Text emphasis tiers via reqore's readable-color helper (key = full readable
     // text, muted = its dimmed variant, faint = the dimmed variant softened
-    // further) instead of hand-rolled hex-alpha suffixes on the raw text colour.
+    // further) instead of hand-rolled hex-alpha suffixes on the raw text color.
     var cKey = (0, colors_1.getReadableColor)(theme);
     var cMuted = (0, colors_1.getReadableColor)(theme, undefined, undefined, true);
     var cFaint = "".concat(cMuted, "99");
@@ -2090,6 +2442,15 @@ var FormEngineImpl = function (_a) {
     var cWarning = ((_d = theme === null || theme === void 0 ? void 0 : theme.intents) === null || _d === void 0 ? void 0 : _d.warning) || '#ffdf34';
     var cInfo = ((_f = theme === null || theme === void 0 ? void 0 : theme.intents) === null || _f === void 0 ? void 0 : _f.info) || '#3b8eea';
     var cSuccess = ((_g = theme === null || theme === void 0 ? void 0 : theme.intents) === null || _g === void 0 ? void 0 : _g.success) || '#36b37e';
+    // the rows' own words and marks, in colors that read on every surface a row is drawn on
+    var rowInks = (0, react_2.useMemo)(function () { return (0, readFirstColors_1.getReadFirstInks)(theme); }, [theme]);
+    // an option panel's short description, faint: as faint as it still reads in the theme
+    var optionDescOpacity = (0, react_2.useMemo)(function () { return (0, readableColors_1.getReadableTextOpacity)(theme, 0.3); }, [theme]);
+    /* an invalid option's mark in its panel's title: the danger, in the shade of it that stands out as reqore draws a
+       title icon, at 70% (danger:lighten:5 was 2.9:1) */
+    var invalidOptionIconColor = (0, react_2.useMemo)(function () {
+        return (0, readableColors_1.getReadableShade)(cDanger, (0, readableColors_1.getThemeSurfaces)(theme), readableColors_1.READABLE_ICON, PANEL_TITLE_ICON_ALPHA);
+    }, [theme, cDanger]);
     var cBg = (theme === null || theme === void 0 ? void 0 : theme.main) || '#181818';
     var cRowBg = (0, colors_1.changeDarkness)((0, colors_1.getMainBackgroundColor)(theme), 0.01);
     var cGroupLine = "".concat(cText, "1f");
@@ -2099,8 +2460,39 @@ var FormEngineImpl = function (_a) {
     // The closure surface the extracted CompactRow reads through context. Refs and
     // setters are stable; the state/memo/handler fields change identity as they do
     // today, so a row re-renders exactly when its inputs do.
+    /* An open field is held in the box it was opened in, so finishing an edit does not remount it elsewhere
+       and take the focus (see `stableBucketOf`). Held, it says where it now belongs - otherwise a value
+       already right sat under "Needs attention" until ✓ was pressed, with nothing saying why (David's review
+       of qorus#646). Keyed by option name: the box it moves to when closed.
+  
+       It is said once per form, on the first field held this way, and on no field once that one is closed:
+       the user knows it from then on, and saying it on every field takes room (qlip build 20261008-083118;
+       David's decision). `movesToNoteFor` is that field - undefined until one is held, null once it is
+       closed. */
+    var heldEntries = expandedOptions
+        .map(function (name) { return [name, settledBucket.current[name], getOptionBucket(name)]; })
+        .filter(function (_a) {
+        var held = _a[1], now = _a[2];
+        return !!held && held !== now;
+    })
+        .map(function (_a) {
+        var name = _a[0], now = _a[2];
+        return [name, now];
+    });
+    if (movesToNoteFor.current === undefined && heldEntries.length) {
+        movesToNoteFor.current = heldEntries[0][0];
+    }
+    else if (movesToNoteFor.current && !expandedOptions.includes(movesToNoteFor.current)) {
+        movesToNoteFor.current = null;
+    }
+    var heldOptionsKey = JSON.stringify(Object.fromEntries(heldEntries.filter(function (_a) {
+        var name = _a[0];
+        return name === movesToNoteFor.current;
+    })));
+    var heldOptions = (0, react_2.useMemo)(function () { return JSON.parse(heldOptionsKey); }, [heldOptionsKey]);
     var compactRowContextValue = (0, react_2.useMemo)(function () { return ({
         templates: templates.value,
+        heldOptions: heldOptions,
         readOnly: readOnly,
         onReadOnlyActivate: onReadOnlyActivate,
         commitMode: commitMode,
@@ -2110,6 +2502,7 @@ var FormEngineImpl = function (_a) {
         focusedEditing: focusedEditing,
         showFieldTypes: showFieldTypes,
         codePreviewRenderer: codePreviewRenderer,
+        readSummaries: readSummaries,
         showAllDescriptions: showAllDescriptions,
         expandedOptions: expandedOptions,
         highlightedOptions: highlightedOptions,
@@ -2147,8 +2540,10 @@ var FormEngineImpl = function (_a) {
         cWarning: cWarning,
         cInfo: cInfo,
         cBg: cBg,
+        rowInks: rowInks,
     }); }, [
         templates.value,
+        heldOptions,
         readOnly,
         commitMode,
         expandMode,
@@ -2157,6 +2552,7 @@ var FormEngineImpl = function (_a) {
         focusedEditing,
         showFieldTypes,
         codePreviewRenderer,
+        readSummaries,
         showAllDescriptions,
         expandedOptions,
         highlightedOptions,
@@ -2194,6 +2590,7 @@ var FormEngineImpl = function (_a) {
         cWarning,
         cInfo,
         cBg,
+        rowInks,
     ]);
     // `compactToolbar` resolved to a full object, so neither the context type nor
     // the toolbar itself has to re-default anything. `null` means no toolbar.
@@ -2571,7 +2968,7 @@ var FormEngineImpl = function (_a) {
                 // "Covers"/"Covered by" chips already say which member satisfies it.
                 if (requiredGroupsInfo.satisfiedBy[grp])
                     return railed;
-                return ((0, jsx_runtime_1.jsxs)(compactRowStyles_1.StyledRequiredClusterBox, { className: 'options-readfirst-required-cluster', "$border": "".concat(cWarning, "33"), "$tint": "".concat(cWarning, "0d"), children: [(0, jsx_runtime_1.jsxs)(compactRowStyles_1.StyledRequiredClusterHeader, { "$color": cWarning, children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreIcon, { icon: 'LinkM', size: '11px', style: { color: cWarning } }), "One of the below is required"] }), railed] }, grp));
+                return ((0, jsx_runtime_1.jsxs)(compactRowStyles_1.StyledRequiredClusterBox, { className: 'options-readfirst-required-cluster', "$border": "".concat(cWarning, "33"), "$tint": "".concat(cWarning, "0d"), children: [(0, jsx_runtime_1.jsxs)(compactRowStyles_1.StyledRequiredClusterHeader, { "$color": rowInks.warning, children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreIcon, { icon: 'LinkM', size: '11px', style: { color: rowInks.warning } }), "One of the below is required"] }), railed] }, grp));
             });
         };
         // One schema group inside a status box: its thin sub-label, the group's
@@ -2655,7 +3052,7 @@ var FormEngineImpl = function (_a) {
                                                visible` to `auto` unless the other axis is visible or
                                                clip, which would put the scrollport straight back. `clip`
                                                keeps the horizontal guard the row ellipsis relies on. */
-                                            overflowY: 'visible', overflowX: 'clip' }, compactPanelProps === null || compactPanelProps === void 0 ? void 0 : compactPanelProps.contentStyle), children: [(0, size_1.default)(groupKeys) === 0 || (readOnly && !bucketCount('set')) ?
+                                            overflowY: 'visible', overflowX: 'clip' }, compactPanelProps === null || compactPanelProps === void 0 ? void 0 : compactPanelProps.contentStyle), children: [(0, jsx_runtime_1.jsx)(HiddenFieldsNote_1.HiddenFieldsNote, { fields: hiddenFieldsWithValues }), (0, size_1.default)(groupKeys) === 0 || (readOnly && !bucketCount('set')) ?
                                                 (0, jsx_runtime_1.jsx)(reqore_1.ReqoreMessage, { flat: true, opaque: false, size: 'small', children: readOnly && !query ?
                                                         'Nothing is set.'
                                                         : 'No fields match the current filters.' })
@@ -2772,7 +3169,7 @@ var FormEngineImpl = function (_a) {
                                                                     })
                                                                     : null] }) }, box.key));
                                                 })] })), commitMode === 'batched' && !readOnly && dirtyOptionNames.length ?
-                                        (0, jsx_runtime_1.jsx)(StyledCommitDock, { "$bg": cBg, "$border": cDivider, children: (0, jsx_runtime_1.jsxs)(reqore_1.ReqoreControlGroup, { className: 'options-readfirst-commitbar', verticalAlign: 'center', wrap: true, children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreTag, { size: 'tiny', minimal: true, flat: true, compact: true, effect: { uppercase: true, spaced: 1 }, intent: 'warning', icon: 'EditLine', label: "".concat(dirtyOptionNames.length, " unsaved change").concat(dirtyOptionNames.length === 1 ? '' : 's') }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreButton, { size: 'small', intent: 'success', icon: 'CheckLine', fixed: true, className: 'options-readfirst-save', disabled: !validityData.isValid, tooltip: validityData.isValid ?
+                                        (0, jsx_runtime_1.jsx)(StyledCommitDock, { "$bg": cBg, "$border": cDivider, children: (0, jsx_runtime_1.jsxs)(reqore_1.ReqoreControlGroup, { className: 'options-readfirst-commitbar', verticalAlign: 'center', wrap: true, children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreTag, { size: 'tiny', minimal: true, flat: true, compact: true, effect: { uppercase: true, spaced: 1 }, intent: 'warning', icon: 'EditLine', label: "".concat(dirtyOptionNames.length, " unsaved change").concat(dirtyOptionNames.length === 1 ? '' : 's') }), validityData.isValid ? null : ((0, jsx_runtime_1.jsx)(reqore_1.ReqoreTag, { size: 'tiny', minimal: true, flat: true, wrap: true, intent: 'danger', icon: 'ErrorWarningLine', className: 'options-readfirst-commit-blocked', label: (0, readFirst_1.describeBlockedSave)(validityData.invalidFields, options) })), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreButton, { size: 'small', intent: 'success', icon: 'CheckLine', fixed: true, className: 'options-readfirst-save', disabled: !validityData.isValid, tooltip: validityData.isValid ?
                                                             'Apply the staged changes'
                                                             : 'Resolve the invalid fields before saving', onClick: handleCommitClick, children: "Save" }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreButton, { size: 'small', minimal: true, flat: true, fixed: true, icon: 'HistoryLine', className: 'options-readfirst-discard', onClick: handleRevertChangesClick, children: "Discard" })] }) })
                                         : null] }) })] }) }) }));
@@ -2780,7 +3177,10 @@ var FormEngineImpl = function (_a) {
     /* Which of the seven waits is holding the form, in the order they are
        tested. Rendered as `data-wait` on the placeholder so a page can be asked
        what it is waiting FOR instead of only that it is waiting. */
-    var waitReason = rest.skeleton ? (rest.skeletonReason ? "host:".concat(rest.skeletonReason) : 'host')
+    var waitReason = rest.skeleton ?
+        skeletonReason ?
+            "host:".concat(skeletonReason)
+            : 'host'
         : templates.loading ? 'templates'
             : typesLoading ? 'types'
                 : optionsLoading ? 'options'
@@ -2816,7 +3216,7 @@ var FormEngineImpl = function (_a) {
                                         : "".concat((0, size_1.default)(validityData.invalidFields) < 2 ? 'A field is not valid and requires' : "".concat((0, size_1.default)(validityData.invalidFields), " fields are not valid and require"), " attention. Click here to only show invalid fields.") })
                                 : null, unavailableOptionsCount.current ?
                                 (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreMessage, { intent: 'warning', opaque: false, size: 'small', margin: 'bottom', children: "".concat(unavailableOptionsCount.current, " fields(s) hidden because they are not supported on the current instance") }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreVerticalSpacer, { height: 10 })] })
-                                : null, children, (0, size_1.default)(filteredOptions) >= 1 && !readOnly ?
+                                : null, (0, jsx_runtime_1.jsx)(HiddenFieldsNote_1.HiddenFieldsNote, { fields: hiddenFieldsWithValues }), children, (0, size_1.default)(filteredOptions) >= 1 && !readOnly ?
                                 (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreVerticalSpacer, { height: 10 }), (0, jsx_runtime_1.jsx)(Select_1.SelectFormField, { items: optionalFields, onChange: function (val) { return handleAddOptionalFieldChange('options', val); }, placeholder: placeholder || 'More Options Available', minimal: true, icon: 'ListView', showDescription: false, fluid: true, size: rest.size })] })
                                 : null] })); }, sortButtonProps: { minimal: true }, showLayoutSwitch: false, style: { width: '100%' }, items: (0, map_1.default)(shownOptions, function (_a, optionName) {
                         var _b, _c, _d, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v;
@@ -2847,7 +3247,7 @@ var FormEngineImpl = function (_a) {
                                 : options[optionName].short_desc || '',
                             descriptionEffect: {
                                 textSize: '11px',
-                                opacity: 0.3,
+                                opacity: optionDescOpacity,
                                 underline: ((_l = options[optionName]) === null || _l === void 0 ? void 0 : _l.desc) ? 'underline dotted #878787' : undefined,
                             },
                             customTheme: {
@@ -2857,7 +3257,7 @@ var FormEngineImpl = function (_a) {
                             icon: !isOptionValid(optionName, type, other.value) ? 'SpamFill'
                                 : undefined,
                             iconColor: !isOptionValid(optionName, type, other.value) ?
-                                'danger:lighten:5'
+                                invalidOptionIconColor
                                 : undefined,
                             transparent: false,
                             intent: getIntent(optionName, type, other.value, other.op),