@syncfusion/ej2-react-form-renderer 0.1.0-beta → 0.1.1-beta

package/src/ConditionalRuleEngine.js

@@ -0,0 +1,489 @@
+/**
+ * ConditionalRuleEngine - Core rule evaluation engine for conditional behaviors
+ *
+ * Evaluates declarative condition rules (from QueryBuilder or manual JSON) against
+ * form state to determine field visibility, read-only state, disabled state, and
+ * which validators should apply.
+ *
+ * @spec CONDITIONAL-VALIDATION.md
+ * @requirement Tasks 3.1-3.12: ConditionalRuleEngine implementation
+ *
+ * Features:
+ * - Simple rule evaluation (field operator value)
+ * - Composite rules (AND/OR combinations with nesting)
+ * - Conditional validators (apply validator only when condition met)
+ * - Relationship validators (cross-field validation with safe expression eval)
+ * - Behavioral flags (visibility, readOnly, disabled)
+ * - Error handling with safe defaults
+ *
+ * Security:
+ * - Uses expr-eval for safe expression evaluation (no eval())
+ * - Defaults to safe behavior on errors (visible, not disabled, not read-only)
+ *
+ * @example
+ * ```typescript
+ * const isVisible = ConditionalRuleEngine.isFieldVisible(
+ *   component.conditions,
+ *   { country: 'US', age: 25 }
+ * );
+ *
+ * const behaviors = ConditionalRuleEngine.applyConditionalBehaviors(
+ *   component.conditions,
+ *   formValues
+ * );
+ * ```
+ */
+import { Internationalization } from '@syncfusion/ej2-base';
+/**
+ * ConditionalRuleEngine class
+ *
+ * @spec CONDITIONAL-VALIDATION.md - Core rule evaluation engine
+ * @requirement Phase 1: Conditional visibility, readOnly, disabled behaviors
+ */
+export class ConditionalRuleEngine {
+    /**
+     * Evaluate a conditional rule against form values
+     *
+     * Handles both simple rules (field operator value) and composite rules (AND/OR).
+     * Returns false for malformed rules.
+     *
+     * @spec CONDITIONAL-VALIDATION.md - evaluateCondition method
+     * @requirement Task 3.2: Implement evaluateCondition with simple and composite handling
+     *
+     * @param rule - ConditionalRule or CompositeConditionalRule
+     * @param formValues - Current form field values (key = field name, value = field value)
+     * @returns true if condition met, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const rule = { field: 'age', operator: 'greaterThan', value: 18 };
+     * const isAdult = ConditionalRuleEngine.evaluateCondition(rule, { age: 25 });
+     * // isAdult = true
+     * ```
+     */
+    static evaluateCondition(rule, formValues) {
+        try {
+            // Handle simple rule (field operator value)
+            if ('field' in rule && 'operator' in rule && 'value' in rule) {
+                return this.evaluateSimpleRule(rule, formValues);
+            }
+            // Handle composite rule (AND/OR)
+            if ('condition' in rule && 'rules' in rule) {
+                return this.evaluateCompositeRule(rule, formValues);
+            }
+            // Malformed rule - default to false (safe default)
+            console.warn('ConditionalRuleEngine: Malformed rule detected', rule);
+            return false;
+        }
+        catch (error) {
+            console.error('ConditionalRuleEngine: Error evaluating condition', error);
+            return false; // Safe default on error
+        }
+    }
+    /**
+     * Evaluate simple field comparison rule
+     *
+     * Supports operators: equal, notEqual, greaterThan, lessThan, greaterThanOrEqual,
+     * lessThanOrEqual, in, notIn, contains, notContains.
+     *
+     * Handles both camelCase (greaterThan) and lowercase (greaterthan) operator formats
+     * for compatibility with QueryBuilder output.
+     *
+     * @spec CONDITIONAL-VALIDATION.md - evaluateSimpleRule method
+     * @requirement Task 3.3: Implement evaluateSimpleRule supporting all operators
+     *
+     * @param rule - Simple conditional rule with field, operator, value
+     * @param formValues - Current form field values
+     * @returns true if comparison is true, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const rule = { field: 'email', operator: 'contains', value: '@' };
+     * const hasAt = evaluateSimpleRule(rule, { email: 'test@example.com' });
+     * // hasAt = true
+     * ```
+     */
+    static evaluateSimpleRule(rule, formValues) {
+        try {
+            const fieldValue = formValues[rule.field];
+            const operator = rule.operator.toLowerCase();
+            // Allow evaluation for operators that make sense when value is undefined/empty
+            if (fieldValue === undefined) {
+                const allowedForUndefined = ['equal', 'equals', 'notequal', 'notequals', 'isempty', 'isnotempty'];
+                if (!allowedForUndefined.includes(operator)) {
+                    return false;
+                }
+            }
+            // Check if field value is an array (for multiselect, checkboxGroup)
+            const isFieldArray = Array.isArray(fieldValue);
+            const intl = new Internationalization();
+            switch (operator) {
+                case 'equal':
+                case 'equals':
+                    return fieldValue === rule.value;
+                case 'notequal':
+                case 'notequals':
+                    return fieldValue !== rule.value;
+                case 'startswith': return fieldValue.startsWith(rule.value);
+                case 'doesnotstartswith': return !fieldValue.startsWith(rule.value);
+                case 'greaterthan':
+                case 'lessthan':
+                case 'greaterthanorequal':
+                case 'lessthanorequal': {
+                    const ln = Number(fieldValue);
+                    const rn = Number(rule.value);
+                    if (!Number.isNaN(ln) && !Number.isNaN(rn)) {
+                        if (operator === 'greaterthan')
+                            return ln > rn;
+                        if (operator === 'lessthan')
+                            return ln < rn;
+                        if (operator === 'greaterthanorequal')
+                            return ln >= rn;
+                        return ln <= rn;
+                    }
+                    return false;
+                }
+                case 'dategreaterthan':
+                case 'datelessthan': {
+                    // try date comparison first
+                    const leftTs = intl.parseDate(fieldValue, { format: 'MM/dd/yyyy' });
+                    const rightTs = intl.parseDate(rule.value, { format: 'MM/dd/yyyy' });
+                    if (leftTs !== null && rightTs !== null) {
+                        if (operator === 'dategreaterthan')
+                            return leftTs > rightTs;
+                        if (operator === 'datelessthan')
+                            return leftTs < rightTs;
+                        return leftTs <= rightTs;
+                    }
+                    return false;
+                }
+                case 'timegreaterthan':
+                case 'timelessthan': {
+                    // Parse time strings (format: hh:mm a)
+                    const leftTime = intl.parseDate(fieldValue, { format: 'hh:mm a', type: 'time' });
+                    const rightTime = intl.parseDate(rule.value, { format: 'hh:mm a', type: 'time' });
+                    if (leftTime !== null && rightTime !== null) {
+                        if (operator === 'timegreaterthan')
+                            return leftTime > rightTime;
+                        if (operator === 'timelessthan')
+                            return leftTime < rightTime;
+                    }
+                    return false;
+                }
+                case 'datetimegreaterthan':
+                case 'datetimelessthan': {
+                    // Parse datetime strings (format: MM/dd/yyyy hh:mm a)
+                    const leftDateTime = intl.parseDate(fieldValue, { format: 'MM/dd/yyyy hh:mm a', type: 'dateTime' });
+                    const rightDateTime = intl.parseDate(rule.value, { format: 'MM/dd/yyyy hh:mm a', type: 'dateTime' });
+                    if (leftDateTime !== null && rightDateTime !== null) {
+                        if (operator === 'datetimegreaterthan')
+                            return leftDateTime > rightDateTime;
+                        if (operator === 'datetimelessthan')
+                            return leftDateTime < rightDateTime;
+                    }
+                    return false;
+                }
+                case 'contains':
+                    // If field value is array, check if array contains the specific value(s)
+                    if (isFieldArray) {
+                        // Parse comma-separated values in rule.value if it's a string
+                        if (typeof rule.value === 'string' && rule.value.includes(',')) {
+                            const searchValues = rule.value.split(',').map(v => v.trim());
+                            // Check if array contains ANY of the search values
+                            return searchValues.some(searchVal => fieldValue.includes(searchVal));
+                        }
+                        return fieldValue.includes(rule.value);
+                    }
+                    // Otherwise, check string contains
+                    return String(fieldValue).includes(String(rule.value));
+                case 'notcontains':
+                    // If field value is array, check if array does NOT contain the specific value(s)
+                    if (isFieldArray) {
+                        // Parse comma-separated values in rule.value if it's a string
+                        if (typeof rule.value === 'string' && rule.value.includes(',')) {
+                            const searchValues = rule.value.split(',').map(v => v.trim());
+                            // Check if array contains NONE of the search values
+                            return !searchValues.some(searchVal => fieldValue.includes(searchVal));
+                        }
+                        return !fieldValue.includes(rule.value);
+                    }
+                    // Otherwise, check string does not contain
+                    return !String(fieldValue).includes(String(rule.value));
+                case 'isempty':
+                    // Check if array is empty
+                    if (isFieldArray) {
+                        return fieldValue.length === 0;
+                    }
+                    // For non-arrays, check if falsy or empty string
+                    return !fieldValue || String(fieldValue).length === 0;
+                case 'isnotempty':
+                    // Check if array has items
+                    if (isFieldArray) {
+                        return fieldValue.length > 0;
+                    }
+                    // For non-arrays, check if truthy and not empty string
+                    return !!fieldValue && String(fieldValue).length > 0;
+                default:
+                    console.warn(`ConditionalRuleEngine: Unknown operator "${rule.operator}"`);
+                    return false;
+            }
+        }
+        catch (error) {
+            console.error('ConditionalRuleEngine: Error in evaluateSimpleRule', error);
+            return false;
+        }
+    }
+    /**
+     * Evaluate composite rule with AND/OR logic
+     *
+     * Recursively evaluates nested rules with AND (all must be true) or OR
+     * (at least one must be true) logic.
+     *
+     * @spec CONDITIONAL-VALIDATION.md - evaluateCompositeRule method
+     * @requirement Task 3.4: Implement evaluateCompositeRule for AND/OR logic
+     *
+     * @param rule - Composite rule with condition ('and'|'or') and rules array
+     * @param formValues - Current form field values
+     * @returns true if composite condition met, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const rule = {
+     *   condition: 'and',
+     *   rules: [
+     *     { field: 'age', operator: 'greaterThan', value: 18 },
+     *     { field: 'country', operator: 'equal', value: 'US' }
+     *   ]
+     * };
+     * const isEligible = evaluateCompositeRule(rule, { age: 25, country: 'US' });
+     * // isEligible = true
+     * ```
+     */
+    static evaluateCompositeRule(rule, formValues) {
+        try {
+            if (!Array.isArray(rule.rules) || rule.rules.length === 0) {
+                console.warn('ConditionalRuleEngine: Composite rule has no rules');
+                return false;
+            }
+            const condition = rule.condition.toLowerCase();
+            if (condition === 'and') {
+                // All rules must be true
+                return rule.rules.every((childRule) => this.evaluateCondition(childRule, formValues));
+            }
+            else if (condition === 'or') {
+                // At least one rule must be true
+                return rule.rules.some((childRule) => this.evaluateCondition(childRule, formValues));
+            }
+            else {
+                console.warn(`ConditionalRuleEngine: Unknown composite condition "${rule.condition}"`);
+                return false;
+            }
+        }
+        catch (error) {
+            console.error('ConditionalRuleEngine: Error in evaluateCompositeRule', error);
+            return false;
+        }
+    }
+    /**
+     * Check if field should be visible
+     *
+     * Evaluates visibleWhen condition. Defaults to true (visible) if no condition
+     * is defined or on error.
+     *
+     * @spec CONDITIONAL-VALIDATION.md - isFieldVisible method
+     * @requirement Task 3.8: Implement isFieldVisible (defaults to true if no condition)
+     *
+     * @param conditions - FormComponentConditions containing visibleWhen rule
+     * @param formValues - Current form field values
+     * @returns true if field should be visible, false if hidden
+     *
+     * @example
+     * ```typescript
+     * const conditions = {
+     *   visibleWhen: { field: 'showEmail', operator: 'equal', value: true }
+     * };
+     * const visible = isFieldVisible(conditions, { showEmail: true });
+     * // visible = true
+     * ```
+     */
+    static isFieldVisible(conditions, formValues) {
+        try {
+            if (!conditions?.visibleWhen) {
+                return true; // Default: visible if no condition
+            }
+            return this.evaluateCondition(conditions.visibleWhen, formValues);
+        }
+        catch (error) {
+            console.error('ConditionalRuleEngine: Error in isFieldVisible', error);
+            return true; // Safe default: visible on error
+        }
+    }
+    /**
+     * Check if field should be read-only
+     *
+     * Evaluates readOnlyWhen condition. Defaults to false (editable) if no
+     * condition is defined or on error.
+     *
+     * @spec CONDITIONAL-VALIDATION.md - isFieldReadOnly method
+     * @requirement Task 3.9: Implement isFieldReadOnly (defaults to false if no condition)
+     *
+     * @param conditions - FormComponentConditions containing readOnlyWhen rule
+     * @param formValues - Current form field values
+     * @returns true if field should be read-only, false if editable
+     *
+     * @example
+     * ```typescript
+     * const conditions = {
+     *   readOnlyWhen: { field: 'isVerified', operator: 'equal', value: true }
+     * };
+     * const readOnly = isFieldReadOnly(conditions, { isVerified: true });
+     * // readOnly = true
+     * ```
+     */
+    static isFieldReadOnly(conditions, formValues) {
+        try {
+            if (!conditions?.readOnlyWhen) {
+                return false; // Default: not read-only if no condition
+            }
+            return this.evaluateCondition(conditions.readOnlyWhen, formValues);
+        }
+        catch (error) {
+            console.error('ConditionalRuleEngine: Error in isFieldReadOnly', error);
+            return false; // Safe default: not read-only on error
+        }
+    }
+    /**
+     * Check if field should be disabled
+     *
+     * Evaluates disabledWhen condition. Defaults to false (enabled) if no
+     * condition is defined or on error.
+     *
+     * @spec CONDITIONAL-VALIDATION.md - isFieldDisabled method
+     * @requirement Task 3.10: Implement isFieldDisabled (defaults to false if no condition)
+     *
+     * @param conditions - FormComponentConditions containing disabledWhen rule
+     * @param formValues - Current form field values
+     * @returns true if field should be disabled, false if enabled
+     *
+     * @example
+     * ```typescript
+     * const conditions = {
+     *   disabledWhen: { field: 'orderStatus', operator: 'equal', value: 'completed' }
+     * };
+     * const disabled = isFieldDisabled(conditions, { orderStatus: 'completed' });
+     * // disabled = true
+     * ```
+     */
+    static isFieldDisabled(conditions, formValues) {
+        try {
+            if (!conditions?.disabledWhen) {
+                return false; // Default: not disabled if no condition
+            }
+            return this.evaluateCondition(conditions.disabledWhen, formValues);
+        }
+        catch (error) {
+            console.error('ConditionalRuleEngine: Error in isFieldDisabled', error);
+            return false; // Safe default: not disabled on error
+        }
+    }
+    /**
+     * Check if field should be hidden
+     *
+     * Evaluates hideWhen condition. Defaults to false (visible) if no condition
+     * is defined or on error.
+     *
+     * @param conditions - FormComponentConditions containing hideWhen rule
+     * @param formValues - Current form field values
+     * @returns true if field should be hidden, false if visible
+     *
+     * @example
+     * ```typescript
+     * const conditions = {
+     *   hideWhen: { field: 'hideEmail', operator: 'equal', value: true }
+     * };
+     * const hidden = isFieldHidden(conditions, { hideEmail: true });
+     * // hidden = true
+     * ```
+     */
+    static isFieldHidden(conditions, formValues) {
+        try {
+            if (!conditions?.hideWhen) {
+                return false; // Default: not hidden if no condition
+            }
+            return this.evaluateCondition(conditions.hideWhen, formValues);
+        }
+        catch (error) {
+            console.error('ConditionalRuleEngine: Error in isFieldHidden', error);
+            return false; // Safe default: not hidden on error
+        }
+    }
+    /**
+     * Check if field should be required
+     *
+     * Evaluates requiredWhen condition. Defaults to false (not required) if no condition
+     * is defined or on error.
+     *
+     * @param conditions - FormComponentConditions containing requiredWhen rule
+     * @param formValues - Current form field values
+     * @returns true if field should be required, false if optional
+     *
+     * @example
+     * ```typescript
+     * const conditions = {
+     *   requiredWhen: { field: 'requireDetails', operator: 'equal', value: true }
+     * };
+     * const required = isFieldRequired(conditions, { requireDetails: true });
+     * // required = true
+     * ```
+     */
+    static isFieldRequired(conditions, formValues) {
+        try {
+            if (!conditions?.requiredWhen) {
+                return false; // Default: not required if no condition
+            }
+            return this.evaluateCondition(conditions.requiredWhen, formValues);
+        }
+        catch (error) {
+            console.error('ConditionalRuleEngine: Error in isFieldRequired', error);
+            return false; // Safe default: not required on error
+        }
+    }
+    /**
+     * Get value to set for field if condition is met
+     *
+     * Evaluates setValueWhen condition and returns the value to assign if true.
+     * Returns undefined if no condition is defined, condition not met, or on error.
+     *
+     * @param conditions - FormComponentConditions containing setValueWhen rule
+     * @param formValues - Current form field values
+     * @returns The value to set if condition met, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const conditions = {
+     *   setValueWhen: {
+     *     condition: { field: 'country', operator: 'equal', value: 'US' },
+     *     value: 'United States'
+     *   }
+     * };
+     * const value = getConditionalValue(conditions, { country: 'US' });
+     * // value = 'United States'
+     * ```
+     */
+    static getConditionalValue(conditions, formValues) {
+        try {
+            if (!conditions?.setValueWhen) {
+                return undefined;
+            }
+            const isMet = this.evaluateCondition(conditions.setValueWhen.condition, formValues);
+            if (isMet) {
+                return conditions.setValueWhen.value;
+            }
+            return undefined;
+        }
+        catch (error) {
+            console.error('ConditionalRuleEngine: Error in getConditionalValue', error);
+            return undefined;
+        }
+    }
+}

package/src/DataGridComponent.d.ts

@@ -14,7 +14,6 @@ export interface DataGridRef {
  */
 export interface DataGridComponentProps extends GridComponentSchema {
     onDataChange?: (data: Record<string, any>[]) => void;
-    isPreviewMode?: boolean;
 }
 /**
  * DataGridComponent: Wrapper around Syncfusion GridComponent

package/src/DataGridComponent.js

@@ -36,7 +36,7 @@ import { GridComponent, ColumnsDirective, ColumnDirective, Inject, Toolbar, Edit
  * - Maps GridColumn.validationRules to ColumnDirective.validationRules
  * - Renders Syncfusion toolbar with CRUD actions based on allowAdding/Editing/Deleting
  */
-export const DataGridComponent = React.forwardRef(({ id, columns, dataSource = [], height = '200px', width = '100%', pageSize = 6, allowPaging = true, allowAdding = true, allowEditing = true, allowDeleting = true, onDataChange, isPreviewMode = false }, ref) => {
+export const DataGridComponent = React.forwardRef(({ id, columns, dataSource = [], height = '200px', width = '100%', locale, cssClass, pageSize = 6, allowPaging = true, allowAdding = true, allowEditing = true, allowDeleting = true, onDataChange }, ref) => {
     // Internal state: maintain current grid data
     const [_currentData, setCurrentData] = useState(Array.isArray(dataSource) ? dataSource : []);
     const gridRef = useRef(null);
@@ -62,23 +62,7 @@ export const DataGridComponent = React.forwardRef(({ id, columns, dataSource = [
     }, [columns, allowAdding, allowDeleting, allowEditing, allowPaging, pageSize]);
     useEffect(() => {
         const normalized = Array.isArray(dataSource) ? dataSource : [];
-        if (gridRef.current && isPreviewMode) {
-            setCurrentData(normalized);
-            setTimeout(() => {
-                try {
-                    if (gridRef.current.dataSource !== normalized) {
-                        gridRef.current.dataSource = normalized;
-                    }
-                    setTimeout(() => {
-                        if (gridRef.current?.refresh) {
-                            gridRef.current.componentRefresh();
-                        }
-                    }, 10);
-                }
-                catch (e) {
-                }
-            }, 50);
-        }
+        setCurrentData(normalized);
     }, [dataSource]);
     /**
      * Expose getGridData() via ref - returns current grid data for form submission
@@ -155,6 +139,6 @@ export const DataGridComponent = React.forwardRef(({ id, columns, dataSource = [
                     allowAdding,
                     allowDeleting,
                     mode: 'Normal',
-                }, toolbar: toolbarConfig, actionComplete: handleActionComplete, height: typeof height === 'string' ? height : `${height}px`, width: typeof width === 'string' ? width : `${width}px`, allowSorting: true, allowFiltering: false, allowSelection: true, children: [_jsx(ColumnsDirective, { children: columns && columns.length > 0 && columns.map((col) => (_jsx(ColumnDirective, { field: col.field, headerText: col.headerText, type: col.type || 'string', isPrimaryKey: col.isPrimaryKey || false, width: col.width, format: col.type === 'date' ? (col.format || 'MM/dd/yyyy') : col.format, editType: col.editType, validationRules: mapValidationRules(col) }, col.field))) }), _jsx(Inject, { services: [Edit, Toolbar, Page, Resize, Sort] })] }) }) }));
+                }, locale: locale || 'en-US', cssClass: cssClass, toolbar: toolbarConfig, actionComplete: handleActionComplete, height: typeof height === 'string' ? height : `${height}px`, width: typeof width === 'string' ? width : `${width}px`, allowSorting: true, allowFiltering: false, allowSelection: true, children: [_jsx(ColumnsDirective, { children: columns && columns.length > 0 && columns.map((col) => (_jsx(ColumnDirective, { field: col.field, headerText: col.headerText, type: col.type || 'string', isPrimaryKey: col.isPrimaryKey || false, width: col.width, format: col.type === 'date' ? (col.format || 'MM/dd/yyyy') : col.format, editType: col.editType, validationRules: mapValidationRules(col) }, col.field))) }), _jsx(Inject, { services: [Edit, Toolbar, Page, Resize, Sort] })] }) }) }));
 });
 DataGridComponent.displayName = 'DataGridComponent';

package/src/FormRenderer.d.ts

@@ -45,17 +45,44 @@ export interface FormRendererProps extends Omit<React.HTMLAttributes<HTMLDivElem
      * - UISchema object (used directly)
      */
     uiSchema?: UISchema | string;
+    /**
+     * Specifies the locale/language for the form component.
+     * Supports locale-specific formatting and translations.
+     * @default 'en-US'
+     */
+    locale?: string;
+    /**
+     * Callback invoked when the form is submitted.
+     * Receives form data and validation status.
+     * @param args - Object containing form data and isValid flag
+     */
     onSubmit?: (args: SubmitEventArgs) => void;
+    /**
+     * Callback invoked when any form field value changes.
+     * Fired on user input for tracked fields.
+     * @param args - Object containing changed field name and new value
+     */
     onChange?: (args: ChangeEventArgs) => void;
+    /**
+     * Callback invoked when a button in the form is clicked.
+     * Applies to all button types (button, submit, splitButton).
+     * @param args - Object containing button click event details
+     */
     onButtonClick?: (args: ButtonClickEventArgs) => void;
+    /**
+     * CSS class names to apply to the root form container element.
+     * Supports space-separated multiple classes.
+     */
     className?: string;
     /**
-     * Form layout configuration (only applies when UI schema is NOT provided)
+     * Form layout configuration (only applies when UI schema is NOT provided).
+     * Determines how form fields are arranged in columns.
      * @default FormLayout.SingleColumn
      */
     layout?: FormLayout;
     /**
-     * Called when all form elements are rendered and ready
+     * Called when all form elements are rendered and ready for interaction.
+     * Useful for performing post-render initialization or setup.
      */
     created?: () => void;
 }