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

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

@@ -5,7 +5,7 @@ import {
   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';
@@ -155,6 +155,45 @@ export const isOptionValueEmpty = (value: unknown): boolean =>
   value === '' ||
   (Array.isArray(value) && value.length === 0);
 
+/**
+ * A schema-declared hash whose every entry is a materialised-but-unset field.
+ *
+ * `preselected` on a sub-field means "show this in the form so the author sees
+ * it exists" — a FORM instruction. Opening the sub-form materialises each one,
+ * `fixOptions` writes `{type: 'int'}` with no value, and the draft autosaves
+ * that, so the stored hash permanently carries keys that stand for nothing.
+ *
+ * The row then read those keys as content: `Runtime Defaults` listed three
+ * sub-fields with no values, counted toward "7/12 set", and showed a green
+ * set-dot — while the sub-form it summarises correctly said 0/3 set. Nothing
+ * was ever entered.
+ *
+ * Requires the sub-schema, and requires each key to be declared by it: without
+ * that, `{type: 'x'}` could be somebody's data rather than an empty envelope.
+ */
+export const isUnsetSchemaHash = (value: unknown, schema?: TQorusFormFieldSchema): boolean => {
+  const argSchema = (schema as { arg_schema?: Record<string, unknown> } | undefined)?.arg_schema;
+  if (!argSchema || typeof argSchema !== 'object') {
+    return false;
+  }
+  const inner =
+    value && typeof value === 'object' && !Array.isArray(value) && 'value' in (value as object) ?
+      (value as { value: unknown }).value
+    : value;
+  if (!inner || typeof inner !== 'object' || Array.isArray(inner)) {
+    return false;
+  }
+  const keys = Object.keys(inner as object);
+  return (
+    keys.length > 0 &&
+    keys.every(
+      (key) =>
+        !!(argSchema as Record<string, unknown>)[key] &&
+        isEmptyUiEnvelope((inner as Record<string, unknown>)[key])
+    )
+  );
+};
+
 export const isFixedCompactAllowedValueOption = (
   schema: TQorusFormFieldSchema | undefined
 ): boolean => {
@@ -200,6 +239,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
@@ -215,13 +261,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
   );
 };
 
@@ -499,7 +562,7 @@ export const formatOptionValue = (
 ): string => {
   const value = option?.value;
 
-  if (isOptionValueEmpty(value)) {
+  if (isOptionValueEmpty(value) || isUnsetSchemaHash(value, schema)) {
     return '';
   }
 
@@ -641,34 +704,55 @@ export const getHashEntries = (
   const argSchema = (schema as { arg_schema?: Record<string, TQorusFormFieldSchema> } | undefined)
     ?.arg_schema;
 
-  return Object.keys(hashObject).map((key) => {
-    const raw = hashObject![key];
-    const subSchema = argSchema?.[key];
-    // A schema-declared (`arg_schema`) hash stores each entry as a
-    // `{ type, value }` field descriptor — gate on the sub-schema's presence.
-    // A schema-less hash *usually* stores raw values, but the server's typed
-    // serialization can nest envelopes there too (e.g. a hash default_value
-    // 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.
-    const isFieldShape =
-      (!!subSchema &&
-        !!raw &&
-        typeof raw === 'object' &&
-        !Array.isArray(raw) &&
-        'value' in (raw as object)) ||
-      isTypedEnvelope(raw);
-    const subOption: IQorusFormField =
-      isFieldShape ?
-        (raw as IQorusFormField)
-      : ({ type: subSchema?.type as IQorusFormField['type'], value: raw } as IQorusFormField);
-
-    return {
-      name: key,
-      label: subSchema?.display_name || key,
-      value: formatOptionValue(subOption, subSchema),
-    };
-  });
+  return Object.keys(hashObject)
+    .filter((key) => {
+      // Only sub-fields with a value belong in a read view. `preselected`
+      // materialises a field so the FORM shows it; that is not a statement
+      // that the object has one, and listing it here says the opposite of
+      // what the sub-form says.
+      const subSchema = argSchema?.[key];
+      return !(subSchema && isEmptyUiEnvelope(hashObject![key]));
+    })
+    .map((key) => {
+      const raw = hashObject![key];
+      const subSchema = argSchema?.[key];
+      // A schema-declared (`arg_schema`) hash stores each entry as a
+      // `{ type, value }` field descriptor — gate on the sub-schema's presence.
+      // A schema-less hash *usually* stores raw values, but the server's typed
+      // serialization can nest envelopes there too (e.g. a hash default_value
+      // 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 ?
+          (raw as IQorusFormField)
+        : ({ type: subSchema?.type as IQorusFormField['type'], value: raw } as IQorusFormField);
+
+      return {
+        name: key,
+        label: subSchema?.display_name || key,
+        value: formatOptionValue(subOption, subSchema),
+      };
+    });
 };
 
 const titleCase = (value: string): string =>
@@ -823,7 +907,10 @@ export const isSet = (value: unknown): boolean =>
  * (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[] => {
+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];
@@ -904,7 +991,10 @@ export const recordIdentity = (
 
   return {
     key,
-    text: formatOptionValue({ type: fieldSchema?.type, value: raw } as IQorusFormField, fieldSchema),
+    text: formatOptionValue(
+      { type: fieldSchema?.type, value: raw } as IQorusFormField,
+      fieldSchema
+    ),
     label: fieldLabel(key, fieldSchema),
     mono: !findAllowedValueOption(raw, fieldSchema),
   };

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/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: {
@@ -364,6 +417,7 @@ export const HashItemsHeadedByIdentity: Story = {
       { description: 'Added but not yet named' },
       {},
     ],
+    renderItem: hashRenderItem,
   },
   parameters: {
     docs: {
@@ -390,5 +444,32 @@ export const HashItemsHeadedByIdentity: Story = {
     // 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/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/);
+  },
+};

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

@@ -18,6 +18,7 @@ import React, { memo, useCallback, useEffect, useState } from 'react';
 import { useUpdateEffect } from 'react-use';
 import useMount from 'react-use/lib/useMount';
 import { typedToYaml, yamlToTyped } from '../../../../helpers/common';
+import { getListElementValue } from '../../../../helpers/options';
 import {
   getTypeFromValue,
   getValueOrDefaultValue,
@@ -212,16 +213,31 @@ function AutoField<T = any>({
   useEffect(() => {
     if (typeof arg_schema === 'string') {
       (async () => {
-        const schema = await query<IOptionsSchema>({
-          url: `dataprovider/arg_schemas/${arg_schema}`,
-          method: 'GET',
-        });
-
-        if (schema.ok) {
-          setError(undefined);
-          setFinalArgSchema(schema.data);
-        } else {
-          setError(schema.error);
+        /* The await is guarded because `query` can REJECT rather than answer
+           `{ ok: false }` — a malformed instance URL, an aborted request, a
+           transport error. Unguarded, that rejection escaped the async IIFE as
+           an unhandled promise rejection, `setError` never ran, `finalArgSchema`
+           stayed undefined, and the field showed "Loading field data..." for the
+           life of the form: a request that failed instantly and a request that
+           is merely slow looked exactly the same, forever. */
+        try {
+          const schema = await query<IOptionsSchema>({
+            url: `dataprovider/arg_schemas/${arg_schema}`,
+            method: 'GET',
+          });
+
+          if (schema.ok) {
+            setError(undefined);
+            setFinalArgSchema(schema.data);
+          } else {
+            setError(schema.error ?? `The schema "${arg_schema}" could not be loaded.`);
+          }
+        } catch (fetchError) {
+          setError(
+            fetchError instanceof Error ?
+              fetchError.message
+            : `The schema "${arg_schema}" could not be loaded.`
+          );
         }
       })();
     } else {
@@ -363,6 +379,18 @@ function AutoField<T = any>({
     return (
       <Override
         {...rest}
+        // The field's SHAPE, which `rest` does not carry: these three are
+        // destructured into named props above, so a host editor received a
+        // field it could not describe. `arg_schema` is the sub-schema a host
+        // sub-form renders FROM — without it the IDE's test-cases drawer fell
+        // back to humanising each key, so `Path`, `Actual` and `Expected` were
+        // asked for with no label of their own and no description, while the
+        // text sat one fetch away. `element_type`/`ui_element_type` travel with
+        // it: a sub-schema alone cannot say whether the value is one hash or a
+        // list of them.
+        arg_schema={arg_schema}
+        element_type={element_type}
+        ui_element_type={ui_element_type}
         name={name}
         value={value}
         onChange={(val: any, emittedType?: IQorusType, emittedIsFunction?: boolean) => {
@@ -407,6 +435,23 @@ function AutoField<T = any>({
     );
   }
 
+  /* The error is checked BEFORE the spinner, and the spinner waits on the error
+     being absent.
+
+     A named `arg_schema` is fetched (`dataprovider/arg_schemas/<name>`), and when
+     that fetch failed `finalArgSchema` stayed undefined forever — so this spinner
+     returned on every subsequent render and the `if (error)` branch further down
+     was unreachable. The field sat on "Loading field data..." for the life of the
+     form with no way to find out why, which is indistinguishable from a request
+     that is merely slow. */
+  if (arg_schema && !finalArgSchema && error) {
+    return (
+      <ReqoreMessage intent='danger' size='small'>
+        {error}
+      </ReqoreMessage>
+    );
+  }
+
   if (arg_schema && !finalArgSchema) {
     return <ReqoreSpinner size='small'>Loading field data...</ReqoreSpinner>;
   }
@@ -424,6 +469,9 @@ function AutoField<T = any>({
         value={value}
         name={name}
         onChange={handleChange}
+        // The picker heads itself with the field's own name rather than a
+        // generic "Select one:".
+        label={rest.display_name}
         size={rest.size}
         disabled={rest.disabled}
         app={rest.app}
@@ -507,6 +555,12 @@ function AutoField<T = any>({
           return (
             <LongStringFormField
               {...rest}
+              // These four share one editor but not one shape: a `string` holds
+              // exactly one line, while `data`, `binary` and `long-string` hold
+              // a document. Without the type the field cannot tell them apart
+              // and treats them all as documents, so an interface's Internal
+              // Name — which becomes a YAML key — accepted Enter.
+              type={currentType}
               onChange={(value) => handleChange(name, value)}
               value={value}
             />
@@ -644,8 +698,16 @@ function AutoField<T = any>({
               });
             };
 
+            // An element may arrive bare or in a `{value, type}` envelope. The
+            // envelope is what `formatToServerValue` writes, so a list the user
+            // has edited in this session is always wrapped — but a list read
+            // back from storage holds exactly what the server contract asks
+            // for, which for a list of strings is the strings themselves.
+            // Reaching for `.value` on those answered `undefined` for every
+            // element: the row rendered as an empty, invalid item, and the
+            // emptiness was then written back over the stored value.
             const formatFromServerValue = (value) => {
-              return (value || []).map((item) => item?.value);
+              return (value || []).map(getListElementValue);
             };
 
             const mappedAllowedValues = rest.element_allowed_values?.map((ev) => ({