@qoretechnologies/reqraft 0.10.65 → 0.10.66-pr.145.g124fc92

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

@@ -107,6 +107,7 @@ var typeChoices_1 = require("./typeChoices");
 var optionActions_1 = require("./optionActions");
 var rendererTypes_1 = require("./rendererTypes");
 var revealRow_1 = require("./revealRow");
+var rowFocus_1 = require("./rowFocus");
 var emittedValues_1 = require("../fields/emittedValues");
 var lodash_1 = require("lodash");
 var map_1 = __importDefault(require("lodash/map"));
@@ -115,6 +116,8 @@ var size_1 = __importDefault(require("lodash/size"));
 var react_2 = __importStar(require("react"));
 var react_use_1 = require("react-use");
 var styled_components_1 = __importStar(require("styled-components"));
+var allowedValues_1 = require("../../../helpers/allowedValues");
+var fieldDescription_1 = require("../../../helpers/fieldDescription");
 var common_1 = require("../../../helpers/common");
 var options_1 = require("../../../helpers/options");
 var validations_1 = require("../../../helpers/validations");
@@ -136,6 +139,7 @@ var OptionFieldMessages_1 = require("./OptionFieldMessages");
 var optionsContext_1 = require("./optionsContext");
 var markdownRendererContext_1 = require("../../Description/markdownRendererContext");
 var OptionsHelpDialog_1 = require("./OptionsHelpDialog");
+var formAppearance_1 = require("./formAppearance");
 var optionUiTypes_1 = require("../../../helpers/optionUiTypes");
 var readFirst_1 = require("./readFirst");
 /**
@@ -521,25 +525,28 @@ var FormEngineImpl = function (_a) {
     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, onReadOnlyActivate = _a.onReadOnlyActivate, _h = _a.allowTemplates, allowTemplates = _h === void 0 ? true : _h, interfaceContext = _a.interfaceContext, templateFieldProps = _a.templateFieldProps, forceDropdown = _a.forceDropdown, _j = _a.showTypeToggle, showTypeToggle = _j === void 0 ? true : _j, compact = _a.compact, 
+    // Read through the context `FormEngine` provides (resolved there against an
+    // inherited appearance); destructured only to keep it out of `rest`.
+    _appearance = _a.appearance, // eslint-disable-line @typescript-eslint/no-unused-vars
     // Destructured only to keep it out of `rest` (and so off the DOM). The gutter
     // this prop documents was never implemented: it was passed to the wrap as
     // `$flush`, whose styled template had no interpolation slot, so it has always
     // 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
-    _k = _a.compactFlush, 
+    _k = _a.compactFlush, // eslint-disable-line @typescript-eslint/no-unused-vars
     // Destructured only to keep it out of `rest` (and so off the DOM). The gutter
     // this prop documents was never implemented: it was passed to the wrap as
     // `$flush`, whose styled template had no interpolation slot, so it has always
     // 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.revealRequired, revealRequired = _o === void 0 ? false : _o, focusAttentionRequest = _a.focusAttentionRequest, onAttentionChange = _a.onAttentionChange, _p = _a.compactStickyBoxHeaders, compactStickyBoxHeaders = _p === void 0 ? true : _p, _q = _a.compactStickyOffset, compactStickyOffset = _q === void 0 ? 0 : _q, _r = _a.compactToolbar, compactToolbar = _r === void 0 ? true : _r, _s = _a.commitMode, commitMode = _s === void 0 ? 'immediate' : _s, _t = _a.expandMode, expandMode = _t === void 0 ? 'single' : _t, onCommit = _a.onCommit, operatorsProp = _a.operators, groups = _a.groups, optionsLoader = _a.optionsLoader, onValidityChange = _a.onValidityChange, optionActions = _a.optionActions, _u = _a.optionActionsCollapse, optionActionsCollapse = _u === void 0 ? 'auto' : _u, componentOverrides = _a.componentOverrides, codePreviewRenderer = _a.codePreviewRenderer, 
     // 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, 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", "appearance", "compactFlush", "compactNested", "compactScroll", "compactPanelProps", "compactCollapsedGroups", "compactBoxLabels", "revealRequired", "focusAttentionRequest", "onAttentionChange", "compactStickyBoxHeaders", "compactStickyOffset", "compactToolbar", "commitMode", "expandMode", "onCommit", "operators", "groups", "optionsLoader", "onValidityChange", "optionActions", "optionActionsCollapse", "componentOverrides", "codePreviewRenderer", "markdownRenderer", "rendererOnlyUiTypes", "templateAwareUiTypes", "anyLikeUiTypes", "inheritedFromParent", "autoFocusFirstRequired", "expandFirstRequired", "initialExpandedOptions", "maxFieldsShown"]);
     // 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,34 +571,50 @@ 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 _v = (0, react_2.useState)((rest === null || rest === void 0 ? void 0 : rest.options) || undefined), servedOptions = _v[0], setOptions = _v[1];
     var options = (0, react_2.useMemo)(function () { return (0, options_1.resolveDegenerateRequiredGroups)(servedOptions); }, [servedOptions]);
     // 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 _w = (0, react_2.useState)(), optionsError = _w[0], setOptionsError = _w[1];
+    var _w = (0, react_2.useState)(!!optionsLoader && !(rest === null || rest === void 0 ? void 0 : rest.options)), optionsLoading = _w[0], setOptionsLoading = _w[1];
+    var _x = (0, react_2.useState)(), optionsError = _x[0], setOptionsError = _x[1];
     // Operators: prop-provided (compact) or fetched via operatorsUrl (dpql,
     // ported from IDE Options) — the fetch overrides the seeded prop value.
-    var _x = (0, react_2.useState)(operatorsProp), operators = _x[0], setOperators = _x[1];
+    var _y = (0, react_2.useState)(operatorsProp), operators = _y[0], setOperators = _y[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 _y = (0, react_2.useState)(!!(url || customUrl || operatorsUrl)), loading = _y[0], setLoading = _y[1];
+    var _z = (0, react_2.useState)(!!(url || customUrl || operatorsUrl)), loading = _z[0], setLoading = _z[1];
     var confirmAction = (0, reqore_1.useReqoreProperty)('confirmAction');
     var theme = (0, reqore_1.useReqoreTheme)();
-    var _z = (0, react_2.useState)(), focusedEditing = _z[0], setFocusedEditing = _z[1];
-    var _0 = (0, react_2.useState)(false), showFieldTypes = _0[0], setShowFieldTypes = _0[1];
+    var calm = (0, formAppearance_1.useIsCalmForm)();
+    var _0 = (0, react_2.useState)(), focusedEditing = _0[0], setFocusedEditing = _0[1];
+    var _1 = (0, react_2.useState)(false), showFieldTypes = _1[0], setShowFieldTypes = _1[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 _1 = (0, react_2.useState)(undefined), showAllDescriptions = _1[0], setShowAllDescriptions = _1[1];
-    var _2 = (0, react_2.useState)(), showHelpForOption = _2[0], setShowHelpForOption = _2[1];
-    var _3 = (0, react_2.useState)(false), showInvalidOptionsOnly = _3[0], setShowInvalidOptionsOnly = _3[1];
+    var _2 = (0, react_2.useState)(undefined), showAllDescriptions = _2[0], setShowAllDescriptions = _2[1];
+    var _3 = (0, react_2.useState)(), showHelpForOption = _3[0], setShowHelpForOption = _3[1];
+    var _4 = (0, react_2.useState)(false), showInvalidOptionsOnly = _4[0], setShowInvalidOptionsOnly = _4[1];
     // Which options are expanded into their editor (several can be open at once).
-    var _4 = (0, react_2.useState)([]), expandedOptions = _4[0], setExpandedOptions = _4[1];
+    var _5 = (0, react_2.useState)([]), expandedOptions = _5[0], setExpandedOptions = _5[1];
+    // The fields the person has opened and left. An empty required field becomes a
+    // fault only then (or after a submit attempt, `revealRequired`): a form nobody has
+    // touched is not already wrong.
+    var _6 = (0, react_2.useState)([]), visitedOptions = _6[0], setVisitedOptions = _6[1];
+    var lastExpandedOptions = (0, react_2.useRef)([]);
+    (0, react_2.useEffect)(function () {
+        var left = lastExpandedOptions.current.filter(function (name) { return !expandedOptions.includes(name); });
+        lastExpandedOptions.current = expandedOptions;
+        if (left.length) {
+            setVisitedOptions(function (prev) {
+                var added = left.filter(function (name) { return !prev.includes(name); });
+                return added.length ? __spreadArray(__spreadArray([], prev, true), added, true) : prev;
+            });
+        }
+    }, [expandedOptions]);
     /** Status boxes whose "N more fields" control the reader has opened. Keyed by
         box so opening Optional does not also unfold Set. */
-    var _5 = (0, react_2.useState)([]), expandedMoreBoxes = _5[0], setExpandedMoreBoxes = _5[1];
+    var _7 = (0, react_2.useState)([]), expandedMoreBoxes = _7[0], setExpandedMoreBoxes = _7[1];
     // --- Reveal a status box's content when it is opened ----------------------
     //
     // The status boxes stack, so the last one ("Optional", which holds every
@@ -607,7 +630,7 @@ var FormEngineImpl = function (_a) {
     // box has not grown and there is nothing to scroll to. A layout effect runs
     // after the DOM is updated and before paint, which makes the reveal
     // deterministic instead of a guessed delay.
-    var _6 = (0, react_2.useState)(undefined), openedStatusBox = _6[0], setOpenedStatusBox = _6[1];
+    var _8 = (0, react_2.useState)(undefined), openedStatusBox = _8[0], setOpenedStatusBox = _8[1];
     var statusBoxRefs = (0, react_2.useRef)({});
     (0, react_2.useLayoutEffect)(function () {
         var _a, _b;
@@ -638,13 +661,13 @@ var FormEngineImpl = function (_a) {
     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 _7 = (0, react_use_1.useMeasure)(), compactWrapRef = _7[0], compactWrapWidth = _7[1].width;
+    var _9 = (0, react_use_1.useMeasure)(), compactWrapRef = _9[0], compactWrapWidth = _9[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 _8 = (0, react_2.useState)(null), compactWrapNode = _8[0], setCompactWrapNode = _8[1];
+    var _10 = (0, react_2.useState)(null), compactWrapNode = _10[0], setCompactWrapNode = _10[1];
     // Ref mirror of the wrap node for callbacks that must not re-create when it
     // mounts (flashOptions reads it inside a rAF).
     var compactWrapNodeRef = (0, react_2.useRef)(null);
@@ -672,7 +695,7 @@ var FormEngineImpl = function (_a) {
        a search row and a field picker that each hide themselves when they have
        nothing to say, and what is left wraps differently at every form width.
        Zero when this form draws no toolbar at all. */
-    var _9 = (0, react_2.useState)(0), compactToolbarHeight = _9[0], setCompactToolbarHeight = _9[1];
+    var _11 = (0, react_2.useState)(0), compactToolbarHeight = _11[0], setCompactToolbarHeight = _11[1];
     (0, react_2.useLayoutEffect)(function () {
         var wrap = compactWrapNode;
         if (!compact || !wrap || compactNested || !compactStickyBoxHeaders) {
@@ -757,8 +780,8 @@ var FormEngineImpl = 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 _10 = (0, react_2.useState)([]), highlightedOptions = _10[0], setHighlightedOptions = _10[1];
-    var _11 = (0, react_2.useState)([]), flashedOptions = _11[0], setFlashedOptions = _11[1];
+    var _12 = (0, react_2.useState)([]), highlightedOptions = _12[0], setHighlightedOptions = _12[1];
+    var _13 = (0, react_2.useState)([]), flashedOptions = _13[0], setFlashedOptions = _13[1];
     var flashTimeout = (0, react_2.useRef)();
     var flashOptions = (0, react_2.useCallback)(function (optionNames, scrollToFirst) {
         if (scrollToFirst === void 0) { scrollToFirst = false; }
@@ -810,16 +833,16 @@ var FormEngineImpl = function (_a) {
         }
     });
     // Info panels auto-open on Tier-1 content; the per-row user override sticks.
-    var _12 = (0, react_2.useState)({}), infoPanelOverrides = _12[0], setInfoPanelOverrides = _12[1];
+    var _14 = (0, react_2.useState)({}), infoPanelOverrides = _14[0], setInfoPanelOverrides = _14[1];
     // Toolbar filters affect the listed rows only — the meter reflects the full set.
-    var _13 = (0, react_2.useState)(false), requiredOnly = _13[0], setRequiredOnly = _13[1];
-    var _14 = (0, react_2.useState)(''), compactQuery = _14[0], setCompactQuery = _14[1];
+    var _15 = (0, react_2.useState)(false), requiredOnly = _15[0], setRequiredOnly = _15[1];
+    var _16 = (0, react_2.useState)(''), compactQuery = _16[0], setCompactQuery = _16[1];
     // Compact field sort (Fields menu → "Sort by"); 'schema' = declared order.
-    var _15 = (0, react_2.useState)('schema'), compactSort = _15[0], setCompactSort = _15[1];
-    var _16 = (0, react_2.useState)(function () { return ({
+    var _17 = (0, react_2.useState)('schema'), compactSort = _17[0], setCompactSort = _17[1];
+    var _18 = (0, react_2.useState)(function () { return ({
         fields: (0, exports.fixOptions)(value, options || {}, undefined, isRendererOnly),
         meta: undefined,
-    }); }), localValue = _16[0], setLocalValue = _16[1];
+    }); }), localValue = _18[0], setLocalValue = _18[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)
@@ -864,7 +887,7 @@ var FormEngineImpl = function (_a) {
         originalValue.current = localValue.fields;
     }
     var unavailableOptionsCount = (0, react_2.useRef)(0);
-    var _17 = (0, useQorusTypes_1.useQorusTypes)(), compactValue = _17.compactValue, typesLoading = _17.loading;
+    var _19 = (0, useQorusTypes_1.useQorusTypes)(), compactValue = _19.compactValue, typesLoading = _19.loading;
     var templates = (0, useTemplates_1.useTemplates)(allowTemplates, rest.stringTemplates, interfaceContext);
     (0, react_2.useEffect)(function () {
         if (!(0, exports.shouldEmitLocalValue)({
@@ -1383,9 +1406,8 @@ var FormEngineImpl = function (_a) {
         var locked = [];
         (0, lodash_1.forEach)(options || {}, function (optionSchema, name) {
             (0, lodash_1.forEach)((optionSchema === null || optionSchema === void 0 ? void 0 : optionSchema.allowed_values) || [], function (allowedValue) {
-                var _a;
                 if (!(0, OptionFieldMessages_1.getAllowedValueAvailability)(allowedValue, availableOptions, options || {}).available) {
-                    locked.push("".concat(name, "\0").concat(JSON.stringify((_a = allowedValue === null || allowedValue === void 0 ? void 0 : allowedValue.value) === null || _a === void 0 ? void 0 : _a.value)));
+                    locked.push("".concat(name, "\0").concat(JSON.stringify((0, allowedValues_1.allowedValueOf)(allowedValue))));
                 }
             });
         });
@@ -1523,6 +1545,11 @@ var FormEngineImpl = function (_a) {
         return (0, reduce_1.default)(availableOptions, function (newValue, option, optionName) {
             var _a;
             if (showInvalidOptionsOnly &&
+                // An open row stays while the reader is in it, as its box does
+                // (`stableBucketOf`): the first character typed into an empty required
+                // field makes it valid, and hiding it then would pull the field out
+                // from under the caret mid-word.
+                !expandedOptions.includes(optionName) &&
                 isOptionValid(optionName, (0, exports.getOptionFieldStorageType)(optionName, option.type, options, operators, option.op, isRendererOnly, optionHoldsExpression(option)), option.value)) {
                 return newValue;
             }
@@ -1530,6 +1557,7 @@ var FormEngineImpl = function (_a) {
         }, {});
     }, [
         showInvalidOptionsOnly,
+        expandedOptions,
         isRendererOnly,
         JSON.stringify(availableOptions),
         JSON.stringify(options),
@@ -1585,8 +1613,11 @@ var FormEngineImpl = function (_a) {
             covered: covered,
             invalid: invalid,
             warned: msgIntent === 'warning',
+            visited: revealRequired || visitedOptions.includes(name),
         });
     }, [
+        revealRequired,
+        visitedOptions,
         isRendererOnly,
         JSON.stringify(options),
         JSON.stringify(availableOptions),
@@ -1615,6 +1646,21 @@ var FormEngineImpl = function (_a) {
         return Object.keys(availableOptions || {}).filter(function (name) { return getOptionBucket(name) === 'attention'; })
             .length;
     }, [JSON.stringify(availableOptions), getOptionBucket]);
+    // How many of those are faults rather than only still to fill in (`pending`). Zero
+    // on a new form, so its first box reads "To fill in" without amber.
+    var readFirstAttentionFaultCount = (0, react_2.useMemo)(function () {
+        return Object.keys(availableOptions || {}).filter(function (name) { return getOptionBucket(name) === 'attention' && getOptionStatus(name) !== 'pending'; }).length;
+    }, [JSON.stringify(availableOptions), getOptionBucket, getOptionStatus]);
+    // The same two numbers, to a host that draws its own submit control from them.
+    var onAttentionChangeRef = (0, react_2.useRef)(onAttentionChange);
+    onAttentionChangeRef.current = onAttentionChange;
+    (0, react_2.useEffect)(function () {
+        var _a;
+        (_a = onAttentionChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onAttentionChangeRef, {
+            count: readFirstAttentionCount,
+            faults: readFirstAttentionFaultCount,
+        });
+    }, [readFirstAttentionCount, readFirstAttentionFaultCount]);
     var getIntent = (0, react_2.useCallback)(
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     function (optName, type, optValue, _op) {
@@ -1717,6 +1763,31 @@ 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.
+    // What the "first field to fix" scans read: the opener on arrival below and the
+    // caret move on a submit attempt (`focusAttentionRequest`) pick the same field.
+    var getAttentionFieldMeta = (0, react_2.useCallback)(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',
+        };
+    }, [options, readOnly, dependencyLockedNames, getOptionBucket]);
+    // Opening a row by name: `expandMode: 'single'` replaces only what a click could
+    // (see the note in the opener below), never a row the host named.
+    var openOption = (0, react_2.useCallback)(function (target) {
+        return setExpandedOptions(function (prev) {
+            return prev.includes(target) ? prev
+                : expandMode === 'multi' ? __spreadArray(__spreadArray([], prev, true), [target], false) : __spreadArray(__spreadArray([], prev.filter(function (name) { return initialExpandedOptions === null || initialExpandedOptions === void 0 ? void 0 : initialExpandedOptions.includes(name); }), true), [target], false);
+        });
+    }, [expandMode, initialExpandedOptions]);
     var hasAutoFocusedRef = (0, react_2.useRef)(false);
     (0, react_2.useEffect)(function () {
         // Two decisions, one scan. Both open the row that needs attention;
@@ -1752,37 +1823,19 @@ 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',
-            };
-        });
+        var target = (0, readFirst_1.getFirstAttentionOptionName)(orderedNames, getAttentionFieldMeta);
         // 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);
-            });
+            // `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. `openOption` keeps
+            // the named rows and replaces only what a click could.
+            openOption(target);
         }
     }, [
         autoFocusFirstRequired,
@@ -1790,12 +1843,48 @@ var FormEngineImpl = function (_a) {
         compact,
         options,
         availableOptions,
-        readOnly,
-        dependencyLockedNames,
-        getOptionBucket,
-        expandMode,
-        initialExpandedOptions,
+        getAttentionFieldMeta,
+        openOption,
     ]);
+    // A submit that could not go is answered with where to type: each new
+    // `focusAttentionRequest` opens the first field that needs attention and puts the
+    // caret in it. The host's submit button holds the caret at that moment, and an open
+    // row never takes a caret held outside it (CompactRow), so the button lets go of it
+    // here first; the person asked to submit, and this is the answer to that.
+    var lastFocusRequest = (0, react_2.useRef)(focusAttentionRequest);
+    (0, react_2.useEffect)(function () {
+        var _a;
+        if (focusAttentionRequest === lastFocusRequest.current) {
+            return;
+        }
+        lastFocusRequest.current = focusAttentionRequest;
+        if (!focusAttentionRequest || !compact || !options) {
+            return;
+        }
+        var target = (0, readFirst_1.getFirstAttentionOptionName)(Object.keys(availableOptions), getAttentionFieldMeta);
+        if (!target) {
+            return;
+        }
+        var wrap = compactWrapNodeRef.current;
+        var active = document.activeElement;
+        if (active && active !== document.body && !(wrap === null || wrap === void 0 ? void 0 : wrap.contains(active))) {
+            active.blur();
+        }
+        if (!expandedOptions.includes(target)) {
+            // The row's own open effect reveals it and takes the caret.
+            openOption(target);
+            return;
+        }
+        // Already open (the field the form opened on arrival): its open effect has run,
+        // so the caret goes to its control here.
+        var row = wrap === null || wrap === void 0 ? void 0 : wrap.querySelector("[data-field=\"".concat(target, "\"]"));
+        if (row) {
+            (0, revealRow_1.revealRow)(row, 'auto');
+            (_a = (0, rowFocus_1.findRowFocusTarget)(row.querySelector('.options-readfirst-row-editor'), {
+                textEntryOnly: row.classList.contains('options-readfirst-card'),
+            })) === null || _a === void 0 ? void 0 : _a.focus({ preventScroll: true });
+        }
+    }, [focusAttentionRequest]);
     // 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 () {
@@ -2042,7 +2131,10 @@ var FormEngineImpl = function (_a) {
                         readOnly ||
                         !(0, validations_1.hasAllDependenciesFullfilled)((_v = options === null || options === void 0 ? void 0 : options[optionName]) === null || _v === void 0 ? void 0 : _v.depends_on, availableOptions, options || {}), readOnly: readOnly, size: editorSize || rest.size, menuItems: (0, typeChoices_1.offersTypeChoices)(options === null || options === void 0 ? void 0 : options[optionName], anyLikeUiTypes) ?
                         getCustomMenuTemplateItems(optionName)
-                        : undefined }, templateFieldProps, { forceDropdown: effectiveForceDropdown })), (0, jsx_runtime_1.jsx)(OptionFieldMessages_1.OptionFieldMessages, { schema: options || {}, allOptions: availableOptions, name: optionName, option: __assign({ type: resolvedType }, other), getType: getTypeForOption, isRendererOnly: isRendererOnly }), operators && (0, size_1.default)(operators) && (0, size_1.default)(other.op) ?
+                        : undefined }, templateFieldProps, { forceDropdown: effectiveForceDropdown })), (0, jsx_runtime_1.jsx)(OptionFieldMessages_1.OptionFieldMessages, { schema: options || {}, allOptions: availableOptions, name: optionName, option: __assign({ type: resolvedType }, other), getType: getTypeForOption, isRendererOnly: isRendererOnly, 
+                    // Open is not left: a field the form opened for typing (the first empty
+                    // one, on a new form) says what it needs without already being wrong.
+                    requirementPending: !(revealRequired || visitedOptions.includes(optionName)) }), 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 ?
                                                 resolvedType === 'richtext' ?
                                                     (0, common_1.richtextToString)(other.value)
@@ -2074,6 +2166,8 @@ var FormEngineImpl = function (_a) {
         getTypeForOption,
         inheritedScopes,
         inheritedFromParent,
+        revealRequired,
+        visitedOptions,
     ]);
     // Compact (read-first) rendering.
     // Theme-derived colours so the flat-row layout adapts to light/dark/custom themes.
@@ -2096,6 +2190,10 @@ var FormEngineImpl = function (_a) {
     // The "N more fields" row's dashed edge. Well above the divider tint: this
     // one is an affordance the reader has to notice, not a hairline between rows.
     var cMoreBorder = "".concat(cText, "4d");
+    // Calm: the section surface and its hairline, from the theme's panel (the
+    // same surface and edge Reqore gives the section panels themselves).
+    var cPanel = (0, formAppearance_1.getCalmPanelSurface)(theme);
+    var cHairline = (0, formAppearance_1.getCalmPanelHairline)(theme);
     // 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.
@@ -2112,6 +2210,8 @@ var FormEngineImpl = function (_a) {
         codePreviewRenderer: codePreviewRenderer,
         showAllDescriptions: showAllDescriptions,
         expandedOptions: expandedOptions,
+        visitedOptions: visitedOptions,
+        revealRequired: revealRequired,
         highlightedOptions: highlightedOptions,
         flashedOptions: flashedOptions,
         infoPanelOverrides: infoPanelOverrides,
@@ -2159,6 +2259,8 @@ var FormEngineImpl = function (_a) {
         codePreviewRenderer,
         showAllDescriptions,
         expandedOptions,
+        visitedOptions,
+        revealRequired,
         highlightedOptions,
         flashedOptions,
         infoPanelOverrides,
@@ -2207,6 +2309,7 @@ var FormEngineImpl = function (_a) {
         readOnly: readOnly,
         invalidCount: (0, size_1.default)(validityData.invalidFields),
         attentionCount: readFirstAttentionCount,
+        attentionFaultCount: readFirstAttentionFaultCount,
         completion: readFirstCompletion,
         showInvalidOnly: showInvalidOptionsOnly,
         onToggleInvalidOnly: handleToggleInvalidOnly,
@@ -2253,6 +2356,7 @@ var FormEngineImpl = function (_a) {
         onReadOnlyActivate,
         validityData,
         readFirstAttentionCount,
+        readFirstAttentionFaultCount,
         readFirstCompletion,
         showInvalidOptionsOnly,
         handleToggleInvalidOnly,
@@ -2282,7 +2386,7 @@ var FormEngineImpl = function (_a) {
     // removes it, and then the header carries just the consumer's own actions.
     var compactHeaderActions = (0, react_2.useMemo)(function () { return __spreadArray(__spreadArray([], (compactToolbarParts ? [{ as: CompactToolbar_1.CompactToolbar, responsive: false }] : []), true), ((compactPanelProps === null || compactPanelProps === void 0 ? void 0 : compactPanelProps.actions) || []), true); }, [compactPanelProps === null || compactPanelProps === void 0 ? void 0 : compactPanelProps.actions, compactToolbarParts]);
     var renderCompact = function () {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _f;
         var headerBg = "".concat((0, colors_1.changeDarkness)((0, colors_1.getMainBackgroundColor)(theme), 0.02)).concat((0, colors_1.percentToHexAlpha)(88));
         // Toolbar filters narrow the listed rows; the meter reflects the full set.
         var query = compactQuery.trim().toLowerCase();
@@ -2512,16 +2616,24 @@ var FormEngineImpl = function (_a) {
         var stickyBoxHeaders = compactStickyBoxHeaders && !compactNested;
         var boxStickyOffset = compactStickyOffset + compactToolbarHeight;
         var STATUS_BOXES = [
-            {
-                key: 'attention',
-                label: (_a = compactBoxLabels === null || compactBoxLabels === void 0 ? void 0 : compactBoxLabels.attention) !== null && _a !== void 0 ? _a : 'Needs attention',
-                intent: 'warning',
-                icon: 'ErrorWarningLine',
-            },
-            { key: 'set', label: (_b = compactBoxLabels === null || compactBoxLabels === void 0 ? void 0 : compactBoxLabels.set) !== null && _b !== void 0 ? _b : 'Set', intent: 'success', icon: 'CheckLine' },
+            // The first box is amber only once something in it is a fault. On a new form it
+            // holds the required fields still to fill in, which is not yet anything wrong.
+            readFirstAttentionFaultCount ?
+                {
+                    key: 'attention',
+                    label: (_a = compactBoxLabels === null || compactBoxLabels === void 0 ? void 0 : compactBoxLabels.attention) !== null && _a !== void 0 ? _a : 'Needs attention',
+                    intent: 'warning',
+                    icon: 'ErrorWarningLine',
+                }
+                : {
+                    key: 'attention',
+                    label: (_b = compactBoxLabels === null || compactBoxLabels === void 0 ? void 0 : compactBoxLabels.pending) !== null && _b !== void 0 ? _b : 'To fill in',
+                    icon: 'CheckboxBlankCircleLine',
+                },
+            { key: 'set', label: (_c = compactBoxLabels === null || compactBoxLabels === void 0 ? void 0 : compactBoxLabels.set) !== null && _c !== void 0 ? _c : 'Set', intent: 'success', icon: 'CheckLine' },
             {
                 key: 'optional',
-                label: (_c = compactBoxLabels === null || compactBoxLabels === void 0 ? void 0 : compactBoxLabels.optional) !== null && _c !== void 0 ? _c : 'Optional',
+                label: (_d = compactBoxLabels === null || compactBoxLabels === void 0 ? void 0 : compactBoxLabels.optional) !== null && _d !== void 0 ? _d : 'Optional',
                 icon: 'CheckboxBlankCircleLine',
             },
         ];
@@ -2571,7 +2683,10 @@ 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));
+                // Amber once someone has been to the group (or a submit was attempted); until
+                // then it is still to fill in, in the quiet colour, like its members.
+                var clusterColor = memberEntries.some(function (e) { return getOptionStatus(e.name) !== 'pending'; }) ? cWarning : cMuted;
+                return ((0, jsx_runtime_1.jsxs)(compactRowStyles_1.StyledRequiredClusterBox, { className: 'options-readfirst-required-cluster', "$border": "".concat(clusterColor, "33"), "$tint": "".concat(clusterColor, "0d"), "$calm": calm, children: [(0, jsx_runtime_1.jsxs)(compactRowStyles_1.StyledRequiredClusterHeader, { className: 'options-readfirst-required-cluster-header', "$color": clusterColor, "$calm": calm, children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreIcon, { icon: 'LinkM', size: calm ? '13px' : '11px', style: { color: clusterColor } }), "One of the below is required"] }), railed] }, grp));
             });
         };
         // One schema group inside a status box: its thin sub-label, the group's
@@ -2590,14 +2705,18 @@ var FormEngineImpl = function (_a) {
                 return null;
             }
             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) })
+                        (0, jsx_runtime_1.jsx)(compactRowStyles_1.StyledStatusBoxGroupLabel, { className: 'options-readfirst-group-label', "$calm": calm, "$color": cKey, 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 })
+                        (0, jsx_runtime_1.jsx)(reqore_1.ReqoreP, { className: 'options-readfirst-group-subtitle', size: 'small', effect: { opacity: 0.6 }, style: calm ?
+                                // Under the calm heading, at the rows' inset; the space below
+                                // it is the next row's own padding.
+                                { margin: 0, padding: "2px ".concat(compactRowStyles_1.CALM_SECTION_INSET, "px 4px") }
+                                : {
+                                    marginTop: 2,
+                                    marginBottom: 8,
+                                    marginLeft: compactRowStyles_1.GROUP_INDENT,
+                                    paddingRight: 10,
+                                }, children: groupConfig.subtitle })
                         : null, renderGroupRows(rows)] }, groupName));
         };
         return ((0, jsx_runtime_1.jsx)(optionsContext_1.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', "$ownScroll": compactScroll === 'own' && !compactNested, children: [(0, jsx_runtime_1.jsxs)(compactRowStyles_1.StyledCompactPanel
@@ -2607,7 +2726,14 @@ var FormEngineImpl = function (_a) {
                                     , __assign({ "$tightHeader": !((compactToolbarParts === null || compactToolbarParts === void 0 ? void 0 : compactToolbarParts.search) && (0, size_1.default)(options) > 1), "$headerBg": compactNested ? 'transparent' : headerBg, "$nested": compactNested, "$stickyBoxes": compactStickyBoxHeaders && !compactNested, "$stackHeader": compactNarrow &&
                                             !!((compactPanelProps === null || compactPanelProps === void 0 ? void 0 : compactPanelProps.label) ||
                                                 (compactPanelProps === null || compactPanelProps === void 0 ? void 0 : compactPanelProps.icon) ||
-                                                ((_d = compactPanelProps === null || compactPanelProps === void 0 ? void 0 : compactPanelProps.actions) === null || _d === void 0 ? void 0 : _d.length)), flat: true, raised: true, minimal: true, 
+                                                ((_f = compactPanelProps === null || compactPanelProps === void 0 ? void 0 : compactPanelProps.actions) === null || _f === void 0 ? void 0 : _f.length)), flat: true, 
+                                        // Calm: no surface and no lift at all. A theme that gives
+                                        // panels a surface of their own (Reqore's `theme.panel`) would
+                                        // otherwise paint this wrapper as a card around the section
+                                        // cards inside it. Transparent and un-raised, Reqore also drops
+                                        // the wrapper's horizontal padding, so the readiness line, the
+                                        // search and the sections share one left edge with the host.
+                                        raised: !calm, minimal: true, transparent: calm || undefined, 
                                         // 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.
@@ -2661,7 +2787,7 @@ var FormEngineImpl = function (_a) {
                                                         : 'No fields match the current filters.' })
                                                 : null, readOnly ?
                                                 bucketCount('set') ?
-                                                    (0, jsx_runtime_1.jsx)("div", { className: 'options-readfirst-read', style: { 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, "$moreBorder": cMoreBorder, className: compactNarrow ? 'readfirst-narrow' : undefined, children: bucketGroups.set.map(function (groupName) { return renderBoxGroup('set', groupName); }) }) })
+                                                    (0, jsx_runtime_1.jsx)("div", { className: 'options-readfirst-read', style: { padding: calm ? 0 : '4px 4px 6px' }, children: (0, jsx_runtime_1.jsx)(compactRowStyles_1.StyledGroupBody, { "$calm": calm, "$hairline": cHairline, "$divider": cDivider, "$hover": cHover, "$focus": cWarning, "$success": cSuccess, "$rowBg": cRowBg, "$lineColor": cGroupLine, "$moreBorder": cMoreBorder, className: "readfirst-read-list".concat(compactNarrow ? ' readfirst-narrow' : ''), children: bucketGroups.set.map(function (groupName) { return renderBoxGroup('set', groupName); }) }) })
                                                     : null
                                                 : STATUS_BOXES.map(function (box) {
                                                     var groupsInBox = bucketGroups[box.key];
@@ -2682,6 +2808,12 @@ var FormEngineImpl = function (_a) {
                                                     // Group order is preserved so the visible rows read in the
                                                     // same order they would if nothing were folded.
                                                     var orderedRows = groupsInBox.flatMap(function (groupName) { return buckets[box.key][groupName] || []; });
+                                                    // The number in the box's header counts the rows whose value
+                                                    // belongs in it NOW. A field being edited keeps its box until it
+                                                    // is left (so it does not jump away under the caret), and it used
+                                                    // to keep its count too: a box read "To fill in 1" while its last
+                                                    // field already had a value and the host's submit read ready.
+                                                    var headerCount = readOnly ? count : (orderedRows.filter(function (entry) { return getOptionBucket(entry.name, entry.hidden) === box.key; }).length);
                                                     // Optional's own rule first: a box opened solely to reveal
                                                     // preselected rows offers those, not an arbitrary first-N.
                                                     var candidateRows = splitForPreselected ? orderedRows.filter(isPreselectedRow) : orderedRows;
@@ -2706,23 +2838,32 @@ var FormEngineImpl = function (_a) {
                                                         return (buckets[box.key][groupName] || []).some(function (entry) { return !shownRowSet.has(entry.name); });
                                                     });
                                                     var moreOpen = Boolean(query) || expandedMoreBoxes.includes(box.key);
-                                                    var accent = box.key === 'attention' ? cWarning
+                                                    var accent = box.key === 'attention' && readFirstAttentionFaultCount ? 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' ?
+                                                    // Calm: every box is the same panel — no recessed one.
+                                                    var boxBg = box.key === 'optional' && !calm ?
                                                         (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, "$surface": stickyBoxHeaders ? (0, colors_1.getMainBackgroundColor)(theme) : undefined, ref: function (node) {
+                                                    return ((0, jsx_runtime_1.jsx)(compactRowStyles_1.StyledStatusBox, { "$accent": accent, "$bg": boxBg, "$calm": calm, "$surface": stickyBoxHeaders ?
+                                                            calm ? cPanel
+                                                                : (0, colors_1.getMainBackgroundColor)(theme)
+                                                            : undefined, ref: function (node) {
                                                             statusBoxRefs.current[box.key] = node;
                                                         }, 
                                                         // Opening arms the reveal; collapsing disarms it, so a
                                                         // close never scrolls.
                                                         onCollapseChange: function (collapsed) {
                                                             return setOpenedStatusBox(collapsed ? undefined : box.key);
-                                                        }, flat: true, minimal: true, 
+                                                        }, 
+                                                        // Calm: an ordinary panel — Reqore paints the theme's
+                                                        // panel surface and its hairline edge. The header stays
+                                                        // minimal (no surface or rule of its own); the first
+                                                        // row's hairline is the line under it.
+                                                        flat: !calm, minimal: true, 
                                                         /* The header stays on screen while its own box is
                                                            being read — see `compactStickyBoxHeaders`. Sticky
                                                            is bounded by its containing block, so the header
@@ -2754,7 +2895,17 @@ var FormEngineImpl = function (_a) {
                                                         // the box reveals the preselected fields without also
                                                         // dumping every not-yet-added optional field on the
                                                         // author.
-                                                        isCollapsed: wouldCollapse && !hasPreselectedRows, 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.jsxs)(compactRowStyles_1.StyledGroupBody, { "$divider": cDivider, "$hover": cHover, "$focus": cWarning, "$success": cSuccess, "$rowBg": cRowBg, "$lineColor": cGroupLine, "$moreBorder": cMoreBorder, className: compactNarrow ? 'readfirst-narrow' : undefined, children: [shownGroups.map(function (groupName) {
+                                                        isCollapsed: wouldCollapse && !hasPreselectedRows, label: calm ?
+                                                            // One status dot and a word — and only where a
+                                                            // person is needed. The count is a quiet number.
+                                                            (0, jsx_runtime_1.jsxs)(compactRowStyles_1.StyledGroupHeader, { "$calm": true, children: [box.key === 'attention' && readFirstAttentionFaultCount ?
+                                                                        (0, jsx_runtime_1.jsx)(compactRowStyles_1.StyledStatusDot, { className: 'options-readfirst-group-dot', "$color": cWarning, "aria-hidden": true })
+                                                                        : null, (0, jsx_runtime_1.jsx)(reqore_1.ReqoreP, { effect: { weight: 'bold' }, size: 'normal', children: box.label }), headerCount ?
+                                                                        (0, jsx_runtime_1.jsx)(reqore_1.ReqoreSpan, { className: 'options-readfirst-group-count', size: 'small', effect: { opacity: 0.65 }, children: headerCount })
+                                                                        : null] })
+                                                            : (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 }), headerCount ?
+                                                                        (0, jsx_runtime_1.jsx)(reqore_1.ReqoreTag, { size: 'small', minimal: true, compact: true, intent: box.intent, label: String(headerCount) })
+                                                                        : null] }), icon: calm ? undefined : box.icon, className: 'options-readfirst-group', padded: false, contentStyle: { padding: calm ? 0 : '4px 4px 6px' }, children: (0, jsx_runtime_1.jsxs)(compactRowStyles_1.StyledGroupBody, { "$calm": calm, "$hairline": cHairline, "$divider": cDivider, "$hover": cHover, "$focus": cWarning, "$success": cSuccess, "$rowBg": cRowBg, "$lineColor": cGroupLine, "$moreBorder": cMoreBorder, className: compactNarrow ? 'readfirst-narrow' : undefined, children: [shownGroups.map(function (groupName) {
                                                                     return renderBoxGroup(box.key, groupName, shownRowSet);
                                                                 }), deferredCount ?
                                                                     (0, jsx_runtime_1.jsxs)("button", { type: 'button', className: 'readfirst-row readfirst-more-row options-readfirst-more', "aria-expanded": moreOpen, onClick: function () {
@@ -2819,7 +2970,7 @@ var FormEngineImpl = function (_a) {
                                 : null, 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;
+                        var _b, _c, _d, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s;
                         var type = _a.type, other = __rest(_a, ["type"]);
                         return ({
                             label: ((_b = options[optionName]) === null || _b === void 0 ? void 0 : _b.display_name) || optionName,
@@ -2835,20 +2986,22 @@ var FormEngineImpl = function (_a) {
                                         cursor: 'help',
                                     }
                                     : undefined,
-                                onClick: ((_f = options[optionName]) === null || _f === void 0 ? void 0 : _f.desc) ? function () { return handleOptionLabelClick(optionName); } : undefined,
+                                onClick: (0, fieldDescription_1.fieldHasLongDescription)(options[optionName]) ?
+                                    function () { return handleOptionLabelClick(optionName); }
+                                    : undefined,
                             },
-                            showLabelTooltip: !!((_g = options[optionName]) === null || _g === void 0 ? void 0 : _g.short_desc),
+                            showLabelTooltip: !!((_f = options[optionName]) === null || _f === void 0 ? void 0 : _f.short_desc),
                             customLabelTooltip: {
                                 delay: 300,
-                                content: ((0, jsx_runtime_1.jsx)(Description_1.Description, { longDescription: "".concat((_h = options[optionName]) === null || _h === void 0 ? void 0 : _h.short_desc).concat(((_j = options[optionName]) === null || _j === void 0 ? void 0 : _j.desc) ? '. Click to learn more.' : ''), margin: 'none' })),
+                                content: ((0, jsx_runtime_1.jsx)(Description_1.Description, { longDescription: "".concat((_g = options[optionName]) === null || _g === void 0 ? void 0 : _g.short_desc).concat((0, fieldDescription_1.fieldHasLongDescription)(options[optionName]) ? '. Click to learn more.' : ''), margin: 'none' })),
                             },
                             description: showFieldTypes ?
-                                "<".concat(options[optionName].ui_type || options[optionName].type).concat(((_k = options[optionName]) === null || _k === void 0 ? void 0 : _k.ui_element_type) ? "[".concat(options[optionName].ui_element_type, "]") : '', "> ").concat(options[optionName].short_desc || '')
+                                "<".concat(options[optionName].ui_type || options[optionName].type).concat(((_h = options[optionName]) === null || _h === void 0 ? void 0 : _h.ui_element_type) ? "[".concat(options[optionName].ui_element_type, "]") : '', "> ").concat(options[optionName].short_desc || '')
                                 : options[optionName].short_desc || '',
                             descriptionEffect: {
                                 textSize: '11px',
                                 opacity: 0.3,
-                                underline: ((_l = options[optionName]) === null || _l === void 0 ? void 0 : _l.desc) ? 'underline dotted #878787' : undefined,
+                                underline: (0, fieldDescription_1.fieldHasLongDescription)(options[optionName]) ? 'underline dotted #878787' : undefined,
                             },
                             customTheme: {
                                 main: 'main:darken:1',
@@ -2885,7 +3038,7 @@ var FormEngineImpl = function (_a) {
                                 menu: [
                                     !readOnly &&
                                         type !== 'code-editor' &&
-                                        (((_m = options[optionName]) === null || _m === void 0 ? void 0 : _m.ui_type) || ((_o = options[optionName]) === null || _o === void 0 ? void 0 : _o.type)) !==
+                                        (((_j = options[optionName]) === null || _j === void 0 ? void 0 : _j.ui_type) || ((_k = options[optionName]) === null || _k === void 0 ? void 0 : _k.type)) !==
                                             'code-editor' && {
                                         label: 'Focused editing',
                                         icon: 'FullscreenLine',
@@ -2905,15 +3058,15 @@ var FormEngineImpl = function (_a) {
                                     !readOnly &&
                                         other.value &&
                                         !(0, lodash_1.isEqual)(other.value, (0, common_1.getDefaultValue)(options[optionName])) &&
-                                        !(((_p = options[optionName]) === null || _p === void 0 ? void 0 : _p.disabled) || ((_q = options[optionName]) === null || _q === void 0 ? void 0 : _q.readonly)) && {
+                                        !(((_l = options[optionName]) === null || _l === void 0 ? void 0 : _l.disabled) || ((_m = options[optionName]) === null || _m === void 0 ? void 0 : _m.readonly)) && {
                                         label: 'Remove value',
                                         icon: 'CloseLine',
                                         className: 'options-item-remove',
                                         onClick: function () { return handleValueChange(optionName, undefined); },
                                     },
                                     !readOnly &&
-                                        !((_r = options[optionName]) === null || _r === void 0 ? void 0 : _r.preselected) &&
-                                        !((_s = options[optionName]) === null || _s === void 0 ? void 0 : _s.required) && {
+                                        !((_o = options[optionName]) === null || _o === void 0 ? void 0 : _o.preselected) &&
+                                        !((_p = options[optionName]) === null || _p === void 0 ? void 0 : _p.required) && {
                                         label: 'Remove option',
                                         icon: 'DeleteBinLine',
                                         intent: 'danger',
@@ -2929,8 +3082,8 @@ var FormEngineImpl = function (_a) {
                                     },
                                 ],
                             }),
-                            content: ((0, jsx_runtime_1.jsxs)(FocusedEditing_1.FocusedEditing, { isFullscreen: focusedEditing === optionName, onClose: function () { return setFocusedEditing(undefined); }, description: (_t = options[optionName]) === null || _t === void 0 ? void 0 : _t.display_name, intent: getIntent(optionName, type, other.value, other.op), children: [focusedEditing === optionName ?
-                                        (0, jsx_runtime_1.jsx)(Description_1.Description, { longDescription: (_u = options[optionName]) === null || _u === void 0 ? void 0 : _u.desc, shortDescription: (_v = options[optionName]) === null || _v === void 0 ? void 0 : _v.short_desc, longDescriptionShownByDefault: true })
+                            content: ((0, jsx_runtime_1.jsxs)(FocusedEditing_1.FocusedEditing, { isFullscreen: focusedEditing === optionName, onClose: function () { return setFocusedEditing(undefined); }, description: (_q = options[optionName]) === null || _q === void 0 ? void 0 : _q.display_name, intent: getIntent(optionName, type, other.value, other.op), children: [focusedEditing === optionName ?
+                                        (0, jsx_runtime_1.jsx)(Description_1.Description, { longDescription: (_r = options[optionName]) === null || _r === void 0 ? void 0 : _r.desc, shortDescription: (_s = options[optionName]) === null || _s === void 0 ? void 0 : _s.short_desc, longDescriptionShownByDefault: true })
                                         : null, renderOption(optionName, __assign({ type: type }, other))] })),
                         });
                     }), defaultZoom: 1, zoomable: false, actions: __spreadArray(__spreadArray([], (rest.actions || []).map(function (action) { return (__assign(__assign({}, action), { minimal: true })); }), true), [
@@ -2967,7 +3120,15 @@ var FormEngineImpl = function (_a) {
  * a child of the row it belongs to. Threading a renderer to each of them by
  * hand is how one of them gets missed.
  */
-var FormEngine = function (props) { return ((0, jsx_runtime_1.jsx)(markdownRendererContext_1.MarkdownRendererContext.Provider, { value: props.markdownRenderer, children: (0, jsx_runtime_1.jsx)(FormEngineImpl, __assign({}, props)) })); };
+var FormEngine = function (props) {
+    var _a;
+    // The form's own `appearance` wins; without one it follows the form (or the
+    // host's provider) it sits in, so a nested sub-form never changes look
+    // halfway down its parent.
+    var inherited = (0, formAppearance_1.useFormAppearance)();
+    var appearance = (_a = props.appearance) !== null && _a !== void 0 ? _a : inherited;
+    return ((0, jsx_runtime_1.jsx)(markdownRendererContext_1.MarkdownRendererContext.Provider, { value: props.markdownRenderer, children: (0, jsx_runtime_1.jsx)(formAppearance_1.FormAppearanceProvider, { value: appearance, children: (0, jsx_runtime_1.jsx)(FormEngineImpl, __assign({}, props)) }) }));
+};
 exports.FormEngine = FormEngine;
 exports.default = exports.FormEngine;
 var templateObject_1, templateObject_2, templateObject_3, templateObject_4;