@qoretechnologies/reqraft 0.10.43-pr.95.gf7f712f → 0.10.43

package/src/components/form/engine/readFirst.ts

@@ -1,6 +1,11 @@
-import { IQorusFormField, TQorusFormFieldSchema, TQorusType } from '@qoretechnologies/ts-toolkit';
+import {
+  IQorusFormField,
+  IQorusFormSchema,
+  TQorusFormFieldSchema,
+  TQorusType,
+} from '@qoretechnologies/ts-toolkit';
 import { isRendererOnlyUiType } from './rendererTypes';
-import { isUiEncodedValue } from './_structuredData/structuredData';
+import { isEmptyUiEnvelope, isUiEncodedValue } from './_structuredData/structuredData';
 import { renderExpressionToText } from '../expressions/renderExpressionToText';
 import { IExpressionValue } from '../expressions/types';
 import yaml from 'js-yaml';
@@ -195,6 +200,13 @@ export const shouldAutoCollapseCompactOption = (
  * Prefer the matching allowed_values entry's display_name (fallback `name`)
  * over the raw stored value.
  *
+ * A LIST carries its options under `element_allowed_values` — they constrain
+ * each element, not the list itself — so a multi-select that was missing here
+ * printed what it stores rather than what you picked: `orders, batch` for
+ * fields whose picker reads "Orders, Batch". The gap shows worst exactly where
+ * allowed values earn their keep, since the stored form is often not readable
+ * at all (a permission code, `PO_REQUIRE_TYPES`, an app-specific id).
+ *
  * Exported (as `findAllowedValueOption`) because the form engine's value
  * validation has to answer the SAME question — "is this stored value one of the
  * declared choices?" — and answering it differently loses data. An
@@ -210,13 +222,30 @@ export const findAllowedValueOption = (
   value: unknown,
   schema?: TQorusFormFieldSchema
 ): any | undefined => {
-  const s = schema as { allowed_values?: any[]; items?: any[] } | undefined;
-  const options = s?.allowed_values?.length ? s.allowed_values : s?.items;
+  const s = schema as
+    { allowed_values?: any[]; element_allowed_values?: any[]; items?: any[] } | undefined;
+  const options =
+    (s?.allowed_values?.length && s.allowed_values) ||
+    (s?.element_allowed_values?.length && s.element_allowed_values) ||
+    s?.items;
   if (!options?.length) {
     return undefined;
   }
+  // A stored element can be the bare value or the typed `{type, value}`
+  // envelope the form engine round-trips; match either against either.
+  const stored =
+    value && typeof value === 'object' && 'value' in (value as Record<string, unknown>) ?
+      (value as Record<string, unknown>).value
+    : value;
+
   return options.find(
-    (option) => option?.value?.value === value || option?.value === value || option?.name === value
+    (option) =>
+      option?.value?.value === value ||
+      option?.value === value ||
+      option?.name === value ||
+      option?.value?.value === stored ||
+      option?.value === stored ||
+      option?.name === stored
   );
 };
 
@@ -646,12 +675,24 @@ export const getHashEntries = (
     // whose entries are `{ type: 'string', value: 'x' }`) — recognise those by
     // their strict shape (a string `type`, a `value`, and no foreign keys) so
     // the sub-row shows 'x' rather than counting the envelope's own keys.
+    // `'value' in raw` is FALSE for a materialised-but-unset field: `fixOptions`
+    // omits the key entirely when the value is undefined, leaving `{type: 'x'}`.
+    // Requiring `value` therefore classed that envelope as a raw hash VALUE and
+    // counted its own `type` key, so an untouched Runtime Defaults collapsed to
+    // "Timeout (Seconds) 1 field" three times over while the sub-form correctly
+    // said 0/3 set. With a sub-schema present, a `type`-only object is an empty
+    // envelope, never content.
+    // Shared with SchemaDataView, which previews this same value one level
+    // down: two renderers disagreeing about what an unset field looks like is
+    // how the row said "1 field" long after this one stopped.
+    const isEmptyEnvelope = !!subSchema && isEmptyUiEnvelope(raw);
     const isFieldShape =
       (!!subSchema &&
         !!raw &&
         typeof raw === 'object' &&
         !Array.isArray(raw) &&
         'value' in (raw as object)) ||
+      isEmptyEnvelope ||
       isTypedEnvelope(raw);
     const subOption: IQorusFormField =
       isFieldShape ?
@@ -793,3 +834,123 @@ export const getFirstAttentionOptionName = (
 
   return undefined;
 };
+
+/* ------------------------------------------------------------------------- */
+/* Record identity — which field says WHICH item this is                      */
+/*                                                                            */
+/* Lives here, beside the formatters it uses, rather than in the view that    */
+/* first needed it: it is data logic, not rendering, and BOTH list renderers  */
+/* plus their tests import it. Keeping it in `SchemaDataView` dragged React,  */
+/* styled-components and every Reqore component it renders into any module    */
+/* that only wanted to know an item's name — which broke `arrayAutoField`'s   */
+/* mocked-Reqore test the moment the editable list started using it.          */
+/* ------------------------------------------------------------------------- */
+
+/** A UI-encoded value carries its type alongside it; the record's own value is inside. */
+const unwrap = (value: unknown): unknown =>
+  isUiEncodedValue(value) ? (value as { value: unknown }).value : value;
+
+/** Whether a value is worth a row of its own. `false` and `0` are values. */
+export const isSet = (value: unknown): boolean =>
+  value !== undefined && value !== null && value !== '' && !(Array.isArray(value) && !value.length);
+
+/**
+ * The keys to render, in the order to render them: the schema's own order first
+ * (that is the order the form puts the fields in), then anything stored that the
+ * schema does not mention, so undescribed data is shown rather than dropped.
+ */
+export const orderedKeys = (
+  record: Record<string, unknown>,
+  schema: IQorusFormSchema
+): string[] => {
+  const described = Object.keys(schema).filter((key) => isSet(unwrap(record[key])));
+  const extra = Object.keys(record).filter((key) => !(key in schema) && isSet(unwrap(record[key])));
+  return [...described, ...extra];
+};
+
+/** A field whose content is source code. `ui_type` is what the form renders by,
+ *  so it is what the preview reads by too — the storage type is just `string`. */
+export const isCodeField = (fieldSchema: TQorusFormFieldSchema | undefined): boolean => {
+  const uiType = (fieldSchema as { ui_type?: string } | undefined)?.ui_type;
+  return uiType === 'code-editor';
+};
+
+/**
+ * The field whose value heads the item — the first DECLARED one holding a plain
+ * scalar.
+ *
+ * Schema order, not value order: the first declared field is the one the form
+ * puts at the top of an item, which is the one that says which item it is. A
+ * code body or a nested level is skipped, not because it is unimportant but
+ * because it has no one-line form — it belongs in the rows below where it can
+ * actually be read.
+ *
+ * One definition, used both to RENDER the heading and to omit that field from
+ * the rows. Computing it twice is how the heading and the rows start disagreeing
+ * about which field was promoted, and the item shows its name twice or not at
+ * all.
+ */
+export const titleKeyFor = (
+  record: Record<string, unknown>,
+  schema: IQorusFormSchema
+): string | undefined =>
+  orderedKeys(record, schema).find((key) => {
+    const fieldSchema = schema[key] as TQorusFormFieldSchema | undefined;
+    if (isCodeField(fieldSchema)) {
+      return false;
+    }
+    const raw = unwrap(record[key]);
+    return typeof raw === 'string' || typeof raw === 'number';
+  });
+
+/** What identifies one record: which field was promoted, and how to draw it. */
+export interface IRecordIdentity {
+  /** The promoted field's key, so a caller can omit it from the rows below. */
+  key: string;
+  /** The value, formatted the way its own row would format it. */
+  text: string;
+  /** The promoted field's label — a caption for the heading, not a second line. */
+  label: string;
+  /** A literal keeps its mono face; a chosen label is prose. */
+  mono: boolean;
+}
+
+/**
+ * The identity of one record, for any surface that heads a list item with it.
+ *
+ * Exported because the preview is not the only place a list of records is shown:
+ * the editable list (`ArrayAuto`) heads the same records, and it must promote the
+ * same field and format it the same way. Two implementations would drift the
+ * moment one of them learned about a new field type, and the reader would meet
+ * an item called `init` in the preview and `#1` in the editor.
+ */
+export const recordIdentity = (
+  record: Record<string, unknown>,
+  schema: IQorusFormSchema | undefined
+): IRecordIdentity | undefined => {
+  if (!schema) {
+    return undefined;
+  }
+
+  const key = titleKeyFor(record, schema);
+
+  if (!key) {
+    return undefined;
+  }
+
+  const fieldSchema = schema[key] as TQorusFormFieldSchema | undefined;
+  const raw = unwrap(record[key]);
+
+  return {
+    key,
+    text: formatOptionValue(
+      { type: fieldSchema?.type, value: raw } as IQorusFormField,
+      fieldSchema
+    ),
+    label: fieldLabel(key, fieldSchema),
+    mono: !findAllowedValueOption(raw, fieldSchema),
+  };
+};
+
+export const fieldLabel = (key: string, fieldSchema: TQorusFormFieldSchema | undefined): string =>
+  (fieldSchema as { display_name?: string } | undefined)?.display_name || key;

package/src/components/form/fields/Field.tsx

@@ -569,7 +569,9 @@ export const FormField = <T extends TFormFieldType>({
       return (
         <ReqoreControlGroup vertical size='tiny'>
           <ReqoreSpan effect={{ opacity: 0.6, uppercase: true, weight: 'bold' }} size='tiny'>
-            Select one:
+            {/* Headed by the field's own name; "Select one:" only when it has
+                none. Same rule as FieldAllowedValuesCheckGroup. */}
+            {display_name ? `${display_name}:` : 'Select one:'}
           </ReqoreSpan>
           {allowed_values.map((item, index) => {
             const itemValue = item.value?.value;

package/src/components/form/fields/allowed-values/AllowedValues.tsx

@@ -43,15 +43,28 @@ export const FieldAllowedValuesCheckGroup = memo(
     onChange,
     name,
     value,
+    label,
     ...rest
   }: Partial<Omit<IFieldAllowedValuesProps, 'items'>> & {
     multiSelect?: boolean;
     items: ISelectFormFieldItem[];
+    /**
+     * The field's own name, used as the group's heading.
+     *
+     * A picker headed by what it IS beats one headed by a generic instruction:
+     * "Select one:" says nothing the shape of a radio group has not already
+     * said, and in a container that absorbs a sibling it forced the field's name
+     * to be printed a second time beside the group. Falls back to the
+     * instruction when a field declares no display name.
+     */
+    label?: string;
   }) => {
     return (
       <ReqoreControlGroup vertical size={rest.size || 'small'} gapSize='tiny'>
         <ReqoreSpan effect={{ opacity: 0.6, uppercase: true, weight: 'bold' }} size='tiny'>
-          {multiSelect ? 'Select one or more:' : 'Select one:'}
+          {label ? `${label}:`
+          : multiSelect ? 'Select one or more:'
+          : 'Select one:'}
         </ReqoreSpan>
         {items?.map((item) => (
           <ReqoreCheckbox
@@ -62,10 +75,17 @@ export const FieldAllowedValuesCheckGroup = memo(
             disabled={rest.disabled}
             readOnly={rest.readOnly}
             intent={item.value === value ? 'info' : undefined}
+            // `isEqual`, and only once there is a value to match. The single
+            // -select branch compared JSON.stringify(value) with
+            // JSON.stringify(item.value), and JSON.stringify(undefined) is
+            // undefined — so an unset field whose items carry no resolved value
+            // compared undefined with undefined and reported EVERY option as
+            // checked, on a field that was simultaneously "This field is
+            // required". Nothing selected must read as nothing selected.
             checked={
               multiSelect
                 ? Array.isArray(value) && value.some((v) => isEqual(v, item.value))
-                : JSON.stringify(value) === JSON.stringify(item.value)
+                : value !== undefined && value !== null && isEqual(value, item.value)
             }
             onClick={() => {
               if (multiSelect) {
@@ -103,6 +123,7 @@ export const FieldAllowedValues = memo(
     disabled,
     name,
     readOnly,
+    label,
   }: IFieldAllowedValuesProps) => {
     const fullItems = useMemo(() => {
       const result = [
@@ -131,6 +152,7 @@ export const FieldAllowedValues = memo(
             onChange={onChange}
             value={value}
             name={name}
+            label={label}
           />
         );
       }

package/src/components/form/fields/array/ArrayAuto.tsx

@@ -24,6 +24,7 @@ import { validateFieldWithResult } from '../../../../helpers/validations';
 import { useWhyDidYouUpdate } from '../../../../hooks/useWhyDidYouUpdate';
 // Direct imports — the cycle (ArrayAuto → TemplateField/auto → ArrayAuto) is
 // safe the same way Field → AutoFormField → Field is.
+import { recordIdentity } from '../../engine/readFirst';
 import { AutoFormField } from '../auto/AutoFormField';
 import { TemplateField } from '../template/TemplateField';
 
@@ -133,12 +134,29 @@ export const ArrayAuto = ({
   // Render list of auto fields
   return (
     <ReqoreControlGroup vertical fluid>
-      {map(localValue, (val: string | number, idx: string) => (
+      {map(localValue, (val: string | number, idx: string) => {
+        // The same field the collapsed preview promotes, resolved by the same
+        // definition — see `recordIdentity`. A list of seven methods headed
+        // `#1 … #7` makes the reader open each one to find out which is which,
+        // and heading them differently in the preview and the editor would make
+        // one item answer to two names.
+        const identity =
+          val && typeof val === 'object' && !Array.isArray(val)
+            ? recordIdentity(val as Record<string, unknown>, rest.arg_schema)
+            : undefined;
+
+        return (
         <ReqorePanel
           key={idx}
-          label={`#${idx + 1}`}
+          // `#N` stays as the fallback: a row whose identifying field is still
+          // empty (one just added) has nothing to be called yet, and a blank
+          // heading would be worse than a number.
+          label={identity?.text || `#${idx + 1}`}
+          tooltip={identity?.label}
           unMountContentOnCollapse={false}
-          badge={display_name || name}
+          // The position moves to the badge once the name owns the heading, so
+          // "which of these is third" stays answerable.
+          badge={identity ? `#${idx + 1}` : display_name || name}
           collapsible
           responsiveActions={false}
           responsiveTitle={false}
@@ -188,7 +206,8 @@ export const ArrayAuto = ({
           />
           {showValidationMessage(val)}
         </ReqorePanel>
-      ))}
+        );
+      })}
       <ReqoreControlGroup fluid>
         <ReqoreButton
           onClick={addValue}

package/src/components/form/fields/array/ArrayAutoField.stories.tsx

@@ -46,6 +46,58 @@ const numberRenderItem: IArrayAutoFieldProps['renderItem'] = ({
   />
 );
 
+/**
+ * Hash items are records, so a renderer that casts the item to a string prints
+ * `[object Object]` and shows nothing at all. This one reads the record through
+ * the schema that describes it: one input per declared field, labelled by that
+ * field's `display_name`, carrying the value actually stored under its key.
+ *
+ * With no `arg_schema` there is nothing to name the parts with, so the record is
+ * shown as JSON — unhelpful, but at least it is the data.
+ */
+const hashRenderItem: IArrayAutoFieldProps['renderItem'] = ({
+  value,
+  onChange,
+  disabled,
+  readOnly,
+  size,
+  arg_schema,
+}) => {
+  const record = (value ?? {}) as Record<string, unknown>;
+  const fields = Object.entries(arg_schema ?? {});
+
+  if (!fields.length) {
+    return (
+      <StringFormField
+        value={JSON.stringify(record)}
+        onChange={() => {}}
+        disabled={disabled}
+        readOnly
+        size={size as any}
+        aria-label='Array item input'
+      />
+    );
+  }
+
+  return (
+    <ReqoreControlGroup vertical fluid gapSize='small'>
+      {fields.map(([fieldName, fieldSchema]) => (
+        <StringFormField
+          key={fieldName}
+          value={(record[fieldName] as string) ?? ''}
+          onChange={(v) => onChange({ ...record, [fieldName]: v })}
+          disabled={disabled}
+          readOnly={readOnly}
+          size={size as any}
+          aria-label={
+            ((fieldSchema as { display_name?: string })?.display_name as string) ?? fieldName
+          }
+        />
+      ))}
+    </ReqoreControlGroup>
+  );
+};
+
 const meta = {
   component: ArrayAutoField,
   title: 'Components/Form/Auto Array',
@@ -322,6 +374,7 @@ export const ComplexHashItems: Story = {
     type: 'hash',
     value: [{ key: 'value' }],
     display_name: 'Hash Items',
+    renderItem: hashRenderItem,
   },
   parameters: {
     docs: {
@@ -339,3 +392,84 @@ export const ComplexHashItems: Story = {
     await expect(document.querySelectorAll('.array-auto-compact-tag').length).toBe(0);
   },
 };
+
+/**
+ * The editable list, headed by what identifies each record.
+ *
+ * The rows used to read `#1 #2 #3`, so finding one method meant opening each in
+ * turn — and the collapsed preview beside it already headed the same records
+ * `init` / `onOrderStatus`, which made one item answer to two names. Both now
+ * resolve the heading through `recordIdentity`: the first field the SCHEMA
+ * declares that holds a scalar, skipping any it leaves unset. The position keeps
+ * a badge, so "the third one" is still answerable.
+ */
+export const HashItemsHeadedByIdentity: Story = {
+  args: {
+    type: 'hash',
+    display_name: 'Service Methods',
+    arg_schema: {
+      name: { type: 'string', ui_type: 'string', display_name: 'Method Name', required: true },
+      description: { type: 'string', ui_type: 'string', display_name: 'Description' },
+    },
+    value: [
+      { name: 'init', description: 'The init method' },
+      { name: 'onOrderStatus', description: 'Handles order status callbacks' },
+      { description: 'Added but not yet named' },
+      {},
+    ],
+    renderItem: hashRenderItem,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders four hash items headed by their identifying value: two named methods read as "init" and "onOrderStatus", one with no name falls through to its description, and an entirely empty one keeps its position number.',
+      },
+    },
+  },
+  async play() {
+    await waitFor(() => expect(document.querySelectorAll('.array-auto-item').length).toBe(4), {
+      timeout: 5000,
+    });
+
+    const headings = [...document.querySelectorAll('.array-auto-item')].map(
+      (item) => item.textContent ?? ''
+    );
+
+    await expect(headings[0]).toContain('init');
+    await expect(headings[1]).toContain('onOrderStatus');
+    // An unset field is skipped rather than promoted blank, so this one is
+    // headed by the next field that IS set.
+    await expect(headings[2]).toContain('Added but not yet named');
+    // And a record with nothing set at all keeps its position — there is
+    // genuinely nothing to call it.
+    await expect(headings[3]).toContain('#4');
+
+    // The heading is only half the story: each item must also render the record
+    // it is heading, field by field. Asserting the inputs is what would have
+    // caught them all printing "[object Object]" — the heading resolved
+    // correctly while every value below it was a stringified hash.
+    const nameInputs = document.querySelectorAll<HTMLInputElement>(
+      'input[aria-label="Method Name"]'
+    );
+    const descInputs = document.querySelectorAll<HTMLInputElement>(
+      'input[aria-label="Description"]'
+    );
+
+    await expect(nameInputs.length).toBe(4);
+    await expect(descInputs.length).toBe(4);
+    await expect(nameInputs[0].value).toBe('init');
+    await expect(descInputs[0].value).toBe('The init method');
+    await expect(nameInputs[1].value).toBe('onOrderStatus');
+    // The unnamed record: no name to show, but the description it IS headed by
+    // has to be there.
+    await expect(nameInputs[2].value).toBe('');
+    await expect(descInputs[2].value).toBe('Added but not yet named');
+    // And the empty one renders empty inputs rather than an empty item.
+    await expect(nameInputs[3].value).toBe('');
+    await expect(descInputs[3].value).toBe('');
+
+    // Nothing anywhere may read as a stringified record.
+    await expect(document.body.textContent).not.toContain('[object Object]');
+  },
+};

package/src/components/form/fields/array/ArrayAutoField.tsx

@@ -9,6 +9,7 @@ import {
 } from '@qoretechnologies/reqore';
 import { IQorusFormSchema } from '@qoretechnologies/ts-toolkit';
 import { map, size } from 'lodash';
+import { recordIdentity } from '../../engine/readFirst';
 import React, { memo, useCallback, useEffect, useRef, useState } from 'react';
 import { useDebounce } from 'react-use';
 import { validateFieldWithResult } from '../../../../helpers/validations';
@@ -279,11 +280,27 @@ export const ArrayAutoField = memo(
 
     return (
       <ReqoreControlGroup vertical fluid>
-        {map(localValue, (val, idx) => (
+        {map(localValue, (val, idx) => {
+          // The same field the collapsed preview promotes, resolved by the same
+          // definition — see `recordIdentity`. Both editable list renderers head
+          // their records with it, so an item cannot be called `init` in one
+          // place and `#1` in another.
+          const identity =
+            val && typeof val === 'object' && !Array.isArray(val)
+              ? recordIdentity(val as Record<string, unknown>, arg_schema)
+              : undefined;
+
+          return (
           <ReqorePanel
             key={idx}
-            label={`#${idx + 1}`}
-            badge={display_name || name}
+            // `#N` stays as the fallback: a record whose identifying field is
+            // still empty has nothing to be called yet, and a blank heading
+            // would be worse than a number.
+            label={identity?.text || `#${idx + 1}`}
+            tooltip={identity?.label}
+            // The position moves to the badge once the name owns the heading,
+            // so "which of these is third" stays answerable.
+            badge={identity ? `#${idx + 1}` : display_name || name}
             collapsible
             unMountContentOnCollapse={false}
             responsiveActions={false}
@@ -321,7 +338,8 @@ export const ArrayAutoField = memo(
             })}
             {renderValidationMessage(val)}
           </ReqorePanel>
-        ))}
+          );
+        })}
 
         <ReqoreButton
           onClick={addItem}

package/src/components/form/fields/auto/AutoFormField.stories.tsx

@@ -11,7 +11,7 @@
 import { StoryObj } from '@storybook/react-vite';
 import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
 import jsyaml from 'js-yaml';
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 
 import { StoryMeta } from '../../../../types';
 import { buildTemplates } from '../../../../helpers/templates';
@@ -512,3 +512,49 @@ export const ListWithElementType: Story = {
     },
   },
 };
+
+/**
+ * A named `arg_schema` whose fetch fails.
+ *
+ * The field asks the server for `dataprovider/arg_schemas/<name>`. When that
+ * request rejected — a malformed instance URL, an aborted request, a transport
+ * error — the rejection escaped the effect's async IIFE unhandled, `setError`
+ * never ran, and `finalArgSchema` stayed undefined. The loading branch then
+ * returned on every subsequent render and the error branch below it was
+ * unreachable, so the field showed "Loading field data..." for the life of the
+ * form: a request that failed instantly and one that is merely slow looked
+ * exactly the same, forever.
+ *
+ * The transport is stubbed rather than left to the dev server, so the story
+ * exercises that path and only that path.
+ */
+export const NamedArgSchemaFetchFails: Story = {
+  args: {
+    name: 'rules',
+    type: 'list',
+    element_type: 'hash',
+    arg_schema: 'a-schema-that-does-not-resolve' as any,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The named arg schema could not be fetched, so the field says so instead of showing an endless "Loading field data..." spinner with the error it had already received never rendered.',
+      },
+    },
+  },
+  decorators: [
+    (Story) => {
+      const real = window.fetch;
+      window.fetch = (() =>
+        Promise.reject(new Error('Failed to fetch the field schema'))) as typeof window.fetch;
+      useEffect(() => () => {
+        window.fetch = real;
+      }, []);
+      return <Story />;
+    },
+  ],
+  play: async () => {
+    await waitForText(/Failed to fetch the field schema|could not be loaded/);
+  },
+};