feat(flow-designer): nested-array columns in the node property form (#2678 P2-5) (#2761)

The server-driven node property form (configSchema → FlowConfigField) now
renders nested arrays inside an objectList repeater instead of degrading them
to a plain text cell that String()-joined and corrupted the array on save. A
repeater column whose item property is itself an array becomes a nested
repeater (repeater-in-repeater):

- json-schema-to-fields `columnsFor` maps an array-typed item property to a
  stringList / numberList / objectList column; object-array columns derive their
  nested columns recursively (bounded by a nesting cap so a pathological / cyclic
  schema can't build a non-terminating form). Unrepresentable arrays fall through
  to the prior text behavior — no regression.
- FlowConfigColumn gains the three list kinds plus a recursive `columns` for
  nested objectList.
- FlowObjectListField renders those columns via the shared FlowStringListField
  (string/number lists, with number[] coercion) and a recursive
  FlowObjectListField (object lists), round-tripping each cell as an array.

Closes the last open acceptance item of #2678 (P2-5). Docs + changeset updated;
new mapper + nested-render tests.


Claude-Session: https://claude.ai/code/session_01Sa7REWrWMsukqPbtoGASPr

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/flow-designer-nested-array-columns.md

@@ -0,0 +1,26 @@
+---
+"@object-ui/app-shell": minor
+---
+
+feat(app-shell): nested-array columns in the flow designer property form (#2678 P2-5)
+
+The server-driven node property form (`configSchema` → `FlowConfigField`) now
+renders **nested arrays** inside an `objectList` repeater instead of degrading
+them to a plain text cell that `String()`-joined and corrupted the array on
+save. A repeater column whose item property is itself an array becomes a
+**nested repeater** (repeater-in-repeater):
+
+- `json-schema-to-fields` `columnsFor` maps an array-typed item property to a
+  `stringList` / `numberList` / `objectList` column; object-array columns derive
+  their own nested columns recursively (bounded by a nesting cap so a
+  pathological / cyclic schema can't build a non-terminating form). Arrays that
+  still aren't representable fall through to the prior text behavior — no
+  regression.
+- `FlowConfigColumn` gains the three list `kind`s plus a recursive `columns` for
+  nested `objectList`.
+- `FlowObjectListField` renders those columns via the shared `FlowStringListField`
+  (string/number lists, with `number[]` coercion) and a recursive
+  `FlowObjectListField` (object lists), round-tripping each cell as an array.
+
+Any engine-published node config with a nested array is now editable inline
+rather than dropping to the Advanced JSON escape hatch.

content/docs/guide/flow-designer.md

@@ -106,6 +106,12 @@ intermediate state.
 For node types whose engine executor publishes a `configSchema` (ADR-0018), the
 inspector renders a **server-driven property form** from that schema — so a
 plugin's node gets a real config UI without the designer hardcoding its fields.
+The mapping covers scalars, enums (→ select), typed references (→ picker),
+free-form maps (→ key/value), and array/object shapes: an array of objects
+becomes a **repeater**, and a repeater column that is itself an array (of
+strings, numbers, or objects) becomes a **nested repeater** — so an
+engine-published nested-array config is editable inline rather than dropping to
+the Advanced JSON block.
 
 A **Decision** node's Branches editor defines each branch's label, CEL
 expression, **and target node** in one table: the **Target** column picks the

packages/app-shell/README.md

@@ -364,7 +364,11 @@ Config keys come in three editable shapes so authors never hand-write JSON:
   single-column **string-list editor** (`stringList` kind).
 - **Arrays of objects** — a `screen` node's **Fields** (a list of
   `{name,label,type,required,visibleWhen}` definitions) — use a column-driven
-  **object-list repeater** (`objectList` kind).
+  **object-list repeater** (`objectList` kind). A repeater column can itself be a
+  list: an item property that is an array of strings / numbers / objects renders
+  as a **nested repeater** (`stringList` / `numberList` / `objectList` column) —
+  a repeater-in-repeater — so an engine-published nested-array config is editable
+  inline instead of falling to the Advanced JSON block (#2678 P2-5).
 
 A `decision` node's **Branches** repeater additionally shows a per-branch
 **Target** column (#1942) — a node picker scoped to this flow — so the whole

packages/app-shell/src/views/metadata-admin/inspectors/FlowNodeConfigField.tsx

@@ -111,6 +111,7 @@ export function FlowNodeConfigField({ field, value, onCommit, disabled, locale,
             addLabel={t('engine.inspector.flowNode.list.add', locale)}
             removeLabel={t('engine.inspector.flowNode.list.remove', locale)}
             emptyLabel={t('engine.inspector.flowNode.list.empty', locale)}
+            itemLabel={t('engine.inspector.flowNode.list.item', locale)}
             context={context}
             scopeGroups={scopeGroups}
           />

packages/app-shell/src/views/metadata-admin/inspectors/FlowObjectListField.nested.test.tsx

@@ -0,0 +1,83 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #2678 P2-5 — an `objectList` column may itself be a list (repeater-in-repeater).
+ * Before this branch a nested array item property fell through to a plain text
+ * cell that `String()`-joined the array and corrupted it on save. These tests
+ * pin that a nested `stringList` / `numberList` / `objectList` column renders its
+ * own editor and round-trips the nested array through `onCommit` as an array —
+ * `numberList` coerced back to `number[]`, not the widget's display strings.
+ */
+
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, screen, cleanup, fireEvent } from '@testing-library/react';
+import { FlowObjectListField } from './FlowObjectListField';
+import type { FlowConfigColumn } from './flow-node-config';
+
+afterEach(cleanup);
+
+const baseProps = {
+  onCommit: vi.fn(),
+  addLabel: 'Add',
+  removeLabel: 'Remove',
+  emptyLabel: 'None',
+  itemLabel: 'Item',
+};
+
+describe('FlowObjectListField — nested stringList column', () => {
+  const columns: FlowConfigColumn[] = [
+    { key: 'name', label: 'Name', kind: 'text' },
+    { key: 'recipients', label: 'Recipients', kind: 'stringList' },
+  ];
+
+  it('renders the nested array as its own list editor (not a joined text cell)', () => {
+    render(<FlowObjectListField label="Rules" columns={columns} value={[{ name: 'r1', recipients: ['a@x.com', 'b@x.com'] }]} {...baseProps} />);
+    // Each nested item is its own input — a text cell would show "a@x.com,b@x.com".
+    expect(screen.getByDisplayValue('a@x.com')).toBeInTheDocument();
+    expect(screen.getByDisplayValue('b@x.com')).toBeInTheDocument();
+    expect(screen.queryByDisplayValue('a@x.com,b@x.com')).not.toBeInTheDocument();
+  });
+
+  it('round-trips an edit to a nested item as a string[] on the parent object', () => {
+    const onCommit = vi.fn();
+    render(<FlowObjectListField label="Rules" columns={columns} value={[{ name: 'r1', recipients: ['a@x.com'] }]} {...baseProps} onCommit={onCommit} />);
+    const input = screen.getByDisplayValue('a@x.com');
+    fireEvent.change(input, { target: { value: 'z@x.com' } });
+    fireEvent.blur(input);
+    expect(onCommit).toHaveBeenCalled();
+    expect(onCommit.mock.calls.at(-1)![0]).toEqual([{ name: 'r1', recipients: ['z@x.com'] }]);
+  });
+});
+
+describe('FlowObjectListField — nested numberList column', () => {
+  const columns: FlowConfigColumn[] = [{ key: 'offsets', label: 'Offsets', kind: 'numberList' }];
+
+  it('shows stored numbers as text and commits number[] (not the display strings)', () => {
+    const onCommit = vi.fn();
+    render(<FlowObjectListField label="Timers" columns={columns} value={[{ offsets: [1, 2] }]} {...baseProps} onCommit={onCommit} />);
+    expect(screen.getByDisplayValue('1')).toBeInTheDocument();
+    expect(screen.getByDisplayValue('2')).toBeInTheDocument();
+    fireEvent.change(screen.getByDisplayValue('1'), { target: { value: '5' } });
+    fireEvent.blur(screen.getByDisplayValue('5'));
+    expect(onCommit.mock.calls.at(-1)![0]).toEqual([{ offsets: [5, 2] }]);
+  });
+});
+
+describe('FlowObjectListField — nested objectList column (repeater-in-repeater)', () => {
+  const columns: FlowConfigColumn[] = [
+    { key: 'label', label: 'Label', kind: 'text' },
+    {
+      key: 'members',
+      label: 'Members',
+      kind: 'objectList',
+      columns: [{ key: 'user', label: 'User', kind: 'text' }],
+    },
+  ];
+
+  it('renders a nested repeater row from the nested array', () => {
+    render(<FlowObjectListField label="Groups" columns={columns} value={[{ label: 'mgr', members: [{ user: 'alice' }] }]} {...baseProps} />);
+    expect(screen.getByDisplayValue('mgr')).toBeInTheDocument();
+    // The doubly-nested member value renders through the recursive mount.
+    expect(screen.getByDisplayValue('alice')).toBeInTheDocument();
+  });
+});

packages/app-shell/src/views/metadata-admin/inspectors/FlowObjectListField.tsx

@@ -9,6 +9,11 @@
  * state with a STABLE id and flushed on blur / Enter / add / remove so a row
  * never remounts mid-keystroke. Empty per-cell values are pruned; a row with no
  * populated cells is dropped on flush; an empty list commits `undefined`.
+ *
+ * A column may itself be a *list* (`stringList` / `numberList` / `objectList`) —
+ * a repeater-in-repeater. Those cells hold an array and render the matching
+ * sibling editor inline (recursively, for `objectList`), so an engine-published
+ * nested-array config is editable here instead of dropping to Advanced JSON.
  */
 
 import * as React from 'react';
@@ -20,16 +25,23 @@ import {
 import { uniqueId } from './_shared';
 import type { FlowConfigColumn } from './flow-node-config';
 import { ReferenceCombobox, resolveRefKind, type FlowReferenceContext } from './FlowReferenceField';
+import { FlowStringListField } from './FlowStringListField';
 import { VariableTextInput } from './VariableTextInput';
 import type { ScopeGroup } from './useFlowScope';
 import { FlowExprIssue } from './FlowExprIssue';
 
-type Cell = string | boolean;
+/** A cell is a scalar (string/boolean) or, for a nested-list column, an array. */
+type Cell = string | boolean | unknown[];
 interface Row {
   id: string;
   values: Record<string, Cell>;
 }
 
+/** Columns whose cell holds an array (a nested repeater) rather than a scalar. */
+function isListColumn(kind: FlowConfigColumn['kind']): boolean {
+  return kind === 'stringList' || kind === 'numberList' || kind === 'objectList';
+}
+
 function toRows(list: Array<Record<string, unknown>>, columns: FlowConfigColumn[]): Row[] {
   const ids: string[] = [];
   return list.map((item) => {
@@ -39,6 +51,7 @@ function toRows(list: Array<Record<string, unknown>>, columns: FlowConfigColumn[
     for (const col of columns) {
       const v = item[col.key];
       if (col.kind === 'boolean') values[col.key] = v === true;
+      else if (isListColumn(col.kind)) values[col.key] = Array.isArray(v) ? v : [];
       else if (v != null) values[col.key] = String(v);
       else values[col.key] = '';
     }
@@ -58,6 +71,13 @@ function rowsToList(rows: Row[], columns: FlowConfigColumn[]): Array<Record<stri
           obj[col.key] = true;
           hasValue = true;
         }
+      } else if (isListColumn(col.kind)) {
+        // A nested list commits its own already-normalized array (string[] /
+        // number[] / object[]); an empty nested list drops the key entirely.
+        if (Array.isArray(v) && v.length > 0) {
+          obj[col.key] = v;
+          hasValue = true;
+        }
       } else if (typeof v === 'string' && v.trim() !== '') {
         obj[col.key] = v.trim();
         hasValue = true;
@@ -77,6 +97,8 @@ export interface FlowObjectListFieldProps {
   addLabel: string;
   removeLabel: string;
   emptyLabel: string;
+  /** Per-item placeholder for nested `stringList` / `numberList` columns. */
+  itemLabel?: string;
   /** Draft + node context so `reference` columns can resolve their options. */
   context?: FlowReferenceContext;
   /** In-scope variable references for `expression` columns (#1934). */
@@ -92,6 +114,7 @@ export function FlowObjectListField({
   addLabel,
   removeLabel,
   emptyLabel,
+  itemLabel,
   context,
   scopeGroups,
 }: FlowObjectListFieldProps) {
@@ -123,9 +146,22 @@ export function FlowObjectListField({
     setRows((rs) => rs.map((r) => (r.id === id ? { ...r, values: { ...r.values, [key]: v } } : r)));
   };
 
+  // Set a cell AND flush — used by controls with no blur to flush on (checkbox,
+  // select) and by the nested-list editors, which each commit a whole array on
+  // their own blur/add/remove. The flush stays inside the `setRows` updater
+  // (the accepted idiom for the sibling scalar controls) so the `lastCommitted`
+  // ref is touched only there, never in the render body.
+  const commitCell = (id: string, key: string, v: Cell) => {
+    setRows((rs) => {
+      const next = rs.map((r) => (r.id === id ? { ...r, values: { ...r.values, [key]: v } } : r));
+      flush(next);
+      return next;
+    });
+  };
+
   const addRow = () => {
     const values: Record<string, Cell> = {};
-    for (const col of columns) values[col.key] = col.kind === 'boolean' ? false : '';
+    for (const col of columns) values[col.key] = col.kind === 'boolean' ? false : isListColumn(col.kind) ? [] : '';
     setRows((rs) => [...rs, { id: uniqueId('ol', rs.map((r) => r.id)), values }]);
   };
 
@@ -161,25 +197,67 @@ export function FlowObjectListField({
               </Button>
             </div>
             <div className="space-y-1.5">
-              {columns.map((col) => (
-                <div key={col.key} className="flex items-center gap-2">
+              {columns.map((col) => {
+                // A nested-list column (repeater-in-repeater) renders full-width
+                // as its own list editor, set off with a left rule. `stringList` /
+                // `numberList` reuse FlowStringListField; `objectList` recurses.
+                if (col.kind === 'stringList' || col.kind === 'numberList') {
+                  const raw = row.values[col.key];
+                  const arr = Array.isArray(raw) ? raw : [];
+                  return (
+                    <div key={col.key} className="border-l-2 border-muted/60 pl-2">
+                      <FlowStringListField
+                        label={col.label}
+                        value={col.kind === 'numberList' ? arr.map((n) => String(n)) : arr}
+                        onCommit={(v) => {
+                          if (col.kind === 'numberList') {
+                            const nums = (v ?? [])
+                              .map((s) => Number(String(s).trim()))
+                              .filter((n) => Number.isFinite(n));
+                            commitCell(row.id, col.key, nums);
+                          } else {
+                            commitCell(row.id, col.key, v ?? []);
+                          }
+                        }}
+                        disabled={disabled}
+                        addLabel={addLabel}
+                        itemLabel={itemLabel ?? col.label}
+                        removeLabel={removeLabel}
+                        emptyLabel={emptyLabel}
+                      />
+                    </div>
+                  );
+                }
+                if (col.kind === 'objectList') {
+                  const raw = row.values[col.key];
+                  const arr = (Array.isArray(raw) ? raw : []) as Array<Record<string, unknown>>;
+                  return (
+                    <div key={col.key} className="border-l-2 border-muted/60 pl-2">
+                      <FlowObjectListField
+                        label={col.label}
+                        columns={col.columns ?? []}
+                        value={arr}
+                        onCommit={(v) => commitCell(row.id, col.key, v ?? [])}
+                        disabled={disabled}
+                        addLabel={addLabel}
+                        removeLabel={removeLabel}
+                        emptyLabel={emptyLabel}
+                        itemLabel={itemLabel}
+                        context={context}
+                        scopeGroups={scopeGroups}
+                      />
+                    </div>
+                  );
+                }
+                return (
+                  <div key={col.key} className="flex items-center gap-2">
                   <Label className="w-24 shrink-0 text-[11px] text-muted-foreground">
                     {col.label}
                   </Label>
                   {col.kind === 'boolean' ? (
                     <Checkbox
                       checked={row.values[col.key] === true}
-                      onCheckedChange={(c) => {
-                        setRows((rs) => {
-                          const next = rs.map((r) =>
-                            r.id === row.id
-                              ? { ...r, values: { ...r.values, [col.key]: c === true } }
-                              : r,
-                          );
-                          flush(next);
-                          return next;
-                        });
-                      }}
+                      onCheckedChange={(c) => commitCell(row.id, col.key, c === true)}
                       disabled={disabled}
                     />
                   ) : col.kind === 'reference' ? (
@@ -213,17 +291,7 @@ export function FlowObjectListField({
                         <div className="flex-1">
                           <Select
                             value={current || undefined}
-                            onValueChange={(v) =>
-                              setRows((rs) => {
-                                const next = rs.map((r) =>
-                                  r.id === row.id
-                                    ? { ...r, values: { ...r.values, [col.key]: v } }
-                                    : r,
-                                );
-                                flush(next);
-                                return next;
-                              })
-                            }
+                            onValueChange={(v) => commitCell(row.id, col.key, v)}
                             disabled={disabled}
                           >
                             <SelectTrigger className="h-8 w-full text-xs">
@@ -274,8 +342,9 @@ export function FlowObjectListField({
                       className="h-8 flex-1 text-xs"
                     />
                   )}
-                </div>
-              ))}
+                  </div>
+                );
+              })}
             </div>
           </div>
         ))}

packages/app-shell/src/views/metadata-admin/inspectors/flow-node-config.ts

@@ -115,11 +115,31 @@ export interface FlowReferenceSpec {
 export interface FlowConfigColumn {
   key: string;
   label: string;
-  kind: 'text' | 'expression' | 'boolean' | 'select' | 'reference';
+  /**
+   * Scalar cells (`text`/`expression`/`boolean`/`select`/`reference`) plus the
+   * three *nested-list* kinds — a cell that is itself a repeater
+   * (repeater-in-repeater). `stringList`/`numberList` hold a primitive array;
+   * `objectList` holds an array-of-objects whose own shape is in {@link columns}.
+   */
+  kind:
+    | 'text'
+    | 'expression'
+    | 'boolean'
+    | 'select'
+    | 'reference'
+    | 'stringList'
+    | 'numberList'
+    | 'objectList';
   placeholder?: string;
   options?: Array<{ value: string; label: string }>;
   /** For `kind: 'reference'` — the picker data source (may be polymorphic). */
   ref?: FlowReferenceSpec;
+  /**
+   * For `kind: 'objectList'` — the nested repeater's own column schema. Recursive:
+   * a nested `objectList` column may itself carry `columns`, so an engine-published
+   * array-of-objects-of-…-arrays renders inline instead of dropping to Advanced JSON.
+   */
+  columns?: FlowConfigColumn[];
 }
 
 export interface FlowConfigField {