form0-core 0.7.0 → 0.8.0

package/src/engine/form-engine.js

@@ -17,6 +17,9 @@ import { buildCalculationDependencyPlan } from '../utilities/calculation-depende
 import { createCalculationDiagnostics } from './calculation-diagnostics.js';
 import { formatLocalDate } from '../utilities/date-utils.js';
 import { createManagedEventDispatcher } from './managed-events.js';
+import { validateInteractionMode } from './event-policy.js';
+import { copyRecordData } from '../utilities/record-data.js';
+import { areStructuredValuesEqual } from '../utilities/value-equality.js';
 
 /**
  * @typedef {Object} CalculationDiagnostic
@@ -53,6 +56,7 @@ import { createManagedEventDispatcher } from './managed-events.js';
  * @param {Object} [options.initialValues]
  * @param {Object} [options.helpers]
  * @param {Object} [options.security]
+ * @param {'edit'|'readonly'} [options.mode='edit'] View preserves supplied calculations/defaults.
  * @param {WarningSystem} [options.warningSystem]
  * @param {Array} [options.runtimeDiagnostics] Deprecated append-only compatibility adapter.
  * Use getDiagnostics() for the latest snapshot or onDiagnostics for evaluation notifications.
@@ -75,15 +79,18 @@ export function createFormEngine({
   diagnostics = {},
   onDiagnostics = null,
   eventScope = { instancePath: [] },
+  mode = 'edit',
 }) {
+  let interactionMode = validateInteractionMode(mode);
   const { schema: preparedSchema, buildingPlanMeta } = expandBuildingPlanSchema(schema);
 
   const contextResolver = new ContextResolver(preparedSchema.form);
   validateSchemaWithContext(preparedSchema.form, contextResolver);
 
   const { form } = preparedSchema;
-  const values = { ...initialValues };
+  const values = copyRecordData(initialValues);
   const allFields = flattenFields(form.elements);
+  const pendingDefaults = new Map();
 
   // Create a lookup map for choice fields
   const choiceFieldMap = new Map();
@@ -104,7 +111,11 @@ export function createFormEngine({
   for (const field of allFields) {
     if (!(field.data_name in values)) {
       // Initialize field with default value if specified
-      values[field.data_name] = getDefaultValue(field);
+      values[field.data_name] = getDefaultValue(
+        interactionMode === 'readonly' ? { ...field, default_value: null } : field
+      );
+      if (interactionMode === 'readonly')
+        pendingDefaults.set(field, copyRecordData(values[field.data_name]));
     } else if (field.type === 'SingleChoiceField' || field.type === 'BooleanField') {
       // Enrich SingleChoiceField and BooleanField values with labels from schema
       const fieldValue = values[field.data_name];
@@ -163,11 +174,16 @@ export function createFormEngine({
   const eventManager = new EventManager(form, contextResolver, sharedWarningSystem);
   eventManager.securityConfig = security; // Pass security config
   const eventHelpers = { ...eventBuiltins, ...helpers };
-  const dispatchManagedEvent = createManagedEventDispatcher(eventManager, eventScope);
+  const getMode = () => interactionMode;
+  const dispatchManagedEvent = createManagedEventDispatcher(eventManager, eventScope, getMode);
 
   // Initialize event code if present
   if (form.events && form.events.code) {
-    const eventContext = buildEventContext(values, eventHelpers, {});
+    const eventContext = buildEventContext(
+      interactionMode === 'readonly' ? copyRecordData(values) : values,
+      eventHelpers,
+      {}
+    );
     eventManager.initializeEventCode(form.events.code, eventContext);
   }
 
@@ -187,17 +203,18 @@ export function createFormEngine({
   function evalForm() {
     const frame = calculationDiagnostics.begin();
     try {
-      evaluateCalculatedFields(
-        form,
-        values,
-        allHelpers,
-        security,
-        contextResolver,
-        sharedWarningSystem,
-        runtimeDiagnostics,
-        calculationPlan,
-        calculationDiagnostics
-      );
+      if (interactionMode === 'edit')
+        evaluateCalculatedFields(
+          form,
+          values,
+          allHelpers,
+          security,
+          contextResolver,
+          sharedWarningSystem,
+          runtimeDiagnostics,
+          calculationPlan,
+          calculationDiagnostics
+        );
       evaluateRequirement(form, values, required, conditionContext);
       evaluateVisibility(form, values, visible, conditionContext);
       evaluateReadOnly(form, values, read_only, conditionContext);
@@ -211,19 +228,35 @@ export function createFormEngine({
 
   function trigger(eventType, fieldKey, metadata = {}) {
     // Update event context with current values for event execution
-    const eventContext = buildEventContext(values, eventHelpers, {
-      eventType,
-      fieldKey,
-      ...metadata,
-    });
+    const eventContext = buildEventContext(
+      interactionMode === 'readonly' ? copyRecordData(values) : values,
+      eventHelpers,
+      {
+        eventType,
+        fieldKey,
+        ...metadata,
+      }
+    );
     eventManager.eventContext = eventContext; // Update the event context
-    return eventManager.trigger(eventType, fieldKey, metadata);
+    return eventManager.trigger(eventType, fieldKey, metadata, interactionMode);
   }
 
   function getState() {
     return { values, errors, visible, required, read_only };
   }
 
+  /** Host-owned mode changes do not replay events, restore a record or evaluate implicitly. */
+  function setMode(nextMode) {
+    interactionMode = validateInteractionMode(nextMode);
+    if (interactionMode === 'edit') {
+      for (const [field, placeholder] of pendingDefaults) {
+        if (areStructuredValuesEqual(values[field.data_name], placeholder))
+          values[field.data_name] = copyRecordData(getDefaultValue(field));
+      }
+      pendingDefaults.clear();
+    }
+  }
+
   /**
    * Dispatch synchronously within this engine's construction scope. No operations are applied.
    * @param {string} eventType Registered event name.
@@ -238,6 +271,8 @@ export function createFormEngine({
 
   return {
     eval: evalForm,
+    getMode,
+    setMode,
     trigger,
     triggerDetailed,
     getState,

package/src/engine/managed-events.js

@@ -1,6 +1,7 @@
 import { getEventInfo, isValidEventType } from './event-registry.js';
 import { closeEventOperationScope, createEventOperationScope } from './event-operation-scope.js';
 import { getEventFieldReferences } from './event-field-references.js';
+import { eventOperationIssue, reportEventOperationIssue } from './event-policy.js';
 
 // Portable defensive copies also work in runtimes without structuredClone (including Hermes).
 function copy(value, seen = new Map()) {
@@ -35,7 +36,7 @@ const managedFieldCaches = new WeakMap();
 const managedRepeatableCaches = new WeakMap();
 
 /** Internal adapter; the public synchronous API is engine.triggerDetailed(). */
-export function createManagedEventDispatcher(manager, constructionScope) {
+export function createManagedEventDispatcher(manager, constructionScope, getMode = () => 'edit') {
   const instancePath = copy(constructionScope?.instancePath);
   const scopeId = constructionScope?.scopeId;
   if (scopeId !== undefined && (typeof scopeId !== 'string' || !scopeId.trim()))
@@ -86,6 +87,7 @@ export function createManagedEventDispatcher(manager, constructionScope) {
   if (!managedReferenceCaches.has(manager)) managedReferenceCaches.set(manager, new WeakMap());
   const referenceCache = managedReferenceCaches.get(manager);
   return function dispatch(eventType, fieldKey, metadata = {}) {
+    const mode = getMode();
     const result = { operations: [], validationIssues: [], issues: [] };
     const issue = (code, message) =>
       result.issues.push({
@@ -136,13 +138,13 @@ export function createManagedEventDispatcher(manager, constructionScope) {
         timestamp: Date.now(),
         instancePath: copy(instancePath),
         scopeId,
+        mode,
       };
     } catch {
       issue('invalid_request', 'Event metadata must contain portable data.');
       return result;
     }
-    const validation = eventType === 'validate-record' || eventType === 'validate-repeatable';
-    const closing = /^(cancel|unload)-/.test(eventType);
+    const registrations = [];
     const eventMap = manager.listeners.get(eventType);
     const listeners = [...(eventMap?.get(fieldKey) || []), ...(eventMap?.get('*') || [])];
     for (const callback of listeners) {
@@ -212,26 +214,31 @@ export function createManagedEventDispatcher(manager, constructionScope) {
         collected = closeEventOperationScope(scope);
       }
       try {
-        if (returned?.type === 'UI_OPERATION' && !collected.includes(returned))
+        if (
+          typeof returned?.type === 'string' &&
+          returned.type.endsWith('_OPERATION') &&
+          !collected.includes(returned)
+        )
           collected.push(copy(returned));
       } catch {
         issue('invalid_operation', 'The returned event operation must contain portable data.');
       }
       for (const operation of collected) {
-        if (operation?.type === 'EVENT_OPERATION') continue;
-        if (operation?.operation === 'INVALID') {
-          if (!validation)
-            issue('invalid_context', 'INVALID() is only available during managed validation.');
-          else
-            result.validationIssues.push({
-              message: operation.params.message,
-              instancePath: copy(instancePath),
-            });
-        } else if (validation || closing) {
-          issue(
-            'operation_not_allowed',
-            'Validation and close handlers cannot perform value or UI operations.'
-          );
+        const rejected = eventOperationIssue(operation, mode, eventType);
+        if (rejected) {
+          issue(rejected.code, rejected.message);
+          if (
+            rejected.code === 'readonly_operation_not_allowed' ||
+            rejected.code === 'invalid_operation'
+          )
+            reportEventOperationIssue(manager.warningSystem, rejected, eventType);
+        } else if (operation.type === 'EVENT_OPERATION') {
+          registrations.push(operation);
+        } else if (operation.operation === 'INVALID') {
+          result.validationIssues.push({
+            message: operation.params.message,
+            instancePath: copy(instancePath),
+          });
         } else if (operation?.type === 'FIELD_OPERATION' && operation.operation === 'SETVALUE') {
           const field = fields.get(operation.params?.fieldDataName);
           if (!field || !same(field.parentPath))
@@ -257,6 +264,7 @@ export function createManagedEventDispatcher(manager, constructionScope) {
     }
     // A failed managed dispatch is not a partially applicable operation batch.
     if (result.issues.length) result.operations = [];
+    else manager.processEventOperations(registrations);
     return copy(result);
   };
 }

package/src/engine/record-context.js

@@ -77,10 +77,15 @@ export function prepareRecordContext(inputSchema, warningSystem = null) {
 }
 
 export function visitRecordScopes(snapshot, context, visit) {
-  function walk(record, path, instancePath, ancestors, participating) {
+  for (const scope of iterateRecordScopes(snapshot, context)) visit(scope);
+}
+
+/** Same traversal for synchronous validation and budgeted private-tree preparation. */
+export function* iterateRecordScopes(snapshot, context) {
+  function* walk(record, path, instancePath, ancestors, participating) {
     const template = context.templates.get(JSON.stringify(path));
     const scope = { record, template, instancePath, ancestors, participating };
-    visit(scope);
+    yield scope;
     for (const field of template.fields) {
       if (field.type !== 'RepeatableSection') continue;
       const info = context.resolver.repeatableSectionTree.get(field.data_name);
@@ -88,7 +93,9 @@ export function visitRecordScopes(snapshot, context, visit) {
       if (!Array.isArray(rows))
         throw new Error(`RepeatableSection '${field.data_name}' must contain an array of rows.`);
       const identities = new Set();
-      rows.forEach((row, index) => {
+      for (let index = 0; index < rows.length; index++) {
+        if (!(index in rows)) continue;
+        const row = rows[index];
         if (!row || typeof row !== 'object' || Array.isArray(row))
           throw new Error('Repeatable rows must be record objects.');
         const id = row.id ?? row.record_id;
@@ -112,15 +119,15 @@ export function visitRecordScopes(snapshot, context, visit) {
           (template.chains.get(field.data_name) || []).every(
             (name) => record.visible?.[name] !== false
           );
-        walk(
+        yield* walk(
           row,
           info.currentPath,
           [...instancePath, segment],
           [...ancestors, scope],
           participating && visible
         );
-      });
+      }
     }
   }
-  walk(snapshot, [], [], [], true);
+  yield* walk(snapshot, [], [], [], true);
 }