extended-dynamic-forms 0.1.15 → 0.1.18

package/README.md

@@ -1,318 +1,668 @@
 # Extended Dynamic Forms
 
-A comprehensive extension of React JSON Schema Form (RJSF) v5 with shadcn/ui components, custom widgets, fields, layouts, and a powerful central event orchestration system with webhook capabilities.
-
-## Features
-
-- 🎨 **shadcn/ui Integration**: Built on top of @rjsf/shadcn for beautiful, accessible components
-- ✨ **Custom Widgets**: Color picker, date picker, file upload, range slider, rating stars
-- 🏗️ **Custom Fields**: Address, phone number, currency input with formatting
-- 📐 **Layout Components**: Vertical, horizontal, and grid layouts
-- 🎯 **Central Event Orchestration**: Unified system capturing all form field events (focus, blur, change)
-- 🔗 **Webhook Integration**: Configure multiple webhook endpoints with debouncing and retry logic
-- 🔧 **Enhanced Form Events**: Before/after submit and validation hooks plus field-level events
-- 🚀 **Conditional Logic**: Show/hide fields, make fields required/optional based on complex conditions
-- 📦 **TypeScript Support**: Fully typed with comprehensive type definitions
-- ⚡ **Vite Powered**: Fast development and optimized builds
-- 🎯 **Tailwind CSS**: Utility-first styling with full customization
-- 🛡️ **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.15.0",
-  "@rjsf/utils": "^5.15.0",
-  "@rjsf/validator-ajv8": "^5.15.0",
-  "@rjsf/shadcn": "^0.1.0"
+  "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
 
-This package uses Tailwind CSS and shadcn/ui components. Make sure to include the required CSS in your application:
+This package uses Ant Design components. Import the CSS in your application:
 
 ```tsx
 // In your main entry file (e.g., App.tsx or index.tsx)
-import 'extended-dynamic-forms/dist/index.css';
+import 'extended-dynamic-forms/dist/style.css'; // Or your specific CSS entry point
 ```
 
-If you're using Tailwind CSS in your project, ensure your `tailwind.config.js` includes the package in the content array:
+### Theming & Customization
 
-```js
-module.exports = {
-  content: [
-    // ... your other content paths
-    "./node_modules/extended-dynamic-forms/**/*.{js,ts,jsx,tsx}",
-  ],
-  // ... rest of your config
+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>
+  );
 }
 ```
 
-## Quick Start
+## 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.
 
-### Basic Form
+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
-import React from 'react';
-import { ExtendedForm } from 'extended-dynamic-forms';
+// Note: v2 conditionals require deep import for optimal tree-shaking
+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' }
+// 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
   },
-  required: ['name', 'email']
-};
+  {
+    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 uiSchema = {
-  rating: {
-    'ui:widget': 'rating',
-    'ui:options': { max: 5 }
-  },
-  favoriteColor: {
-    'ui:widget': 'color'
+const baseUiSchema = {
+  shippingAddress: {
+    'ui:widget': 'hidden', // Initially hidden
+    state: { 'ui:widget': 'text' },
+    province: { 'ui:widget': 'hidden' } // Initially hidden
   }
 };
 
-function App() {
-  const handleSubmit = ({ formData }) => {
-    console.log('Form data:', formData);
-  };
-
-  const handleFieldChange = (event) => {
-    console.log(`Field ${event.fieldId} changed to:`, event.fieldValue);
-  };
-
+// 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={uiSchema}
-      onSubmit={handleSubmit}
-      onFieldChange={handleFieldChange}
+      uiSchema={conditionalUiSchema}
+      formData={formData}
+      onChange={({ formData }) => setFormData(formData)}
     />
   );
 }
 ```
 
-### With Webhook Integration
+### 2. Schema Logic Pillar (`useConditionalSchema`)
+
+Modifies JSON Schema structure (use sparingly - prefer UI or Validation pillars):
 
 ```tsx
-import React from 'react';
-import { ExtendedForm, WebhookConfig } from 'extended-dynamic-forms';
+import { useConditionalSchema, SchemaRule } from 'extended-dynamic-forms/conditionals/v2';
 
-const webhooks: WebhookConfig[] = [
+const schemaRules: SchemaRule[] = [
   {
-    url: 'https://your-api.com/webhooks/form-events',
-    events: ['change'],
-    debounceMs: 300,
-    headers: {
-      'Authorization': 'Bearer your-token'
+    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');
+        }
+      }
     }
   }
 ];
 
-function App() {
+// 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}
-      uiSchema={uiSchema}
-      webhooks={webhooks}
-      onSubmit={({ formData }) => {
-        console.log('Form submitted:', formData);
-      }}
-      onFieldFocus={(event) => {
-        console.log('Field focused:', event.fieldId);
-      }}
+      formData={formData}
+      onChange={({ formData }) => setFormData(formData)}
+      customValidate={customValidate}
     />
   );
 }
 ```
 
-## Custom Widgets
+### 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
 
-### Color Widget
 ```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 = {
-  favoriteColor: {
-    'ui:widget': 'color'
+  directors: {
+    'ui:title': 'Company Directors',
+    'ui:description': 'Add all company directors and their details',
+    items: createDynamicArrayItemsUiSchema(directorItemConditions)
   }
 };
 ```
 
-### Date Widget
-```tsx
-const uiSchema = {
-  birthDate: {
-    'ui:widget': 'date',
-    'ui:options': {
-      inputType: 'datetime-local', // or 'date', 'time'
-      minDate: '2000-01-01',
-      maxDate: '2025-12-31'
-    }
-  }
-};
+**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)
 ```
 
-### File Widget
+**Advanced Patterns:**
 ```tsx
-const uiSchema = {
-  documents: {
-    'ui:widget': 'file',
-    'ui:options': {
-      accept: '.pdf,.doc,.docx',
-      multiple: true
-    }
+// 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;
 };
 ```
 
-### Range Widget
+### Performance Best Practices
+
+> ⚠️ **Critical**: Always define rules and base schemas outside render or memoize them!
+
 ```tsx
-const schema = {
-  volume: {
-    type: 'number',
-    minimum: 0,
-    maximum: 100,
-    multipleOf: 5
-  }
-};
+// ❌ 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
+  );
+}
 
-const uiSchema = {
-  volume: {
-    'ui:widget': 'range'
-  }
-};
+// ✅ GOOD - Stable references
+const rules = [{ condition: () => true, effect: [...] }];
+const baseUiSchema = { field: { 'ui:widget': 'text' } };
+
+function MyForm() {
+  const conditionalUiSchema = useConditionalUi(rules, baseUiSchema, formData);
+}
 ```
 
-### Rating Widget
+### Migration from v1 to v2
+
 ```tsx
-const uiSchema = {
-  satisfaction: {
-    'ui:widget': 'rating',
-    'ui:options': {
-      max: 10 // default is 5
-    }
-  }
-};
+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'
+});
 ```
 
-## Custom Fields
+## Quick Start
+
+### Simple Wizard Form (Recommended)
+
+The `WizardForm` component automatically detects multi-step forms and handles navigation. Use it with Three Pillars v2:
 
-### Address Field
 ```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 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={conditionalUiSchema}
+      formData={formData}
+      onChange={({ formData }) => setFormData(formData)}
+      webhooks={webhooks}
+      onSubmit={(data) => console.log('Submitted:', data.formData)}
+    />
+  );
+}
+```
+
+### Basic Form with Three Pillars v2
+
+```tsx
+import { ExtendedForm } from 'extended-dynamic-forms';
+import { useConditionalUi, UiRule } from 'extended-dynamic-forms/conditionals/v2';
+
 const schema = {
-  homeAddress: {
-    type: 'object',
-    properties: {
-      street: { type: 'string' },
-      city: { type: 'string' },
-      state: { type: 'string' },
-      zip: { type: 'string' },
-      country: { type: 'string' }
-    }
+  type: 'object',
+  properties: {
+    isStudent: { type: 'boolean', title: 'Are you a student?' },
+    studentId: { type: 'string', title: 'Student ID' },
+    school: { type: 'string', title: 'School Name' }
   }
 };
 
-const uiSchema = {
-  homeAddress: {
-    'ui:field': 'address'
-  }
+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={conditionalUiSchema}
+      formData={formData}
+      onChange={({ formData }) => setFormData(formData)}
+    />
+  );
+}
 ```
 
-### Phone Field
+## Custom Widgets
+
+### Available Widgets
+
+The library includes enhanced versions of all standard RJSF widgets plus custom ones:
+
+#### Custom Widgets
+
 ```tsx
+// Color Picker
 const uiSchema = {
-  phoneNumber: {
-    'ui:field': 'phone'
+  favoriteColor: {
+    'ui:widget': 'color'
   }
 };
-```
 
-### Currency Field
-```tsx
+// Rating Widget
 const uiSchema = {
-  price: {
-    'ui:field': 'currency',
+  satisfaction: {
+    'ui:widget': 'rating',
     'ui:options': {
-      currency: 'EUR',
-      symbol: '€'
+      max: 10 // default is 5
     }
   }
 };
-```
-
-## Array Fields
-
-Extended Dynamic Forms provides custom-styled array field templates using shadcn/ui components. Arrays automatically get styled add/remove buttons, reordering controls, and proper visual hierarchy.
 
-### Basic Array Example
-```tsx
+// Range Slider
 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' }
-        }
-      }
-    }
+  volume: {
+    type: 'number',
+    minimum: 0,
+    maximum: 100
+  }
+};
+const uiSchema = {
+  volume: {
+    'ui:widget': 'range'
   }
 };
 
+// File Upload
 const uiSchema = {
-  directors: {
+  documents: {
+    'ui:widget': 'file',
     'ui:options': {
-      orderable: true,    // Enable move up/down buttons
-      addable: true,      // Enable add button
-      removable: true     // Enable remove button
+      accept: '.pdf,.doc,.docx',
+      multiple: true
     }
   }
 };
 ```
 
-### Array Features
-- 🎨 **Styled with shadcn/ui Card components**: Clean, modern appearance
-- ➕ **Add button**: Prominent "Add [Item]" button at the bottom
-- 🗑️ **Remove buttons**: Individual remove buttons for each item
-- 🔄 **Reordering**: Move items up/down with chevron buttons
-- 📱 **Responsive**: Mobile-friendly controls
+#### Enhanced Standard Widgets
 
-Arrays work seamlessly with all other custom widgets and fields in the library, including within nested structures.
+All standard RJSF widgets are enhanced with:
+- **Event Integration**: Automatic integration with the central event system
+- **Ant Design Styling**: Modern, consistent appearance
+- **Error States**: Proper error indication and messaging
+- **Accessibility**: Enhanced ARIA support
 
 ## Central Event Orchestration System
 
-The library features a comprehensive event orchestration system that captures all form field events and enables webhook integration.
-
 ### Field-Level Event Handling
 
 ```tsx
-import { ExtendedForm, FormFieldEvent } from 'extended-dynamic-forms';
+import { ExtendedForm, type FormFieldEvent } from 'extended-dynamic-forms';
 
 <ExtendedForm
   schema={schema}
@@ -322,29 +672,15 @@ import { ExtendedForm, FormFieldEvent } from 'extended-dynamic-forms';
   // Field-level event handlers
   onFieldFocus={(event: FormFieldEvent) => {
     console.log(`Field ${event.fieldId} focused:`, event.fieldValue);
-    // Track user interactions for analytics
   }}
   
   onFieldChange={(event: FormFieldEvent) => {
     console.log(`Field ${event.fieldId} changed:`, event.fieldValue);
     // Real-time validation or processing
-    if (event.fieldId === 'root_email') {
-      validateEmailRealTime(event.fieldValue);
-    }
   }}
   
   onFieldBlur={(event: FormFieldEvent) => {
     console.log(`Field ${event.fieldId} blurred:`, event.fieldValue);
-    // Format field values or trigger validation
-  }}
-  
-  // Traditional form-level events (still supported)
-  beforeSubmit={async (data) => {
-    return { ...data, timestamp: Date.now() };
-  }}
-  
-  afterSubmit={async (data) => {
-    console.log('Form submitted:', data);
   }}
 />
 ```
@@ -354,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[] = [
   {
@@ -366,17 +702,7 @@ const webhookConfigs: WebhookConfig[] = [
     timeout: 5000,               // 5 second timeout
     headers: {
       'Authorization': 'Bearer your-api-token',
-      'X-Form-ID': 'contact-form',
-      'Content-Type': 'application/json'
-    }
-  },
-  {
-    url: 'https://analytics.yourapp.com/field-interactions',
-    events: ['focus'],           // Track focus events for analytics
-    debounceMs: 0,              // No debouncing for real-time analytics
-    retries: 1,
-    headers: {
-      'X-Analytics-Key': 'your-analytics-key'
+      'X-Form-ID': 'contact-form'
     }
   }
 ];
@@ -385,408 +711,390 @@ const webhookConfigs: WebhookConfig[] = [
   schema={schema}
   uiSchema={uiSchema}
   webhooks={webhookConfigs}
-  
-  onFieldChange={(event) => {
-    // Local processing alongside webhooks
-    if (event.fieldId === 'root_email') {
-      setEmailValid(validateEmail(event.fieldValue));
-    }
-  }}
 />
 ```
 
-### Webhook Payload Structure
-
-Your webhook endpoints will receive payloads in this format:
-
-```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"
-}
-```
+## V1 Conditional System (Deprecated)
 
-### Advanced Features
+> ⚠️ **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.
 
-- **Debouncing**: Prevent webhook spam on rapid input changes
-- **Retry Logic**: Automatic retry with exponential backoff for failed requests
-- **Error Isolation**: Webhook failures don't block form functionality
-- **Event Filtering**: Configure which events trigger each webhook
-- **Queue Management**: Asynchronous processing with proper ordering
-- **Custom Headers**: Add authentication, tracking, or custom metadata
+The v1 system uses imperative engines with O(M×N) performance for arrays. While still functional, it has significant limitations compared to v2.
 
-## Layouts
+### Basic V1 Usage (Not Recommended)
 
 ```tsx
-import { VerticalLayout, HorizontalLayout, GridLayout } from 'extended-dynamic-forms';
-
-// Vertical Layout
-<VerticalLayout spacing="medium">
-  <input />
-  <button />
-</VerticalLayout>
+import { ExtendedForm } from 'extended-dynamic-forms';
 
-// Horizontal Layout
-<HorizontalLayout spacing="large" align="center">
-  <label />
-  <input />
-</HorizontalLayout>
+const conditionals = {
+  rules: [
+    {
+      conditions: { isStudent: true },
+      event: { type: "require", params: { field: ["studentId", "school"] } }
+    },
+    {
+      conditions: { isStudent: false },
+      event: { type: "remove", params: { field: ["studentId", "school"] } }
+    }
+  ]
+};
 
-// Grid Layout
-<GridLayout columns={3} gap="medium">
-  <Card />
-  <Card />
-  <Card />
-</GridLayout>
+<ExtendedForm
+  schema={schema}
+  uiSchema={uiSchema}
+  conditionals={conditionals}
+/>
 ```
 
-## Use Cases
+### Why Migrate to v2?
 
-### Real-time Form Analytics
-```tsx
-const webhooks: WebhookConfig[] = [
-  {
-    url: 'https://analytics.yourapp.com/form-interactions',
-    events: ['focus', 'blur', 'change'],
-    debounceMs: 100,
-    headers: { 'X-Analytics-Token': 'your-token' }
-  }
-];
+- **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
 
-// Track user behavior, field completion rates, abandonment points
-```
+## API Reference
 
-### Auto-save & Recovery
-```tsx
-<ExtendedForm
-  schema={schema}
-  onFieldChange={(event) => {
-    // Auto-save to localStorage or server
-    localStorage.setItem(`form_${event.fieldId}`, event.fieldValue);
-  }}
-  webhooks={[{
-    url: 'https://api.yourapp.com/autosave',
-    events: ['change'],
-    debounceMs: 2000 // Save every 2 seconds
-  }]}
-/>
-```
+### ExtendedFormProps
 
-### Real-time Validation
-```tsx
-<ExtendedForm
-  schema={schema}
-  onFieldBlur={async (event) => {
-    if (event.fieldId === 'root_email') {
-      const isValid = await validateEmailWithAPI(event.fieldValue);
-      setEmailValidation(isValid);
-    }
-  }}
-  webhooks={[{
-    url: 'https://validation.yourapp.com/validate',
-    events: ['blur'],
-    headers: { 'Content-Type': 'application/json' }
-  }]}
-/>
+```typescript
+interface ExtendedFormProps<T = any, S extends RJSFSchema = RJSFSchema, F = any> extends FormProps<T, S, F> {
+  // Standard RJSF props
+  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;
+  onFieldBlur?: (event: FormFieldEvent) => Promise<void> | void;  
+  onFieldChange?: (event: FormFieldEvent) => Promise<void> | void;
+  
+  // Webhook configuration
+  webhooks?: WebhookConfig[];
+  
+  // Conditional logic (v1 - deprecated)
+  conditionals?: ConditionalConfig;
+  
+  // Form lifecycle events
+  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;
+}
 ```
 
-### Progressive Form Enhancement
-```tsx
-<ExtendedForm
-  schema={schema}
-  onFieldChange={(event) => {
-    // Show additional fields based on user input
-    if (event.fieldId === 'root_country' && event.fieldValue === 'US') {
-      setShowStateField(true);
-    }
-  }}
-/>
-```
+### Three Pillars v2 Hooks
 
-## Conditional Forms
+```typescript
+// 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
+```
 
-Extended Dynamic Forms includes powerful conditional logic capabilities that allow you to:
-- Show/hide fields based on other field values
-- Make fields required/optional conditionally
-- Enable/disable fields based on complex conditions
-- Support multiple conditions with AND/OR logic
+## Real-World Use Cases
 
-### Basic Conditional Example
+### 🏢 Enterprise Business Applications
 
+**Australian Company Registration** (Featured Demo)
 ```tsx
-import { ConditionalForm, ConditionalRule } from 'extended-dynamic-forms';
-
-const schema = {
-  type: 'object',
-  properties: {
-    accountType: {
-      type: 'string',
-      enum: ['personal', 'business'],
-      title: 'Account Type'
-    },
-    firstName: { type: 'string', title: 'First Name' },
-    lastName: { type: 'string', title: 'Last Name' },
-    businessName: { type: 'string', title: 'Business Name' },
-    taxId: { type: 'string', title: 'Tax ID' }
-  }
+// 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 */ }
 };
 
-const conditionalRules: ConditionalRule[] = [
-  {
-    conditions: {
-      accountType: { equals: 'personal' }
-    },
-    event: {
-      type: 'show',
-      params: { fields: ['firstName', 'lastName'] }
-    }
-  },
-  {
-    conditions: {
-      accountType: { equals: 'business' }
-    },
-    event: {
-      type: 'show',
-      params: { fields: ['businessName', 'taxId'] }
+// 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' }
+      }))
     }
   }
-];
-
-<ConditionalForm
-  schema={schema}
-  conditionalRules={conditionalRules}
-  onSubmit={handleSubmit}
-/>
+};
 ```
 
-### Complex Conditions
+### 💼 Multi-Step Workflows
 
+**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
-const complexRules: ConditionalRule[] = [
-  {
-    // Show state field when country is US AND has address
-    conditions: {
-      all: [
-        { country: { equals: 'US' } },
-        { hasAddress: { equals: true } }
-      ]
-    },
-    event: {
-      type: 'show',
-      params: { fields: ['state', 'zipCode'] }
-    }
-  },
-  {
-    // Show verification for high income personal OR business accounts
-    conditions: {
-      any: [
-        {
-          all: [
-            { accountType: { equals: 'personal' } },
-            { income: { greaterThan: 100000 } }
-          ]
+// 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'
         },
-        {
-          accountType: { equals: 'business' }
+        passport: {
+          'ui:widget': !director.isAustralianResident ? 'text' : 'hidden'
         }
-      ]
-    },
-    event: {
-      type: 'require',
-      params: { fields: ['verificationDocument'] }
+      }))
     }
   }
-];
+};
 ```
 
-### Available Conditions
+**Product Configurations**
+- Dynamic product options based on category
+- Pricing calculations with quantity breaks
+- Feature availability by subscription tier
 
-- `equals` / `notEquals` - Exact value matching
-- `greaterThan` / `lessThan` - Numeric comparisons
-- `greaterThanOrEqual` / `lessThanOrEqual` - Inclusive numeric comparisons
-- `contains` / `notContains` - String contains
-- `in` / `notIn` - Value in array
-- `empty` / `notEmpty` - Check if field has value
+**Address Management**
+- International vs. domestic address formats
+- State/province selection based on country
+- Postal code validation by region
 
-### Available Events
+### 🌐 CMS & Integration Use Cases
 
-- `show` / `hide` - Control field visibility
-- `require` / `unrequire` - Make fields required/optional
-- `enable` / `disable` - Enable/disable fields
-
-### Combining with Webhooks
-
-```tsx
-<ConditionalForm
-  schema={schema}
-  conditionalRules={rules}
-  webhooks={[
-    {
-      url: 'https://api.example.com/validate',
-      events: ['change'],
-      debounceMs: 500
+**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 });
     }
-  ]}
-  onFieldChange={(event) => {
-    // Local handling alongside conditional logic
-    console.log('Field changed:', event);
-  }}
-/>
+  });
+</script>
 ```
 
-## API Reference
+**Legacy System Modernization**
+- Drop-in replacement for static HTML forms
+- Progressive enhancement of existing forms
+- No-build deployment to production environments
 
-### ExtendedFormProps
+## Architecture
 
-```typescript
-interface ExtendedFormProps extends FormProps {
-  // Standard RJSF props
-  schema: RJSFSchema;
-  uiSchema?: UiSchema;
-  formData?: any;
-  onSubmit?: (data: any, event: any) => void;
-  onChange?: (data: any) => void;
-  
-  // Field-level event handlers
-  onFieldFocus?: (event: FormFieldEvent) => Promise<void> | void;
-  onFieldBlur?: (event: FormFieldEvent) => Promise<void> | void;
-  onFieldChange?: (event: FormFieldEvent) => Promise<void> | void;
-  
-  // Webhook configuration
-  webhooks?: WebhookConfig[];
-  
-  // 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;
-}
+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)                  │
+└─────────────────────────────────────────────────┘
 ```
 
-### FormFieldEvent
+## 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 |
 
-```typescript
-interface FormFieldEvent {
-  eventType: 'focus' | 'blur' | 'change';
-  fieldId: string;
-  fieldValue: any;
-  schema?: any;
-  formData?: any;
-  timestamp: number;
-  fieldPath?: string[];
-}
+## Development
+
+### 🚀 Quick Start
+
+```bash
+# Clone and setup
+git clone https://github.com/user/extended-dynamic-forms.git
+cd extended-dynamic-forms
+npm install
+
+# Start development with playground
+npm run dev                    # Launches interactive playground
+npm run playground            # Alternative playground command
+
+# 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
 ```
 
-### WebhookConfig
+### 📦 Build Commands
 
-```typescript
-interface WebhookConfig {
-  url: string;
-  method?: 'POST' | 'PUT' | 'PATCH';
-  headers?: Record<string, string>;
-  events?: ('focus' | 'blur' | 'change')[];
-  debounceMs?: number;
-  retries?: number;
-  timeout?: number;
-}
+```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
 ```
 
-### ConditionalRule
+### 🧪 Testing
 
-```typescript
-interface ConditionalRule {
-  conditions: {
-    [fieldPath: string]: FieldCondition;
-    all?: Array<{ [fieldPath: string]: FieldCondition }>;
-    any?: Array<{ [fieldPath: string]: FieldCondition }>;
-  };
-  event: {
-    type: 'show' | 'hide' | 'require' | 'unrequire' | 'disable' | 'enable';
-    params: {
-      fields: string[];
-    };
-  };
-}
+**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
 
-interface FieldCondition {
-  equals?: any;
-  notEquals?: any;
-  greaterThan?: number;
-  lessThan?: number;
-  greaterThanOrEqual?: number;
-  lessThanOrEqual?: number;
-  contains?: string;
-  notContains?: string;
-  in?: any[];
-  notIn?: any[];
-  empty?: boolean;
-  notEmpty?: boolean;
-}
+```bash
+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
 ```
 
-## Utility Functions
+### 🏗️ Architecture
 
-```tsx
-import { formDataUtils, schemaUtils, validationUtils } from 'extended-dynamic-forms';
-
-// Form Data Utils
-const clonedData = formDataUtils.cloneFormData(formData);
-const mergedData = formDataUtils.mergeFormData(current, updates);
-const nestedValue = formDataUtils.getNestedValue(data, 'user.address.city');
-const updatedData = formDataUtils.setNestedValue(data, 'user.name', 'John');
-const cleanData = formDataUtils.removeEmptyValues(data);
-
-// Schema Utils
-const required = schemaUtils.getRequiredFields(schema);
-const isRequired = schemaUtils.isFieldRequired(schema, 'email');
-const fieldSchema = schemaUtils.getFieldSchema(schema, 'user.address');
-const merged = schemaUtils.mergeSchemas(schema1, schema2);
-const paths = schemaUtils.getAllFieldPaths(schema);
-
-// Validation Utils
-const isEmail = validationUtils.isValidEmail('test@example.com');
-const isPhone = validationUtils.isValidPhone('(555) 123-4567');
-const isUrl = validationUtils.isValidUrl('https://example.com');
-const isDate = validationUtils.isValidDate('2024-01-01');
-const inRange = validationUtils.isInRange(5, 1, 10);
-const message = validationUtils.getValidationMessage('required');
+**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
 ```
 
-## Development
+## Examples & Demos
 
-```bash
-# Install dependencies
-npm install
+### 🎮 Interactive Playground
 
-# Run development server
+The library includes a comprehensive **interactive playground** with extensive real-world demos demonstrating all features:
+
+```bash
+# Run the playground locally
 npm run dev
+# or
+npm run playground
+```
 
-# Build library
-npm run build
+### 📚 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 -->
+```
 
-# Run tests
-npm test
+### 🔗 Live Demo Links
 
-# Lint code
-npm run lint
-```
+- **[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
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## Community & Support
+
+- 📚 [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>