@fogpipe/forma-core 0.6.0

package/src/engine/visibility.ts

@@ -0,0 +1,228 @@
+/**
+ * Visibility Engine
+ *
+ * Determines which fields should be visible based on form data
+ * and Forma visibility rules.
+ */
+
+import { evaluateBoolean } from "../feel/index.js";
+import type {
+  Forma,
+  FieldDefinition,
+  EvaluationContext,
+  VisibilityResult,
+} from "../types.js";
+import { calculate } from "./calculate.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface VisibilityOptions {
+  /** Pre-calculated computed values (avoids recalculation) */
+  computed?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Main Function
+// ============================================================================
+
+/**
+ * Determine visibility for all fields in a form
+ *
+ * Returns a map of field paths to boolean visibility states.
+ * Fields without visibleWhen expressions are always visible.
+ *
+ * @param data - Current form data
+ * @param spec - Form specification
+ * @param options - Optional pre-calculated computed values
+ * @returns Map of field paths to visibility states
+ *
+ * @example
+ * const visibility = getVisibility(
+ *   { age: 21, hasLicense: true },
+ *   forma
+ * );
+ * // => { age: true, hasLicense: true, vehicleType: true, ... }
+ */
+export function getVisibility(
+  data: Record<string, unknown>,
+  spec: Forma,
+  options: VisibilityOptions = {}
+): VisibilityResult {
+  // Calculate computed values if not provided
+  const computed = options.computed ?? calculate(data, spec);
+
+  // Build base evaluation context
+  const baseContext: EvaluationContext = {
+    data,
+    computed,
+    referenceData: spec.referenceData,
+  };
+
+  const result: VisibilityResult = {};
+
+  // Process all fields in field order
+  for (const fieldPath of spec.fieldOrder) {
+    const fieldDef = spec.fields[fieldPath];
+    if (fieldDef) {
+      evaluateFieldVisibility(fieldPath, fieldDef, data, baseContext, result);
+    }
+  }
+
+  return result;
+}
+
+// ============================================================================
+// Field Evaluation
+// ============================================================================
+
+/**
+ * Evaluate visibility for a single field and its nested fields
+ */
+function evaluateFieldVisibility(
+  path: string,
+  fieldDef: FieldDefinition,
+  data: Record<string, unknown>,
+  context: EvaluationContext,
+  result: VisibilityResult
+): void {
+  // Evaluate the field's own visibility
+  if (fieldDef.visibleWhen) {
+    result[path] = evaluateBoolean(fieldDef.visibleWhen, context);
+  } else {
+    result[path] = true; // No condition = always visible
+  }
+
+  // If not visible, children are implicitly not visible
+  if (!result[path]) {
+    return;
+  }
+
+  // Handle array fields with item visibility
+  if (fieldDef.itemFields) {
+    const arrayData = data[path];
+    if (Array.isArray(arrayData)) {
+      evaluateArrayItemVisibility(path, fieldDef, arrayData, context, result);
+    }
+  }
+}
+
+/**
+ * Evaluate visibility for array item fields
+ *
+ * For each item in the array, evaluates the visibility of each
+ * item field using the $item context.
+ */
+function evaluateArrayItemVisibility(
+  arrayPath: string,
+  fieldDef: FieldDefinition,
+  arrayData: unknown[],
+  baseContext: EvaluationContext,
+  result: VisibilityResult
+): void {
+  if (!fieldDef.itemFields) return;
+
+  for (let i = 0; i < arrayData.length; i++) {
+    const item = arrayData[i] as Record<string, unknown>;
+
+    // Create item-specific context
+    const itemContext: EvaluationContext = {
+      ...baseContext,
+      item,
+      itemIndex: i,
+    };
+
+    // Evaluate each item field's visibility
+    for (const [fieldName, itemFieldDef] of Object.entries(fieldDef.itemFields)) {
+      const itemFieldPath = `${arrayPath}[${i}].${fieldName}`;
+
+      if (itemFieldDef.visibleWhen) {
+        result[itemFieldPath] = evaluateBoolean(itemFieldDef.visibleWhen, itemContext);
+      } else {
+        result[itemFieldPath] = true;
+      }
+    }
+  }
+}
+
+// ============================================================================
+// Individual Field Visibility
+// ============================================================================
+
+/**
+ * Check if a single field is visible
+ *
+ * Useful for checking visibility of one field without computing all.
+ *
+ * @param fieldPath - Field path to check
+ * @param data - Current form data
+ * @param spec - Form specification
+ * @param options - Optional pre-calculated computed values
+ * @returns True if the field is visible
+ */
+export function isFieldVisible(
+  fieldPath: string,
+  data: Record<string, unknown>,
+  spec: Forma,
+  options: VisibilityOptions = {}
+): boolean {
+  const fieldDef = spec.fields[fieldPath];
+  if (!fieldDef) {
+    return true; // Unknown fields are visible by default
+  }
+
+  if (!fieldDef.visibleWhen) {
+    return true; // No condition = always visible
+  }
+
+  const computed = options.computed ?? calculate(data, spec);
+  const context: EvaluationContext = {
+    data,
+    computed,
+    referenceData: spec.referenceData,
+  };
+
+  return evaluateBoolean(fieldDef.visibleWhen, context);
+}
+
+// ============================================================================
+// Page Visibility
+// ============================================================================
+
+/**
+ * Determine which pages are visible in a wizard form
+ *
+ * @param data - Current form data
+ * @param spec - Form specification with pages
+ * @param options - Optional pre-calculated computed values
+ * @returns Map of page IDs to visibility states
+ */
+export function getPageVisibility(
+  data: Record<string, unknown>,
+  spec: Forma,
+  options: VisibilityOptions = {}
+): Record<string, boolean> {
+  if (!spec.pages) {
+    return {};
+  }
+
+  const computed = options.computed ?? calculate(data, spec);
+  const context: EvaluationContext = {
+    data,
+    computed,
+    referenceData: spec.referenceData,
+  };
+
+  const result: Record<string, boolean> = {};
+
+  for (const page of spec.pages) {
+    if (page.visibleWhen) {
+      result[page.id] = evaluateBoolean(page.visibleWhen, context);
+    } else {
+      result[page.id] = true;
+    }
+  }
+
+  return result;
+}

package/src/feel/index.ts

@@ -0,0 +1,299 @@
+/**
+ * FEEL Expression Evaluator
+ *
+ * Wraps the feelin library to provide FEEL expression evaluation
+ * with Forma context conventions.
+ *
+ * Context variable conventions:
+ * - `fieldName` - Direct field value access
+ * - `computed.name` - Computed value access
+ * - `ref.path` - Reference data lookup (external lookup tables)
+ * - `item.fieldName` - Array item field access (within array context)
+ * - `itemIndex` - Current array item index (0-based)
+ * - `value` - Current field value (in validation expressions)
+ */
+
+import { evaluate as feelinEvaluate } from "feelin";
+import type { EvaluationContext, FEELExpression } from "../types.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface EvaluateResult<T = unknown> {
+  success: true;
+  value: T;
+}
+
+export interface EvaluateError {
+  success: false;
+  error: string;
+  expression: string;
+}
+
+export type EvaluationOutcome<T = unknown> = EvaluateResult<T> | EvaluateError;
+
+// ============================================================================
+// Context Building
+// ============================================================================
+
+/**
+ * Build the FEEL evaluation context from our EvaluationContext
+ *
+ * Maps our context conventions to feelin context format:
+ * - Form data fields are spread directly
+ * - computed becomes an object (accessed as computed.fieldName)
+ * - ref becomes an object for reference data (accessed as ref.path.to.data)
+ * - item becomes an object for array context (accessed as item.fieldName)
+ * - itemIndex is a number for array context
+ * - value is the current field value
+ */
+function buildFeelContext(ctx: EvaluationContext): Record<string, unknown> {
+  const feelContext: Record<string, unknown> = {
+    // Spread form data directly so fields are accessible by name
+    ...ctx.data,
+  };
+
+  // Add computed values under 'computed' (accessed as computed.fieldName)
+  if (ctx.computed) {
+    feelContext["computed"] = ctx.computed;
+  }
+
+  // Add reference data under 'ref' (accessed as ref.path.to.data)
+  if (ctx.referenceData) {
+    feelContext["ref"] = ctx.referenceData;
+  }
+
+  // Add array item context (accessed as item.fieldName)
+  if (ctx.item !== undefined) {
+    feelContext["item"] = ctx.item;
+  }
+
+  // Add array index
+  if (ctx.itemIndex !== undefined) {
+    feelContext["itemIndex"] = ctx.itemIndex;
+  }
+
+  // Add current field value for validation expressions
+  if (ctx.value !== undefined) {
+    feelContext["value"] = ctx.value;
+  }
+
+  return feelContext;
+}
+
+// ============================================================================
+// Expression Evaluation
+// ============================================================================
+
+/**
+ * Evaluate a FEEL expression and return the result
+ *
+ * @param expression - FEEL expression string
+ * @param context - Evaluation context with form data, computed values, etc.
+ * @returns Evaluation outcome with success/value or error
+ *
+ * @example
+ * // Simple field comparison
+ * evaluate("age >= 18", { data: { age: 21 } })
+ * // => { success: true, value: true }
+ *
+ * @example
+ * // Computed value reference
+ * evaluate("computed.bmi > 30", { data: {}, computed: { bmi: 32.5 } })
+ * // => { success: true, value: true }
+ *
+ * @example
+ * // Array item context
+ * evaluate("item.frequency = \"daily\"", { data: {}, item: { frequency: "daily" } })
+ * // => { success: true, value: true }
+ */
+export function evaluate<T = unknown>(
+  expression: FEELExpression,
+  context: EvaluationContext
+): EvaluationOutcome<T> {
+  try {
+    const feelContext = buildFeelContext(context);
+    const result = feelinEvaluate(expression, feelContext);
+    return {
+      success: true,
+      value: result as T,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+      expression,
+    };
+  }
+}
+
+/**
+ * Evaluate a FEEL expression expecting a boolean result
+ *
+ * Used for visibility, required, and enabled conditions.
+ * Returns false on error or non-boolean result for safety.
+ *
+ * @param expression - FEEL expression that should return boolean
+ * @param context - Evaluation context
+ * @returns Boolean result (false on error)
+ */
+export function evaluateBoolean(
+  expression: FEELExpression,
+  context: EvaluationContext
+): boolean {
+  const result = evaluate<boolean>(expression, context);
+
+  if (!result.success) {
+    console.warn(
+      `FEEL expression error: ${result.error}\nExpression: ${result.expression}`
+    );
+    return false;
+  }
+
+  // FEEL uses three-valued logic where comparisons with null return null.
+  // For form visibility/required/enabled conditions, we treat null as false.
+  if (result.value === null || result.value === undefined) {
+    return false;
+  }
+
+  if (typeof result.value !== "boolean") {
+    console.warn(
+      `FEEL expression did not return boolean: ${expression}\nGot: ${typeof result.value}`
+    );
+    return false;
+  }
+
+  return result.value;
+}
+
+/**
+ * Evaluate a FEEL expression expecting a numeric result
+ *
+ * Used for computed values that return numbers.
+ *
+ * @param expression - FEEL expression that should return number
+ * @param context - Evaluation context
+ * @returns Numeric result or null on error
+ */
+export function evaluateNumber(
+  expression: FEELExpression,
+  context: EvaluationContext
+): number | null {
+  const result = evaluate<number>(expression, context);
+
+  if (!result.success) {
+    console.warn(
+      `FEEL expression error: ${result.error}\nExpression: ${result.expression}`
+    );
+    return null;
+  }
+
+  if (typeof result.value !== "number") {
+    console.warn(
+      `FEEL expression did not return number: ${expression}\nGot: ${typeof result.value}`
+    );
+    return null;
+  }
+
+  return result.value;
+}
+
+/**
+ * Evaluate a FEEL expression expecting a string result
+ *
+ * @param expression - FEEL expression that should return string
+ * @param context - Evaluation context
+ * @returns String result or null on error
+ */
+export function evaluateString(
+  expression: FEELExpression,
+  context: EvaluationContext
+): string | null {
+  const result = evaluate<string>(expression, context);
+
+  if (!result.success) {
+    console.warn(
+      `FEEL expression error: ${result.error}\nExpression: ${result.expression}`
+    );
+    return null;
+  }
+
+  if (typeof result.value !== "string") {
+    console.warn(
+      `FEEL expression did not return string: ${expression}\nGot: ${typeof result.value}`
+    );
+    return null;
+  }
+
+  return result.value;
+}
+
+// ============================================================================
+// Batch Evaluation
+// ============================================================================
+
+/**
+ * Evaluate multiple FEEL expressions at once
+ *
+ * Useful for evaluating all visibility conditions in a form.
+ *
+ * @param expressions - Map of field names to FEEL expressions
+ * @param context - Evaluation context
+ * @returns Map of field names to boolean results
+ */
+export function evaluateBooleanBatch(
+  expressions: Record<string, FEELExpression>,
+  context: EvaluationContext
+): Record<string, boolean> {
+  const results: Record<string, boolean> = {};
+
+  for (const [key, expression] of Object.entries(expressions)) {
+    results[key] = evaluateBoolean(expression, context);
+  }
+
+  return results;
+}
+
+// ============================================================================
+// Expression Validation
+// ============================================================================
+
+/**
+ * Check if a FEEL expression is syntactically valid
+ *
+ * @param expression - FEEL expression to validate
+ * @returns True if the expression can be parsed
+ */
+export function isValidExpression(expression: FEELExpression): boolean {
+  try {
+    // Try to evaluate with empty context - we just want to check parsing
+    feelinEvaluate(expression, {});
+    return true;
+  } catch {
+    // Expression failed to parse or evaluate
+    return false;
+  }
+}
+
+/**
+ * Validate a FEEL expression and return any parsing errors
+ *
+ * @param expression - FEEL expression to validate
+ * @returns Null if valid, error message if invalid
+ */
+export function validateExpression(expression: FEELExpression): string | null {
+  try {
+    // Evaluate with minimal context to catch parse errors
+    feelinEvaluate(expression, {});
+    return null;
+  } catch (error) {
+    // Only return actual parsing errors, not runtime errors
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("parse") || message.includes("syntax")) {
+      return message;
+    }
+    // Runtime errors (missing variables, etc.) are OK for validation
+    return null;
+  }
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @fogpipe/forma-core
+ *
+ * Core runtime for Forma dynamic forms.
+ * Provides types, FEEL expression evaluation, and form state engines.
+ */
+
+// Types
+export * from "./types.js";
+
+// FEEL expression evaluation
+export * from "./feel/index.js";
+
+// Form state engines
+export * from "./engine/index.js";