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

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

@@ -1,4 +1,9 @@
-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 { renderExpressionToText } from '../expressions/renderExpressionToText';
@@ -40,6 +45,57 @@ const summarizeListItem = (item: unknown): string | number | undefined => {
   return undefined;
 };
 
+/**
+ * Label ONE list item from the sub-schema that describes it.
+ *
+ * `summarizeListItem` can only read an item that names ITSELF — one carrying a
+ * `name` or `display_name` key. A hash whose fields are all domain fields names
+ * itself nowhere: an auth profile's scheme has `type`, `cookie_name`,
+ * `redirect_url`, and the row fell back to "2 items" — true, and silent about
+ * which two.
+ *
+ * The `arg_schema` is the same description the sub-form was built from, so the
+ * row can read an item the way the form asked for it: the FIRST declared field
+ * the item actually has, resolved through that field's allowed values. The
+ * scheme list then reads "Default RBAC, Cookie" — the words the author picked —
+ * instead of a count.
+ *
+ * Schema order, not value order: the first declared field is the one the form
+ * puts at the top of the item, which is the one that identifies it to its author.
+ * Value order is insertion order and would vary between two equal items.
+ */
+const summarizeHashItemFromSchema = (
+  item: unknown,
+  argSchema: Record<string, TQorusFormFieldSchema> | undefined
+): string | number | undefined => {
+  if (!argSchema) {
+    return undefined;
+  }
+  const record = isTypedEnvelope(item) ? item.value : item;
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    return undefined;
+  }
+  const fields = record as Record<string, unknown>;
+  const key = Object.keys(argSchema).find((name) => {
+    const raw = fields[name];
+    const value = isTypedEnvelope(raw) ? raw.value : raw;
+    return value !== undefined && value !== null && value !== '';
+  });
+  if (!key) {
+    return undefined;
+  }
+  const raw = fields[key];
+  const value = isTypedEnvelope(raw) ? raw.value : raw;
+  const label = getAllowedValueLabel(value, argSchema[key]);
+  if (label) {
+    return label;
+  }
+  // No allowed values (a free-text field): the stored value IS what was typed,
+  // so it reads correctly as-is. An object at this position has no short form,
+  // and a count beats printing its shape.
+  return typeof value === 'string' || typeof value === 'number' ? value : undefined;
+};
+
 /** Summarise a list value: join item labels, or fall back to an "N items" count
  * (e.g. a list of anonymous hashes). Never prints raw objects. */
 /**
@@ -52,8 +108,15 @@ const summarizeListItem = (item: unknown): string | number | undefined => {
  * does, so it can read the same way instead of printing the wire form back.
  */
 const formatList = (items: unknown[], schema?: TQorusFormFieldSchema): string => {
+  const argSchema = (schema as { arg_schema?: Record<string, TQorusFormFieldSchema> } | undefined)
+    ?.arg_schema;
   const parts = items
-    .map((item) => getAllowedValueLabel(item, schema) ?? summarizeListItem(item))
+    .map(
+      (item) =>
+        getAllowedValueLabel(item, schema) ??
+        summarizeListItem(item) ??
+        summarizeHashItemFromSchema(item, argSchema)
+    )
     .filter((part) => part !== '' && part !== undefined && part !== null);
 
   return parts.length ? parts.join(', ') : pluralize(items.length, 'item');
@@ -133,9 +196,25 @@ export const shouldAutoCollapseCompactOption = (
   !isOptionValueEmpty(value) &&
   (isCompactBooleanOption(schema) || isFixedCompactAllowedValueOption(schema));
 
-/** Prefer the matching allowed_values entry's display_name (fallback `name`)
- * over the raw stored value. */
-const findAllowedOption = (value: unknown, schema?: TQorusFormFieldSchema): any | undefined => {
+/**
+ * Prefer the matching allowed_values entry's display_name (fallback `name`)
+ * over the raw stored value.
+ *
+ * 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
+ * `allowed_values` entry is written three ways: an envelope (`{value: {type,
+ * value}}`), a bare value (`{value: 'default'}`) or a named entry
+ * (`{name: 'default'}`). This has always accepted all three; the engine's
+ * clearing guard accepted only the first and the third, so a schema using the
+ * bare form had its value ERASED on load while this function went on rendering
+ * the display name for it — the row read "Default RBAC" collapsed and "—" when
+ * opened, and the value was gone from the submitted data.
+ */
+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;
   if (!options?.length) {
@@ -154,6 +233,9 @@ const getAllowedValueLabel = (
   return match ? match.display_name || match.title || match.name || undefined : undefined;
 };
 
+/** Local alias for the module's own callers. */
+const findAllowedOption = findAllowedValueOption;
+
 /** True when the field's selectable options carry images (logos). Such a choice
  * renders too tall/rich for an inline row, so compact opens it in the card. */
 export const optionHasImages = (schema?: TQorusFormFieldSchema): boolean => {
@@ -716,3 +798,117 @@ 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/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';
 
@@ -64,6 +65,12 @@ export const ArrayAuto = ({
 }: IArrayAutoProps): any => {
   const confirmAction = useReqoreProperty('confirmAction');
   const [localValue, setLocalValue] = useState(value);
+  // The row this component just created, so its sub-form can open the field it
+  // cannot be saved without. Only a row added HERE gets it: the rows already in
+  // the value were added by an earlier session (or arrived from the server), and
+  // opening one of those on mount would be this component reopening a decision
+  // the author already made.
+  const [justAddedIndex, setJustAddedIndex] = useState<number | undefined>(undefined);
 
   useWhyDidYouUpdate(`Array Auto ${name}`, {
     name,
@@ -87,6 +94,7 @@ export const ArrayAuto = ({
   );
 
   const addValue: () => void = () => {
+    setJustAddedIndex(localValue.length);
     setLocalValue([...localValue, defaultValueByType[rest.type]]);
   };
 
@@ -126,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}
@@ -171,12 +196,18 @@ export const ArrayAuto = ({
             allowTemplates
             defaultType={rest.type}
             name={`${name}-${idx}`}
+            // AFTER `{...rest}` on purpose: this is the one prop that differs
+            // per row, and spreading rest over it would give every row the same
+            // answer. Rides TemplateField's `rest` into the row's AutoFormField,
+            // which hands it to the row's nested FormEngine (case 'hash').
+            expandFirstRequired={Number(idx) === justAddedIndex}
             value={val}
             onChange={(_name, value) => handleChange(idx, value)}
           />
           {showValidationMessage(val)}
         </ReqorePanel>
-      ))}
+        );
+      })}
       <ReqoreControlGroup fluid>
         <ReqoreButton
           onClick={addValue}

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

@@ -339,3 +339,56 @@ 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' },
+      {},
+    ],
+  },
+  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');
+  },
+};

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.tsx

@@ -75,6 +75,10 @@ export interface IAutoFieldProps
   /** Render the arg_schema sub-form in compact (read-first) mode, matching the
    *  parent engine. */
   compact?: boolean;
+  /** Open the arg_schema sub-form's first attention row on mount, without taking
+   *  focus — see FormEngine's `expandFirstRequired`. Set by ArrayAuto on a
+   *  just-added row so its required choice is visible without a second click. */
+  expandFirstRequired?: boolean;
   path?: string;
   column?: boolean;
   level?: number;
@@ -161,6 +165,10 @@ function AutoField<T = any>({
   // Only the nested arg_schema mount sites re-forward this into their
   // sub-forms explicitly.
   inheritedFromParent,
+  // Destructured for the same reason as `inheritedFromParent`: only the nested
+  // sub-form mount site consumes it, and leaving it in `...rest` would spread an
+  // unknown attribute onto the primitive field renderers' DOM nodes.
+  expandFirstRequired,
   ...rest
 }: IAutoFieldProps & T) {
   const [currentType, setType] = useState<IQorusType>(defaultInternalType || null);
@@ -559,6 +567,9 @@ function AutoField<T = any>({
                 wrapperPadding='top'
                 flat
                 compact={compact}
+                // A row added just now: open the field it cannot be saved
+                // without, instead of making the author find it and click it.
+                expandFirstRequired={expandFirstRequired}
                 // Embedded sub-form: no scroll context of its own, so its toolbar
                 // isn't sticky and its header stays transparent (no dark backdrop).
                 compactNested

package/src/helpers/validations.ts

@@ -14,6 +14,51 @@ import { getAddress, getProtocol, splitByteSize } from './common';
 import { getOptionsFromRequiredGroups } from './options';
 import { getTemplateKey, getTemplateValue, isValueTemplate } from './templates';
 
+/** The five cron fields, in order, as a schedule hash may name them. */
+const CRON_FIELDS: [string, string][] = [
+  ['minutes', 'minute'],
+  ['hours', 'hour'],
+  ['days', 'day'],
+  ['months', 'month'],
+  ['dow', 'weekday'],
+];
+
+/**
+ * A five-field cron expression, from either representation a caller may hold.
+ *
+ * A schedule reaches the form in one of two shapes, and both are legitimate: a
+ * joined string (`"0 0 1 1 *"`), or the hash a Qorus job carries
+ * (`{minutes, hours, days, months, dow}` — also accepted under the singular
+ * `minute`/`hour`/`day`/`month`/`weekday` spellings). The renderer already
+ * accepted both; validation did not, and fed the hash straight to
+ * `isValidCron`, which calls `.trim()` on it.
+ *
+ * Returns `undefined` for anything that is neither, so the caller reports an
+ * invalid value rather than throwing.
+ */
+export const cronExpressionFromValue = (value: unknown): string | undefined => {
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return undefined;
+  }
+
+  const hash = value as Record<string, unknown>;
+  const parts = CRON_FIELDS.map(([plural, singular]) => {
+    const field = hash[plural] ?? hash[singular];
+    return field === undefined || field === null || field === '' ? '*' : String(field);
+  });
+
+  // An object with none of the five keys is not a schedule — every part
+  // defaulting to `*` would otherwise turn any object at all into "* * * * *"
+  return parts.every((part) => part === '*') &&
+    !CRON_FIELDS.some(([plural, singular]) => plural in hash || singular in hash)
+    ? undefined
+    : parts.join(' ');
+};
+
 export interface IValidationResult {
   isValid: boolean;
   reason?: string;
@@ -322,11 +367,23 @@ export const _validateField = (
     case 'array':
     case 'file-tree':
       return resultFromBoolean(value && value.length > 0, 'At least one value is required');
-    case 'cron':
+    case 'cron': {
       if (!value) {
         return invalidResult('Cron value is required');
       }
-      return resultFromBoolean(isValidCron(value, { alias: true }), 'Cron expression is invalid');
+      const expression = cronExpressionFromValue(value);
+      // A value that is neither a cron string nor a schedule hash is INVALID,
+      // not a crash: `isValidCron` calls `.trim()` on whatever it is given, so
+      // passing it a hash threw a TypeError out of validation and took the
+      // whole form down through the host's error boundary.
+      if (expression === undefined) {
+        return invalidResult('Cron expression is invalid');
+      }
+      return resultFromBoolean(
+        isValidCron(expression, { alias: true }),
+        'Cron expression is invalid'
+      );
+    }
     case 'date':
       return resultFromBoolean(
         value !== undefined &&

package/src/index.tsx

@@ -62,3 +62,4 @@ export * from './components/supportTicket';
 export * from './components/ticketThread';
 export * from './components/ticketReferences';
 export * from './components/searchFilterBar';
+export * from './components/codeSize';