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

package/src/components/form/engine/FormEngine.tsx

@@ -6,6 +6,7 @@ import {
   ReqoreIcon,
   ReqoreMessage,
   ReqoreP,
+  ReqoreSpan,
   ReqoreTag,
   ReqoreTagGroup,
   ReqoreVerticalSpacer,
@@ -43,6 +44,7 @@ import { offersTypeChoices } from './typeChoices';
 import { optionRowActions, resolveOptionActions, TOptionActions } from './optionActions';
 import { createRendererOnlyUiTypeCheck, isRendererOnlyUiType } from './rendererTypes';
 import { revealRow } from './revealRow';
+import { findRowFocusTarget } from './rowFocus';
 import { useEmittedValues } from '../fields/emittedValues';
 import { cloneDeep, findKey, flatten, forEach, isEqual, isPlainObject, last, uniq } from 'lodash';
 import map from 'lodash/map';
@@ -51,6 +53,8 @@ import size from 'lodash/size';
 import React, { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { useMeasure, useMount, useUpdateEffect } from 'react-use';
 import styled, { css } from 'styled-components';
+import { allowedValueOf } from '../../../helpers/allowedValues';
+import { fieldHasLongDescription } from '../../../helpers/fieldDescription';
 import {
   fixOperatorValue,
   getDefaultValue,
@@ -84,6 +88,7 @@ import { CompactRow } from './CompactRow';
 import { FormFieldsSkeleton } from './FormFieldsSkeleton';
 import { CompactRowContext, ICompactRowContext, TCodePreviewRenderer } from './compactRowContext';
 import {
+  CALM_SECTION_INSET,
   GROUP_INDENT,
   LABEL_AFFORDANCE_WIDTH,
   LABEL_COL_MAX,
@@ -96,6 +101,7 @@ import {
   StyledRequiredClusterHeader,
   StyledStatusBox,
   StyledStatusBoxGroupLabel,
+  StyledStatusDot,
 } from './compactRowStyles';
 import { CompactToolbar } from './CompactToolbar';
 import {
@@ -114,6 +120,14 @@ import {
   TMarkdownRenderer,
 } from '../../Description/markdownRendererContext';
 import { OptionsHelpDialog } from './OptionsHelpDialog';
+import {
+  FormAppearanceProvider,
+  getCalmPanelHairline,
+  getCalmPanelSurface,
+  TFormEngineAppearance,
+  useFormAppearance,
+  useIsCalmForm,
+} from './formAppearance';
 import { firstDeclaredType, isUntypedOptionType } from '../../../helpers/optionUiTypes';
 import {
   TReadFirstStatus,
@@ -197,6 +211,14 @@ export interface IFormValidityData {
   invalidFields: IFormFieldValidityData[];
 }
 
+/** The two numbers the readiness line shows ("2 need attention · 1 to fill in"). */
+export interface IFormAttention {
+  /** Fields in the first box: still to fill in, and faults. */
+  count: number;
+  /** How many of those are faults (amber) rather than only still to fill in. */
+  faults: number;
+}
+
 /**
  * Resolve a field's `inherit_props` map against the current available
  * options (plus any values inherited from an outer FormEngine scope),
@@ -848,6 +870,21 @@ export interface IFormEngineProps extends Omit<IReqoreCollectionProps, 'onChange
    * value; clicking expands the real editor inline, Done collapses it.
    */
   compact?: boolean;
+  /**
+   * How the form LOOKS — never what it does. `'default'` keeps the established
+   * look; `'calm'` draws the status boxes as plain panels on the theme's panel
+   * surface with label/value rows split by hairlines, grey labels, an amber
+   * "Required · add a value" in place of red asterisks and messages, quiet
+   * counts, no dot on a healthy row, Yes/No as words, and a readiness meter
+   * whose done part is grey. See {@link TFormEngineAppearance}.
+   *
+   * Opt-in, so a consumer that does not pass it is unchanged. Inherited: a
+   * nested (`arg_schema`) sub-form and every field editor the form mounts
+   * follow the form's appearance, and a form with no `appearance` of its own
+   * follows a `FormAppearanceProvider` above it. Applies to compact mode; the
+   * classic collection layout only passes it on to its field editors.
+   */
+  appearance?: TFormEngineAppearance;
   /**
    * Compact mode only: drop the read-first wrap's horizontal gutter (the 12px
    * breathing room) so the form sits flush to its container's edges. For embeds
@@ -928,8 +965,32 @@ export interface IFormEngineProps extends Omit<IReqoreCollectionProps, 'onChange
    * `Optional` names a category rather than the things in it, and
    * `Optional settings` is what the reader is looking at. Only the labels
    * change; bucketing, icons and intents are untouched.
+   *
+   * `pending` names the first box while nothing in it is a fault yet — a new form's
+   * empty required fields, which are still to fill in (default `To fill in`).
+   */
+  compactBoxLabels?: Partial<Record<TFormEngineBoxKey | 'pending', string>>;
+  /**
+   * The host attempted a submit. Until then an empty required field the person has not
+   * been to yet is only "to fill in": a new form opens neutral rather than with every
+   * required field in amber, and a field turns amber once someone opens it and leaves
+   * it empty. Pass `true` after a failed submit to show every empty required field as
+   * needing attention. Invalid values are faults from the start either way.
+   */
+  revealRequired?: boolean;
+  /**
+   * Bump it to move the caret to the first field that needs attention: the answer to a
+   * submit that could not go is where to type. Each new value opens that field and puts
+   * the caret in it once, even though the host's submit button holds the caret (an open
+   * row otherwise never takes a caret held outside it). Pair it with `revealRequired`.
+   */
+  focusAttentionRequest?: number;
+  /**
+   * The readiness line's two numbers, reported whenever they change. A host that draws
+   * its own submit control draws it from these, so the control and the form can never
+   * disagree about what is left. `{ count: 0, faults: 0 }` is a form with nothing left.
    */
-  compactBoxLabels?: Partial<Record<TFormEngineBoxKey, string>>;
+  onAttentionChange?: (attention: IFormAttention) => void;
   /**
    * Compact mode only: the three status-box headers stay pinned to the top of
    * whatever scrolls while their own box is in view. Default `true`.
@@ -1235,6 +1296,9 @@ const FormEngineImpl = ({
   forceDropdown,
   showTypeToggle = true,
   compact,
+  // Read through the context `FormEngine` provides (resolved there against an
+  // inherited appearance); destructured only to keep it out of `rest`.
+  appearance: _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
@@ -1247,6 +1311,9 @@ const FormEngineImpl = ({
   compactPanelProps,
   compactCollapsedGroups: compactCollapsedGroupsProp,
   compactBoxLabels,
+  revealRequired = false,
+  focusAttentionRequest,
+  onAttentionChange,
   compactStickyBoxHeaders = true,
   compactStickyOffset = 0,
   compactToolbar = true,
@@ -1318,6 +1385,7 @@ const FormEngineImpl = ({
   const [loading, setLoading] = useState<boolean>(!!(url || customUrl || operatorsUrl));
   const confirmAction = useReqoreProperty('confirmAction');
   const theme = useReqoreTheme();
+  const calm = useIsCalmForm();
   const [focusedEditing, setFocusedEditing] = useState<string>();
   const [showFieldTypes, setShowFieldTypes] = useState<boolean>(false);
   // Global toggle (toolbar ⓘ): reveal the short-description info panel on every
@@ -1330,6 +1398,21 @@ const FormEngineImpl = ({
   const [showInvalidOptionsOnly, setShowInvalidOptionsOnly] = useState<boolean>(false);
   // Which options are expanded into their editor (several can be open at once).
   const [expandedOptions, setExpandedOptions] = useState<string[]>([]);
+  // 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.
+  const [visitedOptions, setVisitedOptions] = useState<string[]>([]);
+  const lastExpandedOptions = useRef<string[]>([]);
+  useEffect(() => {
+    const left = lastExpandedOptions.current.filter((name) => !expandedOptions.includes(name));
+    lastExpandedOptions.current = expandedOptions;
+    if (left.length) {
+      setVisitedOptions((prev) => {
+        const added = left.filter((name) => !prev.includes(name));
+        return added.length ? [...prev, ...added] : prev;
+      });
+    }
+  }, [expandedOptions]);
   /** Status boxes whose "N more fields" control the reader has opened. Keyed by
       box so opening Optional does not also unfold Set. */
   const [expandedMoreBoxes, setExpandedMoreBoxes] = useState<TFormEngineBoxKey[]>([]);
@@ -2270,7 +2353,7 @@ const FormEngineImpl = ({
     forEach(options || {}, (optionSchema, name) => {
       forEach(optionSchema?.allowed_values || [], (allowedValue) => {
         if (!getAllowedValueAvailability(allowedValue, availableOptions, options || {}).available) {
-          locked.push(`${name}\u0000${JSON.stringify(allowedValue?.value?.value)}`);
+          locked.push(`${name}\u0000${JSON.stringify(allowedValueOf(allowedValue))}`);
         }
       });
     });
@@ -2458,6 +2541,11 @@ const FormEngineImpl = ({
       (newValue, option, optionName) => {
         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,
             getOptionFieldStorageType(
@@ -2480,6 +2568,7 @@ const FormEngineImpl = ({
     );
   }, [
     showInvalidOptionsOnly,
+    expandedOptions,
     isRendererOnly,
     JSON.stringify(availableOptions),
     JSON.stringify(options),
@@ -2548,9 +2637,12 @@ const FormEngineImpl = ({
         covered,
         invalid,
         warned: msgIntent === 'warning',
+        visited: revealRequired || visitedOptions.includes(name),
       });
     },
     [
+      revealRequired,
+      visitedOptions,
       isRendererOnly,
       JSON.stringify(options),
       JSON.stringify(availableOptions),
@@ -2583,6 +2675,24 @@ const FormEngineImpl = ({
         .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.
+  const readFirstAttentionFaultCount = useMemo(
+    () =>
+      Object.keys(availableOptions || {}).filter(
+        (name) => 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.
+  const onAttentionChangeRef = useRef(onAttentionChange);
+  onAttentionChangeRef.current = onAttentionChange;
+  useEffect(() => {
+    onAttentionChangeRef.current?.({
+      count: readFirstAttentionCount,
+      faults: readFirstAttentionFaultCount,
+    });
+  }, [readFirstAttentionCount, readFirstAttentionFaultCount]);
 
   const getIntent = useCallback(
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -2708,6 +2818,39 @@ const FormEngineImpl = ({
   // 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.
+  const getAttentionFieldMeta = useCallback(
+    (fieldName: string) => {
+      const schema = options?.[fieldName];
+      if (!schema) {
+        return undefined;
+      }
+      return {
+        focusable:
+          !readOnly &&
+          !schema.disabled &&
+          !(schema as { readonly?: boolean }).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.
+  const openOption = useCallback(
+    (target: string) =>
+      setExpandedOptions((prev) =>
+        prev.includes(target) ? prev
+        : expandMode === 'multi' ? [...prev, target]
+        : [...prev.filter((name) => initialExpandedOptions?.includes(name)), target]
+      ),
+    [expandMode, initialExpandedOptions]
+  );
+
   const hasAutoFocusedRef = useRef(false);
   useEffect(() => {
     // Two decisions, one scan. Both open the row that needs attention;
@@ -2746,22 +2889,7 @@ const FormEngineImpl = ({
       return;
     }
 
-    const target = getFirstAttentionOptionName(orderedNames, (fieldName) => {
-      const schema = options[fieldName];
-      if (!schema) {
-        return undefined;
-      }
-      return {
-        focusable:
-          !readOnly &&
-          !schema.disabled &&
-          !(schema as { readonly?: boolean }).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',
-      };
-    });
+    const target = 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
@@ -2769,17 +2897,13 @@ const FormEngineImpl = ({
     hasAutoFocusedRef.current = true;
 
     if (target) {
-      setExpandedOptions((prev) =>
-        prev.includes(target) ? prev
-        : expandMode === 'multi' ? [...prev, target]
-          // `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.
-        : [...prev.filter((name) => initialExpandedOptions?.includes(name)), target]
-      );
+      // `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,
@@ -2787,13 +2911,52 @@ const FormEngineImpl = ({
     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.
+  const lastFocusRequest = useRef(focusAttentionRequest);
+  useEffect(() => {
+    if (focusAttentionRequest === lastFocusRequest.current) {
+      return;
+    }
+    lastFocusRequest.current = focusAttentionRequest;
+    if (!focusAttentionRequest || !compact || !options) {
+      return;
+    }
+    const target = getFirstAttentionOptionName(
+      Object.keys(availableOptions),
+      getAttentionFieldMeta
+    );
+    if (!target) {
+      return;
+    }
+    const wrap = compactWrapNodeRef.current;
+    const active = document.activeElement as HTMLElement | null;
+    if (active && active !== document.body && !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.
+    const row = wrap?.querySelector<HTMLElement>(`[data-field="${target}"]`);
+    if (row) {
+      revealRow(row, 'auto');
+      findRowFocusTarget(row.querySelector<HTMLElement>('.options-readfirst-row-editor'), {
+        textEntryOnly: row.classList.contains('options-readfirst-card'),
+      })?.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.
   const readFirstCompletion = useMemo(
@@ -3191,6 +3354,9 @@ const FormEngineImpl = ({
             option={{ 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 && size(operators) && size(other.op) ?
             <>
@@ -3242,6 +3408,8 @@ const FormEngineImpl = ({
       getTypeForOption,
       inheritedScopes,
       inheritedFromParent,
+      revealRequired,
+      visitedOptions,
     ]
   );
 
@@ -3266,6 +3434,10 @@ const FormEngineImpl = ({
   // 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.
   const cMoreBorder = `${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).
+  const cPanel = getCalmPanelSurface(theme);
+  const cHairline = 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
@@ -3284,6 +3456,8 @@ const FormEngineImpl = ({
       codePreviewRenderer,
       showAllDescriptions,
       expandedOptions,
+      visitedOptions,
+      revealRequired,
       highlightedOptions,
       flashedOptions,
       infoPanelOverrides,
@@ -3332,6 +3506,8 @@ const FormEngineImpl = ({
       codePreviewRenderer,
       showAllDescriptions,
       expandedOptions,
+      visitedOptions,
+      revealRequired,
       highlightedOptions,
       flashedOptions,
       infoPanelOverrides,
@@ -3383,6 +3559,7 @@ const FormEngineImpl = ({
       readOnly,
       invalidCount: size(validityData.invalidFields),
       attentionCount: readFirstAttentionCount,
+      attentionFaultCount: readFirstAttentionFaultCount,
       completion: readFirstCompletion,
       showInvalidOnly: showInvalidOptionsOnly,
       onToggleInvalidOnly: handleToggleInvalidOnly,
@@ -3430,6 +3607,7 @@ const FormEngineImpl = ({
       onReadOnlyActivate,
       validityData,
       readFirstAttentionCount,
+      readFirstAttentionFaultCount,
       readFirstCompletion,
       showInvalidOptionsOnly,
       handleToggleInvalidOnly,
@@ -3711,12 +3889,20 @@ const FormEngineImpl = ({
       intent?: 'warning' | 'success';
       icon: IReqoreIconName;
     }> = [
-      {
-        key: 'attention',
-        label: compactBoxLabels?.attention ?? 'Needs attention',
-        intent: 'warning',
-        icon: 'ErrorWarningLine',
-      },
+      // 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: compactBoxLabels?.attention ?? 'Needs attention',
+          intent: 'warning',
+          icon: 'ErrorWarningLine',
+        }
+      : {
+          key: 'attention',
+          label: compactBoxLabels?.pending ?? 'To fill in',
+          icon: 'CheckboxBlankCircleLine',
+        },
       { key: 'set', label: compactBoxLabels?.set ?? 'Set', intent: 'success', icon: 'CheckLine' },
       {
         key: 'optional',
@@ -3785,15 +3971,28 @@ const FormEngineImpl = ({
         // 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;
+        // 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.
+        const clusterColor =
+          memberEntries.some((e) => getOptionStatus(e.name) !== 'pending') ? cWarning : cMuted;
         return (
           <StyledRequiredClusterBox
             key={grp}
             className='options-readfirst-required-cluster'
-            $border={`${cWarning}33`}
-            $tint={`${cWarning}0d`}
+            $border={`${clusterColor}33`}
+            $tint={`${clusterColor}0d`}
+            $calm={calm}
           >
-            <StyledRequiredClusterHeader $color={cWarning}>
-              <ReqoreIcon icon='LinkM' size='11px' style={{ color: cWarning }} />
+            <StyledRequiredClusterHeader
+              className='options-readfirst-required-cluster-header'
+              $color={clusterColor}
+              $calm={calm}
+            >
+              <ReqoreIcon
+                icon='LinkM'
+                size={calm ? '13px' : '11px'}
+                style={{ color: clusterColor }}
+              />
               One of the below is required
             </StyledRequiredClusterHeader>
             {railed}
@@ -3821,20 +4020,31 @@ const FormEngineImpl = ({
       return (
         <React.Fragment key={groupName}>
           {showGroupSubLabel(groupName) ?
-            <StyledStatusBoxGroupLabel>
+            <StyledStatusBoxGroupLabel
+              className='options-readfirst-group-label'
+              $calm={calm}
+              $color={cKey}
+            >
               {getOptionGroupLabel(groupName, groups)}
             </StyledStatusBoxGroupLabel>
           : null}
           {showGroupSubLabel(groupName) && groupConfig?.subtitle ?
             <ReqoreP
+              className='options-readfirst-group-subtitle'
               size='small'
               effect={{ opacity: 0.6 }}
-              style={{
-                marginTop: 2,
-                marginBottom: 8,
-                marginLeft: GROUP_INDENT,
-                paddingRight: 10,
-              }}
+              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 ${CALM_SECTION_INSET}px 4px` }
+                : {
+                    marginTop: 2,
+                    marginBottom: 8,
+                    marginLeft: GROUP_INDENT,
+                    paddingRight: 10,
+                  }
+              }
             >
               {groupConfig.subtitle}
             </ReqoreP>
@@ -3888,8 +4098,15 @@ const FormEngineImpl = ({
                     )
                   }
                   flat
-                  raised
+                  // 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
+                  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.
@@ -3967,8 +4184,13 @@ const FormEngineImpl = ({
                       the reader's record withheld, and a page scrolls. */}
                   {readOnly ?
                     bucketCount('set') ?
-                      <div className='options-readfirst-read' style={{ padding: '4px 4px 6px' }}>
+                      <div
+                        className='options-readfirst-read'
+                        style={{ padding: calm ? 0 : '4px 4px 6px' }}
+                      >
                         <StyledGroupBody
+                          $calm={calm}
+                          $hairline={cHairline}
                           $divider={cDivider}
                           $hover={cHover}
                           $focus={cWarning}
@@ -3976,7 +4198,7 @@ const FormEngineImpl = ({
                           $rowBg={cRowBg}
                           $lineColor={cGroupLine}
                           $moreBorder={cMoreBorder}
-                          className={compactNarrow ? 'readfirst-narrow' : undefined}
+                          className={`readfirst-read-list${compactNarrow ? ' readfirst-narrow' : ''}`}
                         >
                           {bucketGroups.set.map((groupName) => renderBoxGroup('set', groupName))}
                         </StyledGroupBody>
@@ -4004,6 +4226,17 @@ const FormEngineImpl = ({
                       const orderedRows: TRowEntry[] = groupsInBox.flatMap(
                         (groupName) => 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.
+                      const headerCount =
+                        readOnly ? count : (
+                          orderedRows.filter(
+                            (entry) => 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.
                       const candidateRows =
@@ -4036,24 +4269,32 @@ const FormEngineImpl = ({
                       );
                       const moreOpen = Boolean(query) || expandedMoreBoxes.includes(box.key);
                       const accent =
-                        box.key === 'attention' ? cWarning
+                        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.
+                      // Calm: every box is the same panel — no recessed one.
                       const boxBg =
-                        box.key === 'optional' ?
+                        box.key === 'optional' && !calm ?
                           changeDarkness(getMainBackgroundColor(theme), 0.06)
                         : undefined;
                       return (
                         <StyledStatusBox
                           $accent={accent}
                           $bg={boxBg}
+                          $calm={calm}
                           // Only a box that PINS needs an opaque header (see
                           // StyledStatusBox); passing it unconditionally would
-                          // repaint every form's boxes for nothing.
-                          $surface={stickyBoxHeaders ? getMainBackgroundColor(theme) : undefined}
+                          // repaint every form's boxes for nothing. A calm box
+                          // pins on its own panel surface.
+                          $surface={
+                            stickyBoxHeaders ?
+                              calm ? cPanel
+                              : getMainBackgroundColor(theme)
+                            : undefined
+                          }
                           key={box.key}
                           ref={(node: HTMLDivElement | null) => {
                             statusBoxRefs.current[box.key] = node;
@@ -4063,7 +4304,11 @@ const FormEngineImpl = ({
                           onCollapseChange={(collapsed) =>
                             setOpenedStatusBox(collapsed ? undefined : box.key)
                           }
-                          flat
+                          // 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
                           /* The header stays on screen while its own box is
                              being read — see `compactStickyBoxHeaders`. Sticky
@@ -4101,29 +4346,57 @@ const FormEngineImpl = ({
                           // author.
                           isCollapsed={wouldCollapse && !hasPreselectedRows}
                           label={
-                            <StyledGroupHeader>
-                              <ReqoreP effect={{ weight: 'bold' }} size='normal'>
-                                {box.label}
-                              </ReqoreP>
-                              <ReqoreTag
-                                size='small'
-                                minimal
-                                compact
-                                intent={box.intent}
-                                label={String(count)}
-                              />
-                            </StyledGroupHeader>
+                            calm ?
+                              // One status dot and a word — and only where a
+                              // person is needed. The count is a quiet number.
+                              <StyledGroupHeader $calm>
+                                {box.key === 'attention' && readFirstAttentionFaultCount ?
+                                  <StyledStatusDot
+                                    className='options-readfirst-group-dot'
+                                    $color={cWarning}
+                                    aria-hidden
+                                  />
+                                : null}
+                                <ReqoreP effect={{ weight: 'bold' }} size='normal'>
+                                  {box.label}
+                                </ReqoreP>
+                                {headerCount ?
+                                  <ReqoreSpan
+                                    className='options-readfirst-group-count'
+                                    size='small'
+                                    effect={{ opacity: 0.65 }}
+                                  >
+                                    {headerCount}
+                                  </ReqoreSpan>
+                                : null}
+                              </StyledGroupHeader>
+                            : <StyledGroupHeader>
+                                <ReqoreP effect={{ weight: 'bold' }} size='normal'>
+                                  {box.label}
+                                </ReqoreP>
+                                {headerCount ?
+                                  <ReqoreTag
+                                    size='small'
+                                    minimal
+                                    compact
+                                    intent={box.intent}
+                                    label={String(headerCount)}
+                                  />
+                                : null}
+                              </StyledGroupHeader>
                           }
-                          icon={box.icon}
+                          icon={calm ? undefined : box.icon}
                           className='options-readfirst-group'
                           padded={false}
-                          contentStyle={{ padding: '4px 4px 6px' }}
+                          contentStyle={{ padding: calm ? 0 : '4px 4px 6px' }}
                         >
                           {/* ONE group body per box: every field block (and the
                             thin schema sub-labels) is a direct flex child, so the
                             inter-field gap is identical everywhere — including
                             across schema-group boundaries. */}
                           <StyledGroupBody
+                            $calm={calm}
+                            $hairline={cHairline}
                             $divider={cDivider}
                             $hover={cHover}
                             $focus={cWarning}
@@ -4379,14 +4652,16 @@ const FormEngineImpl = ({
                     }
                   : undefined,
                 onClick:
-                  options[optionName]?.desc ? () => handleOptionLabelClick(optionName) : undefined,
+                  fieldHasLongDescription(options[optionName]) ?
+                    () => handleOptionLabelClick(optionName)
+                  : undefined,
               },
               showLabelTooltip: !!options[optionName]?.short_desc,
               customLabelTooltip: {
                 delay: 300,
                 content: (
                   <Description
-                    longDescription={`${options[optionName]?.short_desc}${options[optionName]?.desc ? '. Click to learn more.' : ''}`}
+                    longDescription={`${options[optionName]?.short_desc}${fieldHasLongDescription(options[optionName]) ? '. Click to learn more.' : ''}`}
                     margin='none'
                   />
                 ),
@@ -4398,7 +4673,8 @@ const FormEngineImpl = ({
               descriptionEffect: {
                 textSize: '11px',
                 opacity: 0.3,
-                underline: options[optionName]?.desc ? 'underline dotted #878787' : undefined,
+                underline:
+                  fieldHasLongDescription(options[optionName]) ? 'underline dotted #878787' : undefined,
               },
               customTheme: {
                 main: 'main:darken:1',
@@ -4560,10 +4836,20 @@ const FormEngineImpl = ({
  * a child of the row it belongs to. Threading a renderer to each of them by
  * hand is how one of them gets missed.
  */
-export const FormEngine = (props: IFormEngineProps) => (
-  <MarkdownRendererContext.Provider value={props.markdownRenderer}>
-    <FormEngineImpl {...props} />
-  </MarkdownRendererContext.Provider>
-);
+export const FormEngine = (props: IFormEngineProps) => {
+  // 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.
+  const inherited = useFormAppearance();
+  const appearance = props.appearance ?? inherited;
+
+  return (
+    <MarkdownRendererContext.Provider value={props.markdownRenderer}>
+      <FormAppearanceProvider value={appearance}>
+        <FormEngineImpl {...props} />
+      </FormAppearanceProvider>
+    </MarkdownRendererContext.Provider>
+  );
+};
 
 export default FormEngine;