@fogpipe/forma-core 0.6.0 → 0.7.0

package/src/index.ts

@@ -5,8 +5,42 @@
  * Provides types, FEEL expression evaluation, and form state engines.
  */
 
-// Types
-export * from "./types.js";
+// Types (explicit type-only exports)
+export type {
+  // FEEL
+  FEELExpression,
+  // JSON Schema
+  JSONSchema,
+  JSONSchemaProperty,
+  JSONSchemaBase,
+  JSONSchemaString,
+  JSONSchemaNumber,
+  JSONSchemaInteger,
+  JSONSchemaBoolean,
+  JSONSchemaArray,
+  JSONSchemaObject,
+  JSONSchemaEnum,
+  // Field types
+  FieldType,
+  ValidationRule,
+  SelectOption,
+  FieldDefinition,
+  ComputedField,
+  PageDefinition,
+  FormMeta,
+  Forma,
+  // Evaluation
+  EvaluationContext,
+  // Results
+  VisibilityResult,
+  RequiredResult,
+  RequiredFieldsResult,
+  EnabledResult,
+  FieldError,
+  ValidationResult,
+  CalculationError,
+  CalculationResult,
+} from "./types.js";
 
 // FEEL expression evaluation
 export * from "./feel/index.js";

package/dist/engine/index.d.cts

@@ -1,258 +0,0 @@
-import { m as Forma, t as CalculationResult, n as VisibilityResult, o as RequiredFieldsResult, p as EnabledResult, r as ValidationResult, q as FieldError } from '../types-Bs3CG9JZ.cjs';
-
-/**
- * Calculation Engine
- *
- * Evaluates computed fields based on form data.
- * Computed values are derived from form data using FEEL expressions.
- */
-
-/**
- * Calculate all computed values from form data
- *
- * Evaluates each computed field's FEEL expression and returns the results.
- * Errors are collected rather than thrown, allowing partial results.
- *
- * @param data - Current form data
- * @param spec - Form specification with computed fields
- * @returns Computed values and any calculation errors
- *
- * @example
- * const spec = {
- *   computed: {
- *     bmi: {
- *       expression: "weight / (height / 100) ** 2",
- *       label: "BMI",
- *       format: "decimal(1)"
- *     },
- *     isObese: {
- *       expression: "$computed.bmi >= 30"
- *     }
- *   }
- * };
- *
- * const result = calculate({ weight: 85, height: 175 }, spec);
- * // => { values: { bmi: 27.76, isObese: false }, errors: [] }
- */
-declare function calculate(data: Record<string, unknown>, spec: Forma): Record<string, unknown>;
-/**
- * Calculate computed values with error reporting
- *
- * Same as calculate() but also returns any errors that occurred.
- *
- * @param data - Current form data
- * @param spec - Form specification
- * @returns Values and errors
- */
-declare function calculateWithErrors(data: Record<string, unknown>, spec: Forma): CalculationResult;
-/**
- * Get a computed value formatted according to its format specification
- *
- * @param fieldName - Name of the computed field
- * @param data - Current form data
- * @param spec - Form specification
- * @returns Formatted string or null if not displayable
- */
-declare function getFormattedValue(fieldName: string, data: Record<string, unknown>, spec: Forma): string | null;
-/**
- * Calculate a single computed field
- *
- * @param fieldName - Name of the computed field
- * @param data - Current form data
- * @param spec - Form specification
- * @returns Computed value or null if calculation failed
- */
-declare function calculateField(fieldName: string, data: Record<string, unknown>, spec: Forma): unknown;
-
-/**
- * Visibility Engine
- *
- * Determines which fields should be visible based on form data
- * and Forma visibility rules.
- */
-
-interface VisibilityOptions {
-    /** Pre-calculated computed values (avoids recalculation) */
-    computed?: Record<string, unknown>;
-}
-/**
- * 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, ... }
- */
-declare function getVisibility(data: Record<string, unknown>, spec: Forma, options?: VisibilityOptions): VisibilityResult;
-/**
- * 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
- */
-declare function isFieldVisible(fieldPath: string, data: Record<string, unknown>, spec: Forma, options?: VisibilityOptions): boolean;
-/**
- * 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
- */
-declare function getPageVisibility(data: Record<string, unknown>, spec: Forma, options?: VisibilityOptions): Record<string, boolean>;
-
-/**
- * Required Fields Engine
- *
- * Determines which fields are currently required based on
- * conditional requiredWhen expressions and schema required array.
- */
-
-interface RequiredOptions {
-    /** Pre-calculated computed values */
-    computed?: Record<string, unknown>;
-}
-/**
- * Determine which fields are currently required
- *
- * Returns a map of field paths to boolean required states.
- * Evaluates requiredWhen expressions for conditional requirements.
- *
- * @param data - Current form data
- * @param spec - Form specification
- * @param options - Optional pre-calculated computed values
- * @returns Map of field paths to required states
- *
- * @example
- * const required = getRequired(
- *   { hasInsurance: true },
- *   forma
- * );
- * // => { hasInsurance: true, insuranceProvider: true, policyNumber: true }
- */
-declare function getRequired(data: Record<string, unknown>, spec: Forma, options?: RequiredOptions): RequiredFieldsResult;
-/**
- * Check if a single field is currently required
- *
- * @param fieldPath - Path to the field
- * @param data - Current form data
- * @param spec - Form specification
- * @returns True if the field is required
- */
-declare function isRequired(fieldPath: string, data: Record<string, unknown>, spec: Forma): boolean;
-
-/**
- * Enabled Fields Engine
- *
- * Determines which fields are currently enabled (editable) based on
- * conditional enabledWhen expressions.
- */
-
-interface EnabledOptions {
-    /** Pre-calculated computed values */
-    computed?: Record<string, unknown>;
-}
-/**
- * Determine which fields are currently enabled (editable)
- *
- * Returns a map of field paths to boolean enabled states.
- * Fields without enabledWhen expressions are always enabled.
- *
- * @param data - Current form data
- * @param spec - Form specification
- * @param options - Optional pre-calculated computed values
- * @returns Map of field paths to enabled states
- *
- * @example
- * const enabled = getEnabled(
- *   { isLocked: true },
- *   forma
- * );
- * // => { isLocked: true, lockedField: false, ... }
- */
-declare function getEnabled(data: Record<string, unknown>, spec: Forma, options?: EnabledOptions): EnabledResult;
-/**
- * Check if a single field is currently enabled
- *
- * @param fieldPath - Path to the field
- * @param data - Current form data
- * @param spec - Form specification
- * @returns True if the field is enabled
- */
-declare function isEnabled(fieldPath: string, data: Record<string, unknown>, spec: Forma): boolean;
-
-/**
- * Validation Engine
- *
- * Validates form data against Forma rules including:
- * - JSON Schema type validation
- * - Required field validation (with conditional requiredWhen)
- * - Custom FEEL validation rules
- * - Array item validation
- */
-
-interface ValidateOptions {
-    /** Pre-calculated computed values */
-    computed?: Record<string, unknown>;
-    /** Pre-calculated visibility */
-    visibility?: Record<string, boolean>;
-    /** Only validate visible fields (default: true) */
-    onlyVisible?: boolean;
-}
-/**
- * Validate form data against a Forma
- *
- * Performs comprehensive validation including:
- * - Required field checks (respecting conditional requiredWhen)
- * - JSON Schema type validation
- * - Custom FEEL validation rules
- * - Array min/max items validation
- * - Array item field validation
- *
- * By default, only visible fields are validated.
- *
- * @param data - Current form data
- * @param spec - Form specification
- * @param options - Validation options
- * @returns Validation result with valid flag and errors array
- *
- * @example
- * const result = validate(
- *   { name: "", age: 15 },
- *   forma
- * );
- * // => {
- * //   valid: false,
- * //   errors: [
- * //     { field: "name", message: "Name is required", severity: "error" },
- * //     { field: "age", message: "Must be 18 or older", severity: "error" }
- * //   ]
- * // }
- */
-declare function validate(data: Record<string, unknown>, spec: Forma, options?: ValidateOptions): ValidationResult;
-/**
- * Validate a single field
- *
- * @param fieldPath - Path to the field
- * @param data - Current form data
- * @param spec - Form specification
- * @returns Array of errors for this field
- */
-declare function validateSingleField(fieldPath: string, data: Record<string, unknown>, spec: Forma): FieldError[];
-
-export { type EnabledOptions, type RequiredOptions, type ValidateOptions, type VisibilityOptions, calculate, calculateField, calculateWithErrors, getEnabled, getFormattedValue, getPageVisibility, getRequired, getVisibility, isEnabled, isFieldVisible, isRequired, validate, validateSingleField };

package/dist/feel/index.d.cts

@@ -1,105 +0,0 @@
-import { F as FEELExpression, E as EvaluationContext } from '../types-Bs3CG9JZ.cjs';
-
-/**
- * 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)
- */
-
-interface EvaluateResult<T = unknown> {
-    success: true;
-    value: T;
-}
-interface EvaluateError {
-    success: false;
-    error: string;
-    expression: string;
-}
-type EvaluationOutcome<T = unknown> = EvaluateResult<T> | EvaluateError;
-/**
- * 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 }
- */
-declare function evaluate<T = unknown>(expression: FEELExpression, context: EvaluationContext): EvaluationOutcome<T>;
-/**
- * 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)
- */
-declare function evaluateBoolean(expression: FEELExpression, context: EvaluationContext): boolean;
-/**
- * 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
- */
-declare function evaluateNumber(expression: FEELExpression, context: EvaluationContext): number | null;
-/**
- * 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
- */
-declare function evaluateString(expression: FEELExpression, context: EvaluationContext): string | null;
-/**
- * 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
- */
-declare function evaluateBooleanBatch(expressions: Record<string, FEELExpression>, context: EvaluationContext): Record<string, boolean>;
-/**
- * Check if a FEEL expression is syntactically valid
- *
- * @param expression - FEEL expression to validate
- * @returns True if the expression can be parsed
- */
-declare function isValidExpression(expression: FEELExpression): boolean;
-/**
- * Validate a FEEL expression and return any parsing errors
- *
- * @param expression - FEEL expression to validate
- * @returns Null if valid, error message if invalid
- */
-declare function validateExpression(expression: FEELExpression): string | null;
-
-export { type EvaluateError, type EvaluateResult, type EvaluationOutcome, evaluate, evaluateBoolean, evaluateBooleanBatch, evaluateNumber, evaluateString, isValidExpression, validateExpression };

package/dist/index.d.cts

@@ -1,3 +0,0 @@
-export { s as CalculationError, t as CalculationResult, C as ComputedField, p as EnabledResult, E as EvaluationContext, F as FEELExpression, k as FieldDefinition, q as FieldError, j as FieldType, l as FormMeta, m as Forma, J as JSONSchema, g as JSONSchemaArray, b as JSONSchemaBase, f as JSONSchemaBoolean, i as JSONSchemaEnum, e as JSONSchemaInteger, d as JSONSchemaNumber, h as JSONSchemaObject, a as JSONSchemaProperty, c as JSONSchemaString, P as PageDefinition, o as RequiredFieldsResult, R as RequiredResult, S as SelectOption, r as ValidationResult, V as ValidationRule, n as VisibilityResult } from './types-Bs3CG9JZ.cjs';
-export { EvaluateError, EvaluateResult, EvaluationOutcome, evaluate, evaluateBoolean, evaluateBooleanBatch, evaluateNumber, evaluateString, isValidExpression, validateExpression } from './feel/index.cjs';
-export { EnabledOptions, RequiredOptions, ValidateOptions, VisibilityOptions, calculate, calculateField, calculateWithErrors, getEnabled, getFormattedValue, getPageVisibility, getRequired, getVisibility, isEnabled, isFieldVisible, isRequired, validate, validateSingleField } from './engine/index.cjs';

package/dist/types-Bs3CG9JZ.d.cts

@@ -1,283 +0,0 @@
-/**
- * Core Forma Type Definitions
- *
- * This module defines the complete type system for Forma specifications.
- * All conditional logic uses FEEL (Friendly Enough Expression Language).
- */
-/**
- * FEEL expression - a string that will be evaluated at runtime.
- *
- * Available context variables:
- * - `fieldName` - Any field value by name
- * - `computed.name` - Computed value by name
- * - `ref.path` - Reference data lookup (external lookup tables)
- * - `item.fieldName` - Field within current array item
- * - `itemIndex` - Current item index (0-based)
- * - `value` - Current field value (in validation expressions)
- *
- * @example
- * "age >= 18"
- * "claimType = \"Auto\" and wasDriver = true"
- * "computed.bmi > 30"
- * "item.frequency = \"daily\""
- */
-type FEELExpression = string;
-/**
- * Standard JSON Schema (subset we support)
- */
-interface JSONSchema {
-    type: "object";
-    properties: Record<string, JSONSchemaProperty>;
-    required?: string[];
-    $defs?: Record<string, JSONSchemaProperty>;
-}
-type JSONSchemaProperty = JSONSchemaString | JSONSchemaNumber | JSONSchemaInteger | JSONSchemaBoolean | JSONSchemaArray | JSONSchemaObject | JSONSchemaEnum;
-interface JSONSchemaBase {
-    description?: string;
-    title?: string;
-}
-interface JSONSchemaString extends JSONSchemaBase {
-    type: "string";
-    minLength?: number;
-    maxLength?: number;
-    pattern?: string;
-    format?: "date" | "date-time" | "email" | "uri" | "uuid";
-    enum?: string[];
-}
-interface JSONSchemaNumber extends JSONSchemaBase {
-    type: "number";
-    minimum?: number;
-    maximum?: number;
-    exclusiveMinimum?: number;
-    exclusiveMaximum?: number;
-}
-interface JSONSchemaInteger extends JSONSchemaBase {
-    type: "integer";
-    minimum?: number;
-    maximum?: number;
-}
-interface JSONSchemaBoolean extends JSONSchemaBase {
-    type: "boolean";
-}
-interface JSONSchemaArray extends JSONSchemaBase {
-    type: "array";
-    items: JSONSchemaProperty;
-    minItems?: number;
-    maxItems?: number;
-}
-interface JSONSchemaObject extends JSONSchemaBase {
-    type: "object";
-    properties: Record<string, JSONSchemaProperty>;
-    required?: string[];
-}
-interface JSONSchemaEnum extends JSONSchemaBase {
-    type: "string";
-    enum: string[];
-}
-/**
- * Field type enumeration - maps to UI component types
- */
-type FieldType = "text" | "password" | "number" | "integer" | "boolean" | "select" | "multiselect" | "date" | "datetime" | "email" | "url" | "textarea" | "array" | "object" | "computed";
-/**
- * Validation rule with FEEL expression
- */
-interface ValidationRule {
-    /** FEEL expression that should evaluate to true for valid data */
-    rule: FEELExpression;
-    /** Error message shown when validation fails */
-    message: string;
-    /** Severity level - errors block submission, warnings are informational */
-    severity?: "error" | "warning";
-}
-/**
- * Option for select/multiselect fields
- */
-interface SelectOption {
-    /** Option value - can be string or number to match schema types */
-    value: string | number;
-    label: string;
-    /** When to show this option */
-    visibleWhen?: FEELExpression;
-}
-/**
- * Field definition with all conditional logic
- */
-interface FieldDefinition {
-    /** Display label for the field */
-    label?: string;
-    /** Help text or description */
-    description?: string;
-    /** Placeholder text for input fields */
-    placeholder?: string;
-    /** Field type override (inferred from schema if not provided) */
-    type?: FieldType;
-    /** When to show this field. If omitted, always visible. */
-    visibleWhen?: FEELExpression;
-    /** When this field is required. If omitted, uses schema required. */
-    requiredWhen?: FEELExpression;
-    /** When this field is editable. If omitted, always enabled. */
-    enabledWhen?: FEELExpression;
-    /** Custom validation rules using FEEL expressions */
-    validations?: ValidationRule[];
-    /** For array fields: field definitions for each item. Requires type: "array" */
-    itemFields?: Record<string, FieldDefinition>;
-    /** Minimum number of items (overrides schema) */
-    minItems?: number;
-    /** Maximum number of items (overrides schema) */
-    maxItems?: number;
-    /** For select fields: available options */
-    options?: SelectOption[];
-}
-/**
- * Computed field definition - derived values from form data
- */
-interface ComputedField {
-    /** FEEL expression to calculate the value */
-    expression: FEELExpression;
-    /** Display label */
-    label?: string;
-    /** Display format (e.g., "decimal(1)", "currency", "percent") */
-    format?: string;
-    /** Whether to display this value in the form */
-    display?: boolean;
-}
-/**
- * Page definition for multi-step wizard forms
- */
-interface PageDefinition {
-    /** Unique page identifier */
-    id: string;
-    /** Page title */
-    title: string;
-    /** Page description/instructions */
-    description?: string;
-    /** When to show this page */
-    visibleWhen?: FEELExpression;
-    /** Field paths to include on this page */
-    fields: string[];
-}
-/**
- * Form metadata
- */
-interface FormMeta {
-    /** Unique form identifier */
-    id: string;
-    /** Form title */
-    title: string;
-    /** Form description */
-    description?: string;
-    /** Form version */
-    version?: string;
-}
-/**
- * Complete Form Specification
- *
- * This is the root type that defines an entire form including:
- * - Data schema (JSON Schema)
- * - Computed values
- * - Reference data (lookup tables for calculations)
- * - Field-level configuration and conditional logic
- * - Field ordering
- * - Optional wizard/page structure
- */
-interface Forma {
-    /** Schema version identifier */
-    $schema?: string;
-    /** Spec version */
-    version: "1.0";
-    /** Form metadata */
-    meta: FormMeta;
-    /** JSON Schema defining the data structure */
-    schema: JSONSchema;
-    /** Computed/calculated values */
-    computed?: Record<string, ComputedField>;
-    /** Reference data for lookups (external data sources, lookup tables) */
-    referenceData?: Record<string, unknown>;
-    /** Field-level definitions and rules */
-    fields: Record<string, FieldDefinition>;
-    /** Order in which fields should be displayed */
-    fieldOrder: string[];
-    /** Optional multi-page wizard structure */
-    pages?: PageDefinition[];
-}
-/**
- * Context provided when evaluating FEEL expressions
- */
-interface EvaluationContext {
-    /** Current form data */
-    data: Record<string, unknown>;
-    /** Computed values (calculated before field evaluation) */
-    computed?: Record<string, unknown>;
-    /** Reference data for lookups (external data sources, lookup tables) */
-    referenceData?: Record<string, unknown>;
-    /** Current array item (when evaluating within array context) */
-    item?: Record<string, unknown>;
-    /** Current array item index (0-based) */
-    itemIndex?: number;
-    /** Current field value (for validation expressions) */
-    value?: unknown;
-}
-/**
- * Field visibility result - map of field path to visibility state
- */
-interface VisibilityResult {
-    [fieldPath: string]: boolean;
-}
-/**
- * Required fields result - map of field path to required state
- */
-interface RequiredResult {
-    [fieldPath: string]: boolean;
-}
-/**
- * Alias for RequiredResult (backwards compatibility)
- */
-type RequiredFieldsResult = RequiredResult;
-/**
- * Enabled fields result - map of field path to enabled state
- */
-interface EnabledResult {
-    [fieldPath: string]: boolean;
-}
-/**
- * Field validation error
- */
-interface FieldError {
-    /** Field path that has the error */
-    field: string;
-    /** Error message */
-    message: string;
-    /** Error severity */
-    severity: "error" | "warning";
-}
-/**
- * Validation result
- */
-interface ValidationResult {
-    /** Whether the form data is valid */
-    valid: boolean;
-    /** List of validation errors */
-    errors: FieldError[];
-}
-/**
- * Calculation error
- */
-interface CalculationError {
-    /** Computed field name */
-    field: string;
-    /** Error message */
-    message: string;
-    /** The expression that failed */
-    expression: string;
-}
-/**
- * Calculation result with potential errors
- */
-interface CalculationResult {
-    /** Computed values */
-    values: Record<string, unknown>;
-    /** Errors encountered during calculation */
-    errors: CalculationError[];
-}
-
-export type { ComputedField as C, EvaluationContext as E, FEELExpression as F, JSONSchema as J, PageDefinition as P, RequiredResult as R, SelectOption as S, ValidationRule as V, JSONSchemaProperty as a, JSONSchemaBase as b, JSONSchemaString as c, JSONSchemaNumber as d, JSONSchemaInteger as e, JSONSchemaBoolean as f, JSONSchemaArray as g, JSONSchemaObject as h, JSONSchemaEnum as i, FieldType as j, FieldDefinition as k, FormMeta as l, Forma as m, VisibilityResult as n, RequiredFieldsResult as o, EnabledResult as p, FieldError as q, ValidationResult as r, CalculationError as s, CalculationResult as t };