@qoretechnologies/reqraft 0.10.2 → 0.10.5

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

@@ -297,40 +297,44 @@ var FormEngine = 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
     isValid = _a.isValid, // eslint-disable-line @typescript-eslint/no-unused-vars
-    url = _a.url, customUrl = _a.customUrl, operatorsUrl = _a.operatorsUrl, onOptionsLoaded = _a.onOptionsLoaded, recordRequiresSearchOptions = _a.recordRequiresSearchOptions, readOnly = _a.readOnly, _h = _a.allowTemplates, allowTemplates = _h === void 0 ? true : _h, interfaceContext = _a.interfaceContext, templateFieldProps = _a.templateFieldProps, _j = _a.showTypeToggle, showTypeToggle = _j === void 0 ? true : _j, compact = _a.compact, _k = _a.compactFlush, compactFlush = _k === void 0 ? false : _k, _l = _a.commitMode, commitMode = _l === void 0 ? 'immediate' : _l, _m = _a.expandMode, expandMode = _m === void 0 ? 'single' : _m, onCommit = _a.onCommit, operatorsProp = _a.operators, groups = _a.groups, optionsLoader = _a.optionsLoader, onValidityChange = _a.onValidityChange, optionActions = _a.optionActions, componentOverrides = _a.componentOverrides, rest = __rest(_a, ["name", "uniqueName", "value", "onChange", "onSingleOptionsChange", "onDependableOptionChange", "placeholder", "noValueString", "isValid", "url", "customUrl", "operatorsUrl", "onOptionsLoaded", "recordRequiresSearchOptions", "readOnly", "allowTemplates", "interfaceContext", "templateFieldProps", "showTypeToggle", "compact", "compactFlush", "commitMode", "expandMode", "onCommit", "operators", "groups", "optionsLoader", "onValidityChange", "optionActions", "componentOverrides"]);
-    var _o = (0, react_2.useState)((rest === null || rest === void 0 ? void 0 : rest.options) || undefined), options = _o[0], setOptions = _o[1];
+    url = _a.url, customUrl = _a.customUrl, operatorsUrl = _a.operatorsUrl, onOptionsLoaded = _a.onOptionsLoaded, recordRequiresSearchOptions = _a.recordRequiresSearchOptions, readOnly = _a.readOnly, _h = _a.allowTemplates, allowTemplates = _h === void 0 ? true : _h, interfaceContext = _a.interfaceContext, templateFieldProps = _a.templateFieldProps, _j = _a.showTypeToggle, showTypeToggle = _j === void 0 ? true : _j, compact = _a.compact, _k = _a.compactFlush, compactFlush = _k === void 0 ? false : _k, _l = _a.compactNested, compactNested = _l === void 0 ? false : _l, _m = _a.commitMode, commitMode = _m === void 0 ? 'immediate' : _m, _o = _a.expandMode, expandMode = _o === void 0 ? 'single' : _o, onCommit = _a.onCommit, operatorsProp = _a.operators, groups = _a.groups, optionsLoader = _a.optionsLoader, onValidityChange = _a.onValidityChange, optionActions = _a.optionActions, componentOverrides = _a.componentOverrides, rest = __rest(_a, ["name", "uniqueName", "value", "onChange", "onSingleOptionsChange", "onDependableOptionChange", "placeholder", "noValueString", "isValid", "url", "customUrl", "operatorsUrl", "onOptionsLoaded", "recordRequiresSearchOptions", "readOnly", "allowTemplates", "interfaceContext", "templateFieldProps", "showTypeToggle", "compact", "compactFlush", "compactNested", "commitMode", "expandMode", "onCommit", "operators", "groups", "optionsLoader", "onValidityChange", "optionActions", "componentOverrides"]);
+    var _p = (0, react_2.useState)((rest === null || rest === void 0 ? void 0 : rest.options) || undefined), options = _p[0], setOptions = _p[1];
     // optionsLoader lifecycle: loading feeds the skeleton gate, error the banner.
-    var _p = (0, react_2.useState)(!!optionsLoader && !(rest === null || rest === void 0 ? void 0 : rest.options)), optionsLoading = _p[0], setOptionsLoading = _p[1];
-    var _q = (0, react_2.useState)(), optionsError = _q[0], setOptionsError = _q[1];
+    var _q = (0, react_2.useState)(!!optionsLoader && !(rest === null || rest === void 0 ? void 0 : rest.options)), optionsLoading = _q[0], setOptionsLoading = _q[1];
+    var _r = (0, react_2.useState)(), optionsError = _r[0], setOptionsError = _r[1];
     // Operators: prop-provided (compact) or fetched via operatorsUrl (dpql,
     // ported from IDE Options) — the fetch overrides the seeded prop value.
-    var _r = (0, react_2.useState)(operatorsProp), operators = _r[0], setOperators = _r[1];
+    var _s = (0, react_2.useState)(operatorsProp), operators = _s[0], setOperators = _s[1];
     // Remote-fetch loading (ported from IDE Options); only relevant when one of
     // the fetch urls is set — schema-as-props consumers never see the skeleton.
-    var _s = (0, react_2.useState)(!!(url || customUrl || operatorsUrl)), loading = _s[0], setLoading = _s[1];
+    var _t = (0, react_2.useState)(!!(url || customUrl || operatorsUrl)), loading = _t[0], setLoading = _t[1];
     var confirmAction = (0, reqore_1.useReqoreProperty)('confirmAction');
     var theme = (0, reqore_1.useReqoreTheme)();
-    var _t = (0, react_2.useState)(), focusedEditing = _t[0], setFocusedEditing = _t[1];
-    var _u = (0, react_2.useState)(false), showFieldTypes = _u[0], setShowFieldTypes = _u[1];
+    var _u = (0, react_2.useState)(), focusedEditing = _u[0], setFocusedEditing = _u[1];
+    var _v = (0, react_2.useState)(false), showFieldTypes = _v[0], setShowFieldTypes = _v[1];
     // Global toggle (toolbar ⓘ): reveal the short-description info panel on every
     // field that has a short_desc. Per-row ⓘ overrides still win over it.
     // Global field-info visibility, tri-state: `undefined` = default (critical
     // messages auto-open, the rest closed); `true` = show all; `false` = hide all
     // (even message fields). The toolbar ⓘ drives it.
-    var _v = (0, react_2.useState)(undefined), showAllDescriptions = _v[0], setShowAllDescriptions = _v[1];
-    var _w = (0, react_2.useState)(), showHelpForOption = _w[0], setShowHelpForOption = _w[1];
-    var _x = (0, react_2.useState)(false), showInvalidOptionsOnly = _x[0], setShowInvalidOptionsOnly = _x[1];
+    var _w = (0, react_2.useState)(undefined), showAllDescriptions = _w[0], setShowAllDescriptions = _w[1];
+    var _x = (0, react_2.useState)(), showHelpForOption = _x[0], setShowHelpForOption = _x[1];
+    var _y = (0, react_2.useState)(false), showInvalidOptionsOnly = _y[0], setShowInvalidOptionsOnly = _y[1];
     // Which options are expanded into their editor (several can be open at once).
-    var _y = (0, react_2.useState)([]), expandedOptions = _y[0], setExpandedOptions = _y[1];
+    var _z = (0, react_2.useState)([]), expandedOptions = _z[0], setExpandedOptions = _z[1];
+    // Remembers each row's last settled status box, so an actively-edited field
+    // 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)({});
     // Measured form width (not viewport — the form lives in drawers/panels of
     // arbitrary width) drives the stacked narrow layout.
-    var _z = (0, react_use_1.useMeasure)(), compactWrapRef = _z[0], compactWrapWidth = _z[1].width;
+    var _0 = (0, react_use_1.useMeasure)(), compactWrapRef = _0[0], compactWrapWidth = _0[1].width;
     // Own handle on the scroll wrap (useMeasure's ref is a callback, no `.current`)
     // so the label-column measurement can publish its CSS var on the element. It's
     // STATE, not a ref: the wrap mounts only after the loading-skeleton gate
     // resolves, so the measurement effect must re-run when the node appears — a
     // ref wouldn't retrigger it.
-    var _0 = (0, react_2.useState)(null), compactWrapNode = _0[0], setCompactWrapNode = _0[1];
+    var _1 = (0, react_2.useState)(null), compactWrapNode = _1[0], setCompactWrapNode = _1[1];
     var setCompactWrap = (0, react_2.useCallback)(function (node) {
         compactWrapRef(node);
         setCompactWrapNode(function (prev) { return (prev === node ? prev : node); });
@@ -367,15 +371,21 @@ var FormEngine = function (_a) {
     var readRowHeights = (0, react_2.useRef)({});
     // Required-groups linkage: hovering a group chip highlights every member row;
     // clicking a sibling in the chip's popover scrolls to it and flashes it.
-    var _1 = (0, react_2.useState)([]), highlightedOptions = _1[0], setHighlightedOptions = _1[1];
-    var _2 = (0, react_2.useState)([]), flashedOptions = _2[0], setFlashedOptions = _2[1];
+    var _2 = (0, react_2.useState)([]), highlightedOptions = _2[0], setHighlightedOptions = _2[1];
+    var _3 = (0, react_2.useState)([]), flashedOptions = _3[0], setFlashedOptions = _3[1];
     var flashTimeout = (0, react_2.useRef)();
     var flashOptions = (0, react_2.useCallback)(function (optionNames, scrollToFirst) {
-        var _a;
         if (scrollToFirst === void 0) { scrollToFirst = false; }
         if (scrollToFirst && optionNames[0]) {
-            (_a = document
-                .querySelector(".readfirst-row[data-field=\"".concat(optionNames[0], "\"]"))) === null || _a === void 0 ? void 0 : _a.scrollIntoView({ block: 'center', behavior: 'smooth' });
+            // Defer to the next frame: when this fires for a field that just changed
+            // panels, its row has only just re-mounted in the new box — scrolling in the
+            // same tick targets the stale (pre-move) layout, so the page doesn't budge.
+            // A rAF lets the new position settle first.
+            requestAnimationFrame(function () {
+                var _a;
+                (_a = document
+                    .querySelector(".readfirst-row[data-field=\"".concat(optionNames[0], "\"]"))) === null || _a === void 0 ? void 0 : _a.scrollIntoView({ block: 'center', behavior: 'smooth' });
+            });
         }
         setFlashedOptions(optionNames);
         clearTimeout(flashTimeout.current);
@@ -383,18 +393,37 @@ var FormEngine = function (_a) {
     }, []);
     var flashOption = (0, react_2.useCallback)(function (optionName) { return flashOptions([optionName], true); }, [flashOptions]);
     (0, react_2.useEffect)(function () { return function () { return clearTimeout(flashTimeout.current); }; }, []);
+    // Follow a field across panels: when its status bucket changes — e.g. you fill
+    // an optional field and it jumps to Set / Needs attention — scroll to its new
+    // row and flash it so it's easy to keep track of. `settledBucket` holds each
+    // field's current panel (frozen while the field is being edited, it re-buckets
+    // on collapse), so diffing it after every render catches the move the instant it
+    // lands in the new panel. Runs every render; the diff is cheap and only fires a
+    // scroll on an ACTUAL move of a non-expanded field.
+    var prevSettledBucket = (0, react_2.useRef)({});
+    (0, react_2.useEffect)(function () {
+        if (!compact)
+            return;
+        var cur = settledBucket.current;
+        var prev = prevSettledBucket.current;
+        var moved = Object.keys(cur).find(function (name) { return prev[name] && prev[name] !== cur[name] && !expandedOptions.includes(name); });
+        prevSettledBucket.current = __assign({}, cur);
+        if (moved) {
+            flashOptions([moved], true);
+        }
+    });
     var compactNarrow = !!compactWrapWidth && compactWrapWidth < 480;
     // Info panels auto-open on Tier-1 content; the per-row user override sticks.
-    var _3 = (0, react_2.useState)({}), infoPanelOverrides = _3[0], setInfoPanelOverrides = _3[1];
+    var _4 = (0, react_2.useState)({}), infoPanelOverrides = _4[0], setInfoPanelOverrides = _4[1];
     // Toolbar filters affect the listed rows only — the meter reflects the full set.
-    var _4 = (0, react_2.useState)(false), requiredOnly = _4[0], setRequiredOnly = _4[1];
-    var _5 = (0, react_2.useState)(''), compactQuery = _5[0], setCompactQuery = _5[1];
+    var _5 = (0, react_2.useState)(false), requiredOnly = _5[0], setRequiredOnly = _5[1];
+    var _6 = (0, react_2.useState)(''), compactQuery = _6[0], setCompactQuery = _6[1];
     // Compact field sort (Fields menu → "Sort by"); 'schema' = declared order.
-    var _6 = (0, react_2.useState)('schema'), compactSort = _6[0], setCompactSort = _6[1];
-    var _7 = (0, react_2.useState)(function () { return ({
+    var _7 = (0, react_2.useState)('schema'), compactSort = _7[0], setCompactSort = _7[1];
+    var _8 = (0, react_2.useState)(function () { return ({
         fields: (0, exports.fixOptions)(value, options || {}),
         meta: undefined,
-    }); }), localValue = _7[0], setLocalValue = _7[1];
+    }); }), localValue = _8[0], setLocalValue = _8[1];
     var originalValue = (0, react_2.useRef)();
     // Track the last value we emitted via onChange so we can skip re-applying fixOptions
     // when the parent echoes it back as the new value prop (controlled component loop prevention)
@@ -403,7 +432,7 @@ var FormEngine = function (_a) {
         originalValue.current = localValue.fields;
     }
     var unavailableOptionsCount = (0, react_2.useRef)(0);
-    var _8 = (0, useQorusTypes_1.useQorusTypes)(), compactValue = _8.compactValue, typesLoading = _8.loading;
+    var _9 = (0, useQorusTypes_1.useQorusTypes)(), compactValue = _9.compactValue, typesLoading = _9.loading;
     var templates = (0, useTemplates_1.useTemplates)(allowTemplates, rest.stringTemplates, interfaceContext);
     (0, react_2.useEffect)(function () {
         if ((0, lodash_1.isEqual)(localValue.fields, value)) {
@@ -726,6 +755,10 @@ var FormEngine = function (_a) {
                 meta: undefined,
             };
         });
+        // Collapse it too: a removed field drops back to the (collapsed) Optional box
+        // as a quiet addable row — if it was being edited, that editor must close
+        // rather than linger as an open editor for a field that's no longer added.
+        setExpandedOptions(function (prev) { return prev.filter(function (name) { return name !== optionName; }); });
     }, []);
     var handleAddOptionalFieldChange = (0, react_2.useCallback)(function (_name, optionName) {
         var _a, _b, _c;
@@ -889,6 +922,67 @@ var FormEngine = function (_a) {
             return __assign(__assign({}, newValue), (_a = {}, _a[optionName] = option, _a));
         }, {});
     }, [showInvalidOptionsOnly, JSON.stringify(availableOptions)]);
+    // Read-first STATUS / BOX for one option — lifted to component scope so the
+    // status boxes (renderCompact) and the header's "needs attention" count share
+    // exactly one definition. One-of group members travel together (bucket by the
+    // group's satisfaction); everything else by its own status.
+    var schemaMsgIntent = (0, react_2.useCallback)(function (name) {
+        var _a;
+        var msgs = (((_a = options === null || options === void 0 ? void 0 : options[name]) === null || _a === void 0 ? void 0 : _a.messages) || []);
+        if (msgs.some(function (m) { return m.intent === 'danger'; }))
+            return 'danger';
+        if (msgs.some(function (m) { return m.intent === 'warning'; }))
+            return 'warning';
+        return undefined;
+    }, [JSON.stringify(options)]);
+    var getOptionStatus = (0, react_2.useCallback)(function (name, hidden) {
+        var _a;
+        if (hidden === void 0) { hidden = false; }
+        if (hidden)
+            return 'optional';
+        var schema = options === null || options === void 0 ? void 0 : options[name];
+        var type = ((schema === null || schema === void 0 ? void 0 : schema.ui_type) || (schema === null || schema === void 0 ? void 0 : schema.type));
+        var value = (_a = availableOptions === null || availableOptions === void 0 ? void 0 : availableOptions[name]) === null || _a === void 0 ? void 0 : _a.value;
+        var empty = (0, readFirst_1.isOptionValueEmpty)(value);
+        var reqGroups = (schema === null || schema === void 0 ? void 0 : schema.required_groups) || [];
+        var required = !!((schema === null || schema === void 0 ? void 0 : schema.required) || reqGroups.length);
+        var covered = empty &&
+            reqGroups.some(function (g) {
+                var by = requiredGroupsInfo.satisfiedBy[g];
+                return !!by && by !== name;
+            });
+        var msgIntent = schemaMsgIntent(name);
+        var invalid = (!empty && !isOptionValid(name, type, value)) || msgIntent === 'danger';
+        return (0, readFirst_1.getReadFirstStatus)({
+            empty: empty,
+            required: required,
+            covered: covered,
+            invalid: invalid,
+            warned: msgIntent === 'warning',
+        });
+    }, [
+        JSON.stringify(options),
+        JSON.stringify(availableOptions),
+        isOptionValid,
+        requiredGroupsInfo,
+        schemaMsgIntent,
+    ]);
+    var getOptionBucket = (0, react_2.useCallback)(function (name, hidden) {
+        var _a;
+        if (hidden === void 0) { hidden = false; }
+        if (!hidden) {
+            var reqGroups = ((_a = options === null || options === void 0 ? void 0 : options[name]) === null || _a === void 0 ? void 0 : _a.required_groups) || [];
+            if (reqGroups.length) {
+                return reqGroups.some(function (g) { return !requiredGroupsInfo.satisfiedBy[g]; }) ? 'attention' : 'set';
+            }
+        }
+        return (0, readFirst_1.getReadFirstBucket)(getOptionStatus(name, hidden));
+    }, [JSON.stringify(options), requiredGroupsInfo, getOptionStatus]);
+    // 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]);
     var getIntent = (0, react_2.useCallback)(
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     function (optName, type, optValue, _op) {
@@ -1011,13 +1105,27 @@ var FormEngine = function (_a) {
     // The info panel below the row keeps showing schema messages while editing —
     // rendering them in the editor too would balloon a one-line edit.
     suppressSchemaMessages) {
-        var _b, _c, _d, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+        var _b, _c, _d, _f, _g, _h, _j, _k, _l, _m, _o, _p;
         var type = _a.type, other = __rest(_a, ["type"]);
         var operatorParts = (0, exports.fixOperatorValue)(other.op);
-        return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(suppressSchemaMessages ? [] : ((_b = options === null || options === void 0 ? void 0 : options[optionName]) === null || _b === void 0 ? void 0 : _b.messages) || []).map(function (_a, index) {
-                    var intent = _a.intent, title = _a.title, content = _a.content;
-                    return ((0, jsx_runtime_1.jsx)(reqore_1.ReqoreMessage, { intent: intent, title: title, opaque: false, size: 'small', margin: 'bottom', children: content }, title || index));
-                }), operators && (0, size_1.default)(operators) ?
+        return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(function () {
+                    var _a;
+                    var schemaMsgs = (suppressSchemaMessages ? [] : ((_a = options === null || options === void 0 ? void 0 : options[optionName]) === null || _a === void 0 ? void 0 : _a.messages) || []);
+                    if (!schemaMsgs.length)
+                        return null;
+                    var items = schemaMsgs.map(function (_a, index) {
+                        var intent = _a.intent, title = _a.title, content = _a.content;
+                        return ((0, jsx_runtime_1.jsx)(reqore_1.ReqoreMessage, { intent: intent, title: title, opaque: false, size: 'small', 
+                            // Compact: flat (no border) to match the read-row info panels;
+                            // classic forms keep the bordered, bottom-margined message.
+                            flat: compact || undefined, margin: compact ? undefined : 'bottom', children: content }, title || index));
+                    });
+                    // Compact: stack them in a 4px-gap panel so a field's messages look
+                    // identical whether the row is collapsed (read panel) or expanded.
+                    return compact ?
+                        (0, jsx_runtime_1.jsx)("div", { className: 'options-readfirst-info-panel', style: { display: 'flex', flexFlow: 'column', gap: 4, marginBottom: 8 }, children: items })
+                        : (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: items });
+                })(), operators && (0, size_1.default)(operators) ?
                     (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreControlGroup, { fill: true, wrap: true, className: 'operators', children: operatorParts.map(function (operator, index) {
                                     var _a, _b;
                                     return ((0, jsx_runtime_1.jsxs)(react_2.default.Fragment, { children: [(0, jsx_runtime_1.jsx)(Select_1.SelectFormField, { items: (0, map_1.default)(operators, function (op) { return (__assign(__assign({}, op), { value: op.name })); }), disabled: readOnly, value: operator && "".concat((_a = operators === null || operators === void 0 ? void 0 : operators[operator]) === null || _a === void 0 ? void 0 : _a.name), onChange: function (val) {
@@ -1033,18 +1141,21 @@ var FormEngine = function (_a) {
                                                 : null] }, index));
                                 }) }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreVerticalSpacer, { height: 5 })] })
                     : null, (0, react_1.createElement)(TemplateField_1.TemplateField, __assign({ fluid: true }, options === null || options === void 0 ? void 0 : options[optionName], { 
+                    // Propagate compact so an arg_schema field renders a COMPACT sub-form
+                    // (consistent with the parent) rather than the classic FormEngine.
+                    compact: compact, 
                     // SEAM: forwarded through TemplateField's rest-spread to AutoFormField,
                     // which renders consumer-injected editors by field type/ui_type.
-                    componentOverrides: componentOverrides, allowTemplates: !!(allowTemplates && ((_c = options === null || options === void 0 ? void 0 : options[optionName]) === null || _c === void 0 ? void 0 : _c.supports_templates)), allowFunctions: !!((_d = options === null || options === void 0 ? void 0 : options[optionName]) === null || _d === void 0 ? void 0 : _d.supports_expressions), 
+                    componentOverrides: componentOverrides, allowTemplates: !!(allowTemplates && ((_b = options === null || options === void 0 ? void 0 : options[optionName]) === null || _b === void 0 ? void 0 : _b.supports_templates)), allowFunctions: !!((_c = options === null || options === void 0 ? void 0 : options[optionName]) === null || _c === void 0 ? void 0 : _c.supports_expressions), 
                     // reqraft: form-level expression fields get the Visual/Text shell
                     // (DPQL text mode); opt out per-form via `templateFieldProps`.
-                    allowTextExpressions: true, allowCustomValues: ((_f = options === null || options === void 0 ? void 0 : options[optionName]) === null || _f === void 0 ? void 0 : _f.supports_custom_values) !== false && type !== 'any', templates: templates.value }, (0, exports.getTypeAndCanBeNull)(type, (_g = options === null || options === void 0 ? void 0 : options[optionName]) === null || _g === void 0 ? void 0 : _g.allowed_values, other.op), { ui_type: type, name: optionName, uniqueName: "".concat(uniqueName ? "".concat(uniqueName, ".") : "".concat(name ? "".concat(name, ".") : '')).concat(optionName), onChange: 
+                    allowTextExpressions: true, allowCustomValues: ((_d = options === null || options === void 0 ? void 0 : options[optionName]) === null || _d === void 0 ? void 0 : _d.supports_custom_values) !== false && type !== 'any', templates: templates.value }, (0, exports.getTypeAndCanBeNull)(type, (_f = options === null || options === void 0 ? void 0 : options[optionName]) === null || _f === void 0 ? void 0 : _f.allowed_values, other.op), { ui_type: type, name: optionName, uniqueName: "".concat(uniqueName ? "".concat(uniqueName, ".") : "".concat(name ? "".concat(name, ".") : '')).concat(optionName), onChange: 
                     // Identity-stable on purpose: the typed fields debounce on
                     // `[localValue, onChange]` — an inline lambda resets the pending emit
                     // every render and the typed value can starve.
-                    handleValueChange, key: optionName, arg_schema: (_h = options === null || options === void 0 ? void 0 : options[optionName]) === null || _h === void 0 ? void 0 : _h.arg_schema, noSoft: !!(rest === null || rest === void 0 ? void 0 : rest.options), value: other.value, isFunction: other.is_expression, isDefaultFunction: ((_j = options === null || options === void 0 ? void 0 : options[optionName]) === null || _j === void 0 ? void 0 : _j.default_view) === 'expression', sensitive: (_k = options === null || options === void 0 ? void 0 : options[optionName]) === null || _k === void 0 ? void 0 : _k.sensitive, default_value: (0, common_1.getDefaultValue)(options === null || options === void 0 ? void 0 : options[optionName]), isDefaultTemplate: ((_l = options === null || options === void 0 ? void 0 : options[optionName]) === null || _l === void 0 ? void 0 : _l.default_view) === 'template', allowed_values: (_m = options === null || options === void 0 ? void 0 : options[optionName]) === null || _m === void 0 ? void 0 : _m.allowed_values, disabled: ((_o = options === null || options === void 0 ? void 0 : options[optionName]) === null || _o === void 0 ? void 0 : _o.disabled) ||
+                    handleValueChange, key: optionName, arg_schema: (_g = options === null || options === void 0 ? void 0 : options[optionName]) === null || _g === void 0 ? void 0 : _g.arg_schema, noSoft: !!(rest === null || rest === void 0 ? void 0 : rest.options), value: other.value, isFunction: other.is_expression, isDefaultFunction: ((_h = options === null || options === void 0 ? void 0 : options[optionName]) === null || _h === void 0 ? void 0 : _h.default_view) === 'expression', sensitive: (_j = options === null || options === void 0 ? void 0 : options[optionName]) === null || _j === void 0 ? void 0 : _j.sensitive, default_value: (0, common_1.getDefaultValue)(options === null || options === void 0 ? void 0 : options[optionName]), isDefaultTemplate: ((_k = options === null || options === void 0 ? void 0 : options[optionName]) === null || _k === void 0 ? void 0 : _k.default_view) === 'template', allowed_values: (_l = options === null || options === void 0 ? void 0 : options[optionName]) === null || _l === void 0 ? void 0 : _l.allowed_values, disabled: ((_m = options === null || options === void 0 ? void 0 : options[optionName]) === null || _m === void 0 ? void 0 : _m.disabled) ||
                         readOnly ||
-                        !(0, validations_1.hasAllDependenciesFullfilled)((_p = options === null || options === void 0 ? void 0 : options[optionName]) === null || _p === void 0 ? void 0 : _p.depends_on, availableOptions, options || {}), readOnly: readOnly, size: editorSize || rest.size, menuItems: ((_q = options === null || options === void 0 ? void 0 : options[optionName]) === null || _q === void 0 ? void 0 : _q.ui_type) === 'any' ?
+                        !(0, validations_1.hasAllDependenciesFullfilled)((_o = options === null || options === void 0 ? void 0 : options[optionName]) === null || _o === void 0 ? void 0 : _o.depends_on, availableOptions, options || {}), readOnly: readOnly, size: editorSize || rest.size, menuItems: ((_p = options === null || options === void 0 ? void 0 : options[optionName]) === null || _p === void 0 ? void 0 : _p.ui_type) === 'any' ?
                         getCustomMenuTemplateItems(optionName)
                         : undefined }, templateFieldProps)), (0, jsx_runtime_1.jsx)(OptionFieldMessages_1.OptionFieldMessages, { schema: options || {}, allOptions: availableOptions, name: optionName, option: __assign({ type: type }, other), getType: getTypeForOption }), operators && (0, size_1.default)(operators) && (0, size_1.default)(other.op) ?
                     (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreVerticalSpacer, { height: 5 }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreMessage, { size: 'small', children: (0, jsx_runtime_1.jsxs)(reqore_1.ReqoreTagGroup, { children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreTag, { size: 'small', labelKey: 'WHERE', label: optionName }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreTag, { size: 'small', labelKey: 'IS', label: operatorParts.join(' ') }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreTag, { size: 'small', intent: 'info', label: other.value ?
@@ -1187,6 +1298,7 @@ var FormEngine = function (_a) {
     var compactToolbarContextValue = (0, react_2.useMemo)(function () { return ({
         readOnly: readOnly,
         invalidCount: (0, size_1.default)(validityData.invalidFields),
+        attentionCount: readFirstAttentionCount,
         completion: readFirstCompletion,
         showInvalidOnly: showInvalidOptionsOnly,
         onToggleInvalidOnly: handleToggleInvalidOnly,
@@ -1211,6 +1323,7 @@ var FormEngine = function (_a) {
     }); }, [
         readOnly,
         validityData,
+        readFirstAttentionCount,
         readFirstCompletion,
         showInvalidOptionsOnly,
         handleToggleInvalidOnly,
@@ -1265,15 +1378,18 @@ var FormEngine = function (_a) {
                 pushRow(optionName, false);
             }
         });
-        // When searching, also surface matching hidden optional fields (not yet
-        // added) so the search spans the whole schema, not just the visible rows.
-        if (query) {
-            (0, lodash_1.forEach)(filteredOptions, function (_schema, optionName) {
-                if (matchesQuery(optionName)) {
-                    pushRow(optionName, true);
-                }
-            });
-        }
+        // Surface EVERY not-yet-added optional field as an addable (hidden) row, so
+        // the whole schema is browsable inline — they all land in the Optional box
+        // (hidden ⇒ 'optional' bucket) instead of being buried in the Fields menu.
+        // Narrowed by the same filters as the listed rows (search query + required-
+        // only). availableOptions (listed) and filteredOptions (these) are disjoint —
+        // the former is built from fixedValue keys, the latter excludes them — so a
+        // field is never both a listed and a hidden row.
+        (0, lodash_1.forEach)(filteredOptions, function (_schema, optionName) {
+            if (matchesFilters(optionName)) {
+                pushRow(optionName, true);
+            }
+        });
         // User sort (Fields menu → "Sort by"), applied WITHIN each group so the
         // group sections and the required-group rails are preserved. Schema order is
         // the default and the stable tiebreaker (Array.sort is stable, and each
@@ -1317,6 +1433,57 @@ var FormEngine = function (_a) {
                 return 1;
             return groupOrder.indexOf(a) - groupOrder.indexOf(b);
         });
+        var buckets = {
+            attention: {},
+            set: {},
+            optional: {},
+        };
+        var bucketGroups = { attention: [], set: [], optional: [] };
+        // Freeze the box of any field currently being edited (or whose one-of group
+        // has an edited member) to its last settled box — so finishing an edit that
+        // flips its status doesn't remount it in another box and steal focus.
+        var stableBucketOf = function (entry) {
+            var _a;
+            var fresh = getOptionBucket(entry.name, entry.hidden);
+            var groupBeingEdited = !entry.hidden &&
+                (((_a = options === null || options === void 0 ? void 0 : options[entry.name]) === null || _a === void 0 ? void 0 : _a.required_groups) || []).some(function (g) {
+                    return (requiredGroupsInfo.members[g] || []).some(function (m) { return expandedOptions.includes(m); });
+                });
+            if (!entry.hidden && (expandedOptions.includes(entry.name) || groupBeingEdited)) {
+                var memo = settledBucket.current[entry.name];
+                if (memo)
+                    return memo;
+            }
+            settledBucket.current[entry.name] = fresh;
+            return fresh;
+        };
+        groupKeys.forEach(function (groupName) {
+            grouped[groupName].forEach(function (entry) {
+                var b = stableBucketOf(entry);
+                if (!buckets[b][groupName]) {
+                    buckets[b][groupName] = [];
+                    bucketGroups[b].push(groupName);
+                }
+                buckets[b][groupName].push(entry);
+            });
+        });
+        var bucketCount = function (b) {
+            return bucketGroups[b].reduce(function (n, g) { return n + buckets[b][g].length; }, 0);
+        };
+        // 'general' / 'optional' are the SYNTHETIC fallback group keys getOptionGroup
+        // assigns to fields with no explicit `group` — printing a "General"/"Optional"
+        // sub-label for those is just noise, so suppress it. BUT a consumer may also
+        // use 'general' as a REAL group (defining it in the `groups` prop and tagging
+        // fields with `group: 'general'`); in that case it's a named group like any
+        // other and DOES get its sub-label.
+        var showGroupSubLabel = function (groupName) {
+            return (groupName !== 'general' && groupName !== 'optional') || !!(groups === null || groups === void 0 ? void 0 : groups[groupName]);
+        };
+        var STATUS_BOXES = [
+            { key: 'attention', label: 'Needs attention', intent: 'warning', icon: 'ErrorWarningLine' },
+            { key: 'set', label: 'Set', intent: 'success', icon: 'CheckLine' },
+            { key: 'optional', label: 'Optional', icon: 'CheckboxBlankCircleLine' },
+        ];
         // Build the rows for one group: contiguous required-group members are pulled
         // together at the first member's slot and rendered as a connected rail (flat
         // rows — no wrapper — so the value surface applies normally; the rail + nodes
@@ -1331,8 +1498,9 @@ var FormEngine = function (_a) {
                         }
                         : shownOptions[entry.name], hidden: entry.hidden, clustered: clustered, clusterFirst: clusterFirst, clusterLast: clusterLast }, entry.name));
             };
-            if (compactNarrow)
-                return names.map(function (entry) { return renderRow(entry, false); });
+            // (Clustering runs in narrow mode too now — the "One of the below is
+            // required" box wraps the members regardless of width; it no longer relies
+            // on a contiguous rail.)
             var emitted = new Set();
             var groupOf = function (name) { var _a, _b; return (_b = (_a = options === null || options === void 0 ? void 0 : options[name]) === null || _a === void 0 ? void 0 : _a.required_groups) === null || _b === void 0 ? void 0 : _b[0]; };
             return names.map(function (entry) {
@@ -1345,51 +1513,73 @@ var FormEngine = function (_a) {
                 if (memberEntries.length < 2)
                     return renderRow(entry, false);
                 emitted.add(grp);
-                return memberEntries.map(function (e, idx) {
+                var railed = memberEntries.map(function (e, idx) {
                     return renderRow(e, true, idx === 0, idx === memberEntries.length - 1);
                 });
+                // An UNMET one-of group gets the explicit "One of the below is required"
+                // box (the Focus cluster). A met group needs no banner — the rail + the
+                // "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.jsx)(exports.OptionsContext.Provider, { value: { schema: options, value: availableOptions }, children: (0, jsx_runtime_1.jsx)(compactRowContext_1.CompactRowContext.Provider, { value: compactRowContextValue, children: (0, jsx_runtime_1.jsxs)(reqore_1.ReqoreErrorBoundary, { children: [showHelpForOption && ((0, jsx_runtime_1.jsx)(OptionsHelpDialog_1.OptionsHelpDialog, { onClose: function () { return setShowHelpForOption(undefined); }, option: options[showHelpForOption] })), (0, jsx_runtime_1.jsx)(compactToolbarContext_1.CompactToolbarContext.Provider, { value: compactToolbarContextValue, children: (0, jsx_runtime_1.jsxs)(StyledCompactWrap, { ref: setCompactWrap, className: 'options-readfirst-scroll', "$flush": compactFlush, children: [(0, jsx_runtime_1.jsxs)(compactRowStyles_1.StyledCompactPanel, { "$headerBg": headerBg, flat: true, stickyHeader: true, padded: false, actions: compactHeaderActions, contentStyle: {
+        return ((0, jsx_runtime_1.jsx)(exports.OptionsContext.Provider, { value: { schema: options, value: availableOptions }, children: (0, jsx_runtime_1.jsx)(compactRowContext_1.CompactRowContext.Provider, { value: compactRowContextValue, children: (0, jsx_runtime_1.jsxs)(reqore_1.ReqoreErrorBoundary, { children: [showHelpForOption && ((0, jsx_runtime_1.jsx)(OptionsHelpDialog_1.OptionsHelpDialog, { onClose: function () { return setShowHelpForOption(undefined); }, option: options[showHelpForOption] })), (0, jsx_runtime_1.jsx)(compactToolbarContext_1.CompactToolbarContext.Provider, { value: compactToolbarContextValue, children: (0, jsx_runtime_1.jsxs)(StyledCompactWrap, { ref: setCompactWrap, className: 'options-readfirst-scroll', "$flush": compactFlush || compactNested, children: [(0, jsx_runtime_1.jsxs)(compactRowStyles_1.StyledCompactPanel
+                                    // The top-level form scrolls, so its toolbar STICKS and carries a
+                                    // dark blurred backdrop so content ghosts cleanly beneath it. A
+                                    // nested (arg_schema) sub-form owns no scroll context — drop the
+                                    // sticky, the backdrop, and the stacking context so its header is
+                                    // transparent inside the parent's card.
+                                    , { "$headerBg": compactNested ? 'transparent' : headerBg, "$nested": compactNested, flat: true, 
+                                        // No panel background: the form sits transparently on whatever
+                                        // hosts it (page, drawer, or — for an arg_schema field — the
+                                        // parent's edit card) instead of stacking its own dark surface.
+                                        // The status boxes keep their own tints; the sticky toolbar keeps
+                                        // its blurred header via the $headerBg override.
+                                        transparent: true, stickyHeader: !compactNested, padded: false, actions: compactHeaderActions, contentStyle: {
                                             display: 'flex',
                                             flexFlow: 'column',
                                             gap: '10px',
-                                            padding: '0 0 12px',
+                                            // Nested sub-form: no surrounding panel padding (it's flush in
+                                            // the parent card); top-level keeps a small bottom gutter.
+                                            padding: compactNested ? '0' : '0 0 12px',
                                         }, children: [(0, size_1.default)(groupKeys) === 0 ?
                                                 (0, jsx_runtime_1.jsx)(reqore_1.ReqoreMessage, { flat: true, opaque: false, size: 'small', children: "No fields match the current filters." })
-                                                : null, groupKeys.map(function (groupName) {
-                                                var names = grouped[groupName];
-                                                var groupConfig = groups === null || groups === void 0 ? void 0 : groups[groupName];
-                                                var invalidCount = names.filter(function (entry) {
-                                                    var _a, _b, _c;
-                                                    return !entry.hidden &&
-                                                        !isOptionValid(entry.name, ((_a = options === null || options === void 0 ? void 0 : options[entry.name]) === null || _a === void 0 ? void 0 : _a.ui_type) ||
-                                                            ((_b = options === null || options === void 0 ? void 0 : options[entry.name]) === null || _b === void 0 ? void 0 : _b.type), (_c = shownOptions[entry.name]) === null || _c === void 0 ? void 0 : _c.value);
-                                                }).length;
-                                                return ((0, jsx_runtime_1.jsxs)(reqore_1.ReqorePanel, { flat: true, minimal: true, collapseButtonProps: { flat: true, minimal: true, size: 'small' }, collapsible: true, label: (0, jsx_runtime_1.jsxs)(compactRowStyles_1.StyledGroupHeader, { children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreP, { effect: { weight: 'bold' }, size: 'big', children: (0, readFirst_1.getOptionGroupLabel)(groupName, groups) }), (0, jsx_runtime_1.jsx)(compactRowStyles_1.StyledGroupHeaderLine, { "$color": cGroupLine }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreButton, __assign({ readOnly: true, size: 'tiny', minimal: true, flat: true, compact: true, effect: { uppercase: true, spaced: 1 } }, (groupName === 'optional' ? { label: "".concat(names.length, " optional") }
-                                                                : invalidCount ?
-                                                                    {
-                                                                        label: "".concat(invalidCount, " to resolve"),
-                                                                        intent: 'warning',
-                                                                        icon: 'ErrorWarningLine',
-                                                                    }
-                                                                    : {
-                                                                        label: 'All set',
-                                                                        intent: 'success',
-                                                                        icon: 'CheckLine',
-                                                                    })))] }), icon: groupConfig === null || groupConfig === void 0 ? void 0 : groupConfig.icon, className: 'options-readfirst-group', padded: false, contentStyle: { padding: '4px 4px 6px' }, children: [(groupConfig === null || groupConfig === void 0 ? void 0 : groupConfig.subtitle) ?
-                                                            (0, jsx_runtime_1.jsx)(reqore_1.ReqoreP, { size: 'small', effect: { opacity: 0.6 }, 
-                                                                // Indent to the same content line as the rows (StyledGroupBody's
-                                                                // `margin-left` clamp) so the subtitle sits tucked under the group
-                                                                // name instead of at the panel edge — and clears the group's
-                                                                // vertical rule (left:16px) rather than crossing it.
-                                                                style: {
-                                                                    marginTop: 2,
-                                                                    marginBottom: 8,
-                                                                    marginLeft: compactRowStyles_1.GROUP_INDENT,
-                                                                    paddingRight: 10,
-                                                                }, children: groupConfig.subtitle })
-                                                            : null, (0, jsx_runtime_1.jsx)(compactRowStyles_1.StyledGroupBody, { "$divider": cDivider, "$hover": cHover, "$focus": cWarning, "$success": cSuccess, "$rowBg": cRowBg, "$lineColor": cGroupLine, className: compactNarrow ? 'readfirst-narrow' : undefined, children: renderGroupRows(names) })] }, groupName));
+                                                : null, STATUS_BOXES.map(function (box) {
+                                                var groupsInBox = bucketGroups[box.key];
+                                                var count = bucketCount(box.key);
+                                                if (!count)
+                                                    return null;
+                                                var accent = box.key === 'attention' ? cWarning
+                                                    : box.key === 'set' ? cSuccess
+                                                        : cMuted;
+                                                // The muted "Optional" box reads as a quieter, recessed
+                                                // surface — a touch darker than the page rather than the
+                                                // faint grey tint the accent would give.
+                                                var boxBg = box.key === 'optional' ?
+                                                    (0, colors_1.changeDarkness)((0, colors_1.getMainBackgroundColor)(theme), 0.06)
+                                                    : undefined;
+                                                return ((0, jsx_runtime_1.jsx)(compactRowStyles_1.StyledStatusBox, { "$accent": accent, "$bg": boxBg, flat: true, minimal: true, collapseButtonProps: { flat: true, minimal: true, size: 'small' }, collapsible: true, 
+                                                    // The Optional box now holds every not-yet-added field, so
+                                                    // it starts COLLAPSED to keep the form focused on what's in
+                                                    // use. But a SEARCH must surface matching addable fields —
+                                                    // and ReqorePanel unmounts collapsed content — so force it
+                                                    // open whenever a query is active. (isCollapsed is the
+                                                    // panel's controllable state; manual toggling still works
+                                                    // when no query is set.)
+                                                    isCollapsed: box.key === 'optional' && !query, label: (0, jsx_runtime_1.jsxs)(compactRowStyles_1.StyledGroupHeader, { children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreP, { effect: { weight: 'bold' }, size: 'normal', children: box.label }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreTag, { size: 'small', minimal: true, compact: true, intent: box.intent, label: String(count) })] }), icon: box.icon, className: 'options-readfirst-group', padded: false, contentStyle: { padding: '4px 4px 6px' }, children: (0, jsx_runtime_1.jsx)(compactRowStyles_1.StyledGroupBody, { "$divider": cDivider, "$hover": cHover, "$focus": cWarning, "$success": cSuccess, "$rowBg": cRowBg, "$lineColor": cGroupLine, className: compactNarrow ? 'readfirst-narrow' : undefined, children: groupsInBox.map(function (groupName) {
+                                                            var groupConfig = groups === null || groups === void 0 ? void 0 : groups[groupName];
+                                                            return ((0, jsx_runtime_1.jsxs)(react_2.default.Fragment, { children: [showGroupSubLabel(groupName) ?
+                                                                        (0, jsx_runtime_1.jsx)(compactRowStyles_1.StyledStatusBoxGroupLabel, { children: (0, readFirst_1.getOptionGroupLabel)(groupName, groups) })
+                                                                        : null, showGroupSubLabel(groupName) && (groupConfig === null || groupConfig === void 0 ? void 0 : groupConfig.subtitle) ?
+                                                                        (0, jsx_runtime_1.jsx)(reqore_1.ReqoreP, { size: 'small', effect: { opacity: 0.6 }, style: {
+                                                                                marginTop: 2,
+                                                                                marginBottom: 8,
+                                                                                marginLeft: compactRowStyles_1.GROUP_INDENT,
+                                                                                paddingRight: 10,
+                                                                            }, children: groupConfig.subtitle })
+                                                                        : null, renderGroupRows(buckets[box.key][groupName])] }, groupName));
+                                                        }) }) }, 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 ?
                                                             'Apply the staged changes'