form0-core 0.8.1 → 0.9.0

package/README.md

@@ -87,6 +87,30 @@ Schema event callbacks retain their authored source, so ordinary functions and a
 runs once. Local initialization variables are not captured. Callbacks supplied by host helpers still
 require executable `toString()` output; unavailable source produces an event warning.
 
+## Updating values
+
+Use `engine.setValue(dataName, value)` or atomic `engine.setValues(updates)`. Nonempty batches
+evaluate once and return the current engine state; setters never dispatch events automatically.
+
+```js
+engine.setValues({ name: 'Grace' });
+```
+
+Choice input uses string IDs: SingleChoice/Boolean accept a string or `{ choice, other }`, while
+MultiChoice accepts an array of strings or `{ choices, other }`. Labels and metadata in explicit
+objects are preserved; missing labels come from the schema. Null/undefined clears a choice.
+Unknown IDs remain invalid selections, not Other values. Schema defaults and submitted
+`choice_value`/`choices_value` and `other_value` formats do not change.
+
+Malformed calls, unknown/unowned names, calculated/display/container targets and writes in record
+readonly mode throw `TypeError` before applying any part of a batch. Ordinary inputs marked
+`read_only` can still be updated by programmatic code. Initialization accepts shorthand and retains
+malformed loaded drafts for validation. Existing direct state mutation remains compatible.
+
+Adapters can use pure `normalizeFieldValue(field, value)` before their own coordinated evaluation.
+See [value updates and normalization](https://docs.form0.dev/core/engine/value-updates) for scope,
+loading, event operations and the deliberate removal of input aliases and choice-ID coercion.
+
 ## Managed events and custom validation
 
 Use synchronous `engine.triggerDetailed(eventType, fieldDataName, metadata)` to receive defensive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "form0-core",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
@@ -12,7 +12,7 @@
     "SECURITY.md"
   ],
   "scripts": {
-    "test": "node tests/form0-core.test.js && node tests/conditions.test.js && node tests/condition-scope.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/builtin-import-isolation.test.js && node tests/builtin-catalog-examples.test.js && node tests/date-builtins.test.js && node tests/calculation-expression-utils.test.js && node tests/calculation-editor.test.js && node tests/form-event-editor.test.js && node tests/form-authoring.test.js && node tests/calculation-dependency-engine.test.js && node tests/calculation-diagnostics.characterization.test.js && node tests/calculation-diagnostics.test.js && node tests/calculation-missing-result.test.js && node tests/evaluator-reentry.test.js && node tests/expression-compilation.test.js && node tests/event-compatibility.characterization.test.js && node tests/event-hermes.test.js && node tests/event-async-isolation.test.js && node tests/managed-events.test.js && node tests/security-test.js && node tests/record-evaluator.test.js && node tests/complex-record-evaluator.test.js && node tests/record-scope.test.js && node tests/consumer-compatibility.test.js",
+    "test": "node tests/form0-core.test.js && node tests/conditions.test.js && node tests/condition-scope.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/builtin-import-isolation.test.js && node tests/builtin-catalog-examples.test.js && node tests/date-builtins.test.js && node tests/calculation-expression-utils.test.js && node tests/calculation-editor.test.js && node tests/form-event-editor.test.js && node tests/form-authoring.test.js && node tests/calculation-dependency-engine.test.js && node tests/calculation-diagnostics.characterization.test.js && node tests/calculation-diagnostics.test.js && node tests/calculation-missing-result.test.js && node tests/evaluator-reentry.test.js && node tests/expression-compilation.test.js && node tests/event-compatibility.characterization.test.js && node tests/event-hermes.test.js && node tests/event-async-isolation.test.js && node tests/managed-events.test.js && node tests/security-test.js && node tests/record-evaluator.test.js && node tests/complex-record-evaluator.test.js && node tests/record-scope.test.js && node tests/consumer-compatibility.test.js && node tests/field-value-registry.test.js && node tests/value-updates.test.js",
     "format": "prettier --write \"src/**/*.{js,jsx}\" \"tests/**/*.{js,jsx}\" \"scripts/**/*.{js,mjs}\" package.json README.md EVENT_CONTRACT.md SECURITY.md SUPPORT.md CONTRIBUTING.md eslint.config.js .github/workflows/ci.yml .github/workflows/publish.yml",
     "format:check": "prettier --check \"src/**/*.{js,jsx}\" \"tests/**/*.{js,jsx}\" \"scripts/**/*.{js,mjs}\" package.json README.md EVENT_CONTRACT.md SECURITY.md SUPPORT.md CONTRIBUTING.md eslint.config.js .github/workflows/ci.yml .github/workflows/publish.yml",
     "lint:check": "eslint src tests",

package/src/engine/events.js

@@ -547,6 +547,7 @@ export class EventManager {
 
         // Validate operations against context restrictions before adding them
         const validOps = this.validateOperations(runtimeOps, executionContext);
+        if (validOps.length !== runtimeOps.length) rejectedBatch = true;
         operations.push(...validOps);
 
         // Listener updates are committed after the entire permitted dispatch, never sent to hosts.
@@ -565,7 +566,11 @@ export class EventManager {
             rejectedBatch = true;
             reportEventOperationIssue(this.warningSystem, rejected, eventType);
           } else if (result.type === 'EVENT_OPERATION') registrations.push(result);
-          else operations.push(...this.validateOperations([result], executionContext));
+          else {
+            const validOps = this.validateOperations([result], executionContext);
+            if (!validOps.length) rejectedBatch = true;
+            operations.push(...validOps);
+          }
         }
       } catch (error) {
         console.warn(`[form0] Event listener failed: ${error.message}`);

package/src/engine/form-engine.js

@@ -20,6 +20,10 @@ 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';
+import {
+  normalizeLoadedFieldValue,
+  prepareValueUpdates,
+} from '../utilities/field-value-normalization.js';
 
 /**
  * @typedef {Object} CalculationDiagnostic
@@ -92,22 +96,6 @@ export function createFormEngine({
   const allFields = flattenFields(form.elements);
   const pendingDefaults = new Map();
 
-  // Create a lookup map for choice fields
-  const choiceFieldMap = new Map();
-  for (const field of allFields) {
-    if (
-      field.type === 'SingleChoiceField' ||
-      field.type === 'MultiChoiceField' ||
-      field.type === 'BooleanField'
-    ) {
-      const valueToLabelMap = new Map();
-      field.choices.forEach((choice) => {
-        valueToLabelMap.set(choice.value, choice.label);
-      });
-      choiceFieldMap.set(field.data_name, valueToLabelMap);
-    }
-  }
-
   for (const field of allFields) {
     if (!(field.data_name in values)) {
       // Initialize field with default value if specified
@@ -116,42 +104,11 @@ export function createFormEngine({
       );
       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];
-      if (fieldValue && typeof fieldValue === 'object' && Array.isArray(fieldValue.choice)) {
-        const labelMap = choiceFieldMap.get(field.data_name);
-        fieldValue.choice = fieldValue.choice.map((choice) => {
-          if (choice && choice.value && !choice.label) {
-            // Auto-populate label from schema
-            const label = labelMap.get(choice.value);
-            return {
-              ...choice,
-              label: label || choice.value, // fallback to value if label not found
-            };
-          }
-          return choice;
-        });
-      }
-    } else if (field.type === 'MultiChoiceField') {
-      // Enrich MultiChoiceField values with labels from schema
-      const fieldValue = values[field.data_name];
-      if (fieldValue && typeof fieldValue === 'object' && Array.isArray(fieldValue.choices)) {
-        const labelMap = choiceFieldMap.get(field.data_name);
-        fieldValue.choices = fieldValue.choices.map((choice) => {
-          if (choice && choice.value && !choice.label) {
-            // Auto-populate label from schema
-            const label = labelMap.get(choice.value);
-            return {
-              ...choice,
-              label: label || choice.value, // fallback to value if label not found
-            };
-          }
-          return choice;
-        });
-      }
+    } else {
+      values[field.data_name] = normalizeLoadedFieldValue(field, values[field.data_name]);
     }
   }
+
   const errors = {};
   const visible = {};
   const required = {};
@@ -245,6 +202,24 @@ export function createFormEngine({
     return { values, errors, visible, required, read_only };
   }
 
+  /** Apply one input update and evaluate once; event dispatch stays host-owned. */
+  function setValue(dataName, value) {
+    if (typeof dataName !== 'string' || !dataName)
+      throw new TypeError('A value-update field must be a nonempty data_name string.');
+    return engine.setValues({ [dataName]: value });
+  }
+
+  /** Preflight/copy every update before committing the complete batch. */
+  function setValues(updates) {
+    const prepared = prepareValueUpdates(writableScopeFields, updates, interactionMode);
+    if (Object.keys(prepared).length) {
+      Object.defineProperties(values, Object.getOwnPropertyDescriptors(prepared));
+      // Bindings can decorate evaluation with their existing record-scope coordinator.
+      engine.eval();
+    }
+    return getState();
+  }
+
   /** Host-owned mode changes do not replay events, restore a record or evaluate implicitly. */
   function setMode(nextMode) {
     interactionMode = validateInteractionMode(nextMode);
@@ -269,8 +244,25 @@ export function createFormEngine({
     return dispatchManagedEvent(eventType, fieldKey, metadata);
   }
 
-  return {
+  const ownershipPath = eventScope.instancePath.map((part) => part.repeatableKey);
+  const writableScopeFields = new Map(
+    [...contextResolver.elementOwnership]
+      .filter(
+        ([, entry]) =>
+          entry.parentPath.length === ownershipPath.length &&
+          entry.parentPath.every((key, index) => key === ownershipPath[index])
+      )
+      .map(([name, entry]) => [name, entry.field])
+  );
+  if (!ownershipPath.length) {
+    if (form.status_field?.enabled)
+      writableScopeFields.set(form.status_field.data_name, form.status_field);
+    if (form.title_field) writableScopeFields.set(form.title_field.data_name, form.title_field);
+  }
+  const engine = {
     eval: evalForm,
+    setValue,
+    setValues,
     getMode,
     setMode,
     trigger,
@@ -282,6 +274,7 @@ export function createFormEngine({
     getBuildingPlanMeta: () => buildingPlanMeta,
     getPreparedSchema: () => preparedSchema,
   };
+  return engine;
 }
 
 export function getDefaultValue(field) {

package/src/engine/managed-events.js

@@ -2,6 +2,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';
+import { assertWritableField } from '../utilities/field-value-normalization.js';
 
 // Portable defensive copies also work in runtimes without structuredClone (including Hermes).
 function copy(value, seen = new Map()) {
@@ -248,9 +249,10 @@ export function createManagedEventDispatcher(manager, constructionScope, getMode
             );
           else {
             try {
+              assertWritableField(field.field);
               result.operations.push(copy(operation));
-            } catch {
-              issue('invalid_operation', 'Event operations must contain portable data.');
+            } catch (error) {
+              issue('invalid_operation', error.message);
             }
           }
         } else {

package/src/index.js

@@ -1,4 +1,5 @@
 export { createFormEngine } from './engine/form-engine.js';
+export { normalizeFieldValue } from './utilities/field-value-normalization.js';
 export { WarningSystem } from './engine/warning-system.js';
 export {
   createStructuredRecord,

package/src/utilities/field-value-normalization.js

@@ -0,0 +1,106 @@
+import { copyRecordData } from './record-data.js';
+
+const CHOICE_TYPES = new Set(['SingleChoiceField', 'BooleanField', 'MultiChoiceField']);
+const PROTECTED_TYPES = new Set([
+  'CalculatedField',
+  'LabelField',
+  'TitleField',
+  'Section',
+  'RepeatableSection',
+  'BuildingPlanSection',
+]);
+const isObject = (value) =>
+  value !== null &&
+  typeof value === 'object' &&
+  !Array.isArray(value) &&
+  [Object.prototype, null].includes(Object.getPrototypeOf(value));
+
+const invalid = (field, message) =>
+  new TypeError(`Invalid value update for "${field?.data_name || 'unknown field'}": ${message}`);
+
+export function assertWritableField(field) {
+  if (!field || PROTECTED_TYPES.has(field.type))
+    throw invalid(field, 'the target must be an input field.');
+}
+
+/**
+ * Copy a writable field's live value, expanding string choice shorthand without changing schema
+ * or stored-record formats. Invalid selections remain data; malformed calls throw TypeError.
+ * @param {Object} field Schema field definition.
+ * @param {*} value Live value or type-appropriate choice shorthand.
+ * @returns {*} Defensive live value; immutable native media handles are retained.
+ */
+export function normalizeFieldValue(field, value) {
+  assertWritableField(field);
+  try {
+    if (!CHOICE_TYPES.has(field.type)) return copyRecordData(value);
+    const multiple = field.type === 'MultiChoiceField';
+    const key = multiple ? 'choices' : 'choice';
+    const opposite = multiple ? 'choice' : 'choices';
+    let live;
+    if (value == null) return { [key]: [], other: [] };
+    if (!multiple && typeof value === 'string') {
+      live = { choice: [{ value }], other: [] };
+    } else if (multiple && Array.isArray(value)) {
+      if (value.some((entry) => typeof entry !== 'string'))
+        throw invalid(field, 'multiple-choice shorthand must contain string IDs.');
+      live = { choices: value.map((entry) => ({ value: entry })), other: [] };
+    } else {
+      if (!isObject(value) || Object.hasOwn(value, opposite) || !Array.isArray(value[key]))
+        throw invalid(
+          field,
+          `use ${multiple ? 'an array of string IDs' : 'a string ID'} or a { ${key}, other } object.`
+        );
+      live = copyRecordData(value);
+      if (!Object.hasOwn(live, 'other')) live.other = [];
+    }
+    if (!Array.isArray(live.other)) throw invalid(field, 'other must be an array.');
+    for (const entry of live[key]) {
+      if (!isObject(entry) || typeof entry.value !== 'string')
+        throw invalid(field, `${key} entries must be objects with a string value.`);
+      if (entry.label == null) {
+        const defined = field.choices?.find((choice) => choice.value === entry.value);
+        entry.label = defined?.label ?? entry.value;
+      }
+    }
+    for (const entry of live.other)
+      if (!isObject(entry) || !Object.hasOwn(entry, 'label'))
+        throw invalid(field, 'other entries must be objects with a label.');
+    return live;
+  } catch (error) {
+    if (error instanceof TypeError) throw error;
+    throw invalid(field, error.message);
+  }
+}
+
+/** Loaded drafts remain inspectable even if their existing field structures are invalid. */
+export function normalizeLoadedFieldValue(field, value) {
+  if (CHOICE_TYPES.has(field.type)) {
+    try {
+      return normalizeFieldValue(field, value);
+    } catch (error) {
+      if (!(error instanceof TypeError)) throw error;
+    }
+  }
+  return copyRecordData(value);
+}
+
+/** Preflight the entire batch before any caller changes live or optimistic state. */
+export function prepareValueUpdates(fields, updates, mode = 'edit') {
+  if (!isObject(updates)) throw new TypeError('Value updates must be a plain object.');
+  const entries = Object.entries(updates);
+  if (entries.length && mode === 'readonly')
+    throw new TypeError('Cannot set values while the record is readonly.');
+  const prepared = {};
+  for (const [name, value] of entries) {
+    const field = fields.get(name);
+    if (!field) throw new TypeError(`Unknown or unowned value-update field "${name}".`);
+    Object.defineProperty(prepared, name, {
+      value: normalizeFieldValue(field, value),
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    });
+  }
+  return prepared;
+}