@qoretechnologies/reqraft 0.10.46-pr.95.ge595a13 → 0.10.46

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

@@ -49,7 +49,12 @@ import React, { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useSta
 import { useMeasure, useMount, useUpdateEffect } from 'react-use';
 import styled from 'styled-components';
 import { createContext } from 'use-context-selector';
-import { getDefaultValue, insertAtIndex, richtextToString } from '../../../helpers/common';
+import {
+  fixOperatorValue,
+  getDefaultValue,
+  insertAtIndex,
+  richtextToString,
+} from '../../../helpers/common';
 import { getRequiredOptionMessage } from '../../../helpers/options';
 import {
   IValidationResult,
@@ -70,11 +75,7 @@ import {
   isValueTemplate,
 } from '../fields/template/TemplateField';
 import { CompactRow } from './CompactRow';
-import {
-  CompactRowContext,
-  ICompactRowContext,
-  TCodePreviewRenderer,
-} from './compactRowContext';
+import { CompactRowContext, ICompactRowContext, TCodePreviewRenderer } from './compactRowContext';
 import {
   GROUP_INDENT,
   LABEL_AFFORDANCE_WIDTH,
@@ -117,9 +118,25 @@ import {
   isOptionValueEmpty,
   isFixedCompactAllowedValueOption,
   shouldAutoCollapseCompactOption,
+  isUnsetSchemaHash,
 } from './readFirst';
 
 // Re-export types for consumers
+/** The compact form's three status boxes. */
+export type TFormEngineBoxKey = 'attention' | 'set' | 'optional';
+
+/** Which parts of the compact toolbar to render — see `compactToolbar`. */
+export interface IFormEngineToolbarParts {
+  /** The "Ready / 4 of 6 set / 67%" line and its meter. */
+  completion?: boolean;
+  /** The "Filter fields…" input. */
+  search?: boolean;
+  /** The field-picker dropdown (add optional fields, reset, revert). */
+  fields?: boolean;
+  /** The help button that opens the options dialog. */
+  help?: boolean;
+}
+
 export type IOptions = TQorusForm;
 export type TFlatOptions = TQorusFlatForm;
 export type TOption = IQorusFormField;
@@ -133,8 +150,7 @@ export type TOperatorValue = TQorusFormOperatorValue;
  * consumer gets.
  */
 export interface IOptionFieldMessage
-  extends IQorusFormFieldMessage,
-    Pick<IConditionalFieldMessage, 'when' | 'unless'> {}
+  extends IQorusFormFieldMessage, Pick<IConditionalFieldMessage, 'when' | 'unless'> {}
 export type IOptionsSchemaArg = TQorusFormFieldSchema;
 export interface IOptionsSchema extends IQorusFormSchema {}
 export interface IOperator extends IQorusFormOperator {}
@@ -292,9 +308,10 @@ const getTypeFromOperator = (
   return (operators[last(operatorData) as string]?.type as TQorusType) || null;
 };
 
-export const fixOperatorValue = (operator: TOperatorValue): (string | null | undefined)[] => {
-  return isArray(operator) ? operator : [operator];
-};
+/** Re-exported from `helpers/common` so existing importers keep working; it
+ *  lives there because `helpers/validations` needs it and cannot import this
+ *  module (this module imports the validators). */
+export { fixOperatorValue } from '../../../helpers/common';
 
 /**
  * The renderer-only predicate. Defaults to reqraft's built-ins; a FormEngine
@@ -307,11 +324,9 @@ const getOptionSchemaStorageType = (
   option?: TQorusFormFieldSchema,
   isRendererOnly: TRendererOnlyCheck = isRendererOnlyUiType
 ): TQorusType =>
-  ((isFixedCompactAllowedValueOption(option)
-    ? option?.type || option?.ui_type
-    : isRendererOnly(option?.ui_type)
-    ? option?.type || option?.ui_type
-    : option?.ui_type || option?.type) || 'any') as TQorusType;
+  ((isFixedCompactAllowedValueOption(option) ? option?.type || option?.ui_type
+  : isRendererOnly(option?.ui_type) ? option?.type || option?.ui_type
+  : option?.ui_type || option?.type) || 'any') as TQorusType;
 
 const getOptionFieldStorageType = (
   optionName: string,
@@ -323,9 +338,9 @@ const getOptionFieldStorageType = (
 ): TQorusType => {
   const schemaOption = schema?.[optionName];
   const storedType =
-    fieldType && !(fieldType === schemaOption?.ui_type && isRendererOnly(fieldType))
-      ? fieldType
-      : getOptionSchemaStorageType(schemaOption, isRendererOnly);
+    fieldType && !(fieldType === schemaOption?.ui_type && isRendererOnly(fieldType)) ?
+      fieldType
+    : getOptionSchemaStorageType(schemaOption, isRendererOnly);
 
   return getType(storedType as TQorusType, operators, operatorData);
 };
@@ -373,6 +388,23 @@ export const fixOptions = (
         (fixedValue[name] as IQorusFormField)?.value === undefined
       ) {
         obj = option.default_value as IQorusFormField;
+      } else if (
+        option.default_view === 'expression' &&
+        (fixedValue[name] as IQorusFormField)?.value === undefined
+      ) {
+        // A field the schema declares as opening in expression mode starts as an
+        // EMPTY expression, not as its raw default. `isDefaultFunction` already
+        // makes the renderer open that way, so without this the data disagreed
+        // with what the operator was looking at: an expression editor whose
+        // value was still the plain default, and no `is_expression` on the field
+        // until the first edit.
+        obj = {
+          type,
+          value: {
+            args: [],
+          },
+          is_expression: true,
+        };
       } else {
         obj = {
           type,
@@ -438,9 +470,19 @@ export const fixOptions = (
       // every value declared the bare way: the collapsed row still showed its
       // display name while the editor showed "—" and the value never reached
       // the submitted data.
+      // `allowed_values: []` is NOT "no value is permitted" — it is the server
+      // saying it has no reference values to offer right now (the app-action
+      // catalogue ships exactly that, with an
+      // `option_reference_values_unavailable` message attached). An empty array
+      // is truthy, so testing the array itself made every such option erase the
+      // operator's stored value on the first render, before the
+      // connection-refreshed schema arrived to say otherwise — and the emptied
+      // form then autosaved over the draft, so the value was gone for good.
+      // Only an option that actually declares choices can have a value that is
+      // not one of them.
       if (
         newOption.value !== undefined &&
-        options?.[optionName]?.allowed_values &&
+        options?.[optionName]?.allowed_values?.length &&
         !findAllowedValueOption(newOption.value, options?.[optionName]) &&
         !isValueTemplate(newOption.value) &&
         !options?.[optionName]?.multiselect &&
@@ -626,6 +668,37 @@ export interface IFormEngineProps extends Omit<IReqoreCollectionProps, 'onChange
    * No-op in classic (non-compact) mode.
    */
   compactPanelProps?: IReqorePanelProps;
+  /**
+   * Compact mode only: which status boxes start collapsed. Defaults to
+   * `['optional']` — a form opens on what is in use.
+   *
+   * Pass `['set', 'optional']` where the form is one item in a longer list and
+   * the reader is choosing WHICH to open rather than reading this one, e.g. a
+   * template's per-action option forms stacked in a drawer.
+   *
+   * Two escapes override this and are not negotiable: a box always opens while
+   * a search query is running (`ReqorePanel` unmounts collapsed content, so a
+   * match inside a closed box would be unreachable), and the Optional box stays
+   * open when every row is optional, because collapsing it would render a card
+   * that looks empty and broken.
+   */
+  compactCollapsedGroups?: TFormEngineBoxKey[];
+  /**
+   * Compact mode only: which parts of the form's toolbar to show. `true`
+   * (default) shows all of it; `false` hides the whole thing.
+   *
+   * The parts already hide themselves when they have nothing to say — the
+   * completion meter needs at least one counted option, and the search and
+   * field-picker need more than one option to pick between — so reach for this
+   * only to hide something that WOULD have rendered. A per-action form asking
+   * for one value, say, has a meter reading 0/1 that tells the reader nothing
+   * they cannot see in the row below it.
+   *
+   * Hiding `search` removes the only way to run a query, which is what forces
+   * a collapsed box open; `compactCollapsedGroups` then fully determines what
+   * is open.
+   */
+  compactToolbar?: boolean | IFormEngineToolbarParts;
   /** Compact mode only: per-group display metadata (label / icon / subtitle /
    * order) — the server only sends the bare group key. */
   groups?: Record<string, IFormEngineGroup>;
@@ -762,6 +835,24 @@ export interface IFormEngineProps extends Omit<IReqoreCollectionProps, 'onChange
    * (non-compact) mode.
    */
   initialExpandedOptions?: string[];
+
+  /**
+   * Cap how many rows a status box shows before the rest fold behind a
+   * "N more fields" control. Applies to every box — Needs attention, Set and
+   * Optional alike — so a long form stays scannable instead of making the
+   * reader page past one box to reach the next.
+   *
+   * Optional keeps its own rule on top of this: a box that would have
+   * collapsed but holds preselected rows shows those rows rather than an
+   * arbitrary first-N. The cap then applies to that set, so
+   * `maxFieldsShown: 5` over 10 preselected fields shows 5 — and opening the
+   * control reveals EVERY row in the box, not just the other 5 preselected
+   * ones, because once the reader has asked to see more, hiding the rest is
+   * the same defect one level down.
+   *
+   * Unset (the default) leaves every box uncapped.
+   */
+  maxFieldsShown?: number;
 }
 
 // Option types rendered full-width (IDE Options parity, commit 8e6b7781).
@@ -792,6 +883,8 @@ const FormEngineImpl = ({
   compactFlush = false,
   compactNested = false,
   compactPanelProps,
+  compactCollapsedGroups = ['optional'],
+  compactToolbar = true,
   commitMode = 'immediate',
   expandMode = 'single',
   onCommit,
@@ -812,6 +905,7 @@ const FormEngineImpl = ({
   autoFocusFirstRequired,
   expandFirstRequired,
   initialExpandedOptions,
+  maxFieldsShown,
   ...rest
 }: IFormEngineProps) => {
   // Built-ins + whatever the consumer declared for its own injected editors.
@@ -859,6 +953,9 @@ 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[]>([]);
+  /** 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[]>([]);
 
   // --- Reveal a status box's content when it is opened ----------------------
   //
@@ -1129,7 +1226,10 @@ const FormEngineImpl = ({
           setOptions({});
           return;
         }
-        setLocalValue({ fields: fixOptions(value, data.data, undefined, isRendererOnly), meta: undefined });
+        setLocalValue({
+          fields: fixOptions(value, data.data, undefined, isRendererOnly),
+          meta: undefined,
+        });
         if (!operatorsUrl) {
           setLoading(false);
         }
@@ -1174,7 +1274,10 @@ const FormEngineImpl = ({
         }
         setOptions(data.data);
         onOptionsLoaded?.(data.data);
-        setLocalValue({ fields: fixOptions({}, data.data, undefined, isRendererOnly), meta: undefined });
+        setLocalValue({
+          fields: fixOptions({}, data.data, undefined, isRendererOnly),
+          meta: undefined,
+        });
       })();
     }
   }, [url, customUrl]);
@@ -1231,12 +1334,14 @@ const FormEngineImpl = ({
         const isAnyLike = schemaType === 'any' || schemaType === 'auto';
         // For any/auto schema types, preserve the user's chosen type stored in the field
         const resolvedSchemaType =
-          isAnyLike && (fields[optionName] as IQorusFormField)?.type
-            ? ((fields[optionName] as IQorusFormField).type as TQorusType)
-            : (fields[optionName] as IQorusFormField)?.type === options?.[optionName]?.ui_type &&
-                isRendererOnly((fields[optionName] as IQorusFormField)?.type)
-              ? schemaType
-              : schemaType || ((fields[optionName] as IQorusFormField)?.type as TQorusType);
+          isAnyLike && (fields[optionName] as IQorusFormField)?.type ?
+            ((fields[optionName] as IQorusFormField).type as TQorusType)
+          : (
+            (fields[optionName] as IQorusFormField)?.type === options?.[optionName]?.ui_type &&
+            isRendererOnly((fields[optionName] as IQorusFormField)?.type)
+          ) ?
+            schemaType
+          : schemaType || ((fields[optionName] as IQorusFormField)?.type as TQorusType);
         const type =
           _type ||
           getTypeAndCanBeNull(resolvedSchemaType, options?.[optionName]?.allowed_values).type;
@@ -1310,11 +1415,7 @@ const FormEngineImpl = ({
 
         onSingleOptionsChange?.(optionName, updatedValue[optionName]);
 
-        if (
-          compact &&
-          !readOnly &&
-          shouldAutoCollapseCompactOption(options?.[optionName], val)
-        ) {
+        if (compact && !readOnly && shouldAutoCollapseCompactOption(options?.[optionName], val)) {
           setExpandedOptions((prev) => prev.filter((name) => name !== optionName));
         }
 
@@ -1757,7 +1858,11 @@ const FormEngineImpl = ({
         isRendererOnly
       );
       const value = (availableOptions as TQorusForm)?.[name]?.value;
-      const empty = isOptionValueEmpty(value);
+      // A schema-declared hash whose every entry is a materialised-but-unset
+      // field holds nothing, so it is not "set" — without this the row showed a
+      // green set-dot and counted toward the completion meter while the
+      // sub-form it summarises said 0/3 set.
+      const empty = isOptionValueEmpty(value) || isUnsetSchemaHash(value, schema);
       const reqGroups = (schema?.required_groups as string[] | undefined) || [];
       const required = !!(schema?.required || reqGroups.length);
       const covered =
@@ -2060,7 +2165,10 @@ const FormEngineImpl = ({
           next[optionName] = value as IQorusFormField;
         }
       });
-      return { fields: fixOptions(next, options || {}, operators, isRendererOnly), meta: undefined };
+      return {
+        fields: fixOptions(next, options || {}, operators, isRendererOnly),
+        meta: undefined,
+      };
     });
     setRequiredOnly(false);
   }, [JSON.stringify(options), JSON.stringify(operators), isRendererOnly]);
@@ -2108,11 +2216,10 @@ const FormEngineImpl = ({
       const schemaUiType = optionSchema?.ui_type as TQorusType;
       const uiTypeIsAnyLike = schemaUiType === 'any' || schemaUiType === 'auto';
       const resolvedType =
-        (isFixedCompactAllowedValueOption(optionSchema)
-          ? getOptionSchemaStorageType(optionSchema, isRendererOnly)
-          : schemaUiType && !uiTypeIsAnyLike
-            ? schemaUiType
-            : undefined) ||
+        (isFixedCompactAllowedValueOption(optionSchema) ?
+          getOptionSchemaStorageType(optionSchema, isRendererOnly)
+        : schemaUiType && !uiTypeIsAnyLike ? schemaUiType
+        : undefined) ||
         type ||
         schemaUiType ||
         (optionSchema?.type as TQorusType) ||
@@ -2307,6 +2414,11 @@ const FormEngineImpl = ({
             allowed_values_creatable={options?.[optionName]?.allowed_values_creatable}
             disabled={
               options?.[optionName]?.disabled ||
+              // a system-owned field states that as `readonly`; only the older
+              // compat projection also sent `disabled`, so honouring only
+              // `disabled` rendered an editable control for a value the user
+              // cannot change (see CompactRow's `fieldReadonly`)
+              (options?.[optionName] as { readonly?: boolean } | undefined)?.readonly ||
               readOnly ||
               !hasAllDependenciesFullfilled(
                 options?.[optionName]?.depends_on,
@@ -2400,6 +2512,9 @@ const FormEngineImpl = ({
   const cBg = (theme as { main?: string } | undefined)?.main || '#181818';
   const cRowBg = changeDarkness(getMainBackgroundColor(theme), 0.01);
   const cGroupLine = `${cText}1f`;
+  // 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`;
 
   // The closure surface the extracted CompactRow reads through context. Refs and
   // setters are stable; the state/memo/handler fields change identity as they do
@@ -2503,6 +2618,14 @@ const FormEngineImpl = ({
     ]
   );
 
+  // `compactToolbar` resolved to a full object, so neither the context type nor
+  // the toolbar itself has to re-default anything. `null` means no toolbar.
+  const compactToolbarParts = useMemo(() => {
+    if (compactToolbar === false) return null;
+    const all = { completion: true, search: true, fields: true, help: true };
+    return compactToolbar === true ? all : { ...all, ...compactToolbar };
+  }, [JSON.stringify(compactToolbar)]);
+
   const compactToolbarContextValue = useMemo<ICompactToolbarContext>(
     () => ({
       readOnly,
@@ -2511,6 +2634,12 @@ const FormEngineImpl = ({
       completion: readFirstCompletion,
       showInvalidOnly: showInvalidOptionsOnly,
       onToggleInvalidOnly: handleToggleInvalidOnly,
+      parts: compactToolbarParts ?? {
+        completion: false,
+        search: false,
+        fields: false,
+        help: false,
+      },
       hasMultipleOptions: size(availableOptions) > 1,
       compactQuery,
       setCompactQuery,
@@ -2561,10 +2690,14 @@ const FormEngineImpl = ({
 
   // The engine's own toolbar action, plus whatever the consumer added through
   // `compactPanelProps.actions` — appended, so an outside action can never
-  // knock the form's toolbar out of the header.
+  // knock the form's toolbar out of the header. Only `compactToolbar={false}`
+  // removes it, and then the header carries just the consumer's own actions.
   const compactHeaderActions = useMemo(
-    () => [{ as: CompactToolbar, responsive: false }, ...(compactPanelProps?.actions || [])],
-    [compactPanelProps?.actions]
+    () => [
+      ...(compactToolbarParts ? [{ as: CompactToolbar, responsive: false }] : []),
+      ...(compactPanelProps?.actions || []),
+    ],
+    [compactPanelProps?.actions, compactToolbarParts]
   );
   const renderCompact = () => {
     const headerBg = `${changeDarkness(getMainBackgroundColor(theme), 0.02)}${percentToHexAlpha(88)}`;
@@ -2699,17 +2832,20 @@ const FormEngineImpl = ({
     // schema-group order (thin sub-labels) and the required-group clustering: an
     // unmet one-of group's members all land in attention and still rail up.
     type TRowEntry = { name: string; hidden: boolean };
-    type TBucketKey = 'attention' | 'set' | 'optional';
-    const buckets: Record<TBucketKey, Record<string, TRowEntry[]>> = {
+    const buckets: Record<TFormEngineBoxKey, Record<string, TRowEntry[]>> = {
       attention: {},
       set: {},
       optional: {},
     };
-    const bucketGroups: Record<TBucketKey, string[]> = { attention: [], set: [], optional: [] };
+    const bucketGroups: Record<TFormEngineBoxKey, string[]> = {
+      attention: [],
+      set: [],
+      optional: [],
+    };
     // Freeze the box of any field currently being edited (or whose one-of group
     // has an edited member) to its last settled box — so finishing an edit that
     // flips its status doesn't remount it in another box and steal focus.
-    const stableBucketOf = (entry: TRowEntry): TBucketKey => {
+    const stableBucketOf = (entry: TRowEntry): TFormEngineBoxKey => {
       const fresh = getOptionBucket(entry.name, entry.hidden);
       const groupBeingEdited =
         !entry.hidden &&
@@ -2733,7 +2869,7 @@ const FormEngineImpl = ({
         buckets[b][groupName].push(entry);
       });
     });
-    const bucketCount = (b: TBucketKey) =>
+    const bucketCount = (b: TFormEngineBoxKey) =>
       bucketGroups[b].reduce((n, g) => n + buckets[b][g].length, 0);
 
     // "Is the Optional box the whole form?" — when nothing needs attention and
@@ -2748,8 +2884,32 @@ const FormEngineImpl = ({
     // other and DOES get its sub-label.
     const showGroupSubLabel = (groupName: string) =>
       (groupName !== 'general' && groupName !== 'optional') || !!groups?.[groupName];
+
+    // `preselected` means "show this option by default when a new form is
+    // loaded, so it's visible to the user". An empty non-required preselected
+    // field buckets to 'optional' (nothing is wrong with it, and it has no
+    // value), and the Optional box is collapsed by default — so the very
+    // fields the schema asked to put in front of the author were the ones
+    // nobody could see. A preselected row therefore forces its box open.
+    //
+    // A hidden row is an addable the author has not put in the form yet, so it
+    // is never what `preselected` is talking about, however its schema is
+    // flagged.
+    const isPreselectedRow = (entry: TRowEntry) =>
+      !entry.hidden &&
+      !!(options?.[entry.name] as { preselected?: boolean } | undefined)?.preselected;
+    // ONLY the Optional box. A preselected field that HAS a value buckets to
+    // 'set' and one that fails validation to 'attention'; in both boxes the
+    // field is already accounted for, and whether those boxes start collapsed
+    // is the consumer's deliberate `compactCollapsedGroups` choice. Overriding
+    // them here forced the Set box open against an explicit request.
+    const groupHasPreselectedRow = (boxKey: TFormEngineBoxKey, groupName: string) =>
+      boxKey === 'optional' && (buckets[boxKey][groupName] || []).some(isPreselectedRow);
+    const boxHasPreselectedRows = (boxKey: TFormEngineBoxKey) =>
+      boxKey === 'optional' &&
+      bucketGroups[boxKey].some((groupName) => groupHasPreselectedRow(boxKey, groupName));
     const STATUS_BOXES: Array<{
-      key: TBucketKey;
+      key: TFormEngineBoxKey;
       label: string;
       intent?: 'warning' | 'success';
       icon: IReqoreIconName;
@@ -2836,6 +2996,52 @@ const FormEngineImpl = ({
       });
     };
 
+    // One schema group inside a status box: its thin sub-label, the group's
+    // subtitle, then its rows. Factored out of the box body so the SAME markup
+    // renders both the groups a box shows directly and the ones it defers
+    // behind the inner collapse.
+    /** @param only when given, render just these rows of the group — the group
+        can be split across the shown and folded halves of a capped box, and its
+        label must appear above whichever half holds its first row. */
+    const renderBoxGroup = (
+      boxKey: TFormEngineBoxKey,
+      groupName: string,
+      only?: Set<string>
+    ) => {
+      const groupConfig = groups?.[groupName];
+      const rows =
+        only ?
+          (buckets[boxKey][groupName] || []).filter((entry) => only.has(entry.name))
+        : buckets[boxKey][groupName];
+      if (only && !rows.length) {
+        return null;
+      }
+      return (
+        <React.Fragment key={groupName}>
+          {showGroupSubLabel(groupName) ?
+            <StyledStatusBoxGroupLabel>
+              {getOptionGroupLabel(groupName, groups)}
+            </StyledStatusBoxGroupLabel>
+          : null}
+          {showGroupSubLabel(groupName) && groupConfig?.subtitle ?
+            <ReqoreP
+              size='small'
+              effect={{ opacity: 0.6 }}
+              style={{
+                marginTop: 2,
+                marginBottom: 8,
+                marginLeft: GROUP_INDENT,
+                paddingRight: 10,
+              }}
+            >
+              {groupConfig.subtitle}
+            </ReqoreP>
+          : null}
+          {renderGroupRows(rows)}
+        </React.Fragment>
+      );
+    };
+
     return (
       <OptionsContext.Provider value={{ schema: options, value: availableOptions }}>
         <CompactRowContext.Provider value={compactRowContextValue}>
@@ -2855,6 +3061,10 @@ const FormEngineImpl = ({
                 $flush={compactFlush || compactNested}
               >
                 <StyledCompactPanel
+                  // Mirrors the toolbar's own search-row gate: when no search
+                  // row renders, the header is a thin strip and sits tight to
+                  // the first status box (see StyledCompactPanel).
+                  $tightHeader={!(compactToolbarParts?.search && size(availableOptions) > 1)}
                   // The top-level form scrolls, so its toolbar STICKS and carries a
                   // dark blurred backdrop so content ghosts cleanly beneath it. A
                   // nested (arg_schema) sub-form owns no scroll context — drop the
@@ -2893,6 +3103,54 @@ const FormEngineImpl = ({
                     const groupsInBox = bucketGroups[box.key];
                     const count = bucketCount(box.key);
                     if (!count) return null;
+                    const hasPreselectedRows = boxHasPreselectedRows(box.key);
+                    const wouldCollapse =
+                      compactCollapsedGroups.includes(box.key) &&
+                      !query &&
+                      !(box.key === 'optional' && onlyOptionalRows);
+                    // Only a box that was opened SOLELY to reveal a preselected
+                    // row splits its body; a box that renders open anyway shows
+                    // all of its groups as before.
+                    const splitForPreselected = wouldCollapse && hasPreselectedRows;
+
+                    // Which rows this box shows, and which fold away, decided at
+                    // ROW level because `maxFieldsShown` counts fields — a
+                    // group-level split can only ever cut at a group boundary.
+                    // Group order is preserved so the visible rows read in the
+                    // same order they would if nothing were folded.
+                    const orderedRows: TRowEntry[] = groupsInBox.flatMap(
+                      (groupName) => buckets[box.key][groupName] || []
+                    );
+                    // Optional's own rule first: a box opened solely to reveal
+                    // preselected rows offers those, not an arbitrary first-N.
+                    const candidateRows =
+                      splitForPreselected ? orderedRows.filter(isPreselectedRow) : orderedRows;
+                    // …then the cap applies to whatever that left.
+                    const capped =
+                      maxFieldsShown !== undefined && candidateRows.length > maxFieldsShown;
+                    const shownRows = capped ? candidateRows.slice(0, maxFieldsShown) : candidateRows;
+                    const shownRowSet = new Set(shownRows.map((entry) => entry.name));
+                    // Everything the box holds that is not on show. Once the
+                    // reader asks for more they get the whole box — withholding
+                    // the non-preselected remainder behind a second control is
+                    // the same defect one level down.
+                    const deferredRowSet = new Set(
+                      orderedRows
+                        .filter((entry) => !shownRowSet.has(entry.name))
+                        .map((entry) => entry.name)
+                    );
+                    const deferredCount = deferredRowSet.size;
+                    const shownGroups = groupsInBox.filter((groupName) =>
+                      (buckets[box.key][groupName] || []).some((entry) =>
+                        shownRowSet.has(entry.name)
+                      )
+                    );
+                    const deferredGroups = groupsInBox.filter((groupName) =>
+                      (buckets[box.key][groupName] || []).some(
+                        (entry) => !shownRowSet.has(entry.name)
+                      )
+                    );
+                    const moreOpen = Boolean(query) || expandedMoreBoxes.includes(box.key);
                     const accent =
                       box.key === 'attention' ? cWarning
                       : box.key === 'set' ? cSuccess
@@ -2921,24 +3179,33 @@ const FormEngineImpl = ({
                         minimal
                         collapseButtonProps={{ flat: true, minimal: true, size: 'small' }}
                         collapsible
-                        // The Optional box now holds every not-yet-added field, so
-                        // it starts COLLAPSED to keep the form focused on what's in
-                        // use. But a SEARCH must surface matching addable fields —
-                        // and ReqorePanel unmounts collapsed content — so force it
-                        // open whenever a query is active. (isCollapsed is the
-                        // panel's controllable state; manual toggling still works
-                        // when no query is set.)
-                        // The Optional box starts collapsed so a form opens on what
-                        // is in use — but only when there IS something else to
-                        // open on. When every field is optional it is the whole
-                        // form, and collapsing it renders a card that looks empty
-                        // and broken: an auth profile's Authorization block, whose
-                        // nine requirement fields are all optional, showed as a
-                        // titled card containing one collapsed "Optional 9" strip
-                        // and nothing else. A search still forces it open
-                        // (ReqorePanel unmounts collapsed content, so a match
-                        // inside it would be unreachable otherwise).
-                        isCollapsed={box.key === 'optional' && !query && !onlyOptionalRows}
+                        // Which boxes start closed is the consumer's call
+                        // (`compactCollapsedGroups`, default `['optional']`: the
+                        // Optional box holds every not-yet-added field, so a form
+                        // opens on what is in use). Two rules override it:
+                        //
+                        // A SEARCH forces every box open — ReqorePanel unmounts
+                        // collapsed content, so a match inside a closed box would
+                        // be unreachable. (isCollapsed is the panel's controllable
+                        // state; manual toggling still works with no query set.)
+                        //
+                        // The Optional box stays open when it is the ONLY box,
+                        // because collapsing it renders a card that looks empty and
+                        // broken: an auth profile's Authorization block, whose nine
+                        // requirement fields are all optional, showed as a titled
+                        // card containing one collapsed "Optional 9" strip and
+                        // nothing else. This does not generalise to the other two —
+                        // a lone Set box collapsed is a deliberate ask, and its
+                        // header still reports what is in there.
+                        //
+                        // A PRESELECTED row overrides it too: the schema asked
+                        // for that field to be visible on a new form, so the
+                        // box it lands in opens. The groups it does NOT appear
+                        // in stay behind an inner collapse below, so opening
+                        // the box reveals the preselected fields without also
+                        // dumping every not-yet-added optional field on the
+                        // author.
+                        isCollapsed={wouldCollapse && !hasPreselectedRows}
                         label={
                           <StyledGroupHeader>
                             <ReqoreP effect={{ weight: 'bold' }} size='normal'>
@@ -2969,35 +3236,51 @@ const FormEngineImpl = ({
                           $success={cSuccess}
                           $rowBg={cRowBg}
                           $lineColor={cGroupLine}
+                          $moreBorder={cMoreBorder}
                           className={compactNarrow ? 'readfirst-narrow' : undefined}
                         >
-                          {groupsInBox.map((groupName) => {
-                            const groupConfig = groups?.[groupName];
-                            return (
-                              <React.Fragment key={groupName}>
-                                {showGroupSubLabel(groupName) ?
-                                  <StyledStatusBoxGroupLabel>
-                                    {getOptionGroupLabel(groupName, groups)}
-                                  </StyledStatusBoxGroupLabel>
-                                : null}
-                                {showGroupSubLabel(groupName) && groupConfig?.subtitle ?
-                                  <ReqoreP
-                                    size='small'
-                                    effect={{ opacity: 0.6 }}
-                                    style={{
-                                      marginTop: 2,
-                                      marginBottom: 8,
-                                      marginLeft: GROUP_INDENT,
-                                      paddingRight: 10,
-                                    }}
-                                  >
-                                    {groupConfig.subtitle}
-                                  </ReqoreP>
-                                : null}
-                                {renderGroupRows(buckets[box.key][groupName])}
-                              </React.Fragment>
-                            );
-                          })}
+                          {shownGroups.map((groupName) =>
+                            renderBoxGroup(box.key, groupName, shownRowSet)
+                          )}
+                          {/* The control lives INSIDE the group body, as the last
+                              row, so it inherits the rows' grid, padding and
+                              hover and lines up with them. Outside it was a bare
+                              line of text in the box's corner, which is what the
+                              build #154 review rejected. */}
+                          {deferredCount ?
+                            <button
+                              type='button'
+                              className='readfirst-row readfirst-more-row options-readfirst-more'
+                              aria-expanded={moreOpen}
+                              onClick={() =>
+                                setExpandedMoreBoxes((prev) =>
+                                  prev.includes(box.key) ?
+                                    prev.filter((k) => k !== box.key)
+                                  : [...prev, box.key]
+                                )
+                              }
+                            >
+                              <ReqoreP size='small' effect={{ opacity: 0.8 }}>
+                                {moreOpen ?
+                                  'Show fewer'
+                                : `${deferredCount} more ${box.key === 'optional' ? 'optional ' : ''}field${deferredCount === 1 ? '' : 's'}`
+                                }
+                              </ReqoreP>
+                              <ReqoreIcon
+                                icon='ArrowDownSLine'
+                                size='small'
+                                className='readfirst-more-chevron'
+                                effect={{ opacity: 0.8 }}
+                              />
+                            </button>
+                          : null}
+                          {/* A search forces the fold open for the same reason
+                              the boxes open: an unmounted row cannot be found. */}
+                          {deferredCount && moreOpen ?
+                            deferredGroups.map((groupName) =>
+                              renderBoxGroup(box.key, groupName, deferredRowSet)
+                            )
+                          : null}
                         </StyledGroupBody>
                       </StyledStatusBox>
                     );