extended-dynamic-forms 0.1.14 → 0.1.17

package/README.md

@@ -1,20 +1,19 @@
 # Extended Dynamic Forms
 
-A comprehensive extension of React JSON Schema Form (RJSF) v5 with shadcn/ui components, custom widgets, fields, layouts, and a powerful central event orchestration system with webhook capabilities.
+A comprehensive extension of React JSON Schema Form (RJSF) v6 with Ant Design components, custom widgets, fields, layouts, and a powerful central event orchestration system with webhook capabilities.
 
 ## Features
 
-- 🎨 **shadcn/ui Integration**: Built on top of @rjsf/shadcn for beautiful, accessible components
-- ✨ **Custom Widgets**: Color picker, date picker, file upload, range slider, rating stars
+- 🎨 **Ant Design Integration**: Built on @rjsf/antd with modern, accessible components
+- ✨ **Enhanced Widgets**: Color picker, date picker, file upload, range slider, rating widget, enhanced input controls
 - 🏗️ **Custom Fields**: Address, phone number, currency input with formatting
-- 📐 **Layout Components**: Vertical, horizontal, and grid layouts
+- 🧙‍♂️ **Wizard Forms**: Multi-step forms with automatic step detection, progress tracking, and navigation
 - 🎯 **Central Event Orchestration**: Unified system capturing all form field events (focus, blur, change)
 - 🔗 **Webhook Integration**: Configure multiple webhook endpoints with debouncing and retry logic
+- 🎭 **Advanced Conditional Logic**: Dynamic form behavior with JSON Rules Engine support and step-aware processing
 - 🔧 **Enhanced Form Events**: Before/after submit and validation hooks plus field-level events
-- 🚀 **Conditional Logic**: Show/hide fields, make fields required/optional based on complex conditions
 - 📦 **TypeScript Support**: Fully typed with comprehensive type definitions
 - ⚡ **Vite Powered**: Fast development and optimized builds
-- 🎯 **Tailwind CSS**: Utility-first styling with full customization
 - 🛡️ **Error Handling**: Robust error recovery and retry mechanisms
 - ⚡ **Performance Optimized**: Debouncing, queuing, and async processing
 
@@ -34,10 +33,9 @@ This package requires the following peer dependencies:
 {
   "react": "^18.0.0",
   "react-dom": "^18.0.0",
-  "@rjsf/core": "^5.15.0",
-  "@rjsf/utils": "^5.15.0",
-  "@rjsf/validator-ajv8": "^5.15.0",
-  "@rjsf/shadcn": "^0.1.0"
+  "@rjsf/core": "^5.0.0 || ^6.0.0-beta.10",
+  "@rjsf/utils": "^5.0.0 || ^6.0.0-beta.10",
+  "@rjsf/validator-ajv8": "^5.0.0 || ^6.0.0-beta.10"
 }
 ```
 
@@ -45,31 +43,51 @@ This package requires the following peer dependencies:
 
 ### CSS Requirements
 
-This package uses Tailwind CSS and shadcn/ui components. Make sure to include the required CSS in your application:
+This package uses Ant Design components. Import the CSS in your application:
 
 ```tsx
 // In your main entry file (e.g., App.tsx or index.tsx)
-import 'extended-dynamic-forms/dist/index.css';
+import 'extended-dynamic-forms/dist/style.css'; // Or your specific CSS entry point
 ```
 
-If you're using Tailwind CSS in your project, ensure your `tailwind.config.js` includes the package in the content array:
+## Quick Start
+
+### Simple Wizard Form (Recommended)
 
-```js
-module.exports = {
-  content: [
-    // ... your other content paths
-    "./node_modules/extended-dynamic-forms/**/*.{js,ts,jsx,tsx}",
-  ],
-  // ... rest of your config
+The `WizardForm` component automatically detects multi-step forms and handles navigation:
+
+```tsx
+import { WizardForm } from 'extended-dynamic-forms';
+import schema from './schema.json';
+import uiSchema from './ui-schema.json';
+import conditions from './conditions.json';
+import webhooks from './webhooks.json';
+
+function App() {
+  return (
+    <WizardForm
+      schema={schema}
+      uiSchema={uiSchema}
+      conditions={conditions}
+      webhooks={webhooks}
+      onSubmit={(data) => console.log('Submitted:', data)}
+    />
+  );
 }
 ```
 
-## Quick Start
+**WizardForm Features:**
+- ✅ Auto-detects wizard structure (properties starting with `STEP_`)
+- ✅ Creates progress tracking and navigation
+- ✅ Handles step-aware conditional logic
+- ✅ Manages form state and validation
+- ✅ Integrates webhooks for real-time events
 
-### Basic Form
+### Basic Form (Using ExtendedForm)
+
+For more control, use the `ExtendedForm` component directly:
 
 ```tsx
-import React from 'react';
 import { ExtendedForm } from 'extended-dynamic-forms';
 
 const schema = {
@@ -94,127 +112,76 @@ const uiSchema = {
 };
 
 function App() {
-  const handleSubmit = ({ formData }) => {
-    console.log('Form data:', formData);
-  };
-
-  const handleFieldChange = (event) => {
-    console.log(`Field ${event.fieldId} changed to:`, event.fieldValue);
-  };
-
   return (
     <ExtendedForm
       schema={schema}
       uiSchema={uiSchema}
-      onSubmit={handleSubmit}
-      onFieldChange={handleFieldChange}
+      onSubmit={({ formData }) => console.log(formData)}
     />
   );
 }
 ```
 
-### With Webhook Integration
-
-```tsx
-import React from 'react';
-import { ExtendedForm, WebhookConfig } from 'extended-dynamic-forms';
+## Custom Widgets
 
-const webhooks: WebhookConfig[] = [
-  {
-    url: 'https://your-api.com/webhooks/form-events',
-    events: ['change'],
-    debounceMs: 300,
-    headers: {
-      'Authorization': 'Bearer your-token'
-    }
-  }
-];
+### Available Widgets
 
-function App() {
-  return (
-    <ExtendedForm
-      schema={schema}
-      uiSchema={uiSchema}
-      webhooks={webhooks}
-      onSubmit={({ formData }) => {
-        console.log('Form submitted:', formData);
-      }}
-      onFieldFocus={(event) => {
-        console.log('Field focused:', event.fieldId);
-      }}
-    />
-  );
-}
-```
+The library includes enhanced versions of all standard RJSF widgets plus custom ones:
 
-## Custom Widgets
+#### Custom Widgets
 
-### Color Widget
 ```tsx
+// Color Picker
 const uiSchema = {
   favoriteColor: {
     'ui:widget': 'color'
   }
 };
-```
 
-### Date Widget
-```tsx
+// Rating Widget
 const uiSchema = {
-  birthDate: {
-    'ui:widget': 'date',
-    'ui:options': {
-      inputType: 'datetime-local', // or 'date', 'time'
-      minDate: '2000-01-01',
-      maxDate: '2025-12-31'
-    }
-  }
-};
-```
-
-### File Widget
-```tsx
-const uiSchema = {
-  documents: {
-    'ui:widget': 'file',
+  satisfaction: {
+    'ui:widget': 'rating',
     'ui:options': {
-      accept: '.pdf,.doc,.docx',
-      multiple: true
+      max: 10 // default is 5
     }
   }
 };
-```
 
-### Range Widget
-```tsx
+// Range Slider
 const schema = {
   volume: {
     type: 'number',
     minimum: 0,
-    maximum: 100,
-    multipleOf: 5
+    maximum: 100
   }
 };
-
 const uiSchema = {
   volume: {
     'ui:widget': 'range'
   }
 };
-```
 
-### Rating Widget
-```tsx
+// File Upload
 const uiSchema = {
-  satisfaction: {
-    'ui:widget': 'rating',
+  documents: {
+    'ui:widget': 'file',
     'ui:options': {
-      max: 10 // default is 5
+      accept: '.pdf,.doc,.docx',
+      multiple: 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
+
 ## Custom Fields
 
 ### Address Field
@@ -263,9 +230,8 @@ const uiSchema = {
 
 ## Array Fields
 
-Extended Dynamic Forms provides custom-styled array field templates using shadcn/ui components. Arrays automatically get styled add/remove buttons, reordering controls, and proper visual hierarchy.
+The library provides Ant Design-styled array field templates with enhanced functionality:
 
-### Basic Array Example
 ```tsx
 const schema = {
   type: 'object',
@@ -296,19 +262,15 @@ const uiSchema = {
 };
 ```
 
-### Array Features
-- 🎨 **Styled with shadcn/ui Card components**: Clean, modern appearance
-- ➕ **Add button**: Prominent "Add [Item]" button at the bottom
-- 🗑️ **Remove buttons**: Individual remove buttons for each item
-- 🔄 **Reordering**: Move items up/down with chevron buttons
-- 📱 **Responsive**: Mobile-friendly controls
-
-Arrays work seamlessly with all other custom widgets and fields in the library, including within nested structures.
+**Array Features:**
+- 🎨 **Ant Design Cards**: Clean, modern appearance
+- ➕ **Add Button**: Prominent "Add [Item]" button
+- 🗑️ **Remove Buttons**: Individual remove buttons for each item
+- 🔄 **Reordering**: Move items up/down with controls
+- 📱 **Responsive**: Mobile-friendly design
 
 ## Central Event Orchestration System
 
-The library features a comprehensive event orchestration system that captures all form field events and enables webhook integration.
-
 ### Field-Level Event Handling
 
 ```tsx
@@ -322,29 +284,15 @@ import { ExtendedForm, FormFieldEvent } from 'extended-dynamic-forms';
   // Field-level event handlers
   onFieldFocus={(event: FormFieldEvent) => {
     console.log(`Field ${event.fieldId} focused:`, event.fieldValue);
-    // Track user interactions for analytics
   }}
   
   onFieldChange={(event: FormFieldEvent) => {
     console.log(`Field ${event.fieldId} changed:`, event.fieldValue);
     // Real-time validation or processing
-    if (event.fieldId === 'root_email') {
-      validateEmailRealTime(event.fieldValue);
-    }
   }}
   
   onFieldBlur={(event: FormFieldEvent) => {
     console.log(`Field ${event.fieldId} blurred:`, event.fieldValue);
-    // Format field values or trigger validation
-  }}
-  
-  // Traditional form-level events (still supported)
-  beforeSubmit={async (data) => {
-    return { ...data, timestamp: Date.now() };
-  }}
-  
-  afterSubmit={async (data) => {
-    console.log('Form submitted:', data);
   }}
 />
 ```
@@ -366,17 +314,7 @@ const webhookConfigs: WebhookConfig[] = [
     timeout: 5000,               // 5 second timeout
     headers: {
       'Authorization': 'Bearer your-api-token',
-      'X-Form-ID': 'contact-form',
-      'Content-Type': 'application/json'
-    }
-  },
-  {
-    url: 'https://analytics.yourapp.com/field-interactions',
-    events: ['focus'],           // Track focus events for analytics
-    debounceMs: 0,              // No debouncing for real-time analytics
-    retries: 1,
-    headers: {
-      'X-Analytics-Key': 'your-analytics-key'
+      'X-Form-ID': 'contact-form'
     }
   }
 ];
@@ -385,20 +323,11 @@ const webhookConfigs: WebhookConfig[] = [
   schema={schema}
   uiSchema={uiSchema}
   webhooks={webhookConfigs}
-  
-  onFieldChange={(event) => {
-    // Local processing alongside webhooks
-    if (event.fieldId === 'root_email') {
-      setEmailValid(validateEmail(event.fieldValue));
-    }
-  }}
 />
 ```
 
 ### Webhook Payload Structure
 
-Your webhook endpoints will receive payloads in this format:
-
 ```json
 {
   "event": {
@@ -422,232 +351,151 @@ Your webhook endpoints will receive payloads in this format:
 }
 ```
 
-### Advanced Features
+## Advanced Conditional Logic System
 
-- **Debouncing**: Prevent webhook spam on rapid input changes
-- **Retry Logic**: Automatic retry with exponential backoff for failed requests
-- **Error Isolation**: Webhook failures don't block form functionality
-- **Event Filtering**: Configure which events trigger each webhook
-- **Queue Management**: Asynchronous processing with proper ordering
-- **Custom Headers**: Add authentication, tracking, or custom metadata
+The library includes a comprehensive conditional logic system with support for JSON Rules Engine format and step-aware processing for wizard forms.
 
-## Layouts
+### Basic Conditional Logic
 
 ```tsx
-import { VerticalLayout, HorizontalLayout, GridLayout } from 'extended-dynamic-forms';
-
-// Vertical Layout
-<VerticalLayout spacing="medium">
-  <input />
-  <button />
-</VerticalLayout>
-
-// Horizontal Layout
-<HorizontalLayout spacing="large" align="center">
-  <label />
-  <input />
-</HorizontalLayout>
-
-// Grid Layout
-<GridLayout columns={3} gap="medium">
-  <Card />
-  <Card />
-  <Card />
-</GridLayout>
-```
-
-## Use Cases
+import { ExtendedForm } from 'extended-dynamic-forms';
+import { smartTransformJsonRulesEngine } from 'extended-dynamic-forms';
 
-### Real-time Form Analytics
-```tsx
-const webhooks: WebhookConfig[] = [
+const conditions = [
+  {
+    conditions: {
+      isStudent: true
+    },
+    event: {
+      type: "show",
+      params: { field: ["studentId", "school"] }
+    }
+  },
   {
-    url: 'https://analytics.yourapp.com/form-interactions',
-    events: ['focus', 'blur', 'change'],
-    debounceMs: 100,
-    headers: { 'X-Analytics-Token': 'your-token' }
+    conditions: {
+      isStudent: false
+    },
+    event: {
+      type: "hide",
+      params: { field: ["studentId", "school"] }
+    }
   }
 ];
 
-// Track user behavior, field completion rates, abandonment points
-```
-
-### Auto-save & Recovery
-```tsx
-<ExtendedForm
-  schema={schema}
-  onFieldChange={(event) => {
-    // Auto-save to localStorage or server
-    localStorage.setItem(`form_${event.fieldId}`, event.fieldValue);
-  }}
-  webhooks={[{
-    url: 'https://api.yourapp.com/autosave',
-    events: ['change'],
-    debounceMs: 2000 // Save every 2 seconds
-  }]}
-/>
-```
+// Transform JSON Rules Engine format to internal format
+const transformedRules = smartTransformJsonRulesEngine(conditions);
 
-### Real-time Validation
-```tsx
-<ExtendedForm
-  schema={schema}
-  onFieldBlur={async (event) => {
-    if (event.fieldId === 'root_email') {
-      const isValid = await validateEmailWithAPI(event.fieldValue);
-      setEmailValidation(isValid);
-    }
-  }}
-  webhooks={[{
-    url: 'https://validation.yourapp.com/validate',
-    events: ['blur'],
-    headers: { 'Content-Type': 'application/json' }
-  }]}
-/>
-```
+const conditionalConfig = {
+  rules: transformedRules,
+  onSchemaChange: ({ schema, uiSchema }) => {
+    console.log('Schema updated:', { schema, uiSchema });
+  }
+};
 
-### Progressive Form Enhancement
-```tsx
-<ExtendedForm
+<ExtendedForm 
   schema={schema}
-  onFieldChange={(event) => {
-    // Show additional fields based on user input
-    if (event.fieldId === 'root_country' && event.fieldValue === 'US') {
-      setShowStateField(true);
-    }
-  }}
+  uiSchema={uiSchema}
+  conditionals={conditionalConfig}
+  onChange={handleChange}
 />
 ```
 
-## Conditional Forms
+### Wizard Form with Step-Aware Conditionals
 
-Extended Dynamic Forms includes powerful conditional logic capabilities that allow you to:
-- Show/hide fields based on other field values
-- Make fields required/optional conditionally
-- Enable/disable fields based on complex conditions
-- Support multiple conditions with AND/OR logic
-
-### Basic Conditional Example
+The `WizardForm` component automatically handles step-aware conditional processing:
 
 ```tsx
-import { ConditionalForm, ConditionalRule } from 'extended-dynamic-forms';
+import { WizardForm } from 'extended-dynamic-forms';
 
-const schema = {
+// Schema with step structure
+const wizardSchema = {
   type: 'object',
   properties: {
-    accountType: {
-      type: 'string',
-      enum: ['personal', 'business'],
-      title: 'Account Type'
+    STEP_PERSONAL: {
+      type: 'object',
+      title: 'Personal Information',
+      properties: {
+        name: { type: 'string', title: 'Name' },
+        isStudent: { type: 'boolean', title: 'Are you a student?' },
+        studentId: { type: 'string', title: 'Student ID' }
+      }
     },
-    firstName: { type: 'string', title: 'First Name' },
-    lastName: { type: 'string', title: 'Last Name' },
-    businessName: { type: 'string', title: 'Business Name' },
-    taxId: { type: 'string', title: 'Tax ID' }
+    STEP_CONTACT: {
+      type: 'object',
+      title: 'Contact Information',
+      properties: {
+        email: { type: 'string', format: 'email' },
+        phone: { type: 'string' }
+      }
+    }
   }
 };
 
-const conditionalRules: ConditionalRule[] = [
+// Conditions that reference step fields
+const stepConditions = [
   {
     conditions: {
-      accountType: { equals: 'personal' }
+      "STEP_PERSONAL.isStudent": false
     },
     event: {
-      type: 'show',
-      params: { fields: ['firstName', 'lastName'] }
-    }
-  },
-  {
-    conditions: {
-      accountType: { equals: 'business' }
-    },
-    event: {
-      type: 'show',
-      params: { fields: ['businessName', 'taxId'] }
+      type: "hide",
+      params: { field: "STEP_PERSONAL.studentId" }
     }
   }
 ];
 
-<ConditionalForm
-  schema={schema}
-  conditionalRules={conditionalRules}
+<WizardForm
+  schema={wizardSchema}
+  uiSchema={uiSchema}
+  conditions={stepConditions}
   onSubmit={handleSubmit}
 />
 ```
 
-### Complex Conditions
+### Supported Conditional Actions
+The conditional engine directly supports the following actions (defined in `ConditionalActions.ts`):
+- `show` - Makes fields visible (adds them back to the schema if previously removed).
+- `remove` - Removes fields from the schema and uiSchema (effectively hides them).
+- `enable` / `disable` - Enable or disable fields.  
+- `require` / `optional` - Make fields required or optional.
+- `uiAppend` - Appends to existing uiSchema properties (e.g., concatenates classNames, merges `ui:order`).
+- `uiOverride` - Overrides specific uiSchema fields.
+- `uiReplace` - Replaces entire uiSchema sections.
+- Custom actions - Register your own conditional actions
+    
+**Note on `smartTransformJsonRulesEngine`:**
+When providing conditions in the JSON Rules Engine format (e.g., to `WizardForm` or by calling `smartTransformJsonRulesEngine` directly):
+- Input rules with `event.type: "show"` are typically converted into an internal `remove` action with *inverted* conditions.
+- Input rules with `event.type: "hide"` are converted into an internal `remove` action.
+- Input rules with `event.type: "required"` or `"optional"` are transformed into internal `require` or `optional` actions, respectively.
+
+### JSON Rules Engine Support
+
+The library includes transformation utilities for json-rules-engine format:
 
 ```tsx
-const complexRules: ConditionalRule[] = [
+import { smartTransformJsonRulesEngine } from 'extended-dynamic-forms';
+
+const jsonRulesEngineFormat = [
   {
-    // Show state field when country is US AND has address
     conditions: {
       all: [
-        { country: { equals: 'US' } },
-        { hasAddress: { equals: true } }
-      ]
-    },
-    event: {
-      type: 'show',
-      params: { fields: ['state', 'zipCode'] }
-    }
-  },
-  {
-    // Show verification for high income personal OR business accounts
-    conditions: {
-      any: [
-        {
-          all: [
-            { accountType: { equals: 'personal' } },
-            { income: { greaterThan: 100000 } }
-          ]
-        },
         {
-          accountType: { equals: 'business' }
+          fact: "age",
+          operator: "greaterThanInclusive", 
+          value: 18
         }
       ]
     },
     event: {
-      type: 'require',
-      params: { fields: ['verificationDocument'] }
+      type: "show",
+      params: { field: "driverLicense" }
     }
   }
 ];
-```
-
-### Available Conditions
-
-- `equals` / `notEquals` - Exact value matching
-- `greaterThan` / `lessThan` - Numeric comparisons
-- `greaterThanOrEqual` / `lessThanOrEqual` - Inclusive numeric comparisons
-- `contains` / `notContains` - String contains
-- `in` / `notIn` - Value in array
-- `empty` / `notEmpty` - Check if field has value
-
-### Available Events
 
-- `show` / `hide` - Control field visibility
-- `require` / `unrequire` - Make fields required/optional
-- `enable` / `disable` - Enable/disable fields
-
-### Combining with Webhooks
-
-```tsx
-<ConditionalForm
-  schema={schema}
-  conditionalRules={rules}
-  webhooks={[
-    {
-      url: 'https://api.example.com/validate',
-      events: ['change'],
-      debounceMs: 500
-    }
-  ]}
-  onFieldChange={(event) => {
-    // Local handling alongside conditional logic
-    console.log('Field changed:', event);
-  }}
-/>
+// Automatically transforms operators and structure
+const internalRules = smartTransformJsonRulesEngine(jsonRulesEngineFormat);
 ```
 
 ## API Reference
@@ -660,17 +508,20 @@ interface ExtendedFormProps extends FormProps {
   schema: RJSFSchema;
   uiSchema?: UiSchema;
   formData?: any;
-  onSubmit?: (data: any, event: any) => void;
+  onSubmit?: (data: import('@rjsf/utils').IChangeEvent<any, RJSFSchema, any>, event?: React.FormEvent<HTMLFormElement>) => void;
   onChange?: (data: any) => void;
-  
+      
   // Field-level event handlers
   onFieldFocus?: (event: FormFieldEvent) => Promise<void> | void;
-  onFieldBlur?: (event: FormFieldEvent) => Promise<void> | void;
+  onFieldBlur?: (event: FormFieldEvent) => Promise<void> | void;  
   onFieldChange?: (event: FormFieldEvent) => Promise<void> | void;
   
   // Webhook configuration
   webhooks?: WebhookConfig[];
   
+  // Conditional logic
+  conditionals?: ConditionalConfig;
+  
   // Form lifecycle events
   beforeSubmit?: (data: any) => Promise<any> | any;
   afterSubmit?: (data: any) => Promise<void> | void;
@@ -679,6 +530,35 @@ interface ExtendedFormProps extends FormProps {
 }
 ```
 
+### WizardFormProps
+
+```typescript
+interface WizardFormProps {
+  // Required JSON configurations
+  schema: any;
+  uiSchema: any;
+  conditions?: any[];
+  webhooks?: WebhookConfig[];
+
+  // Optional initial data
+  formData?: any;
+
+  // Event handlers
+  onSubmit?: (data: any) => void;
+  onStepChange?: (step: number, data: any) => void;
+  onFieldFocus?: (event: any) => void;
+  onFieldBlur?: (event: any) => void;
+  onFieldChange?: (event: any) => void;
+
+  // UI customization
+  showProgressBar?: boolean;
+  showStepDescription?: boolean;
+  submitButtonText?: string;
+  liveValidate?: boolean;
+  showErrorList?: boolean;
+}
+```
+
 ### FormFieldEvent
 
 ```typescript
@@ -707,67 +587,6 @@ interface WebhookConfig {
 }
 ```
 
-### ConditionalRule
-
-```typescript
-interface ConditionalRule {
-  conditions: {
-    [fieldPath: string]: FieldCondition;
-    all?: Array<{ [fieldPath: string]: FieldCondition }>;
-    any?: Array<{ [fieldPath: string]: FieldCondition }>;
-  };
-  event: {
-    type: 'show' | 'hide' | 'require' | 'unrequire' | 'disable' | 'enable';
-    params: {
-      fields: string[];
-    };
-  };
-}
-
-interface FieldCondition {
-  equals?: any;
-  notEquals?: any;
-  greaterThan?: number;
-  lessThan?: number;
-  greaterThanOrEqual?: number;
-  lessThanOrEqual?: number;
-  contains?: string;
-  notContains?: string;
-  in?: any[];
-  notIn?: any[];
-  empty?: boolean;
-  notEmpty?: boolean;
-}
-```
-
-## Utility Functions
-
-```tsx
-import { formDataUtils, schemaUtils, validationUtils } from 'extended-dynamic-forms';
-
-// Form Data Utils
-const clonedData = formDataUtils.cloneFormData(formData);
-const mergedData = formDataUtils.mergeFormData(current, updates);
-const nestedValue = formDataUtils.getNestedValue(data, 'user.address.city');
-const updatedData = formDataUtils.setNestedValue(data, 'user.name', 'John');
-const cleanData = formDataUtils.removeEmptyValues(data);
-
-// Schema Utils
-const required = schemaUtils.getRequiredFields(schema);
-const isRequired = schemaUtils.isFieldRequired(schema, 'email');
-const fieldSchema = schemaUtils.getFieldSchema(schema, 'user.address');
-const merged = schemaUtils.mergeSchemas(schema1, schema2);
-const paths = schemaUtils.getAllFieldPaths(schema);
-
-// Validation Utils
-const isEmail = validationUtils.isValidEmail('test@example.com');
-const isPhone = validationUtils.isValidPhone('(555) 123-4567');
-const isUrl = validationUtils.isValidUrl('https://example.com');
-const isDate = validationUtils.isValidDate('2024-01-01');
-const inRange = validationUtils.isInRange(5, 1, 10);
-const message = validationUtils.getValidationMessage('required');
-```
-
 ## Development
 
 ```bash
@@ -787,6 +606,53 @@ npm test
 npm run lint
 ```
 
+## Examples
+
+The library includes comprehensive examples demonstrating all features. Run the development server to see them:
+
+```bash
+npm run dev
+```
+
+Key examples include:
+
+- **Simple Wizard Example**: Multi-step company onboarding form
+- **Conditional Logic Demo**: Dynamic field visibility and requirements
+- **Event System Demo**: Real-time form analytics and webhooks
+- **Custom Widget Showcase**: All available widgets and their options
+
+## Use Cases
+
+### Real-time Form Analytics
+- Track user interactions and field completion rates
+- Monitor form abandonment points
+- Capture detailed user behavior data
+
+### Auto-save & Recovery
+- Automatically save form data as users type
+- Implement form recovery after page reload
+- Background data synchronization
+
+### Dynamic Form Behavior
+- Show/hide fields based on user input
+- Change validation rules dynamically
+- Progressive form enhancement
+
+### Multi-step Workflows
+- Complex onboarding processes
+- Survey and questionnaire systems
+- Application and registration forms
+
+## Architecture
+
+The library is built on three core principles:
+
+1. **Wrapper Architecture**: Extends RJSF v6 without breaking existing functionality
+2. **Central Event Orchestration**: All form interactions flow through a unified event system
+3. **Conditional Logic Engine**: Dynamic schema transformations with comprehensive rule support
+
+For detailed architectural information, see the [Developer Guide](./DEVELOPER_GUIDE.md).
+
 ## License
 
-MIT
+MIT