@ilife-tech/react-application-flow-renderer 1.0.68 → 1.0.70

package/README.md

@@ -1,1928 +1,1928 @@
-# React Dynamic Form Renderer
-
-A powerful and flexible React package for rendering dynamic forms with advanced validation, conditional logic, and third-party API integration capabilities.
-
-[![npm version](https://img.shields.io/npm/v/@ilife-tech/react-application-flow-renderer.svg)](https://www.npmjs.com/package/@ilife-tech/react-application-flow-renderer)
-[![license](https://img.shields.io/npm/l/@ilife-tech/react-application-flow-renderer.svg)](https://github.com/ilife-technologies/react-dynamic-form-renderer/blob/main/LICENSE)
-
-## Table of Contents
-
-- [Features](#features)
-- [Prerequisites](#prerequisites)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Form Schema Structure](#form-schema-structure)
-- [API Integration](#api-integration)
-- [Props Reference](#props-reference)
-- [Field Types](#field-types)
-- [Advanced Configuration](#advanced-configuration)
-- [Performance & Engine Options](#performance--engine-options)
-- [Troubleshooting](#troubleshooting)
-- [Examples & Best Practices](#examples--best-practices)
-
-## Features
-
-### Core Capabilities
-
-- **Schema-Driven Forms:** Generate complex forms from JSON schema
-- **Dynamic Validation:** Client and server-side validation support
-- **Conditional Logic:** Show/hide fields based on advanced rule conditions
-- **Third-Party API Integration:** Seamless integration with external APIs
-- **Nested Forms:** Support for complex, nested form structures
-- **Responsive Design:** Mobile-friendly with customizable breakpoints
-- **Accessibility:** WCAG 2.1 compliant components
-
-## Prerequisites
-
-- React 18+
-- Node.js 20+
-- npm 10+ or Yarn
-- Browser support: Latest versions of Chrome, Firefox, Safari, and Edge
-
-## Installation
-
-```bash
-# Using npm
-npm install @ilife-tech/react-application-flow-renderer
-
-# Using yarn
-yarn add @ilife-tech/react-application-flow-renderer
-```
-
-## Quick Start
-
-### Basic Implementation
-
-```jsx
-import React, { useState } from 'react';
-import DynamicForm from '@ilife-tech/react-application-flow-renderer';
-
-const App = () => {
-  // Form schema definition
-  const questionGroups = [
-    {
-      groupId: 'personalInfo',
-      groupName: 'Personal Information',
-      questions: [
-        {
-          questionId: 'fullName',
-          questionType: 'text',
-          label: 'Full Name',
-          validation: { required: true },
-        },
-        {
-          questionId: 'email',
-          questionType: 'email',
-          label: 'Email Address',
-          validation: { required: true, email: true },
-        },
-      ],
-    },
-  ];
-
-  // Action buttons configuration
-  const actionSchema = [
-    { text: 'Submit', action: 'submit' },
-    { text: 'Cancel', action: 'cancel' },
-  ];
-
-  // Form submission handler
-  const handleSubmit = (formState, action) => {
-    console.log('Form submitted:', formState.values);
-    console.log('Action:', action);
-  };
-
-  return (
-    <DynamicForm
-      questionGroups={questionGroups}
-      actionSchema={actionSchema}
-      onSubmit={handleSubmit}
-    />
-  );
-};
-```
-
-### Real-World Example
-
-Below is a comprehensive real-world implementation showcasing advanced features like API integration, state management, and theming:
-
-```jsx
-import React, { useState, useEffect, useCallback, useMemo } from 'react';
-import SectionListRenderer from '@ilife-tech/react-section-renderer';
-import { DynamicForm } from '@ilife-tech/react-application-flow-renderer';
-
-// Constants and configuration
-const API_CONFIG = {
-  BASE_URL: process.env.REACT_APP_API_BASE_URL || '<API_BASE_URL>',
-  ENDPOINTS: {
-    STORE_VENDOR: '<API_ENDPOINT>',
-  },
-  MAX_API_ATTEMPTS: 8,
-};
-
-const INITIAL_QUESTIONS = [
-  {
-    name: 'userToken',
-    value: process.env.REACT_APP_USER_TOKEN || '<USER_TOKEN>',
-  },
-  { name: 'user', value: '<USER_TYPE>' },
-  { name: 'productName', value: '<PRODUCT_NAME>' },
-  { name: 'stateName', value: '<STATE_NAME>' },
-];
-
-// API configuration for third-party integrations
-const apiConfig = {
-  googlePlaces: {
-    apiKey: process.env.REACT_APP_GOOGLE_PLACES_API_KEY,
-    options: {
-      minSearchLength: 3,
-      debounceTime: 300,
-      componentRestrictions: {
-        country: process.env.REACT_APP_GOOGLE_PLACES_REGION || 'US',
-      },
-      types: ['address'],
-      fields: ['address_components', 'formatted_address', 'geometry', 'place_id'],
-      maxRequestsPerSecond: 10,
-      maxRequestsPerDay: 1000,
-      language: process.env.REACT_APP_GOOGLE_PLACES_LANGUAGE,
-      region: process.env.REACT_APP_GOOGLE_PLACES_REGION,
-    },
-  },
-  customApi: {
-    baseUrl: process.env.REACT_APP_CUSTOM_API_BASE_URL,
-    headers: {
-      Authorization: process.env.REACT_APP_AUTH_TOKEN,
-      'Carrier-Auth': process.env.REACT_APP_CARRIER_AUTH,
-    },
-  },
-};
-
-// Theme configuration
-const THEME = {
-  breakpoints: {
-    mobile: '@media (max-width: 480px)',
-    tablet: '@media (min-width: 481px) and (max-width: 768px)',
-    desktop: '@media (min-width: 769px)',
-  },
-  body: {
-    backgroundColor: '#FFFFFF',
-    color: '#333333',
-    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
-    fontSize: '16px',
-    lineHeight: '1.5',
-  },
-  form: {
-    backgroundColor: '#FFFFFF',
-    padding: '20px',
-    maxWidth: '800px',
-    margin: '0 auto',
-    fieldSpacing: '1.5rem',
-    groupSpacing: '2rem',
-  },
-  colors: {
-    primary: '#1D4ED8',
-    secondary: '#6B7280',
-    success: '#059669',
-    danger: '#DC2626',
-    warning: '#D97706',
-    info: '#2563EB',
-    light: '#F3F4F6',
-    dark: '#1F2937',
-    error: '#DC2626',
-    border: '#D1D5DB',
-    inputBackground: '#FFFFFF',
-    headerBackground: '#EFF6FF',
-  },
-  field: {
-    marginBottom: '1rem',
-    width: '100%',
-  },
-  label: {
-    display: 'block',
-    marginBottom: '0.5rem',
-    fontSize: '0.875rem',
-    fontWeight: '500',
-    color: '#374151',
-  },
-  input: {
-    width: '100%',
-    padding: '0.5rem',
-    fontSize: '1rem',
-    borderRadius: '0.375rem',
-    border: '1px solid #D1D5DB',
-    backgroundColor: '#FFFFFF',
-    '&:focus': {
-      outline: 'none',
-      borderColor: '#2563EB',
-      boxShadow: '0 0 0 2px rgba(37, 99, 235, 0.2)',
-    },
-  },
-  error: {
-    color: '#DC2626',
-    fontSize: '0.875rem',
-    marginTop: '0.25rem',
-  },
-};
-
-function App() {
-  // State Management
-  const [formState, setFormState] = useState({
-    storeVenderData: null,
-    questionGroups: [],
-    pageRules: [],
-    pageRuleGroup: [],
-    validationSchema: [],
-    actionSchema: [],
-    sectionSchema: [],
-    caseId: null,
-    pageId: null,
-    apiCallCounter: 0,
-    selectedAction: '',
-    error: null,
-    isLoading: false,
-  });
-
-  // Memoized API headers
-  const headers = useMemo(
-    () => ({
-      'Content-Type': 'application/json',
-      Authorization: process.env.REACT_APP_AUTH_TOKEN || '<AUTH_TOKEN>',
-      CarrierAuthorization: process.env.REACT_APP_CARRIER_AUTH || '<CARRIER_AUTH_TOKEN>',
-    }),
-    []
-  );
-
-  // Transform form data with error handling
-  const transformFormData = useCallback((formData, schema) => {
-    try {
-      // Handle empty array or non-object formData
-      const formDataObj = Array.isArray(formData) || typeof formData !== 'object' ? {} : formData;
-      const { values = {}, visibility = {}, disabled = {} } = formDataObj;
-      const transformedData = [];
-
-      // Process form data based on schema
-      // ... (transform logic omitted for brevity)
-
-      return transformedData;
-    } catch (error) {
-      console.error('Error transforming form data:', error);
-      throw new Error('Failed to transform form data');
-    }
-  }, []);
-
-  // API call with error handling
-  const fetchStoreQuestionVendor = useCallback(
-    async (questions, action = '', nextPageId = '') => {
-      try {
-        const { caseId, pageId } = formState;
-        setFormState((prev) => ({ ...prev, isLoading: true, error: null }));
-
-        const requestPayload = {
-          caseId,
-          pageId,
-          questions,
-          user: '<USER_TYPE>',
-          agentId: '<AGENT_ID>',
-          templateName: '<PRODUCT_NAME>',
-          ...(action && { action }),
-          ...(nextPageId && { nextPageId }),
-        };
-
-        const response = await fetch(`${API_CONFIG.BASE_URL}${API_CONFIG.ENDPOINTS.STORE_VENDOR}`, {
-          method: 'POST',
-          headers,
-          body: JSON.stringify(requestPayload),
-        });
-
-        if (!response.ok) {
-          throw new Error(`API Error: ${response.status}`);
-        }
-
-        const { data: result } = await response.json();
-        const { pageDefinition, sectionList, caseId: newCaseId, pageId: newPageId } = result || {};
-
-        const {
-          questionGroups = [],
-          pageRules: rawPageRules = null,
-          pageRuleGroup: rawPageRuleGroup = null,
-          validationErrors = [],
-          actionButtons = [],
-        } = pageDefinition || {};
-
-        // Process and update state with API response
-        setFormState((prev) => ({
-          ...prev,
-          storeVenderData: result,
-          questionGroups,
-          pageRules: Array.isArray(rawPageRules) ? rawPageRules : [],
-          pageRuleGroup: Array.isArray(rawPageRuleGroup) ? rawPageRuleGroup : [],
-          validationSchema: validationErrors,
-          actionSchema: actionButtons,
-          sectionSchema: sectionList || [],
-          caseId: newCaseId || '',
-          pageId: newPageId || '',
-          selectedAction: action,
-          isLoading: false,
-        }));
-      } catch (error) {
-        console.error('API Error:', error);
-        setFormState((prev) => ({
-          ...prev,
-          error: error.message,
-          isLoading: false,
-        }));
-      }
-    },
-    [formState.caseId, formState.pageId, headers]
-  );
-
-  // Form submission handler
-  const handleSubmit = useCallback(
-    (newFormState, action) => {
-      const { questionGroups } = formState;
-      const transformedData = transformFormData(newFormState, questionGroups);
-      fetchStoreQuestionVendor(transformedData, action);
-    },
-    [fetchStoreQuestionVendor, formState.questionGroups, transformFormData]
-  );
-
-  // Section change handler
-  const handleSectionChange = useCallback(
-    (pageId) => {
-      const { questionGroups } = formState;
-      const transformedData = transformFormData([], questionGroups);
-      fetchStoreQuestionVendor(transformedData, '', pageId);
-    },
-    [fetchStoreQuestionVendor, formState.questionGroups, transformFormData]
-  );
-
-  // Initial data fetch
-  useEffect(() => {
-    fetchStoreQuestionVendor(INITIAL_QUESTIONS);
-  }, []);
-
-  // Extract commonly used state values
-  const {
-    error,
-    isLoading,
-    storeVenderData,
-    sectionSchema,
-    questionGroups,
-    pageRules,
-    pageRuleGroup,
-    validationSchema,
-    actionSchema,
-    pageId,
-  } = formState;
-
-  // Handle API triggers from form fields
-  const handleApiTrigger = (apiRequest) => {
-    // Implementation for API trigger handling
-    console.log('API request:', apiRequest);
-    // Return promise with response structure
-    return Promise.resolve({
-      success: true,
-      data: {
-        // Example: update options for a dropdown
-        options: [
-          { name: 'Option 1', value: 'option1' },
-          { name: 'Option 2', value: 'option2' },
-        ],
-      },
-    });
-  };
-
-  return (
-    <div className="app-container">
-      <header className="app-header">
-        <h1>Dynamic Form Example</h1>
-      </header>
-
-      <div className="app-main">
-        {error && (
-          <div className="error-message" role="alert">
-            {error}
-          </div>
-        )}
-
-        {isLoading && (
-          <div className="loading-indicator" role="status">
-            Loading...
-          </div>
-        )}
-
-        {storeVenderData && (
-          <>
-            <aside className="app-sidebar">
-              {!isLoading && sectionSchema?.length > 0 && (
-                <SectionListRenderer
-                  sectionLists={sectionSchema}
-                  onSectionClick={handleSectionChange}
-                  customStyles={{ backgroundColor: '#f5f5f5' }}
-                  pageId={pageId || sectionSchema[0]?.pageId}
-                />
-              )}
-            </aside>
-
-            <main className="app-content">
-              {questionGroups?.length > 0 && (
-                <DynamicForm
-                  questionGroups={questionGroups}
-                  pageRules={pageRules}
-                  pageRuleGroup={pageRuleGroup}
-                  validationErrors={validationSchema}
-                  actionButtons={actionSchema}
-                  theme={THEME}
-                  onSubmit={handleSubmit}
-                  onApiTrigger={handleApiTrigger}
-                  apiConfig={apiConfig}
-                />
-              )}
-            </main>
-          </>
-        )}
-      </div>
-    </div>
-  );
-}
-
-export default App;
-```
-
-## Form Schema Structure
-
-The form structure is defined by a JSON schema that specifies question groups and their fields. Each form consists of one or more question groups, each containing multiple field definitions.
-
-### Question Group Structure
-
-```javascript
-{
-  groupId: string,           // Unique identifier for the group
-  groupName: string,         // Display name for the group (optional)
-  description: string,       // Group description (optional)
-  columnCount: number,       // Number of columns for layout (default: 1)
-  visible: boolean,          // Group visibility (default: true)
-  questions: Array<Question> // Array of question objects
-}
-```
-
-### Question (Field) Structure
-
-```javascript
-{
-  questionId: string,       // Unique identifier for the question/field
-  questionType: string,      // Field type (text, dropdown, checkbox, etc.)
-  label: string,             // Field label
-  placeholder: string,       // Field placeholder (optional)
-  helpText: string,          // Help text below the field (optional)
-  defaultValue: any,         // Default field value (optional)
-  validation: Object,        // Validation rules (optional)
-  visible: boolean,          // Field visibility (default: true)
-  disabled: boolean,         // Field disabled state (default: false)
-  required: boolean,         // Whether field is required (default: false)
-  options: Array<Option>,    // Options for select/dropdown/radio fields
-  layout: Object,            // Layout configuration (optional)
-  style: Object,             // Custom styling (optional)
-  apiTrigger: Object         // API integration configuration (optional)
-}
-```
-
-### Action Schema Structure
-
-The action schema defines form buttons and their behaviors:
-
-```javascript
-[
-  {
-    text: string, // Button text
-    action: string, // Action identifier (e.g., 'submit', 'back', 'next')
-    position: string, // Button position (optional, default: 'right')
-  },
-];
-```
-
-## API Integration
-
-The package provides robust third-party API integration capabilities, allowing forms to fetch data, populate options, and submit data to external services.
-
-### Basic API Integration
-
-API integration is handled through the `onApiTrigger` prop, which receives API trigger events from form fields:
-
-```jsx
-import React from 'react';
-import DynamicForm from '@ilife-tech/react-application-flow-renderer';
-import { handleApiTrigger } from './services/apiService';
-
-const MyForm = () => {
-  // Form schema with API trigger configuration
-  const questionGroups = [
-    {
-      groupId: 'locationInfo',
-      questions: [
-        {
-          questionId: 'country',
-          questionType: 'dropdown',
-          label: 'Country',
-          options: [
-            { name: 'United States', value: 'US' },
-            { name: 'Canada', value: 'CA' },
-          ],
-        },
-        {
-          questionId: 'state',
-          questionType: 'dropdown',
-          label: 'State/Province',
-          placeholder: 'Select a state',
-          // API trigger configuration
-          apiTrigger: {
-            type: 'dropdown',
-            dependsOn: ['country'], // Fields this API call depends on
-            apiUrl: 'getStatesByCountry', // API identifier
-            triggerEvents: ['onChange', 'onLoad'], // When to trigger API
-          },
-        },
-      ],
-    },
-  ];
-
-  // API configuration
-  const apiConfig = {
-    baseUrl: process.env.REACT_APP_API_BASE_URL || 'https://api.example.com',
-    headers: {
-      'Content-Type': 'application/json',
-      Authorization: `Bearer ${process.env.REACT_APP_API_TOKEN}`,
-    },
-    timeout: 5000,
-  };
-
-  return (
-    <DynamicForm
-      questionGroups={questionGroups}
-      onApiTrigger={handleApiTrigger}
-      apiConfig={apiConfig}
-    />
-  );
-};
-
-export default MyForm;
-```
-
-### Implementing the API Handler
-
-The API handler function processes API triggers and returns updates to the form. Here's a practical example based on the package's example implementation:
-
-```javascript
-// services/apiService.js
-import { createApiResponse } from '../utils/apiUtils';
-
-/**
- * Handle API trigger events from form fields
- * @param {Object} triggerData - Data from the form's onApiTrigger event
- * @returns {Promise<Object>} - Response with form updates
- */
-export const handleApiTrigger = async (triggerData) => {
-  const { question, value, triggerType, formState } = triggerData;
-
-  // Extract API configuration
-  const { apiTrigger, questionId } = question;
-
-  // Skip if no API trigger is configured
-  if (!apiTrigger || !apiTrigger.apiUrl) {
-    return null;
-  }
-
-  try {
-    // For dropdown fields that depend on other fields
-    if (question.questionType === 'dropdown' && triggerType === 'onChange') {
-      // Example: Fetch states based on selected country
-      if (apiTrigger.apiUrl === 'getStatesByCountry') {
-        const countryValue = formState.values[apiTrigger.dependsOn[0]];
-
-        // Don't proceed if no country is selected
-        if (!countryValue) {
-          return createApiResponse({
-            options: { [questionId]: [] },
-            values: { [questionId]: '' },
-          });
-        }
-
-        // Make API request
-        const response = await fetch(`${apiConfig.baseUrl}/states?country=${countryValue}`, {
-          headers: apiConfig.headers,
-        });
-
-        const data = await response.json();
-
-        // Map API response to dropdown options
-        const stateOptions = data.map((state) => ({
-          name: state.name,
-          value: state.code,
-        }));
-
-        // Return updates for the form
-        return createApiResponse({
-          options: { [questionId]: stateOptions },
-          visibility: { [questionId]: true },
-          disabled: { [questionId]: false },
-        });
-      }
-    }
-
-    return null;
-  } catch (error) {
-    console.error('API error:', error);
-
-    // Return error response
-    return createApiResponse({
-      apiErrors: { [questionId]: 'Failed to fetch data. Please try again.' },
-    });
-  }
-};
-```
-
-### API Response Structure
-
-API responses should be formatted as an object with field updates:
-
-```javascript
-// utils/apiUtils.js
-
-/**
- * Create formatted API response for form updates
- * @param {Object} updates - Updates to apply to the form
- * @returns {Object} - Formatted response
- */
-export const createApiResponse = (updates = {}) => {
-  return {
-    // Field values to update
-    values: updates.values || {},
-
-    // Dropdown options to update
-    options: updates.options || {},
-
-    // Field visibility updates
-    visibility: updates.visibility || {},
-
-    // Field disabled state updates
-    disabled: updates.disabled || {},
-
-    // Field required state updates
-    required: updates.required || {},
-
-    // Error messages
-    apiErrors: updates.apiErrors || {},
-
-    // Loading states
-    apiLoading: updates.apiLoading || {},
-  };
-};
-```
-
-### Advanced API Integration Example
-
-Here's a more comprehensive example showing how to handle complex API integration with request queuing and response mapping:
-
-```javascript
-// services/api/handlers/dropdownApiHandler.js
-
-import { createApiResponse } from '../../../utils/apiUtils';
-
-// Request queue for managing concurrent API calls
-class ApiRequestQueue {
-  constructor() {
-    this.queue = new Map();
-  }
-
-  async enqueue(questionId, apiCall) {
-    if (this.queue.has(questionId)) {
-      return this.queue.get(questionId);
-    }
-
-    const promise = apiCall().finally(() => {
-      this.queue.delete(questionId);
-    });
-
-    this.queue.set(questionId, promise);
-    return promise;
-  }
-}
-
-const requestQueue = new ApiRequestQueue();
-
-/**
- * Handle API calls for dropdown fields
- * @param {Object} triggerData - API trigger data
- * @returns {Promise<Object>} Response with options and updates
- */
-export const handleDropdownApi = async (triggerData) => {
-  const { question, value, triggerType, formState } = triggerData;
-  const { questionId, apiTrigger } = question;
-
-  // Example: Handle different API endpoints based on apiUrl
-  switch (apiTrigger?.apiUrl) {
-    case 'getHouseholdMembers':
-      return requestQueue.enqueue(questionId, () =>
-        getHouseholdMembers(apiTrigger.apiUrl, formState)
-      );
-
-    case 'getStatesByCountry':
-      // Get dependent field value
-      const country = formState.values[apiTrigger.dependsOn[0]];
-      if (!country) {
-        return createApiResponse({
-          options: { [questionId]: [] },
-          disabled: { [questionId]: true },
-        });
-      }
-
-      return requestQueue.enqueue(questionId, () => getStatesByCountry(apiTrigger.apiUrl, country));
-
-    default:
-      return null;
-  }
-};
-
-/**
- * Example API implementation for fetching states by country
- */
-async function getStatesByCountry(apiUrl, country) {
-  try {
-    // Here we'd normally implement our API call
-    const response = await fetch(`https://api.example.com/states?country=${country}`);
-    const data = await response.json();
-
-    // Map response to options format
-    const options = data.map((state) => ({
-      name: state.stateName || state.name,
-      value: state.stateCode || state.code,
-    }));
-
-    return createApiResponse({
-      options: { state: options },
-      disabled: { state: false },
-      visibility: { state: true },
-    });
-  } catch (error) {
-    console.error('API error:', error);
-    return createApiResponse({
-      apiErrors: { state: 'Failed to fetch states. Please try again.' },
-      options: { state: [] },
-    });
-  }
-}
-```
-
-## Props Reference
-
-The `DynamicForm` component accepts the following props:
-
-| Prop               | Type       | Required | Default | Description                                       |
-| ------------------ | ---------- | -------- | ------- | ------------------------------------------------- |
-| `questionGroups`   | `Array`    | Yes      | `[]`    | Array of question groups defining form structure  |
-| `actionSchema`     | `Array`    | No       | `[]`    | Array of action buttons configuration             |
-| `onSubmit`         | `Function` | No       | -       | Form submission handler                           |
-| `onApiTrigger`     | `Function` | No       | -       | API trigger event handler                         |
-| `apiConfig`        | `Object`   | No       | `{}`    | API configuration options                         |
-| `theme`            | `Object`   | No       | `{}`    | Theme customization                               |
-| `validationSchema` | `Array`    | No       | `[]`    | Additional validation rules                       |
-| `pageRules`        | `Array`    | No       | `[]`    | Page rules for conditional logic                  |
-| `pageRuleGroup`    | `Array`    | No       | `[]`    | Page rule groups with complex boolean expressions |
-| `debug`            | `Boolean`  | No       | `false` | Enable debug mode                                 |
-| `formApiRef`       | `Object`   | No       | -       | Ref object to access form API methods             |
-| `toastConfig`      | `Object`   | No       | `{}`    | Toast configuration                               |
-
-### Props Details
-
-#### `questionGroups`
-
-An array of question group objects that defines the form structure. Each group contains questions (fields) to render.
-
-```javascript
-const questionGroups = [
-  {
-    groupId: 'group1',
-    groupName: 'Personal Information',
-    questions: [
-      /* question objects */
-    ],
-  },
-];
-```
-
-#### `actionSchema`
-
-An array of action button configurations for the form.
-
-```javascript
-const actionSchema = [
-  { text: 'Submit', action: 'submit' },
-  { text: 'Previous', action: 'back' },
-];
-```
-
-#### `onSubmit`
-
-Callback function called when a form action is triggered. Receives the form state and action identifier.
-
-```javascript
-const handleSubmit = (formState, action) => {
-  // formState contains values, errors, etc.
-  // action is the identifier of the action button clicked
-  if (action === 'submit') {
-    // Handle form submission
-    console.log('Form values:', formState.values);
-  }
-};
-```
-
-#### `onApiTrigger`
-
-Callback function for handling API trigger events from form fields. Receives trigger data object.
-
-```javascript
-const handleApiTrigger = async (triggerData) => {
-  // triggerData contains question, value, triggerType, and formState
-  // Return formatted API response with updates to the form
-};
-```
-
-#### `apiConfig`
-
-Object containing API configuration options passed to the `onApiTrigger` handler.
-
-```javascript
-const apiConfig = {
-  baseUrl: 'https://api.example.com',
-  headers: {
-    'Content-Type': 'application/json',
-    Authorization: 'Bearer YOUR_TOKEN',
-  },
-  timeout: 5000,
-};
-```
-
-## Field Types
-
-The package supports a wide range of field types to handle various input requirements:
-
-### Basic Field Types
-
-| Field Type | Component       | Description                           |
-| ---------- | --------------- | ------------------------------------- |
-| `text`     | `TextField`     | Standard text input field             |
-| `textarea` | `TextAreaField` | Multi-line text input                 |
-| `email`    | `EmailField`    | Email input with validation           |
-| `password` | `PasswordField` | Password input with visibility toggle |
-| `number`   | `NumberField`   | Numeric input with constraints        |
-| `phone`    | `PhoneField`    | Phone number input with formatting    |
-| `currency` | `CurrencyField` | Monetary value input with formatting  |
-| `date`     | `DateField`     | Date picker with calendar             |
-| `datetime` | `DateTimeField` | Combined date and time picker         |
-
-### Selection Field Types
-
-| Field Type        | Component              | Description                                 |
-| ----------------- | ---------------------- | ------------------------------------------- |
-| `dropdown`        | `SelectField`          | Dropdown selection menu                     |
-| `combobox`        | `ComboboxField`        | Searchable dropdown with multiple selection |
-| `radio`           | `RadioField`           | Single-selection radio buttons              |
-| `radioGroup`      | `RadioGroupField`      | Group of radio buttons with custom layout   |
-| `radioSwitch`     | `RadioSwitchField`     | Toggle-style radio selection                |
-| `radioTabButtons` | `RadioTabButtonsField` | Tab-style radio selection                   |
-| `checkbox`        | `CheckboxField`        | Single checkbox                             |
-| `checkboxGroup`   | `CheckboxGroupField`   | Group of checkboxes with multiple selection |
-
-### Specialized Field Types
-
-| Field Type       | Component             | Description                                                |
-| ---------------- | --------------------- | ---------------------------------------------------------- |
-| `address`        | `AddressField`        | Address input with validation and auto-complete            |
-| `beneficiary`    | `BeneficiaryField`    | Complex beneficiary information with percentage validation |
-| `identification` | `IdentificationField` | SSN/ITIN input with masking and validation                 |
-| `file`           | `FileField`           | File upload with preview                                   |
-| `pdf`            | `PDFField`            | PDF file upload and display                                |
-| `cardList`       | `CardListField`       | Dynamic array of nested form fields                        |
-| `display`        | `DisplayTextField`    | Read-only text display                                     |
-| `hyperlink`      | `HyperlinkField`      | Clickable hyperlink field                                  |
-| `button`         | `ButtonField`         | Action button field                                        |
-| `spinner`        | `SpinnerField`        | Loading indicator field                                    |
-
-## Input Masking and Security
-
-The React Dynamic Form Renderer includes advanced **dual masking system** for sensitive data fields, providing both input formatting and security masking capabilities.
-
-### Dual Masking System
-
-The package implements a sophisticated dual masking approach:
-
-1. **Input Masking**: Real-time formatting during user input (e.g., `123-45-6789`)
-2. **Security Masking**: Hide sensitive characters for privacy (e.g., `***-**-6789`)
-
-### Supported Field Types
-
-The following field types support dual masking:
-
-| Field Type    | Input Formatting | Security Masking | Eye Icon Toggle |
-| ------------- | ---------------- | ---------------- | --------------- |
-| `ssn`         | ✅               | ✅               | ✅              |
-| `itin`        | ✅               | ✅               | ✅              |
-| `phonenumber` | ✅               | ✅               | ✅              |
-| `phone`       | ✅               | ✅               | ✅              |
-| `currency`    | ✅               | ❌               | ❌              |
-| `number`      | ✅               | ❌               | ❌              |
-| `percentage`  | ✅               | ❌               | ❌              |
-
-### Configuration Options
-
-#### Input Masking
-
-```javascript
-{
-  "questionId": "ssn_field",
-  "label": "Social Security Number",
-  "questionType": "ssn",
-  "maskInput": "###-##-####",  // Input formatting pattern
-  "required": true
-}
-```
-
-#### Security Masking
-
-```javascript
-{
-  "questionId": "ssn_field",
-  "label": "Social Security Number",
-  "questionType": "ssn",
-  "maskInput": "###-##-####",     // Input formatting
-  "maskingType": "prefix",        // "prefix" or "suffix"
-  "maskingLength": 6,             // Number of characters to mask
-  "required": true
-}
-```
-
-### Masking Patterns
-
-#### Common Patterns
-
-| Field Type | Pattern          | Example Input | Formatted      | Security Masked    |
-| ---------- | ---------------- | ------------- | -------------- | ------------------ |
-| SSN        | `###-##-####`    | 123456789     | 123-45-6789    | **\*-**-6789       |
-| Phone      | `(###) ###-####` | 1234567890    | (123) 456-7890 | (123) 456-\*\*\*\* |
-| ITIN       | `###-##-####`    | 912456789     | 912-45-6789    | **\*-**-6789       |
-
-#### Custom Patterns
-
-You can define custom masking patterns using:
-
-- `#` for digits (0-9)
-- `*` for any character
-- Special characters (hyphens, parentheses, etc.) are preserved
-
-### Eye Icon Toggle
-
-Fields with security masking automatically display an eye icon (👁️/🙈) that allows users to toggle between:
-
-- **Masked View**: Shows security masked value (e.g., `***-**-6789`)
-- **Original View**: Shows formatted value (e.g., `123-45-6789`)
-
-#### Accessibility Features
-
-- **Keyboard Navigation**: Eye icon supports Tab navigation
-- **Keyboard Activation**: Toggle with Enter or Space keys
-- **Screen Reader Support**: Proper ARIA labels and descriptions
-- **Focus Management**: Clear focus indicators
-
-### Advanced Configuration
-
-#### Prefix vs Suffix Masking
-
-```javascript
-// Prefix masking (mask first N characters)
-{
-  "maskingType": "prefix",
-  "maskingLength": 6,
-  // "123-45-6789" → "***-**-6789"
-}
-
-// Suffix masking (mask last N characters)
-{
-  "maskingType": "suffix",
-  "maskingLength": 4,
-  // "123-45-6789" → "123-45-****"
-}
-```
-
-#### Validation with Masking
-
-The masking system integrates seamlessly with validation:
-
-```javascript
-{
-  "questionId": "ssn_field",
-  "maskInput": "###-##-####",
-  "maskingType": "prefix",
-  "maskingLength": 6,
-  "minLength": 9,           // Validates unmasked length
-  "maxLength": 9,           // Validates unmasked length
-  "required": true,
-  "validation": {
-    "pattern": "^\\d{9}$",  // Validates digits only
-    "message": "Please enter a valid 9-digit SSN"
-  }
-}
-```
-
-### Implementation Notes
-
-- **Real-time Processing**: Masking is applied during user input, not just on blur
-- **Form Integration**: Masked values are properly integrated with form state
-- **Performance**: Optimized for large forms with multiple masked fields
-- **Browser Compatibility**: Works across all modern browsers
-- **Mobile Support**: Touch-friendly eye icon and responsive design
-
-### Troubleshooting
-
-#### Common Issues
-
-1. **Masking Not Applied**: Ensure `maskInput` pattern is correctly formatted
-2. **Eye Icon Missing**: Verify both `maskingType` and `maskingLength` are set
-3. **Validation Errors**: Check that validation patterns match unmasked values
-4. **Performance Issues**: Avoid overly complex masking patterns in large forms
-
-#### Debug Tips
-
-```javascript
-// Enable console logging for masking operations
-console.log('Masked Value:', maskedValue);
-console.log('Display Value:', displayValue);
-console.log('Mask Config:', maskConfig);
-```
-
-## Conditional Logic
-
-The Dynamic Form Renderer provides powerful conditional logic capabilities through the `pageRules` and `pageRuleGroup` props.
-
-### PageRules
-
-Page rules define individual conditions and actions for dynamic form behavior:
-
-```javascript
-const pageRules = [
-  {
-    ruleId: 'rule1',
-    triggerQuestionIds: ['101'],
-    comparison: 'equals',
-    compareValue: 'yes',
-    action: 'showquestion',
-    targetQuestionIds: ['201'],
-  },
-  // more rules...
-];
-```
-
-### Enhanced PageRuleGroup
-
-The enhanced `pageRuleGroup` feature provides sophisticated boolean expressions for complex conditional logic:
-
-```javascript
-// New array-based format with complex boolean expressions
-const pageRuleGroup = [
-  {
-    questionId: '40374',
-    evaluationExpression: 'rule1 AND rule2',
-  },
-  {
-    questionId: '40555',
-    evaluationExpression: '(rule1 AND rule2) OR rule3',
-  },
-];
-```
-
-#### Key Features
-
-- **Complex Boolean Logic**: Combine multiple rules with AND/OR operations
-- **Parentheses Support**: Control operator precedence for complex evaluations
-- **Backward Compatibility**: Supports legacy object-based format
-
-#### Expression Syntax
-
-- **Operators**: `AND`, `OR` (case-insensitive)
-- **Rule References**: Use `ruleId` values from the pageRules array
-- **Parentheses**: Group expressions to control evaluation order
-
-#### Examples
-
-```javascript
-// Simple AND condition
-{
-  questionId: "40374",
-  evaluationExpression: "rule1 AND rule2"
-}
-
-// Complex nested conditions
-{
-  questionId: "40890",
-  evaluationExpression: "(rule1 AND rule2) OR (rule3 AND rule4)"
-}
-```
-
-For detailed documentation on the enhanced pageRuleGroup feature, see the [PageRuleGroupEnhancement.md](docs/PageRuleGroupImplementation/PageRuleGroupEnhancement.md) file.
-
-## Advanced Configuration
-
-## Performance & Engine Options
-
-When using the provider-level API, you can tune performance and engine behavior.
-
-### FormProvider props
-
-- `performanceConfig`
-  - `debounceDelayMs: number` (default: 120) – Debounce for textual input processing
-
-- `engineOptions`
-  - `enablePerActionGating: boolean` (default: true) – Toggle per-action gating via questionRules
-  - `maxEvaluationDepth: number` (default: 20) – Reflexive evaluation depth guard
-
-### Example
-
-```jsx
-import { FormProvider } from '@ilife-tech/react-application-flow-renderer/context/FormContext';
-import DynamicFormInner from '@ilife-tech/react-application-flow-renderer/src/components/core/components/DynamicFormInner';
-
-<FormProvider
-  formSchema={questionGroups}
-  questionRuleDetails={questionRuleDetails}
-  questionRules={questionRules}
-  performanceConfig={{ debounceDelayMs: 150 }}
-  engineOptions={{ enablePerActionGating: true, maxEvaluationDepth: 20 }}
->
-  <DynamicFormInner schema={questionGroups} actionSchema={actionSchema} onSubmit={handleSubmit} />
-</FormProvider>;
-```
-
-Note: The top-level `DynamicForm` abstraction may not expose these knobs directly. Use `FormProvider` for fine-grained control.
-
-### Toast Notifications
-
-The Dynamic Form Renderer uses react-toastify for displaying notifications such as error messages, warnings, and success confirmations.
-
-#### Toast Configuration
-
-The form renderer integrates with your application's react-toastify setup. **Important: Your host application MUST include a `<ToastContainer />` component** for notifications to appear.
-
-```jsx
-// Required: Import react-toastify in your host application
-import { ToastContainer } from 'react-toastify';
-import 'react-toastify/dist/ReactToastify.css';
-
-const App = () => {
-  return (
-    <>
-      {/* Required: Add ToastContainer at the root level */}
-      <ToastContainer />
-
-      <DynamicForm
-        questionGroups={questionGroups}
-        toastConfig={{
-          disableToasts: false, // Disable toast notifications completely (default: false)
-          useHostToastify: true, // Whether to use host app's react-toastify (default: true)
-        }}
-        onSubmit={handleSubmit}
-        onApiTrigger={handleApiTrigger}
-      />
-    </>
-  );
-};
-```
-
-#### API Response Format for Toast Notifications
-
-When implementing the `onApiTrigger` handler, you can return success and error messages that will be displayed as toast notifications:
-
-```javascript
-// Example of API trigger handler with toast notifications
-const handleApiTrigger = async (triggerData) => {
-  try {
-    // Your API logic here
-    const response = await myApiCall(triggerData);
-
-    // Return success message (will display as green toast)
-    return {
-      success: {
-        message: 'Operation completed successfully',
-        // You can also include field-specific success messages
-        // fieldName: 'Field updated successfully'
-      },
-      // Other response properties like updates, options, visibility...
-    };
-  } catch (error) {
-    // Return error message (will display as red toast)
-    return {
-      errors: {
-        error: 'An error occurred during the operation',
-        // You can also include field-specific error messages
-        // fieldName: 'Invalid value for this field'
-      },
-    };
-  }
-};
-```
-
-#### Integration with Host Applications
-
-If your application already uses react-toastify, the renderer will:
-
-1. Use your application's react-toastify instance
-2. Respect your toast styling and configuration
-
-**Important:** Only one `<ToastContainer />` should be rendered in your application tree. The package will not render its own ToastContainer - this must be provided by the host application.
-
-### Toast Configuration
-
-The Dynamic Form Renderer uses react-toastify for displaying notifications. You can configure toast behavior using the `toastConfig` prop:
-
-```jsx
-<DynamicForm
-  // Other props...
-  toastConfig={{
-    disableToasts: false, // Set to true to disable all toast notifications
-    useHostToastify: true, // Set to true to use host application's ToastContainer
-    // Additional toast options can be passed here
-  }}
-/>
-```
-
-#### ToastContainer Requirements
-
-To properly display toast notifications:
-
-1. Import ToastContainer and CSS in your host application:
-
-   ```jsx
-   import { ToastContainer } from 'react-toastify';
-   import 'react-toastify/dist/ReactToastify.css';
-   ```
-
-2. Add the ToastContainer to your app's root component:
-   ```jsx
-   function App() {
-     return (
-       <>
-         <YourAppComponents />
-         <ToastContainer position="top-right" autoClose={5000} />
-       </>
-     );
-   }
-   ```
-
-#### API Response Format for Toast Messages
-
-When implementing custom API triggers with `onApiTrigger`, your handler should return a promise that resolves to an object with the following structure to properly display toast notifications:
-
-```javascript
-const handleApiTrigger = async (triggerData) => {
-  // Your API call implementation
-  try {
-    // Process API call
-    return {
-      // Success messages that will trigger toast notifications
-      success: {
-        message: 'General success message', // General success toast
-        fieldId: 'Field-specific success', // Field-specific success toast
-      },
-      // Optional field updates
-      updates: {
-        fieldId1: 'new value', // Update field values
-        fieldId2: [{ name: 'Option 1', value: 'opt1' }], // Update field options
-      },
-    };
-  } catch (error) {
-    return {
-      // Error messages that will trigger toast notifications
-      errors: {
-        error: 'General error message', // General error toast
-        fieldId: 'Field-specific error', // Field-specific error toast
-      },
-    };
-  }
-};
-```
-
-#### Compatibility Notes
-
-- The Dynamic Form Renderer is compatible with react-toastify v9.1.x for React 17 applications
-- For React 18+ applications, you can use react-toastify v9.x or higher
-- Toast styles will follow your application's theme if available
-- Error and success messages from API responses and form validation will use appropriate toast types
-
-#### Troubleshooting
-
-- **No toasts appear**: Ensure your application has a `<ToastContainer />` component and has imported the CSS
-- **\_useSyncExternalStore error**: This usually indicates a version compatibility issue between React and react-toastify. For React 17, use react-toastify v9.1.x
-- **Multiple toasts appear**: Ensure you only have one `<ToastContainer />` in your application
-
-### Theme Customization
-
-The DynamicForm component supports deep theme customization through the `theme` prop:
-
-```javascript
-const customTheme = {
-  typography: {
-    fontFamily: '"Roboto", "Helvetica", "Arial", sans-serif',
-    fontSize: '16px',
-    lineHeight: 1.5,
-    headings: {
-      h1: { fontSize: '2rem', fontWeight: 700 },
-      h2: { fontSize: '1.5rem', fontWeight: 600 },
-      h3: { fontSize: '1.25rem', fontWeight: 600 },
-    },
-  },
-  palette: {
-    primary: {
-      main: '#0066cc',
-      light: '#3383d6',
-      dark: '#004c99',
-      contrastText: '#ffffff',
-    },
-    error: {
-      main: '#d32f2f',
-      light: '#ef5350',
-      dark: '#c62828',
-      contrastText: '#ffffff',
-    },
-    success: {
-      main: '#2e7d32',
-      light: '#4caf50',
-      dark: '#1b5e20',
-      contrastText: '#ffffff',
-    },
-  },
-  spacing: {
-    unit: '8px',
-    form: '24px',
-    field: '16px',
-  },
-  shape: {
-    borderRadius: '4px',
-  },
-  breakpoints: {
-    xs: 0,
-    sm: 600,
-    md: 960,
-    lg: 1280,
-    xl: 1920,
-  },
-  fields: {
-    input: {
-      height: '40px',
-      padding: '8px 12px',
-      fontSize: '16px',
-      borderRadius: '4px',
-      borderColor: '#cccccc',
-      focusBorderColor: '#0066cc',
-      errorBorderColor: '#d32f2f',
-      background: '#ffffff',
-    },
-    label: {
-      fontSize: '14px',
-      fontWeight: 600,
-      marginBottom: '4px',
-      color: '#333333',
-    },
-    helperText: {
-      fontSize: '12px',
-      color: '#666666',
-      marginTop: '4px',
-    },
-    error: {
-      fontSize: '12px',
-      color: '#d32f2f',
-      marginTop: '4px',
-    },
-  },
-  buttons: {
-    primary: {
-      background: '#0066cc',
-      color: '#ffffff',
-      hoverBackground: '#004c99',
-      fontSize: '16px',
-      padding: '8px 24px',
-      borderRadius: '4px',
-    },
-    secondary: {
-      background: '#f5f5f5',
-      color: '#333333',
-      hoverBackground: '#e0e0e0',
-      fontSize: '16px',
-      padding: '8px 24px',
-      borderRadius: '4px',
-    },
-  },
-};
-
-// Usage
-<DynamicForm
-  questionGroups={questionGroups}
-  theme={customTheme}
-  // Other props
-/>;
-```
-
-### Validation Configuration
-
-#### Client-side Validation
-
-Validation can be defined directly in the form schema or through a separate validation schema:
-
-```javascript
-// In form schema
-const questionGroups = [
-  {
-    groupId: 'personalInfo',
-    questions: [
-      {
-        questionId: 'email',
-        questionType: 'email',
-        label: 'Email Address',
-        validation: {
-          required: true,
-          email: true,
-          requiredMessage: 'Email is required',
-          errorMessage: 'Please enter a valid email address',
-          pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
-          patternMessage: 'Email format is invalid',
-        },
-      },
-      {
-        questionId: 'password',
-        questionType: 'password',
-        label: 'Password',
-        validation: {
-          required: true,
-          minLength: 8,
-          minLengthMessage: 'Password must be at least 8 characters',
-          pattern: /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]+$/,
-          patternMessage:
-            'Password must include uppercase, lowercase, number and special character',
-        },
-      },
-    ],
-  },
-];
-
-// Separate validation schema
-const validationSchema = [
-  {
-    field: 'confirmPassword',
-    rules: [
-      'required',
-      {
-        name: 'matchesField',
-        params: ['password'],
-        message: 'Passwords must match',
-      },
-    ],
-  },
-];
-```
-
-#### Available Validation Message Types
-
-| Message Type       | Description                                         |
-| ------------------ | --------------------------------------------------- |
-| `requiredMessage`  | Displayed when a required field is empty            |
-| `errorMessage`     | General error message for field validation          |
-| `lengthMessage`    | Error for overall length validation                 |
-| `minLengthMessage` | Error for minimum length validation                 |
-| `maxLengthMessage` | Error for maximum length validation                 |
-| `patternMessage`   | Error for regex pattern validation                  |
-| `typeMessage`      | Error for type validation (email, number, etc.)     |
-| `formatMessage`    | Error for format validation (phone, currency, etc.) |
-
-### CardList Configuration
-
-The `CardListField` component enables dynamic form arrays with complete validation and state management:
-
-```javascript
-const cardListQuestion = {
-  questionId: 'beneficiaries',
-  questionType: 'cardList',
-  label: 'Beneficiaries',
-  addCardLabel: 'Add Beneficiary',
-  cardSchema: [
-    {
-      groupId: 'beneficiaryInfo',
-      questions: [
-        {
-          questionId: 'name',
-          questionType: 'text',
-          label: 'Full Name',
-          validation: { required: true },
-        },
-        {
-          questionId: 'relationship',
-          questionType: 'dropdown',
-          label: 'Relationship',
-          options: [
-            { name: 'Spouse', value: 'spouse' },
-            { name: 'Child', value: 'child' },
-            { name: 'Parent', value: 'parent' },
-            { name: 'Other', value: 'other' },
-          ],
-          validation: { required: true },
-        },
-        {
-          questionId: 'percentage',
-          questionType: 'currency',
-          label: 'Percentage',
-          validation: {
-            required: true,
-            min: 0,
-            max: 100,
-            minMessage: 'Percentage must be positive',
-            maxMessage: 'Percentage cannot exceed 100%',
-          },
-        },
-      ],
-    },
-  ],
-  validation: {
-    minCards: 1,
-    maxCards: 5,
-    minCardsMessage: 'At least one beneficiary is required',
-    maxCardsMessage: 'Maximum of 5 beneficiaries allowed',
-    totalValidator: (cards) => {
-      // Calculate total percentage across all cards
-      const total = cards.reduce((sum, card) => {
-        const percentage = parseFloat(card.values.percentage) || 0;
-        return sum + percentage;
-      }, 0);
-
-      // Validate total is 100%
-      if (Math.abs(total - 100) > 0.01) {
-        return 'Total percentage must equal 100%';
-      }
-
-      return null; // No error
-    },
-  },
-};
-```
-
-#### CardList State Management
-
-Each card in a CardList manages its own state, including:
-
-- Form values
-- Validation errors
-- Visibility rules
-- Disabled states
-
-You can access the CardList state through the form context:
-
-```javascript
-const MyForm = () => {
-  const formApiRef = useRef(null);
-
-  const handleSubmit = (formState) => {
-    // Access cardList data as an array of card states
-    const beneficiaries = formState.values.beneficiaries;
-    console.log('Beneficiary cards:', beneficiaries);
-  };
-
-  return (
-    <DynamicForm questionGroups={questionGroups} onSubmit={handleSubmit} formApiRef={formApiRef} />
-  );
-};
-```
-
-## Troubleshooting
-
-### Common Issues
-
-#### API Integration Issues
-
-| Issue                           | Solution                                                                           |
-| ------------------------------- | ---------------------------------------------------------------------------------- |
-| API calls not triggering        | Ensure `apiTrigger` configuration in field schema includes correct `triggerEvents` |
-| API responses not updating form | Verify that the `onApiTrigger` handler returns the correct response structure      |
-| Multiple concurrent API calls   | Use request queuing as shown in the advanced API integration example               |
-| CORS errors                     | Configure proper CORS headers in your API or use a proxy service                   |
-
-#### Validation Issues
-
-| Issue                          | Solution                                                                         |
-| ------------------------------ | -------------------------------------------------------------------------------- |
-| ValidationSchema not applying  | Ensure field names in validation schema match questionIds in form schema         |
-| Custom validation not working  | Check that validation functions return error message strings, not boolean values |
-| Form submitting with errors    | Verify that onSubmit handler checks formState.errors before proceeding           |
-| Cross-field validation failing | Use the validationSchema approach for dependencies between fields                |
-
-#### Rendering Issues
-
-| Issue                                | Solution                                                       |
-| ------------------------------------ | -------------------------------------------------------------- |
-| Fields not respecting column layout  | Check columnCount setting in group configuration               |
-| Theme customizations not applying    | Ensure theme prop structure matches expected format            |
-| Responsive layout issues             | Verify breakpoints in theme configuration                      |
-| Fields rendering in unexpected order | Check if columns are properly balanced in group configurations |
-
-### Debugging Tips
-
-#### Using Debug Mode
-
-Enable debug mode to get verbose console output of form state changes:
-
-```jsx
-<DynamicForm
-  questionGroups={questionGroups}
-  debug={true}
-  // Other props
-/>
-```
-
-#### Accessing Form API
-
-Use the formApiRef prop to access form methods imperatively:
-
-```jsx
-const MyForm = () => {
-  const formApiRef = useRef(null);
-
-  const handleClick = () => {
-    // Access form API methods
-    const api = formApiRef.current;
-
-    // Get current form state
-    const state = api.getState();
-    console.log('Form values:', state.values);
-
-    // Set field value
-    api.setValue('email', 'user@example.com');
-
-    // Validate specific field
-    api.validateField('email');
-
-    // Validate entire form
-    api.validateForm().then((errors) => {
-      console.log('Validation errors:', errors);
-    });
-  };
-
-  return (
-    <>
-      <DynamicForm questionGroups={questionGroups} formApiRef={formApiRef} />
-      <button onClick={handleClick}>Debug Form</button>
-    </>
-  );
-};
-```
-
-### Performance Optimization
-
-#### Large Forms
-
-For large forms with many fields:
-
-- Split form into multiple pages or sections
-- Use the `visibleGroups` prop to only render visible question groups
-- Implement form sections with conditional rendering
-- Consider lazy loading for complex field components
-
-#### API Efficiency
-
-Improve API integration performance:
-
-- Implement response caching as shown in API integration examples
-- Use debounce for onChange API triggers
-- Batch API calls when possible
-- Implement request cancellation for outdated requests
-
-## Examples & Best Practices
-
-### Real-world Implementation Patterns
-
-#### Multi-step Form Wizard
-
-Implement a form wizard with progress tracking:
-
-```jsx
-import React, { useState } from 'react';
-import DynamicForm from '@ilife-tech/react-application-flow-renderer';
-
-const MultiStepForm = () => {
-  const [step, setStep] = useState(0);
-  const [formData, setFormData] = useState({});
-
-  // Define steps with their schemas
-  const steps = [
-    {
-      title: 'Personal Information',
-      schema: [
-        {
-          groupId: 'personal',
-          questions: [
-            /* Personal info questions */
-          ],
-        },
-      ],
-      actions: [{ text: 'Next', action: 'next' }],
-    },
-    {
-      title: 'Contact Details',
-      schema: [
-        {
-          groupId: 'contact',
-          questions: [
-            /* Contact info questions */
-          ],
-        },
-      ],
-      actions: [
-        { text: 'Back', action: 'back' },
-        { text: 'Next', action: 'next' },
-      ],
-    },
-    {
-      title: 'Review & Submit',
-      schema: [
-        {
-          groupId: 'review',
-          questions: [
-            /* Review fields */
-          ],
-        },
-      ],
-      actions: [
-        { text: 'Back', action: 'back' },
-        { text: 'Submit', action: 'submit' },
-      ],
-    },
-  ];
-
-  const currentStep = steps[step];
-
-  const handleAction = (state, action) => {
-    if (action === 'next' && step < steps.length - 1) {
-      // Store current step data
-      setFormData((prev) => ({ ...prev, ...state.values }));
-      setStep(step + 1);
-    } else if (action === 'back' && step > 0) {
-      setStep(step - 1);
-    } else if (action === 'submit') {
-      // Combine all step data and submit
-      const finalData = { ...formData, ...state.values };
-      console.log('Submitting form:', finalData);
-      // Submit to server
-    }
-  };
-
-  return (
-    <div className="multi-step-form">
-      <div className="progress-bar">
-        {steps.map((s, i) => (
-          <div key={i} className={`step ${i <= step ? 'active' : ''}`}>
-            {s.title}
-          </div>
-        ))}
-      </div>
-
-      <DynamicForm
-        questionGroups={currentStep.schema}
-        actionSchema={currentStep.actions}
-        initialValues={formData}
-        onSubmit={handleAction}
-      />
-    </div>
-  );
-};
-```
-
-#### Dynamic API-driven Form
-
-Create a form that dynamically loads its schema from an API:
-
-```jsx
-import React, { useState, useEffect } from 'react';
-import DynamicForm from '@ilife-tech/react-application-flow-renderer';
-import { handleApiTrigger } from './services/apiService';
-
-const DynamicApiForm = ({ formId }) => {
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState(null);
-  const [formSchema, setFormSchema] = useState(null);
-
-  useEffect(() => {
-    async function fetchFormSchema() {
-      try {
-        setLoading(true);
-
-        // Fetch form schema from API
-        const response = await fetch(`https://api.example.com/forms/${formId}`);
-
-        if (!response.ok) {
-          throw new Error(`Failed to load form: ${response.statusText}`);
-        }
-
-        const data = await response.json();
-
-        setFormSchema({
-          questionGroups: data.groups,
-          actionSchema: data.actions,
-          initialValues: data.initialValues || {},
-        });
-      } catch (err) {
-        setError(err.message);
-      } finally {
-        setLoading(false);
-      }
-    }
-
-    fetchFormSchema();
-  }, [formId]);
-
-  const handleSubmit = async (formState, action) => {
-    if (action === 'submit') {
-      try {
-        // Submit form data to API
-        const response = await fetch('https://api.example.com/submissions', {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json',
-          },
-          body: JSON.stringify({
-            formId,
-            values: formState.values,
-          }),
-        });
-
-        const result = await response.json();
-        console.log('Submission result:', result);
-      } catch (err) {
-        console.error('Submission error:', err);
-      }
-    }
-  };
-
-  if (loading) {
-    return <div className="loading">Loading form...</div>;
-  }
-
-  if (error) {
-    return <div className="error">{error}</div>;
-  }
-
-  return (
-    <DynamicForm
-      questionGroups={formSchema.questionGroups}
-      actionSchema={formSchema.actionSchema}
-      initialValues={formSchema.initialValues}
-      onSubmit={handleSubmit}
-      onApiTrigger={handleApiTrigger}
-    />
-  );
-};
-```
-
-### Security Best Practices
-
-1. **API Key Management**:
-   - Never hardcode API keys in your JavaScript code
-   - Use environment variables for all sensitive credentials
-   - Consider using token exchange services for third-party APIs
-
-2. **Sensitive Data Handling**:
-   - Use the built-in masking features for fields like SSN and credit card numbers
-   - Avoid storing sensitive data in localStorage or sessionStorage
-   - Clear sensitive form data after submission
-
-3. **Input Validation**:
-   - Always validate both on client and server side
-   - Use strong validation rules for sensitive fields
-   - Implement proper error handling for failed validations
-
-### Accessibility Guidelines
-
-1. **Screen Reader Support**:
-   - All form fields include proper ARIA attributes
-   - Error messages are announced to screen readers
-   - Focus management follows a logical flow
-
-2. **Keyboard Navigation**:
-   - All interactive elements are focusable
-   - Tab order follows a logical sequence
-   - Custom components support keyboard interactions
-
-3. **Visual Considerations**:
-   - Color is not the only means of conveying information
-   - Sufficient color contrast for text and UI elements
-   - Form supports browser zoom and text resizing
-
-## Conclusion
-
-The React Dynamic Form Renderer package provides a comprehensive solution for creating dynamic, interactive forms with advanced validation, conditional logic, and third-party API integration. By leveraging the JSON schema approach, you can rapidly develop complex forms without sacrificing flexibility or control.
-
-For more detailed documentation, refer to the [user guide](./docs/user-guide.md) or check out the [example implementations](./example) included with the package.
-
-We welcome contributions and feedback! Please file issues or submit pull requests on our [GitHub repository](https://github.com/ilife-technologies/react-dynamic-form-renderer).
+# React Dynamic Form Renderer
+
+A powerful and flexible React package for rendering dynamic forms with advanced validation, conditional logic, and third-party API integration capabilities.
+
+[![npm version](https://img.shields.io/npm/v/@ilife-tech/react-application-flow-renderer.svg)](https://www.npmjs.com/package/@ilife-tech/react-application-flow-renderer)
+[![license](https://img.shields.io/npm/l/@ilife-tech/react-application-flow-renderer.svg)](https://github.com/ilife-technologies/react-dynamic-form-renderer/blob/main/LICENSE)
+
+## Table of Contents
+
+- [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Form Schema Structure](#form-schema-structure)
+- [API Integration](#api-integration)
+- [Props Reference](#props-reference)
+- [Field Types](#field-types)
+- [Advanced Configuration](#advanced-configuration)
+- [Performance & Engine Options](#performance--engine-options)
+- [Troubleshooting](#troubleshooting)
+- [Examples & Best Practices](#examples--best-practices)
+
+## Features
+
+### Core Capabilities
+
+- **Schema-Driven Forms:** Generate complex forms from JSON schema
+- **Dynamic Validation:** Client and server-side validation support
+- **Conditional Logic:** Show/hide fields based on advanced rule conditions
+- **Third-Party API Integration:** Seamless integration with external APIs
+- **Nested Forms:** Support for complex, nested form structures
+- **Responsive Design:** Mobile-friendly with customizable breakpoints
+- **Accessibility:** WCAG 2.1 compliant components
+
+## Prerequisites
+
+- React 18+
+- Node.js 20+
+- npm 10+ or Yarn
+- Browser support: Latest versions of Chrome, Firefox, Safari, and Edge
+
+## Installation
+
+```bash
+# Using npm
+npm install @ilife-tech/react-application-flow-renderer
+
+# Using yarn
+yarn add @ilife-tech/react-application-flow-renderer
+```
+
+## Quick Start
+
+### Basic Implementation
+
+```jsx
+import React, { useState } from 'react';
+import DynamicForm from '@ilife-tech/react-application-flow-renderer';
+
+const App = () => {
+  // Form schema definition
+  const questionGroups = [
+    {
+      groupId: 'personalInfo',
+      groupName: 'Personal Information',
+      questions: [
+        {
+          questionId: 'fullName',
+          questionType: 'text',
+          label: 'Full Name',
+          validation: { required: true },
+        },
+        {
+          questionId: 'email',
+          questionType: 'email',
+          label: 'Email Address',
+          validation: { required: true, email: true },
+        },
+      ],
+    },
+  ];
+
+  // Action buttons configuration
+  const actionSchema = [
+    { text: 'Submit', action: 'submit' },
+    { text: 'Cancel', action: 'cancel' },
+  ];
+
+  // Form submission handler
+  const handleSubmit = (formState, action) => {
+    console.log('Form submitted:', formState.values);
+    console.log('Action:', action);
+  };
+
+  return (
+    <DynamicForm
+      questionGroups={questionGroups}
+      actionSchema={actionSchema}
+      onSubmit={handleSubmit}
+    />
+  );
+};
+```
+
+### Real-World Example
+
+Below is a comprehensive real-world implementation showcasing advanced features like API integration, state management, and theming:
+
+```jsx
+import React, { useState, useEffect, useCallback, useMemo } from 'react';
+import SectionListRenderer from '@ilife-tech/react-section-renderer';
+import { DynamicForm } from '@ilife-tech/react-application-flow-renderer';
+
+// Constants and configuration
+const API_CONFIG = {
+  BASE_URL: process.env.REACT_APP_API_BASE_URL || '<API_BASE_URL>',
+  ENDPOINTS: {
+    STORE_VENDOR: '<API_ENDPOINT>',
+  },
+  MAX_API_ATTEMPTS: 8,
+};
+
+const INITIAL_QUESTIONS = [
+  {
+    name: 'userToken',
+    value: process.env.REACT_APP_USER_TOKEN || '<USER_TOKEN>',
+  },
+  { name: 'user', value: '<USER_TYPE>' },
+  { name: 'productName', value: '<PRODUCT_NAME>' },
+  { name: 'stateName', value: '<STATE_NAME>' },
+];
+
+// API configuration for third-party integrations
+const apiConfig = {
+  googlePlaces: {
+    apiKey: process.env.REACT_APP_GOOGLE_PLACES_API_KEY,
+    options: {
+      minSearchLength: 3,
+      debounceTime: 300,
+      componentRestrictions: {
+        country: process.env.REACT_APP_GOOGLE_PLACES_REGION || 'US',
+      },
+      types: ['address'],
+      fields: ['address_components', 'formatted_address', 'geometry', 'place_id'],
+      maxRequestsPerSecond: 10,
+      maxRequestsPerDay: 1000,
+      language: process.env.REACT_APP_GOOGLE_PLACES_LANGUAGE,
+      region: process.env.REACT_APP_GOOGLE_PLACES_REGION,
+    },
+  },
+  customApi: {
+    baseUrl: process.env.REACT_APP_CUSTOM_API_BASE_URL,
+    headers: {
+      Authorization: process.env.REACT_APP_AUTH_TOKEN,
+      'Carrier-Auth': process.env.REACT_APP_CARRIER_AUTH,
+    },
+  },
+};
+
+// Theme configuration
+const THEME = {
+  breakpoints: {
+    mobile: '@media (max-width: 480px)',
+    tablet: '@media (min-width: 481px) and (max-width: 768px)',
+    desktop: '@media (min-width: 769px)',
+  },
+  body: {
+    backgroundColor: '#FFFFFF',
+    color: '#333333',
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+    fontSize: '16px',
+    lineHeight: '1.5',
+  },
+  form: {
+    backgroundColor: '#FFFFFF',
+    padding: '20px',
+    maxWidth: '800px',
+    margin: '0 auto',
+    fieldSpacing: '1.5rem',
+    groupSpacing: '2rem',
+  },
+  colors: {
+    primary: '#1D4ED8',
+    secondary: '#6B7280',
+    success: '#059669',
+    danger: '#DC2626',
+    warning: '#D97706',
+    info: '#2563EB',
+    light: '#F3F4F6',
+    dark: '#1F2937',
+    error: '#DC2626',
+    border: '#D1D5DB',
+    inputBackground: '#FFFFFF',
+    headerBackground: '#EFF6FF',
+  },
+  field: {
+    marginBottom: '1rem',
+    width: '100%',
+  },
+  label: {
+    display: 'block',
+    marginBottom: '0.5rem',
+    fontSize: '0.875rem',
+    fontWeight: '500',
+    color: '#374151',
+  },
+  input: {
+    width: '100%',
+    padding: '0.5rem',
+    fontSize: '1rem',
+    borderRadius: '0.375rem',
+    border: '1px solid #D1D5DB',
+    backgroundColor: '#FFFFFF',
+    '&:focus': {
+      outline: 'none',
+      borderColor: '#2563EB',
+      boxShadow: '0 0 0 2px rgba(37, 99, 235, 0.2)',
+    },
+  },
+  error: {
+    color: '#DC2626',
+    fontSize: '0.875rem',
+    marginTop: '0.25rem',
+  },
+};
+
+function App() {
+  // State Management
+  const [formState, setFormState] = useState({
+    storeVenderData: null,
+    questionGroups: [],
+    pageRules: [],
+    pageRuleGroup: [],
+    validationSchema: [],
+    actionSchema: [],
+    sectionSchema: [],
+    caseId: null,
+    pageId: null,
+    apiCallCounter: 0,
+    selectedAction: '',
+    error: null,
+    isLoading: false,
+  });
+
+  // Memoized API headers
+  const headers = useMemo(
+    () => ({
+      'Content-Type': 'application/json',
+      Authorization: process.env.REACT_APP_AUTH_TOKEN || '<AUTH_TOKEN>',
+      CarrierAuthorization: process.env.REACT_APP_CARRIER_AUTH || '<CARRIER_AUTH_TOKEN>',
+    }),
+    []
+  );
+
+  // Transform form data with error handling
+  const transformFormData = useCallback((formData, schema) => {
+    try {
+      // Handle empty array or non-object formData
+      const formDataObj = Array.isArray(formData) || typeof formData !== 'object' ? {} : formData;
+      const { values = {}, visibility = {}, disabled = {} } = formDataObj;
+      const transformedData = [];
+
+      // Process form data based on schema
+      // ... (transform logic omitted for brevity)
+
+      return transformedData;
+    } catch (error) {
+      console.error('Error transforming form data:', error);
+      throw new Error('Failed to transform form data');
+    }
+  }, []);
+
+  // API call with error handling
+  const fetchStoreQuestionVendor = useCallback(
+    async (questions, action = '', nextPageId = '') => {
+      try {
+        const { caseId, pageId } = formState;
+        setFormState((prev) => ({ ...prev, isLoading: true, error: null }));
+
+        const requestPayload = {
+          caseId,
+          pageId,
+          questions,
+          user: '<USER_TYPE>',
+          agentId: '<AGENT_ID>',
+          templateName: '<PRODUCT_NAME>',
+          ...(action && { action }),
+          ...(nextPageId && { nextPageId }),
+        };
+
+        const response = await fetch(`${API_CONFIG.BASE_URL}${API_CONFIG.ENDPOINTS.STORE_VENDOR}`, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify(requestPayload),
+        });
+
+        if (!response.ok) {
+          throw new Error(`API Error: ${response.status}`);
+        }
+
+        const { data: result } = await response.json();
+        const { pageDefinition, sectionList, caseId: newCaseId, pageId: newPageId } = result || {};
+
+        const {
+          questionGroups = [],
+          pageRules: rawPageRules = null,
+          pageRuleGroup: rawPageRuleGroup = null,
+          validationErrors = [],
+          actionButtons = [],
+        } = pageDefinition || {};
+
+        // Process and update state with API response
+        setFormState((prev) => ({
+          ...prev,
+          storeVenderData: result,
+          questionGroups,
+          pageRules: Array.isArray(rawPageRules) ? rawPageRules : [],
+          pageRuleGroup: Array.isArray(rawPageRuleGroup) ? rawPageRuleGroup : [],
+          validationSchema: validationErrors,
+          actionSchema: actionButtons,
+          sectionSchema: sectionList || [],
+          caseId: newCaseId || '',
+          pageId: newPageId || '',
+          selectedAction: action,
+          isLoading: false,
+        }));
+      } catch (error) {
+        console.error('API Error:', error);
+        setFormState((prev) => ({
+          ...prev,
+          error: error.message,
+          isLoading: false,
+        }));
+      }
+    },
+    [formState.caseId, formState.pageId, headers]
+  );
+
+  // Form submission handler
+  const handleSubmit = useCallback(
+    (newFormState, action) => {
+      const { questionGroups } = formState;
+      const transformedData = transformFormData(newFormState, questionGroups);
+      fetchStoreQuestionVendor(transformedData, action);
+    },
+    [fetchStoreQuestionVendor, formState.questionGroups, transformFormData]
+  );
+
+  // Section change handler
+  const handleSectionChange = useCallback(
+    (pageId) => {
+      const { questionGroups } = formState;
+      const transformedData = transformFormData([], questionGroups);
+      fetchStoreQuestionVendor(transformedData, '', pageId);
+    },
+    [fetchStoreQuestionVendor, formState.questionGroups, transformFormData]
+  );
+
+  // Initial data fetch
+  useEffect(() => {
+    fetchStoreQuestionVendor(INITIAL_QUESTIONS);
+  }, []);
+
+  // Extract commonly used state values
+  const {
+    error,
+    isLoading,
+    storeVenderData,
+    sectionSchema,
+    questionGroups,
+    pageRules,
+    pageRuleGroup,
+    validationSchema,
+    actionSchema,
+    pageId,
+  } = formState;
+
+  // Handle API triggers from form fields
+  const handleApiTrigger = (apiRequest) => {
+    // Implementation for API trigger handling
+    console.log('API request:', apiRequest);
+    // Return promise with response structure
+    return Promise.resolve({
+      success: true,
+      data: {
+        // Example: update options for a dropdown
+        options: [
+          { name: 'Option 1', value: 'option1' },
+          { name: 'Option 2', value: 'option2' },
+        ],
+      },
+    });
+  };
+
+  return (
+    <div className="app-container">
+      <header className="app-header">
+        <h1>Dynamic Form Example</h1>
+      </header>
+
+      <div className="app-main">
+        {error && (
+          <div className="error-message" role="alert">
+            {error}
+          </div>
+        )}
+
+        {isLoading && (
+          <div className="loading-indicator" role="status">
+            Loading...
+          </div>
+        )}
+
+        {storeVenderData && (
+          <>
+            <aside className="app-sidebar">
+              {!isLoading && sectionSchema?.length > 0 && (
+                <SectionListRenderer
+                  sectionLists={sectionSchema}
+                  onSectionClick={handleSectionChange}
+                  customStyles={{ backgroundColor: '#f5f5f5' }}
+                  pageId={pageId || sectionSchema[0]?.pageId}
+                />
+              )}
+            </aside>
+
+            <main className="app-content">
+              {questionGroups?.length > 0 && (
+                <DynamicForm
+                  questionGroups={questionGroups}
+                  pageRules={pageRules}
+                  pageRuleGroup={pageRuleGroup}
+                  validationErrors={validationSchema}
+                  actionButtons={actionSchema}
+                  theme={THEME}
+                  onSubmit={handleSubmit}
+                  onApiTrigger={handleApiTrigger}
+                  apiConfig={apiConfig}
+                />
+              )}
+            </main>
+          </>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## Form Schema Structure
+
+The form structure is defined by a JSON schema that specifies question groups and their fields. Each form consists of one or more question groups, each containing multiple field definitions.
+
+### Question Group Structure
+
+```javascript
+{
+  groupId: string,           // Unique identifier for the group
+  groupName: string,         // Display name for the group (optional)
+  description: string,       // Group description (optional)
+  columnCount: number,       // Number of columns for layout (default: 1)
+  visible: boolean,          // Group visibility (default: true)
+  questions: Array<Question> // Array of question objects
+}
+```
+
+### Question (Field) Structure
+
+```javascript
+{
+  questionId: string,       // Unique identifier for the question/field
+  questionType: string,      // Field type (text, dropdown, checkbox, etc.)
+  label: string,             // Field label
+  placeholder: string,       // Field placeholder (optional)
+  helpText: string,          // Help text below the field (optional)
+  defaultValue: any,         // Default field value (optional)
+  validation: Object,        // Validation rules (optional)
+  visible: boolean,          // Field visibility (default: true)
+  disabled: boolean,         // Field disabled state (default: false)
+  required: boolean,         // Whether field is required (default: false)
+  options: Array<Option>,    // Options for select/dropdown/radio fields
+  layout: Object,            // Layout configuration (optional)
+  style: Object,             // Custom styling (optional)
+  apiTrigger: Object         // API integration configuration (optional)
+}
+```
+
+### Action Schema Structure
+
+The action schema defines form buttons and their behaviors:
+
+```javascript
+[
+  {
+    text: string, // Button text
+    action: string, // Action identifier (e.g., 'submit', 'back', 'next')
+    position: string, // Button position (optional, default: 'right')
+  },
+];
+```
+
+## API Integration
+
+The package provides robust third-party API integration capabilities, allowing forms to fetch data, populate options, and submit data to external services.
+
+### Basic API Integration
+
+API integration is handled through the `onApiTrigger` prop, which receives API trigger events from form fields:
+
+```jsx
+import React from 'react';
+import DynamicForm from '@ilife-tech/react-application-flow-renderer';
+import { handleApiTrigger } from './services/apiService';
+
+const MyForm = () => {
+  // Form schema with API trigger configuration
+  const questionGroups = [
+    {
+      groupId: 'locationInfo',
+      questions: [
+        {
+          questionId: 'country',
+          questionType: 'dropdown',
+          label: 'Country',
+          options: [
+            { name: 'United States', value: 'US' },
+            { name: 'Canada', value: 'CA' },
+          ],
+        },
+        {
+          questionId: 'state',
+          questionType: 'dropdown',
+          label: 'State/Province',
+          placeholder: 'Select a state',
+          // API trigger configuration
+          apiTrigger: {
+            type: 'dropdown',
+            dependsOn: ['country'], // Fields this API call depends on
+            apiUrl: 'getStatesByCountry', // API identifier
+            triggerEvents: ['onChange', 'onLoad'], // When to trigger API
+          },
+        },
+      ],
+    },
+  ];
+
+  // API configuration
+  const apiConfig = {
+    baseUrl: process.env.REACT_APP_API_BASE_URL || 'https://api.example.com',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${process.env.REACT_APP_API_TOKEN}`,
+    },
+    timeout: 5000,
+  };
+
+  return (
+    <DynamicForm
+      questionGroups={questionGroups}
+      onApiTrigger={handleApiTrigger}
+      apiConfig={apiConfig}
+    />
+  );
+};
+
+export default MyForm;
+```
+
+### Implementing the API Handler
+
+The API handler function processes API triggers and returns updates to the form. Here's a practical example based on the package's example implementation:
+
+```javascript
+// services/apiService.js
+import { createApiResponse } from '../utils/apiUtils';
+
+/**
+ * Handle API trigger events from form fields
+ * @param {Object} triggerData - Data from the form's onApiTrigger event
+ * @returns {Promise<Object>} - Response with form updates
+ */
+export const handleApiTrigger = async (triggerData) => {
+  const { question, value, triggerType, formState } = triggerData;
+
+  // Extract API configuration
+  const { apiTrigger, questionId } = question;
+
+  // Skip if no API trigger is configured
+  if (!apiTrigger || !apiTrigger.apiUrl) {
+    return null;
+  }
+
+  try {
+    // For dropdown fields that depend on other fields
+    if (question.questionType === 'dropdown' && triggerType === 'onChange') {
+      // Example: Fetch states based on selected country
+      if (apiTrigger.apiUrl === 'getStatesByCountry') {
+        const countryValue = formState.values[apiTrigger.dependsOn[0]];
+
+        // Don't proceed if no country is selected
+        if (!countryValue) {
+          return createApiResponse({
+            options: { [questionId]: [] },
+            values: { [questionId]: '' },
+          });
+        }
+
+        // Make API request
+        const response = await fetch(`${apiConfig.baseUrl}/states?country=${countryValue}`, {
+          headers: apiConfig.headers,
+        });
+
+        const data = await response.json();
+
+        // Map API response to dropdown options
+        const stateOptions = data.map((state) => ({
+          name: state.name,
+          value: state.code,
+        }));
+
+        // Return updates for the form
+        return createApiResponse({
+          options: { [questionId]: stateOptions },
+          visibility: { [questionId]: true },
+          disabled: { [questionId]: false },
+        });
+      }
+    }
+
+    return null;
+  } catch (error) {
+    console.error('API error:', error);
+
+    // Return error response
+    return createApiResponse({
+      apiErrors: { [questionId]: 'Failed to fetch data. Please try again.' },
+    });
+  }
+};
+```
+
+### API Response Structure
+
+API responses should be formatted as an object with field updates:
+
+```javascript
+// utils/apiUtils.js
+
+/**
+ * Create formatted API response for form updates
+ * @param {Object} updates - Updates to apply to the form
+ * @returns {Object} - Formatted response
+ */
+export const createApiResponse = (updates = {}) => {
+  return {
+    // Field values to update
+    values: updates.values || {},
+
+    // Dropdown options to update
+    options: updates.options || {},
+
+    // Field visibility updates
+    visibility: updates.visibility || {},
+
+    // Field disabled state updates
+    disabled: updates.disabled || {},
+
+    // Field required state updates
+    required: updates.required || {},
+
+    // Error messages
+    apiErrors: updates.apiErrors || {},
+
+    // Loading states
+    apiLoading: updates.apiLoading || {},
+  };
+};
+```
+
+### Advanced API Integration Example
+
+Here's a more comprehensive example showing how to handle complex API integration with request queuing and response mapping:
+
+```javascript
+// services/api/handlers/dropdownApiHandler.js
+
+import { createApiResponse } from '../../../utils/apiUtils';
+
+// Request queue for managing concurrent API calls
+class ApiRequestQueue {
+  constructor() {
+    this.queue = new Map();
+  }
+
+  async enqueue(questionId, apiCall) {
+    if (this.queue.has(questionId)) {
+      return this.queue.get(questionId);
+    }
+
+    const promise = apiCall().finally(() => {
+      this.queue.delete(questionId);
+    });
+
+    this.queue.set(questionId, promise);
+    return promise;
+  }
+}
+
+const requestQueue = new ApiRequestQueue();
+
+/**
+ * Handle API calls for dropdown fields
+ * @param {Object} triggerData - API trigger data
+ * @returns {Promise<Object>} Response with options and updates
+ */
+export const handleDropdownApi = async (triggerData) => {
+  const { question, value, triggerType, formState } = triggerData;
+  const { questionId, apiTrigger } = question;
+
+  // Example: Handle different API endpoints based on apiUrl
+  switch (apiTrigger?.apiUrl) {
+    case 'getHouseholdMembers':
+      return requestQueue.enqueue(questionId, () =>
+        getHouseholdMembers(apiTrigger.apiUrl, formState)
+      );
+
+    case 'getStatesByCountry':
+      // Get dependent field value
+      const country = formState.values[apiTrigger.dependsOn[0]];
+      if (!country) {
+        return createApiResponse({
+          options: { [questionId]: [] },
+          disabled: { [questionId]: true },
+        });
+      }
+
+      return requestQueue.enqueue(questionId, () => getStatesByCountry(apiTrigger.apiUrl, country));
+
+    default:
+      return null;
+  }
+};
+
+/**
+ * Example API implementation for fetching states by country
+ */
+async function getStatesByCountry(apiUrl, country) {
+  try {
+    // Here we'd normally implement our API call
+    const response = await fetch(`https://api.example.com/states?country=${country}`);
+    const data = await response.json();
+
+    // Map response to options format
+    const options = data.map((state) => ({
+      name: state.stateName || state.name,
+      value: state.stateCode || state.code,
+    }));
+
+    return createApiResponse({
+      options: { state: options },
+      disabled: { state: false },
+      visibility: { state: true },
+    });
+  } catch (error) {
+    console.error('API error:', error);
+    return createApiResponse({
+      apiErrors: { state: 'Failed to fetch states. Please try again.' },
+      options: { state: [] },
+    });
+  }
+}
+```
+
+## Props Reference
+
+The `DynamicForm` component accepts the following props:
+
+| Prop               | Type       | Required | Default | Description                                       |
+| ------------------ | ---------- | -------- | ------- | ------------------------------------------------- |
+| `questionGroups`   | `Array`    | Yes      | `[]`    | Array of question groups defining form structure  |
+| `actionSchema`     | `Array`    | No       | `[]`    | Array of action buttons configuration             |
+| `onSubmit`         | `Function` | No       | -       | Form submission handler                           |
+| `onApiTrigger`     | `Function` | No       | -       | API trigger event handler                         |
+| `apiConfig`        | `Object`   | No       | `{}`    | API configuration options                         |
+| `theme`            | `Object`   | No       | `{}`    | Theme customization                               |
+| `validationSchema` | `Array`    | No       | `[]`    | Additional validation rules                       |
+| `pageRules`        | `Array`    | No       | `[]`    | Page rules for conditional logic                  |
+| `pageRuleGroup`    | `Array`    | No       | `[]`    | Page rule groups with complex boolean expressions |
+| `debug`            | `Boolean`  | No       | `false` | Enable debug mode                                 |
+| `formApiRef`       | `Object`   | No       | -       | Ref object to access form API methods             |
+| `toastConfig`      | `Object`   | No       | `{}`    | Toast configuration                               |
+
+### Props Details
+
+#### `questionGroups`
+
+An array of question group objects that defines the form structure. Each group contains questions (fields) to render.
+
+```javascript
+const questionGroups = [
+  {
+    groupId: 'group1',
+    groupName: 'Personal Information',
+    questions: [
+      /* question objects */
+    ],
+  },
+];
+```
+
+#### `actionSchema`
+
+An array of action button configurations for the form.
+
+```javascript
+const actionSchema = [
+  { text: 'Submit', action: 'submit' },
+  { text: 'Previous', action: 'back' },
+];
+```
+
+#### `onSubmit`
+
+Callback function called when a form action is triggered. Receives the form state and action identifier.
+
+```javascript
+const handleSubmit = (formState, action) => {
+  // formState contains values, errors, etc.
+  // action is the identifier of the action button clicked
+  if (action === 'submit') {
+    // Handle form submission
+    console.log('Form values:', formState.values);
+  }
+};
+```
+
+#### `onApiTrigger`
+
+Callback function for handling API trigger events from form fields. Receives trigger data object.
+
+```javascript
+const handleApiTrigger = async (triggerData) => {
+  // triggerData contains question, value, triggerType, and formState
+  // Return formatted API response with updates to the form
+};
+```
+
+#### `apiConfig`
+
+Object containing API configuration options passed to the `onApiTrigger` handler.
+
+```javascript
+const apiConfig = {
+  baseUrl: 'https://api.example.com',
+  headers: {
+    'Content-Type': 'application/json',
+    Authorization: 'Bearer YOUR_TOKEN',
+  },
+  timeout: 5000,
+};
+```
+
+## Field Types
+
+The package supports a wide range of field types to handle various input requirements:
+
+### Basic Field Types
+
+| Field Type | Component       | Description                           |
+| ---------- | --------------- | ------------------------------------- |
+| `text`     | `TextField`     | Standard text input field             |
+| `textarea` | `TextAreaField` | Multi-line text input                 |
+| `email`    | `EmailField`    | Email input with validation           |
+| `password` | `PasswordField` | Password input with visibility toggle |
+| `number`   | `NumberField`   | Numeric input with constraints        |
+| `phone`    | `PhoneField`    | Phone number input with formatting    |
+| `currency` | `CurrencyField` | Monetary value input with formatting  |
+| `date`     | `DateField`     | Date picker with calendar             |
+| `datetime` | `DateTimeField` | Combined date and time picker         |
+
+### Selection Field Types
+
+| Field Type        | Component              | Description                                 |
+| ----------------- | ---------------------- | ------------------------------------------- |
+| `dropdown`        | `SelectField`          | Dropdown selection menu                     |
+| `combobox`        | `ComboboxField`        | Searchable dropdown with multiple selection |
+| `radio`           | `RadioField`           | Single-selection radio buttons              |
+| `radioGroup`      | `RadioGroupField`      | Group of radio buttons with custom layout   |
+| `radioSwitch`     | `RadioSwitchField`     | Toggle-style radio selection                |
+| `radioTabButtons` | `RadioTabButtonsField` | Tab-style radio selection                   |
+| `checkbox`        | `CheckboxField`        | Single checkbox                             |
+| `checkboxGroup`   | `CheckboxGroupField`   | Group of checkboxes with multiple selection |
+
+### Specialized Field Types
+
+| Field Type       | Component             | Description                                                |
+| ---------------- | --------------------- | ---------------------------------------------------------- |
+| `address`        | `AddressField`        | Address input with validation and auto-complete            |
+| `beneficiary`    | `BeneficiaryField`    | Complex beneficiary information with percentage validation |
+| `identification` | `IdentificationField` | SSN/ITIN input with masking and validation                 |
+| `file`           | `FileField`           | File upload with preview                                   |
+| `pdf`            | `PDFField`            | PDF file upload and display                                |
+| `cardList`       | `CardListField`       | Dynamic array of nested form fields                        |
+| `display`        | `DisplayTextField`    | Read-only text display                                     |
+| `hyperlink`      | `HyperlinkField`      | Clickable hyperlink field                                  |
+| `button`         | `ButtonField`         | Action button field                                        |
+| `spinner`        | `SpinnerField`        | Loading indicator field                                    |
+
+## Input Masking and Security
+
+The React Dynamic Form Renderer includes advanced **dual masking system** for sensitive data fields, providing both input formatting and security masking capabilities.
+
+### Dual Masking System
+
+The package implements a sophisticated dual masking approach:
+
+1. **Input Masking**: Real-time formatting during user input (e.g., `123-45-6789`)
+2. **Security Masking**: Hide sensitive characters for privacy (e.g., `***-**-6789`)
+
+### Supported Field Types
+
+The following field types support dual masking:
+
+| Field Type    | Input Formatting | Security Masking | Eye Icon Toggle |
+| ------------- | ---------------- | ---------------- | --------------- |
+| `ssn`         | ✅               | ✅               | ✅              |
+| `itin`        | ✅               | ✅               | ✅              |
+| `phonenumber` | ✅               | ✅               | ✅              |
+| `phone`       | ✅               | ✅               | ✅              |
+| `currency`    | ✅               | ❌               | ❌              |
+| `number`      | ✅               | ❌               | ❌              |
+| `percentage`  | ✅               | ❌               | ❌              |
+
+### Configuration Options
+
+#### Input Masking
+
+```javascript
+{
+  "questionId": "ssn_field",
+  "label": "Social Security Number",
+  "questionType": "ssn",
+  "maskInput": "###-##-####",  // Input formatting pattern
+  "required": true
+}
+```
+
+#### Security Masking
+
+```javascript
+{
+  "questionId": "ssn_field",
+  "label": "Social Security Number",
+  "questionType": "ssn",
+  "maskInput": "###-##-####",     // Input formatting
+  "maskingType": "prefix",        // "prefix" or "suffix"
+  "maskingLength": 6,             // Number of characters to mask
+  "required": true
+}
+```
+
+### Masking Patterns
+
+#### Common Patterns
+
+| Field Type | Pattern          | Example Input | Formatted      | Security Masked    |
+| ---------- | ---------------- | ------------- | -------------- | ------------------ |
+| SSN        | `###-##-####`    | 123456789     | 123-45-6789    | **\*-**-6789       |
+| Phone      | `(###) ###-####` | 1234567890    | (123) 456-7890 | (123) 456-\*\*\*\* |
+| ITIN       | `###-##-####`    | 912456789     | 912-45-6789    | **\*-**-6789       |
+
+#### Custom Patterns
+
+You can define custom masking patterns using:
+
+- `#` for digits (0-9)
+- `*` for any character
+- Special characters (hyphens, parentheses, etc.) are preserved
+
+### Eye Icon Toggle
+
+Fields with security masking automatically display an eye icon (👁️/🙈) that allows users to toggle between:
+
+- **Masked View**: Shows security masked value (e.g., `***-**-6789`)
+- **Original View**: Shows formatted value (e.g., `123-45-6789`)
+
+#### Accessibility Features
+
+- **Keyboard Navigation**: Eye icon supports Tab navigation
+- **Keyboard Activation**: Toggle with Enter or Space keys
+- **Screen Reader Support**: Proper ARIA labels and descriptions
+- **Focus Management**: Clear focus indicators
+
+### Advanced Configuration
+
+#### Prefix vs Suffix Masking
+
+```javascript
+// Prefix masking (mask first N characters)
+{
+  "maskingType": "prefix",
+  "maskingLength": 6,
+  // "123-45-6789" → "***-**-6789"
+}
+
+// Suffix masking (mask last N characters)
+{
+  "maskingType": "suffix",
+  "maskingLength": 4,
+  // "123-45-6789" → "123-45-****"
+}
+```
+
+#### Validation with Masking
+
+The masking system integrates seamlessly with validation:
+
+```javascript
+{
+  "questionId": "ssn_field",
+  "maskInput": "###-##-####",
+  "maskingType": "prefix",
+  "maskingLength": 6,
+  "minLength": 9,           // Validates unmasked length
+  "maxLength": 9,           // Validates unmasked length
+  "required": true,
+  "validation": {
+    "pattern": "^\\d{9}$",  // Validates digits only
+    "message": "Please enter a valid 9-digit SSN"
+  }
+}
+```
+
+### Implementation Notes
+
+- **Real-time Processing**: Masking is applied during user input, not just on blur
+- **Form Integration**: Masked values are properly integrated with form state
+- **Performance**: Optimized for large forms with multiple masked fields
+- **Browser Compatibility**: Works across all modern browsers
+- **Mobile Support**: Touch-friendly eye icon and responsive design
+
+### Troubleshooting
+
+#### Common Issues
+
+1. **Masking Not Applied**: Ensure `maskInput` pattern is correctly formatted
+2. **Eye Icon Missing**: Verify both `maskingType` and `maskingLength` are set
+3. **Validation Errors**: Check that validation patterns match unmasked values
+4. **Performance Issues**: Avoid overly complex masking patterns in large forms
+
+#### Debug Tips
+
+```javascript
+// Enable console logging for masking operations
+console.log('Masked Value:', maskedValue);
+console.log('Display Value:', displayValue);
+console.log('Mask Config:', maskConfig);
+```
+
+## Conditional Logic
+
+The Dynamic Form Renderer provides powerful conditional logic capabilities through the `pageRules` and `pageRuleGroup` props.
+
+### PageRules
+
+Page rules define individual conditions and actions for dynamic form behavior:
+
+```javascript
+const pageRules = [
+  {
+    ruleId: 'rule1',
+    triggerQuestionIds: ['101'],
+    comparison: 'equals',
+    compareValue: 'yes',
+    action: 'showquestion',
+    targetQuestionIds: ['201'],
+  },
+  // more rules...
+];
+```
+
+### Enhanced PageRuleGroup
+
+The enhanced `pageRuleGroup` feature provides sophisticated boolean expressions for complex conditional logic:
+
+```javascript
+// New array-based format with complex boolean expressions
+const pageRuleGroup = [
+  {
+    questionId: '40374',
+    evaluationExpression: 'rule1 AND rule2',
+  },
+  {
+    questionId: '40555',
+    evaluationExpression: '(rule1 AND rule2) OR rule3',
+  },
+];
+```
+
+#### Key Features
+
+- **Complex Boolean Logic**: Combine multiple rules with AND/OR operations
+- **Parentheses Support**: Control operator precedence for complex evaluations
+- **Backward Compatibility**: Supports legacy object-based format
+
+#### Expression Syntax
+
+- **Operators**: `AND`, `OR` (case-insensitive)
+- **Rule References**: Use `ruleId` values from the pageRules array
+- **Parentheses**: Group expressions to control evaluation order
+
+#### Examples
+
+```javascript
+// Simple AND condition
+{
+  questionId: "40374",
+  evaluationExpression: "rule1 AND rule2"
+}
+
+// Complex nested conditions
+{
+  questionId: "40890",
+  evaluationExpression: "(rule1 AND rule2) OR (rule3 AND rule4)"
+}
+```
+
+For detailed documentation on the enhanced pageRuleGroup feature, see the [PageRuleGroupEnhancement.md](docs/PageRuleGroupImplementation/PageRuleGroupEnhancement.md) file.
+
+## Advanced Configuration
+
+## Performance & Engine Options
+
+When using the provider-level API, you can tune performance and engine behavior.
+
+### FormProvider props
+
+- `performanceConfig`
+  - `debounceDelayMs: number` (default: 120) – Debounce for textual input processing
+
+- `engineOptions`
+  - `enablePerActionGating: boolean` (default: true) – Toggle per-action gating via questionRules
+  - `maxEvaluationDepth: number` (default: 20) – Reflexive evaluation depth guard
+
+### Example
+
+```jsx
+import { FormProvider } from '@ilife-tech/react-application-flow-renderer/context/FormContext';
+import DynamicFormInner from '@ilife-tech/react-application-flow-renderer/src/components/core/components/DynamicFormInner';
+
+<FormProvider
+  formSchema={questionGroups}
+  questionRuleDetails={questionRuleDetails}
+  questionRules={questionRules}
+  performanceConfig={{ debounceDelayMs: 150 }}
+  engineOptions={{ enablePerActionGating: true, maxEvaluationDepth: 20 }}
+>
+  <DynamicFormInner schema={questionGroups} actionSchema={actionSchema} onSubmit={handleSubmit} />
+</FormProvider>;
+```
+
+Note: The top-level `DynamicForm` abstraction may not expose these knobs directly. Use `FormProvider` for fine-grained control.
+
+### Toast Notifications
+
+The Dynamic Form Renderer uses react-toastify for displaying notifications such as error messages, warnings, and success confirmations.
+
+#### Toast Configuration
+
+The form renderer integrates with your application's react-toastify setup. **Important: Your host application MUST include a `<ToastContainer />` component** for notifications to appear.
+
+```jsx
+// Required: Import react-toastify in your host application
+import { ToastContainer } from 'react-toastify';
+import 'react-toastify/dist/ReactToastify.css';
+
+const App = () => {
+  return (
+    <>
+      {/* Required: Add ToastContainer at the root level */}
+      <ToastContainer />
+
+      <DynamicForm
+        questionGroups={questionGroups}
+        toastConfig={{
+          disableToasts: false, // Disable toast notifications completely (default: false)
+          useHostToastify: true, // Whether to use host app's react-toastify (default: true)
+        }}
+        onSubmit={handleSubmit}
+        onApiTrigger={handleApiTrigger}
+      />
+    </>
+  );
+};
+```
+
+#### API Response Format for Toast Notifications
+
+When implementing the `onApiTrigger` handler, you can return success and error messages that will be displayed as toast notifications:
+
+```javascript
+// Example of API trigger handler with toast notifications
+const handleApiTrigger = async (triggerData) => {
+  try {
+    // Your API logic here
+    const response = await myApiCall(triggerData);
+
+    // Return success message (will display as green toast)
+    return {
+      success: {
+        message: 'Operation completed successfully',
+        // You can also include field-specific success messages
+        // fieldName: 'Field updated successfully'
+      },
+      // Other response properties like updates, options, visibility...
+    };
+  } catch (error) {
+    // Return error message (will display as red toast)
+    return {
+      errors: {
+        error: 'An error occurred during the operation',
+        // You can also include field-specific error messages
+        // fieldName: 'Invalid value for this field'
+      },
+    };
+  }
+};
+```
+
+#### Integration with Host Applications
+
+If your application already uses react-toastify, the renderer will:
+
+1. Use your application's react-toastify instance
+2. Respect your toast styling and configuration
+
+**Important:** Only one `<ToastContainer />` should be rendered in your application tree. The package will not render its own ToastContainer - this must be provided by the host application.
+
+### Toast Configuration
+
+The Dynamic Form Renderer uses react-toastify for displaying notifications. You can configure toast behavior using the `toastConfig` prop:
+
+```jsx
+<DynamicForm
+  // Other props...
+  toastConfig={{
+    disableToasts: false, // Set to true to disable all toast notifications
+    useHostToastify: true, // Set to true to use host application's ToastContainer
+    // Additional toast options can be passed here
+  }}
+/>
+```
+
+#### ToastContainer Requirements
+
+To properly display toast notifications:
+
+1. Import ToastContainer and CSS in your host application:
+
+   ```jsx
+   import { ToastContainer } from 'react-toastify';
+   import 'react-toastify/dist/ReactToastify.css';
+   ```
+
+2. Add the ToastContainer to your app's root component:
+   ```jsx
+   function App() {
+     return (
+       <>
+         <YourAppComponents />
+         <ToastContainer position="top-right" autoClose={5000} />
+       </>
+     );
+   }
+   ```
+
+#### API Response Format for Toast Messages
+
+When implementing custom API triggers with `onApiTrigger`, your handler should return a promise that resolves to an object with the following structure to properly display toast notifications:
+
+```javascript
+const handleApiTrigger = async (triggerData) => {
+  // Your API call implementation
+  try {
+    // Process API call
+    return {
+      // Success messages that will trigger toast notifications
+      success: {
+        message: 'General success message', // General success toast
+        fieldId: 'Field-specific success', // Field-specific success toast
+      },
+      // Optional field updates
+      updates: {
+        fieldId1: 'new value', // Update field values
+        fieldId2: [{ name: 'Option 1', value: 'opt1' }], // Update field options
+      },
+    };
+  } catch (error) {
+    return {
+      // Error messages that will trigger toast notifications
+      errors: {
+        error: 'General error message', // General error toast
+        fieldId: 'Field-specific error', // Field-specific error toast
+      },
+    };
+  }
+};
+```
+
+#### Compatibility Notes
+
+- The Dynamic Form Renderer is compatible with react-toastify v9.1.x for React 17 applications
+- For React 18+ applications, you can use react-toastify v9.x or higher
+- Toast styles will follow your application's theme if available
+- Error and success messages from API responses and form validation will use appropriate toast types
+
+#### Troubleshooting
+
+- **No toasts appear**: Ensure your application has a `<ToastContainer />` component and has imported the CSS
+- **\_useSyncExternalStore error**: This usually indicates a version compatibility issue between React and react-toastify. For React 17, use react-toastify v9.1.x
+- **Multiple toasts appear**: Ensure you only have one `<ToastContainer />` in your application
+
+### Theme Customization
+
+The DynamicForm component supports deep theme customization through the `theme` prop:
+
+```javascript
+const customTheme = {
+  typography: {
+    fontFamily: '"Roboto", "Helvetica", "Arial", sans-serif',
+    fontSize: '16px',
+    lineHeight: 1.5,
+    headings: {
+      h1: { fontSize: '2rem', fontWeight: 700 },
+      h2: { fontSize: '1.5rem', fontWeight: 600 },
+      h3: { fontSize: '1.25rem', fontWeight: 600 },
+    },
+  },
+  palette: {
+    primary: {
+      main: '#0066cc',
+      light: '#3383d6',
+      dark: '#004c99',
+      contrastText: '#ffffff',
+    },
+    error: {
+      main: '#d32f2f',
+      light: '#ef5350',
+      dark: '#c62828',
+      contrastText: '#ffffff',
+    },
+    success: {
+      main: '#2e7d32',
+      light: '#4caf50',
+      dark: '#1b5e20',
+      contrastText: '#ffffff',
+    },
+  },
+  spacing: {
+    unit: '8px',
+    form: '24px',
+    field: '16px',
+  },
+  shape: {
+    borderRadius: '4px',
+  },
+  breakpoints: {
+    xs: 0,
+    sm: 600,
+    md: 960,
+    lg: 1280,
+    xl: 1920,
+  },
+  fields: {
+    input: {
+      height: '40px',
+      padding: '8px 12px',
+      fontSize: '16px',
+      borderRadius: '4px',
+      borderColor: '#cccccc',
+      focusBorderColor: '#0066cc',
+      errorBorderColor: '#d32f2f',
+      background: '#ffffff',
+    },
+    label: {
+      fontSize: '14px',
+      fontWeight: 600,
+      marginBottom: '4px',
+      color: '#333333',
+    },
+    helperText: {
+      fontSize: '12px',
+      color: '#666666',
+      marginTop: '4px',
+    },
+    error: {
+      fontSize: '12px',
+      color: '#d32f2f',
+      marginTop: '4px',
+    },
+  },
+  buttons: {
+    primary: {
+      background: '#0066cc',
+      color: '#ffffff',
+      hoverBackground: '#004c99',
+      fontSize: '16px',
+      padding: '8px 24px',
+      borderRadius: '4px',
+    },
+    secondary: {
+      background: '#f5f5f5',
+      color: '#333333',
+      hoverBackground: '#e0e0e0',
+      fontSize: '16px',
+      padding: '8px 24px',
+      borderRadius: '4px',
+    },
+  },
+};
+
+// Usage
+<DynamicForm
+  questionGroups={questionGroups}
+  theme={customTheme}
+  // Other props
+/>;
+```
+
+### Validation Configuration
+
+#### Client-side Validation
+
+Validation can be defined directly in the form schema or through a separate validation schema:
+
+```javascript
+// In form schema
+const questionGroups = [
+  {
+    groupId: 'personalInfo',
+    questions: [
+      {
+        questionId: 'email',
+        questionType: 'email',
+        label: 'Email Address',
+        validation: {
+          required: true,
+          email: true,
+          requiredMessage: 'Email is required',
+          errorMessage: 'Please enter a valid email address',
+          pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+          patternMessage: 'Email format is invalid',
+        },
+      },
+      {
+        questionId: 'password',
+        questionType: 'password',
+        label: 'Password',
+        validation: {
+          required: true,
+          minLength: 8,
+          minLengthMessage: 'Password must be at least 8 characters',
+          pattern: /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]+$/,
+          patternMessage:
+            'Password must include uppercase, lowercase, number and special character',
+        },
+      },
+    ],
+  },
+];
+
+// Separate validation schema
+const validationSchema = [
+  {
+    field: 'confirmPassword',
+    rules: [
+      'required',
+      {
+        name: 'matchesField',
+        params: ['password'],
+        message: 'Passwords must match',
+      },
+    ],
+  },
+];
+```
+
+#### Available Validation Message Types
+
+| Message Type       | Description                                         |
+| ------------------ | --------------------------------------------------- |
+| `requiredMessage`  | Displayed when a required field is empty            |
+| `errorMessage`     | General error message for field validation          |
+| `lengthMessage`    | Error for overall length validation                 |
+| `minLengthMessage` | Error for minimum length validation                 |
+| `maxLengthMessage` | Error for maximum length validation                 |
+| `patternMessage`   | Error for regex pattern validation                  |
+| `typeMessage`      | Error for type validation (email, number, etc.)     |
+| `formatMessage`    | Error for format validation (phone, currency, etc.) |
+
+### CardList Configuration
+
+The `CardListField` component enables dynamic form arrays with complete validation and state management:
+
+```javascript
+const cardListQuestion = {
+  questionId: 'beneficiaries',
+  questionType: 'cardList',
+  label: 'Beneficiaries',
+  addCardLabel: 'Add Beneficiary',
+  cardSchema: [
+    {
+      groupId: 'beneficiaryInfo',
+      questions: [
+        {
+          questionId: 'name',
+          questionType: 'text',
+          label: 'Full Name',
+          validation: { required: true },
+        },
+        {
+          questionId: 'relationship',
+          questionType: 'dropdown',
+          label: 'Relationship',
+          options: [
+            { name: 'Spouse', value: 'spouse' },
+            { name: 'Child', value: 'child' },
+            { name: 'Parent', value: 'parent' },
+            { name: 'Other', value: 'other' },
+          ],
+          validation: { required: true },
+        },
+        {
+          questionId: 'percentage',
+          questionType: 'currency',
+          label: 'Percentage',
+          validation: {
+            required: true,
+            min: 0,
+            max: 100,
+            minMessage: 'Percentage must be positive',
+            maxMessage: 'Percentage cannot exceed 100%',
+          },
+        },
+      ],
+    },
+  ],
+  validation: {
+    minCards: 1,
+    maxCards: 5,
+    minCardsMessage: 'At least one beneficiary is required',
+    maxCardsMessage: 'Maximum of 5 beneficiaries allowed',
+    totalValidator: (cards) => {
+      // Calculate total percentage across all cards
+      const total = cards.reduce((sum, card) => {
+        const percentage = parseFloat(card.values.percentage) || 0;
+        return sum + percentage;
+      }, 0);
+
+      // Validate total is 100%
+      if (Math.abs(total - 100) > 0.01) {
+        return 'Total percentage must equal 100%';
+      }
+
+      return null; // No error
+    },
+  },
+};
+```
+
+#### CardList State Management
+
+Each card in a CardList manages its own state, including:
+
+- Form values
+- Validation errors
+- Visibility rules
+- Disabled states
+
+You can access the CardList state through the form context:
+
+```javascript
+const MyForm = () => {
+  const formApiRef = useRef(null);
+
+  const handleSubmit = (formState) => {
+    // Access cardList data as an array of card states
+    const beneficiaries = formState.values.beneficiaries;
+    console.log('Beneficiary cards:', beneficiaries);
+  };
+
+  return (
+    <DynamicForm questionGroups={questionGroups} onSubmit={handleSubmit} formApiRef={formApiRef} />
+  );
+};
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### API Integration Issues
+
+| Issue                           | Solution                                                                           |
+| ------------------------------- | ---------------------------------------------------------------------------------- |
+| API calls not triggering        | Ensure `apiTrigger` configuration in field schema includes correct `triggerEvents` |
+| API responses not updating form | Verify that the `onApiTrigger` handler returns the correct response structure      |
+| Multiple concurrent API calls   | Use request queuing as shown in the advanced API integration example               |
+| CORS errors                     | Configure proper CORS headers in your API or use a proxy service                   |
+
+#### Validation Issues
+
+| Issue                          | Solution                                                                         |
+| ------------------------------ | -------------------------------------------------------------------------------- |
+| ValidationSchema not applying  | Ensure field names in validation schema match questionIds in form schema         |
+| Custom validation not working  | Check that validation functions return error message strings, not boolean values |
+| Form submitting with errors    | Verify that onSubmit handler checks formState.errors before proceeding           |
+| Cross-field validation failing | Use the validationSchema approach for dependencies between fields                |
+
+#### Rendering Issues
+
+| Issue                                | Solution                                                       |
+| ------------------------------------ | -------------------------------------------------------------- |
+| Fields not respecting column layout  | Check columnCount setting in group configuration               |
+| Theme customizations not applying    | Ensure theme prop structure matches expected format            |
+| Responsive layout issues             | Verify breakpoints in theme configuration                      |
+| Fields rendering in unexpected order | Check if columns are properly balanced in group configurations |
+
+### Debugging Tips
+
+#### Using Debug Mode
+
+Enable debug mode to get verbose console output of form state changes:
+
+```jsx
+<DynamicForm
+  questionGroups={questionGroups}
+  debug={true}
+  // Other props
+/>
+```
+
+#### Accessing Form API
+
+Use the formApiRef prop to access form methods imperatively:
+
+```jsx
+const MyForm = () => {
+  const formApiRef = useRef(null);
+
+  const handleClick = () => {
+    // Access form API methods
+    const api = formApiRef.current;
+
+    // Get current form state
+    const state = api.getState();
+    console.log('Form values:', state.values);
+
+    // Set field value
+    api.setValue('email', 'user@example.com');
+
+    // Validate specific field
+    api.validateField('email');
+
+    // Validate entire form
+    api.validateForm().then((errors) => {
+      console.log('Validation errors:', errors);
+    });
+  };
+
+  return (
+    <>
+      <DynamicForm questionGroups={questionGroups} formApiRef={formApiRef} />
+      <button onClick={handleClick}>Debug Form</button>
+    </>
+  );
+};
+```
+
+### Performance Optimization
+
+#### Large Forms
+
+For large forms with many fields:
+
+- Split form into multiple pages or sections
+- Use the `visibleGroups` prop to only render visible question groups
+- Implement form sections with conditional rendering
+- Consider lazy loading for complex field components
+
+#### API Efficiency
+
+Improve API integration performance:
+
+- Implement response caching as shown in API integration examples
+- Use debounce for onChange API triggers
+- Batch API calls when possible
+- Implement request cancellation for outdated requests
+
+## Examples & Best Practices
+
+### Real-world Implementation Patterns
+
+#### Multi-step Form Wizard
+
+Implement a form wizard with progress tracking:
+
+```jsx
+import React, { useState } from 'react';
+import DynamicForm from '@ilife-tech/react-application-flow-renderer';
+
+const MultiStepForm = () => {
+  const [step, setStep] = useState(0);
+  const [formData, setFormData] = useState({});
+
+  // Define steps with their schemas
+  const steps = [
+    {
+      title: 'Personal Information',
+      schema: [
+        {
+          groupId: 'personal',
+          questions: [
+            /* Personal info questions */
+          ],
+        },
+      ],
+      actions: [{ text: 'Next', action: 'next' }],
+    },
+    {
+      title: 'Contact Details',
+      schema: [
+        {
+          groupId: 'contact',
+          questions: [
+            /* Contact info questions */
+          ],
+        },
+      ],
+      actions: [
+        { text: 'Back', action: 'back' },
+        { text: 'Next', action: 'next' },
+      ],
+    },
+    {
+      title: 'Review & Submit',
+      schema: [
+        {
+          groupId: 'review',
+          questions: [
+            /* Review fields */
+          ],
+        },
+      ],
+      actions: [
+        { text: 'Back', action: 'back' },
+        { text: 'Submit', action: 'submit' },
+      ],
+    },
+  ];
+
+  const currentStep = steps[step];
+
+  const handleAction = (state, action) => {
+    if (action === 'next' && step < steps.length - 1) {
+      // Store current step data
+      setFormData((prev) => ({ ...prev, ...state.values }));
+      setStep(step + 1);
+    } else if (action === 'back' && step > 0) {
+      setStep(step - 1);
+    } else if (action === 'submit') {
+      // Combine all step data and submit
+      const finalData = { ...formData, ...state.values };
+      console.log('Submitting form:', finalData);
+      // Submit to server
+    }
+  };
+
+  return (
+    <div className="multi-step-form">
+      <div className="progress-bar">
+        {steps.map((s, i) => (
+          <div key={i} className={`step ${i <= step ? 'active' : ''}`}>
+            {s.title}
+          </div>
+        ))}
+      </div>
+
+      <DynamicForm
+        questionGroups={currentStep.schema}
+        actionSchema={currentStep.actions}
+        initialValues={formData}
+        onSubmit={handleAction}
+      />
+    </div>
+  );
+};
+```
+
+#### Dynamic API-driven Form
+
+Create a form that dynamically loads its schema from an API:
+
+```jsx
+import React, { useState, useEffect } from 'react';
+import DynamicForm from '@ilife-tech/react-application-flow-renderer';
+import { handleApiTrigger } from './services/apiService';
+
+const DynamicApiForm = ({ formId }) => {
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+  const [formSchema, setFormSchema] = useState(null);
+
+  useEffect(() => {
+    async function fetchFormSchema() {
+      try {
+        setLoading(true);
+
+        // Fetch form schema from API
+        const response = await fetch(`https://api.example.com/forms/${formId}`);
+
+        if (!response.ok) {
+          throw new Error(`Failed to load form: ${response.statusText}`);
+        }
+
+        const data = await response.json();
+
+        setFormSchema({
+          questionGroups: data.groups,
+          actionSchema: data.actions,
+          initialValues: data.initialValues || {},
+        });
+      } catch (err) {
+        setError(err.message);
+      } finally {
+        setLoading(false);
+      }
+    }
+
+    fetchFormSchema();
+  }, [formId]);
+
+  const handleSubmit = async (formState, action) => {
+    if (action === 'submit') {
+      try {
+        // Submit form data to API
+        const response = await fetch('https://api.example.com/submissions', {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({
+            formId,
+            values: formState.values,
+          }),
+        });
+
+        const result = await response.json();
+        console.log('Submission result:', result);
+      } catch (err) {
+        console.error('Submission error:', err);
+      }
+    }
+  };
+
+  if (loading) {
+    return <div className="loading">Loading form...</div>;
+  }
+
+  if (error) {
+    return <div className="error">{error}</div>;
+  }
+
+  return (
+    <DynamicForm
+      questionGroups={formSchema.questionGroups}
+      actionSchema={formSchema.actionSchema}
+      initialValues={formSchema.initialValues}
+      onSubmit={handleSubmit}
+      onApiTrigger={handleApiTrigger}
+    />
+  );
+};
+```
+
+### Security Best Practices
+
+1. **API Key Management**:
+   - Never hardcode API keys in your JavaScript code
+   - Use environment variables for all sensitive credentials
+   - Consider using token exchange services for third-party APIs
+
+2. **Sensitive Data Handling**:
+   - Use the built-in masking features for fields like SSN and credit card numbers
+   - Avoid storing sensitive data in localStorage or sessionStorage
+   - Clear sensitive form data after submission
+
+3. **Input Validation**:
+   - Always validate both on client and server side
+   - Use strong validation rules for sensitive fields
+   - Implement proper error handling for failed validations
+
+### Accessibility Guidelines
+
+1. **Screen Reader Support**:
+   - All form fields include proper ARIA attributes
+   - Error messages are announced to screen readers
+   - Focus management follows a logical flow
+
+2. **Keyboard Navigation**:
+   - All interactive elements are focusable
+   - Tab order follows a logical sequence
+   - Custom components support keyboard interactions
+
+3. **Visual Considerations**:
+   - Color is not the only means of conveying information
+   - Sufficient color contrast for text and UI elements
+   - Form supports browser zoom and text resizing
+
+## Conclusion
+
+The React Dynamic Form Renderer package provides a comprehensive solution for creating dynamic, interactive forms with advanced validation, conditional logic, and third-party API integration. By leveraging the JSON schema approach, you can rapidly develop complex forms without sacrificing flexibility or control.
+
+For more detailed documentation, refer to the [user guide](./docs/user-guide.md) or check out the [example implementations](./example) included with the package.
+
+We welcome contributions and feedback! Please file issues or submit pull requests on our [GitHub repository](https://github.com/ilife-technologies/react-dynamic-form-renderer).