form0-core 0.3.1 → 0.4.1

package/src/engine/events.js

@@ -1,7 +1,14 @@
 import { runExpression } from './evaluator.js';
-import { __consumeEventOperations } from '../builtins/registry.js';
+import { eventBuiltins } from '../builtins/registry.js';
 import { ContextResolver } from './context-resolver.js';
 import { WarningSystem } from './warning-system.js';
+import { createEventSourceRegistry } from './event-source.js';
+import {
+  bindEventBuiltins,
+  closeEventOperationScope,
+  createEventOperationScope,
+  runInEventOperationScope,
+} from './event-operation-scope.js';
 
 // Global registry to track logged event handlers (development only)
 const _loggedHandlers = new Set();
@@ -19,6 +26,7 @@ export class EventManager {
     this.contextResolver = contextResolver || (schema ? new ContextResolver(schema) : null);
     this.warningSystem = warningSystem || new WarningSystem();
     this.schema = schema;
+    this.callbackSources = createEventSourceRegistry();
   }
 
   /**
@@ -29,7 +37,7 @@ export class EventManager {
   initializeEventCode(eventCode, context) {
     this.eventContext = context;
     try {
-      // Execute the event code to register listeners (recompile each time)
+      // Execute initialization once; retain authored callback source for scoped dispatch.
       this.executeEventCode(eventCode, context);
     } catch (error) {
       console.warn('[form0] Event code initialization failed:', error.message);
@@ -42,13 +50,79 @@ export class EventManager {
    * @param {Object} context - The execution context
    */
   executeEventCode(code, context) {
-    // Execute the code to register event listeners (same security as calculated fields)
-    // ON() and OFF() are now available as regular event builtins
-    runExpression(code, context, this.securityConfig, true, this.schema);
+    const executionContext = {
+      type: 'event',
+      eventType: 'initialization',
+      fieldName: null,
+    };
+    const scope = this.createOperationScope(executionContext, 'form.events.code');
+    const scopedContext = bindEventBuiltins(context, eventBuiltins, scope);
+
+    try {
+      // Execute the code to register event listeners (same security as calculated fields).
+      const prepared = this.callbackSources.prepare(code, scopedContext);
+      const result = runInEventOperationScope(scope, () =>
+        runExpression(prepared.code, prepared.context, this.securityConfig, true, this.schema, {
+          sourceExpression: code,
+        })
+      );
+      this.reportAsyncHandlerResult(result, executionContext, 'form.events.code');
+    } finally {
+      this.processEventOperations(closeEventOperationScope(scope));
+    }
+  }
+
+  createOperationScope(executionContext, handlerName) {
+    return createEventOperationScope((operationName) => {
+      this.emitHandlerWarning(
+        'late_event_operation_discarded',
+        executionContext,
+        handlerName,
+        operationName
+      );
+    });
+  }
+
+  emitHandlerWarning(reason, executionContext, handlerName, operationName = null) {
+    const eventName = executionContext.eventType;
+    const messages = {
+      async_handler_unsupported: `Event handler '${handlerName}' for event '${eventName}' returned a Promise or thenable.`,
+      late_event_operation_discarded: `Event handler '${handlerName}' for event '${eventName}' attempted ${operationName || 'an event operation'} after its synchronous scope closed. The operation was discarded.`,
+      async_handler_rejected: `Event handler '${handlerName}' for event '${eventName}' rejected after its synchronous scope closed.`,
+    };
+
+    this.warningSystem.emitWarning({
+      type: 'EVENT_HANDLER_WARNING',
+      reason,
+      severity: reason === 'async_handler_rejected' ? 'error' : 'warning',
+      message: messages[reason],
+      suggestion:
+        'Keep event handlers synchronous and create every event operation before the handler returns.',
+      executionContext: { ...executionContext },
+      fieldContext: {
+        handlerName,
+        ...(operationName ? { operationName } : {}),
+      },
+    });
+  }
+
+  reportAsyncHandlerResult(result, executionContext, handlerName) {
+    if ((typeof result !== 'object' || result === null) && typeof result !== 'function') return;
+
+    let then;
+    try {
+      then = result.then;
+    } catch {
+      this.emitHandlerWarning('async_handler_rejected', executionContext, handlerName);
+      return;
+    }
 
-    // Process any ON/OFF operations that were collected during initialization
-    const initOperations = __consumeEventOperations();
-    this.processEventOperations(initOperations);
+    if (typeof then !== 'function') return;
+
+    this.emitHandlerWarning('async_handler_unsupported', executionContext, handlerName);
+    Promise.resolve(result).catch(() => {
+      this.emitHandlerWarning('async_handler_rejected', executionContext, handlerName);
+    });
   }
 
   /**
@@ -175,7 +249,7 @@ export class EventManager {
    * @param {Object} event - The event object
    * @returns {*} The result of the event handler
    */
-  executeHandlerWithContext(callback, event) {
+  executeHandlerWithContext(callback, event, scope) {
     // Create execution context for this event
     const executionContext = {
       type: 'event',
@@ -184,7 +258,7 @@ export class EventManager {
     };
 
     // Get the callback code for field reference analysis
-    const callbackCode = callback.toString();
+    const callbackCode = this.callbackSources.getSource(callback);
 
     // Build scoped context if context resolver is available
     let contextWithEvent;
@@ -203,10 +277,16 @@ export class EventManager {
       };
     }
 
+    contextWithEvent = bindEventBuiltins(contextWithEvent, eventBuiltins, scope);
+
     // Execute the callback function with the scoped context
     // This ensures EVAL() and other builtins have access to field values
     const functionCall = `(${callbackCode})(event)`;
-    return runExpression(functionCall, contextWithEvent, this.securityConfig, true, this.schema);
+    return runInEventOperationScope(scope, () =>
+      runExpression(functionCall, contextWithEvent, this.securityConfig, true, this.schema, {
+        evaluateAsExpression: true,
+      })
+    );
   }
 
   /**
@@ -408,13 +488,19 @@ export class EventManager {
     const wildcardListeners = eventMap.get('*') || [];
 
     [...fieldListeners, ...wildcardListeners].forEach((callback) => {
+      const handlerName = callback.name || '<anonymous>';
+      const scope = this.createOperationScope(executionContext, handlerName);
+      let result;
+      let collectedOps = [];
       try {
         // Execute the callback with current form context
         // This ensures EVAL() and other builtins have access to field values
-        const result = this.executeHandlerWithContext(callback, event);
-
-        // Consume any collected event operations
-        const collectedOps = __consumeEventOperations();
+        result = this.executeHandlerWithContext(callback, event, scope);
+      } catch (error) {
+        // Simple error message for now
+        console.warn(`[form0] Event listener failed: ${error.message}`);
+      } finally {
+        collectedOps = closeEventOperationScope(scope);
         const runtimeOps = collectedOps.filter(
           (operation) => operation?.type !== 'EVENT_OPERATION'
         );
@@ -425,16 +511,16 @@ export class EventManager {
 
         // EVENT_OPERATION processing is initialization-only. ON/OFF calls inside a handler neither
         // mutate the listener registry nor leak internal registration descriptors to the host.
+      }
 
+      try {
+        this.reportAsyncHandlerResult(result, executionContext, handlerName);
         // For backward compatibility, still handle returned operations
-        if (result && result.type === 'UI_OPERATION') {
+        if (result && result.type === 'UI_OPERATION' && !collectedOps.includes(result)) {
           operations.push(result);
         }
       } catch (error) {
-        // Simple error message for now
         console.warn(`[form0] Event listener failed: ${error.message}`);
-        // Make sure to consume operations even if callback fails
-        __consumeEventOperations();
       }
     });
 

package/src/engine/form-engine.js

@@ -13,6 +13,35 @@ import { ContextResolver } from './context-resolver.js';
 import { WarningSystem } from './warning-system.js';
 import { expandBuildingPlanSchema } from '../schema/building-plan-expander.js';
 import { buildCalculationDependencyPlan } from '../utilities/calculation-dependencies.js';
+import { createCalculationDiagnostics } from './calculation-diagnostics.js';
+import { formatLocalDate } from '../utilities/date-utils.js';
+
+/**
+ * @typedef {Object} CalculationDiagnostic
+ * @property {string} code Stable diagnostic identifier.
+ * @property {'warning'|'error'} severity
+ * @property {string} message
+ * @property {string} fieldName Calculated field's data_name.
+ * @property {'dependency'|'scope'|'validation'|'syntax'|'runtime'} phase
+ * @property {string|null} suggestion
+ * @property {Object} context JSON-safe metadata; no expression source, values or stack.
+ */
+
+/**
+ * Create a form engine. Calculations collect diagnostics independently of validation.
+ * @param {Object} options
+ * @param {Object} options.schema
+ * @param {Object} [options.initialValues]
+ * @param {Object} [options.helpers]
+ * @param {Object} [options.security]
+ * @param {WarningSystem} [options.warningSystem]
+ * @param {Array} [options.runtimeDiagnostics] Deprecated append-only compatibility adapter.
+ * Use getDiagnostics() for the latest snapshot or onDiagnostics for evaluation notifications.
+ * @param {{console?: boolean}} [options.diagnostics] Omit console to preserve legacy reporting.
+ * @param {(snapshot: CalculationDiagnostic[]) => (void|Promise<void>)} [options.onDiagnostics]
+ * Called once per completed evaluation, including empty/identical snapshots. Failures are isolated.
+ * @returns {Object} Engine with getDiagnostics(): defensive copy of latest evaluation (initially []).
+ */
 
 export function createFormEngine({
   schema,
@@ -21,6 +50,8 @@ export function createFormEngine({
   security = DEFAULT_SECURITY_CONFIG,
   warningSystem = null,
   runtimeDiagnostics = null,
+  diagnostics = {},
+  onDiagnostics = null,
 }) {
   const { schema: preparedSchema, buildingPlanMeta } = expandBuildingPlanSchema(schema);
 
@@ -97,6 +128,12 @@ export function createFormEngine({
   const contextResolver = new ContextResolver(form);
   const calculationPlan = buildCalculationDependencyPlan(form, contextResolver);
   const sharedWarningSystem = warningSystem || new WarningSystem();
+  const calculationDiagnostics = createCalculationDiagnostics(
+    diagnostics,
+    onDiagnostics,
+    contextResolver,
+    sharedWarningSystem
+  );
 
   // Initialize event system with context resolution
   const eventManager = new EventManager(form, contextResolver, sharedWarningSystem);
@@ -123,20 +160,28 @@ export function createFormEngine({
   }
 
   function evalForm() {
-    evaluateCalculatedFields(
-      form,
-      values,
-      allHelpers,
-      security,
-      contextResolver,
-      sharedWarningSystem,
-      runtimeDiagnostics,
-      calculationPlan
-    );
-    evaluateRequirement(form, values, required);
-    evaluateVisibility(form, values, visible);
-    evaluateReadOnly(form, values, read_only);
-    validateFields(form, values, errors);
+    const frame = calculationDiagnostics.begin();
+    try {
+      evaluateCalculatedFields(
+        form,
+        values,
+        allHelpers,
+        security,
+        contextResolver,
+        sharedWarningSystem,
+        runtimeDiagnostics,
+        calculationPlan,
+        calculationDiagnostics
+      );
+      evaluateRequirement(form, values, required);
+      evaluateVisibility(form, values, visible);
+      evaluateReadOnly(form, values, read_only);
+      validateFields(form, values, errors);
+    } catch (error) {
+      calculationDiagnostics.abort(frame);
+      throw error;
+    }
+    calculationDiagnostics.complete(frame);
   }
 
   function trigger(eventType, fieldKey, metadata = {}) {
@@ -158,6 +203,7 @@ export function createFormEngine({
     eval: evalForm,
     trigger,
     getState,
+    getDiagnostics: calculationDiagnostics.getSnapshot,
     getWarningSystem: () => sharedWarningSystem,
     getContextResolver: () => contextResolver,
     getBuildingPlanMeta: () => buildingPlanMeta,
@@ -222,8 +268,7 @@ function getDefaultValueLegacy(field) {
 
     case 'DateField':
       if (field.default_value === 'now') {
-        const today = new Date();
-        return today.toISOString().split('T')[0]; // YYYY-MM-DD format
+        return formatLocalDate(); // YYYY-MM-DD, local calendar day
       }
       return null;
 

package/src/engine/warning-system.js

@@ -118,7 +118,7 @@ export class WarningSystem {
    * Emit warning to all registered handlers
    * @param {Object} warning - Warning object with structured information
    */
-  emitWarning(warning) {
+  emitWarning(warning, options = {}) {
     // Throttle warnings to prevent spam
     if (this.shouldThrottleWarning(warning)) {
       return;
@@ -136,12 +136,12 @@ export class WarningSystem {
     }
 
     // Console logging for development
-    if (this.enableConsoleWarnings) {
+    if (options.console ?? this.enableConsoleWarnings) {
       this.logWarningToConsole(warning);
     }
 
     // Custom handlers (for "reform" and other integrations)
-    this.notifyCustomHandlers(warning);
+    this.notifyCustomHandlers(warning, options);
   }
 
   /**
@@ -194,12 +194,14 @@ export class WarningSystem {
    * Notify all custom warning handlers
    * @param {Object} warning - Warning object
    */
-  notifyCustomHandlers(warning) {
+  notifyCustomHandlers(warning, options = {}) {
     for (const handler of this.warningHandlers) {
       try {
         handler(warning);
       } catch (err) {
-        console.error('[form0] Warning handler failed:', err);
+        if (options.console ?? this.enableConsoleWarnings) {
+          console.error('[form0] Warning handler failed:', err);
+        }
         // Don't remove the handler automatically - let the user decide
       }
     }

package/src/schema/field-specs.js

@@ -6,6 +6,7 @@ import {
   validateFormLinkRecordConditions,
 } from './form-link-validators.js';
 import { BUILDING_PLAN_BLUEPRINT } from './building-plan-blueprint.js';
+import { formatLocalDate } from '../utilities/date-utils.js';
 const AI_ATTRIBUTE_DEFINITION = {
   type: 'object',
   required: false,
@@ -725,8 +726,7 @@ export const FIELD_SPECS = {
     },
     defaultProducer: (field) => {
       if (field.default_value === 'now') {
-        const today = new Date();
-        return today.toISOString().split('T')[0]; // YYYY-MM-DD format
+        return formatLocalDate(); // YYYY-MM-DD, local calendar day
       }
       return null;
     },

package/src/security/validation.js

@@ -1,15 +1,17 @@
-import { calculationBuiltins, eventBuiltins } from '../builtins/registry.js';
+import {
+  CALCULATION_BUILTIN_DEFINITIONS,
+  EVENT_BUILTIN_DEFINITIONS,
+} from '../builtins/builtin-definitions.js';
 import { DEFAULT_SECURITY_CONFIG, SAFE_SECURITY_CONFIG, SECURITY_MODES } from './config.js';
 
 // Helper function to validate builtin function names in expressions
 function validateBuiltinNames(expr, includeEventBuiltins = false) {
-  // Always use fresh builtin sets (no caching) to support dynamic builtin registration
-  const validCalculationBuiltinsSet = new Set(Object.keys(calculationBuiltins));
-  const validEventBuiltinsSet = new Set(Object.keys(eventBuiltins));
-
-  const allowedBuiltins = includeEventBuiltins
-    ? validEventBuiltinsSet
-    : validCalculationBuiltinsSet;
+  // 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));
 
   // Extract function calls from the expression
   // This regex matches function calls like FUNCTIONNAME( allowing for whitespace

package/src/utilities/calculation-editor.js

@@ -1,3 +1,4 @@
+import { parse } from 'acorn';
 import { BUILTIN_CONTEXTS } from '../builtins/builtin-metadata.js';
 import {
   BUILTIN_DEFINITION_BY_NAME,
@@ -143,6 +144,38 @@ function isFinalFunctionCall(code, call) {
   return index === code.length;
 }
 
+function hasTopLevelReturnStatement(code) {
+  let program;
+  try {
+    program = parse(code, {
+      ecmaVersion: 'latest',
+      allowReturnOutsideFunction: true,
+    });
+  } catch {
+    return false;
+  }
+
+  const visit = (node) => {
+    if (!node || typeof node !== 'object') return false;
+    if (node.type === 'ReturnStatement') return true;
+    if (
+      node.type === 'FunctionDeclaration' ||
+      node.type === 'FunctionExpression' ||
+      node.type === 'ArrowFunctionExpression'
+    ) {
+      return false;
+    }
+
+    return Object.entries(node).some(([key, value]) => {
+      if (key === 'start' || key === 'end' || key === 'loc') return false;
+      if (Array.isArray(value)) return value.some(visit);
+      return visit(value);
+    });
+  };
+
+  return program.body.some(visit);
+}
+
 function cloneCatalogDefinition(definition) {
   return {
     ...definition,
@@ -582,14 +615,19 @@ export function analyzeCalculationExpression({
     );
   }
 
-  if (isMultilineCalculationExpression(normalizedExpression) && setResultCalls.length === 0) {
+  if (
+    isMultilineCalculationExpression(normalizedExpression) &&
+    setResultCalls.length === 0 &&
+    !hasTopLevelReturnStatement(normalizedExpression)
+  ) {
     addIssue(
       issues,
       issueKeys,
       createIssue({
         code: 'noncanonical_multiline_result',
         severity: 'warning',
-        message: 'Multiline calculations should finish with exactly one SETRESULT() call.',
+        message:
+          'Multiline calculations should finish with exactly one SETRESULT() call or an explicit return statement.',
         index: 0,
         length: 1,
       })
@@ -754,13 +792,12 @@ export function createCalculationPreviewSession({
     enableConsoleWarnings: false,
     throttleMs: 0,
   });
-  const runtimeDiagnostics = [];
   const engine = createFormEngine({
     schema: simulationSchema,
     initialValues: {},
     security,
     warningSystem,
-    runtimeDiagnostics,
+    diagnostics: { console: false },
   });
 
   engine.eval();
@@ -777,7 +814,6 @@ export function createCalculationPreviewSession({
       }
 
       warningSystem.clearCollectedWarnings();
-      runtimeDiagnostics.length = 0;
 
       if (typeof nextExpression === 'string' && nextExpression !== currentExpression) {
         targetField.calculate = nextExpression;
@@ -790,6 +826,7 @@ export function createCalculationPreviewSession({
       try {
         engine.eval();
 
+        const runtimeDiagnostics = engine.getDiagnostics();
         const simulatedResult = engineState.values[fieldDataName];
         const runtimeError =
           runtimeDiagnostics.find(
@@ -818,7 +855,6 @@ export function createCalculationPreviewSession({
     dispose: () => {
       disposed = true;
       warningSystem.clearCollectedWarnings();
-      runtimeDiagnostics.length = 0;
       clearRecord(engineState.values);
     },
   };

package/src/utilities/date-utils.js

@@ -0,0 +1,72 @@
+// Calendar-date helpers for DateField values, which use the YYYY-MM-DD format.
+// Dates are handled as UTC calendar days so that arithmetic never shifts across DST changes.
+
+const ISO_DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const MIN_CALENDAR_YEAR = 1;
+const MAX_CALENDAR_YEAR = 9999;
+
+const pad = (value, length = 2) => String(value).padStart(length, '0');
+
+/**
+ * Format a Date as YYYY-MM-DD using the local calendar day.
+ *
+ * @param {Date} [date]
+ * @returns {string}
+ */
+export function formatLocalDate(date = new Date()) {
+  return `${pad(date.getFullYear(), 4)}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+/**
+ * Parse a YYYY-MM-DD string into a day number (days since 1970-01-01).
+ *
+ * @param {string} value
+ * @returns {number | null} null when the value is not a valid calendar date
+ */
+export function parseIsoDate(value) {
+  if (typeof value !== 'string') return null;
+  const match = ISO_DATE_PATTERN.exec(value);
+  if (!match) return null;
+
+  const [year, month, day] = match.slice(1).map(Number);
+  if (year < MIN_CALENDAR_YEAR || year > MAX_CALENDAR_YEAR) return null;
+
+  const date = new Date(0);
+  date.setUTCFullYear(year, month - 1, day);
+  if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1) return null;
+  if (date.getUTCDate() !== day) return null;
+
+  return date.getTime() / MS_PER_DAY;
+}
+
+/**
+ * Format a day number (days since 1970-01-01) as YYYY-MM-DD.
+ *
+ * @param {number} dayNumber
+ * @returns {string}
+ */
+export function formatIsoDate(dayNumber) {
+  const date = new Date(dayNumber * MS_PER_DAY);
+  const year = date.getUTCFullYear();
+  if (
+    !Number.isInteger(dayNumber) ||
+    Number.isNaN(date.getTime()) ||
+    year < MIN_CALENDAR_YEAR ||
+    year > MAX_CALENDAR_YEAR
+  ) {
+    throw new Error(
+      'Date arithmetic result is outside the supported date range 0001-01-01 to 9999-12-31'
+    );
+  }
+
+  return `${pad(year, 4)}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}`;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isBlankDateArgument(value) {
+  return value === null || value === undefined || value === '';
+}

package/src/builtins/docs/choice/choicelabel.mdx

@@ -1,110 +0,0 @@
----
-title: "CHOICELABEL Builtin"
-description: "Retrieve the selected choice field label with type preservation"
-category: "choice"
-tags: ["choice", "label", "display"]
----
-
-# CHOICELABEL Function
-
-The `CHOICELABEL` builtin retrieves the currently selected choice field label, preserving the original data type. If the label is a number, it preserves the number type; otherwise, it returns a string.
-
-## Syntax
-
-```javascript
-CHOICELABEL(choiceField)
-```
-
-## Parameters
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `choiceField` | `Object` | The choice field object with choice and other arrays |
-
-## Return Value
-
-Returns the selected choice label with preserved type, or `null` if no selection is made.
-
-## Examples
-
-### Basic Usage
-
-```javascript
-// Get the selected city label
-CHOICELABEL($city)
-```
-
-### Display Logic
-
-```javascript
-// Use in display expressions
-"You selected: " + CHOICELABEL($city)
-```
-
-### Conditional Display
-
-```javascript
-// Show different content based on label
-IF(CHOICELABEL($membership) === "Premium", "Premium benefits apply", "Standard benefits")
-```
-
-### Form Feedback
-
-```javascript
-// Provide user feedback
-"Your choice: " + CHOICELABEL($preference)
-```
-
-## Type Preservation
-
-The function preserves the original data type of the choice label:
-
-```javascript
-// If choice label is "42" (string), returns 42 (number)
-// If choice label is "Premium" (string), returns "Premium" (string)
-// If choice label is 5 (number), returns 5 (number)
-```
-
-
-
-## Common Use Cases
-
-- **User feedback**: Display the human-readable label of selected choices
-- **Conditional display**: Show different content based on selected labels
-- **Form summaries**: Include readable choice labels in form summaries
-- **Reporting**: Use labels in reports and analytics
-
-## Best Practices
-
-1. **User-friendly display**: Use labels for user-facing content instead of values
-2. **Handle null values**: Always check for null when no selection is made
-3. **Internationalization**: Consider that labels might be translated
-
-## Related Functions
-
-- [`CHOICEVALUE`](./choicevalue.mdx) - Get the selected choice value
-- [`HASOTHER`](./hasother.mdx) - Check if other option is selected
-- [`OTHER`](./other.mdx) - Get the other option value
-
-## Examples by Use Case
-
-### User Confirmation
-
-```javascript
-// Confirm user selection
-"You have selected: " + CHOICELABEL($plan)
-```
-
-### Conditional Messaging
-
-```javascript
-// Show different messages based on selection
-IF(CHOICELABEL($support) === "Priority Support", "Priority support activated", "Standard support")
-```
-
-### Form Summary
-
-```javascript
-// Create form summary
-"Location: " + CHOICELABEL($location) + ", Plan: " + CHOICELABEL($plan)
-```