@qoretechnologies/reqraft 0.10.36 → 0.10.37-pr.95.g4e65c57

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,
@@ -2494,9 +2577,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[] = [];
@@ -2649,6 +2763,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 },
@@ -2671,6 +2790,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
@@ -2679,6 +2801,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);
@@ -2783,6 +2909,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' }}

package/src/components/form/engine/_structuredData/SchemaDataView.stories.tsx

@@ -0,0 +1,129 @@
+import { Meta, StoryObj } from '@storybook/react-vite';
+import { expect } from 'storybook/test';
+import { SchemaDataView } from './SchemaDataView';
+
+/**
+ * The read-only rendering of a value described by an `arg_schema`.
+ *
+ * Rendered directly here rather than through a whole FormEngine: these stories
+ * are about what the VIEW does with a described value, and mounting a form
+ * around it only adds chrome that the form's own stories already cover.
+ */
+const meta: Meta<typeof SchemaDataView> = {
+  title: 'Form/Engine/SchemaDataView',
+  component: SchemaDataView,
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Auth-profile schemes: the first field is a CHOICE, so its heading is prose. */
+const SchemeSchema = {
+  type: {
+    type: 'string',
+    display_name: 'Scheme Type',
+    allowed_values: [
+      { value: 'default', display_name: 'Default RBAC' },
+      { value: 'cookie', display_name: 'Cookie' },
+    ],
+  },
+  cookie_name: { type: 'string', display_name: 'Session Cookie Name' },
+  redirect_url: { type: 'string', display_name: 'Redirect URL' },
+} as never;
+
+const schemeValue = [
+  { type: 'hash', value: { type: 'default' } },
+  {
+    type: 'hash',
+    value: {
+      type: 'cookie',
+      cookie_name: 'qorus-session',
+      redirect_url: 'https://example.com/login',
+    },
+  },
+];
+
+/** Service methods: the first field is a LITERAL, so its heading is mono. */
+const MethodSchema = {
+  name: { type: 'string', display_name: 'Method Name' },
+  desc: { type: 'string', display_name: 'Description' },
+} as never;
+
+const methodValue = [
+  { type: 'hash', value: { name: 'init', desc: 'init method' } },
+  { type: 'hash', value: { name: 'onOrderStatus', desc: 'returns the status of a single order' } },
+  { type: 'hash', value: { name: 'onConnect', desc: 'connection lifecycle hook' } },
+];
+
+const colors = { key: '#f1f0ee', muted: '#a0a0a0', border: '#a0a0a066', accent: '#3b8eea' };
+
+export const Schemes: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'A described list whose identifying field is a choice — each item is headed by the display name of that choice, in prose.',
+      },
+    },
+  },
+  args: { value: schemeValue, schema: SchemeSchema, colors },
+  play: async ({ canvasElement }) => {
+    const titles = [...canvasElement.querySelectorAll('.schema-view-item-title')].map((element) =>
+      (element.textContent ?? '').trim()
+    );
+    await expect(titles).toEqual(['Default RBAC', 'Cookie']);
+  },
+};
+
+export const ServiceMethods: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "A described list whose identifying field is a literal — each item is headed by the method's name, which keeps the mono face it has as a value.",
+      },
+    },
+  },
+  args: { value: methodValue, schema: MethodSchema, colors },
+  play: async ({ canvasElement }) => {
+    await expect(canvasElement.querySelectorAll('.schema-view-item-title')).toHaveLength(3);
+  },
+};
+
+export const Undescribed: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Keys the schema does not describe are still shown, under their raw name, after the described ones — a preview that dropped data would be worse than a raw tree.',
+      },
+    },
+  },
+  args: {
+    value: [{ type: 'hash', value: { type: 'cookie', legacy_flag: 'kept' } }],
+    schema: SchemeSchema,
+    colors,
+  },
+  play: async ({ canvasElement }) => {
+    await expect(canvasElement.textContent).toContain('legacy_flag');
+
+    // A field name renders on ONE line. The label column is measured from the
+    // longest name, and the label carries `overflow-wrap: anywhere` — so an
+    // under-measured column does not ellipsise, it breaks the name in half.
+    // That is exactly what happened when the labels became uppercase and the
+    // measurement was still in `ch`, which knows nothing about the tracking:
+    // `LEGACY_FLAG` came out over two lines.
+    //
+    // Asserted as geometry rather than as a width, because the width is the
+    // thing that keeps being wrong — the invariant is that the name fits.
+    const label = [...canvasElement.querySelectorAll<HTMLElement>('.schema-view-fields > *')].find(
+      (element) => (element.textContent ?? '').trim().toLowerCase() === 'legacy_flag'
+    );
+
+    await expect(label).toBeTruthy();
+
+    const lineHeight = parseFloat(getComputedStyle(label!).lineHeight) || 16;
+
+    await expect(label!.offsetHeight).toBeLessThan(lineHeight * 1.6);
+  },
+};