@qoretechnologies/reqraft 0.10.39-pr.99.gdbafa34 → 0.10.39

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,
@@ -107,6 +112,7 @@ import {
 import { OptionsHelpDialog } from './OptionsHelpDialog';
 import {
   TReadFirstStatus,
+  findAllowedValueOption,
   getFirstAttentionOptionName,
   getOptionGroup,
   getOptionGroupLabel,
@@ -119,21 +125,6 @@ import {
 } 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;
@@ -306,9 +297,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
@@ -387,6 +379,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,
@@ -444,13 +453,28 @@ export const fixOptions = (
         };
       }
 
+      // A value that is not one of the declared choices is dropped. What counts
+      // as "one of the choices" is `findAllowedValueOption` — the same predicate
+      // the read-first row uses to LABEL a value — because a value the row can
+      // name is by definition a value the form must keep. Inlining a narrower
+      // test here (envelope and `name`, but not a bare `value`) silently erased
+      // 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?.find(
-          (allowedValue: any) =>
-            allowedValue.value?.value === newOption.value || allowedValue.name === newOption.value
-        ) &&
+        options?.[optionName]?.allowed_values?.length &&
+        !findAllowedValueOption(newOption.value, options?.[optionName]) &&
         !isValueTemplate(newOption.value) &&
         !options?.[optionName]?.multiselect &&
         !options?.[optionName]?.allowed_values_creatable
@@ -635,37 +659,6 @@ 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>;
@@ -761,6 +754,27 @@ export interface IFormEngineProps extends Omit<IReqoreCollectionProps, 'onChange
    */
   autoFocusFirstRequired?: boolean;
 
+  /**
+   * Opt-in: on mount, OPEN the first row that needs attention — without taking
+   * focus.
+   *
+   * `autoFocusFirstRequired` fuses two decisions that are not the same: which
+   * row is open (layout) and where the caret is (focus). Focus is the half that
+   * can be stolen, so that flag waits for focus to be free — and a form mounted
+   * BY a click never sees free focus, because the button that mounted it still
+   * has it. Adding a list item is exactly that case: the row the author must
+   * fill stayed shut behind a second click, and the flag that exists to prevent
+   * it could not fire.
+   *
+   * Opening a row takes nothing from the user, so this half needs no guard. Use
+   * it where the mount is already the answer to a deliberate action; use
+   * `autoFocusFirstRequired` where the form is the destination and the caret
+   * should land in it. Setting both keeps the focusing behaviour. Same one-shot
+   * contract: it fires on the first render with focusable content and then never
+   * again for the life of the instance. No-op in classic mode. Default: off.
+   */
+  expandFirstRequired?: boolean;
+
   /**
    * Names of read-first rows to open on mount, in addition to whatever the
    * user opens afterwards.
@@ -811,8 +825,6 @@ const FormEngineImpl = ({
   compactFlush = false,
   compactNested = false,
   compactPanelProps,
-  compactCollapsedGroups = ['optional'],
-  compactToolbar = true,
   commitMode = 'immediate',
   expandMode = 'single',
   onCommit,
@@ -831,6 +843,7 @@ const FormEngineImpl = ({
   rendererOnlyUiTypes,
   inheritedFromParent,
   autoFocusFirstRequired,
+  expandFirstRequired,
   initialExpandedOptions,
   ...rest
 }: IFormEngineProps) => {
@@ -879,6 +892,47 @@ 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[]>([]);
+
+  // --- Reveal a status box's content when it is opened ----------------------
+  //
+  // The status boxes stack, so the last one ("Optional", which holds every
+  // not-yet-added field) sits at the bottom of the form — frequently at the
+  // bottom of the scroll container too. Opening it mounts its rows BELOW the
+  // fold: the box's own header is all that stays on screen, the click appears to
+  // have done nothing, and the fields it just revealed have to be hunted for by
+  // scrolling.
+  //
+  // The box that was just opened, read by the layout effect below. Held as state
+  // rather than acted on inside the collapse handler because the handler runs
+  // BEFORE React re-renders — at that moment the rows do not exist yet, so the
+  // 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.
+  const [openedStatusBox, setOpenedStatusBox] = useState<string | undefined>(undefined);
+  const statusBoxRefs = useRef<Record<string, HTMLDivElement | null>>({});
+  useLayoutEffect(() => {
+    if (!openedStatusBox) {
+      return;
+    }
+    const element = statusBoxRefs.current[openedStatusBox];
+    // Consume it either way: a box that has gone (a search narrowed it out of
+    // existence) must not leave a pending reveal armed for a later render.
+    setOpenedStatusBox(undefined);
+    // `scrollIntoView` is not implemented in jsdom, and a missing reveal must
+    // never break a form.
+    if (!element?.scrollIntoView) {
+      return;
+    }
+    // 'nearest' scrolls the MINIMUM needed: nothing at all when the box is
+    // already fully visible, and a top-alignment when it is taller than the
+    // viewport (header plus the first rows — the right answer for a long
+    // Optional list). Anything else moves the page when it did not need to.
+    element.scrollIntoView({
+      block: 'nearest',
+      behavior:
+        window.matchMedia?.('(prefers-reduced-motion: reduce)')?.matches ? 'auto' : 'smooth',
+    });
+  }, [openedStatusBox]);
   // Remembers each row's last settled status box, so an actively-edited field
   // stays put when its status flips (e.g. becomes valid) instead of jumping to
   // another box mid-edit and stealing focus. Keyed by option name.
@@ -1911,7 +1965,11 @@ const FormEngineImpl = ({
   // (or below-the-fold) form is never scrolled into view on mount.
   const autoFocusNameRef = useRef<string | undefined>(undefined);
   useEffect(() => {
-    if (!autoFocusFirstRequired || !compact || !options) {
+    // Two decisions, one scan. `autoFocusFirstRequired` opens the row AND puts
+    // the caret in it; `expandFirstRequired` only opens it. Setting both keeps
+    // the focusing behaviour, since focusing implies opening.
+    const wantsFocus = !!autoFocusFirstRequired;
+    if ((!wantsFocus && !expandFirstRequired) || !compact || !options) {
       return;
     }
     if (hasAutoFocusedRef.current) {
@@ -1929,8 +1987,14 @@ const FormEngineImpl = ({
     // clean mount focus rests on the body, so the intended "drop into the first
     // field" still fires. Bailing here leaves `hasAutoFocusedRef` false, so it
     // retries once focus is free.
+    //
+    // Only the FOCUSING variant waits: opening a row moves no caret, so there is
+    // nothing to steal and nothing to wait for. Making the expand-only variant
+    // wait here would make it a no-op in its main use — a sub-form mounted by a
+    // click, where the button that mounted it still holds focus and never gives
+    // it up.
     const active = document.activeElement as HTMLElement | null;
-    if (active && active !== document.body) {
+    if (wantsFocus && active && active !== document.body) {
       return;
     }
 
@@ -1958,7 +2022,10 @@ const FormEngineImpl = ({
 
     if (target) {
       // Set the ref before the state update so CompactRow's focus timer sees it.
-      autoFocusNameRef.current = target;
+      // Expand-only leaves it unset, which is what keeps the caret where it is.
+      if (wantsFocus) {
+        autoFocusNameRef.current = target;
+      }
       setExpandedOptions((prev) =>
         prev.includes(target) ? prev
         : expandMode === 'multi' ? [...prev, target]
@@ -1967,6 +2034,7 @@ const FormEngineImpl = ({
     }
   }, [
     autoFocusFirstRequired,
+    expandFirstRequired,
     compact,
     options,
     availableOptions,
@@ -2468,14 +2536,6 @@ 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,
@@ -2484,7 +2544,6 @@ const FormEngineImpl = ({
       completion: readFirstCompletion,
       showInvalidOnly: showInvalidOptionsOnly,
       onToggleInvalidOnly: handleToggleInvalidOnly,
-      parts: compactToolbarParts ?? { completion: false, search: false, fields: false, help: false },
       hasMultipleOptions: size(availableOptions) > 1,
       compactQuery,
       setCompactQuery,
@@ -2535,14 +2594,10 @@ 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. Only `compactToolbar={false}`
-  // removes it, and then the header carries just the consumer's own actions.
+  // knock the form's toolbar out of the header.
   const compactHeaderActions = useMemo(
-    () => [
-      ...(compactToolbarParts ? [{ as: CompactToolbar, responsive: false }] : []),
-      ...(compactPanelProps?.actions || []),
-    ],
-    [compactPanelProps?.actions, compactToolbarParts]
+    () => [{ as: CompactToolbar, responsive: false }, ...(compactPanelProps?.actions || [])],
+    [compactPanelProps?.actions]
   );
   const renderCompact = () => {
     const headerBg = `${changeDarkness(getMainBackgroundColor(theme), 0.02)}${percentToHexAlpha(88)}`;
@@ -2555,9 +2610,40 @@ const FormEngineImpl = ({
       if (requiredOnly && !(schema?.required || schema?.required_groups)) {
         return false;
       }
-      return matchesQuery(optionName);
+      // A field that absorbs a sibling also answers for it: searching
+      // "language" has to surface the row that now holds the language control,
+      // or the field becomes unreachable through the filter.
+      if (matchesQuery(optionName)) return true;
+      const absorb = (schema as { absorb_fields?: string[] } | undefined)?.absorb_fields;
+      return !!absorb?.some((absorbedName) => matchesQuery(absorbedName));
     };
 
+    // Fields a sibling absorbs into its own container.
+    //
+    // A field declaring `absorb_fields: ['language']` renders that sibling's
+    // control inside its own row instead of letting it have a row of its own.
+    // The pair this exists for is a code editor and its language: they are one
+    // decision — "what is this code, and in what language" — and reading them
+    // as two unrelated rows one above the other is what the layout used to say.
+    //
+    // Absorbed fields stay in `grouped`, and therefore in the Set / Optional /
+    // Needs-attention counts and in the completion meter. Only the ROW is
+    // skipped. Dropping them from the buckets instead would leave the meter
+    // ("13/18 set", computed from `availableOptions`) disagreeing with the box
+    // badge beside it, which counts row entries.
+    const absorbedBy: Record<string, string> = {};
+    forEach(options, (option, optionName) => {
+      const absorb = (option as { absorb_fields?: string[] } | undefined)?.absorb_fields;
+      if (!absorb?.length) return;
+      absorb.forEach((absorbedName) => {
+        // Only absorb a sibling that exists and is not already spoken for; a
+        // schema naming a missing field must not make the field disappear.
+        if (options?.[absorbedName] && !absorbedBy[absorbedName]) {
+          absorbedBy[absorbedName] = optionName;
+        }
+      });
+    });
+
     // Group the options by their raw `group` key, remembering the order groups
     // first appear in the schema. Each row carries a `hidden` flag.
     const groupOrder: string[] = [];
@@ -2646,16 +2732,17 @@ 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 };
-    const buckets: Record<TFormEngineBoxKey, Record<string, TRowEntry[]>> = {
+    type TBucketKey = 'attention' | 'set' | 'optional';
+    const buckets: Record<TBucketKey, Record<string, TRowEntry[]>> = {
       attention: {},
       set: {},
       optional: {},
     };
-    const bucketGroups: Record<TFormEngineBoxKey, string[]> = { attention: [], set: [], optional: [] };
+    const bucketGroups: Record<TBucketKey, 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): TFormEngineBoxKey => {
+    const stableBucketOf = (entry: TRowEntry): TBucketKey => {
       const fresh = getOptionBucket(entry.name, entry.hidden);
       const groupBeingEdited =
         !entry.hidden &&
@@ -2679,7 +2766,7 @@ const FormEngineImpl = ({
         buckets[b][groupName].push(entry);
       });
     });
-    const bucketCount = (b: TFormEngineBoxKey) =>
+    const bucketCount = (b: TBucketKey) =>
       bucketGroups[b].reduce((n, g) => n + buckets[b][g].length, 0);
 
     // "Is the Optional box the whole form?" — when nothing needs attention and
@@ -2695,7 +2782,7 @@ const FormEngineImpl = ({
     const showGroupSubLabel = (groupName: string) =>
       (groupName !== 'general' && groupName !== 'optional') || !!groups?.[groupName];
     const STATUS_BOXES: Array<{
-      key: TFormEngineBoxKey;
+      key: TBucketKey;
       label: string;
       intent?: 'warning' | 'success';
       icon: IReqoreIconName;
@@ -2709,6 +2796,11 @@ const FormEngineImpl = ({
     // together at the first member's slot and rendered as a connected rail (flat
     // rows — no wrapper — so the value surface applies normally; the rail + nodes
     // are drawn per member). Narrow stacks fall back to flat rows.
+    // The absorbed siblings a host row must render, in schema order. Empty for
+    // every row that absorbs nothing, which is all of them by default.
+    const absorbedNamesFor = (hostName: string): string[] =>
+      Object.keys(absorbedBy).filter((absorbedName) => absorbedBy[absorbedName] === hostName);
+
     const renderGroupRows = (names: Array<{ name: string; hidden: boolean }>) => {
       const renderRow = (
         entry: { name: string; hidden?: boolean },
@@ -2731,6 +2823,9 @@ const FormEngineImpl = ({
           clustered={clustered}
           clusterFirst={clusterFirst}
           clusterLast={clusterLast}
+          // The siblings this row renders inside itself instead of leaving
+          // them a row of their own — see `absorbedBy`.
+          absorbedFields={absorbedNamesFor(entry.name)}
         />
       );
       // (Clustering runs in narrow mode too now — the "One of the below is
@@ -2739,6 +2834,10 @@ const FormEngineImpl = ({
       const emitted = new Set<string>();
       const groupOf = (name: string) =>
         (options?.[name]?.required_groups as string[] | undefined)?.[0];
+      // An absorbed field keeps its place in the buckets — so the Set /
+      // Optional counts and the completion meter still see it — but its host
+      // renders its control, so it gets no row of its own here.
+      names = names.filter((entry) => !absorbedBy[entry.name]);
       return names.map((entry) => {
         const grp = groupOf(entry.name);
         if (!grp) return renderRow(entry, false);
@@ -2843,33 +2942,36 @@ const FormEngineImpl = ({
                         $accent={accent}
                         $bg={boxBg}
                         key={box.key}
+                        ref={(node: HTMLDivElement | null) => {
+                          statusBoxRefs.current[box.key] = node;
+                        }}
+                        // Opening arms the reveal; collapsing disarms it, so a
+                        // close never scrolls.
+                        onCollapseChange={(collapsed) =>
+                          setOpenedStatusBox(collapsed ? undefined : box.key)
+                        }
                         flat
                         minimal
                         collapseButtonProps={{ flat: true, minimal: true, size: 'small' }}
                         collapsible
-                        // 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.
-                        isCollapsed={
-                          compactCollapsedGroups.includes(box.key) &&
-                          !query &&
-                          !(box.key === 'optional' && onlyOptionalRows)
-                        }
+                        // 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}
                         label={
                           <StyledGroupHeader>
                             <ReqoreP effect={{ weight: 'bold' }} size='normal'>