form0-core 0.6.0 → 0.8.0

package/src/engine/record-freshness.js

@@ -0,0 +1,19 @@
+import { copyRecordData } from '../utilities/record-data.js';
+
+/** Group pending field identities by complete row path; retain no values or proposal history. */
+export function createRecordFreshness(schemaRevision, changes = []) {
+  const affected = new Map();
+  for (const { instancePath, fieldName, fieldKey } of changes) {
+    if (!instancePath.length) continue;
+    const key = JSON.stringify(instancePath);
+    if (!affected.has(key))
+      affected.set(key, { instancePath: copyRecordData(instancePath), fields: [] });
+    affected.get(key).fields.push({ fieldName, fieldKey });
+  }
+  return {
+    version: 1,
+    status: affected.size ? 'pending' : 'current',
+    schemaRevision,
+    affected: [...affected.values()],
+  };
+}

package/src/engine/submission-validation.js

@@ -0,0 +1,130 @@
+/**
+ * @typedef {Object} SubmissionFinding
+ * @property {'required'|'error'|'custom'} kind
+ * @property {string} message
+ * @property {Object[]} instancePath Complete row ancestry; [] for root.
+ * @property {string} [fieldName] Absent for scope-level custom findings.
+ * @property {string} [fieldKey]
+ *
+ * @typedef {Object} SubmissionValidationSummary
+ * @property {boolean} hasErrors
+ * @property {SubmissionFinding[]} requiredFieldErrors
+ * @property {SubmissionFinding[]} generalErrors
+ * @property {SubmissionFinding[]} scopeIssues
+ * @property {SubmissionFinding[]} orderedIssues
+ */
+
+import { prepareRecordContext, visitRecordScopes } from './record-context.js';
+
+const hasText = (value) => typeof value === 'string' && value.trim().length > 0;
+const hasChoice = (entries) =>
+  Array.isArray(entries) &&
+  entries.some(
+    (entry) => entry && ((entry.value != null && entry.value !== '') || hasText(entry.label))
+  );
+const hasOther = (entries) =>
+  Array.isArray(entries) &&
+  entries.some((entry) =>
+    typeof entry === 'string'
+      ? hasText(entry)
+      : entry && (hasText(entry.label) || (entry.value != null && entry.value !== ''))
+  );
+
+/** Type-aware input emptiness shared with submission participation; zero/false are values. */
+export function isFieldValueEmpty(field, value) {
+  if (!field || value == null) return true;
+  switch (field.type) {
+    case 'TextField':
+    case 'CalculatedField':
+    case 'DateField':
+    case 'TimeField':
+    case 'TitleField':
+    case 'StatusField':
+      return typeof value === 'string' && !value.trim();
+    case 'NumericField':
+      return typeof value === 'number' ? false : typeof value === 'string' ? !value.trim() : true;
+    case 'SingleChoiceField':
+    case 'BooleanField':
+      return !hasChoice(value.choice) && !hasOther(value.other);
+    case 'MultiChoiceField':
+      return !hasChoice(value.choices) && !hasOther(value.other);
+    case 'PhotoField':
+    case 'VideoField':
+      return !Array.isArray(value) || value.length === 0;
+    case 'SignatureField':
+      return typeof value === 'string'
+        ? !value.trim()
+        : !(hasText(value?.data) || hasText(value?.url));
+    default:
+      return Array.isArray(value)
+        ? value.length === 0
+        : typeof value === 'object'
+          ? Object.keys(value).length === 0
+          : false;
+  }
+}
+
+export function validateScope(scope) {
+  const findings = [];
+  if (!scope.participating) return findings;
+  const { record, template, instancePath } = scope;
+  for (const field of template.fields) {
+    if (['Section', 'BuildingPlanSection', 'RepeatableSection', 'LabelField'].includes(field.type))
+      continue;
+    if (
+      record.visible?.[field.data_name] === false ||
+      !(template.chains.get(field.data_name) || []).every(
+        (name) => record.visible?.[name] !== false
+      )
+    )
+      continue;
+    const message = record.errors?.[field.data_name];
+    const required = record.required?.[field.data_name] ?? field.required;
+    const base = {
+      fieldName: field.data_name,
+      fieldKey: field.key || field.data_name,
+      instancePath,
+    };
+    if (message) findings.push({ ...base, kind: 'error', message });
+    else if (required && isFieldValueEmpty(field, record.values?.[field.data_name]))
+      findings.push({ ...base, kind: 'required', message: 'This field is required' });
+  }
+  return findings;
+}
+
+export function validateSubmissionWithContext(snapshot, context, customIssues = []) {
+  const orderedIssues = [];
+  const issuesByScope = new Map();
+  for (const custom of customIssues) {
+    const key = JSON.stringify(custom.instancePath || []);
+    if (!issuesByScope.has(key)) issuesByScope.set(key, []);
+    issuesByScope.get(key).push(custom);
+  }
+  visitRecordScopes(snapshot, context, (scope) => {
+    orderedIssues.push(...validateScope(scope));
+    if (scope.participating)
+      for (const custom of issuesByScope.get(JSON.stringify(scope.instancePath)) || [])
+        orderedIssues.push({ ...custom, instancePath: scope.instancePath, kind: 'custom' });
+  });
+  return summarizeSubmissionFindings(orderedIssues);
+}
+
+/** Shared ordering/classification for a complete tree or a selected editor scope. */
+export function summarizeSubmissionFindings(orderedIssues) {
+  return {
+    hasErrors: orderedIssues.length > 0,
+    requiredFieldErrors: orderedIssues.filter((issue) => issue.kind === 'required'),
+    generalErrors: orderedIssues.filter((issue) => issue.kind === 'error'),
+    scopeIssues: orderedIssues.filter((issue) => issue.kind === 'custom'),
+    orderedIssues,
+  };
+}
+
+/**
+ * Validate an already evaluated runtime record tree; never evaluates or mutates intrinsic errors.
+ * @param {{schema: Object, snapshot: Object, validationIssues?: Object[]}} options
+ * @returns {SubmissionValidationSummary} Ordered field and scope findings; no freshness assertion.
+ */
+export function validateSubmission({ schema, snapshot, validationIssues = [] }) {
+  return validateSubmissionWithContext(snapshot, prepareRecordContext(schema), validationIssues);
+}

package/src/index.js

@@ -1,6 +1,9 @@
 export { createFormEngine } from './engine/form-engine.js';
 export { WarningSystem } from './engine/warning-system.js';
-export { createStructuredRecord } from './utilities/record-transformer.js';
+export {
+  createStructuredRecord,
+  createStructuredRecordAsync,
+} from './utilities/record-transformer.js';
 export {
   normalizeStructuredRecord,
   buildFormRecordSnapshot,
@@ -86,3 +89,6 @@ export {
   applyFormMutationBatch,
 } from './authoring/form-authoring.js';
 export { INVALID } from './builtins/event/control/invalid.js';
+
+export { createRecordEvaluator } from './engine/record-evaluator.js';
+export { validateSubmission, isFieldValueEmpty } from './engine/submission-validation.js';

package/src/schema/schema-validator.js

@@ -85,6 +85,11 @@ export function validateSchemaWithContext(form, contextResolver) {
   const duplicateDataNames = new Set();
   const duplicateKeys = new Set();
   const errors = [];
+  if (
+    form.repeatable_recalculation !== undefined &&
+    !['automatic', 'confirm'].includes(form.repeatable_recalculation)
+  )
+    errors.push('form.repeatable_recalculation must be automatic or confirm');
 
   const formAIValidation = validateFormAIMetadata(form);
   if (!formAIValidation.isValid) {

package/src/security/validation.js

@@ -4,14 +4,14 @@ import {
 } from '../builtins/builtin-definitions.js';
 import { DEFAULT_SECURITY_CONFIG, SAFE_SECURITY_CONFIG, SECURITY_MODES } from './config.js';
 
+const calculationBuiltinNames = new Set(CALCULATION_BUILTIN_DEFINITIONS.map(({ name }) => name));
+const eventBuiltinNames = new Set(EVENT_BUILTIN_DEFINITIONS.map(({ name }) => name));
+
 // Helper function to validate builtin function names in expressions
 function validateBuiltinNames(expr, includeEventBuiltins = false) {
   // Read the same immutable catalog used to build the runtime helpers, without
   // importing their implementations (EVAL itself depends on this validator).
-  const definitions = includeEventBuiltins
-    ? EVENT_BUILTIN_DEFINITIONS
-    : CALCULATION_BUILTIN_DEFINITIONS;
-  const allowedBuiltins = new Set(definitions.map(({ name }) => name));
+  const allowedBuiltins = includeEventBuiltins ? eventBuiltinNames : calculationBuiltinNames;
 
   // Extract function calls from the expression
   // This regex matches function calls like FUNCTIONNAME( allowing for whitespace

package/src/utilities/calculation-dependencies.js

@@ -1,3 +1,4 @@
+import { analyzeRepeatableCollections } from './repeatable-collections.js';
 import { ContextResolver } from '../engine/context-resolver.js';
 import { flattenFields } from './field-helpers.js';
 
@@ -378,7 +379,7 @@ export function removeEvalContents(code) {
 }
 
 export function extractStaticFieldReferenceMatches(code) {
-  const cleanedCode = removeEvalContents(code);
+  const cleanedCode = removeEvalContents(analyzeRepeatableCollections(code).scalarSource);
   const fieldRegex = /\$([a-zA-Z_][a-zA-Z0-9_]*)/g;
   const matches = [];
   let match;

package/src/utilities/calculation-editor.js

@@ -1,3 +1,5 @@
+import { analyzeRepeatableCollections } from './repeatable-collections.js';
+import { createRecordEvaluator } from '../engine/record-evaluator.js';
 import { parse } from 'acorn';
 import { BUILTIN_CONTEXTS } from '../builtins/builtin-metadata.js';
 import {
@@ -363,6 +365,7 @@ function createSimulationErrorResult(runtimeError, warnings = []) {
  * @property {string | null} description
  * @property {string | null} displayStyle
  * @property {string[]} parentPath
+ * @property {boolean} [collectionOnly] Section references are valid only in collection calls.
  * @property {{
  *   level: 'accessible' | 'restricted',
  *   code: 'main_form' | 'same_repeatable_section' | 'ancestor_repeatable_context' | 'different_repeatable_section',
@@ -396,18 +399,20 @@ export function getCalculationBuiltinCatalog() {
  * @param {Object} options.schema
  * @param {string} options.fieldDataName
  * @param {boolean} [options.includeRestricted=false]
+ * @param {boolean} [options.includeCollections=false] Include collection-only section references.
  * @returns {CalculationReferenceDefinition[]}
  */
 export function getCalculationReferenceCatalog({
   schema,
   fieldDataName,
   includeRestricted = false,
+  includeCollections = false,
 }) {
   const form = normalizeCalculationFormSchema(schema);
   const resolver = new ContextResolver(form);
   const executionContext = buildCalculationExecutionContext(form, fieldDataName, resolver);
 
-  return flattenFields(form.elements)
+  const scalarReferences = flattenFields(form.elements)
     .filter((field) => field && typeof field === 'object')
     .filter((field) => field.data_name && field.data_name !== fieldDataName)
     .filter(
@@ -419,6 +424,33 @@ export function getCalculationReferenceCatalog({
     .map((field) => toCalculationReferenceDefinition(field, resolver, executionContext))
     .filter((reference) => reference !== null)
     .filter((reference) => includeRestricted || reference.access.level === 'accessible');
+  if (!includeCollections) return scalarReferences;
+  const collections = [...resolver.repeatableSectionTree.values()]
+    .map((info) => {
+      const accessible =
+        ContextResolver.isPrefix(executionContext.parentPath, info.parentPath) ||
+        ContextResolver.isPrefix(info.parentPath, executionContext.parentPath);
+      return {
+        key: info.preferredKey,
+        reference: `$${info.field.data_name}`,
+        dataName: info.field.data_name,
+        label: info.field.label,
+        type: 'RepeatableSection',
+        description: info.field.description,
+        displayStyle: null,
+        parentPath: [...info.parentPath],
+        collectionOnly: true,
+        access: {
+          level: accessible ? 'accessible' : 'restricted',
+          code: accessible ? 'same_repeatable_section' : 'different_repeatable_section',
+          message: accessible ? null : 'Collection is outside the record ancestry.',
+          suggestion:
+            'Use this reference only as the first argument of REPEATABLEVALUES or REPEATABLESUM.',
+        },
+      };
+    })
+    .filter((reference) => includeRestricted || reference.access.level === 'accessible');
+  return [...scalarReferences, ...collections];
 }
 
 /**
@@ -434,6 +466,7 @@ export function getCalculationReferenceCatalog({
  *   issues: CalculationExpressionIssue[],
  *   usedBuiltins: string[],
  *   referencedFields: string[],
+ *   collectionReferences: Array<{builtinName: string, sectionDataName: string, targetDataName: string, startIndex: number, endIndex: number}>,
  * }}
  */
 export function analyzeCalculationExpression({
@@ -651,6 +684,13 @@ export function analyzeCalculationExpression({
     );
   }
 
+  const collectionAnalysis = analyzeRepeatableCollections(
+    normalizedExpression,
+    resolver,
+    fieldDataName
+  );
+  for (const issue of collectionAnalysis.issues)
+    addIssue(issues, issueKeys, createIssue({ ...issue, severity: 'error' }));
   for (const reference of extractStaticFieldReferenceMatches(normalizedExpression)) {
     if (!referencedFieldNames.has(reference.fieldName)) {
       referencedFieldNames.add(reference.fieldName);
@@ -732,6 +772,13 @@ export function analyzeCalculationExpression({
     issues,
     usedBuiltins,
     referencedFields,
+    collectionReferences: collectionAnalysis.calls.map((call) => ({
+      builtinName: call.name,
+      sectionDataName: call.section,
+      targetDataName: call.target,
+      startIndex: call.index,
+      endIndex: call.index + call.length,
+    })),
   };
 }
 
@@ -757,6 +804,7 @@ export function analyzeCalculationExpression({
  *       fieldContext: Object | null,
  *     }>,
  *   },
+ *   runRecord: (options: {snapshot: Object, instancePath?: Object[], expression?: string}) => Promise<{result: unknown, runtimeError: string|null, warnings: Object[], evaluation?: Object}>,
  *   dispose: () => void,
  * }}
  */
@@ -774,6 +822,10 @@ export function createCalculationPreviewSession({
     return {
       run: () =>
         createSimulationErrorResult(`Field '${fieldDataName}' does not exist in the form schema.`),
+      runRecord: async () =>
+        createSimulationErrorResult(
+          `Field '${fieldDataName}' does not exist or is not a CalculatedField.`
+        ),
       dispose: () => {},
     };
   }
@@ -781,6 +833,10 @@ export function createCalculationPreviewSession({
   if (targetField.type !== 'CalculatedField') {
     return {
       run: () => createSimulationErrorResult(`Field '${fieldDataName}' is not a CalculatedField.`),
+      runRecord: async () =>
+        createSimulationErrorResult(
+          `Field '${fieldDataName}' does not exist or is not a CalculatedField.`
+        ),
       dispose: () => {},
     };
   }
@@ -852,6 +908,43 @@ export function createCalculationPreviewSession({
         );
       }
     },
+    runRecord: async ({ snapshot, instancePath = [], expression: nextExpression, ...options }) => {
+      if (disposed)
+        return createSimulationErrorResult('Calculation preview session has been disposed.');
+      if (typeof nextExpression === 'string') targetField.calculate = nextExpression;
+      const evaluator = createRecordEvaluator({
+        schema: simulationSchema,
+        security,
+        warningSystem,
+        diagnostics: { console: false },
+      });
+      const evaluation = await evaluator.evaluate(snapshot, { ...options, mode: 'refresh' });
+      if (evaluation.status !== 'evaluated')
+        return {
+          ...createSimulationErrorResult(evaluation.issues[0]?.message || 'Record preview failed.'),
+          evaluation,
+        };
+      let record = evaluation.snapshot;
+      for (const segment of instancePath)
+        record = record?.repeatable?.[segment.repeatableKey]?.[segment.index];
+      if (!record?.values || !Object.hasOwn(record.values, fieldDataName))
+        return {
+          ...createSimulationErrorResult(
+            'Preview instancePath must identify the record owning the calculated field.'
+          ),
+          evaluation,
+        };
+      const runtimeError =
+        evaluation.diagnostics.find(
+          (item) => item.fieldName === fieldDataName && item.severity === 'error'
+        )?.message || null;
+      return {
+        result: record?.values?.[fieldDataName] ?? null,
+        runtimeError,
+        warnings: sanitizeCollectedWarnings(warningSystem.getCollectedWarnings()),
+        evaluation,
+      };
+    },
     dispose: () => {
       disposed = true;
       warningSystem.clearCollectedWarnings();

package/src/utilities/form-event-editor.js

@@ -39,6 +39,7 @@ function toFormEventBuiltinDefinition(definition) {
     signature: definition.signature,
     description: definition.description,
     examples: Object.freeze([...definition.examples]),
+    ...(definition.operation ? { operation: definition.operation } : {}),
     status: getFormEventBuiltinStatus(definition.name),
   });
 }
@@ -247,6 +248,9 @@ function cloneCatalogDefinition(definition) {
   return {
     ...definition,
     examples: [...definition.examples],
+    ...(definition.operation
+      ? { operation: { ...definition.operation, effects: [...definition.operation.effects] } }
+      : {}),
   };
 }
 

package/src/utilities/record-data.js

@@ -0,0 +1,69 @@
+function createContainer(value, seen) {
+  if (seen.has(value)) throw new Error('Record data must not contain cyclic references.');
+  if (!Array.isArray(value) && ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+    throw new Error('Record data must use plain objects, arrays, dates or native media handles.');
+  return Array.isArray(value) ? [] : {};
+}
+
+/** Clone portable record data without copying immutable binary media into JS memory. */
+export function copyRecordData(value, seen = new Map()) {
+  if (typeof value === 'function' || typeof value === 'symbol')
+    throw new Error('Record data must not contain functions or symbols.');
+  if (value === null || typeof value !== 'object') return value;
+  if (value instanceof Date) return new Date(value.getTime());
+  if (typeof Blob === 'function' && value instanceof Blob) return value;
+  const result = createContainer(value, seen);
+  seen.set(value, result);
+  for (const key of Object.keys(value)) {
+    Object.defineProperty(result, key, {
+      value: copyRecordData(value[key], seen),
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+  }
+  seen.delete(value);
+  return result;
+}
+
+/** Copy privately captured results in bounded batches; never use this to capture live inputs. */
+export async function copyRecordDataCooperatively(value, checkpoint) {
+  const seen = new Map();
+  const frames = [];
+  function begin(source) {
+    if (
+      source === null ||
+      typeof source !== 'object' ||
+      source instanceof Date ||
+      (typeof Blob === 'function' && source instanceof Blob)
+    )
+      return copyRecordData(source, seen);
+    const target = createContainer(source, seen);
+    seen.set(source, target);
+    frames.push({ source, target, keys: Object.keys(source), index: 0 });
+    return target;
+  }
+  const result = begin(value);
+  let work = 0;
+  while (frames.length) {
+    const frame = frames[frames.length - 1];
+    if (frame.index === frame.keys.length) {
+      seen.delete(frame.source);
+      frames.pop();
+      continue;
+    }
+    const key = frame.keys[frame.index++];
+    Object.defineProperty(frame.target, key, {
+      value: begin(frame.source[key]),
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+    if (++work === 128) {
+      work = 0;
+      await checkpoint();
+    }
+  }
+  await checkpoint();
+  return result;
+}