extended-dynamic-forms 0.1.17 → 0.1.18

package/README.md

@@ -1,44 +1,228 @@
 # Extended Dynamic Forms
 
-A comprehensive extension of React JSON Schema Form (RJSF) v6 with Ant Design components, custom widgets, fields, layouts, and a powerful central event orchestration system with webhook capabilities.
-
-## Features
-
-- 🎨 **Ant Design Integration**: Built on @rjsf/antd with modern, accessible components
-- ✨ **Enhanced Widgets**: Color picker, date picker, file upload, range slider, rating widget, enhanced input controls
-- 🏗️ **Custom Fields**: Address, phone number, currency input with formatting
-- 🧙‍♂️ **Wizard Forms**: Multi-step forms with automatic step detection, progress tracking, and navigation
-- 🎯 **Central Event Orchestration**: Unified system capturing all form field events (focus, blur, change)
-- 🔗 **Webhook Integration**: Configure multiple webhook endpoints with debouncing and retry logic
-- 🎭 **Advanced Conditional Logic**: Dynamic form behavior with JSON Rules Engine support and step-aware processing
-- 🔧 **Enhanced Form Events**: Before/after submit and validation hooks plus field-level events
-- 📦 **TypeScript Support**: Fully typed with comprehensive type definitions
-- ⚡ **Vite Powered**: Fast development and optimized builds
-- 🛡️ **Error Handling**: Robust error recovery and retry mechanisms
-- ⚡ **Performance Optimized**: Debouncing, queuing, and async processing
+**A revolutionary extension library for [React JSON Schema Form (RJSF)](https://github.com/rjsf-team/react-jsonschema-form)** that transforms schema-driven forms into sophisticated, enterprise-ready applications with O(N) performance and professional UI components.
+
+Built on top of the excellent RJSF v6 foundation, this library introduces the **Three Pillars v2 Architecture** for conditional logic, multi-step wizard orchestration, central event systems with webhook integration, and a comprehensive suite of 25+ Ant Design components. 
+
+[![npm version](https://img.shields.io/npm/v/extended-dynamic-forms.svg)](https://www.npmjs.com/package/extended-dynamic-forms)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/user/extended-dynamic-forms/blob/main/LICENSE)
+[![Built on RJSF](https://img.shields.io/badge/built%20on-RJSF%20v6-brightgreen)](https://github.com/rjsf-team/react-jsonschema-form)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![Standalone JS](https://img.shields.io/badge/Vanilla%20JS-Supported-orange.svg)](#standalone-javascript-support)
+
+## Why Extended Dynamic Forms?
+
+While [RJSF](https://github.com/rjsf-team/react-jsonschema-form) provides an excellent foundation for generating forms from JSON Schema, enterprise applications demand more sophisticated capabilities:
+
+### 🚀 **Performance Revolution**
+- **O(N) Conditional Logic**: Advanced Three Pillars v2 architecture vs traditional O(M×N) systems
+- **Optimized Array Processing**: Per-item evaluation with dynamic array conditionals
+- **Memory Efficient**: Immutable schema processing with intelligent caching
+
+### 🎯 **Enterprise-Grade Features**
+- **Complex Conditional Logic**: Multi-field dependencies, nested conditions, and dynamic validation
+- **Multi-Step Workflows**: Automatic wizard detection with step-aware conditional logic
+- **Real-Time Integration**: Production-ready webhooks with retry logic and error isolation
+- **Professional UI**: Comprehensive suite of enhanced Ant Design components with consistent styling
+
+### 🔄 **Developer Experience**
+- **Dual Architecture Support**: Modern React hooks + vanilla JavaScript compatibility
+- **Type-Safe Throughout**: Comprehensive TypeScript interfaces and validation
+- **Rich Ecosystem**: Interactive playground with comprehensive real-world demos
+- **Migration Ready**: Automated v1-to-v2 conversion utilities
+
+This library transforms RJSF from a simple form generator into a complete enterprise form solution while preserving its declarative approach.
+
+## Core Features
+
+### 🚀 Three Pillars v2 Architecture (Recommended)
+- **UI Logic Pillar**: Control form appearance with JSON Patch operations
+- **Schema Logic Pillar**: Modify data structure when truly needed
+- **Validation Logic Pillar**: Dynamic validation rules without schema changes
+- **O(N) Performance**: Superior array handling vs v1's O(M×N)
+- **React Hooks**: Modern, declarative API with `useConditionalUi`, `useConditionalSchema`, `useConditionalValidation`
+
+### 🎯 Declarative Conditional Logic
+- Define complex form behavior without code
+- Dynamic array support with per-item evaluation
+- Compatible with `json-rules-engine` format
+- Built-in migration utilities from v1 to v2
+
+For example, you can integrate existing business logic:
+
+```tsx
+import { engine } from './rules-engine'; // Your configured json-rules-engine instance
+
+const uiRules: UiRule[] = [{
+  name: 'Apply business logic for premium users',
+  // The condition can be a promise-based async function
+  condition: async (formData) => {
+    const { events } = await engine.run(formData);
+    return events.some(event => event.type === 'show-premium-feature');
+  },
+  effect: [...]
+}];
+```
+
+### 🧙‍♂️ Multi-Step Wizard Forms 
+- Automatic step detection from schema structure
+- Step-aware conditional logic
+- Built-in progress indicators and navigation
+- Per-step validation
+
+**Step-Aware Conditional Logic**
+
+The `WizardForm` automatically scopes conditional logic to the current step. Use v2 `UiRule`s with field prefixes:
+
+```tsx
+// Define steps with prefixed field names to avoid collisions
+const schema = {
+  type: 'object',
+  properties: {
+    STEP_PERSONAL: {
+      type: 'object',
+      title: 'Personal Information',
+      properties: {
+        isUSCitizen: { type: 'boolean', title: 'Are you a US Citizen?' },
+        ssn: { type: 'string', title: 'Social Security Number' }
+      }
+    }
+    // ... other steps
+  }
+};
+
+// Use v2 UiRules to handle step-aware conditionals
+const uiRules: UiRule[] = [{
+  name: 'Show SSN only for US Citizens in Personal step',
+  condition: (formData) => !formData.STEP_PERSONAL?.isUSCitizen,
+  effect: [
+    { op: 'add', path: '/STEP_PERSONAL/properties/ssn/ui:widget', value: 'hidden' }
+  ]
+}];
+
+// The WizardForm handles the step isolation automatically
+```
+
+### 🔗 Central Event Orchestration
+- Unified event system for all field interactions
+- Webhook integration with retry logic
+- Real-time form analytics capabilities
+- Debounced event processing
+
+### 🎨 Ant Design Components
+- Complete widget suite built with Ant Design v5
+- Enhanced standard widgets with event integration
+- Custom widgets: Rating, Color Picker, Range Slider
+- Professional field components: Address, Phone, Currency
+
+### ⚡ Form Lifecycle Hooks
+- Intercept and modify form data at key stages
+- `beforeSubmit`, `afterSubmit`, `beforeValidation`, `afterValidation`
+- Ideal for data transformation, logging, or triggering side effects
+
+### 📦 Additional Features
+- **TypeScript**: Full type safety and IntelliSense with comprehensive interface definitions
+- **Performance**: Optimized re-renders and memoization with intelligent caching
+- **Extensible**: Add custom widgets, fields, and actions with clean APIs
+- **Well-Tested**: Extensive test suite covering all major features and edge cases
+- **Developer Experience**: Interactive playground with dozens of real-world demos
+
+### 🌐 Standalone JavaScript Support
+
+**Complete vanilla JavaScript compatibility** with a production-ready UMD bundle that includes React, Ant Design, and all dependencies:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script src="https://unpkg.com/extended-dynamic-forms/dist/standalone.umd.js"></script>
+  <link rel="stylesheet" href="https://unpkg.com/extended-dynamic-forms/dist/style.css">
+</head>
+<body>
+  <div id="form-container"></div>
+  
+  <script>
+    const { createForm, createWizard } = ExtendedDynamicForms;
+    
+    // Create a complete form without React knowledge
+    const form = createForm({
+      schema: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', title: 'Full Name' },
+          email: { type: 'string', format: 'email', title: 'Email' }
+        }
+      },
+      container: document.getElementById('form-container'),
+      onSubmit: (data) => console.log('Form submitted:', data)
+    });
+  </script>
+</body>
+</html>
+```
+
+**Perfect for:**
+- WordPress/Drupal integrations
+- Legacy applications
+- CMS form builders
+- No-build environments
+- PHP/ASP.NET applications
+
+## Credits & Acknowledgments
+
+This library is built on top of [React JSON Schema Form (RJSF)](https://github.com/rjsf-team/react-jsonschema-form), an amazing open-source project that provides the core form generation engine. We extend RJSF's capabilities while maintaining full compatibility with its ecosystem.
+
+Special thanks to the RJSF team and contributors for creating such a flexible and well-architected foundation.
 
 ## Installation
 
+### React Projects
+
 ```bash
 npm install extended-dynamic-forms
 # or
 yarn add extended-dynamic-forms
+# or
+pnpm add extended-dynamic-forms
+```
+
+### Standalone JavaScript (No Build Required)
+
+```html
+<!-- Production CDN -->
+<script src="https://unpkg.com/extended-dynamic-forms@latest/dist/standalone.umd.js"></script>
+<link rel="stylesheet" href="https://unpkg.com/extended-dynamic-forms@latest/dist/style.css">
+
+<!-- Or download and host locally -->
+<script src="./path/to/extended-dynamic-forms-standalone.js"></script>
 ```
 
 ### Peer Dependencies
 
-This package requires the following peer dependencies:
+**Current Version**: `0.1.17` - Optimized for **RJSF v6** with Three Pillars v2 architecture.
 
 ```json
 {
   "react": "^18.0.0",
   "react-dom": "^18.0.0",
-  "@rjsf/core": "^5.0.0 || ^6.0.0-beta.10",
-  "@rjsf/utils": "^5.0.0 || ^6.0.0-beta.10",
-  "@rjsf/validator-ajv8": "^5.0.0 || ^6.0.0-beta.10"
+  "antd": "^5.24.0"
 }
 ```
 
+**RJSF Dependencies** (automatically handled):
+- `@rjsf/core`: ^6.0.0+
+- `@rjsf/utils`: ^6.0.0+ 
+- `@rjsf/validator-ajv8`: ^6.0.0+
+- `@rjsf/antd`: ^6.0.0+
+
+> **Development Note**: This library is currently developed against RJSF v6 and includes all necessary RJSF dependencies. No additional RJSF packages need to be installed separately.
+
+**Additional Dependencies**:
+- `dayjs`: ^1.11.13 (Date handling)
+- `json-rules-engine-simplified`: ^0.2.0 (v1 conditional logic)
+
+> **Note**: This library is specifically built for RJSF v6 to leverage the latest performance improvements and API enhancements. All examples and documentation assume RJSF v6.
+
 ## Setup
 
 ### CSS Requirements
@@ -50,73 +234,364 @@ This package uses Ant Design components. Import the CSS in your application:
 import 'extended-dynamic-forms/dist/style.css'; // Or your specific CSS entry point
 ```
 
+### Theming & Customization
+
+Since Extended Dynamic Forms uses Ant Design components, you can customize the appearance using Ant Design's powerful theming system:
+
+```tsx
+import { ConfigProvider, theme } from 'antd';
+import { ExtendedForm, WizardForm } from 'extended-dynamic-forms';
+
+function App() {
+  return (
+    <ConfigProvider
+      theme={{
+        token: {
+          colorPrimary: '#00b96b',
+          borderRadius: 8,
+          fontSize: 16,
+        },
+        algorithm: theme.darkAlgorithm, // Optional: Use dark theme
+      }}
+    >
+      <WizardForm 
+        schema={schema} 
+        uiSchema={uiSchema}
+        conditionals={conditionals}
+      />
+    </ConfigProvider>
+  );
+}
+```
+
+## Three Pillars v2 Architecture (Recommended Approach)
+
+> ⚠️ **IMPORTANT**: The v1 conditional system is deprecated. We strongly recommend using the Three Pillars v2 architecture for all new implementations.
+
+The Three Pillars v2 system provides superior performance, cleaner separation of concerns, and better maintainability. It consists of three independent pillars:
+
+### 1. UI Logic Pillar (`useConditionalUi`)
+
+Controls form appearance using JSON Patch operations:
+
+```tsx
+// Note: v2 conditionals require deep import for optimal tree-shaking
+import { useConditionalUi, UiRule } from 'extended-dynamic-forms/conditionals/v2';
+
+// Define UI rules with JSON Patch operations
+const uiRules: UiRule[] = [
+  {
+    name: 'Show shipping address when required',
+    condition: (formData) => formData.requiresShipping === true,
+    effect: [{ op: 'remove', path: '/shippingAddress/ui:widget' }],
+    order: 1
+  },
+  {
+    name: 'Dynamic country fields',
+    condition: (formData) => formData.shippingAddress?.country === 'USA',
+    effect: [
+      { op: 'remove', path: '/shippingAddress/state/ui:widget' },
+      { op: 'add', path: '/shippingAddress/province/ui:widget', value: 'hidden' }
+    ],
+    order: 2
+  }
+];
+
+const baseUiSchema = {
+  shippingAddress: {
+    'ui:widget': 'hidden', // Initially hidden
+    state: { 'ui:widget': 'text' },
+    province: { 'ui:widget': 'hidden' } // Initially hidden
+  }
+};
+
+// In your component
+function MyForm() {
+  const [formData, setFormData] = useState({});
+  
+  // IMPORTANT: Define rules outside render or memoize them!
+  const conditionalUiSchema = useConditionalUi(uiRules, baseUiSchema, formData);
+  
+  return (
+    <ExtendedForm
+      schema={schema}
+      uiSchema={conditionalUiSchema}
+      formData={formData}
+      onChange={({ formData }) => setFormData(formData)}
+    />
+  );
+}
+```
+
+### 2. Schema Logic Pillar (`useConditionalSchema`)
+
+Modifies JSON Schema structure (use sparingly - prefer UI or Validation pillars):
+
+```tsx
+import { useConditionalSchema, SchemaRule } from 'extended-dynamic-forms/conditionals/v2';
+
+const schemaRules: SchemaRule[] = [
+  {
+    name: 'Add premium fields',
+    condition: (formData) => formData.accountType === 'premium',
+    effect: [
+      { 
+        op: 'add', 
+        path: '/properties/premiumFeatures',
+        value: {
+          type: 'object',
+          properties: {
+            priority: { type: 'string', enum: ['high', 'medium', 'low'] }
+          }
+        }
+      }
+    ]
+  }
+];
+
+const conditionalSchema = useConditionalSchema(schemaRules, baseSchema, formData);
+```
+
+### 3. Validation Logic Pillar (`useConditionalValidation`)
+
+Adds conditional validation without modifying schema:
+
+```tsx
+import { useMemo } from 'react';
+import { useConditionalValidation, ValidationRule, createCustomValidate } from 'extended-dynamic-forms/conditionals/v2';
+
+const validationRules: ValidationRule[] = [
+  {
+    name: 'Require consent for minors',
+    condition: (formData) => formData.age < 18,
+    effect: {
+      type: 'validation',
+      validate: (errors, formData) => {
+        if (!formData.parentConsent) {
+          errors.parentConsent.addError('Parent consent is required for minors');
+        }
+      }
+    }
+  }
+];
+
+// In your component
+function MyForm({ schema }) {
+  const [formData, setFormData] = useState({});
+  
+  // 1. Get the conditional validation configuration
+  const conditionalValidationConfig = useConditionalValidation(validationRules, {}, formData);
+  
+  // 2. Create the memoized validate function
+  const customValidate = useMemo(
+    () => createCustomValidate(conditionalValidationConfig),
+    [conditionalValidationConfig]
+  );
+  
+  // 3. Use with ExtendedForm
+  return (
+    <ExtendedForm
+      schema={schema}
+      formData={formData}
+      onChange={({ formData }) => setFormData(formData)}
+      customValidate={customValidate}
+    />
+  );
+}
+```
+
+### Dynamic Arrays with O(N) Performance
+
+#### **The Performance Revolution: `createDynamicArrayItemsUiSchema`**
+
+One of the most significant breakthroughs in v2 is the `createDynamicArrayItemsUiSchema` function, which enables **true O(N) performance** for array conditionals. This is a fundamental improvement over traditional form libraries that struggle with dynamic array logic.
+
+**How It Works:**
+- **Per-Item Evaluation**: Each array item's conditionals are evaluated independently during render
+- **No Rule Explosion**: Unlike v1's wildcard expansion, no rules are multiplied by array size
+- **React-Optimized**: Leverages React's rendering cycle for optimal performance
+
+```tsx
+import { createDynamicArrayItemsUiSchema } from 'extended-dynamic-forms/conditionals/v2';
+
+// Define per-item conditional logic - this function runs for each array item
+const directorItemConditions = (director, index) => ({
+  shareholdingPercentage: {
+    'ui:widget': director.hasShareholding ? 'percentage' : 'hidden'
+  },
+  tfn: {
+    'ui:widget': director.isAustralianResident ? 'text' : 'hidden'
+  },
+  passport: {
+    'ui:widget': !director.isAustralianResident ? 'text' : 'hidden'
+  },
+  // Add visual indicator for the chairman
+  'ui:classNames': index === 0 ? 'chairman-director' : 'regular-director'
+});
+
+// Apply to your array field
+const uiSchema = {
+  directors: {
+    'ui:title': 'Company Directors',
+    'ui:description': 'Add all company directors and their details',
+    items: createDynamicArrayItemsUiSchema(directorItemConditions)
+  }
+};
+```
+
+**Performance Comparison:**
+```typescript
+// ❌ Traditional approach: O(M×N) - Rules × Array Items
+// With 10 rules and 50 directors = 500 evaluations
+
+// ✅ v2 approach: O(N) - Per-item evaluation  
+// With 50 directors = 50 evaluations (regardless of rule complexity)
+```
+
+**Advanced Patterns:**
+```tsx
+// Complex business logic with multiple conditions
+const productItemConditions = (product, index) => {
+  const baseConfig = {
+    price: { 'ui:widget': 'currency' },
+    quantity: { 'ui:widget': 'number' }
+  };
+
+  // Category-specific fields
+  if (product.category === 'software') {
+    baseConfig.licenseType = { 'ui:widget': 'select' };
+    baseConfig.maintenancePeriod = { 'ui:widget': 'hidden' };
+  }
+
+  // Subscription-specific logic
+  if (product.billingType === 'subscription') {
+    baseConfig.recurringPrice = { 'ui:widget': 'currency' };
+    baseConfig.billingCycle = { 'ui:widget': 'select' };
+  }
+
+  return baseConfig;
+};
+```
+
+### Performance Best Practices
+
+> ⚠️ **Critical**: Always define rules and base schemas outside render or memoize them!
+
+```tsx
+// ❌ BAD - Creates new objects every render
+function MyForm() {
+  const conditionalUiSchema = useConditionalUi(
+    [{ condition: () => true, effect: [...] }],  // New array every render!
+    { field: { 'ui:widget': 'text' } },           // New object every render!
+    formData
+  );
+}
+
+// ✅ GOOD - Stable references
+const rules = [{ condition: () => true, effect: [...] }];
+const baseUiSchema = { field: { 'ui:widget': 'text' } };
+
+function MyForm() {
+  const conditionalUiSchema = useConditionalUi(rules, baseUiSchema, formData);
+}
+```
+
+### Migration from v1 to v2
+
+```tsx
+import { 
+  migrateV1ToUiRules, 
+  generateMigrationReport,
+  analyzeRules 
+} from 'extended-dynamic-forms/conditionals/v2';
+
+// Analyze existing rules
+const analysis = analyzeRules(v1Rules);
+
+// Auto-migrate UI rules
+const { rules: migratedRules, report } = migrateV1ToUiRules(v1Rules);
+
+// Generate detailed migration report
+const migrationReport = generateMigrationReport(v1Rules, {
+  includeExamples: true,
+  outputFormat: 'markdown'
+});
+```
+
 ## Quick Start
 
 ### Simple Wizard Form (Recommended)
 
-The `WizardForm` component automatically detects multi-step forms and handles navigation:
+The `WizardForm` component automatically detects multi-step forms and handles navigation. Use it with Three Pillars v2:
 
 ```tsx
+import { useState } from 'react';
 import { WizardForm } from 'extended-dynamic-forms';
+import { useConditionalUi, UiRule } from 'extended-dynamic-forms/conditionals/v2';
 import schema from './schema.json';
-import uiSchema from './ui-schema.json';
-import conditions from './conditions.json';
+import baseUiSchema from './ui-schema.json';
+import uiRules from './ui-rules'; // Your v2 UI rules
 import webhooks from './webhooks.json';
 
 function App() {
+  const [formData, setFormData] = useState({});
+  const conditionalUiSchema = useConditionalUi(uiRules, baseUiSchema, formData);
+
   return (
     <WizardForm
       schema={schema}
-      uiSchema={uiSchema}
-      conditions={conditions}
+      uiSchema={conditionalUiSchema}
+      formData={formData}
+      onChange={({ formData }) => setFormData(formData)}
       webhooks={webhooks}
-      onSubmit={(data) => console.log('Submitted:', data)}
+      onSubmit={(data) => console.log('Submitted:', data.formData)}
     />
   );
 }
 ```
 
-**WizardForm Features:**
-- ✅ Auto-detects wizard structure (properties starting with `STEP_`)
-- ✅ Creates progress tracking and navigation
-- ✅ Handles step-aware conditional logic
-- ✅ Manages form state and validation
-- ✅ Integrates webhooks for real-time events
-
-### Basic Form (Using ExtendedForm)
-
-For more control, use the `ExtendedForm` component directly:
+### Basic Form with Three Pillars v2
 
 ```tsx
 import { ExtendedForm } from 'extended-dynamic-forms';
+import { useConditionalUi, UiRule } from 'extended-dynamic-forms/conditionals/v2';
 
 const schema = {
   type: 'object',
   properties: {
-    name: { type: 'string', title: 'Name' },
-    email: { type: 'string', format: 'email', title: 'Email' },
-    rating: { type: 'number', title: 'Rating' },
-    favoriteColor: { type: 'string', title: 'Favorite Color' }
-  },
-  required: ['name', 'email']
+    isStudent: { type: 'boolean', title: 'Are you a student?' },
+    studentId: { type: 'string', title: 'Student ID' },
+    school: { type: 'string', title: 'School Name' }
+  }
 };
 
-const uiSchema = {
-  rating: {
-    'ui:widget': 'rating',
-    'ui:options': { max: 5 }
-  },
-  favoriteColor: {
-    'ui:widget': 'color'
-  }
+const baseUiSchema = {
+  studentId: { 'ui:widget': 'text' },
+  school: { 'ui:widget': 'text' }
 };
 
+// Define UI rules outside component
+const uiRules: UiRule[] = [
+  {
+    name: 'Show student fields when student',
+    condition: (formData) => !formData.isStudent,
+    effect: [
+      { op: 'add', path: '/studentId/ui:widget', value: 'hidden' },
+      { op: 'add', path: '/school/ui:widget', value: 'hidden' }
+    ]
+  }
+];
+
 function App() {
+  const [formData, setFormData] = useState({});
+  const conditionalUiSchema = useConditionalUi(uiRules, baseUiSchema, formData);
+  
   return (
     <ExtendedForm
       schema={schema}
-      uiSchema={uiSchema}
-      onSubmit={({ formData }) => console.log(formData)}
+      uiSchema={conditionalUiSchema}
+      formData={formData}
+      onChange={({ formData }) => setFormData(formData)}
     />
   );
 }
@@ -182,99 +657,12 @@ All standard RJSF widgets are enhanced with:
 - **Error States**: Proper error indication and messaging
 - **Accessibility**: Enhanced ARIA support
 
-## Custom Fields
-
-### Address Field
-```tsx
-const schema = {
-  homeAddress: {
-    type: 'object',
-    properties: {
-      street: { type: 'string' },
-      city: { type: 'string' },
-      state: { type: 'string' },
-      zip: { type: 'string' },
-      country: { type: 'string' }
-    }
-  }
-};
-
-const uiSchema = {
-  homeAddress: {
-    'ui:field': 'address'
-  }
-};
-```
-
-### Phone Field
-```tsx
-const uiSchema = {
-  phoneNumber: {
-    'ui:field': 'phone'
-  }
-};
-```
-
-### Currency Field
-```tsx
-const uiSchema = {
-  price: {
-    'ui:field': 'currency',
-    'ui:options': {
-      currency: 'EUR',
-      symbol: '€'
-    }
-  }
-};
-```
-
-## Array Fields
-
-The library provides Ant Design-styled array field templates with enhanced functionality:
-
-```tsx
-const schema = {
-  type: 'object',
-  properties: {
-    directors: {
-      type: 'array',
-      title: 'Company Directors',
-      items: {
-        type: 'object',
-        properties: {
-          firstName: { type: 'string', title: 'First Name' },
-          lastName: { type: 'string', title: 'Last Name' },
-          email: { type: 'string', format: 'email', title: 'Email' }
-        }
-      }
-    }
-  }
-};
-
-const uiSchema = {
-  directors: {
-    'ui:options': {
-      orderable: true,    // Enable move up/down buttons
-      addable: true,      // Enable add button
-      removable: true     // Enable remove button
-    }
-  }
-};
-```
-
-**Array Features:**
-- 🎨 **Ant Design Cards**: Clean, modern appearance
-- ➕ **Add Button**: Prominent "Add [Item]" button
-- 🗑️ **Remove Buttons**: Individual remove buttons for each item
-- 🔄 **Reordering**: Move items up/down with controls
-- 📱 **Responsive**: Mobile-friendly design
-
 ## Central Event Orchestration System
 
 ### Field-Level Event Handling
 
 ```tsx
-import { ExtendedForm, FormFieldEvent } from 'extended-dynamic-forms';
+import { ExtendedForm, type FormFieldEvent } from 'extended-dynamic-forms';
 
 <ExtendedForm
   schema={schema}
@@ -302,7 +690,7 @@ import { ExtendedForm, FormFieldEvent } from 'extended-dynamic-forms';
 Configure multiple webhook endpoints to receive real-time form events:
 
 ```tsx
-import { ExtendedForm, WebhookConfig } from 'extended-dynamic-forms';
+import { ExtendedForm, type WebhookConfig } from 'extended-dynamic-forms';
 
 const webhookConfigs: WebhookConfig[] = [
   {
@@ -326,190 +714,57 @@ const webhookConfigs: WebhookConfig[] = [
 />
 ```
 
-### Webhook Payload Structure
+## V1 Conditional System (Deprecated)
 
-```json
-{
-  "event": {
-    "eventType": "change",
-    "fieldId": "root_email",
-    "fieldValue": "user@example.com",
-    "schema": {
-      "type": "string",
-      "format": "email",
-      "title": "Email Address"
-    },
-    "formData": {
-      "email": "user@example.com",
-      "name": "John Doe"
-    },
-    "timestamp": 1678901234567,
-    "fieldPath": ["email"]
-  },
-  "timestamp": 1678901234567,
-  "source": "extended-dynamic-forms"
-}
-```
-
-## Advanced Conditional Logic System
+> ⚠️ **DEPRECATED**: The v1 conditional system is deprecated and will be removed in a future version. Use the Three Pillars v2 system for all new implementations.
 
-The library includes a comprehensive conditional logic system with support for JSON Rules Engine format and step-aware processing for wizard forms.
+The v1 system uses imperative engines with O(M×N) performance for arrays. While still functional, it has significant limitations compared to v2.
 
-### Basic Conditional Logic
+### Basic V1 Usage (Not Recommended)
 
 ```tsx
 import { ExtendedForm } from 'extended-dynamic-forms';
-import { smartTransformJsonRulesEngine } from 'extended-dynamic-forms';
 
-const conditions = [
-  {
-    conditions: {
-      isStudent: true
+const conditionals = {
+  rules: [
+    {
+      conditions: { isStudent: true },
+      event: { type: "require", params: { field: ["studentId", "school"] } }
     },
-    event: {
-      type: "show",
-      params: { field: ["studentId", "school"] }
+    {
+      conditions: { isStudent: false },
+      event: { type: "remove", params: { field: ["studentId", "school"] } }
     }
-  },
-  {
-    conditions: {
-      isStudent: false
-    },
-    event: {
-      type: "hide",
-      params: { field: ["studentId", "school"] }
-    }
-  }
-];
-
-// Transform JSON Rules Engine format to internal format
-const transformedRules = smartTransformJsonRulesEngine(conditions);
-
-const conditionalConfig = {
-  rules: transformedRules,
-  onSchemaChange: ({ schema, uiSchema }) => {
-    console.log('Schema updated:', { schema, uiSchema });
-  }
+  ]
 };
 
-<ExtendedForm 
+<ExtendedForm
   schema={schema}
   uiSchema={uiSchema}
-  conditionals={conditionalConfig}
-  onChange={handleChange}
+  conditionals={conditionals}
 />
 ```
 
-### Wizard Form with Step-Aware Conditionals
+### Why Migrate to v2?
 
-The `WizardForm` component automatically handles step-aware conditional processing:
-
-```tsx
-import { WizardForm } from 'extended-dynamic-forms';
-
-// Schema with step structure
-const wizardSchema = {
-  type: 'object',
-  properties: {
-    STEP_PERSONAL: {
-      type: 'object',
-      title: 'Personal Information',
-      properties: {
-        name: { type: 'string', title: 'Name' },
-        isStudent: { type: 'boolean', title: 'Are you a student?' },
-        studentId: { type: 'string', title: 'Student ID' }
-      }
-    },
-    STEP_CONTACT: {
-      type: 'object',
-      title: 'Contact Information',
-      properties: {
-        email: { type: 'string', format: 'email' },
-        phone: { type: 'string' }
-      }
-    }
-  }
-};
-
-// Conditions that reference step fields
-const stepConditions = [
-  {
-    conditions: {
-      "STEP_PERSONAL.isStudent": false
-    },
-    event: {
-      type: "hide",
-      params: { field: "STEP_PERSONAL.studentId" }
-    }
-  }
-];
-
-<WizardForm
-  schema={wizardSchema}
-  uiSchema={uiSchema}
-  conditions={stepConditions}
-  onSubmit={handleSubmit}
-/>
-```
-
-### Supported Conditional Actions
-The conditional engine directly supports the following actions (defined in `ConditionalActions.ts`):
-- `show` - Makes fields visible (adds them back to the schema if previously removed).
-- `remove` - Removes fields from the schema and uiSchema (effectively hides them).
-- `enable` / `disable` - Enable or disable fields.  
-- `require` / `optional` - Make fields required or optional.
-- `uiAppend` - Appends to existing uiSchema properties (e.g., concatenates classNames, merges `ui:order`).
-- `uiOverride` - Overrides specific uiSchema fields.
-- `uiReplace` - Replaces entire uiSchema sections.
-- Custom actions - Register your own conditional actions
-    
-**Note on `smartTransformJsonRulesEngine`:**
-When providing conditions in the JSON Rules Engine format (e.g., to `WizardForm` or by calling `smartTransformJsonRulesEngine` directly):
-- Input rules with `event.type: "show"` are typically converted into an internal `remove` action with *inverted* conditions.
-- Input rules with `event.type: "hide"` are converted into an internal `remove` action.
-- Input rules with `event.type: "required"` or `"optional"` are transformed into internal `require` or `optional` actions, respectively.
-
-### JSON Rules Engine Support
-
-The library includes transformation utilities for json-rules-engine format:
-
-```tsx
-import { smartTransformJsonRulesEngine } from 'extended-dynamic-forms';
-
-const jsonRulesEngineFormat = [
-  {
-    conditions: {
-      all: [
-        {
-          fact: "age",
-          operator: "greaterThanInclusive", 
-          value: 18
-        }
-      ]
-    },
-    event: {
-      type: "show",
-      params: { field: "driverLicense" }
-    }
-  }
-];
-
-// Automatically transforms operators and structure
-const internalRules = smartTransformJsonRulesEngine(jsonRulesEngineFormat);
-```
+- **Performance**: O(N) vs O(M×N) for arrays
+- **Maintainability**: Clear separation of concerns
+- **Type Safety**: Full TypeScript support
+- **Predictability**: No complex rule interactions
+- **Modern React**: Hooks-based architecture
 
 ## API Reference
 
 ### ExtendedFormProps
 
 ```typescript
-interface ExtendedFormProps extends FormProps {
+interface ExtendedFormProps<T = any, S extends RJSFSchema = RJSFSchema, F = any> extends FormProps<T, S, F> {
   // Standard RJSF props
-  schema: RJSFSchema;
-  uiSchema?: UiSchema;
-  formData?: any;
-  onSubmit?: (data: import('@rjsf/utils').IChangeEvent<any, RJSFSchema, any>, event?: React.FormEvent<HTMLFormElement>) => void;
-  onChange?: (data: any) => void;
+  schema: S;
+  uiSchema?: UiSchema<T, S, F>;
+  formData?: T;
+  onSubmit?: (data: IChangeEvent<T, S, F>, event?: React.FormEvent<HTMLFormElement>) => void;
+  onChange?: (data: IChangeEvent<T, S, F>) => void;
       
   // Field-level event handlers
   onFieldFocus?: (event: FormFieldEvent) => Promise<void> | void;
@@ -519,140 +774,327 @@ interface ExtendedFormProps extends FormProps {
   // Webhook configuration
   webhooks?: WebhookConfig[];
   
-  // Conditional logic
+  // Conditional logic (v1 - deprecated)
   conditionals?: ConditionalConfig;
   
   // Form lifecycle events
-  beforeSubmit?: (data: any) => Promise<any> | any;
-  afterSubmit?: (data: any) => Promise<void> | void;
-  beforeValidation?: (data: any) => Promise<any> | any;
-  afterValidation?: (data: any, errors: any) => Promise<void> | void;
+  beforeSubmit?: (data: T) => Promise<T> | T;
+  afterSubmit?: (data: T) => Promise<void> | void;
+  beforeValidation?: (data: T) => Promise<T> | T;
+  afterValidation?: (data: T, errors: RJSFValidationError[]) => Promise<void> | void;
 }
 ```
 
-### WizardFormProps
+### Three Pillars v2 Hooks
 
 ```typescript
-interface WizardFormProps {
-  // Required JSON configurations
-  schema: any;
-  uiSchema: any;
-  conditions?: any[];
-  webhooks?: WebhookConfig[];
+// UI Logic Pillar
+function useConditionalUi(
+  rules: UiRule[],
+  baseUiSchema: UiSchema,
+  formData: any
+): UiSchema
+
+// Schema Logic Pillar
+function useConditionalSchema(
+  rules: SchemaRule[],
+  baseSchema: RJSFSchema,
+  formData: any
+): RJSFSchema
+
+// Validation Logic Pillar
+function useConditionalValidation(
+  rules: ValidationRule[],
+  baseConfig: ValidationConfig,
+  formData: any
+): ValidationConfig
+```
 
-  // Optional initial data
-  formData?: any;
-
-  // Event handlers
-  onSubmit?: (data: any) => void;
-  onStepChange?: (step: number, data: any) => void;
-  onFieldFocus?: (event: any) => void;
-  onFieldBlur?: (event: any) => void;
-  onFieldChange?: (event: any) => void;
-
-  // UI customization
-  showProgressBar?: boolean;
-  showStepDescription?: boolean;
-  submitButtonText?: string;
-  liveValidate?: boolean;
-  showErrorList?: boolean;
-}
+## Real-World Use Cases
+
+### 🏢 Enterprise Business Applications
+
+**Australian Company Registration** (Featured Demo)
+```tsx
+// Complete 5-step wizard with dynamic conditionals
+const companyOnboardingSchema = {
+  STEP_COMPANY: { /* Company details */ },
+  STEP_DIRECTORS: { /* Dynamic director array */ },
+  STEP_ADDRESS: { /* Address with postal logic */ },
+  STEP_FINANCIAL: { /* Banking with international support */ },
+  STEP_COMPLIANCE: { /* Regulatory requirements */ }
+};
+
+// Per-director conditionals with O(N) performance
+const uiSchema = {
+  STEP_DIRECTORS: {
+    directors: {
+      items: createDynamicArrayItemsUiSchema((director) => ({
+        tfn: { 'ui:widget': director.isAustralianResident ? 'text' : 'hidden' },
+        passport: { 'ui:widget': !director.isAustralianResident ? 'text' : 'hidden' }
+      }))
+    }
+  }
+};
 ```
 
-### FormFieldEvent
+### 💼 Multi-Step Workflows
 
-```typescript
-interface FormFieldEvent {
-  eventType: 'focus' | 'blur' | 'change';
-  fieldId: string;
-  fieldValue: any;
-  schema?: any;
-  formData?: any;
-  timestamp: number;
-  fieldPath?: string[];
-}
+**Loan Applications**
+- Conditional document requirements based on loan type
+- Income verification with employment status logic
+- Asset declaration with property type conditionals
+
+**Employee Onboarding**
+- Role-based form sections (technical vs. non-technical)
+- Security clearance workflows
+- Benefits enrollment with eligibility rules
+
+**Grant Applications**
+- Multi-stage submissions with validation gates
+- Budget calculations with category-based rules
+- Compliance checks based on funding type
+
+### 🔄 Dynamic Array Management
+
+**Board of Directors Management**
+```tsx
+// Professional-grade array handling with O(N) performance
+import { createDynamicArrayItemsUiSchema } from 'extended-dynamic-forms';
+
+const uiSchema = {
+  STEP_DIRECTORS: {
+    directors: {
+      items: createDynamicArrayItemsUiSchema((director, index) => ({
+        shareholdingPercentage: { 
+          'ui:widget': director.hasShareholding ? 'percentage' : 'hidden' 
+        },
+        tfn: {
+          'ui:widget': director.isAustralianResident ? 'text' : 'hidden'
+        },
+        passport: {
+          'ui:widget': !director.isAustralianResident ? 'text' : 'hidden'
+        }
+      }))
+    }
+  }
+};
 ```
 
-### WebhookConfig
+**Product Configurations**
+- Dynamic product options based on category
+- Pricing calculations with quantity breaks
+- Feature availability by subscription tier
 
-```typescript
-interface WebhookConfig {
-  url: string;
-  method?: 'POST' | 'PUT' | 'PATCH';
-  headers?: Record<string, string>;
-  events?: ('focus' | 'blur' | 'change')[];
-  debounceMs?: number;
-  retries?: number;
-  timeout?: number;
-}
+**Address Management**
+- International vs. domestic address formats
+- State/province selection based on country
+- Postal code validation by region
+
+### 🌐 CMS & Integration Use Cases
+
+**WordPress/Drupal Forms**
+```html
+<!-- Standalone JavaScript integration -->
+<script>
+  const { createWizard } = ExtendedDynamicForms;
+  
+  createWizard({
+    schema: wpFormSchema,
+    container: '#wp-form-container',
+    onSubmit: (data) => {
+      // Submit to WordPress REST API
+      wp.apiRequest({ path: '/wp/v2/forms', method: 'POST', data });
+    }
+  });
+</script>
+```
+
+**Legacy System Modernization**
+- Drop-in replacement for static HTML forms
+- Progressive enhancement of existing forms
+- No-build deployment to production environments
+
+## Architecture
+
+Extended Dynamic Forms uses a layered architecture that cleanly extends RJSF:
+
+```
+┌─────────────────────────────────────────────────┐
+│     Three Pillars v2 (Conditional System)       │
+├─────────────────────────────────────────────────┤
+│          Application Layer (WizardForm)          │
+├─────────────────────────────────────────────────┤
+│      Event Layer (FormEventHub)                 │
+├─────────────────────────────────────────────────┤
+│   Component Layer (Widgets/Fields/Templates)    │
+├─────────────────────────────────────────────────┤
+│        Base Layer (@rjsf/antd)                  │
+└─────────────────────────────────────────────────┘
 ```
 
+## Feature Comparison
+
+| Feature | Basic RJSF | Extended Dynamic Forms |
+|---------|------------|----------------------|
+| **Form Generation** | ✅ JSON Schema | ✅ Enhanced JSON Schema |
+| **UI Components** | Basic HTML | ✅ Comprehensive Ant Design Suite |
+| **Conditional Logic** | ❌ Manual | ✅ Three Pillars v2 (O(N)) |
+| **Multi-Step Forms** | ❌ Manual | ✅ Automatic Wizard Detection |
+| **Event System** | Basic onChange | ✅ Central Event Orchestration |
+| **Webhook Integration** | ❌ None | ✅ Production-Ready with Retry |
+| **Array Conditionals** | ❌ None | ✅ Per-Item O(N) Performance |
+| **TypeScript** | Partial | ✅ Comprehensive Type Definitions |
+| **Standalone JS** | ❌ React Only | ✅ Complete UMD Bundle |
+| **Testing** | Basic | ✅ Extensive Test Coverage |
+| **Performance** | Standard | ✅ Optimized with Caching |
+| **Validation** | Basic | ✅ Dynamic + Custom Rules |
+| **Developer Tools** | Limited | ✅ Interactive Playground |
+
 ## Development
 
+### 🚀 Quick Start
+
 ```bash
-# Install dependencies
+# Clone and setup
+git clone https://github.com/user/extended-dynamic-forms.git
+cd extended-dynamic-forms
 npm install
 
-# Run development server
-npm run dev
+# Start development with playground
+npm run dev                    # Launches interactive playground
+npm run playground            # Alternative playground command
 
-# Build library
-npm run build
+# Development workflow
+npm run test                  # Run complete test suite
+npm run test:ui              # Visual test runner
+npm run lint                 # ESLint validation
+npm run format              # Prettier formatting
+```
 
-# Run tests
-npm test
+### 📦 Build Commands
 
-# Lint code
-npm run lint
+```bash
+# Library builds
+npm run build               # TypeScript + Vite library build
+npm run build:vanilla      # Standalone UMD bundle
+npm run build:all          # Both library and standalone
+
+# Production validation
+npm run preview            # Preview library build
+npm run serve:examples     # Serve vanilla JS examples
 ```
 
-## Examples
+### 🧪 Testing
 
-The library includes comprehensive examples demonstrating all features. Run the development server to see them:
+**Test Coverage**: Extensive test suite with focus on:
+- **Conditional Logic**: Comprehensive coverage for v1 and v2 systems
+- **Wizard Forms**: Step navigation and validation
+- **Performance**: Array conditional optimization
+- **Integration**: Component interaction testing
 
 ```bash
-npm run dev
+npm run test              # Run complete test suite
+npm run test -- --grep "conditional"  # Test conditional logic
+npm run test -- --grep "wizard"       # Test wizard forms
+npm run test -- --grep "array"        # Test array handling
+```
+
+### 🏗️ Architecture
+
+**Build Configuration**:
+- **Library**: ES + UMD via Vite with TypeScript declarations
+- **Standalone**: Complete UMD bundle with React/antd included
+- **External Dependencies**: React, antd marked as externals in library build
+- **Type Generation**: `vite-plugin-dts` for .d.ts files
+
+**File Structure**:
+```
+src/
+├── ExtendedForm.tsx          # Main form wrapper
+├── WizardForm.tsx           # Multi-step orchestrator
+├── conditionals/            # v1 + v2 conditional systems
+│   ├── v2/                 # Three Pillars architecture
+│   └── DynamicArrayConditionalEngine.ts
+├── events/                  # Central event orchestration
+├── widgets/                 # Enhanced component suite
+├── components/              # Field and template components
+└── utils/                   # Form manipulation utilities
 ```
 
-Key examples include:
+## Examples & Demos
 
-- **Simple Wizard Example**: Multi-step company onboarding form
-- **Conditional Logic Demo**: Dynamic field visibility and requirements
-- **Event System Demo**: Real-time form analytics and webhooks
-- **Custom Widget Showcase**: All available widgets and their options
+### 🎮 Interactive Playground
 
-## Use Cases
+The library includes a comprehensive **interactive playground** with extensive real-world demos demonstrating all features:
 
-### Real-time Form Analytics
-- Track user interactions and field completion rates
-- Monitor form abandonment points
-- Capture detailed user behavior data
+```bash
+# Run the playground locally
+npm run dev
+# or
+npm run playground
+```
 
-### Auto-save & Recovery
-- Automatically save form data as users type
-- Implement form recovery after page reload
-- Background data synchronization
+### 📚 Demo Categories
+
+#### **Three Pillars v2 Demonstrations**
+- **Global UI Rules**: Dynamic show/hide with JSON Patch operations
+- **Dynamic Array Items**: Per-item conditional logic with O(N) performance
+- **Conditional Validation**: Custom validation rules without schema changes
+- **Migration Examples**: Automated v1-to-v2 rule conversion
+
+#### **🧙‍♂️ Wizard Form Showcases**
+- **Australian Company Onboarding**: 5-step enterprise form with:
+  - Dynamic director arrays with per-item conditionals
+  - Real-time fee calculations based on business rules
+  - Complex validation (ABN/ACN numbers, postcodes)
+  - Step-aware conditional logic
+  - Professional business workflow
+
+#### **🔗 Event System Demos**
+- **Real-time Form Analytics**: Webhook integration with retry logic
+- **Field-Level Event Handling**: Focus/blur/change event orchestration
+- **Webhook Configuration**: Multiple endpoints with custom headers
+
+#### **🎨 Widget Showcase**
+- **Enhanced Standard Widgets**: All RJSF widgets with Ant Design styling
+- **Custom Widgets**: Color picker, rating, range slider, file upload
+- **Professional Fields**: Address, currency, phone number components
+
+### 📱 Vanilla JavaScript Examples
+
+Complete standalone examples in `/examples/vanilla-js/`:
+
+```html
+<!-- Basic Form -->
+basic-form.html          <!-- Simple contact form -->
+conditional-form.html    <!-- Dynamic field visibility -->
+wizard-form.html         <!-- Multi-step onboarding -->
+```
 
-### Dynamic Form Behavior
-- Show/hide fields based on user input
-- Change validation rules dynamically
-- Progressive form enhancement
+### 🔗 Live Demo Links
 
-### Multi-step Workflows
-- Complex onboarding processes
-- Survey and questionnaire systems
-- Application and registration forms
+- **[Playground](https://extended-dynamic-forms-playground.vercel.app)** - Interactive demo environment
+- **[Australian Company Onboarding](https://extended-dynamic-forms-playground.vercel.app/wizard/australian-company)** - Full enterprise form showcase
+- **[Three Pillars v2 Demo](https://extended-dynamic-forms-playground.vercel.app/conditionals/three-pillars)** - Modern conditional logic patterns
 
-## Architecture
+## Contributing
 
-The library is built on three core principles:
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
 
-1. **Wrapper Architecture**: Extends RJSF v6 without breaking existing functionality
-2. **Central Event Orchestration**: All form interactions flow through a unified event system
-3. **Conditional Logic Engine**: Dynamic schema transformations with comprehensive rule support
+## Community & Support
 
-For detailed architectural information, see the [Developer Guide](./DEVELOPER_GUIDE.md).
+- 📚 [Documentation](https://extended-dynamic-forms.dev)
+- 🐛 [Issue Tracker](https://github.com/user/extended-dynamic-forms/issues)
+- 💬 [Discussions](https://github.com/user/extended-dynamic-forms/discussions)
+- 📧 [Email Support](mailto:support@extended-dynamic-forms.dev)
 
 ## License
 
-MIT
+MIT © [Your Name/Organization]
+
+---
+
+<p align="center">
+  Built with ❤️ on top of <a href="https://github.com/rjsf-team/react-jsonschema-form">React JSON Schema Form</a>
+</p>