@qoretechnologies/reqraft 0.10.36 → 0.10.38-pr.95.gf1f6403

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

@@ -1164,7 +1164,7 @@ export const NestedOptionInheritsRenderPropFromAncestorCompact: Story = {
     docs: {
       description: {
         story:
-          "Renders the NestedOptionInheritsRenderPropFromAncestor schema with compact=true — the compact renderer summarises the list-of-hash rows as 'init, run' rather than [object Object].",
+          "Renders the NestedOptionInheritsRenderPropFromAncestor schema with compact=true — the compact renderer previews the list-of-hash rows through their arg_schema, naming each method, rather than printing [object Object].",
       },
     },
   },
@@ -1229,11 +1229,13 @@ export const NestedOptionInheritsRenderPropFromAncestorCompact: Story = {
     await waitFor(() => expect(canvas.getAllByText('Methods').length).toBeGreaterThan(0), {
       timeout: 5000,
     });
-    // The list-of-hashes value summarises by the items' names — never a raw
-    // "[object Object]" (regression: it used to stringify each hash envelope).
-    await expect(
-      await canvas.findByText('init, run', undefined, { timeout: 5000 })
-    ).toBeInTheDocument();
+    // The list-of-hashes value names its items — never a raw "[object Object]"
+    // (regression: it used to stringify each hash envelope). The names now come
+    // from the schema preview rather than a joined summary line above it, so the
+    // assertion moved with them; what must never come back is the stringified
+    // envelope.
+    await expect(await canvas.findByText('init', undefined, { timeout: 5000 })).toBeInTheDocument();
+    await expect(await canvas.findByText('run')).toBeInTheDocument();
     await expect(canvasElement.textContent ?? '').not.toContain('[object Object]');
   },
 };
@@ -1290,12 +1292,15 @@ export const CompactNestedListRowsStayCompact: Story = {
     } as unknown as IOptionsSchema,
   },
   play: async ({ canvasElement }) => {
-    // Collapsed, the row summarises by the items' names.
-    await _testsWaitForText('init, run');
+    // Collapsed, the row previews its items through their schema — one numbered
+    // entry per method, each naming itself.
+    await _testsWaitForText('Method Name');
+    await _testsWaitForText('init');
 
     // Open the Methods row — this mounts ArrayAuto and, with it, one
-    // arg_schema sub-form per row.
-    await _testsClickText('init, run');
+    // arg_schema sub-form per row. Clicked by the field's NAME: the joined
+    // summary that used to sit on this row is gone, replaced by the preview.
+    await _testsClickText('Methods');
 
     await waitFor(
       () => expect(canvasElement.querySelectorAll('.array-auto-item')).toHaveLength(2),
@@ -1347,8 +1352,8 @@ export const CompactNestedListRowsStayCompactMobile: Story = {
     ),
   ],
   play: async ({ canvasElement }) => {
-    await _testsWaitForText('init, run');
-    await _testsClickText('init, run');
+    await _testsWaitForText('init');
+    await _testsClickText('Methods');
 
     await waitFor(
       () => expect(canvasElement.querySelectorAll('.array-auto-item')).toHaveLength(2),
@@ -4122,6 +4127,29 @@ export const CompactFieldTypes: Story = {
           secure: { type: 'bool', display_name: 'Secure' },
         },
       },
+      // The list counterpart of `connectionInfo`: a list of hashes whose fields
+      // are declared. This is the shape the schema preview was built for, and the
+      // catalogue was missing it — it covered the described HASH but not the
+      // described LIST, which is the case that was actually reported.
+      routes: {
+        type: 'list',
+        ui_type: 'list',
+        element_type: 'hash',
+        display_name: 'List of hashes (arg_schema)',
+        group: 'structured',
+        arg_schema: {
+          method: {
+            type: 'string',
+            display_name: 'Method',
+            allowed_values: [
+              { value: 'get', display_name: 'GET' },
+              { value: 'post', display_name: 'POST' },
+            ],
+          },
+          path: { type: 'string', display_name: 'Path' },
+          handler: { type: 'string', ui_type: 'code-editor', display_name: 'Handler' },
+        },
+      },
       freeConfig: {
         type: 'free-hash',
         ui_type: 'free-hash',
@@ -4330,6 +4358,22 @@ export const CompactFieldTypes: Story = {
           secure: { type: 'bool', value: true },
         },
       },
+      routes: {
+        type: 'list',
+        value: [
+          // One item complete, one with the optional field unset — the empty
+          // state stays exercised rather than being filled in everywhere.
+          {
+            type: 'hash',
+            value: {
+              method: 'get',
+              path: '/orders',
+              handler: 'sub get_orders() {\n    return orders.all();\n}',
+            },
+          },
+          { type: 'hash', value: { method: 'post', path: '/orders' } },
+        ],
+      },
       freeConfig: { type: 'free-hash', value: '%YAML 1.2\n---\nretries: 3\ntimeout: 30\n' },
       bigConfig: {
         type: 'hash',
@@ -4412,7 +4456,23 @@ export const CompactFieldTypes: Story = {
     await _testsWaitForText('#0000FF'); // colour → uppercase hex
     await _testsWaitForText('rgba(255, 0, 0, 0.5)'); // colour with alpha → rgba()
     await _testsWaitForText('config.txt'); // file → filename
-    await _testsWaitForText('3 fields'); // structured hash → field count summary
+    // A hash the schema DESCRIBES needs no count: its preview names every field,
+    // so "3 fields" above "Host / Port / Secure" would be the same fact twice.
+    // A hash it does not describe keeps the count — the untyped tree beneath it
+    // says nothing about what the value means, so the count is the only line
+    // that does. Both halves asserted here: the distinction IS the behaviour.
+    await _testsWaitForText('2 fields'); // undescribed hash → field count summary
+    await _testsWaitForText('Host'); // described hash → its fields, by name
+    await _testsWaitForTextToNotExist('3 fields');
+
+    // Described LIST of hashes: numbered items, labels by display_name, and the
+    // allowed value read back as its label rather than the stored `get`.
+    await _testsWaitForText('Path');
+    await _testsWaitForText('/orders');
+    await _testsWaitForText('GET');
+    // A code sub-field renders AS code, not as a flattened mono line.
+    await _testsWaitForText('Handler');
+    await _testsWaitForText(/sub get_orders/);
     await _testsWaitForText('order-to-invoice'); // interface reference → raw value
 
     // Field stack (merged from dpql): byte-size shows its value string; the
@@ -5915,3 +5975,243 @@ export const CompactRowMarkdownWithoutRenderer: Story = {
     expect(descText).not.toContain('**');
   },
 };
+
+/**
+ * The auth-profile scheme sub-schema, which is where all three of the list-row
+ * affordances below were reported. One required choice with named allowed
+ * values, one field that belongs to a single choice.
+ */
+const AuthSchemeArgSchema = {
+  type: {
+    type: 'string',
+    ui_type: 'string',
+    display_name: 'Scheme Type',
+    short_desc: 'Authentication scheme type',
+    required: true,
+    allowed_values: [
+      { value: 'default', display_name: 'Default RBAC' },
+      { value: 'cookie', display_name: 'Cookie' },
+      { value: 'oauth2', display_name: 'OAuth2' },
+    ],
+  },
+  cookie_name: {
+    type: 'string',
+    ui_type: 'string',
+    display_name: 'Session Cookie Name',
+    short_desc: 'Applies to the Cookie scheme alone',
+    depends_on: ['type=cookie'],
+  },
+} as unknown as IOptionsSchema;
+
+const AuthSchemeOptions = {
+  schemes: {
+    type: 'list',
+    ui_type: 'list',
+    element_type: 'hash',
+    display_name: 'Authentication Schemes',
+    short_desc: 'Schemes tried in order, first match wins',
+    required: true,
+    arg_schema: AuthSchemeArgSchema,
+  },
+} as unknown as IOptionsSchema;
+
+/**
+ * A list-of-hash row reads back in the words the form asked for the value.
+ *
+ * Reported on an auth profile: the row summarised as "2 items" and its preview
+ * printed a data tree — "Object · 1 field" over `type: default`. Both are
+ * exactly what is stored, and neither is a string the author has ever seen: the
+ * form calls that key "Scheme Type" and that value "Default RBAC". A row meant
+ * to confirm a choice showed a value nobody had chosen, in a shape nobody had
+ * asked about.
+ *
+ * A generic data view has to announce what it found, because inference is all it
+ * has. A field with an `arg_schema` needs none of that — the shape, the names and
+ * the choices are known before the value arrives — so the preview renders
+ * THROUGH the schema (`SchemaDataView`) and the summary resolves through the
+ * same one. The row, the preview and the editor cannot describe a value three
+ * ways.
+ */
+export const CompactListOfHashReadsInSchemaWords: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'A list-of-hash option whose sub-schema names its fields and values. The collapsed row summarises by those names ("Default RBAC, Cookie") and the preview renders as labelled schema rows — "Scheme Type · Default RBAC" per numbered item — instead of an untyped data tree over the stored `type: default`.',
+      },
+    },
+  },
+  args: {
+    compact: true,
+    minColumnWidth: '300px',
+    options: AuthSchemeOptions,
+    value: {
+      schemes: {
+        type: 'list',
+        value: [
+          { type: 'hash', value: { type: 'default' } },
+          { type: 'hash', value: { type: 'cookie', cookie_name: 'qorus-session' } },
+        ],
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    // The preview IS the value here — the row prints no summary line above it.
+    // A joined "Default RBAC, Cookie" directly over a preview that names both
+    // items is the same facts twice, the lossy version first.
+    const preview = await waitFor(() => {
+      const element = canvasElement.querySelector('.schema-data-view');
+      expect(element).toBeTruthy();
+      return element!;
+    });
+    const text = preview.textContent ?? '';
+    expect(text).toContain('Scheme Type');
+    expect(text).toContain('Default RBAC');
+    expect(text).toContain('Session Cookie Name');
+
+    // Nothing announces the container's shape — that is the tell of a renderer
+    // guessing at data it has not been told about.
+    expect(text).not.toMatch(/Object\b/);
+    expect(text).not.toMatch(/\d+ fields?\b/);
+
+    // The joined summary is gone from the row, and it is the ROW that has to be
+    // checked: the same words still exist inside the preview, so asserting on
+    // the whole canvas would pass whether or not the line was removed.
+    const valueLine = canvasElement.querySelector(
+      '[data-field="schemes"] .options-readfirst-valuetext'
+    );
+    expect(valueLine?.textContent ?? '').not.toBe('Default RBAC, Cookie');
+
+    // A literal the author typed is set in mono; a chosen label is not.
+    const mono = [...preview.querySelectorAll('.schema-view-data')].map((el) =>
+      (el.textContent ?? '').trim()
+    );
+    expect(mono).toContain('qorus-session');
+    expect(mono).not.toContain('Default RBAC');
+
+    // The stored spellings are what the author never chose, so they must not be
+    // in the preview at all. Substring checks cannot say this — "Scheme Type"
+    // contains "type" and "Default RBAC" contains "default" — so the assertion
+    // is on whole leaf elements: no chip or cell reads exactly `type`,
+    // `cookie_name` or `default`. A substring assertion here passed against a
+    // preview that was still rendering the raw pair.
+    const leafTexts = [...preview.querySelectorAll('*')]
+      .filter((element) => element.children.length === 0)
+      .map((element) => (element.textContent ?? '').trim());
+    expect(leafTexts).toContain('Scheme Type');
+    for (const stored of ['type', 'cookie_name', 'default']) {
+      expect(leafTexts).not.toContain(stored);
+    }
+    expect(canvasElement.textContent ?? '').not.toContain('[object Object]');
+  },
+};
+
+/**
+ * Adding a list item opens the field the item cannot be saved without.
+ *
+ * `+ Add new item for "Authentication Scheme"` added a row whose one required
+ * field sat collapsed, so the author had to find it and click it before the
+ * form could be completed — a second click to reach the only thing the first
+ * click could have meant.
+ *
+ * The engine already had `autoFocusFirstRequired`, and it could not fire here:
+ * it waits for focus to be free so it never steals a caret, and a form mounted
+ * BY a click never sees free focus — the button that mounted it still holds it.
+ * Opening a row and moving the caret are separate decisions, so they are now
+ * separate flags; this one only opens.
+ */
+export const CompactAddedListRowOpensItsRequiredField: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Clicks "Add new item" on a list-of-hash option and shows the new row with its required "Scheme Type" field already open. Rows that were already in the value stay collapsed — only the row just added is opened.',
+      },
+    },
+  },
+  args: {
+    compact: true,
+    minColumnWidth: '300px',
+    options: AuthSchemeOptions,
+    value: {
+      schemes: {
+        type: 'list',
+        value: [{ type: 'hash', value: { type: 'default' } }],
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    // Open the list itself, which mounts the rows and the Add button. Clicked by
+    // FIELD, not by its text: the row no longer prints a summary line, and the
+    // words that remain live inside the preview.
+    await _testsClickText('Authentication Schemes');
+    await waitFor(() => expect(canvasElement.querySelectorAll('.array-auto-item')).toHaveLength(1));
+
+    // The row that was already there is collapsed — this is the state the new
+    // row must NOT be confused with.
+    const isOpen = (element: Element | null | undefined) =>
+      !!element &&
+      (element.classList.contains('readfirst-row-editing') ||
+        element.classList.contains('options-readfirst-card'));
+    const typeRows = () => canvasElement.querySelectorAll('[data-field="type"]');
+    expect([...typeRows()].some(isOpen)).toBe(false);
+
+    await _testsClickButton({ label: 'Add new item for "Authentication Schemes"' });
+
+    await waitFor(() => expect(canvasElement.querySelectorAll('.array-auto-item')).toHaveLength(2));
+    // Exactly one open required field: the one belonging to the row just added.
+    await waitFor(() => expect([...typeRows()].filter(isOpen)).toHaveLength(1));
+  },
+};
+
+/**
+ * The same schema-worded row at a phone-class width.
+ *
+ * The narrow branch is what makes this worth its own story: below 480px the row
+ * stacks the value under the label, so a summary and a preview that were both
+ * rewritten to be READ (rather than decoded) have to survive the stacking
+ * without wrapping into an unreadable column. `compactNarrow` comes from
+ * `useMeasure` on the form's own wrapper, not from a media query, so a narrow
+ * container is the honest way to reach the branch here — the viewport-parameter
+ * rule applies to media-query components, which this is not.
+ */
+export const CompactListOfHashReadsInSchemaWordsMobile: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The schema-worded list-of-hash row at a ~360px width: the summary and the renamed preview stack under the field name and stay legible in one column.',
+      },
+    },
+  },
+  args: CompactListOfHashReadsInSchemaWords.args,
+  decorators: [
+    (StoryComponent: React.ComponentType) => (
+      <div style={{ maxWidth: 360, margin: '0 auto', border: '1px dashed #ffffff22' }}>
+        <StoryComponent />
+      </div>
+    ),
+  ],
+  play: async ({ canvasElement }) => {
+    await _testsWaitForText('Scheme Type');
+
+    // The narrow branch is actually engaged — otherwise this is the desktop
+    // story with a border round it, and it would pass while proving nothing.
+    await waitFor(() =>
+      expect(canvasElement.querySelector('.readfirst-narrow')).toBeTruthy()
+    );
+
+    const preview = await waitFor(() => {
+      const element = canvasElement.querySelector('.schema-data-view');
+      expect(element).toBeTruthy();
+      return element!;
+    });
+    const leafTexts = [...preview.querySelectorAll('*')]
+      .filter((element) => element.children.length === 0)
+      .map((element) => (element.textContent ?? '').trim());
+    expect(leafTexts).toContain('Scheme Type');
+    for (const stored of ['type', 'cookie_name', 'default']) {
+      expect(leafTexts).not.toContain(stored);
+    }
+  },
+};

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

@@ -107,6 +107,7 @@ import {
 import { OptionsHelpDialog } from './OptionsHelpDialog';
 import {
   TReadFirstStatus,
+  findAllowedValueOption,
   getFirstAttentionOptionName,
   getOptionGroup,
   getOptionGroupLabel,
@@ -429,13 +430,18 @@ 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.
       if (
         newOption.value !== undefined &&
         options?.[optionName]?.allowed_values &&
-        !options?.[optionName]?.allowed_values?.find(
-          (allowedValue: any) =>
-            allowedValue.value?.value === newOption.value || allowedValue.name === newOption.value
-        ) &&
+        !findAllowedValueOption(newOption.value, options?.[optionName]) &&
         !isValueTemplate(newOption.value) &&
         !options?.[optionName]?.multiselect &&
         !options?.[optionName]?.allowed_values_creatable
@@ -715,6 +721,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.
@@ -783,6 +810,7 @@ const FormEngineImpl = ({
   rendererOnlyUiTypes,
   inheritedFromParent,
   autoFocusFirstRequired,
+  expandFirstRequired,
   initialExpandedOptions,
   ...rest
 }: IFormEngineProps) => {
@@ -831,6 +859,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.
@@ -1863,7 +1932,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) {
@@ -1881,8 +1954,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;
     }
 
@@ -1910,7 +1989,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]
@@ -1919,6 +2001,7 @@ const FormEngineImpl = ({
     }
   }, [
     autoFocusFirstRequired,
+    expandFirstRequired,
     compact,
     options,
     availableOptions,
@@ -2783,6 +2866,14 @@ 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' }}