extended-dynamic-forms 0.2.1 → 0.3.0

package/README.md

@@ -1,1548 +1,543 @@
 # Extended Dynamic Forms
 
-## 🚨 BREAKING CHANGE: v0.2.0 - JsonLogic Only Conditions
+## BREAKING CHANGE: v0.2.0
 
-> **⚠️ IMPORTANT**: Starting with v0.2.0, Extended Dynamic Forms **ONLY** supports JsonLogic for conditional logic. Function-based conditions are no longer supported. This is a breaking change that improves security, performance, and maintainability.
->
-> **Migration Required**: If you are using function-based conditions like `condition: (formData) => ...`, you must migrate to JsonLogic format: `condition: { "==": [{ "var": "fieldName" }, "value"] }`
+All conditional logic now uses **JsonLogic rules only** for conditions. Function-based conditions have been removed for security and portability. Note that validation effects may still use functions. See migration examples below.
 
-## ⚠️ Project Status: Active Development & Documentation Refinement
+## Project Status
 
-**Important Notice**: This project is currently undergoing significant documentation updates to better reflect the actual implementation. Some features described in this README may not be fully implemented or may differ from the documentation. We are actively working to align the documentation with the codebase.
+**Important Notes:**
+- Requires RJSF source in sibling directory for development
+- Cannot be installed from npm due to local file dependencies  
+- JSON logic conditions don't work with vanilla JavaScript builds
+- Array drag-and-drop is not implemented
+- Limited test coverage for UI components and event system
+- JSON Patch implementation supports add/remove/replace only (not move/copy/test)
 
-**Known Issues**:
-- The project currently uses local file dependencies that require a specific directory structure to build
-- The project requires RJSF packages from a sibling directory (../react-jsonschema-form/)
-- Array drag-and-drop functionality mentioned in documentation is not implemented
-- Test coverage is limited for UI components and event systems
-- Several documented features have incomplete implementations
-- Significant dead code: 76% of utility functions are unused (13 out of 17 functions)
-- JSON Patch implementation in v2 doesn't fully comply with RFC 6902 (no move/copy/test operations)
+## Overview
 
-**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.
+Extended Dynamic Forms is an extension library for React JSON Schema Form (RJSF) v6 that adds:
 
-Built on top of the excellent RJSF v6 foundation, this library introduces the **Three Pillars 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 architecture with optimized performance
-- **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
-
-This library transforms RJSF from a simple form generator into a complete enterprise form solution while preserving its declarative approach.
-
-## Core Features
-
-### 🚀 Three Pillars Architecture with JsonLogic
-- **UI Logic Pillar**: Control form appearance with JsonLogic conditions and JSON Patch operations
-- **Schema Logic Pillar**: Modify data structure with JsonLogic rules when truly needed
-- **Validation Logic Pillar**: Dynamic validation rules with JsonLogic conditions
-- **O(N) Performance**: Superior array handling with optimized evaluation
-- **JsonLogic-Only**: Secure, data-driven conditions without code execution
-- **React Hooks**: Modern, declarative API with `useConditionalUi`, `useConditionalSchema`, `useConditionalValidation`
-
-### 🎯 Declarative Conditional Logic with JsonLogic
-- Define complex form behavior with secure JsonLogic rules
-- Dynamic array support with per-item evaluation
-- No code execution - all conditions are data-driven
-- Type-safe with comprehensive TypeScript support
-
-```tsx
-import { UiRule, JsonLogicRule } from 'extended-dynamic-forms/conditionals/v2';
-
-const uiRules: UiRule[] = [{
-  name: 'Show premium features for premium users',
-  condition: {
-    "==": [{ "var": "accountType" }, "premium"]
-  } as JsonLogicRule,
-  effect: [
-    { op: 'remove', path: '/premiumFeatures/ui:widget' }
-  ]
-}];
-```
-
-### 🧙‍♂️ Multi-Step Wizard Forms 
-- Automatic step detection from schema structure
-- **Full conditional logic support** with step-aware rule processing
-- Built-in progress indicators and navigation
-- Per-step validation
-- Supports Three Pillars architecture with JsonLogic conditions
-
-**Step-Aware Conditional Logic**
-
-The `WizardForm` automatically filters and transforms conditional rules to work within the current step's context. This means you can define conditions that reference fields across different steps, and the wizard will intelligently apply only the relevant rules for the active step:
-
-```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 UiRules with JsonLogic to handle step-aware conditionals
-const uiRules: UiRule[] = [{
-  name: 'Show SSN only for US Citizens in Personal step',
-  condition: {
-    "!": { "var": "STEP_PERSONAL.isUSCitizen" }
-  } as JsonLogicRule,
-  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
-- **Enhanced webhook support** for form-level events (submit, stepChange, validationError)
-
-### 🎨 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
-- **Test Coverage**: Focused on conditional logic and wizard forms (UI components have limited coverage)
-- **Developer Experience**: Interactive playground with real-world demos (note: some deprecated)
-
-### 🌐 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>
-```
-
-**Important Notes on Conditional Logic in Vanilla JS:**
-- **JsonLogic is NOT supported in vanilla JS** - The JsonLogic runtime requires React hooks
-- For JsonLogic benefits, you must use the React-based API
-
-**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.
+- **Three Pillars Architecture** for conditional logic with O(N) performance (where N is the number of conditional rules/array items)
+- **Multi-step wizard forms** with automatic step detection
+- **Central event orchestration** with webhook support
+- **25+ Ant Design components** for professional UI
+- **TypeScript-first** development with full type safety
 
 ## Installation
 
-> ⚠️ **Important Note**: This library currently uses local file dependencies for RJSF packages (pointing to `../react-jsonschema-form/`). This means:
-> - The library cannot be installed directly from npm without modifications
-> - You need the RJSF source code in a sibling directory for development
-> - Consider using a monorepo structure or git submodules for proper dependency management
-
-### React Projects
+**Note:** This library currently requires local development setup and cannot be installed via npm due to local file dependencies.
 
 ```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">
+# Clone RJSF as sibling directory (required)
+cd ..
+git clone https://github.com/rjsf-team/react-jsonschema-form.git
 
-<!-- Or download and host locally -->
-<script src="./path/to/extended-dynamic-forms-standalone.js"></script>
-```
-
-### Peer Dependencies
-
-**Current Version**: `0.2.0` - Built for **RJSF v6** with Three Pillars architecture (JsonLogic-only).
-
-```json
-{
-  "react": "^18.0.0 || ^19.0.0",
-  "react-dom": "^18.0.0 || ^19.0.0",
-  "antd": "^5.24.0"
-}
+# Setup Extended Dynamic Forms
+cd extended-dynamic-forms
+npm install
+npm run dev
 ```
 
-> **React 19 Support**: This library supports both React 18 and React 19. See [REACT-19-COMPATIBILITY.md](archive/REACT-19-COMPATIBILITY.md) for migration details.
-
-**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+
+**Important:** The library is currently designed for internal use or as part of a monorepo setup. Standalone npm package distribution is not yet supported.
 
-> **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.
+## Core Architecture
 
-**Additional Dependencies**:
-- `dayjs`: ^1.11.13 (Date handling)
-- `json-rules-engine-simplified`: ^0.2.0
+### Three Pillars Conditional System
 
-> **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.
+The conditional logic system is divided into three independent pillars:
 
-## Setup
+#### 1. UI Logic Pillar
+Controls form appearance using JsonLogic conditions and JSON Patch operations:
 
-### CSS Requirements
-
-This package uses Ant Design components. Import the CSS in your application:
+```typescript
+import { useConditionalUi, UiRule } from 'extended-dynamic-forms/conditionals/v2';
 
-```tsx
-// In your main entry file (e.g., App.tsx or index.tsx)
-import 'extended-dynamic-forms/dist/style.css'; // Or your specific CSS entry point
-```
+const uiRules: UiRule[] = [{
+  name: 'Show license number when has license',
+  condition: { "==": [{ "var": "hasDriversLicense" }, true] },
+  effect: [{ op: 'remove', path: '/licenseNumber/ui:widget' }]
+}];
 
-### 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>
-  );
-}
+const conditionalUiSchema = useConditionalUi(uiRules, baseUiSchema, formData);
 ```
 
-## Three Pillars Architecture with JsonLogic (Required Approach)
-
-> ⚠️ **BREAKING CHANGE**: As of v0.2.0, the Three Pillars system ONLY supports JsonLogic conditions. Function-based conditions are no longer supported for security and maintainability reasons.
-
-The Three Pillars system with JsonLogic provides superior performance, cleaner separation of concerns, and better security. It consists of three independent pillars:
+#### 2. Schema Logic Pillar  
+Modifies JSON Schema structure dynamically (use sparingly):
 
-### 1. UI Logic Pillar (`useConditionalUi`)
-
-Controls form appearance using JSON Patch operations with JsonLogic conditions:
-
-```tsx
-// Note: conditionals require deep import for optimal tree-shaking
-import { useConditionalUi, UiRule, JsonLogicRule } from 'extended-dynamic-forms/conditionals/v2';
-
-// Define UI rules with JsonLogic conditions and JSON Patch operations
-const uiRules: UiRule[] = [
-  {
-    name: 'Show shipping address when required',
-    condition: {
-      "==": [{ "var": "requiresShipping" }, true]
-    } as JsonLogicRule,
-    effect: [{ op: 'remove', path: '/shippingAddress/ui:widget' }],
-    order: 1
-  },
-  {
-    name: 'Dynamic country fields',
-    condition: {
-      "==": [{ "var": "shippingAddress.country" }, "USA"]
-    } as JsonLogicRule,
-    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)}
-    />
-  );
-}
+```typescript
+const schemaRules: SchemaRule[] = [{
+  name: 'Add premium fields',
+  condition: { "==": [{ "var": "accountType" }, "premium"] },
+  effect: [{ op: 'add', path: '/properties/premiumFeatures', value: {...} }]
+}];
 ```
 
-### 2. Schema Logic Pillar (`useConditionalSchema`)
-
-Modifies JSON Schema structure (use sparingly - prefer UI or Validation pillars):
-
-```tsx
-import { useConditionalSchema, SchemaRule, JsonLogicRule } from 'extended-dynamic-forms/conditionals/v2';
-
-const schemaRules: SchemaRule[] = [
-  {
-    name: 'Add premium fields',
-    condition: {
-      "==": [{ "var": "accountType" }, "premium"]
-    } as JsonLogicRule,
-    effect: [
-      { 
-        op: 'add', 
-        path: '/properties/premiumFeatures',
-        value: {
-          type: 'object',
-          properties: {
-            priority: { type: 'string', enum: ['high', 'medium', 'low'] }
-          }
-        }
-      }
-    ]
-  }
-];
+#### 3. Validation Logic Pillar
+Adds conditional validation rules:
 
-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, JsonLogicRule, createCustomValidate } from 'extended-dynamic-forms/conditionals/v2';
-
-const validationRules: ValidationRule[] = [
-  {
-    name: 'Require consent for minors',
-    condition: {
-      "<": [{ "var": "age" }, 18]
-    } as JsonLogicRule,
-    effect: {
-      type: 'validation',
-      validate: (errors, formData) => {
-        if (!formData.parentConsent) {
-          errors.parentConsent.addError('Parent consent is required for minors');
-        }
+```typescript
+const validationRules: ValidationRule[] = [{
+  name: 'Require consent for minors',
+  condition: { "<": [{ "var": "age" }, 18] },
+  effect: {
+    name: 'Parent consent validation',
+    isActive: { "<": [{ "var": "age" }, 18] },
+    validate: (errors, formData) => {
+      if (!formData.parentConsent) {
+        errors.parentConsent.__errors = ['Parent consent required'];
       }
     }
   }
-];
-
-// 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`**
+Provides efficient handling of conditional logic within arrays, where N is the number of array items:
 
-One of the most significant breakthroughs 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**: No rules are multiplied by array size
-- **React-Optimized**: Leverages React's rendering cycle for optimal performance
-
-> **Note**: `createDynamicArrayItemsUiSchema` still supports function-based conditions as it evaluates per-item during render. This is not a security risk as the functions are defined in your code, not from user input.
-
-```tsx
+```typescript
 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
-
-// ✅ Our 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' };
+    items: createDynamicArrayItemsUiSchema((director, index) => ({
+      shareholdingPercentage: {
+        'ui:widget': director.hasShareholding ? 'percentage' : 'hidden'
+      }
+    }))
   }
-
-  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);
-}
-```
-
-### JsonLogic Conditions (Required)
-
-As of v0.2.0, ONLY JsonLogic conditions are supported for security and maintainability:
-
-```tsx
-import { JsonLogicRule, UiRule } from 'extended-dynamic-forms/conditionals/v2';
-
-// JsonLogic rule examples
-const simpleRule: UiRule = {
-  name: 'Show field B when A is true',
-  condition: { "==": [{ "var": "fieldA" }, true] } as JsonLogicRule,
-  effect: [{ op: 'remove', path: '/fieldB/ui:widget' }]
-};
-
-const complexRule: UiRule = {
-  name: 'Complex business logic',
-  condition: {
-    "and": [
-      { "==": [{ "var": "accountType" }, "premium"] },
-      { ">": [{ "var": "revenue" }, 100000] },
-      { "in": [{ "var": "country" }, ["USA", "Canada", "UK"]] }
-    ]
-  } as JsonLogicRule,
-  effect: [{ op: 'remove', path: '/advancedFeatures/ui:widget' }]
 };
 ```
 
-## Quick Start
-
-### Simple Wizard Form (Recommended)
+## Multi-Step Wizard Forms
 
-The `WizardForm` component automatically detects multi-step forms and handles navigation. It fully supports conditional logic through the Three Pillars architecture:
+Create wizard forms with automatic step detection:
 
-```tsx
-import { useState } from 'react';
+```typescript
 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 webhooks from './webhooks.json';
-
-// Example: Three Pillars approach with JsonLogic (required)
-const uiRules: UiRule[] = [
-  {
-    name: 'Show tax ID in company step when listed',
-    condition: {
-      "==": [{ "var": "STEP_COMPANY.isListedCompany" }, true]
-    } as JsonLogicRule,
-    effect: [{ op: 'remove', path: '/STEP_COMPANY/taxId/ui:widget' }]
-  },
-  {
-    name: 'Show shareholding percentage for directors with shares',
-    condition: {
-      "some": [
-        { "var": "STEP_DIRECTORS.directors" },
-        { "var": "hasShareholding" }
-      ]
-    } as JsonLogicRule,
-    effect: [{ op: 'remove', path: '/STEP_DIRECTORS/directors/items/shareholdingPercentage/ui:widget' }]
-  }
-];
-
-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)}
-    />
-  );
-}
 
+<WizardForm
+  schema={wizardSchema}
+  uiSchema={conditionalUiSchema}
+  formData={formData}
+  onStepChange={(fromStep, toStep) => {
+    console.log(`Step ${fromStep} → ${toStep}`);
+  }}
+/>
 ```
 
-### Basic Form with Three Pillars
-
-```tsx
-import { ExtendedForm } from 'extended-dynamic-forms';
-import { useConditionalUi, UiRule, JsonLogicRule } from 'extended-dynamic-forms/conditionals/v2';
+**Important:** Wizard forms flatten nested step data. Use flat paths in conditions:
 
+```typescript
+// Schema uses STEP_ prefixes
 const schema = {
-  type: 'object',
   properties: {
-    isStudent: { type: 'boolean', title: 'Are you a student?' },
-    studentId: { type: 'string', title: 'Student ID' },
-    school: { type: 'string', title: 'School Name' }
+    STEP_PERSONAL: {
+      properties: {
+        hasDriversLicense: { type: 'boolean' }
+      }
+    }
   }
 };
 
-const baseUiSchema = {
-  studentId: { 'ui:widget': 'text' },
-  school: { 'ui:widget': 'text' }
-};
-
-// Define UI rules outside component with JsonLogic
-const uiRules: UiRule[] = [
-  {
-    name: 'Show student fields when student',
-    condition: {
-      "!": { "var": "isStudent" }
-    } as JsonLogicRule,
-    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)}
-    />
-  );
-}
+// Conditions use flat paths (no STEP_ prefix)
+condition: { "==": [{ "var": "hasDriversLicense" }, true] }
 ```
 
-## Custom Widgets
+## Event System & Webhooks
 
-### Available Widgets
+Central event orchestration for all form interactions:
 
-The library includes enhanced versions of all standard RJSF widgets plus custom ones:
+```typescript
+<ExtendedForm
+  schema={schema}
+  uiSchema={uiSchema}
+  webhooks={[{
+    url: 'https://api.example.com/events',
+    events: ['change', 'blur'],
+    debounceMs: 500,
+    retries: 3
+  }]}
+  onFieldChange={(event) => console.log(event.fieldId, event.fieldValue)}
+/>
+```
 
-#### Custom Widgets
+**Event Types:**
+- `focus` - Field focus
+- `blur` - Field blur
+- `change` - Value changes
+- `submit` - Form submission
+- `stepChange` - Wizard navigation
+- `validationError` - Validation failures
 
-```tsx
-// Color Picker
-const uiSchema = {
-  favoriteColor: {
-    'ui:widget': 'color'
-  }
-};
+## Custom Widgets
 
-// Rating Widget
-const uiSchema = {
-  satisfaction: {
-    'ui:widget': 'rating',
-    'ui:options': {
-      max: 10 // default is 5
-    }
-  }
-};
+All widgets must integrate with the event system:
 
-// Range Slider
-const schema = {
-  volume: {
-    type: 'number',
-    minimum: 0,
-    maximum: 100
-  }
-};
-const uiSchema = {
-  volume: {
-    'ui:widget': 'range'
-  }
-};
+```typescript
+import { WidgetProps } from '@rjsf/utils';
+import { useFieldEventHandlers } from 'extended-dynamic-forms/events';
 
-// File Upload
-const uiSchema = {
-  documents: {
-    'ui:widget': 'file',
-    'ui:options': {
-      accept: '.pdf,.doc,.docx',
-      multiple: true
-    }
-  }
+export const CustomWidget: FC<WidgetProps> = ({ id, value, onChange, schema }) => {
+  const fieldEventHandlers = useFieldEventHandlers(id, schema);
+  
+  const handleChange = async (newValue) => {
+    onChange(newValue);  // RJSF update
+    await fieldEventHandlers.onChange(newValue);  // Event system
+  };
+  
+  return <Input value={value} onChange={(e) => handleChange(e.target.value)} />;
 };
 ```
 
-#### Enhanced Standard Widgets
+## JsonLogic Migration Examples
 
-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
+Common patterns for migrating from function-based conditions:
 
-### Array Templates
+```typescript
+// Equality
+// Before: (formData) => formData.field === "value"
+// After:  { "==": [{ "var": "field" }, "value"] }
 
-The library provides Ant Design Card-based array templates for better visual organization:
-- **ArrayFieldTemplate**: Card container with proper spacing and visual hierarchy
-- **ArrayFieldItemTemplate**: Individual array items with integrated add/remove buttons
-- **Visual Design**: Clean card-based layout for array management
-- **Note**: Drag-and-drop reordering is not currently implemented
+// Boolean check
+// Before: (formData) => formData.isEnabled
+// After:  { "var": "isEnabled" }
 
-## Central Event Orchestration System
+// AND condition
+// Before: (formData) => formData.a && formData.b
+// After:  { "and": [{ "var": "a" }, { "var": "b" }] }
 
-### Field-Level Event Handling
+// Array contains
+// Before: (formData) => formData.roles?.includes("admin")
+// After:  { "in": ["admin", { "var": "roles" }] }
+```
 
-```tsx
-import { ExtendedForm, type FormFieldEvent } from 'extended-dynamic-forms';
+## Available Widgets
 
-<ExtendedForm
-  schema={schema}
-  uiSchema={uiSchema}
-  formData={formData}
-  
-  // Field-level event handlers
-  onFieldFocus={(event: FormFieldEvent) => {
-    console.log(`Field ${event.fieldId} focused:`, event.fieldValue);
-  }}
-  
-  onFieldChange={(event: FormFieldEvent) => {
-    console.log(`Field ${event.fieldId} changed:`, event.fieldValue);
-    // Real-time validation or processing
-  }}
-  
-  onFieldBlur={(event: FormFieldEvent) => {
-    console.log(`Field ${event.fieldId} blurred:`, event.fieldValue);
-  }}
-/>
-```
+### Complete Widget List
 
-### Enhanced Webhook Integration
-
-Configure multiple webhook endpoints to receive real-time form events, including form-level events for submit, validation errors, and wizard step changes:
-
-```tsx
-import { ExtendedForm, WizardForm, type WebhookConfig } from 'extended-dynamic-forms';
-
-// Comprehensive webhook configuration for all event types
-const webhookConfigs: WebhookConfig[] = [
-  {
-    url: 'https://api.yourapp.com/form-events',
-    method: 'POST',
-    events: ['change', 'blur', 'submit', 'validationError'],  // Multiple event types
-    debounceMs: 500,             // Wait 500ms before sending (field events)
-    retries: 3,                  // Retry failed requests
-    timeout: 5000,               // 5 second timeout
-    headers: {
-      'Authorization': 'Bearer your-api-token',
-      'X-Form-ID': 'contact-form'
-    }
-  },
-  {
-    url: 'https://analytics.yourapp.com/wizard-tracking',
-    method: 'POST',
-    events: ['stepChange', 'submit'],  // Wizard-specific events
-    debounceMs: 0,               // No debouncing for navigation
-    headers: {
-      'X-Session-ID': sessionId
-    }
-  }
-];
+#### Choice Widget (Unified Selection)
+- **ChoiceWidget** - Intelligent widget that automatically adapts based on schema:
+  - Renders as dropdown/select for regular choices
+  - Renders as radio group when `ui:widget` is "radio"
+  - Renders as checkbox group for multi-select arrays
+  - Supports static and dynamic data sources (API, WebSocket)
 
-// Use with ExtendedForm - includes webhook status callbacks
-<ExtendedForm
-  schema={schema}
-  uiSchema={uiSchema}
-  webhooks={webhookConfigs}
-  onWebhookStart={(webhook, event) => {
-    console.log('Webhook started:', webhook.url, event.eventType);
-  }}
-  onWebhookComplete={(webhook, event, response) => {
-    console.log('Webhook completed:', response.status);
-  }}
-  onWebhookError={(webhook, event, error) => {
-    console.error('Webhook failed:', error.message);
-  }}
-/>
+#### Text Input Widgets
+- **TextWidget** - Standard text input with Ant Design styling
+- **TextareaWidget** - Multi-line text input
+- **PasswordWidget** - Password input with visibility toggle
 
-// Use with WizardForm - automatically tracks step changes
-<WizardForm
-  schema={wizardSchema}
-  uiSchema={wizardUiSchema}
-  webhooks={webhookConfigs}
-  onWebhookError={(webhook, event, error) => {
-    // Handle webhook failures gracefully
-    notifyUser('Form data saved locally, will sync when online');
-  }}
-/>
-```
+#### Specialized Input Widgets
+- **ColorWidget** - Color picker using HTML5 color input
+- **EmailWidget** - Email input with validation
+- **URLWidget** - URL input with validation
+- **TelephoneWidget** - Phone number input
+- **NumberWidget** - Numeric input with increment/decrement controls
 
-#### Webhook Event Types and Payloads
+#### Visual Input Widgets
+- **RangeWidget** / **SliderWidget** - Slider for numeric ranges
+- **RatingWidget** - Star rating component
 
-All webhook events follow a standardized payload structure with common fields plus event-specific data:
+#### Date & Time Widgets
+- **DateWidget** / **EnhancedDateWidget** - Date picker with Ant Design DatePicker
+- **DateTimeWidget** - Combined date and time picker
 
-##### Field Events (existing)
-```typescript
-// Focus, Blur, Change events
-{
-  eventType: 'focus' | 'blur' | 'change',
-  fieldId: 'email',
-  fieldValue: 'user@example.com',
-  schema: { type: 'string', format: 'email' },
-  fieldPath: ['contact', 'email'],
-  timestamp: 1234567890123,
-  formData: { /* complete form data */ },
-  source: 'extended-dynamic-forms'
-}
-```
+#### File Upload Widgets
+- **FileWidget** - Basic file input
+- **FileUploadWidget** - Enhanced upload with progress, preview, and base64 support
 
-##### Submit Event
-```typescript
-// Triggered after successful form submission
+### Widget Configuration Examples
+
+#### Basic Text Input
+```json
 {
-  eventType: 'submit',
-  formData: {
-    name: 'John Doe',
-    email: 'john@example.com',
-    // ... all submitted data
+  "schema": {
+    "type": "string",
+    "title": "Full Name"
   },
-  timestamp: 1234567890123,
-  source: 'extended-dynamic-forms'
+  "uiSchema": {
+    "ui:widget": "text",
+    "ui:placeholder": "Enter your full name"
+  }
 }
 ```
 
-##### Step Change Event (WizardForm only)
-```typescript
-// Triggered when user navigates between wizard steps
+#### Number Input with Range
+```json
 {
-  eventType: 'stepChange',
-  fromStep: 0,  // Previous step index
-  toStep: 1,    // New step index
-  formData: { /* current form data */ },
-  timestamp: 1234567890123,
-  source: 'extended-dynamic-forms'
+  "schema": {
+    "type": "number",
+    "title": "Age",
+    "minimum": 0,
+    "maximum": 120
+  },
+  "uiSchema": {
+    "ui:widget": "number"
+  }
 }
 ```
 
-##### Validation Error Event
-```typescript
-// Triggered when form validation fails
+#### Rating Widget
+```json
 {
-  eventType: 'validationError',
-  errors: [
-    {
-      property: '.email',
-      message: 'Email is required',
-      name: 'required',
-      stack: '.email Email is required',
-      schemaPath: '#/properties/email'
-    },
-    {
-      property: '.age',
-      message: 'Age must be at least 18',
-      name: 'minimum',
-      argument: 18,
-      stack: '.age Age must be at least 18',
-      schemaPath: '#/properties/age/minimum'
+  "schema": {
+    "type": "number",
+    "title": "Rate your experience",
+    "minimum": 0,
+    "maximum": 5
+  },
+  "uiSchema": {
+    "ui:widget": "rating",
+    "ui:options": {
+      "count": 5,
+      "allowHalf": true
     }
-  ],
-  formData: { /* form data that failed validation */ },
-  timestamp: 1234567890123,
-  source: 'extended-dynamic-forms'
+  }
 }
 ```
 
-#### Advanced Webhook Examples
-
-##### Form Analytics and Monitoring
-```tsx
-// Track user behavior and form completion rates
-const analyticsWebhook: WebhookConfig = {
-  url: 'https://analytics.yourapp.com/form-events',
-  events: ['stepChange', 'submit', 'validationError'],
-  headers: {
-    'X-Analytics-Key': process.env.ANALYTICS_KEY
+#### Choice Widget (Dropdown)
+```json
+{
+  "schema": {
+    "type": "string",
+    "title": "Country",
+    "enum": ["us", "uk", "au", "ca"],
+    "enumNames": ["United States", "United Kingdom", "Australia", "Canada"]
+  },
+  "uiSchema": {
+    "ui:widget": "choice"
   }
-};
-
-// Monitor form health and errors
-const monitoringWebhook: WebhookConfig = {
-  url: 'https://monitoring.yourapp.com/form-errors',
-  events: ['validationError'],  // Only track errors
-  method: 'POST',
-  retries: 5  // Ensure error tracking is reliable
-};
+}
 ```
 
-##### Progressive Form Saving
-```tsx
-// Auto-save form progress
-const autoSaveWebhook: WebhookConfig = {
-  url: 'https://api.yourapp.com/form-drafts',
-  events: ['change', 'stepChange'],
-  debounceMs: 2000,  // Save every 2 seconds of inactivity
-  headers: {
-    'X-User-ID': userId,
-    'X-Draft': 'true'
-  }
-};
-
-// Final submission
-const submitWebhook: WebhookConfig = {
-  url: 'https://api.yourapp.com/form-submissions',
-  events: ['submit'],
-  headers: {
-    'X-User-ID': userId,
-    'X-Final': 'true'
+#### Choice Widget (Radio Group)
+```json
+{
+  "schema": {
+    "type": "string",
+    "title": "Gender",
+    "enum": ["male", "female", "other"]
+  },
+  "uiSchema": {
+    "ui:widget": "choice",
+    "ui:options": {
+      "presenter": "radio"
+    }
   }
-};
+}
 ```
 
-##### Conditional Webhook Logic
-```tsx
-// Different endpoints based on form data
-function App() {
-  const [formData, setFormData] = useState({});
-  
-  // Dynamic webhook configuration based on form state
-  const webhooks = useMemo(() => {
-    const configs: WebhookConfig[] = [];
-    
-    // Add region-specific webhook
-    if (formData.country === 'USA') {
-      configs.push({
-        url: 'https://us-api.yourapp.com/forms',
-        events: ['submit'],
-        headers: { 'X-Region': 'US' }
-      });
-    } else if (formData.country === 'EU') {
-      configs.push({
-        url: 'https://eu-api.yourapp.com/forms',
-        events: ['submit'],
-        headers: { 'X-Region': 'EU', 'X-GDPR': 'true' }
-      });
+#### Choice Widget (Checkbox Group - Multi-select)
+```json
+{
+  "schema": {
+    "type": "array",
+    "title": "Interests",
+    "items": {
+      "type": "string",
+      "enum": ["sports", "music", "reading", "travel"]
+    },
+    "uniqueItems": true
+  },
+  "uiSchema": {
+    "ui:widget": "choice",
+    "ui:options": {
+      "presenter": "checkbox"
     }
-    
-    return configs;
-  }, [formData.country]);
-  
-  return (
-    <ExtendedForm
-      schema={schema}
-      formData={formData}
-      onChange={({ formData }) => setFormData(formData)}
-      webhooks={webhooks}
-    />
-  );
+  }
 }
 ```
 
-##### Error Handling and Retry Strategies
-```tsx
-// Robust webhook configuration with fallbacks
-const primaryWebhook: WebhookConfig = {
-  url: 'https://api.yourapp.com/primary',
-  events: ['submit'],
-  timeout: 5000,
-  retries: 3
-};
-
-// Fallback webhook for critical data
-const fallbackWebhook: WebhookConfig = {
-  url: 'https://backup.yourapp.com/forms',
-  events: ['submit'],
-  timeout: 10000,
-  retries: 5
-};
-
-<ExtendedForm
-  webhooks={[primaryWebhook, fallbackWebhook]}
-  onWebhookError={(webhook, event, error) => {
-    if (webhook.url === primaryWebhook.url) {
-      console.log('Primary webhook failed, fallback will handle');
+#### Date Picker
+```json
+{
+  "schema": {
+    "type": "string",
+    "title": "Date of Birth",
+    "format": "date"
+  },
+  "uiSchema": {
+    "ui:widget": "date",
+    "ui:options": {
+      "format": "DD/MM/YYYY",
+      "picker": "date"
     }
-    
-    // Store locally for later sync
-    localStorage.setItem(`pending-${Date.now()}`, JSON.stringify(event));
-  }}
-/>
-```
-
-
-## API Reference
-
-### ExtendedFormProps
-
-```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[];
-  
-  // Webhook status callbacks
-  onWebhookStart?: (webhook: WebhookConfig, event: any) => void;
-  onWebhookComplete?: (webhook: WebhookConfig, event: any, response: any) => void;
-  onWebhookError?: (webhook: WebhookConfig, event: any, error: Error) => void;
-  
-  
-  // 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;
+  }
 }
 ```
 
-### WebhookConfig
-
-```typescript
-interface WebhookConfig {
-  url: string;
-  method?: 'POST' | 'PUT' | 'PATCH';
-  headers?: Record<string, string>;
-  events?: ('focus' | 'blur' | 'change' | 'submit' | 'stepChange' | 'validationError')[];
-  debounceMs?: number;
-  retries?: number;
-  timeout?: number;
+#### File Upload
+```json
+{
+  "schema": {
+    "type": "string",
+    "title": "Resume",
+    "format": "data-url"
+  },
+  "uiSchema": {
+    "ui:widget": "FileUploadWidget",
+    "ui:options": {
+      "accept": ".pdf,.doc,.docx",
+      "maxSize": 5242880,
+      "multiple": false
+    }
+  }
 }
 ```
 
-### Webhook Event Types
-
-```typescript
-type WebhookEventType = 'focus' | 'blur' | 'change' | 'submit' | 'stepChange' | 'validationError';
-
-// Base event structure
-interface BaseWebhookEvent {
-  eventType: WebhookEventType;
-  timestamp: number;
-  formData: any;
-  source: 'extended-dynamic-forms';
-}
-
-// Field events
-interface FieldWebhookEvent extends BaseWebhookEvent {
-  eventType: 'focus' | 'blur' | 'change';
-  fieldId: string;
-  fieldValue: any;
-  schema?: any;
-  fieldPath?: string[];
-}
-
-// Submit event
-interface SubmitWebhookEvent extends BaseWebhookEvent {
-  eventType: 'submit';
-}
-
-// Step change event
-interface StepChangeWebhookEvent extends BaseWebhookEvent {
-  eventType: 'stepChange';
-  fromStep: number;
-  toStep: number;
-}
-
-// Validation error event
-interface ValidationErrorWebhookEvent extends BaseWebhookEvent {
-  eventType: 'validationError';
-  errors: Array<{
-    property: string;
-    message: string;
-    name: string;
-    argument?: any;
-    stack: string;
-    schemaPath: string;
-  }>;
+#### Color Picker
+```json
+{
+  "schema": {
+    "type": "string",
+    "title": "Favorite Color",
+    "format": "color"
+  },
+  "uiSchema": {
+    "ui:widget": "color"
+  }
 }
 ```
 
-### Three Pillars Hooks
-
-```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
-```
-
-## 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' }
-      }))
+#### Range/Slider Widget
+```json
+{
+  "schema": {
+    "type": "number",
+    "title": "Volume",
+    "minimum": 0,
+    "maximum": 100
+  },
+  "uiSchema": {
+    "ui:widget": "range",
+    "ui:options": {
+      "marks": {
+        "0": "Mute",
+        "50": "50%",
+        "100": "Max"
+      }
     }
   }
-};
+}
 ```
 
-### 💼 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
-// 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'
-        }
-      }))
-    }
+#### Hidden Field
+```json
+{
+  "schema": {
+    "type": "string",
+    "title": "User ID"
+  },
+  "uiSchema": {
+    "ui:widget": "hidden"
   }
-};
+}
 ```
 
-**Product Configurations**
-- Dynamic product options based on category
-- Pricing calculations with quantity breaks
-- Feature availability by subscription tier
-
-**Address Management**
-- International vs. domestic address formats
-- State/province selection based on country
-- Postal code validation by region
+### Widget Registration
 
-### 🌐 CMS & Integration Use Cases
+Register custom widgets with ExtendedForm:
 
-**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
+```typescript
+import { ExtendedForm, customWidgets } from 'extended-dynamic-forms';
 
-Extended Dynamic Forms uses a layered architecture that cleanly extends RJSF:
+// Use all built-in widgets
+<ExtendedForm 
+  widgets={customWidgets}
+  schema={schema}
+  uiSchema={uiSchema}
+/>
 
+// Or register specific widgets
+<ExtendedForm 
+  widgets={{
+    text: customWidgets.text,
+    date: customWidgets.date,
+    choice: customWidgets.choice
+  }}
+/>
 ```
-┌─────────────────────────────────────────────────┐
-│     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 (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 | ⚠️ Focused on Conditionals/Wizards |
-| **Performance** | Standard | ✅ Optimized with Caching |
-| **Validation** | Basic | ✅ Dynamic + Custom Rules |
-| **Developer Tools** | Limited | ✅ Interactive Playground |
 
 ## Development
 
-### 🚀 Quick Start
-
-> **Development Setup Note**: Due to local file dependencies, you need:
-> 1. Clone RJSF repository in a sibling directory: `../react-jsonschema-form/`
-> 2. Ensure the RJSF packages are built and available
-
 ```bash
-# Clone and setup (requires specific directory structure)
-git clone https://github.com/user/extended-dynamic-forms.git
-cd extended-dynamic-forms
-npm install  # Note: Will fail without ../react-jsonschema-form/ directory
+# Development
+npm run dev              # Start playground
+npm run test             # Run tests
+npm run test:ui          # Test with UI
 
-# Start development with playground
-npm run dev                    # Launches interactive playground
-npm run playground            # Alternative playground command
+# Building
+npm run build            # Build library
+npm run build:vanilla    # Build standalone (currently broken - JsonLogic incompatible)
+npm run preview          # Preview 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
+# Code Quality
+npm run lint             # ESLint
+npm run format           # Prettier
 ```
 
-### 📦 Build Commands
+## Project Structure
 
-```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
-```
-
-### 🧪 Testing
-
-**Test Coverage**: Test suite focuses primarily on:
-- **Conditional Logic**: Comprehensive coverage for conditional systems (16+ test files)
-- **Wizard Forms**: Step navigation and validation
-- **Performance**: Array conditional optimization
-- **Note**: Limited coverage for UI components, event system, and utility functions
-
-```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
-```
-
-### 🏗️ 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/            # Conditional systems
-│   ├── v2/                 # Three Pillars architecture
-│   └── DynamicArrayConditionalEngine.ts
-├── events/                  # Central event orchestration
-├── widgets/                 # Enhanced component suite
-├── components/              # Field and template components
-└── utils/                   # Utilities (Note: 76% are unused)
-```
-
-## Examples & Demos
-
-### 🎮 Interactive Playground
-
-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
-```
-
-### 📚 Demo Categories
-
-> **Note**: Some playground demos may be outdated.
-
-#### **Three Pillars 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
-
-#### **🧙‍♂️ 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
-- **Form-Level Event Handling**: Submit, validation error, and step change events
-- **Webhook Configuration**: Multiple endpoints with custom headers and event filtering
-- **Webhook Status Tracking**: Callbacks for monitoring webhook success/failure
-
-#### **🎨 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 -->
-```
-
-### 🔗 Live Demo Links
-
-- **[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 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.
-
-## Migration Guide: Enhanced Webhook Events
-
-### Upgrading to Enhanced Webhook System
-
-The enhanced webhook system is **fully backward compatible**. Existing webhook configurations will continue to work without any changes. The new event types are additive and opt-in.
-
-#### For Existing Webhook Users
-
-Your current webhook configurations will continue to work exactly as before:
-
-```typescript
-// This existing configuration still works perfectly
-const webhookConfig: WebhookConfig = {
-  url: 'https://api.example.com/form-events',
-  method: 'POST',
-  debounceMs: 500
-};
-// Without the 'events' array, it receives ALL events (backward compatible)
+├── components/          # Core form components
+├── conditionals/        # Three Pillars system
+│   └── v2/             # Current implementation
+├── events/             # Event orchestration
+├── layouts/            # Layout systems
+│   └── wizard/         # Wizard form components
+├── widgets/            # Input widgets
+└── utils/              # Utilities
 ```
 
-To take advantage of new event types:
+## Examples
 
-```typescript
-// Option 1: Subscribe to specific new events only
-const webhookConfig: WebhookConfig = {
-  url: 'https://api.example.com/form-events',
-  events: ['submit', 'validationError'],  // Only these new events
-  debounceMs: 1000
-};
+Interactive examples available at `/playground/src/demos/`:
 
-// Option 2: Mix old and new events
-const webhookConfig: WebhookConfig = {
-  url: 'https://api.example.com/form-events',
-  events: ['change', 'blur', 'submit', 'stepChange'],  // Mixed event types
-  debounceMs: 500
-};
-```
+- **Wizard Forms**: Australian Company Onboarding, Employee Onboarding
+- **Conditionals**: Dynamic visibility, validation, array handling
+- **Events**: Webhook integration, field tracking
+- **Widgets**: All available components
 
-#### For New Implementations
+Run `npm run dev` to explore examples.
 
-If you're implementing webhooks for the first time, consider these patterns:
+## Known Limitations
 
-```typescript
-// Complete form lifecycle monitoring
-const lifecycleWebhook: WebhookConfig = {
-  url: 'https://api.example.com/form-lifecycle',
-  events: ['focus', 'change', 'blur', 'submit', 'validationError'],
-  method: 'POST',
-  headers: {
-    'X-API-Key': 'your-api-key'
-  },
-  debounceMs: 500,
-  retries: 3,
-  timeout: 10000
-};
-
-// Wizard-specific tracking
-const wizardWebhook: WebhookConfig = {
-  url: 'https://analytics.example.com/wizard-tracking',
-  events: ['stepChange', 'submit'],
-  method: 'POST',
-  debounceMs: 0,  // No debouncing for navigation events
-  retries: 1
-};
-
-// Error monitoring only
-const errorWebhook: WebhookConfig = {
-  url: 'https://monitoring.example.com/form-errors',
-  events: ['validationError'],
-  method: 'POST',
-  retries: 5  // Ensure error tracking is reliable
-};
-```
+1. **Dependencies**: Requires RJSF source in sibling directory
+2. **Installation**: Cannot install from npm
+3. **Vanilla JS**: JsonLogic not supported in standalone builds
+4. **Arrays**: No drag-and-drop functionality
+5. **JSON Patch**: Only supports add/remove/replace operations
+6. **Test Coverage**: Limited for UI components and events
 
-#### Using Webhook Status Callbacks
+## TypeScript
 
-The new webhook status callbacks provide visibility into webhook processing:
+Full TypeScript support with exported types:
 
 ```typescript
-<ExtendedForm
-  schema={schema}
-  webhooks={webhooks}
-  onWebhookStart={(webhook, event) => {
-    // Show loading indicator
-    setWebhookLoading(true);
-  }}
-  onWebhookComplete={(webhook, event, response) => {
-    // Hide loading indicator
-    setWebhookLoading(false);
-    
-    // Handle success
-    if (response.ok) {
-      showNotification('Data saved successfully');
-    }
-  }}
-  onWebhookError={(webhook, event, error) => {
-    // Hide loading indicator
-    setWebhookLoading(false);
-    
-    // Handle error gracefully
-    console.error('Webhook failed:', error);
-    showNotification('Saving to server failed, will retry later');
-    
-    // Store for offline sync
-    queueForLaterSync(event);
-  }}
-/>
+import {
+  ExtendedForm,
+  WizardForm,
+  UiRule,
+  SchemaRule,
+  ValidationRule,
+  JsonLogicRule,
+  FormEvent,
+  WebhookConfig
+} from 'extended-dynamic-forms';
 ```
 
-#### Important Notes
-
-1. **Event Filtering**: If you specify the `events` array, only those events will trigger webhooks
-2. **Debouncing**: Form-level events (submit, stepChange, validationError) respect debounceMs settings
-3. **Payload Structure**: All events now include standard fields (timestamp, formData, eventType, source)
-4. **No Breaking Changes**: All existing functionality remains unchanged
-
-## 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)
-
+## Contributing
 
+1. Fork the repository
+2. Create your feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Submit a pull request
 
----
+## License
 
-<p align="center">
-  Built with ❤️ on top of <a href="https://github.com/rjsf-team/react-jsonschema-form">React JSON Schema Form</a>
-</p>
+MIT License - see LICENSE file for details.