@qoretechnologies/reqraft 0.10.41-pr.95.g294e5aa → 0.10.41

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

@@ -1,4 +1,10 @@
-import { ReqoreCollapsibleContent, ReqoreIcon, ReqoreP, ReqoreTag } from '@qoretechnologies/reqore';
+import {
+  ReqoreCollapsibleContent,
+  ReqoreIcon,
+  ReqoreLink,
+  ReqoreP,
+  ReqoreTag,
+} from '@qoretechnologies/reqore';
 import {
   IQorusFormField,
   IQorusFormSchema,
@@ -9,7 +15,16 @@ import styled from 'styled-components';
 import { useContextSelector } from 'use-context-selector';
 import { CompactRowContext } from '../compactRowContext';
 import { MONO_FONT_STACK, StyledCodePreview, StyledRowLabel, StyledRowValue } from '../compactRowStyles';
-import { findAllowedValueOption, formatOptionValue, getAllowedValueImage } from '../readFirst';
+import {
+  fieldLabel,
+  findAllowedValueOption,
+  formatOptionValue,
+  getAllowedValueImage,
+  isCodeField,
+  orderedKeys,
+  recordIdentity,
+  titleKeyFor,
+} from '../readFirst';
 import { isUiEncodedValue } from './structuredData';
 
 /**
@@ -26,10 +41,11 @@ import { isUiEncodedValue } from './structuredData';
  * So a described value is rendered the way the form asked for it, in the form's
  * own clothes:
  *
- * - Field names use `StyledRowLabel` and values use `StyledRowValue` — the very
- *   components the option rows above are built from. Not a copy of their CSS: a
- *   copy is a second definition of "what a form label looks like", and the two
- *   drift the first time either is touched.
+ * - Field names use `StyledFieldLabel` (a `StyledRowLabel` in the read-only
+ *   eyebrow treatment) and values use `StyledRowValue` — the very components the
+ *   option rows above are built from. Not a copy of their CSS: a copy is a
+ *   second definition of "what a form label looks like", and the two drift the
+ *   first time either is touched.
  * - Values are formatted by the same `formatOptionValue` the rows use, so an
  *   `allowed_values` entry resolves to its display name, a bool to Yes/No, a
  *   date to the app's format. The same words appear in the summary, the preview
@@ -129,10 +145,39 @@ const StyledItemTitle = styled.div<{ $color: string; $mono: boolean; $accent: st
   ${({ $mono }) => ($mono ? `font-family: ${MONO_FONT_STACK}; font-size: 15px;` : '')}
 `;
 
-/** The rule tying an item's fields to its number. */
-const StyledItemFields = styled.div<{ $border: string }>`
-  border-left: 1px solid ${({ $border }) => $border};
-  padding-left: 10px;
+/**
+ * Does this record have anything to show BELOW its heading?
+ *
+ * The heading consumes the identifying field, so a record holding only that has
+ * an empty body — and a rule drawn down an empty body is a line to nowhere.
+ */
+const hasContentUnderHeading = (record: unknown, schema?: IQorusFormSchema): boolean => {
+  if (!isRecord(record)) {
+    return true;
+  }
+  const titleKey = titleKeyFor(record, schema);
+
+  return Object.entries(record).some(
+    ([key, value]) =>
+      key !== titleKey && value !== undefined && value !== null && value !== ''
+  );
+};
+
+/** The rule tying an item's fields to its number.
+ *
+ * Same 3px as the heading's accent bar directly above it: at 1px the two read as
+ * two different devices stacked on each other rather than one rule running down
+ * the item, and the padding drops to 8px so the text stays on the same column.
+ *
+ * The rule is drawn only when something is actually under the heading. The
+ * heading is pulled left of the rule by its own negative margin, so an item
+ * whose record holds nothing but its identity showed a 1-2px sliver of line and
+ * nothing else — which reads as a rendering artefact, because that is what it
+ * was. It keeps a transparent border in that case so the column does not shift.
+ */
+const StyledItemFields = styled.div<{ $border: string; $rule: boolean }>`
+  border-left: 3px solid ${({ $border, $rule }) => ($rule ? $border : 'transparent')};
+  padding-left: 8px;
   min-width: 0;
 `;
 
@@ -144,6 +189,30 @@ const StyledItemFields = styled.div<{ $border: string }>`
  * and leave the items ragged against each other, which reads as a rendering
  * fault rather than as a list.
  */
+/**
+ * A record field's name, in the detail-page vocabulary.
+ *
+ * Uppercase, tracked and dimmed, so a field name reads as furniture and the
+ * VALUE beside it is what the eye lands on. Same treatment the read-only
+ * interface panels use, which is the point: an in-editor list of records and a
+ * detail-page panel showing the same shape should not look like two components.
+ *
+ * A variant rather than a change to `StyledRowLabel`: that one is the FORM's own
+ * option-row label, and the form's fields are not read-only furniture — they are
+ * the things you are about to edit. Composing it keeps the colour, weight base
+ * and wrapping behaviour in one place instead of copying them.
+ *
+ * Applies to the label only. A VALUE is never uppercased: values are frequently
+ * case-sensitive — a service method is `onOrderStatus`, not `ONORDERSTATUS` —
+ * and the item heading is a value.
+ */
+const StyledFieldLabel = styled(StyledRowLabel)`
+  font-size: 12px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  opacity: 0.55;
+`;
+
 const StyledFields = styled.div`
   /* The supporting fields step in under the heading, so the heading keeps the
      left edge to itself. This is the half that answers "the name is written in
@@ -224,59 +293,6 @@ const unwrap = (item: unknown): unknown => (isUiEncodedValue(item) ? item.value
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   !!value && typeof value === 'object' && !Array.isArray(value);
 
-/** Whether a value is worth a row of its own. `false` and `0` are values. */
-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.
- */
-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`. */
-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.
- */
-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';
-  });
-
-const fieldLabel = (key: string, fieldSchema: TQorusFormFieldSchema | undefined): string =>
-  (fieldSchema as { display_name?: string } | undefined)?.display_name || key;
-
 /**
  * The width of the shared label column, measured from the longest name that will
  * actually be rendered.
@@ -286,6 +302,12 @@ const fieldLabel = (key: string, fieldSchema: TQorusFormFieldSchema | undefined)
  * the `%` ceiling stops one long name from taking the whole row when the inset
  * is narrow — a phone, or a deeply nested level.
  */
+/** Approximate rendered width of one label character, in px. See `labelColumn`. */
+const LABEL_CHAR_PX = 9.5;
+
+/** Gap to the value, so the longest label is not flush against it. */
+const LABEL_SLACK_PX = 14;
+
 const labelColumn = (value: unknown, schema: IQorusFormSchema): string => {
   const inner = unwrap(value);
   const records = (Array.isArray(inner) ? inner.map(unwrap) : [inner]).filter(isRecord);
@@ -297,9 +319,26 @@ const labelColumn = (value: unknown, schema: IQorusFormSchema): string => {
     );
     return Math.max(widest, own);
   }, 0);
-  return longest ? `min(${longest + 1}ch, 45%)` : '140px';
+  // px, not `ch`. `ch` is the base font's `0` advance and knows nothing about
+  // the label's own treatment — uppercase, semibold, `letter-spacing: 0.06em`,
+  // at 12px — so it under-measures by about a tenth. With `overflow-wrap:
+  // anywhere` on the label, an under-measured column does not ellipsise, it
+  // BREAKS THE NAME IN HALF: `LEGACY_FLAG` came out over two lines the moment
+  // the labels became uppercase. Erring high costs a few px of gap; erring low
+  // costs a broken word.
+  return longest ? `min(${Math.ceil(longest * LABEL_CHAR_PX + LABEL_SLACK_PX)}px, 45%)` : '140px';
 };
 
+/**
+ * `true` when a value is an address a browser can open.
+ *
+ * Deliberately per VALUE, not per field: a field named `url` frequently holds
+ * something that is not one — a bare path, a regex, a template — and offering
+ * those a link promises a destination there is not.
+ */
+const isNavigableUrl = (value: unknown): value is string =>
+  typeof value === 'string' && /^(https?|wss?|ftps?):\/\//i.test(value);
+
 /** One field's value, rendered the way its row above renders it. */
 const FieldValue = ({
   field,
@@ -345,7 +384,22 @@ const FieldValue = ({
               style={{ flexShrink: 0, marginRight: 6, verticalAlign: 'middle' }}
             />
           : null}
-          {formatted}
+          {isNavigableUrl(field.value) ?
+            // The address IS the link — it used to render as inert text with a
+            // separate icon button beside it to open it, which is two things
+            // where there is one. ReqoreLink renders a real anchor, so
+            // middle-click and "copy link address" still work;
+            // `stopPropagation` because the row around it toggles.
+            <ReqoreLink
+              className='schema-view-open-url'
+              href={field.value}
+              target='_blank'
+              rel='noreferrer noopener'
+              onClick={(event: React.MouseEvent) => event.stopPropagation()}
+            >
+              {formatted}
+            </ReqoreLink>
+          : formatted}
         </span>
       }
     </StyledRowValue>
@@ -394,7 +448,7 @@ const SchemaRecord = ({
         return (
           <React.Fragment key={key}>
             <StyledNestedLabel>
-              <StyledRowLabel $color={colors.key}>{labelWithType}</StyledRowLabel>
+              <StyledFieldLabel $color={colors.key}>{labelWithType}</StyledFieldLabel>
             </StyledNestedLabel>
             <StyledNested $border={colors.border}>
               <SchemaLevel value={value} schema={nested} showTypes={showTypes} colors={colors} />
@@ -412,7 +466,7 @@ const SchemaRecord = ({
         return (
           <React.Fragment key={key}>
             <StyledNestedLabel>
-              <StyledRowLabel $color={colors.key}>{labelWithType}</StyledRowLabel>
+              <StyledFieldLabel $color={colors.key}>{labelWithType}</StyledFieldLabel>
             </StyledNestedLabel>
             <StyledCodeCell onClick={(event) => event.stopPropagation()}>
               <ReqoreCollapsibleContent
@@ -444,9 +498,9 @@ const SchemaRecord = ({
 
       return (
         <React.Fragment key={key}>
-          <StyledRowLabel $color={colors.key} title={label}>
+          <StyledFieldLabel $color={colors.key} title={label}>
             {labelWithType}
-          </StyledRowLabel>
+          </StyledFieldLabel>
           <FieldValue
             field={{ type: fieldSchema?.type, value } as IQorusFormField}
             fieldSchema={fieldSchema}
@@ -481,16 +535,17 @@ const SchemaLevel = ({
           return (
             <StyledItem key={index} className='schema-view-item'>
               <StyledMarker $color={colors.muted}>{index + 1}.</StyledMarker>
-              <StyledItemFields $border={colors.border}>
+              <StyledItemFields
+                $border={colors.border}
+                $rule={hasContentUnderHeading(record, schema)}
+              >
                 {isRecord(record) ?
                   <>
                     {(() => {
-                      const titleKey = titleKeyFor(record, schema);
-                      if (!titleKey) {
+                      const identity = recordIdentity(record, schema);
+                      if (!identity) {
                         return null;
                       }
-                      const fieldSchema = schema[titleKey] as TQorusFormFieldSchema | undefined;
-                      const raw = unwrap(record[titleKey]);
                       return (
                         <StyledItemTitle
                           className='schema-view-item-title'
@@ -498,14 +553,11 @@ const SchemaLevel = ({
                           // A literal keeps the mono treatment it has as a value —
                           // promoting it must not change what it IS. A chosen
                           // label ("Default RBAC") is prose and stays prose.
-                          $mono={!findAllowedValueOption(raw, fieldSchema)}
+                          $mono={identity.mono}
                           $accent={colors.accent}
-                          title={fieldLabel(titleKey, fieldSchema)}
+                          title={identity.label}
                         >
-                          {formatOptionValue(
-                            { type: fieldSchema?.type, value: raw } as IQorusFormField,
-                            fieldSchema
-                          )}
+                          {identity.text}
                         </StyledItemTitle>
                       );
                     })()}

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

@@ -61,6 +61,9 @@ export const PANEL_LEFT_CSS = `calc(${LABEL_COL} + ${COMPACT_ROW_PAD_X + COMPACT
 export const StyledCompactPanel = styled(ReqorePanel)<{
   $headerBg: string;
   $nested?: boolean;
+  /** True when the toolbar renders no search row (hidden via `compactToolbar`,
+   *  self-hidden on a single-option form, or no toolbar at all). */
+  $tightHeader?: boolean;
 }>`
   > .reqore-panel-title {
     /* The blur + translateZ exist only to make the STICKY top-level toolbar ghost
@@ -71,7 +74,17 @@ export const StyledCompactPanel = styled(ReqorePanel)<{
         'backdrop-filter: blur(6px); -webkit-backdrop-filter: blur(6px); transform: translateZ(0);'
       )}
     padding-top: ${GAP_FROM_SIZE[HEADER_GAP]}px;
-    padding-bottom: ${GAP_FROM_SIZE[HEADER_GAP]}px;
+    /* A header with a SEARCH ROW keeps the \`big\` gap below it — a tall
+       interactive control earns separation from the content it filters. A
+       header without one (search hidden via \`compactToolbar\`, self-hidden on
+       a single-option form, or no toolbar at all) is a thin strip, and at
+       \`big\` its padding stacked onto the panel content's own 8px into a 26px
+       dead band between the completion meter and the first status box —
+       rejected on build #140 as "unnecessarily big". \`normal\` lands it at
+       the boxes' own 10px rhythm, and scoping the change here keeps every
+       search-bearing form pixel-identical. */
+    padding-bottom: ${({ $tightHeader }) =>
+      $tightHeader ? GAP_FROM_SIZE.normal : GAP_FROM_SIZE[HEADER_GAP]}px;
   }
 
   /* Group framing. The HORIZONTAL rule is a real element in the header
@@ -320,6 +333,12 @@ export const StyledRowValue = styled.div<{ $color: string; $empty?: boolean }>`
     text-overflow: ellipsis;
     white-space: nowrap;
   }
+  /* The code size chip kept above an OPEN editor. The read row puts the same chip
+     at the top of the value cell with a 2px row-gap under it; matching that here is
+     what stops the editor moving as the field opens. */
+  .options-readfirst-editing-summary {
+    margin-bottom: 2px;
+  }
   .options-readfirst-reason {
     font-style: italic;
     font-size: 12px;
@@ -684,3 +703,27 @@ export const StyledGroupBody = styled.div<{
     padding-bottom: 0;
   }
 `;
+
+// One absorbed sibling, rendered inside its host row's container rather than
+// on a row of its own (see `absorb_fields`). The pair this exists for is a code
+// editor and its language: reading them as two unrelated rows one above the
+// other said they were separate decisions, and they are not.
+//
+// Laid out as label-then-control on one line so it reads as a property of the
+// element it now sits in, and separated from the editor below it by a hairline
+// rather than a gap — the two share one container, so the seam has to look like
+// a division inside it and not like two stacked things.
+export const StyledAbsorbedField = styled.div`
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-width: 0;
+  padding-bottom: 8px;
+  margin-bottom: 8px;
+  border-bottom: 1px solid ${({ theme }) => `${theme.main}22`};
+`;
+
+export const StyledAbsorbedLabel = styled(ReqoreP)`
+  flex: 0 0 auto;
+  margin: 0;
+`;

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

@@ -24,6 +24,14 @@ 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';
@@ -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,31 @@ 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 +676,27 @@ 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.
+    const isEmptyEnvelope =
+      !!subSchema &&
+      !!raw &&
+      typeof raw === 'object' &&
+      !Array.isArray(raw) &&
+      !('value' in (raw as object)) &&
+      Object.keys(raw as object).every((k) => k === 'type' || k === 'is_expression');
     const isFieldShape =
       (!!subSchema &&
         !!raw &&
         typeof raw === 'object' &&
         !Array.isArray(raw) &&
         'value' in (raw as object)) ||
+      isEmptyEnvelope ||
       isTypedEnvelope(raw);
     const subOption: IQorusFormField =
       isFieldShape ?
@@ -793,3 +838,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;