@ilife-tech/react-application-flow-renderer 1.0.17 → 1.0.20

package/README.md

@@ -16,6 +16,7 @@ A powerful and flexible React package for rendering dynamic forms with advanced
 - [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)
 
@@ -314,8 +315,7 @@ function App() {
           storeVenderData: result,
           questionGroups,
           pageRules: Array.isArray(rawPageRules) ? rawPageRules : [],
-          pageRuleGroup:
-            Array.isArray(rawPageRuleGroup) ? rawPageRuleGroup : [],
+          pageRuleGroup: Array.isArray(rawPageRuleGroup) ? rawPageRuleGroup : [],
           validationSchema: validationErrors,
           actionSchema: actionButtons,
           sectionSchema: sectionList || [],
@@ -777,20 +777,20 @@ async function getStatesByCountry(apiUrl, country) {
 
 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                 |
+| 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                              |
+| `debug`            | `Boolean`  | No       | `false` | Enable debug mode                                 |
+| `formApiRef`       | `Object`   | No       | -       | Ref object to access form API methods             |
+| `toastConfig`      | `Object`   | No       | `{}`    | Toast configuration                               |
 
 ### Props Details
 
@@ -908,6 +908,157 @@ The package supports a wide range of field types to handle various input require
 | `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.
@@ -919,12 +1070,12 @@ 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"]
+    ruleId: 'rule1',
+    triggerQuestionIds: ['101'],
+    comparison: 'equals',
+    compareValue: 'yes',
+    action: 'showquestion',
+    targetQuestionIds: ['201'],
   },
   // more rules...
 ];
@@ -938,13 +1089,13 @@ The enhanced `pageRuleGroup` feature provides sophisticated boolean expressions
 // New array-based format with complex boolean expressions
 const pageRuleGroup = [
   {
-    questionId: "40374",
-    evaluationExpression: "rule1 AND rule2"
+    questionId: '40374',
+    evaluationExpression: 'rule1 AND rule2',
   },
   {
-    questionId: "40555",
-    evaluationExpression: "(rule1 AND rule2) OR rule3"
-  }
+    questionId: '40555',
+    evaluationExpression: '(rule1 AND rule2) OR rule3',
+  },
 ];
 ```
 
@@ -980,6 +1131,38 @@ For detailed documentation on the enhanced pageRuleGroup feature, see the [PageR
 
 ## 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.
@@ -1705,13 +1888,11 @@ const DynamicApiForm = ({ formId }) => {
 ### 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
@@ -1724,13 +1905,11 @@ const DynamicApiForm = ({ formId }) => {
 ### 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