Introduction

Raven Form Engine is a schema-driven, adapter-based React form engine that lets you build complex forms without committing to a specific UI component library or form-state management library.

Core Philosophy

The engine is split into three independent layers:

┌─────────────────────────────────────────────────────┐
│                   Your Application                   │
│                                                     │
│   <RavenForm schema={...} onSubmit={...} />         │
└──────────────────────┬──────────────────────────────┘
                       │
       ┌───────────────┼───────────────┐
       ▼               ▼               ▼
  ┌─────────┐   ┌───────────┐   ┌──────────────┐
  │  Schema  │   │ FormAdapter│   │  UIAdapter   │
  │  (JSON)  │   │  (RHF,    │   │ (ShadCN,     │
  │          │   │  Formik,  │   │  AntD,       │
  │          │   │  Zustand) │   │  MUI, …)     │
  └─────────┘   └───────────┘   └──────────────┘

Layer	Responsibility
Schema	Declarative field definitions — type, label, validation, visibility, layout
FormAdapter	Manages form state (dirty, touched, errors, submission)
UIAdapter	Maps field types to actual UI components

Key Features

• 🏗️ Schema-driven — define your entire form as a plain JS/JSON object
• 🔌 Adapter-based — swap UI libs and state libs without changing your form schema
• 🪜 Wizard forms — built-in multi-step forms with step validation
• 🔁 Repeater fields — dynamic rows of sub-fields
• 🎭 Conditional fields — hidden and disabled can be functions of form values
• ✅ Validation — sync and async validators, with React Hook Form support
• 🎭 Masking — composable mask pipeline
• 🛠 DevTools — floating panel with live form state inspection

Architecture Diagram

RavenFormProvider
├── UIAdapterContext       → provides UIAdapter to all children
├── FormAdapterContext     → provides FormAdapter to all children
└── RavenAdapterRegistry  → optional multi-adapter registry

RavenForm
├── FormAdapter.Provider  → initialises form state
│   ├── RavenField        → field.type → UIAdapter.components[type]
│   ├── RavenField
│   └── ...
└── Submit / Reset buttons

RavenWizardForm
├── FormAdapter.Provider  → single state across all steps
│   ├── Step 1..N
│   │   └── RavenField[]
│   └── Progress bar + Prev/Next navigation
└── Submit button (last step only)

What's Included

• RavenForm — single-page form
• RavenWizardForm — multi-step wizard form
• RavenRepeaterField — dynamic repeating field groups
• RavenFormProvider / RavenDevToolsProvider — app-level adapter injection
• Built-in adapters: React Hook Form, ShadCN UI, Ant Design
• Utilities: createUIAdapter, createFormAdapter, mask engine, validators

---

🚀 See It In Action

The Advanced Demo page shows full real-world scenarios — a 5-step wizard, conditional fields, cross-field validation, and repeater line items — all with live DevTools:

🚀  Open Advanced Demo