extended-dynamic-forms 0.2.0 → 0.3.0

package/README.md

@@ -1,1220 +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/)
-- Some playground demos use deprecated v1 conditional patterns (01-simple-conditionals.demo.tsx)
-- 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 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 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 vs v1's O(M×N)
-- **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 both v1 conditions (deprecated) and v2 Three Pillars architecture
-
-**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 v2 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
-
-### 🎨 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
-- Only v1 conditions are supported with the `conditionals` prop
-- Subject to v1's O(M×N) performance for array conditionals
-- For JsonLogic and v2 benefits, you must use the React-based API
-
-```javascript
-// Vanilla JS supports only v1 conditionals
-ExtendedDynamicForms.createForm({
-  container: '#my-form',
-  schema: schema,
-  conditionals: {
-    rules: [
-      {
-        conditions: { showField: true },
-        event: { type: 'show', params: { field: 'conditionalField' } }
-      }
-    ]
-  }
-});
-```
-
-**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 v2 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](./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 (v1 conditional logic)
+### 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 v2 Architecture with JsonLogic (Required Approach)
-
-> ⚠️ **BREAKING CHANGE**: As of v0.2.0, the Three Pillars v2 system ONLY supports JsonLogic conditions. Function-based conditions are no longer supported for security and maintainability reasons.
-
-The Three Pillars v2 system with JsonLogic provides superior performance, cleaner separation of concerns, and better security. It consists of three independent pillars:
-
-### 1. UI Logic Pillar (`useConditionalUi`)
-
-Controls form appearance using JSON Patch operations with JsonLogic conditions:
-
-```tsx
-// Note: v2 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
-  }
-};
+#### 2. Schema Logic Pillar  
+Modifies JSON Schema structure dynamically (use sparingly):
 
-// 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`**
-
-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
+Provides efficient handling of conditional logic within arrays, where N is the number of array items:
 
-> **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)
+    items: createDynamicArrayItemsUiSchema((director, index) => ({
+      shareholdingPercentage: {
+        'ui:widget': director.hasShareholding ? 'percentage' : 'hidden'
+      }
+    }))
   }
 };
 ```
 
-**Performance Comparison:**
+## Multi-Step Wizard Forms
+
+Create wizard forms with automatic step detection:
+
 ```typescript
-// ❌ Traditional approach: O(M×N) - Rules × Array Items
-// With 10 rules and 50 directors = 500 evaluations
+import { WizardForm } from 'extended-dynamic-forms';
 
-// ✅ v2 approach: O(N) - Per-item evaluation  
-// With 50 directors = 50 evaluations (regardless of rule complexity)
+<WizardForm
+  schema={wizardSchema}
+  uiSchema={conditionalUiSchema}
+  formData={formData}
+  onStepChange={(fromStep, toStep) => {
+    console.log(`Step ${fromStep} → ${toStep}`);
+  }}
+/>
 ```
 
-**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' };
-  }
+**Important:** Wizard forms flatten nested step data. Use flat paths in conditions:
 
-  // Subscription-specific logic
-  if (product.billingType === 'subscription') {
-    baseConfig.recurringPrice = { 'ui:widget': 'currency' };
-    baseConfig.billingCycle = { 'ui:widget': 'select' };
+```typescript
+// Schema uses STEP_ prefixes
+const schema = {
+  properties: {
+    STEP_PERSONAL: {
+      properties: {
+        hasDriversLicense: { type: 'boolean' }
+      }
+    }
   }
-
-  return baseConfig;
 };
-```
 
-### Performance Best Practices
+// Conditions use flat paths (no STEP_ prefix)
+condition: { "==": [{ "var": "hasDriversLicense" }, true] }
+```
 
-> ⚠️ **Critical**: Always define rules and base schemas outside render or memoize them!
+## Event System & Webhooks
 
-```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
-  );
-}
+Central event orchestration for all form interactions:
 
-// ✅ GOOD - Stable references
-const rules = [{ condition: () => true, effect: [...] }];
-const baseUiSchema = { field: { 'ui:widget': 'text' } };
-
-function MyForm() {
-  const conditionalUiSchema = useConditionalUi(rules, baseUiSchema, formData);
-}
+```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)}
+/>
 ```
 
-### JsonLogic Conditions (Required)
+**Event Types:**
+- `focus` - Field focus
+- `blur` - Field blur
+- `change` - Value changes
+- `submit` - Form submission
+- `stepChange` - Wizard navigation
+- `validationError` - Validation failures
 
-As of v0.2.0, v2 ONLY supports JsonLogic conditions for security and maintainability:
+## Custom Widgets
 
-```tsx
-import { JsonLogicRule, UiRule } from 'extended-dynamic-forms/conditionals/v2';
+All widgets must integrate with the event system:
 
-// 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' }]
-};
+```typescript
+import { WidgetProps } from '@rjsf/utils';
+import { useFieldEventHandlers } from 'extended-dynamic-forms/events';
 
-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' }]
+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)} />;
 };
 ```
 
-## Quick Start
+## JsonLogic Migration Examples
 
-### Simple Wizard Form (Recommended)
+Common patterns for migrating from function-based conditions:
 
-The `WizardForm` component automatically detects multi-step forms and handles navigation. It fully supports conditional logic through either v1 conditions (deprecated) or the recommended Three Pillars v2 architecture:
+```typescript
+// Equality
+// Before: (formData) => formData.field === "value"
+// After:  { "==": [{ "var": "field" }, "value"] }
 
-```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 webhooks from './webhooks.json';
-
-// Example: v2 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)}
-    />
-  );
-}
+// Boolean check
+// Before: (formData) => formData.isEnabled
+// After:  { "var": "isEnabled" }
 
-// Alternative: v1 conditions approach (deprecated but still supported)
-const v1Conditions = [
-  {
-    conditions: { "STEP_COMPANY.isListedCompany": true },
-    event: { type: "show", params: { field: "STEP_COMPANY.taxId" } }
-  },
-  {
-    conditions: { "STEP_DIRECTORS.directors[*].hasShareholding": true },
-    event: { type: "show", params: { field: "STEP_DIRECTORS.directors[*].shareholdingPercentage" } }
-  }
-];
+// AND condition
+// Before: (formData) => formData.a && formData.b
+// After:  { "and": [{ "var": "a" }, { "var": "b" }] }
 
-// Pass v1 conditions directly to WizardForm
-<WizardForm
-  schema={schema}
-  uiSchema={uiSchema}
-  conditions={v1Conditions}  // WizardForm handles step-aware transformation
-  onSubmit={(data) => console.log('Submitted:', data.formData)}
-/>
+// Array contains
+// Before: (formData) => formData.roles?.includes("admin")
+// After:  { "in": ["admin", { "var": "roles" }] }
 ```
 
-### Basic Form with Three Pillars v2
-
-```tsx
-import { ExtendedForm } from 'extended-dynamic-forms';
-import { useConditionalUi, UiRule, JsonLogicRule } from 'extended-dynamic-forms/conditionals/v2';
-
-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' }
-  }
-};
+## Available Widgets
 
-const baseUiSchema = {
-  studentId: { 'ui:widget': 'text' },
-  school: { 'ui:widget': 'text' }
-};
+### Complete Widget List
 
-// 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' }
-    ]
-  }
-];
+#### 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)
 
-function App() {
-  const [formData, setFormData] = useState({});
-  const conditionalUiSchema = useConditionalUi(uiRules, baseUiSchema, formData);
-  
-  return (
-    <ExtendedForm
-      schema={schema}
-      uiSchema={conditionalUiSchema}
-      formData={formData}
-      onChange={({ formData }) => setFormData(formData)}
-    />
-  );
-}
-```
+#### Text Input Widgets
+- **TextWidget** - Standard text input with Ant Design styling
+- **TextareaWidget** - Multi-line text input
+- **PasswordWidget** - Password input with visibility toggle
 
-## Custom Widgets
+#### 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
 
-### Available Widgets
+#### Visual Input Widgets
+- **RangeWidget** / **SliderWidget** - Slider for numeric ranges
+- **RatingWidget** - Star rating component
 
-The library includes enhanced versions of all standard RJSF widgets plus custom ones:
+#### Date & Time Widgets
+- **DateWidget** / **EnhancedDateWidget** - Date picker with Ant Design DatePicker
+- **DateTimeWidget** - Combined date and time picker
 
-#### Custom Widgets
+#### File Upload Widgets
+- **FileWidget** - Basic file input
+- **FileUploadWidget** - Enhanced upload with progress, preview, and base64 support
 
-```tsx
-// Color Picker
-const uiSchema = {
-  favoriteColor: {
-    'ui:widget': 'color'
-  }
-};
+### Widget Configuration Examples
 
-// Rating Widget
-const uiSchema = {
-  satisfaction: {
-    'ui:widget': 'rating',
-    'ui:options': {
-      max: 10 // default is 5
-    }
+#### Basic Text Input
+```json
+{
+  "schema": {
+    "type": "string",
+    "title": "Full Name"
+  },
+  "uiSchema": {
+    "ui:widget": "text",
+    "ui:placeholder": "Enter your full name"
   }
-};
+}
+```
 
-// Range Slider
-const schema = {
-  volume: {
-    type: 'number',
-    minimum: 0,
-    maximum: 100
-  }
-};
-const uiSchema = {
-  volume: {
-    'ui:widget': 'range'
+#### Number Input with Range
+```json
+{
+  "schema": {
+    "type": "number",
+    "title": "Age",
+    "minimum": 0,
+    "maximum": 120
+  },
+  "uiSchema": {
+    "ui:widget": "number"
   }
-};
+}
+```
 
-// File Upload
-const uiSchema = {
-  documents: {
-    'ui:widget': 'file',
-    'ui:options': {
-      accept: '.pdf,.doc,.docx',
-      multiple: true
+#### Rating Widget
+```json
+{
+  "schema": {
+    "type": "number",
+    "title": "Rate your experience",
+    "minimum": 0,
+    "maximum": 5
+  },
+  "uiSchema": {
+    "ui:widget": "rating",
+    "ui:options": {
+      "count": 5,
+      "allowHalf": true
     }
   }
-};
+}
 ```
 
-#### Enhanced Standard Widgets
-
-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
-
-### Array Templates
-
-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
-
-## Central Event Orchestration System
-
-### Field-Level Event Handling
-
-```tsx
-import { ExtendedForm, type FormFieldEvent } from 'extended-dynamic-forms';
-
-<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);
-  }}
-/>
+#### 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"
+  }
+}
 ```
 
-### Webhook Integration
-
-Configure multiple webhook endpoints to receive real-time form events:
-
-```tsx
-import { ExtendedForm, type WebhookConfig } from 'extended-dynamic-forms';
-
-const webhookConfigs: WebhookConfig[] = [
-  {
-    url: 'https://api.yourapp.com/form-events',
-    method: 'POST',
-    events: ['change', 'blur'],  // Only trigger on change and blur
-    debounceMs: 500,             // Wait 500ms before sending
-    retries: 3,                  // Retry failed requests
-    timeout: 5000,               // 5 second timeout
-    headers: {
-      'Authorization': 'Bearer your-api-token',
-      'X-Form-ID': 'contact-form'
+#### Choice Widget (Radio Group)
+```json
+{
+  "schema": {
+    "type": "string",
+    "title": "Gender",
+    "enum": ["male", "female", "other"]
+  },
+  "uiSchema": {
+    "ui:widget": "choice",
+    "ui:options": {
+      "presenter": "radio"
     }
   }
-];
-
-<ExtendedForm
-  schema={schema}
-  uiSchema={uiSchema}
-  webhooks={webhookConfigs}
-/>
+}
 ```
 
-## V1 Conditional System (Deprecated)
-
-> ⚠️ **DEPRECATED**: The v1 conditional system is deprecated and will be removed in a future version. Use the Three Pillars v2 system for all new implementations.
-
-The v1 system uses imperative engines with O(M×N) performance for arrays. While still functional, it has significant limitations compared to v2.
-
-### Basic V1 Usage (Not Recommended)
-
-```tsx
-import { ExtendedForm } from 'extended-dynamic-forms';
-
-const conditionals = {
-  rules: [
-    {
-      conditions: { isStudent: true },
-      event: { type: "require", params: { field: ["studentId", "school"] } }
+#### Choice Widget (Checkbox Group - Multi-select)
+```json
+{
+  "schema": {
+    "type": "array",
+    "title": "Interests",
+    "items": {
+      "type": "string",
+      "enum": ["sports", "music", "reading", "travel"]
     },
-    {
-      conditions: { isStudent: false },
-      event: { type: "remove", params: { field: ["studentId", "school"] } }
+    "uniqueItems": true
+  },
+  "uiSchema": {
+    "ui:widget": "choice",
+    "ui:options": {
+      "presenter": "checkbox"
     }
-  ]
-};
-
-<ExtendedForm
-  schema={schema}
-  uiSchema={uiSchema}
-  conditionals={conditionals}
-/>
-```
-
-### Why Migrate to v2?
-
-- **Performance**: O(N) vs O(M×N) for arrays
-- **Maintainability**: Clear separation of concerns
-- **Type Safety**: Full TypeScript support
-- **Predictability**: No complex rule interactions
-- **Modern React**: Hooks-based architecture
-
-## API Reference
-
-### ExtendedFormProps
-
-```typescript
-interface ExtendedFormProps<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;
+  }
 }
 ```
 
-### Three Pillars v2 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' }
-      }))
+#### Date Picker
+```json
+{
+  "schema": {
+    "type": "string",
+    "title": "Date of Birth",
+    "format": "date"
+  },
+  "uiSchema": {
+    "ui:widget": "date",
+    "ui:options": {
+      "format": "DD/MM/YYYY",
+      "picker": "date"
     }
   }
-};
+}
 ```
 
-### 💼 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'
-        }
-      }))
+#### 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
     }
   }
-};
+}
 ```
 
-**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
-
-### 🌐 CMS & Integration Use Cases
+#### Color Picker
+```json
+{
+  "schema": {
+    "type": "string",
+    "title": "Favorite Color",
+    "format": "color"
+  },
+  "uiSchema": {
+    "ui:widget": "color"
+  }
+}
+```
 
-**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 });
+#### 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"
+      }
     }
-  });
-</script>
+  }
+}
 ```
 
-**Legacy System Modernization**
-- Drop-in replacement for static HTML forms
-- Progressive enhancement of existing forms
-- No-build deployment to production environments
-
-## Architecture
-
-Extended Dynamic Forms uses a layered architecture that cleanly extends RJSF:
-
-```
-┌─────────────────────────────────────────────────┐
-│     Three Pillars v2 (Conditional System)       │
-├─────────────────────────────────────────────────┤
-│          Application Layer (WizardForm)          │
-├─────────────────────────────────────────────────┤
-│      Event Layer (FormEventHub)                 │
-├─────────────────────────────────────────────────┤
-│   Component Layer (Widgets/Fields/Templates)    │
-├─────────────────────────────────────────────────┤
-│        Base Layer (@rjsf/antd)                  │
-└─────────────────────────────────────────────────┘
+#### Hidden Field
+```json
+{
+  "schema": {
+    "type": "string",
+    "title": "User ID"
+  },
+  "uiSchema": {
+    "ui:widget": "hidden"
+  }
+}
 ```
 
-## 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 | ⚠️ Focused on Conditionals/Wizards |
-| **Performance** | Standard | ✅ Optimized with Caching |
-| **Validation** | Basic | ✅ Dynamic + Custom Rules |
-| **Developer Tools** | Limited | ✅ Interactive Playground |
+### Widget Registration
 
-## 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
+Register custom widgets with ExtendedForm:
 
-```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
+```typescript
+import { ExtendedForm, customWidgets } from 'extended-dynamic-forms';
 
-# Start development with playground
-npm run dev                    # Launches interactive playground
-npm run playground            # Alternative playground command
+// Use all built-in widgets
+<ExtendedForm 
+  widgets={customWidgets}
+  schema={schema}
+  uiSchema={uiSchema}
+/>
 
-# 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
+// Or register specific widgets
+<ExtendedForm 
+  widgets={{
+    text: customWidgets.text,
+    date: customWidgets.date,
+    choice: customWidgets.choice
+  }}
+/>
 ```
 
-### 📦 Build Commands
+## Development
 
 ```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
-```
+# Development
+npm run dev              # Start playground
+npm run test             # Run tests
+npm run test:ui          # Test with UI
 
-### 🧪 Testing
+# Building
+npm run build            # Build library
+npm run build:vanilla    # Build standalone (currently broken - JsonLogic incompatible)
+npm run preview          # Preview build
 
-**Test Coverage**: Test suite focuses primarily on:
-- **Conditional Logic**: Comprehensive coverage for v1 and v2 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
+# Code Quality
+npm run lint             # ESLint
+npm run format           # Prettier
 ```
 
-### 🏗️ Architecture
+## Project Structure
 
-**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/                   # 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
+├── 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
 ```
 
-### 📚 Demo Categories
+## Examples
 
-> **Note**: Some playground demos may be outdated. The v1 conditional demo (`/playground/src/demos/conditionals/01-deprecated-v1-conditions.demo.tsx`) is deprecated and should not be used as a reference for new implementations.
+Interactive examples available at `/playground/src/demos/`:
 
-#### **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 Forms**: Australian Company Onboarding, Employee Onboarding
+- **Conditionals**: Dynamic visibility, validation, array handling
+- **Events**: Webhook integration, field tracking
+- **Widgets**: All available components
 
-#### **🧙‍♂️ 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
+Run `npm run dev` to explore examples.
 
-#### **🔗 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
+## Known Limitations
 
-#### **🎨 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
+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
 
-### 📱 Vanilla JavaScript Examples
+## TypeScript
 
-Complete standalone examples in `/examples/vanilla-js/`:
+Full TypeScript support with exported types:
 
-```html
-<!-- Basic Form -->
-basic-form.html          <!-- Simple contact form -->
-conditional-form.html    <!-- Dynamic field visibility -->
-wizard-form.html         <!-- Multi-step onboarding -->
+```typescript
+import {
+  ExtendedForm,
+  WizardForm,
+  UiRule,
+  SchemaRule,
+  ValidationRule,
+  JsonLogicRule,
+  FormEvent,
+  WebhookConfig
+} from 'extended-dynamic-forms';
 ```
 
-### 🔗 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 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)
-
-
+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.