@qoretechnologies/reqraft 0.10.36 → 0.10.38-pr.95.gf1f6403

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

@@ -0,0 +1,462 @@
+import { ReqoreCollapsibleContent, ReqoreIcon, ReqoreP, ReqoreTag } from '@qoretechnologies/reqore';
+import {
+  IQorusFormField,
+  IQorusFormSchema,
+  TQorusFormFieldSchema,
+} from '@qoretechnologies/ts-toolkit';
+import React from 'react';
+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 { isUiEncodedValue } from './structuredData';
+
+/**
+ * A read-only rendering of a value THROUGH the schema that describes it.
+ *
+ * `StructuredDataView` renders data nobody has described: it has to announce
+ * what it found ("Object · 2 fields"), print raw keys, and colour values by
+ * inferred type, because inference is all it has. That is the right rendering
+ * for untyped data and the wrong one for ours — a form field with an
+ * `arg_schema` is a value whose shape, names and choices are all known in
+ * advance, and showing it as a data tree asks the reader to decode a structure
+ * the form already knows how to say out loud.
+ *
+ * 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.
+ * - 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
+ *   and the editor.
+ * - Fields appear in the schema's order — the order the form puts them in.
+ *
+ * A list renders as numbered items: the number sits in a left margin with a rule
+ * running down beside the fields belonging to it, and the item's first field
+ * starts on the number's own line. The rule is what makes a list of multi-field
+ * items readable — without it, "which item does this field belong to?" is
+ * answered only by counting.
+ *
+ * Two deliberate properties:
+ *
+ * - **Nothing is hidden.** A key the schema does not describe is still shown,
+ *   under its raw name, after the described ones. A preview that quietly dropped
+ *   data would be worse than a raw tree, not better.
+ * - **It degrades, it does not fail.** With no schema for a level, the caller
+ *   keeps using `StructuredDataView` — undescribed data still deserves the
+ *   renderer built for undescribed data.
+ */
+
+/** Width of the shared label column, set once on the root (see `labelColumn`). */
+const LABEL_COL_VAR = '--schema-view-label-col';
+
+const StyledSchemaView = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  min-width: 0;
+`;
+
+/**
+ * One list item: its number in the left margin, its fields beside it.
+ *
+ * `align-items: start` over a single grid row is what puts the first field on
+ * the number's line — the fields are one block starting at the top, not a grid
+ * row each, so nothing can push them down past their own marker.
+ */
+const StyledItem = styled.div`
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  column-gap: 8px;
+  align-items: start;
+  min-width: 0;
+`;
+
+/** The item number. Furniture, so it reads quieter than the data it indexes;
+ *  `tabular-nums` keeps "9." and "10." the same width. */
+const StyledMarker = styled.div<{ $color: string }>`
+  color: ${({ $color }) => $color};
+  font-size: 12px;
+  font-variant-numeric: tabular-nums;
+  line-height: 20px;
+  white-space: nowrap;
+`;
+
+/** 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;
+  min-width: 0;
+`;
+
+/**
+ * A record's fields: one shared label column, values in the next.
+ *
+ * The column width is a variable set once on the root, so every field of every
+ * item lines up on one edge. Sizing per record would align an item's own fields
+ * and leave the items ragged against each other, which reads as a rendering
+ * fault rather than as a list.
+ */
+const StyledFields = styled.div`
+  display: grid;
+  grid-template-columns: var(${LABEL_COL_VAR}, 140px) minmax(0, 1fr);
+  column-gap: 10px;
+  row-gap: 2px;
+  align-items: baseline;
+  min-width: 0;
+
+  /* A row's value truncates because a row is one line high. The preview is the
+     place that shows what the row could not, so a long value wraps here instead
+     of ellipsising — otherwise opening the preview would reveal exactly as
+     little as the line above it. */
+  .options-readfirst-valuetext {
+    white-space: normal;
+    overflow: visible;
+    text-overflow: clip;
+    overflow-wrap: anywhere;
+  }
+
+  /* Mono faces run visually larger than the UI face at the same pixel size, so
+     a literal set at the row's 13px looks a step bolder than the label naming
+     it. A hair smaller puts the two back on the same footing. */
+  .schema-view-data {
+    font-size: 12.5px;
+  }
+`;
+
+/** A nested level spans both columns and indents under its own name. */
+const StyledNested = styled.div<{ $border: string }>`
+  grid-column: 1 / -1;
+  margin-left: 2px;
+  padding-left: 10px;
+  border-left: 1px solid ${({ $border }) => $border};
+  min-width: 0;
+`;
+
+const StyledNestedLabel = styled.div`
+  grid-column: 1 / -1;
+`;
+
+/** A code value is a block, not a cell: it spans the grid under its own name. */
+const StyledCodeCell = styled.div`
+  grid-column: 1 / -1;
+  min-width: 0;
+  margin: 2px 0 4px;
+`;
+
+export interface ISchemaDataViewProps {
+  /** The stored value, with or without `{type, value}` envelopes. */
+  value: unknown;
+  /** The schema describing this level — a field's `arg_schema`. */
+  schema: IQorusFormSchema;
+  /** Show each field's declared type beside its name. */
+  showTypes?: boolean;
+  /** Colours, taken from the row so the preview matches its surroundings. */
+  colors: { key: string; muted: string; border: string };
+  onItemClick?: () => void;
+}
+
+/** Look inside a `{type, value}` envelope, once. `isUiEncodedValue` is the
+ *  engine's single authority on what an envelope is — a looser test would unwrap
+ *  a real user hash that happens to carry a `value` key and drop its siblings. */
+const unwrap = (item: unknown): unknown => (isUiEncodedValue(item) ? item.value : item);
+
+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';
+};
+
+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.
+ *
+ * A fixed width is a guess in both directions: too wide and a name sits far from
+ * its value, too narrow and every name ellipsises. Measuring fits the content;
+ * the `%` ceiling stops one long name from taking the whole row when the inset
+ * is narrow — a phone, or a deeply nested level.
+ */
+const labelColumn = (value: unknown, schema: IQorusFormSchema): string => {
+  const inner = unwrap(value);
+  const records = (Array.isArray(inner) ? inner.map(unwrap) : [inner]).filter(isRecord);
+  const longest = records.reduce((widest, record) => {
+    const own = orderedKeys(record, schema).reduce(
+      (max, key) =>
+        Math.max(max, fieldLabel(key, schema[key] as TQorusFormFieldSchema | undefined).length),
+      0
+    );
+    return Math.max(widest, own);
+  }, 0);
+  return longest ? `min(${longest + 1}ch, 45%)` : '140px';
+};
+
+/** One field's value, rendered the way its row above renders it. */
+const FieldValue = ({
+  field,
+  fieldSchema,
+  color,
+}: {
+  field: IQorusFormField;
+  fieldSchema: TQorusFormFieldSchema | undefined;
+  color: string;
+}) => {
+  const formatted = formatOptionValue(field, fieldSchema);
+  // An allowed value that carries a logo shows it here too, exactly as the row
+  // above does — the preview is the same value, so it gets the same treatment.
+  const image = getAllowedValueImage(field.value, fieldSchema);
+
+  // Data reads in mono; a chosen label does not.
+  //
+  // "qorus-session" is a literal the author typed — an identifier where the
+  // characters themselves matter, and where a proportional font makes `l`/`1`
+  // and `O`/`0` a guess. "Default RBAC" is not data at all: it is the name of a
+  // choice, written by whoever wrote the schema, and setting it in mono would
+  // dress up a label as a value. Resolving through `allowed_values` is what
+  // separates the two, and it is the same lookup that produced the text.
+  const isChosenLabel = !!findAllowedValueOption(field.value, fieldSchema);
+
+  return (
+    <StyledRowValue $color={color}>
+      {field.value === true || field.value === false ?
+        <ReqoreTag
+          size='small'
+          minimal
+          intent={field.value === true ? 'success' : 'danger'}
+          label={formatted}
+        />
+      : <span
+          className={`options-readfirst-valuetext${isChosenLabel ? '' : ' schema-view-data'}`}
+          style={isChosenLabel ? undefined : { fontFamily: MONO_FONT_STACK }}
+        >
+          {image ?
+            <ReqoreIcon
+              image={image}
+              size='14px'
+              style={{ flexShrink: 0, marginRight: 6, verticalAlign: 'middle' }}
+            />
+          : null}
+          {formatted}
+        </span>
+      }
+    </StyledRowValue>
+  );
+};
+
+/** One described hash: its fields as label/value pairs in the shared columns. */
+const SchemaRecord = ({
+  record,
+  schema,
+  showTypes,
+  colors,
+}: {
+  record: Record<string, unknown>;
+  schema: IQorusFormSchema;
+  showTypes?: boolean;
+  colors: ISchemaDataViewProps['colors'];
+}) => {
+  // The SAME host renderer the row above uses for a `code-editor` field. Read
+  // from context rather than threaded through props: a nested level is arbitrarily
+  // deep, and the renderer is a property of the form, not of any one level.
+  const codePreviewRenderer = useContextSelector(
+    CompactRowContext,
+    (v) => v.codePreviewRenderer
+  );
+  const cHover = useContextSelector(CompactRowContext, (v) => v.cHover);
+
+  return (
+  <StyledFields className='schema-view-fields'>
+    {orderedKeys(record, schema).map((key) => {
+      const fieldSchema = schema[key] as TQorusFormFieldSchema | undefined;
+      const nested = (fieldSchema as { arg_schema?: IQorusFormSchema } | undefined)?.arg_schema;
+      const value = unwrap(record[key]);
+      const label = fieldLabel(key, fieldSchema);
+      const labelWithType =
+        showTypes && fieldSchema?.type ? `${label} · ${fieldSchema.type}` : label;
+
+      // A field that describes its own level renders AS that level, indented
+      // under its name — the same decision, one step down.
+      if (nested && (isRecord(value) || Array.isArray(value))) {
+        return (
+          <React.Fragment key={key}>
+            <StyledNestedLabel>
+              <StyledRowLabel $color={colors.key}>{labelWithType}</StyledRowLabel>
+            </StyledNestedLabel>
+            <StyledNested $border={colors.border}>
+              <SchemaLevel value={value} schema={nested} showTypes={showTypes} colors={colors} />
+            </StyledNested>
+          </React.Fragment>
+        );
+      }
+
+      // A code value is source, and source is read as source: the host's renderer
+      // gives it the syntax highlighting (and read-only LSP hover) it has in the
+      // Source Code field, and "Show more" keeps a long body from taking over the
+      // preview. Flattening it to one mono line — which is what a plain value cell
+      // does — throws all of that away for a field whose whole content is code.
+      if (isCodeField(fieldSchema) && typeof value === 'string') {
+        return (
+          <React.Fragment key={key}>
+            <StyledNestedLabel>
+              <StyledRowLabel $color={colors.key}>{labelWithType}</StyledRowLabel>
+            </StyledNestedLabel>
+            <StyledCodeCell onClick={(event) => event.stopPropagation()}>
+              <ReqoreCollapsibleContent
+                maxCollapsedHeight={96}
+                buttonProps={{ className: 'options-readfirst-viewmore' }}
+              >
+                {codePreviewRenderer ?
+                  codePreviewRenderer({
+                    value,
+                    name: key,
+                    schema: fieldSchema,
+                    options: schema,
+                    values: record as never,
+                  })
+                : <StyledCodePreview
+                    className='options-readfirst-code'
+                    $bg={cHover}
+                    $border={`${colors.border}88`}
+                    $fg={colors.key}
+                  >
+                    {value}
+                  </StyledCodePreview>
+                }
+              </ReqoreCollapsibleContent>
+            </StyledCodeCell>
+          </React.Fragment>
+        );
+      }
+
+      return (
+        <React.Fragment key={key}>
+          <StyledRowLabel $color={colors.key} title={label}>
+            {labelWithType}
+          </StyledRowLabel>
+          <FieldValue
+            field={{ type: fieldSchema?.type, value } as IQorusFormField}
+            fieldSchema={fieldSchema}
+            color={colors.key}
+          />
+        </React.Fragment>
+      );
+    })}
+  </StyledFields>
+  );
+};
+
+/** A level: a list of numbered items, or a single described hash. */
+const SchemaLevel = ({
+  value,
+  schema,
+  showTypes,
+  colors,
+}: {
+  value: unknown;
+  schema: IQorusFormSchema;
+  showTypes?: boolean;
+  colors: ISchemaDataViewProps['colors'];
+}) => {
+  const inner = unwrap(value);
+
+  if (Array.isArray(inner)) {
+    return (
+      <>
+        {inner.map((item, index) => {
+          const record = unwrap(item);
+          return (
+            <StyledItem key={index} className='schema-view-item'>
+              <StyledMarker $color={colors.muted}>{index + 1}.</StyledMarker>
+              <StyledItemFields $border={colors.border}>
+                {isRecord(record) ?
+                  <SchemaRecord
+                    record={record}
+                    schema={schema}
+                    showTypes={showTypes}
+                    colors={colors}
+                  />
+                : <StyledRowValue $color={colors.key}>
+                    <span
+                      className='options-readfirst-valuetext schema-view-data'
+                      style={{ fontFamily: MONO_FONT_STACK }}
+                    >
+                      {formatOptionValue({ value: record } as IQorusFormField)}
+                    </span>
+                  </StyledRowValue>
+                }
+              </StyledItemFields>
+            </StyledItem>
+          );
+        })}
+      </>
+    );
+  }
+
+  if (isRecord(inner)) {
+    return <SchemaRecord record={inner} schema={schema} showTypes={showTypes} colors={colors} />;
+  }
+
+  return (
+    <ReqoreP size='small' style={{ color: colors.key }}>
+      {formatOptionValue({ value: inner } as IQorusFormField)}
+    </ReqoreP>
+  );
+};
+
+export const SchemaDataView = React.memo(
+  ({ value, schema, showTypes, colors, onItemClick }: ISchemaDataViewProps) => (
+    <StyledSchemaView
+      className='schema-data-view'
+      onClick={onItemClick}
+      style={{ [LABEL_COL_VAR]: labelColumn(value, schema) } as React.CSSProperties}
+    >
+      <SchemaLevel value={value} schema={schema} showTypes={showTypes} colors={colors} />
+    </StyledSchemaView>
+  )
+);
+
+SchemaDataView.displayName = 'SchemaDataView';
+
+/**
+ * Whether a value can be rendered through a schema at all.
+ *
+ * A schema describes fields, so there has to be a described level to show: a
+ * hash, or a list of them. A list of scalars has no field names to use and falls
+ * back to the untyped renderer, which is the right tool for it.
+ */
+export const canRenderWithSchema = (value: unknown, schema: unknown): boolean => {
+  if (!schema || typeof schema !== 'object' || !Object.keys(schema).length) {
+    return false;
+  }
+  const inner = unwrap(value);
+  if (Array.isArray(inner)) {
+    return inner.some((item) => isRecord(unwrap(item)));
+  }
+  return isRecord(inner);
+};

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

@@ -381,6 +381,19 @@ export const StyledRowInset = styled.div`
   margin-top: 4px;
 `;
 
+/**
+ * The stack literal text renders in: source, ids, tokens, data strings.
+ *
+ * Defined HERE rather than taken from reqore's `ReqoreFonts.mono`, which is the
+ * same stack. Reqore is a peer dependency at `>=0.71.16` and that export arrived
+ * later, so reading it would crash every consumer inside the declared range —
+ * the whole form preview lost over a font choice. One local constant costs
+ * nothing and keeps the code preview and the schema view's data values
+ * identical, which is the only reason to share it in the first place.
+ */
+export const MONO_FONT_STACK =
+  "ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace";
+
 // A collapsed code-block preview shown under the value summary for a
 // `code-editor` field.  Multi-line, monospace, subtle background — matches
 // the aesthetic of the classic code-view surface but small enough to sit
@@ -393,8 +406,7 @@ export const StyledCodePreview = styled.pre<{ $bg: string; $border: string; $fg:
   background: ${({ $bg }) => $bg};
   border: 1px solid ${({ $border }) => $border};
   color: ${({ $fg }) => $fg};
-  font-family:
-    ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace;
+  font-family: ${MONO_FONT_STACK};
   font-size: 11.5px;
   line-height: 1.5;
   white-space: pre;

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

@@ -40,6 +40,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 +103,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 +191,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 +228,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 => {

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

@@ -64,6 +64,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 +93,7 @@ export const ArrayAuto = ({
   );
 
   const addValue: () => void = () => {
+    setJustAddedIndex(localValue.length);
     setLocalValue([...localValue, defaultValueByType[rest.type]]);
   };
 
@@ -171,6 +178,11 @@ 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)}
           />

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