form0-core 0.1.12 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "form0-core",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
@@ -8,7 +8,7 @@
   "main": "src/index.js",
   "type": "module",
   "scripts": {
-    "test": "node tests/form0-core.test.js && node tests/dataset-descriptors.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/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",
     "postinstall": "node scripts/postinstall.cjs",
     "format": "prettier --write \"**/*.{js,jsx,json,ts,tsx,md}\"",
     "format:check": "prettier --check \"**/*.{js,jsx,json,ts,tsx,md}\""

package/src/index.js

@@ -1,6 +1,10 @@
 export { createFormEngine } from './engine/form-engine.js';
 export { WarningSystem } from './engine/warning-system.js';
 export { createStructuredRecord } from './utilities/record-transformer.js';
+export {
+  normalizeStructuredRecord,
+  buildFormRecordSnapshot,
+} from './utilities/structured-record.js';
 export { validateSchema } from './schema/schema-validator.js';
 //export { validateSchema, resolveSupportingImagePath } from './schema/schema-validator.js';
 export { generateKey } from './utilities/hash.js';

package/src/utilities/dataset-descriptors.js

@@ -15,6 +15,20 @@ const toTrimmedString = (value) => {
   return trimmed.length > 0 ? trimmed : null;
 };
 
+const toFiniteNumberOrNull = (value) => {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : null;
+  }
+
+  const trimmed = toTrimmedString(value);
+  if (!trimmed) {
+    return null;
+  }
+
+  const parsed = Number(trimmed);
+  return Number.isFinite(parsed) ? parsed : null;
+};
+
 const toSchemaFormNode = (schema) => {
   if (!isRecord(schema)) {
     return null;
@@ -87,8 +101,11 @@ const QUERY_SEMANTICS_BY_FIELD_TYPE = {
     default_operator: 'contains',
     allowed_operators: [
       'contains',
+      'not_contains',
       'eq',
       'neq',
+      'in',
+      'not_in',
       'starts_with',
       'ends_with',
       'is_blank',
@@ -109,6 +126,8 @@ const QUERY_SEMANTICS_BY_FIELD_TYPE = {
       'neq',
       'gt',
       'lt',
+      'in',
+      'not_in',
       'is_blank',
       'is_not_blank',
     ],
@@ -127,6 +146,8 @@ const QUERY_SEMANTICS_BY_FIELD_TYPE = {
       'neq',
       'gt',
       'lt',
+      'in',
+      'not_in',
       'is_blank',
       'is_not_blank',
     ],
@@ -145,6 +166,8 @@ const QUERY_SEMANTICS_BY_FIELD_TYPE = {
       'neq',
       'gt',
       'lt',
+      'in',
+      'not_in',
       'is_blank',
       'is_not_blank',
     ],
@@ -202,6 +225,8 @@ const getCalculatedFieldSemantics = (field) => {
         'neq',
         'gt',
         'lt',
+        'in',
+        'not_in',
         'is_blank',
         'is_not_blank',
       ],
@@ -223,6 +248,8 @@ const getCalculatedFieldSemantics = (field) => {
         'neq',
         'gt',
         'lt',
+        'in',
+        'not_in',
         'is_blank',
         'is_not_blank',
       ],
@@ -244,6 +271,8 @@ const getCalculatedFieldSemantics = (field) => {
         'neq',
         'gt',
         'lt',
+        'in',
+        'not_in',
         'is_blank',
         'is_not_blank',
       ],
@@ -258,8 +287,11 @@ const getCalculatedFieldSemantics = (field) => {
     default_operator: 'contains',
     allowed_operators: [
       'contains',
+      'not_contains',
       'eq',
       'neq',
+      'in',
+      'not_in',
       'starts_with',
       'ends_with',
       'is_blank',
@@ -293,33 +325,179 @@ const toChoiceValueList = (field) => {
   return field.choices.filter((choice) => isRecord(choice));
 };
 
-const toSingleChoiceLabel = (field, rawValue) => {
-  const choices = toChoiceValueList(field);
-  if (choices.length === 0) {
-    return rawValue;
+const isChoicePrimitive = (value) =>
+  typeof value === 'string' ||
+  typeof value === 'number' ||
+  typeof value === 'boolean';
+
+const normalizeChoiceEntryValue = (entry) => {
+  if (isChoicePrimitive(entry)) {
+    return entry;
+  }
+
+  if (!isRecord(entry)) {
+    return undefined;
+  }
+
+  if (isChoicePrimitive(entry.value)) {
+    return entry.value;
+  }
+
+  if (isChoicePrimitive(entry.label)) {
+    return entry.label;
+  }
+
+  return undefined;
+};
+
+const normalizeChoiceEntryDisplayValue = (entry) => {
+  if (isChoicePrimitive(entry)) {
+    return entry;
+  }
+
+  if (!isRecord(entry)) {
+    return undefined;
+  }
+
+  if (isChoicePrimitive(entry.label)) {
+    return entry.label;
   }
 
-  const matched = choices.find(
-    (choice) => Object.prototype.hasOwnProperty.call(choice, 'value') && choice.value === rawValue,
+  if (isChoicePrimitive(entry.value)) {
+    return entry.value;
+  }
+
+  return undefined;
+};
+
+const normalizeChoiceEntryLabel = (field, entry) => {
+  const normalizedValue = normalizeChoiceEntryValue(entry);
+  if (typeof normalizedValue === 'undefined') {
+    return undefined;
+  }
+
+  const matched = toChoiceValueList(field).find(
+    (choice) =>
+      Object.prototype.hasOwnProperty.call(choice, 'value') &&
+      choice.value === normalizedValue,
   );
-  if (!matched) {
-    return rawValue;
+  if (matched) {
+    return toTrimmedString(matched.label) ?? normalizedValue;
   }
 
-  return toTrimmedString(matched.label) ?? rawValue;
+  if (isRecord(entry) && isChoicePrimitive(entry.label)) {
+    return entry.label;
+  }
+
+  return normalizedValue;
 };
 
-const toMultiChoiceLabels = (field, rawValue) => {
-  if (!Array.isArray(rawValue)) {
+const toSingleChoiceSelectionValues = (rawValue) => {
+  if (isRecord(rawValue)) {
+    const choiceValues = Array.isArray(rawValue.choice)
+      ? rawValue.choice
+          .map((entry) => normalizeChoiceEntryValue(entry))
+          .filter((entry) => typeof entry !== 'undefined')
+      : [];
+    const otherValues = Array.isArray(rawValue.other)
+      ? rawValue.other
+          .map((entry) => normalizeChoiceEntryValue(entry))
+          .filter((entry) => typeof entry !== 'undefined')
+      : [];
+
+    return [...choiceValues, ...otherValues];
+  }
+
+  const normalized = normalizeChoiceEntryValue(rawValue);
+  return typeof normalized === 'undefined' ? [] : [normalized];
+};
+
+const toSingleChoiceDisplayValues = (field, rawValue) => {
+  if (isRecord(rawValue)) {
+    const choiceLabels = Array.isArray(rawValue.choice)
+      ? rawValue.choice
+          .map((entry) => normalizeChoiceEntryLabel(field, entry))
+          .filter((entry) => typeof entry !== 'undefined')
+      : [];
+    const otherLabels = Array.isArray(rawValue.other)
+      ? rawValue.other
+          .map((entry) => normalizeChoiceEntryDisplayValue(entry))
+          .filter((entry) => typeof entry !== 'undefined')
+      : [];
+
+    return [...choiceLabels, ...otherLabels];
+  }
+
+  const normalized = normalizeChoiceEntryLabel(field, rawValue);
+  return typeof normalized === 'undefined' ? [] : [normalized];
+};
+
+const toMultiChoiceSelectionValues = (rawValue) => {
+  if (isRecord(rawValue)) {
+    const selectedValues = Array.isArray(rawValue.choices)
+      ? rawValue.choices
+          .map((entry) => normalizeChoiceEntryValue(entry))
+          .filter((entry) => typeof entry !== 'undefined')
+      : [];
+    const otherValues = Array.isArray(rawValue.other)
+      ? rawValue.other
+          .map((entry) => normalizeChoiceEntryValue(entry))
+          .filter((entry) => typeof entry !== 'undefined')
+      : [];
+
+    return [...selectedValues, ...otherValues];
+  }
+
+  if (Array.isArray(rawValue)) {
+    return rawValue
+      .map((entry) => normalizeChoiceEntryValue(entry))
+      .filter((entry) => typeof entry !== 'undefined');
+  }
+
+  return [];
+};
+
+const toMultiChoiceDisplayValues = (field, rawValue) => {
+  if (isRecord(rawValue)) {
+    const selectedLabels = Array.isArray(rawValue.choices)
+      ? rawValue.choices
+          .map((entry) => normalizeChoiceEntryLabel(field, entry))
+          .filter((entry) => typeof entry !== 'undefined')
+      : [];
+    const otherLabels = Array.isArray(rawValue.other)
+      ? rawValue.other
+          .map((entry) => normalizeChoiceEntryDisplayValue(entry))
+          .filter((entry) => typeof entry !== 'undefined')
+      : [];
+
+    return [...selectedLabels, ...otherLabels];
+  }
+
+  if (Array.isArray(rawValue)) {
+    return rawValue
+      .map((entry) => normalizeChoiceEntryLabel(field, entry))
+      .filter((entry) => typeof entry !== 'undefined');
+  }
+
+  return [];
+};
+
+const toSingleChoiceLabel = (field, rawValue) => {
+  const labels = toSingleChoiceDisplayValues(field, rawValue);
+  if (labels.length === 0) {
     return rawValue;
   }
 
-  const choices = toChoiceValueList(field);
-  if (choices.length === 0) {
+  return labels.length === 1 ? labels[0] : labels;
+};
+
+const toMultiChoiceLabels = (field, rawValue) => {
+  const labels = toMultiChoiceDisplayValues(field, rawValue);
+  if (labels.length === 0) {
     return rawValue;
   }
 
-  return rawValue.map((entry) => toSingleChoiceLabel(field, entry));
+  return labels;
 };
 
 const toDisplayValue = (field, rawValue) => {
@@ -497,15 +675,33 @@ const readFirstAliasValue = (value, aliases) => {
   return undefined;
 };
 
-const normalizeScalarValue = (value) => {
+const normalizeScalarValue = (field, value) => {
+  if (
+    field?.field_type === 'SingleChoiceField' ||
+    field?.field_type === 'BooleanField'
+  ) {
+    return toSingleChoiceSelectionValues(value)[0];
+  }
+
   if (Array.isArray(value)) {
     return undefined;
   }
 
+  if (field?.display_kind === 'number') {
+    const parsedNumber = toFiniteNumberOrNull(value);
+    if (parsedNumber !== null) {
+      return parsedNumber;
+    }
+  }
+
   return value;
 };
 
-const normalizeTermValues = (value) => {
+const normalizeTermValues = (field, value) => {
+  if (field?.field_type === 'MultiChoiceField') {
+    return toMultiChoiceSelectionValues(value);
+  }
+
   if (!Array.isArray(value)) {
     return [];
   }
@@ -539,7 +735,7 @@ export function projectDatasetRowValues(descriptor, rowValues) {
     displayValues[field.field_id] = toDisplayValue(field, rawValue);
 
     if (field.query_kind === 'scalar') {
-      const scalarValue = normalizeScalarValue(rawValue);
+      const scalarValue = normalizeScalarValue(field, rawValue);
       if (typeof scalarValue !== 'undefined') {
         scalarValues[field.field_id] = scalarValue;
       }
@@ -547,7 +743,7 @@ export function projectDatasetRowValues(descriptor, rowValues) {
     }
 
     if (field.query_kind === 'terms') {
-      const terms = normalizeTermValues(rawValue);
+      const terms = normalizeTermValues(field, rawValue);
       if (terms.length > 0) {
         termValues[field.field_id] = terms;
       }

package/src/utilities/structured-record.js

@@ -0,0 +1,505 @@
+import { createFormEngine } from '../engine/form-engine.js';
+import {
+  buildDatasetDescriptors,
+  buildFieldIdentityMap,
+  projectDatasetRowValues,
+} from './dataset-descriptors.js';
+
+const CONTAINER_TYPES = new Set(['Section', 'BuildingPlanSection']);
+const TIMESTAMP_KEYS = [
+  'created_at_client',
+  'updated_at_client',
+  'created_at_server',
+  'updated_at_server',
+];
+const ROOT_DATASET_ID = '__root__';
+
+const isRecordObject = (value) =>
+  Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+const cloneJson = (value) => {
+  if (typeof structuredClone === 'function') {
+    return structuredClone(value);
+  }
+  return JSON.parse(JSON.stringify(value));
+};
+
+const trimString = (value) => {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+};
+
+const toNullableString = (value) =>
+  value === null || typeof value === 'string' ? value : undefined;
+
+const toOutputKey = (field) => trimString(field?.data_name) ?? trimString(field?.key);
+
+const toDataName = (field, fallback) => trimString(field?.data_name) ?? fallback;
+
+const toAliasList = (field) => {
+  const aliases = [];
+  const outputKey = toOutputKey(field);
+  const dataName = trimString(field?.data_name);
+  const key = trimString(field?.key);
+
+  if (outputKey) {
+    aliases.push(outputKey);
+  }
+  if (dataName && !aliases.includes(dataName)) {
+    aliases.push(dataName);
+  }
+  if (key && !aliases.includes(key)) {
+    aliases.push(key);
+  }
+
+  return aliases;
+};
+
+const findFirstAliasEntry = (value, aliases) => {
+  if (!isRecordObject(value)) {
+    return null;
+  }
+
+  for (const alias of aliases) {
+    if (Object.prototype.hasOwnProperty.call(value, alias)) {
+      return {
+        key: alias,
+        value: value[alias],
+      };
+    }
+  }
+
+  return null;
+};
+
+const buildScopeFromElements = (elements) => {
+  const scope = {
+    valueFields: [],
+    repeatables: [],
+  };
+
+  if (!Array.isArray(elements)) {
+    return scope;
+  }
+
+  for (const element of elements) {
+    if (!isRecordObject(element) || typeof element.type !== 'string') {
+      continue;
+    }
+
+    if (CONTAINER_TYPES.has(element.type)) {
+      const childScope = buildScopeFromElements(
+        Array.isArray(element.elements) ? element.elements : []
+      );
+      scope.valueFields.push(...childScope.valueFields);
+      scope.repeatables.push(...childScope.repeatables);
+      continue;
+    }
+
+    if (element.type === 'RepeatableSection') {
+      const outputKey = toOutputKey(element);
+      if (!outputKey) {
+        continue;
+      }
+
+      scope.repeatables.push({
+        aliases: toAliasList(element),
+        outputKey,
+        repeatableKey: trimString(element.key) ?? trimString(element.data_name) ?? outputKey,
+        childScope: buildScopeFromElements(Array.isArray(element.elements) ? element.elements : []),
+      });
+      continue;
+    }
+
+    const outputKey = toOutputKey(element);
+    if (!outputKey) {
+      continue;
+    }
+
+    scope.valueFields.push({
+      aliases: toAliasList(element),
+      dataName: toDataName(element, outputKey),
+      outputKey,
+      field: element,
+    });
+  }
+
+  return scope;
+};
+
+const resolveChoiceLabel = (field, rawValue, fallbackLabel) => {
+  const normalizedValue = trimString(rawValue);
+  if (!normalizedValue) {
+    return fallbackLabel ?? null;
+  }
+
+  if (Array.isArray(field?.choices)) {
+    const matched = field.choices.find(
+      (choice) =>
+        isRecordObject(choice) &&
+        Object.prototype.hasOwnProperty.call(choice, 'value') &&
+        choice.value === normalizedValue
+    );
+    if (matched) {
+      return trimString(matched.label) ?? normalizedValue;
+    }
+  }
+
+  return fallbackLabel ?? normalizedValue;
+};
+
+const normalizeChoiceEntry = (field, entry) => {
+  if (!isRecordObject(entry)) {
+    return entry;
+  }
+
+  const rawValue = trimString(entry.value) ?? trimString(entry.label) ?? trimString(entry.id);
+  if (!rawValue) {
+    return { ...entry };
+  }
+
+  return {
+    ...entry,
+    value: rawValue,
+    label: resolveChoiceLabel(field, rawValue, trimString(entry.label)),
+  };
+};
+
+const normalizeChoiceList = (field, entries) => {
+  if (!Array.isArray(entries)) {
+    return entries;
+  }
+
+  return entries.map((entry) => normalizeChoiceEntry(field, entry));
+};
+
+const normalizeChoiceStructuredValue = (field, rawValue) => {
+  if (!isRecordObject(rawValue)) {
+    return rawValue;
+  }
+
+  const normalized = { ...rawValue };
+
+  if (field?.type === 'SingleChoiceField' || field?.type === 'BooleanField') {
+    if (Array.isArray(rawValue.choice_value)) {
+      normalized.choice_value = normalizeChoiceList(field, rawValue.choice_value);
+    }
+    if (Array.isArray(rawValue.choice)) {
+      normalized.choice = normalizeChoiceList(field, rawValue.choice);
+    }
+    if (Array.isArray(rawValue.other_value)) {
+      normalized.other_value = rawValue.other_value.map((entry) =>
+        isRecordObject(entry) ? { ...entry } : entry
+      );
+    }
+    if (Array.isArray(rawValue.other)) {
+      normalized.other = rawValue.other.map((entry) =>
+        isRecordObject(entry) ? { ...entry } : entry
+      );
+    }
+    return normalized;
+  }
+
+  if (field?.type === 'MultiChoiceField') {
+    if (Array.isArray(rawValue.choices_value)) {
+      normalized.choices_value = normalizeChoiceList(field, rawValue.choices_value);
+    }
+    if (Array.isArray(rawValue.choices)) {
+      normalized.choices = normalizeChoiceList(field, rawValue.choices);
+    }
+    if (Array.isArray(rawValue.other_value)) {
+      normalized.other_value = rawValue.other_value.map((entry) =>
+        isRecordObject(entry) ? { ...entry } : entry
+      );
+    }
+    if (Array.isArray(rawValue.other)) {
+      normalized.other = rawValue.other.map((entry) =>
+        isRecordObject(entry) ? { ...entry } : entry
+      );
+    }
+    return normalized;
+  }
+
+  return normalized;
+};
+
+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;
+  }
+
+  const formValues = isRecordObject(record.form_values) ? record.form_values : null;
+  if (!formValues) {
+    return record;
+  }
+
+  scope.valueFields.forEach((field) => {
+    const entry = findFirstAliasEntry(formValues, field.aliases);
+    if (!entry) {
+      return;
+    }
+
+    if (
+      field.field?.type === 'SingleChoiceField' ||
+      field.field?.type === 'BooleanField' ||
+      field.field?.type === 'MultiChoiceField'
+    ) {
+      formValues[entry.key] = normalizeChoiceStructuredValue(field.field, entry.value);
+    }
+  });
+
+  scope.repeatables.forEach((repeatable) => {
+    const entry = findFirstAliasEntry(formValues, repeatable.aliases);
+    if (!entry || !Array.isArray(entry.value)) {
+      return;
+    }
+
+    formValues[entry.key] = entry.value.map((childRecord) => {
+      if (!isRecordObject(childRecord)) {
+        return childRecord;
+      }
+
+      const normalizedChild = cloneJson(childRecord);
+      normalizeRecordScope(normalizedChild, repeatable.childScope);
+      return normalizedChild;
+    });
+  });
+
+  return record;
+};
+
+const buildSnapshotState = (formValues, scope) => {
+  const rawValues = {};
+  const repeatable = {};
+  const source = isRecordObject(formValues) ? formValues : {};
+
+  scope.valueFields.forEach((field) => {
+    const entry = findFirstAliasEntry(source, field.aliases);
+    if (!entry) {
+      return;
+    }
+
+    rawValues[field.dataName] = cloneJson(entry.value);
+  });
+
+  scope.repeatables.forEach((repeatableField) => {
+    const entry = findFirstAliasEntry(source, repeatableField.aliases);
+    if (!entry || !Array.isArray(entry.value)) {
+      return;
+    }
+
+    const instances = entry.value
+      .map((instance) => buildRepeatableInstanceSnapshot(instance, repeatableField.childScope))
+      .filter(Boolean);
+
+    if (instances.length > 0) {
+      repeatable[repeatableField.repeatableKey] = instances;
+    }
+  });
+
+  return {
+    rawValues,
+    repeatable,
+  };
+};
+
+const buildRepeatableInstanceSnapshot = (record, scope) => {
+  if (!isRecordObject(record)) {
+    return null;
+  }
+
+  const { rawValues, repeatable } = buildSnapshotState(record.form_values, scope);
+  const result = {
+    values: rawValues,
+    repeatable,
+  };
+
+  const recordId = trimString(record.id) ?? trimString(record.record_id);
+  if (recordId) {
+    result.id = recordId;
+  }
+
+  const status = toNullableString(record['@status']);
+  if (typeof status !== 'undefined') {
+    result['@status'] = status;
+  }
+
+  const title = toNullableString(record['@title']);
+  if (typeof title !== 'undefined') {
+    result['@title'] = title;
+  }
+
+  if (typeof record.draft === 'boolean') {
+    result.draft = record.draft;
+  }
+
+  TIMESTAMP_KEYS.forEach((key) => {
+    const value = toNullableString(record[key]);
+    if (typeof value !== 'undefined') {
+      result[key] = value;
+    }
+  });
+
+  return result;
+};
+
+const extractSnapshotTimestamps = (record) => ({
+  created_at_client:
+    toNullableString(record?.created_at_client) ?? toNullableString(record?.created_at) ?? null,
+  updated_at_client:
+    toNullableString(record?.updated_at_client) ?? toNullableString(record?.updated_at) ?? null,
+  created_at_server: toNullableString(record?.created_at_server) ?? null,
+  updated_at_server: toNullableString(record?.updated_at_server) ?? null,
+});
+
+export function normalizeStructuredRecord(schema, record, options = {}) {
+  const normalized = isRecordObject(record) ? cloneJson(record) : {};
+  const mode = trimString(options.mode) ?? 'derived';
+
+  if (mode !== 'derived') {
+    return normalized;
+  }
+
+  const formNode = isRecordObject(schema?.form) ? schema.form : null;
+  const scope = buildScopeFromElements(Array.isArray(formNode?.elements) ? formNode.elements : []);
+
+  normalizeRecordScope(normalized, scope);
+
+  if (formNode) {
+    normalized['@title'] = computeStructuredRecordTitle(schema, normalized);
+  }
+
+  return normalized;
+}
+
+export function buildFormRecordSnapshot(schema, record, options = {}) {
+  const normalizedRecord = normalizeStructuredRecord(schema, record, {
+    mode: 'derived',
+  });
+  const formNode = isRecordObject(schema?.form) ? schema.form : null;
+  const scope = buildScopeFromElements(Array.isArray(formNode?.elements) ? formNode.elements : []);
+  const { rawValues: extractedRawValues, repeatable } = buildSnapshotState(
+    normalizedRecord.form_values,
+    scope
+  );
+
+  const rawValues = cloneJson(extractedRawValues);
+  const statusField = isRecordObject(formNode?.status_field) ? formNode.status_field : null;
+  const statusFieldName = trimString(statusField?.data_name);
+  if (statusFieldName) {
+    const status = toNullableString(normalizedRecord['@status']);
+    if (typeof status !== 'undefined') {
+      rawValues[statusFieldName] = status;
+    }
+  }
+
+  TIMESTAMP_KEYS.forEach((key) => {
+    const value = toNullableString(normalizedRecord[key]);
+    if (typeof value !== 'undefined') {
+      rawValues[key] = value;
+    }
+  });
+
+  const mode = trimString(options.mode) ?? 'default';
+  const snapshotRawValues =
+    mode === 'editor' && formNode
+      ? (() => {
+          const engine = createFormEngine({
+            schema,
+            initialValues: rawValues,
+          });
+          engine.eval();
+          return cloneJson(engine.getState().values);
+        })()
+      : rawValues;
+
+  return {
+    raw_values: snapshotRawValues,
+    repeatable,
+    timestamps: extractSnapshotTimestamps(normalizedRecord),
+  };
+}