form0-core 0.1.25 → 0.1.26

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "form0-core",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
-  "description": "Schema-driven engine that powers form0 ecosystem. Looking for the full form0 ecosystem? Install the CLI: `npm install -g form0-cli`",
+  "description": "The schema-driven form engine behind form0, the open-source form ecosystem by paqu.io. Framework-agnostic: conditional visibility, validation and calculations from a JSON schema, in Node.js, browsers and React Native.",
   "main": "src/index.js",
   "type": "module",
   "scripts": {
-    "test": "node tests/form0-core.test.js && node tests/numeric-field-schema.test.js && node tests/dataset-descriptors.test.js && node tests/structured-record.test.js && node tests/builtin-metadata.test.js && node tests/calculation-editor.test.js && node tests/form-event-editor.test.js && node tests/security-test.js",
+    "test": "node tests/form0-core.test.js && node tests/numeric-field-schema.test.js && node tests/dataset-descriptors.test.js && node tests/structured-record.test.js && node tests/title-fields.test.js && node tests/builtin-metadata.test.js && node tests/calculation-editor.test.js && node tests/form-event-editor.test.js && node tests/security-test.js",
     "format": "prettier --write \"**/*.{js,jsx,json,ts,tsx,md}\"",
     "format:check": "prettier --check \"**/*.{js,jsx,json,ts,tsx,md}\""
   },
@@ -22,15 +22,17 @@
     "url": "git+https://github.com/paqu-io/form0-core.git"
   },
   "keywords": [
-    "form",
-    "form-builder",
-    "form-generator",
+    "form0",
+    "paqu-io",
     "form-engine",
-    "schema",
+    "schema-driven-forms",
     "json-schema",
-    "react",
-    "react-native",
-    "dynamic-forms"
+    "dynamic-forms",
+    "conditional-logic",
+    "form-validation",
+    "calculated-fields",
+    "headless-forms",
+    "framework-agnostic"
   ],
   "author": "paqu.io <hello@paqu.io> (https://paqu.io/)",
   "contributors": [

package/src/index.js

@@ -39,6 +39,7 @@ export {
   getFieldExportKind,
   getFieldQuerySemantics,
   projectDatasetRowValues,
+  resolveDatasetRowTitle,
   resolveDatasetDescriptorById,
 } from './utilities/dataset-descriptors.js';
 export { generateUuidV7 } from './utilities/uuid.js';

package/src/schema/field-specs.js

@@ -932,6 +932,7 @@ export const FIELD_SPECS = {
       visible_conditions: { type: 'object', required: true, nullable: true },
       location_enabled: { type: 'boolean', required: true, nullable: false },
       location_required: { type: 'boolean', required: true, nullable: false },
+      title_field: { type: 'object', required: false, nullable: true },
       elements: { type: 'array', required: true, nullable: false },
     },
     schemaValidators: [

package/src/schema/schema-validator.js

@@ -3,6 +3,73 @@ import { validateFieldSchema, validateDefaultValue } from './field-schema-regist
 import { isSupportedFieldType } from '../utilities/field-types.js';
 import { validateFieldConditions } from './operators.js';
 import { validateFormAIMetadata } from './ai-metadata-validator.js';
+import { buildDatasetDescriptors } from '../utilities/dataset-descriptors.js';
+
+const toNonEmptyString = (value) =>
+  typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+
+const getDescriptorFieldReferences = (field) =>
+  new Set(
+    [field?.field_id, field?.output_key, field?.key, field?.data_name, ...(field?.aliases || [])]
+      .map(toNonEmptyString)
+      .filter(Boolean)
+  );
+
+const validateScopedTitleFields = (form, errors) => {
+  const descriptors = buildDatasetDescriptors({ form });
+  const allReferenceDatasets = new Map();
+
+  descriptors.forEach((descriptor) => {
+    (descriptor.fields || []).forEach((field) => {
+      getDescriptorFieldReferences(field).forEach((reference) => {
+        if (!allReferenceDatasets.has(reference)) {
+          allReferenceDatasets.set(reference, new Set());
+        }
+        allReferenceDatasets.get(reference).add(descriptor.id);
+      });
+    });
+  });
+
+  descriptors.forEach((descriptor) => {
+    const titleField = descriptor.title_field;
+    if (!titleField) {
+      return;
+    }
+
+    const scopeLabel = descriptor.kind === 'root' ? 'title_field' : `RepeatableSection title_field`;
+    const titleValidation = validateFieldSchema(titleField);
+    if (!titleValidation.isValid) {
+      errors.push(...titleValidation.errors.map((error) => `${scopeLabel}: ${error}`));
+      return;
+    }
+
+    const scopedFields = descriptor.fields || [];
+    titleField.elements.forEach((entry) => {
+      const reference = toNonEmptyString(entry);
+      if (!reference) {
+        return;
+      }
+
+      const matchedField = scopedFields.find((field) =>
+        getDescriptorFieldReferences(field).has(reference)
+      );
+      if (!matchedField) {
+        if (allReferenceDatasets.has(reference)) {
+          errors.push(`${scopeLabel} reference "${reference}" is outside its record scope`);
+        } else {
+          errors.push(`${scopeLabel} reference "${reference}" does not match any field`);
+        }
+        return;
+      }
+
+      if (matchedField.title_eligible !== true) {
+        errors.push(
+          `${scopeLabel} reference "${reference}" uses unsupported field type ${matchedField.field_type}`
+        );
+      }
+    });
+  });
+};
 
 export function validateSchema(form) {
   const fields = flattenFields(form.elements);
@@ -180,12 +247,7 @@ export function validateSchema(form) {
       }
     }
   }
-  if (form.title_field) {
-    const titleValidation = validateFieldSchema(form.title_field);
-    if (!titleValidation.isValid) {
-      errors.push(...titleValidation.errors.map((e) => `title_field: ${e}`));
-    }
-  }
+  validateScopedTitleFields(form, errors);
 
   // Add duplicate errors to the main errors array
   if (duplicateDataNames.size > 0) {
@@ -225,7 +287,11 @@ export function validateSchema(form) {
               }
             }
 
-            if (!entry.form_id || typeof entry.form_id !== 'string' || entry.form_id.trim() === '') {
+            if (
+              !entry.form_id ||
+              typeof entry.form_id !== 'string' ||
+              entry.form_id.trim() === ''
+            ) {
               errors.push(`form_links.to[${index}].form_id must be a non-empty string`);
             }
           });
@@ -242,7 +308,11 @@ export function validateSchema(form) {
               return;
             }
 
-            if (!entry.form_id || typeof entry.form_id !== 'string' || entry.form_id.trim() === '') {
+            if (
+              !entry.form_id ||
+              typeof entry.form_id !== 'string' ||
+              entry.form_id.trim() === ''
+            ) {
               errors.push(`form_links.from[${index}].form_id must be a non-empty string`);
             }
 

package/src/utilities/dataset-descriptors.js

@@ -6,6 +6,16 @@ import {
 
 const ROOT_DATASET_ID = '__root__';
 const CONTAINER_TYPES = new Set(['Section', 'BuildingPlanSection']);
+const TITLE_ELIGIBLE_FIELD_TYPES = new Set([
+  'TextField',
+  'NumericField',
+  'DateField',
+  'TimeField',
+  'SingleChoiceField',
+  'MultiChoiceField',
+  'BooleanField',
+  'CalculatedField',
+]);
 
 const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 
@@ -79,6 +89,8 @@ const toRepeatableLabel = (field) =>
   toTrimmedString(field?.key) ??
   'Repeatable section';
 
+const cloneTitleField = (value) => (isRecord(value) ? { ...value } : null);
+
 const normalizeCalculatedDisplayStyle = (value) => {
   const normalized = toTrimmedString(value);
   if (!normalized) {
@@ -435,6 +447,7 @@ const buildDatasetFieldDescriptor = (field, dataset) => {
     data_name: toTrimmedString(field.data_name),
     label: toFieldLabel(field),
     field_type: toTrimmedString(field.type) ?? 'UnknownField',
+    title_eligible: TITLE_ELIGIBLE_FIELD_TYPES.has(field.type),
     export_kind: getFieldExportKind(field),
     choices: Array.isArray(field.choices)
       ? field.choices.filter((choice) => isRecord(choice)).map((choice) => ({ ...choice }))
@@ -510,6 +523,7 @@ const collectRepeatableDatasets = (elements, context, datasets) => {
       root_dataset_id: ROOT_DATASET_ID,
       location_enabled: toBooleanOrDefault(element.location_enabled),
       location_required: toBooleanOrDefault(element.location_required),
+      title_field: cloneTitleField(element.title_field),
       fields: [],
     };
 
@@ -548,6 +562,7 @@ export function buildDatasetDescriptors(schema) {
     root_dataset_id: ROOT_DATASET_ID,
     location_enabled: toBooleanOrDefault(formNode.location_enabled),
     location_required: toBooleanOrDefault(formNode.location_required),
+    title_field: cloneTitleField(formNode.title_field),
     fields: [],
   };
 
@@ -669,6 +684,138 @@ export function projectDatasetRowValues(descriptor, rowValues) {
   };
 }
 
+const toLiveChoiceDisplayValues = (field, rawValue) => {
+  if (rawValue === null || typeof rawValue === 'undefined') {
+    return [];
+  }
+
+  if (typeof rawValue !== 'object' || Array.isArray(rawValue)) {
+    const matched = Array.isArray(field?.choices)
+      ? field.choices.find((choice) => choice?.value === rawValue)
+      : null;
+    return [matched?.label ?? rawValue];
+  }
+
+  const selectionKey = field?.field_type === 'MultiChoiceField' ? 'choices' : 'choice';
+  const selected = Array.isArray(rawValue[selectionKey]) ? rawValue[selectionKey] : [];
+  const other = Array.isArray(rawValue.other) ? rawValue.other : [];
+  const labels = selected.map((entry) => {
+    const value = isRecord(entry) ? entry.value : entry;
+    const matched = Array.isArray(field?.choices)
+      ? field.choices.find((choice) => choice?.value === value)
+      : null;
+    return matched?.label ?? (isRecord(entry) ? (entry.label ?? entry.value) : entry);
+  });
+
+  other.forEach((entry) => {
+    labels.push(isRecord(entry) ? (entry.label ?? entry.value) : entry);
+  });
+
+  return labels.filter((entry) => entry !== null && typeof entry !== 'undefined');
+};
+
+const toTitleDisplayValue = (field, rawValue) => {
+  if (
+    isRecord(rawValue) &&
+    ['choice', 'choices', 'other'].some((key) =>
+      Object.prototype.hasOwnProperty.call(rawValue, key)
+    )
+  ) {
+    return toLiveChoiceDisplayValues(field, rawValue);
+  }
+
+  if (
+    field?.field_type === 'SingleChoiceField' ||
+    field?.field_type === 'MultiChoiceField' ||
+    field?.field_type === 'BooleanField'
+  ) {
+    if (!isRecord(rawValue)) {
+      return toLiveChoiceDisplayValues(field, rawValue);
+    }
+    return readStoredChoiceDisplayValues(field, rawValue, {
+      context: 'resolveDatasetRowTitle',
+    });
+  }
+
+  return rawValue;
+};
+
+const toTitlePart = (value) => {
+  if (Array.isArray(value)) {
+    const parts = value.map(toTitlePart).filter(Boolean);
+    return parts.length > 0 ? parts.join(', ') : null;
+  }
+
+  if (typeof value === 'string') {
+    return toTrimmedString(value);
+  }
+
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+
+  if (isRecord(value) && Object.prototype.hasOwnProperty.call(value, 'value')) {
+    return toTitlePart(value.value);
+  }
+
+  return null;
+};
+
+/**
+ * Resolve a derived title for one root or repeatable dataset row.
+ * Supports renderer/live values and canonical stored record values.
+ */
+export function resolveDatasetRowTitle(descriptor, rowValues) {
+  const titleField = isRecord(descriptor?.title_field) ? descriptor.title_field : null;
+  const references = Array.isArray(titleField?.elements) ? titleField.elements : [];
+  if (!titleField || titleField.enabled === false || references.length === 0) {
+    return null;
+  }
+
+  const sourceRecord = isRecord(rowValues) ? rowValues : {};
+  const source = isRecord(sourceRecord.form_values) ? sourceRecord.form_values : sourceRecord;
+  const fields = Array.isArray(descriptor?.fields) ? descriptor.fields : [];
+  const fieldByReference = new Map();
+
+  fields.forEach((field) => {
+    if (field?.title_eligible !== true) {
+      return;
+    }
+    [
+      field.field_id,
+      field.output_key,
+      field.key,
+      field.data_name,
+      ...(field.aliases ?? []),
+    ].forEach((reference) => {
+      const normalized = toTrimmedString(reference);
+      if (normalized && !fieldByReference.has(normalized)) {
+        fieldByReference.set(normalized, field);
+      }
+    });
+  });
+
+  const parts = [];
+  references.forEach((reference) => {
+    const normalizedReference = toTrimmedString(reference);
+    const field = normalizedReference ? fieldByReference.get(normalizedReference) : null;
+    if (!field) {
+      return;
+    }
+    const rawValue = readFirstAliasValue(source, field.aliases ?? []);
+    const part = toTitlePart(toTitleDisplayValue(field, rawValue));
+    if (part) {
+      parts.push(part);
+    }
+  });
+
+  return parts.length > 0 ? parts.join(', ') : null;
+}
+
 export function resolveDatasetDescriptorById(schema, datasetId) {
   return buildDatasetDescriptors(schema).find((dataset) => dataset.id === datasetId) ?? null;
 }

package/src/utilities/record-transformer.js

@@ -6,6 +6,7 @@
 import { FIELD_SPECS } from '../schema/field-specs.js';
 import { recordVersion } from './version-utils.js';
 import { buildRepeatableMetadata } from './repeatable-helpers.js';
+import { buildDatasetDescriptors, resolveDatasetRowTitle } from './dataset-descriptors.js';
 
 const hasMeaningfulValue = (value) => {
   if (value === null || value === undefined) {
@@ -178,26 +179,44 @@ export function createStructuredRecord(state, fields = null, options = {}, id =
       dataNameToFieldMap.set(field.data_name, field);
     });
   }
-  // Create mapping from key to field for title resolution
-  const keyToFieldMap = new Map();
-  if (Array.isArray(fields)) {
-    fields.forEach((field) => {
-      if (field.key) keyToFieldMap.set(field.key, field);
-    });
-  }
-
   // Build a comprehensive tree structure for nested RepeatableSections
   const elementsSource = Array.isArray(options.originalElements)
     ? options.originalElements
     : Array.isArray(fields)
-    ? fields
-    : [];
-
-  const {
-    repeatableSectionTree,
-    fieldOwnership,
-    sectionFields,
-  } = buildRepeatableMetadata(elementsSource);
+      ? fields
+      : [];
+
+  const { repeatableSectionTree, fieldOwnership, sectionFields } =
+    buildRepeatableMetadata(elementsSource);
+
+  const titleDatasetDescriptors = buildDatasetDescriptors({
+    form: {
+      elements: elementsSource,
+      title_field: options.title_field || null,
+    },
+  });
+  const rootTitleDescriptor = titleDatasetDescriptors.find(
+    (descriptor) => descriptor.kind === 'root'
+  );
+  const repeatableTitleDescriptors = new Map();
+  titleDatasetDescriptors.forEach((descriptor) => {
+    if (descriptor.kind !== 'repeatable') {
+      return;
+    }
+    [descriptor.repeatable_field_id, descriptor.repeatable_output_key].forEach((reference) => {
+      if (reference) {
+        repeatableTitleDescriptors.set(reference, descriptor);
+      }
+    });
+  });
+
+  const resolveRepeatableTitle = (repInfo, rowValues) => {
+    const descriptor =
+      repeatableTitleDescriptors.get(repInfo?.preferredKey) ||
+      repeatableTitleDescriptors.get(repInfo?.field?.key) ||
+      repeatableTitleDescriptors.get(repInfo?.field?.data_name);
+    return descriptor ? resolveDatasetRowTitle(descriptor, rowValues) : null;
+  };
 
   const hasStructuredRepeatableState =
     state &&
@@ -237,12 +256,7 @@ export function createStructuredRecord(state, fields = null, options = {}, id =
 
     // Apply output formatting if field spec exists
     let processedValue = value;
-    if (
-      field &&
-      field.type &&
-      FIELD_SPECS[field.type] &&
-      FIELD_SPECS[field.type].outputProducer
-    ) {
+    if (field && field.type && FIELD_SPECS[field.type] && FIELD_SPECS[field.type].outputProducer) {
       try {
         processedValue = FIELD_SPECS[field.type].outputProducer(field, value);
       } catch (err) {
@@ -384,6 +398,10 @@ export function createStructuredRecord(state, fields = null, options = {}, id =
           childRecord.form_values[childOutputKey] = childRepeatableArray;
         }
 
+        if (repInfo.field?.title_field) {
+          childRecord['@title'] = resolveRepeatableTitle(repInfo, instanceValues);
+        }
+
         if (hasMeaningfulRecord(childRecord)) {
           childRecords.push(childRecord);
         }
@@ -498,6 +516,13 @@ export function createStructuredRecord(state, fields = null, options = {}, id =
           }
         }
 
+        if (repInfo.field?.title_field) {
+          childRecord['@title'] = resolveRepeatableTitle(
+            repInfo,
+            i === 0 ? state.values : childRecord.form_values
+          );
+        }
+
         if (hasMeaningfulRecord(childRecord)) {
           childRecords.push(childRecord);
         }
@@ -600,70 +625,8 @@ export function createStructuredRecord(state, fields = null, options = {}, id =
   // Add top-level @title and @status
   // ==============================
   try {
-    // Compute @title from TitleField elements if provided in options
-    const titleField = options.title_field;
-    if (titleField && Array.isArray(titleField.elements)) {
-      const parts = [];
-      for (const ref of titleField.elements) {
-        let fieldDef = null;
-        // Prefer key lookup
-        if (keyToFieldMap.has(ref)) {
-          fieldDef = keyToFieldMap.get(ref);
-        } else if (dataNameToFieldMap.has(ref)) {
-          fieldDef = dataNameToFieldMap.get(ref);
-        }
-        if (!fieldDef) continue;
-        const value = state.values[fieldDef.data_name];
-        if (value == null) continue;
-        // Extract display text by field type
-        if (fieldDef.type === 'SingleChoiceField') {
-          let labels = [];
-          if (value.choice && Array.isArray(value.choice) && value.choice.length > 0) {
-            const v = value.choice[0].value;
-            const found = (fieldDef.choices || []).find((c) => c.value === v);
-            labels.push(found?.label || value.choice[0].label || v);
-          }
-          if (value.other && Array.isArray(value.other)) {
-            for (const o of value.other) {
-              if (o && (o.label || o.value)) labels.push(o.label || o.value);
-            }
-          }
-          const text = labels.filter(Boolean).join(', ');
-          if (text) parts.push(text);
-        } else if (fieldDef.type === 'MultiChoiceField') {
-          let labels = [];
-          if (value.choices && Array.isArray(value.choices)) {
-            for (const c of value.choices) {
-              const found = (fieldDef.choices || []).find((cc) => cc.value === c.value);
-              labels.push(found?.label || c.label || c.value);
-            }
-          }
-          if (value.other && Array.isArray(value.other)) {
-            for (const o of value.other) {
-              if (o && (o.label || o.value)) labels.push(o.label || o.value);
-            }
-          }
-          const text = labels.filter(Boolean).join(', ');
-          if (text) parts.push(text);
-        } else if (fieldDef.type === 'BooleanField') {
-          let label = '';
-          if (value.choice && Array.isArray(value.choice) && value.choice.length > 0) {
-            const v = value.choice[0].value;
-            const found = (fieldDef.choices || []).find((c) => c.value === v);
-            label = found?.label || value.choice[0].label || v;
-          }
-          if (label) parts.push(label);
-        } else {
-          const text = typeof value === 'object' ? null : String(value);
-          if (text && text.trim() !== '') parts.push(text);
-        }
-      }
-      const titleText = parts.join(', ');
-      if (titleText) {
-        record['@title'] = titleText;
-      } else {
-        record['@title'] = null;
-      }
+    if (options.title_field && rootTitleDescriptor) {
+      record['@title'] = resolveDatasetRowTitle(rootTitleDescriptor, state.values);
     }
   } catch (err) {
     console.warn('[form0] createStructuredRecord: failed to compute @title:', err);

package/src/utilities/structured-record.js

@@ -1,9 +1,5 @@
 import { createFormEngine } from '../engine/form-engine.js';
-import {
-  buildDatasetDescriptors,
-  buildFieldIdentityMap,
-  projectDatasetRowValues,
-} from './dataset-descriptors.js';
+import { buildDatasetDescriptors, resolveDatasetRowTitle } from './dataset-descriptors.js';
 import {
   isChoiceFieldLike,
   normalizeStoredChoiceValue,
@@ -81,10 +77,11 @@ const findFirstAliasEntry = (value, aliases) => {
   return null;
 };
 
-const buildScopeFromElements = (elements) => {
+const buildScopeFromElements = (elements, descriptorByRepeatable = new Map()) => {
   const scope = {
     valueFields: [],
     repeatables: [],
+    datasetDescriptor: null,
   };
 
   if (!Array.isArray(elements)) {
@@ -98,7 +95,8 @@ const buildScopeFromElements = (elements) => {
 
     if (CONTAINER_TYPES.has(element.type)) {
       const childScope = buildScopeFromElements(
-        Array.isArray(element.elements) ? element.elements : []
+        Array.isArray(element.elements) ? element.elements : [],
+        descriptorByRepeatable
       );
       scope.valueFields.push(...childScope.valueFields);
       scope.repeatables.push(...childScope.repeatables);
@@ -115,8 +113,15 @@ const buildScopeFromElements = (elements) => {
         aliases: toAliasList(element),
         outputKey,
         repeatableKey: trimString(element.key) ?? trimString(element.data_name) ?? outputKey,
-        childScope: buildScopeFromElements(Array.isArray(element.elements) ? element.elements : []),
+        childScope: buildScopeFromElements(
+          Array.isArray(element.elements) ? element.elements : [],
+          descriptorByRepeatable
+        ),
       });
+      scope.repeatables[scope.repeatables.length - 1].childScope.datasetDescriptor =
+        descriptorByRepeatable.get(trimString(element.key)) ||
+        descriptorByRepeatable.get(trimString(element.data_name)) ||
+        null;
       continue;
     }
 
@@ -136,86 +141,6 @@ const buildScopeFromElements = (elements) => {
   return scope;
 };
 
-const buildFieldReferenceMap = (schema) => {
-  const identityMap = buildFieldIdentityMap(schema);
-  const references = new Map();
-
-  Object.values(identityMap).forEach((field) => {
-    if (!isRecordObject(field)) {
-      return;
-    }
-
-    [field.field_id, field.output_key, field.key, field.data_name].forEach((ref) => {
-      const normalizedRef = trimString(ref);
-      if (normalizedRef && !references.has(normalizedRef)) {
-        references.set(normalizedRef, field.field_id);
-      }
-    });
-  });
-
-  return references;
-};
-
-const toTitlePart = (value) => {
-  if (Array.isArray(value)) {
-    const parts = value
-      .map((entry) => toTitlePart(entry))
-      .filter((entry) => typeof entry === 'string' && entry.length > 0);
-    return parts.length > 0 ? parts.join(', ') : null;
-  }
-
-  if (typeof value === 'number' || typeof value === 'boolean') {
-    return String(value);
-  }
-
-  if (typeof value === 'string') {
-    const normalized = value.trim();
-    return normalized.length > 0 ? normalized : null;
-  }
-
-  return null;
-};
-
-const computeStructuredRecordTitle = (schema, record) => {
-  const formNode = isRecordObject(schema?.form) ? schema.form : null;
-  const titleField = isRecordObject(formNode?.title_field) ? formNode.title_field : null;
-  const titleElements = Array.isArray(titleField?.elements) ? titleField.elements : [];
-
-  if (!titleField || titleField.enabled === false || titleElements.length === 0) {
-    return null;
-  }
-
-  const descriptors = buildDatasetDescriptors(schema);
-  const rootDescriptor =
-    descriptors.find((descriptor) => descriptor.id === ROOT_DATASET_ID) ?? descriptors[0] ?? null;
-  if (!rootDescriptor) {
-    return null;
-  }
-
-  const projected = projectDatasetRowValues(rootDescriptor, record);
-  const references = buildFieldReferenceMap(schema);
-  const parts = [];
-
-  titleElements.forEach((entry) => {
-    const normalizedEntry = trimString(entry);
-    if (!normalizedEntry) {
-      return;
-    }
-
-    const fieldId = references.get(normalizedEntry);
-    if (!fieldId) {
-      return;
-    }
-
-    const part = toTitlePart(projected.displayValues[fieldId]);
-    if (part) {
-      parts.push(part);
-    }
-  });
-
-  return parts.length > 0 ? parts.join(', ') : null;
-};
-
 const normalizeRecordScope = (record, scope) => {
   if (!isRecordObject(record)) {
     return record;
@@ -256,9 +181,43 @@ const normalizeRecordScope = (record, scope) => {
     });
   });
 
+  if (scope.datasetDescriptor) {
+    record['@title'] = resolveDatasetRowTitle(scope.datasetDescriptor, record);
+  }
+
   return record;
 };
 
+const findRepeatableElement = (elements, descriptor) => {
+  if (!Array.isArray(elements)) {
+    return null;
+  }
+
+  for (const element of elements) {
+    if (!isRecordObject(element)) {
+      continue;
+    }
+    if (
+      element.type === 'RepeatableSection' &&
+      [element.key, element.data_name].some(
+        (reference) =>
+          reference === descriptor.repeatable_field_id ||
+          reference === descriptor.repeatable_output_key
+      )
+    ) {
+      return element;
+    }
+    if (CONTAINER_TYPES.has(element.type) || element.type === 'RepeatableSection') {
+      const match = findRepeatableElement(element.elements, descriptor);
+      if (match) {
+        return match;
+      }
+    }
+  }
+
+  return null;
+};
+
 const buildSnapshotState = (formValues, scope) => {
   const rawValues = {};
   const repeatable = {};
@@ -360,14 +319,42 @@ export function normalizeStructuredRecord(schema, record, options = {}) {
   }
 
   const formNode = isRecordObject(schema?.form) ? schema.form : null;
-  const scope = buildScopeFromElements(Array.isArray(formNode?.elements) ? formNode.elements : []);
-
-  normalizeRecordScope(normalized, scope);
+  const descriptors = buildDatasetDescriptors(schema);
+  const descriptorByRepeatable = new Map();
+  descriptors.forEach((descriptor) => {
+    if (descriptor.kind !== 'repeatable') {
+      return;
+    }
+    [descriptor.repeatable_field_id, descriptor.repeatable_output_key].forEach((reference) => {
+      if (reference) {
+        descriptorByRepeatable.set(reference, descriptor);
+      }
+    });
+  });
 
-  if (formNode) {
-    normalized['@title'] = computeStructuredRecordTitle(schema, normalized);
+  const requestedDatasetId = trimString(options.datasetId) ?? ROOT_DATASET_ID;
+  const datasetDescriptor = descriptors.find((descriptor) => descriptor.id === requestedDatasetId);
+  if (!datasetDescriptor) {
+    throw new Error(`[form0] normalizeStructuredRecord: unknown dataset "${requestedDatasetId}"`);
   }
 
+  const datasetElement =
+    datasetDescriptor.kind === 'repeatable'
+      ? findRepeatableElement(formNode?.elements, datasetDescriptor)
+      : null;
+  const scopeElements =
+    datasetDescriptor.kind === 'root'
+      ? Array.isArray(formNode?.elements)
+        ? formNode.elements
+        : []
+      : Array.isArray(datasetElement?.elements)
+        ? datasetElement.elements
+        : [];
+  const scope = buildScopeFromElements(scopeElements, descriptorByRepeatable);
+  scope.datasetDescriptor = datasetDescriptor;
+
+  normalizeRecordScope(normalized, scope);
+
   return normalized;
 }