extended-dynamic-forms 0.2.0 → 0.2.1

package/README.md

@@ -13,7 +13,6 @@
 **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
@@ -22,7 +21,7 @@
 
 **A revolutionary extension library for [React JSON Schema Form (RJSF)](https://github.com/rjsf-team/react-jsonschema-form)** that transforms schema-driven forms into sophisticated, enterprise-ready applications with O(N) performance and professional UI components.
 
-Built on top of the excellent RJSF v6 foundation, this library introduces the **Three Pillars v2 Architecture** for conditional logic, multi-step wizard orchestration, central event systems with webhook integration, and a comprehensive suite of 25+ Ant Design components. 
+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)
@@ -35,7 +34,7 @@ Built on top of the excellent RJSF v6 foundation, this library introduces the **
 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
+- **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
 
@@ -49,17 +48,16 @@ While [RJSF](https://github.com/rjsf-team/react-jsonschema-form) provides an exc
 - **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
+### 🚀 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 vs v1's O(M×N)
+- **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`
 
@@ -88,7 +86,7 @@ const uiRules: UiRule[] = [{
 - **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
+- Supports Three Pillars architecture with JsonLogic conditions
 
 **Step-Aware Conditional Logic**
 
@@ -111,7 +109,7 @@ const schema = {
   }
 };
 
-// Use v2 UiRules with JsonLogic to handle step-aware conditionals
+// Use UiRules with JsonLogic to handle step-aware conditionals
 const uiRules: UiRule[] = [{
   name: 'Show SSN only for US Citizens in Personal step',
   condition: {
@@ -130,6 +128,7 @@ const uiRules: UiRule[] = [{
 - 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
@@ -185,25 +184,7 @@ const uiRules: UiRule[] = [{
 
 **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' } }
-      }
-    ]
-  }
-});
-```
+- For JsonLogic benefits, you must use the React-based API
 
 **Perfect for:**
 - WordPress/Drupal integrations
@@ -248,7 +229,7 @@ pnpm add extended-dynamic-forms
 
 ### Peer Dependencies
 
-**Current Version**: `0.2.0` - Built for **RJSF v6** with Three Pillars v2 architecture (JsonLogic-only).
+**Current Version**: `0.2.0` - Built for **RJSF v6** with Three Pillars architecture (JsonLogic-only).
 
 ```json
 {
@@ -258,7 +239,7 @@ pnpm add extended-dynamic-forms
 }
 ```
 
-> **React 19 Support**: This library supports both React 18 and React 19. See [REACT-19-COMPATIBILITY.md](./REACT-19-COMPATIBILITY.md) for migration details.
+> **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+
@@ -270,7 +251,7 @@ pnpm add extended-dynamic-forms
 
 **Additional Dependencies**:
 - `dayjs`: ^1.11.13 (Date handling)
-- `json-rules-engine-simplified`: ^0.2.0 (v1 conditional logic)
+- `json-rules-engine-simplified`: ^0.2.0
 
 > **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.
 
@@ -315,18 +296,18 @@ function App() {
 }
 ```
 
-## Three Pillars v2 Architecture with JsonLogic (Required Approach)
+## Three Pillars 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.
+> ⚠️ **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 v2 system with JsonLogic provides superior performance, cleaner separation of concerns, and better security. It consists of three independent pillars:
+The Three Pillars 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
+// 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
@@ -463,11 +444,11 @@ function MyForm({ schema }) {
 
 #### **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.
+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**: Unlike v1's wildcard expansion, no rules are multiplied by array size
+- **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.
@@ -505,7 +486,7 @@ const uiSchema = {
 // ❌ Traditional approach: O(M×N) - Rules × Array Items
 // With 10 rules and 50 directors = 500 evaluations
 
-// ✅ v2 approach: O(N) - Per-item evaluation  
+// ✅ Our approach: O(N) - Per-item evaluation  
 // With 50 directors = 50 evaluations (regardless of rule complexity)
 ```
 
@@ -559,7 +540,7 @@ function MyForm() {
 
 ### JsonLogic Conditions (Required)
 
-As of v0.2.0, v2 ONLY supports JsonLogic conditions for security and maintainability:
+As of v0.2.0, ONLY JsonLogic conditions are supported for security and maintainability:
 
 ```tsx
 import { JsonLogicRule, UiRule } from 'extended-dynamic-forms/conditionals/v2';
@@ -588,7 +569,7 @@ const complexRule: UiRule = {
 
 ### Simple Wizard Form (Recommended)
 
-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:
+The `WizardForm` component automatically detects multi-step forms and handles navigation. It fully supports conditional logic through the Three Pillars architecture:
 
 ```tsx
 import { useState } from 'react';
@@ -598,7 +579,7 @@ import schema from './schema.json';
 import baseUiSchema from './ui-schema.json';
 import webhooks from './webhooks.json';
 
-// Example: v2 Three Pillars approach with JsonLogic (required)
+// Example: Three Pillars approach with JsonLogic (required)
 const uiRules: UiRule[] = [
   {
     name: 'Show tax ID in company step when listed',
@@ -635,28 +616,9 @@ function App() {
   );
 }
 
-// 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" } }
-  }
-];
-
-// 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)}
-/>
 ```
 
-### Basic Form with Three Pillars v2
+### Basic Form with Three Pillars
 
 ```tsx
 import { ExtendedForm } from 'extended-dynamic-forms';
@@ -801,73 +763,257 @@ import { ExtendedForm, type FormFieldEvent } from 'extended-dynamic-forms';
 />
 ```
 
-### Webhook Integration
+### Enhanced Webhook Integration
 
-Configure multiple webhook endpoints to receive real-time form events:
+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, type WebhookConfig } from 'extended-dynamic-forms';
+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'],  // Only trigger on change and blur
-    debounceMs: 500,             // Wait 500ms before sending
+    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
+    }
   }
 ];
 
+// 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);
+  }}
+/>
+
+// 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');
+  }}
 />
 ```
 
-## V1 Conditional System (Deprecated)
+#### Webhook Event Types and Payloads
 
-> ⚠️ **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.
+All webhook events follow a standardized payload structure with common fields plus event-specific data:
 
-The v1 system uses imperative engines with O(M×N) performance for arrays. While still functional, it has significant limitations compared to v2.
+##### 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'
+}
+```
 
-### Basic V1 Usage (Not Recommended)
+##### Submit Event
+```typescript
+// Triggered after successful form submission
+{
+  eventType: 'submit',
+  formData: {
+    name: 'John Doe',
+    email: 'john@example.com',
+    // ... all submitted data
+  },
+  timestamp: 1234567890123,
+  source: 'extended-dynamic-forms'
+}
+```
 
-```tsx
-import { ExtendedForm } from 'extended-dynamic-forms';
+##### Step Change Event (WizardForm only)
+```typescript
+// Triggered when user navigates between wizard steps
+{
+  eventType: 'stepChange',
+  fromStep: 0,  // Previous step index
+  toStep: 1,    // New step index
+  formData: { /* current form data */ },
+  timestamp: 1234567890123,
+  source: 'extended-dynamic-forms'
+}
+```
 
-const conditionals = {
-  rules: [
+##### Validation Error Event
+```typescript
+// Triggered when form validation fails
+{
+  eventType: 'validationError',
+  errors: [
     {
-      conditions: { isStudent: true },
-      event: { type: "require", params: { field: ["studentId", "school"] } }
+      property: '.email',
+      message: 'Email is required',
+      name: 'required',
+      stack: '.email Email is required',
+      schemaPath: '#/properties/email'
     },
     {
-      conditions: { isStudent: false },
-      event: { type: "remove", params: { field: ["studentId", "school"] } }
+      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'
     }
-  ]
+  ],
+  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
+  }
+};
+
+// 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'
+  }
+};
+```
+
+##### 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' }
+      });
+    }
+    
+    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
-  schema={schema}
-  uiSchema={uiSchema}
-  conditionals={conditionals}
+  webhooks={[primaryWebhook, fallbackWebhook]}
+  onWebhookError={(webhook, event, error) => {
+    if (webhook.url === primaryWebhook.url) {
+      console.log('Primary webhook failed, fallback will handle');
+    }
+    
+    // Store locally for later sync
+    localStorage.setItem(`pending-${Date.now()}`, JSON.stringify(event));
+  }}
 />
 ```
 
-### 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
 
@@ -890,8 +1036,11 @@ interface ExtendedFormProps<T = any, S extends RJSFSchema = RJSFSchema, F = any>
   // Webhook configuration
   webhooks?: WebhookConfig[];
   
-  // Conditional logic (v1 - deprecated)
-  conditionals?: ConditionalConfig;
+  // 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;
@@ -901,7 +1050,69 @@ interface ExtendedFormProps<T = any, S extends RJSFSchema = RJSFSchema, F = any>
 }
 ```
 
-### Three Pillars v2 Hooks
+### 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;
+}
+```
+
+### 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;
+  }>;
+}
+```
+
+### Three Pillars Hooks
 
 ```typescript
 // UI Logic Pillar
@@ -1055,7 +1266,7 @@ Extended Dynamic Forms uses a layered architecture that cleanly extends RJSF:
 |---------|------------|----------------------|
 | **Form Generation** | ✅ JSON Schema | ✅ Enhanced JSON Schema |
 | **UI Components** | Basic HTML | ✅ Comprehensive Ant Design Suite |
-| **Conditional Logic** | ❌ Manual | ✅ Three Pillars v2 (O(N)) |
+| **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 |
@@ -1108,7 +1319,7 @@ npm run serve:examples     # Serve vanilla JS examples
 ### 🧪 Testing
 
 **Test Coverage**: Test suite focuses primarily on:
-- **Conditional Logic**: Comprehensive coverage for v1 and v2 systems (16+ test files)
+- **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
@@ -1133,7 +1344,7 @@ npm run test -- --grep "array"        # Test array handling
 src/
 ├── ExtendedForm.tsx          # Main form wrapper
 ├── WizardForm.tsx           # Multi-step orchestrator
-├── conditionals/            # v1 + v2 conditional systems
+├── conditionals/            # Conditional systems
 │   ├── v2/                 # Three Pillars architecture
 │   └── DynamicArrayConditionalEngine.ts
 ├── events/                  # Central event orchestration
@@ -1157,13 +1368,12 @@ npm run playground
 
 ### 📚 Demo Categories
 
-> **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.
+> **Note**: Some playground demos may be outdated.
 
-#### **Three Pillars v2 Demonstrations**
+#### **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
-- **Migration Examples**: Automated v1-to-v2 rule conversion
 
 #### **🧙‍♂️ Wizard Form Showcases**
 - **Australian Company Onboarding**: 5-step enterprise form with:
@@ -1176,7 +1386,9 @@ npm run playground
 #### **🔗 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
+- **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
@@ -1198,12 +1410,128 @@ wizard-form.html         <!-- Multi-step onboarding -->
 
 - **[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
+- **[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)
+```
+
+To take advantage of new event types:
+
+```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
+};
+
+// 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
+};
+```
+
+#### For New Implementations
+
+If you're implementing webhooks for the first time, consider these patterns:
+
+```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
+};
+```
+
+#### Using Webhook Status Callbacks
+
+The new webhook status callbacks provide visibility into webhook processing:
+
+```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);
+  }}
+/>
+```
+
+#### 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)