@syncfusion/ej2-react-form-builder 0.1.0-beta

package/Common/MinMaxRuleEngine.js

@@ -0,0 +1,365 @@
+/**
+ * Extract min/max constraints from minMaxRange array
+ * @private
+ */
+export class MinMaxRuleEngine {
+    /**
+     * Extract min/max constraints from minMaxRange array
+     * Handles three cases:
+     * 1. Direct values (enabled: false)
+     * 2. Single field reference (enabled: true, 1 range)
+     * 3. Multiple ranges (enabled: true, 2+ ranges) - takes UTMOST
+     * @private
+     * @param minMaxRange - Array of range configurations
+     * @param formValues - Current form state values (id → value)
+     * @param componentType - 'number' | 'date' | 'dateRange'
+     * @returns Constraints object with appropriate keys
+     */
+    static getConstraints(minMaxRange, formValues, componentType = 'number') {
+        // No ranges provided
+        if (!minMaxRange || minMaxRange.length === 0) {
+            return this.getEmptyConstraints(componentType);
+        }
+        // First, check for CASE 1: Direct values (enabled: false)
+        const directValueRange = minMaxRange.find(range => range.enabled === false);
+        if (directValueRange) {
+            // Use direct values without field lookup
+            const minValue = this.resolveValue(directValueRange.minValue, {});
+            const maxValue = this.resolveValue(directValueRange.maxValue, {});
+            if (componentType === 'date' || componentType === 'dateRange') {
+                return {
+                    minValue: undefined,
+                    maxValue: undefined,
+                    minDate: minValue,
+                    maxDate: maxValue,
+                    minTime: undefined,
+                    maxTime: undefined
+                };
+            }
+            if (componentType === 'time') {
+                return {
+                    minValue: undefined,
+                    maxValue: undefined,
+                    minDate: undefined,
+                    maxDate: undefined,
+                    minTime: minValue,
+                    maxTime: maxValue
+                };
+            }
+            return {
+                minValue,
+                maxValue,
+                minDate: undefined,
+                maxDate: undefined,
+                minTime: undefined,
+                maxTime: undefined
+            };
+        }
+        // CASE 2 & 3: Field references (enabled: true)
+        const enabledRanges = minMaxRange.filter(range => range.enabled === true);
+        // No enabled ranges - return empty
+        if (enabledRanges.length === 0) {
+            return this.getEmptyConstraints(componentType);
+        }
+        // Extract resolved values from each enabled range
+        const resolvedRanges = enabledRanges
+            .map(range => ({
+            min: this.resolveValue(range.minValue, formValues),
+            max: this.resolveValue(range.maxValue, formValues)
+        }))
+            .filter(range => range.min !== undefined || range.max !== undefined);
+        // No valid ranges
+        if (resolvedRanges.length === 0) {
+            return this.getEmptyConstraints(componentType);
+        }
+        // Combine multiple ranges using UTMOST (most permissive)
+        const finalMin = this.getPermissiveMin(resolvedRanges, componentType);
+        const finalMax = this.getPermissiveMax(resolvedRanges, componentType);
+        // Return appropriate keys based on component type
+        if (componentType === 'date' || componentType === 'dateRange') {
+            return {
+                minValue: undefined,
+                maxValue: undefined,
+                minDate: finalMin,
+                maxDate: finalMax,
+                minTime: undefined,
+                maxTime: undefined
+            };
+        }
+        if (componentType === 'time') {
+            return {
+                minValue: undefined,
+                maxValue: undefined,
+                minDate: undefined,
+                maxDate: undefined,
+                minTime: finalMin,
+                maxTime: finalMax
+            };
+        }
+        return {
+            minValue: finalMin,
+            maxValue: finalMax,
+            minDate: undefined,
+            maxDate: undefined,
+            minTime: undefined,
+            maxTime: undefined
+        };
+    }
+    /**
+     * Resolve a single value - either direct or field reference
+     *
+     * @param value - Direct value or field reference object
+     * @param formValues - Form state values for field lookup
+     * @returns Resolved value or undefined
+     */
+    static resolveValue(value, formValues) {
+        // Direct value (number or string)
+        if (typeof value === 'number') {
+            return value;
+        }
+        if (typeof value === 'string') {
+            return value;
+        }
+        // Field reference object
+        if (value && typeof value === 'object' && value.field) {
+            const fieldId = value.field;
+            const fieldValue = formValues[fieldId];
+            return fieldValue !== undefined ? fieldValue : undefined;
+        }
+        return undefined;
+    }
+    /**
+     * Get the most permissive (widest) minimum value
+     * For numbers: MIN of all mins
+     * For dates: earliest date (MIN string comparison on ISO format)
+     * For times: earliest time (MIN string comparison on 24-hour format)
+     *
+     * @param ranges - Array of {min, max} values
+     * @param componentType - Type of component
+     * @returns Most permissive minimum value
+     */
+    static getPermissiveMin(ranges, componentType) {
+        if (ranges.length === 0)
+            return undefined;
+        if (componentType === 'date' || componentType === 'dateRange') {
+            // For dates, find earliest (minimum) date
+            return ranges.reduce((earliest, current) => {
+                if (!current.min)
+                    return earliest;
+                if (!earliest)
+                    return current.min;
+                const earliestIso = this.convertToISO(earliest);
+                const currentIso = this.convertToISO(current.min);
+                return currentIso < earliestIso ? current.min : earliest;
+            }, undefined);
+        }
+        if (componentType === 'time') {
+            // For times, find earliest (minimum) time
+            return ranges.reduce((earliest, current) => {
+                if (!current.min)
+                    return earliest;
+                if (!earliest)
+                    return current.min;
+                const earliest24 = this.convertTimeTo24Hour(earliest);
+                const current24 = this.convertTimeTo24Hour(current.min);
+                return current24 < earliest24 ? current.min : earliest;
+            }, undefined);
+        }
+        // For numbers, find minimum (skip undefined values)
+        const minValues = ranges.map(r => r.min).filter(v => v !== undefined);
+        return minValues.length > 0 ? Math.min(...minValues) : undefined;
+    }
+    /**
+     * Get the most permissive (widest) maximum value
+     * For numbers: MAX of all maxs
+     * For dates: latest date (MAX string comparison on ISO format)
+     * For times: latest time (MAX string comparison on 24-hour format)
+     *
+     * @param ranges - Array of {min, max} values
+     * @param componentType - Type of component
+     * @returns Most permissive maximum value
+     */
+    static getPermissiveMax(ranges, componentType) {
+        if (ranges.length === 0)
+            return undefined;
+        if (componentType === 'date' || componentType === 'dateRange') {
+            // For dates, find latest (maximum) date
+            return ranges.reduce((latest, current) => {
+                if (!current.max)
+                    return latest;
+                if (!latest)
+                    return current.max;
+                const latestIso = this.convertToISO(latest);
+                const currentIso = this.convertToISO(current.max);
+                return currentIso > latestIso ? current.max : latest;
+            }, undefined);
+        }
+        if (componentType === 'time') {
+            // For times, find latest (maximum) time
+            return ranges.reduce((latest, current) => {
+                if (!current.max)
+                    return latest;
+                if (!latest)
+                    return current.max;
+                const latest24 = this.convertTimeTo24Hour(latest);
+                const current24 = this.convertTimeTo24Hour(current.max);
+                return current24 > latest24 ? current.max : latest;
+            }, undefined);
+        }
+        // For numbers, find maximum (skip undefined values)
+        const maxValues = ranges.map(r => r.max).filter(v => v !== undefined);
+        return maxValues.length > 0 ? Math.max(...maxValues) : undefined;
+    }
+    /**
+     * Convert MM/DD/YYYY date format to ISO (YYYY-MM-DD) for comparison
+     * Handles both formats gracefully
+     *
+     * @param dateString - Date in MM/DD/YYYY or ISO format
+     * @returns ISO date string (YYYY-MM-DD)
+     */
+    static convertToISO(dateString) {
+        if (!dateString)
+            return '';
+        // Already ISO format (YYYY-MM-DD)
+        if (dateString.includes('-') && dateString.length === 10) {
+            return dateString;
+        }
+        // MM/DD/YYYY format
+        if (dateString.includes('/')) {
+            const [month, day, year] = dateString.split('/');
+            if (!month || !day || !year)
+                return dateString;
+            return `${year}-${month.padStart(2, '0')}-${day.padStart(2, '0')}`;
+        }
+        return dateString;
+    }
+    /**
+     * Convert 12-hour time format to 24-hour format for comparison
+     * Handles both 12-hour (hh:mm a) and 24-hour (HH:mm) formats
+     *
+     * @param timeString - Time in 12-hour (hh:mm a/p) or 24-hour (HH:mm) format
+     * @returns 24-hour format time string (HH:mm)
+     */
+    static convertTimeTo24Hour(timeString) {
+        if (!timeString)
+            return '';
+        // Check if it contains AM/PM (12-hour format)
+        const isPM = /PM/i.test(timeString);
+        const isAM = /AM/i.test(timeString);
+        if (isAM || isPM) {
+            // Extract time part (before AM/PM)
+            const timePart = timeString.replace(/\s*(AM|PM)/i, '').trim();
+            const [hours, minutes] = timePart.split(':');
+            if (!hours || !minutes)
+                return timeString;
+            let hour = parseInt(hours, 10);
+            if (isPM && hour !== 12) {
+                hour += 12; // Convert PM hours (except 12) to 24-hour
+            }
+            else if (isAM && hour === 12) {
+                hour = 0; // Convert 12 AM to 00:00
+            }
+            return `${String(hour).padStart(2, '0')}:${minutes}`;
+        }
+        // Already in 24-hour format or unknown format
+        return timeString;
+    }
+    /**
+     * Get empty constraints object based on component type
+     */
+    static getEmptyConstraints(componentType) {
+        if (componentType === 'date' || componentType === 'dateRange') {
+            return {
+                minValue: undefined,
+                maxValue: undefined,
+                minDate: undefined,
+                maxDate: undefined,
+                minTime: undefined,
+                maxTime: undefined
+            };
+        }
+        if (componentType === 'time') {
+            return {
+                minValue: undefined,
+                maxValue: undefined,
+                minDate: undefined,
+                maxDate: undefined,
+                minTime: undefined,
+                maxTime: undefined
+            };
+        }
+        return {
+            minValue: undefined,
+            maxValue: undefined,
+            minDate: undefined,
+            maxDate: undefined,
+            minTime: undefined,
+            maxTime: undefined
+        };
+    }
+    /**
+     * Validate if a value passes all min/max constraints (optional)
+     * Can be used for client-side validation before submission
+     *
+     * @param value - Value to validate
+     * @param constraints - Constraints to check against
+     * @param componentType - Type of component
+     * @returns Validation result with error message if invalid
+     */
+    static validateValue(value, constraints, componentType) {
+        if (value === undefined || value === null || value === '') {
+            return { isValid: true }; // Empty values pass (required handled separately)
+        }
+        if (componentType === 'date' || componentType === 'dateRange') {
+            if (constraints.minDate) {
+                const minIso = this.convertToISO(constraints.minDate);
+                const valueIso = this.convertToISO(value);
+                if (valueIso < minIso) {
+                    return { isValid: false, error: `Date must be on or after ${constraints.minDate}` };
+                }
+            }
+            if (constraints.maxDate) {
+                const maxIso = this.convertToISO(constraints.maxDate);
+                const valueIso = this.convertToISO(value);
+                if (valueIso > maxIso) {
+                    return { isValid: false, error: `Date must be on or before ${constraints.maxDate}` };
+                }
+            }
+        }
+        else if (componentType === 'time') {
+            if (constraints.minTime) {
+                if (value < constraints.minTime) {
+                    return { isValid: false, error: `Time must be on or after ${constraints.minTime}` };
+                }
+            }
+            if (constraints.maxTime) {
+                if (value > constraints.maxTime) {
+                    return { isValid: false, error: `Time must be on or before ${constraints.maxTime}` };
+                }
+            }
+        }
+        else {
+            // Number type
+            const numValue = Number(value);
+            if (constraints.minValue !== undefined) {
+                const minNum = Number(constraints.minValue);
+                if (numValue < minNum) {
+                    return {
+                        isValid: false,
+                        error: `Value must be at least ${constraints.minValue}`
+                    };
+                }
+            }
+            if (constraints.maxValue !== undefined) {
+                const maxNum = Number(constraints.maxValue);
+                if (numValue > maxNum) {
+                    return {
+                        isValid: false,
+                        error: `Value must be at most ${constraints.maxValue}`
+                    };
+                }
+            }
+        }
+        return { isValid: true };
+    }
+}

package/Common/StaticHtmlRenderer.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+/**
+ * @private
+ */
+export interface StaticHtmlRendererProps {
+    content: string;
+    id?: string;
+    enableHtmlSanitizer?: boolean;
+}
+/**
+ * @private
+ */
+export declare const StaticHtmlRenderer: React.FC<StaticHtmlRendererProps>;
+export default StaticHtmlRenderer;

package/Common/StaticHtmlRenderer.js

@@ -0,0 +1,24 @@
+import React from 'react';
+import { SanitizeHtmlHelper } from '@syncfusion/ej2-base';
+/**
+ * @private
+ */
+export const StaticHtmlRenderer = ({ content, id, enableHtmlSanitizer }) => {
+    const sanitizedHtml = React.useMemo(() => {
+        try {
+            if (enableHtmlSanitizer) {
+                return SanitizeHtmlHelper.sanitize(content);
+            }
+            return content;
+        }
+        catch (error) {
+            console.error('HTML sanitization error:', error);
+            return '';
+        }
+    }, [content]);
+    return React.createElement('div', {
+        id,
+        dangerouslySetInnerHTML: { __html: sanitizedHtml }
+    });
+};
+export default StaticHtmlRenderer;

package/Common/expressions/DependencyTracker.d.ts

@@ -0,0 +1,30 @@
+/**
+ * DependencyTracker - Extract and track field dependencies
+ *
+ * Analyzes expressions to find field references and build dependency graphs
+ * Detects circular dependencies and calculates evaluation order
+ * @private
+ * @spec Expression_Engine.md
+ */
+export declare class DependencyTracker {
+    private escapedBracePattern;
+    /**
+     * Extract field names referenced in expression
+     */
+    extractFieldReferences(expression: string): string[];
+    /**
+     * Build dependency graph from multiple expressions
+     */
+    buildGraph(expressions: Record<string, string>): Record<string, string[]>;
+    /**
+     * Detect circular dependencies using DFS
+     */
+    detectCircularDependencies(graph: Record<string, string[]>): string[][];
+    /**
+     * Get topological sort order for evaluation
+     */
+    getTopologicalOrder(graph: Record<string, string[]>): string[];
+    private isFunctionCall;
+    private isOperator;
+    private isKeyword;
+}

package/Common/expressions/DependencyTracker.js

@@ -0,0 +1,128 @@
+/**
+ * DependencyTracker - Extract and track field dependencies
+ *
+ * Analyzes expressions to find field references and build dependency graphs
+ * Detects circular dependencies and calculates evaluation order
+ * @private
+ * @spec Expression_Engine.md
+ */
+export class DependencyTracker {
+    escapedBracePattern = /\\{.*?\\}/g;
+    /**
+     * Extract field names referenced in expression
+     */
+    extractFieldReferences(expression) {
+        if (!expression)
+            return [];
+        const refs = new Set();
+        let match;
+        // Remove escaped braces first
+        const cleanExpression = expression.replace(this.escapedBracePattern, '');
+        // Extract field references from {field} syntax
+        const fieldRefPattern = /\{([^{}]+)\}/g;
+        while ((match = fieldRefPattern.exec(cleanExpression)) !== null) {
+            const ref = match[1].trim();
+            // Skip if it's a function call or operator
+            if (!this.isFunctionCall(ref) && !this.isOperator(ref)) {
+                // Extract field name from nested paths
+                const fieldName = ref.split(/[.\[\]]/)[0].trim();
+                if (fieldName && !this.isKeyword(fieldName)) {
+                    refs.add(fieldName);
+                }
+            }
+        }
+        // Extract identifiers from ${...} math expressions
+        const mathExprPattern = /\$\{([^}]+)\}/g;
+        while ((match = mathExprPattern.exec(cleanExpression)) !== null) {
+            const mathExpr = match[1];
+            // Extract all identifiers from the math expression
+            // Match word boundaries followed by identifier characters
+            // But skip if followed by ( or . (those are function calls or property access)
+            const identPattern = /\b([a-zA-Z_][a-zA-Z0-9_]*)\b(?!\s*[(\.])/g;
+            let idMatch;
+            while ((idMatch = identPattern.exec(mathExpr)) !== null) {
+                const identifier = idMatch[1];
+                // Skip keywords and constants
+                if (!this.isKeyword(identifier) && identifier !== 'Math') {
+                    refs.add(identifier);
+                }
+            }
+        }
+        return Array.from(refs);
+    }
+    /**
+     * Build dependency graph from multiple expressions
+     */
+    buildGraph(expressions) {
+        const graph = {};
+        for (const [fieldName, expression] of Object.entries(expressions)) {
+            const deps = this.extractFieldReferences(expression);
+            graph[fieldName] = deps;
+        }
+        return graph;
+    }
+    /**
+     * Detect circular dependencies using DFS
+     */
+    detectCircularDependencies(graph) {
+        const visited = new Set();
+        const recursionStack = new Set();
+        const cycles = [];
+        const visit = (node, path) => {
+            visited.add(node);
+            recursionStack.add(node);
+            path.push(node);
+            const deps = graph[node] || [];
+            for (const dep of deps) {
+                if (!visited.has(dep)) {
+                    visit(dep, [...path]);
+                }
+                else if (recursionStack.has(dep)) {
+                    const cycleStart = path.indexOf(dep);
+                    cycles.push([...path.slice(cycleStart), dep]);
+                }
+            }
+            recursionStack.delete(node);
+        };
+        for (const node of Object.keys(graph)) {
+            if (!visited.has(node)) {
+                visit(node, []);
+            }
+        }
+        return cycles;
+    }
+    /**
+     * Get topological sort order for evaluation
+     */
+    getTopologicalOrder(graph) {
+        const visited = new Set();
+        const order = [];
+        const visit = (node) => {
+            if (visited.has(node))
+                return;
+            visited.add(node);
+            const deps = graph[node] || [];
+            for (const dep of deps) {
+                if (graph[dep]) {
+                    visit(dep);
+                }
+            }
+            order.push(node);
+        };
+        for (const node of Object.keys(graph)) {
+            visit(node);
+        }
+        return order;
+    }
+    // Private helpers
+    isFunctionCall(ref) {
+        return /^\w+\s*\(/.test(ref);
+    }
+    isOperator(ref) {
+        return /^[+\-*/()=!<>&|]/.test(ref);
+    }
+    isKeyword(name) {
+        const keywords = ['PI', 'TRUE', 'FALSE', 'NULL', 'UNDEFINED', 'and', 'or', 'in'];
+        return keywords.includes(name.toUpperCase());
+    }
+}

package/Common/expressions/ExpressionEngine.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @private
+ */
+export type FormValueType = string | number | boolean | Date | null | undefined | any[];
+/**
+ * @private
+ */
+export interface EvaluationOptions {
+    timeout?: number;
+    maxDepth?: number;
+    locale?: string;
+    currencyCode?: string;
+    throwOnError?: boolean;
+}
+/**
+ * @private
+ */
+export type DependencyGraph = Record<string, string[]>;
+/**
+ * ExpressionEngine - Core evaluation engine
+ *
+ * Safely evaluates user-defined expressions against form state
+ * Supports field references, math operations, functions, and conditionals
+ * @private
+ */
+export declare class ExpressionEngine {
+    private parser;
+    private dependencyTracker;
+    private evaluationCache;
+    private compiledFunctions;
+    constructor();
+    /**
+     * Evaluate expression against form values
+     */
+    evaluate(expression: string, formValues: Record<string, FormValueType>, options?: EvaluationOptions, isCustomValidation?: boolean): any;
+    /**
+     * Extract field names referenced in expression
+     */
+    extractDependencies(expression: string): string[];
+    /**
+     * Build dependency graph for all expressions
+     */
+    buildDependencyGraph(components: any[]): DependencyGraph;
+    /**
+     * Detect circular dependencies
+     */
+    detectCircularDependencies(graph: DependencyGraph): string[][];
+    /**
+     * Get topological order for evaluation
+     */
+    getTopologicalOrder(graph: DependencyGraph): string[];
+    /**
+     * Clear internal caches
+     */
+    clearCache(): void;
+    private getCacheKey;
+    private buildContext;
+}
+/**
+ * ExpressionValidator - Validates expressions before runtime
+ *
+ * Checks syntax, validates field references, and detects circular dependencies
+ * @private
+ * @spec Expression_Engine.md
+ */
+export declare class ExpressionValidator {
+    private supportedFunctions;
+    private keywords;
+    /**
+     * Validate expression against available fields
+     */
+    validate(expression: string, availableFields: string[] | any[]): ValidationError[];
+    /**
+     * Validate field operations - check for invalid operators on string/date types
+     */
+    private validateFieldOperations;
+    private validateSyntax;
+    /**
+     * @private
+     */
+    validateFieldReferences(expression: string, availableFields: string[] | any[]): ValidationError[];
+    private validateFunctionCalls;
+    private isFunctionCall;
+    private isMathExpression;
+}
+/**
+ * @private
+ */
+export interface ValidationError {
+    type: 'SyntaxError' | 'UndefinedField' | 'InvalidFunction' | 'CircularDependency' | 'InvalidOperation';
+    message: string;
+    field?: string;
+    line?: number;
+    column?: number;
+}