@qoretechnologies/reqraft 0.10.39-pr.99.gdbafa34 → 0.10.39

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

@@ -24,14 +24,6 @@ export interface ICompactToolbarOptionalField {
  */
 export interface ICompactToolbarContext {
   readOnly?: boolean;
-  /** Which parts to render, already resolved from the engine's `compactToolbar`
-   *  prop — every key present, no undefined to re-default here. */
-  parts: {
-    completion: boolean;
-    search: boolean;
-    fields: boolean;
-    help: boolean;
-  };
   // Completion meter
   invalidCount: number;
   attentionCount: number;

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,7 +196,8 @@ export const shouldAutoCollapseCompactOption = (
   !isOptionValueEmpty(value) &&
   (isCompactBooleanOption(schema) || isFixedCompactAllowedValueOption(schema));
 
-/** Prefer the matching allowed_values entry's display_name (fallback `name`)
+/**
+ * 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
@@ -141,8 +205,23 @@ export const shouldAutoCollapseCompactOption = (
  * 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). */
-const findAllowedOption = (value: unknown, schema?: TQorusFormFieldSchema): any | undefined => {
+ * 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
+ * `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[]; element_allowed_values?: any[]; items?: any[] }
     | undefined;
@@ -179,6 +258,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 => {
@@ -741,3 +823,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/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';
 
@@ -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

@@ -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}