@fogpipe/forma-core 0.6.0

package/dist/types-Bs3CG9JZ.d.ts

@@ -0,0 +1,283 @@
+/**
+ * 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 };

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@fogpipe/forma-core",
+  "version": "0.6.0",
+  "description": "Forma core runtime: Types and evaluation engines for dynamic forms with FEEL expressions",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./engine": {
+      "import": {
+        "types": "./dist/engine/index.d.ts",
+        "default": "./dist/engine/index.js"
+      },
+      "require": {
+        "types": "./dist/engine/index.d.ts",
+        "default": "./dist/engine/index.cjs"
+      }
+    },
+    "./feel": {
+      "import": {
+        "types": "./dist/feel/index.d.ts",
+        "default": "./dist/feel/index.js"
+      },
+      "require": {
+        "types": "./dist/feel/index.d.ts",
+        "default": "./dist/feel/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint .",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "feelin": "^5.1.0"
+  },
+  "devDependencies": {
+    "@fogpipe/eslint-config": "*",
+    "@fogpipe/typescript-config": "*",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "keywords": [
+    "form",
+    "feel",
+    "validation",
+    "conditional-logic",
+    "dynamic-forms"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fogpipe/forma.git",
+    "directory": "packages/forma-core"
+  },
+  "bugs": {
+    "url": "https://github.com/fogpipe/forma/issues"
+  },
+  "homepage": "https://github.com/fogpipe/forma#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}