react-form-atlas-engine 1.1.0

package/README.md

@@ -0,0 +1,92 @@
+# react-form-atlas-engine
+
+[![npm version](https://img.shields.io/npm/v/react-form-atlas-engine.svg?style=flat-square)](https://www.npmjs.com/package/react-form-atlas-engine)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
+
+**The Brain of Your Forms.** Framework-agnostic graph-based form engine that eliminates "condition hell" in complex multi-step flows.
+
+## 🚀 Why Graph-Based?
+
+Traditional linear forms (`[Step1, Step2, Step3]`) break when logic gets complex. **React Form Atlas** treats your form as a **Directed Acyclic Graph (DAG)**.
+
+```mermaid
+graph LR
+  Start((Start)) --> UserType{User Type?}
+  UserType -->|Business| Biz[Business Details]
+  UserType -->|Individual| Pers[Personal Details]
+  Biz --> Tax[Tax Info]
+  Pers --> Complete((Complete))
+  Tax --> Complete
+  style Start fill:#f9f,stroke:#333,stroke-width:2px
+  style Complete fill:#9f9,stroke:#333,stroke-width:2px
+```
+
+| Feature | ❌ Linear Forms | ✅ React Form Atlas (Graph) |
+| :--- | :--- | :--- |
+| **Logic** | Nested `if/else` spaghetti | Declarative Edges |
+| **Navigation** | Hardcoded implementation | Auto-computed Paths |
+| **Progress** | `Step / Total` (Inaccurate) | Weighted Path Calculation |
+| **Validation** | Field-level only | Predictive Path Validation |
+
+## 📦 Installation
+
+```bash
+npm install react-form-atlas-engine
+```
+
+## ⚡ Quick Start
+
+[![Try on StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/edit/node?file=index.js&dependencies=react-form-atlas-engine)
+
+```javascript
+import { FormEngine } from 'react-form-atlas-engine';
+
+// 1. Define your map (Schema)
+const schema = {
+  id: 'onboarding-flow',
+  initial: 'welcome',
+  states: {
+    welcome: {
+      on: { NEXT: 'userType' }
+    },
+    userType: {
+      on: {
+        BUSINESS: 'businessDetails',
+        INDIVIDUAL: 'personalDetails'
+      }
+    },
+    businessDetails: { on: { NEXT: 'complete' } },
+    personalDetails: { on: { NEXT: 'complete' } },
+    complete: { type: 'final' }
+  }
+};
+
+// 2. Initialize the engine
+const engine = new FormEngine({
+  schema,
+  autoSave: true, // Auto-saves to IndexedDB
+  onComplete: (data) => console.log('🎉 Form Completed:', data)
+});
+
+await engine.start();
+
+// 3. Drive!
+console.log(engine.getCurrentState()); // 'welcome'
+await engine.transition('NEXT'); 
+console.log(engine.getCurrentState()); // 'userType'
+```
+
+## 📚 Documentation
+
+- [**Core Concepts**](https://github.com/Mehulbirare/react-form/blob/main/docs/core-concepts.md) - Learn about Nodes, Edges, and Travelers.
+- [**API Reference**](https://github.com/Mehulbirare/react-form/blob/main/docs/api-reference.md) - Full method documentation.
+- [**Examples**](https://github.com/Mehulbirare/react-form/tree/main/examples) - Real-world usage.
+
+## 📄 License
+
+MIT © [Mehul Birare](https://github.com/Mehulbirare)
+
+
+
+

package/dist/index.d.mts

@@ -0,0 +1,174 @@
+/**
+ * Core types for React Form Atlas
+ */
+type TransitionEvent = string;
+interface FormState {
+    id: string;
+    on?: Record<TransitionEvent, string | ConditionalTransition>;
+    meta?: {
+        weight?: number;
+        validation?: ValidationRule[];
+        [key: string]: any;
+    };
+}
+interface ConditionalTransition {
+    target: string;
+    cond?: (context: FormContext) => boolean;
+}
+interface FormSchema {
+    id: string;
+    initial: string;
+    states: Record<string, FormState>;
+    context?: Record<string, any>;
+}
+interface FormContext {
+    [key: string]: any;
+}
+interface ValidationRule {
+    type: 'required' | 'email' | 'min' | 'max' | 'pattern' | 'custom';
+    message: string;
+    value?: any;
+    validator?: (value: any, context: FormContext) => boolean;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+interface StepChangeEvent {
+    from: string;
+    to: string;
+    context: FormContext;
+}
+interface FormEngineOptions {
+    schema: FormSchema;
+    autoSave?: boolean;
+    storageKey?: string;
+    onStepChange?: (event: StepChangeEvent) => void;
+    onComplete?: (context: FormContext) => void;
+    onError?: (error: Error) => void;
+}
+interface FormEngineState {
+    currentState: string;
+    context: FormContext;
+    history: string[];
+    completedSteps: Set<string>;
+}
+
+/**
+ * Form Engine - The core state machine for graph-based forms
+ */
+declare class FormEngine {
+    private schema;
+    private state;
+    private storage;
+    private listeners;
+    private options;
+    constructor(options: FormEngineOptions);
+    /**
+     * Start the form engine
+     */
+    start(): Promise<void>;
+    /**
+     * Transition to the next state based on an event
+     */
+    transition(event: string, data?: any): Promise<void>;
+    /**
+     * Go back to the previous state
+     */
+    back(): Promise<void>;
+    /**
+     * Update context without transitioning
+     */
+    updateContext(data: Partial<FormContext>): Promise<void>;
+    /**
+     * Get current progress percentage
+     */
+    getProgress(): number;
+    /**
+     * Get current state
+     */
+    getCurrentState(): string;
+    /**
+     * Get current context
+     */
+    getContext(): FormContext;
+    /**
+     * Get possible next states
+     */
+    getPossibleNextStates(): string[];
+    /**
+     * Reset the form
+     */
+    reset(): Promise<void>;
+    /**
+     * Event emitter
+     */
+    on(event: string, callback: Function): void;
+    /**
+     * Remove event listener
+     */
+    off(event: string, callback: Function): void;
+    /**
+     * Emit event
+     */
+    private emit;
+    /**
+     * Get all possible paths from current state
+     */
+    getPossiblePaths(): string[][];
+    /**
+     * Check if we can go back
+     */
+    canGoBack(): boolean;
+    /**
+     * Get the full state (for debugging)
+     */
+    getState(): FormEngineState;
+}
+
+/**
+ * Storage adapter for persisting form state
+ */
+declare class StorageAdapter {
+    private storageKey;
+    private useIndexedDB;
+    constructor(storageKey?: string);
+    save(state: FormEngineState): Promise<void>;
+    load(): Promise<FormEngineState | null>;
+    clear(): Promise<void>;
+}
+
+/**
+ * Validator for form fields and paths
+ */
+declare class Validator {
+    /**
+     * Validate a single field value
+     */
+    static validateField(value: any, rules: ValidationRule[], context: FormContext): ValidationResult;
+    /**
+     * Predictive validation: Check if the current path is still valid
+     * This prevents users from entering data that makes future steps impossible
+     */
+    static validatePath(currentState: string, context: FormContext, schema: any): ValidationResult;
+}
+
+/**
+ * Calculate the total weight of a path through the form graph
+ */
+declare class PathCalculator {
+    /**
+     * Calculate the total possible weight from current state to completion
+     */
+    static calculateRemainingWeight(currentState: string, schema: FormSchema, visited?: Set<string>): number;
+    /**
+     * Calculate progress percentage based on completed path weight
+     */
+    static calculateProgress(currentState: string, completedSteps: Set<string>, schema: FormSchema): number;
+    /**
+     * Get all possible paths from current state
+     */
+    static getPossiblePaths(currentState: string, schema: FormSchema, context?: any): string[][];
+}
+
+export { type ConditionalTransition, type FormContext, FormEngine, type FormEngineOptions, type FormEngineState, type FormSchema, type FormState, PathCalculator, type StepChangeEvent, StorageAdapter, type TransitionEvent, type ValidationResult, type ValidationRule, Validator };

package/dist/index.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Core types for React Form Atlas
+ */
+type TransitionEvent = string;
+interface FormState {
+    id: string;
+    on?: Record<TransitionEvent, string | ConditionalTransition>;
+    meta?: {
+        weight?: number;
+        validation?: ValidationRule[];
+        [key: string]: any;
+    };
+}
+interface ConditionalTransition {
+    target: string;
+    cond?: (context: FormContext) => boolean;
+}
+interface FormSchema {
+    id: string;
+    initial: string;
+    states: Record<string, FormState>;
+    context?: Record<string, any>;
+}
+interface FormContext {
+    [key: string]: any;
+}
+interface ValidationRule {
+    type: 'required' | 'email' | 'min' | 'max' | 'pattern' | 'custom';
+    message: string;
+    value?: any;
+    validator?: (value: any, context: FormContext) => boolean;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+interface StepChangeEvent {
+    from: string;
+    to: string;
+    context: FormContext;
+}
+interface FormEngineOptions {
+    schema: FormSchema;
+    autoSave?: boolean;
+    storageKey?: string;
+    onStepChange?: (event: StepChangeEvent) => void;
+    onComplete?: (context: FormContext) => void;
+    onError?: (error: Error) => void;
+}
+interface FormEngineState {
+    currentState: string;
+    context: FormContext;
+    history: string[];
+    completedSteps: Set<string>;
+}
+
+/**
+ * Form Engine - The core state machine for graph-based forms
+ */
+declare class FormEngine {
+    private schema;
+    private state;
+    private storage;
+    private listeners;
+    private options;
+    constructor(options: FormEngineOptions);
+    /**
+     * Start the form engine
+     */
+    start(): Promise<void>;
+    /**
+     * Transition to the next state based on an event
+     */
+    transition(event: string, data?: any): Promise<void>;
+    /**
+     * Go back to the previous state
+     */
+    back(): Promise<void>;
+    /**
+     * Update context without transitioning
+     */
+    updateContext(data: Partial<FormContext>): Promise<void>;
+    /**
+     * Get current progress percentage
+     */
+    getProgress(): number;
+    /**
+     * Get current state
+     */
+    getCurrentState(): string;
+    /**
+     * Get current context
+     */
+    getContext(): FormContext;
+    /**
+     * Get possible next states
+     */
+    getPossibleNextStates(): string[];
+    /**
+     * Reset the form
+     */
+    reset(): Promise<void>;
+    /**
+     * Event emitter
+     */
+    on(event: string, callback: Function): void;
+    /**
+     * Remove event listener
+     */
+    off(event: string, callback: Function): void;
+    /**
+     * Emit event
+     */
+    private emit;
+    /**
+     * Get all possible paths from current state
+     */
+    getPossiblePaths(): string[][];
+    /**
+     * Check if we can go back
+     */
+    canGoBack(): boolean;
+    /**
+     * Get the full state (for debugging)
+     */
+    getState(): FormEngineState;
+}
+
+/**
+ * Storage adapter for persisting form state
+ */
+declare class StorageAdapter {
+    private storageKey;
+    private useIndexedDB;
+    constructor(storageKey?: string);
+    save(state: FormEngineState): Promise<void>;
+    load(): Promise<FormEngineState | null>;
+    clear(): Promise<void>;
+}
+
+/**
+ * Validator for form fields and paths
+ */
+declare class Validator {
+    /**
+     * Validate a single field value
+     */
+    static validateField(value: any, rules: ValidationRule[], context: FormContext): ValidationResult;
+    /**
+     * Predictive validation: Check if the current path is still valid
+     * This prevents users from entering data that makes future steps impossible
+     */
+    static validatePath(currentState: string, context: FormContext, schema: any): ValidationResult;
+}
+
+/**
+ * Calculate the total weight of a path through the form graph
+ */
+declare class PathCalculator {
+    /**
+     * Calculate the total possible weight from current state to completion
+     */
+    static calculateRemainingWeight(currentState: string, schema: FormSchema, visited?: Set<string>): number;
+    /**
+     * Calculate progress percentage based on completed path weight
+     */
+    static calculateProgress(currentState: string, completedSteps: Set<string>, schema: FormSchema): number;
+    /**
+     * Get all possible paths from current state
+     */
+    static getPossiblePaths(currentState: string, schema: FormSchema, context?: any): string[][];
+}
+
+export { type ConditionalTransition, type FormContext, FormEngine, type FormEngineOptions, type FormEngineState, type FormSchema, type FormState, PathCalculator, type StepChangeEvent, StorageAdapter, type TransitionEvent, type ValidationResult, type ValidationRule, Validator };

package/dist/index.js

@@ -0,0 +1,457 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FormEngine: () => FormEngine,
+  PathCalculator: () => PathCalculator,
+  StorageAdapter: () => StorageAdapter,
+  Validator: () => Validator
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/storage.ts
+var import_idb_keyval = require("idb-keyval");
+var StorageAdapter = class {
+  constructor(storageKey = "React Form Atlas-state") {
+    this.storageKey = storageKey;
+    this.useIndexedDB = typeof indexedDB !== "undefined";
+  }
+  async save(state) {
+    try {
+      const serialized = JSON.stringify({
+        ...state,
+        completedSteps: Array.from(state.completedSteps)
+      });
+      if (this.useIndexedDB) {
+        await (0, import_idb_keyval.set)(this.storageKey, serialized);
+      } else {
+        localStorage.setItem(this.storageKey, serialized);
+      }
+    } catch (error) {
+      console.error("Failed to save form state:", error);
+      throw error;
+    }
+  }
+  async load() {
+    try {
+      let serialized = null;
+      if (this.useIndexedDB) {
+        const result = await (0, import_idb_keyval.get)(this.storageKey);
+        serialized = result;
+      } else {
+        serialized = localStorage.getItem(this.storageKey);
+      }
+      if (!serialized) return null;
+      const parsed = JSON.parse(serialized);
+      return {
+        ...parsed,
+        completedSteps: new Set(parsed.completedSteps)
+      };
+    } catch (error) {
+      console.error("Failed to load form state:", error);
+      return null;
+    }
+  }
+  async clear() {
+    try {
+      if (this.useIndexedDB) {
+        await (0, import_idb_keyval.del)(this.storageKey);
+      } else {
+        localStorage.removeItem(this.storageKey);
+      }
+    } catch (error) {
+      console.error("Failed to clear form state:", error);
+      throw error;
+    }
+  }
+};
+
+// src/validator.ts
+var Validator = class {
+  /**
+   * Validate a single field value
+   */
+  static validateField(value, rules, context) {
+    const errors = [];
+    for (const rule of rules) {
+      switch (rule.type) {
+        case "required":
+          if (value === void 0 || value === null || value === "") {
+            errors.push(rule.message);
+          }
+          break;
+        case "email":
+          if (value && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
+            errors.push(rule.message);
+          }
+          break;
+        case "min":
+          if (typeof value === "number" && value < rule.value) {
+            errors.push(rule.message);
+          } else if (typeof value === "string" && value.length < rule.value) {
+            errors.push(rule.message);
+          }
+          break;
+        case "max":
+          if (typeof value === "number" && value > rule.value) {
+            errors.push(rule.message);
+          } else if (typeof value === "string" && value.length > rule.value) {
+            errors.push(rule.message);
+          }
+          break;
+        case "pattern":
+          if (value && !new RegExp(rule.value).test(value)) {
+            errors.push(rule.message);
+          }
+          break;
+        case "custom":
+          if (rule.validator && !rule.validator(value, context)) {
+            errors.push(rule.message);
+          }
+          break;
+      }
+    }
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+  /**
+   * Predictive validation: Check if the current path is still valid
+   * This prevents users from entering data that makes future steps impossible
+   */
+  static validatePath(currentState, context, schema) {
+    const errors = [];
+    const state = schema.states[currentState];
+    if (state?.meta?.validation) {
+      const result = this.validateField(
+        context[currentState],
+        state.meta.validation,
+        context
+      );
+      errors.push(...result.errors);
+    }
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+};
+
+// src/path-calculator.ts
+var PathCalculator = class {
+  /**
+   * Calculate the total possible weight from current state to completion
+   */
+  static calculateRemainingWeight(currentState, schema, visited = /* @__PURE__ */ new Set()) {
+    if (visited.has(currentState)) {
+      return 0;
+    }
+    visited.add(currentState);
+    const state = schema.states[currentState];
+    if (!state || !state.on) {
+      return state?.meta?.weight || 1;
+    }
+    const currentWeight = state.meta?.weight || 1;
+    const transitions = Object.values(state.on);
+    if (transitions.length === 0) {
+      return currentWeight;
+    }
+    const maxFutureWeight = Math.max(
+      ...transitions.map((transition) => {
+        const target = typeof transition === "string" ? transition : transition.target;
+        return this.calculateRemainingWeight(target, schema, new Set(visited));
+      })
+    );
+    return currentWeight + maxFutureWeight;
+  }
+  /**
+   * Calculate progress percentage based on completed path weight
+   */
+  static calculateProgress(currentState, completedSteps, schema) {
+    const totalWeight = this.calculateRemainingWeight(schema.initial, schema);
+    let completedWeight = 0;
+    for (const step of completedSteps) {
+      const state = schema.states[step];
+      completedWeight += state?.meta?.weight || 1;
+    }
+    return totalWeight > 0 ? completedWeight / totalWeight * 100 : 0;
+  }
+  /**
+   * Get all possible paths from current state
+   */
+  static getPossiblePaths(currentState, schema, context = {}) {
+    const paths = [];
+    const visited = /* @__PURE__ */ new Set();
+    const traverse = (state, currentPath) => {
+      if (visited.has(state)) return;
+      const stateConfig = schema.states[state];
+      if (!stateConfig) return;
+      const newPath = [...currentPath, state];
+      if (!stateConfig.on || Object.keys(stateConfig.on).length === 0) {
+        paths.push(newPath);
+        return;
+      }
+      visited.add(state);
+      for (const transition of Object.values(stateConfig.on)) {
+        const target = typeof transition === "string" ? transition : transition.target;
+        if (typeof transition === "object" && transition.cond) {
+          if (!transition.cond(context)) continue;
+        }
+        traverse(target, newPath);
+      }
+      visited.delete(state);
+    };
+    traverse(currentState, []);
+    return paths;
+  }
+};
+
+// src/engine.ts
+var FormEngine = class {
+  constructor(options) {
+    this.storage = null;
+    this.listeners = /* @__PURE__ */ new Map();
+    this.options = options;
+    this.schema = options.schema;
+    this.state = {
+      currentState: this.schema.initial,
+      context: this.schema.context || {},
+      history: [],
+      completedSteps: /* @__PURE__ */ new Set()
+    };
+    if (options.autoSave) {
+      this.storage = new StorageAdapter(options.storageKey);
+    }
+  }
+  /**
+   * Start the form engine
+   */
+  async start() {
+    if (this.storage) {
+      const savedState = await this.storage.load();
+      if (savedState) {
+        this.state = savedState;
+        this.emit("resumed", { state: this.state });
+      }
+    }
+    this.emit("started", { state: this.state });
+  }
+  /**
+   * Transition to the next state based on an event
+   */
+  async transition(event, data) {
+    const currentStateConfig = this.schema.states[this.state.currentState];
+    if (!currentStateConfig?.on) {
+      throw new Error(`No transitions defined for state: ${this.state.currentState}`);
+    }
+    const transition = currentStateConfig.on[event];
+    if (!transition) {
+      throw new Error(`No transition found for event: ${event} in state: ${this.state.currentState}`);
+    }
+    if (data) {
+      this.state.context = { ...this.state.context, ...data };
+    }
+    let targetState;
+    if (typeof transition === "string") {
+      targetState = transition;
+    } else {
+      const conditionalTransition = transition;
+      if (conditionalTransition.cond && !conditionalTransition.cond(this.state.context)) {
+        throw new Error(`Condition not met for transition to: ${conditionalTransition.target}`);
+      }
+      targetState = conditionalTransition.target;
+    }
+    const validation = Validator.validatePath(
+      this.state.currentState,
+      this.state.context,
+      this.schema
+    );
+    if (!validation.valid) {
+      this.emit("validationError", { errors: validation.errors });
+      if (this.options.onError) {
+        this.options.onError(new Error(validation.errors.join(", ")));
+      }
+      return;
+    }
+    const previousState = this.state.currentState;
+    this.state.completedSteps.add(previousState);
+    this.state.history.push(previousState);
+    this.state.currentState = targetState;
+    if (this.storage) {
+      await this.storage.save(this.state);
+    }
+    const stepChangeEvent = {
+      from: previousState,
+      to: targetState,
+      context: this.state.context
+    };
+    this.emit("stepChange", stepChangeEvent);
+    if (this.options.onStepChange) {
+      this.options.onStepChange(stepChangeEvent);
+    }
+    const targetStateConfig = this.schema.states[targetState];
+    if (!targetStateConfig?.on || Object.keys(targetStateConfig.on).length === 0) {
+      this.emit("complete", { context: this.state.context });
+      if (this.options.onComplete) {
+        this.options.onComplete(this.state.context);
+      }
+    }
+  }
+  /**
+   * Go back to the previous state
+   */
+  async back() {
+    if (this.state.history.length === 0) {
+      throw new Error("Cannot go back: no history available");
+    }
+    const previousState = this.state.history.pop();
+    this.state.completedSteps.delete(this.state.currentState);
+    const currentState = this.state.currentState;
+    this.state.currentState = previousState;
+    if (this.storage) {
+      await this.storage.save(this.state);
+    }
+    this.emit("stepChange", {
+      from: currentState,
+      to: previousState,
+      context: this.state.context
+    });
+  }
+  /**
+   * Update context without transitioning
+   */
+  async updateContext(data) {
+    this.state.context = { ...this.state.context, ...data };
+    if (this.storage) {
+      await this.storage.save(this.state);
+    }
+    this.emit("contextUpdate", { context: this.state.context });
+  }
+  /**
+   * Get current progress percentage
+   */
+  getProgress() {
+    return PathCalculator.calculateProgress(
+      this.state.currentState,
+      this.state.completedSteps,
+      this.schema
+    );
+  }
+  /**
+   * Get current state
+   */
+  getCurrentState() {
+    return this.state.currentState;
+  }
+  /**
+   * Get current context
+   */
+  getContext() {
+    return { ...this.state.context };
+  }
+  /**
+   * Get possible next states
+   */
+  getPossibleNextStates() {
+    const currentStateConfig = this.schema.states[this.state.currentState];
+    if (!currentStateConfig?.on) {
+      return [];
+    }
+    return Object.values(currentStateConfig.on).map(
+      (transition) => typeof transition === "string" ? transition : transition.target
+    );
+  }
+  /**
+   * Reset the form
+   */
+  async reset() {
+    this.state = {
+      currentState: this.schema.initial,
+      context: this.schema.context || {},
+      history: [],
+      completedSteps: /* @__PURE__ */ new Set()
+    };
+    if (this.storage) {
+      await this.storage.clear();
+    }
+    this.emit("reset", {});
+  }
+  /**
+   * Event emitter
+   */
+  on(event, callback) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(callback);
+  }
+  /**
+   * Remove event listener
+   */
+  off(event, callback) {
+    const callbacks = this.listeners.get(event);
+    if (callbacks) {
+      callbacks.delete(callback);
+    }
+  }
+  /**
+   * Emit event
+   */
+  emit(event, data) {
+    const callbacks = this.listeners.get(event);
+    if (callbacks) {
+      callbacks.forEach((callback) => callback(data));
+    }
+  }
+  /**
+   * Get all possible paths from current state
+   */
+  getPossiblePaths() {
+    return PathCalculator.getPossiblePaths(
+      this.state.currentState,
+      this.schema,
+      this.state.context
+    );
+  }
+  /**
+   * Check if we can go back
+   */
+  canGoBack() {
+    return this.state.history.length > 0;
+  }
+  /**
+   * Get the full state (for debugging)
+   */
+  getState() {
+    return {
+      ...this.state,
+      completedSteps: new Set(this.state.completedSteps)
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FormEngine,
+  PathCalculator,
+  StorageAdapter,
+  Validator
+});

package/dist/index.mjs

@@ -0,0 +1,427 @@
+// src/storage.ts
+import { get, set, del } from "idb-keyval";
+var StorageAdapter = class {
+  constructor(storageKey = "React Form Atlas-state") {
+    this.storageKey = storageKey;
+    this.useIndexedDB = typeof indexedDB !== "undefined";
+  }
+  async save(state) {
+    try {
+      const serialized = JSON.stringify({
+        ...state,
+        completedSteps: Array.from(state.completedSteps)
+      });
+      if (this.useIndexedDB) {
+        await set(this.storageKey, serialized);
+      } else {
+        localStorage.setItem(this.storageKey, serialized);
+      }
+    } catch (error) {
+      console.error("Failed to save form state:", error);
+      throw error;
+    }
+  }
+  async load() {
+    try {
+      let serialized = null;
+      if (this.useIndexedDB) {
+        const result = await get(this.storageKey);
+        serialized = result;
+      } else {
+        serialized = localStorage.getItem(this.storageKey);
+      }
+      if (!serialized) return null;
+      const parsed = JSON.parse(serialized);
+      return {
+        ...parsed,
+        completedSteps: new Set(parsed.completedSteps)
+      };
+    } catch (error) {
+      console.error("Failed to load form state:", error);
+      return null;
+    }
+  }
+  async clear() {
+    try {
+      if (this.useIndexedDB) {
+        await del(this.storageKey);
+      } else {
+        localStorage.removeItem(this.storageKey);
+      }
+    } catch (error) {
+      console.error("Failed to clear form state:", error);
+      throw error;
+    }
+  }
+};
+
+// src/validator.ts
+var Validator = class {
+  /**
+   * Validate a single field value
+   */
+  static validateField(value, rules, context) {
+    const errors = [];
+    for (const rule of rules) {
+      switch (rule.type) {
+        case "required":
+          if (value === void 0 || value === null || value === "") {
+            errors.push(rule.message);
+          }
+          break;
+        case "email":
+          if (value && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
+            errors.push(rule.message);
+          }
+          break;
+        case "min":
+          if (typeof value === "number" && value < rule.value) {
+            errors.push(rule.message);
+          } else if (typeof value === "string" && value.length < rule.value) {
+            errors.push(rule.message);
+          }
+          break;
+        case "max":
+          if (typeof value === "number" && value > rule.value) {
+            errors.push(rule.message);
+          } else if (typeof value === "string" && value.length > rule.value) {
+            errors.push(rule.message);
+          }
+          break;
+        case "pattern":
+          if (value && !new RegExp(rule.value).test(value)) {
+            errors.push(rule.message);
+          }
+          break;
+        case "custom":
+          if (rule.validator && !rule.validator(value, context)) {
+            errors.push(rule.message);
+          }
+          break;
+      }
+    }
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+  /**
+   * Predictive validation: Check if the current path is still valid
+   * This prevents users from entering data that makes future steps impossible
+   */
+  static validatePath(currentState, context, schema) {
+    const errors = [];
+    const state = schema.states[currentState];
+    if (state?.meta?.validation) {
+      const result = this.validateField(
+        context[currentState],
+        state.meta.validation,
+        context
+      );
+      errors.push(...result.errors);
+    }
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+};
+
+// src/path-calculator.ts
+var PathCalculator = class {
+  /**
+   * Calculate the total possible weight from current state to completion
+   */
+  static calculateRemainingWeight(currentState, schema, visited = /* @__PURE__ */ new Set()) {
+    if (visited.has(currentState)) {
+      return 0;
+    }
+    visited.add(currentState);
+    const state = schema.states[currentState];
+    if (!state || !state.on) {
+      return state?.meta?.weight || 1;
+    }
+    const currentWeight = state.meta?.weight || 1;
+    const transitions = Object.values(state.on);
+    if (transitions.length === 0) {
+      return currentWeight;
+    }
+    const maxFutureWeight = Math.max(
+      ...transitions.map((transition) => {
+        const target = typeof transition === "string" ? transition : transition.target;
+        return this.calculateRemainingWeight(target, schema, new Set(visited));
+      })
+    );
+    return currentWeight + maxFutureWeight;
+  }
+  /**
+   * Calculate progress percentage based on completed path weight
+   */
+  static calculateProgress(currentState, completedSteps, schema) {
+    const totalWeight = this.calculateRemainingWeight(schema.initial, schema);
+    let completedWeight = 0;
+    for (const step of completedSteps) {
+      const state = schema.states[step];
+      completedWeight += state?.meta?.weight || 1;
+    }
+    return totalWeight > 0 ? completedWeight / totalWeight * 100 : 0;
+  }
+  /**
+   * Get all possible paths from current state
+   */
+  static getPossiblePaths(currentState, schema, context = {}) {
+    const paths = [];
+    const visited = /* @__PURE__ */ new Set();
+    const traverse = (state, currentPath) => {
+      if (visited.has(state)) return;
+      const stateConfig = schema.states[state];
+      if (!stateConfig) return;
+      const newPath = [...currentPath, state];
+      if (!stateConfig.on || Object.keys(stateConfig.on).length === 0) {
+        paths.push(newPath);
+        return;
+      }
+      visited.add(state);
+      for (const transition of Object.values(stateConfig.on)) {
+        const target = typeof transition === "string" ? transition : transition.target;
+        if (typeof transition === "object" && transition.cond) {
+          if (!transition.cond(context)) continue;
+        }
+        traverse(target, newPath);
+      }
+      visited.delete(state);
+    };
+    traverse(currentState, []);
+    return paths;
+  }
+};
+
+// src/engine.ts
+var FormEngine = class {
+  constructor(options) {
+    this.storage = null;
+    this.listeners = /* @__PURE__ */ new Map();
+    this.options = options;
+    this.schema = options.schema;
+    this.state = {
+      currentState: this.schema.initial,
+      context: this.schema.context || {},
+      history: [],
+      completedSteps: /* @__PURE__ */ new Set()
+    };
+    if (options.autoSave) {
+      this.storage = new StorageAdapter(options.storageKey);
+    }
+  }
+  /**
+   * Start the form engine
+   */
+  async start() {
+    if (this.storage) {
+      const savedState = await this.storage.load();
+      if (savedState) {
+        this.state = savedState;
+        this.emit("resumed", { state: this.state });
+      }
+    }
+    this.emit("started", { state: this.state });
+  }
+  /**
+   * Transition to the next state based on an event
+   */
+  async transition(event, data) {
+    const currentStateConfig = this.schema.states[this.state.currentState];
+    if (!currentStateConfig?.on) {
+      throw new Error(`No transitions defined for state: ${this.state.currentState}`);
+    }
+    const transition = currentStateConfig.on[event];
+    if (!transition) {
+      throw new Error(`No transition found for event: ${event} in state: ${this.state.currentState}`);
+    }
+    if (data) {
+      this.state.context = { ...this.state.context, ...data };
+    }
+    let targetState;
+    if (typeof transition === "string") {
+      targetState = transition;
+    } else {
+      const conditionalTransition = transition;
+      if (conditionalTransition.cond && !conditionalTransition.cond(this.state.context)) {
+        throw new Error(`Condition not met for transition to: ${conditionalTransition.target}`);
+      }
+      targetState = conditionalTransition.target;
+    }
+    const validation = Validator.validatePath(
+      this.state.currentState,
+      this.state.context,
+      this.schema
+    );
+    if (!validation.valid) {
+      this.emit("validationError", { errors: validation.errors });
+      if (this.options.onError) {
+        this.options.onError(new Error(validation.errors.join(", ")));
+      }
+      return;
+    }
+    const previousState = this.state.currentState;
+    this.state.completedSteps.add(previousState);
+    this.state.history.push(previousState);
+    this.state.currentState = targetState;
+    if (this.storage) {
+      await this.storage.save(this.state);
+    }
+    const stepChangeEvent = {
+      from: previousState,
+      to: targetState,
+      context: this.state.context
+    };
+    this.emit("stepChange", stepChangeEvent);
+    if (this.options.onStepChange) {
+      this.options.onStepChange(stepChangeEvent);
+    }
+    const targetStateConfig = this.schema.states[targetState];
+    if (!targetStateConfig?.on || Object.keys(targetStateConfig.on).length === 0) {
+      this.emit("complete", { context: this.state.context });
+      if (this.options.onComplete) {
+        this.options.onComplete(this.state.context);
+      }
+    }
+  }
+  /**
+   * Go back to the previous state
+   */
+  async back() {
+    if (this.state.history.length === 0) {
+      throw new Error("Cannot go back: no history available");
+    }
+    const previousState = this.state.history.pop();
+    this.state.completedSteps.delete(this.state.currentState);
+    const currentState = this.state.currentState;
+    this.state.currentState = previousState;
+    if (this.storage) {
+      await this.storage.save(this.state);
+    }
+    this.emit("stepChange", {
+      from: currentState,
+      to: previousState,
+      context: this.state.context
+    });
+  }
+  /**
+   * Update context without transitioning
+   */
+  async updateContext(data) {
+    this.state.context = { ...this.state.context, ...data };
+    if (this.storage) {
+      await this.storage.save(this.state);
+    }
+    this.emit("contextUpdate", { context: this.state.context });
+  }
+  /**
+   * Get current progress percentage
+   */
+  getProgress() {
+    return PathCalculator.calculateProgress(
+      this.state.currentState,
+      this.state.completedSteps,
+      this.schema
+    );
+  }
+  /**
+   * Get current state
+   */
+  getCurrentState() {
+    return this.state.currentState;
+  }
+  /**
+   * Get current context
+   */
+  getContext() {
+    return { ...this.state.context };
+  }
+  /**
+   * Get possible next states
+   */
+  getPossibleNextStates() {
+    const currentStateConfig = this.schema.states[this.state.currentState];
+    if (!currentStateConfig?.on) {
+      return [];
+    }
+    return Object.values(currentStateConfig.on).map(
+      (transition) => typeof transition === "string" ? transition : transition.target
+    );
+  }
+  /**
+   * Reset the form
+   */
+  async reset() {
+    this.state = {
+      currentState: this.schema.initial,
+      context: this.schema.context || {},
+      history: [],
+      completedSteps: /* @__PURE__ */ new Set()
+    };
+    if (this.storage) {
+      await this.storage.clear();
+    }
+    this.emit("reset", {});
+  }
+  /**
+   * Event emitter
+   */
+  on(event, callback) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(callback);
+  }
+  /**
+   * Remove event listener
+   */
+  off(event, callback) {
+    const callbacks = this.listeners.get(event);
+    if (callbacks) {
+      callbacks.delete(callback);
+    }
+  }
+  /**
+   * Emit event
+   */
+  emit(event, data) {
+    const callbacks = this.listeners.get(event);
+    if (callbacks) {
+      callbacks.forEach((callback) => callback(data));
+    }
+  }
+  /**
+   * Get all possible paths from current state
+   */
+  getPossiblePaths() {
+    return PathCalculator.getPossiblePaths(
+      this.state.currentState,
+      this.schema,
+      this.state.context
+    );
+  }
+  /**
+   * Check if we can go back
+   */
+  canGoBack() {
+    return this.state.history.length > 0;
+  }
+  /**
+   * Get the full state (for debugging)
+   */
+  getState() {
+    return {
+      ...this.state,
+      completedSteps: new Set(this.state.completedSteps)
+    };
+  }
+};
+export {
+  FormEngine,
+  PathCalculator,
+  StorageAdapter,
+  Validator
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+    "name": "react-form-atlas-engine",
+    "version": "1.1.0",
+    "description": "Framework-agnostic graph-based form engine",
+    "main": "./dist/index.js",
+    "module": "./dist/index.mjs",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "require": "./dist/index.js",
+            "import": "./dist/index.mjs",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsup src/index.ts --format cjs,esm --dts",
+        "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+        "test": "vitest",
+        "test:coverage": "vitest --coverage"
+    },
+    "keywords": [
+        "forms",
+        "state-machine",
+        "graph",
+        "branching-logic",
+        "multi-step-forms"
+    ],
+    "author": "Mehul Birare",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/Mehulbirare/react-form.git",
+        "directory": "packages/core"
+    },
+    "license": "MIT",
+    "devDependencies": {
+        "tsup": "^8.0.1",
+        "typescript": "^5.3.3",
+        "vitest": "^1.2.0"
+    },
+    "dependencies": {
+        "idb-keyval": "^6.2.1"
+    }
+}