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

package/src/FormValidator.d.ts

@@ -0,0 +1,479 @@
+import * as React from 'react';
+import { type FormHTMLAttributes } from 'react';
+export declare const VALIDATION_REGEX: {
+    [key: string]: RegExp;
+};
+/**
+ * Specifies the possible value types for form fields.
+ */
+export type FormValueType = string | number | boolean | Date | File | FileList | string[] | number[] | React.ReactNode | null | undefined;
+/**
+ * Defines the structure for a validation rule in the form system.
+ *
+ * A ValidationRule is a two-part array containing:
+ * - A validation condition (as boolean, RegExp, number, function, etc.)
+ * - An optional custom error message to show when validation fails
+ *
+ * The first element's type depends on the specific rule:
+ * - For boolean rules (like 'required'): true/false
+ * - For pattern rules (like 'email', 'regex'): RegExp object
+ * - For range rules: number or number[] (min/max values)
+ * - For equality checks: string (field name to compare with)
+ * - For custom validation: () => boolean function
+ *
+ * ```tsx
+ * const requiredRule: ValidationRule = [true, 'This field is required'];
+ * ```
+ */
+export type ValidationRule = [boolean | RegExp | number | number[] | string | Date | (() => boolean), string?];
+/**
+ * Defines the comprehensive set of validation rules that can be applied to form fields.
+ *
+ * This interface outlines all available validation types that can be configured for
+ * each field in the form. Each validation type accepts a ValidationRule containing
+ * both the validation criteria and an optional custom error message.
+ */
+export interface FieldValidationRules {
+    /**
+     * Validates that the field has a non-empty value. When configured with [true], the field cannot be empty, null, or undefined.
+     *
+     * ```tsx
+     * required: [true, 'This field must be filled in']
+     * ```
+     */
+    required?: ValidationRule;
+    /**
+     * Validates that the input conforms to a standard email address format. Checks for proper formatting with @ symbol and domain structure.
+     *
+     * ```tsx
+     * email: [true, 'Please enter a valid email address']
+     * ```
+     */
+    email?: ValidationRule;
+    /**
+     * Validates that the input is a properly formatted URL. Checks for proper protocol, domain structure, and path format.
+     *
+     * ```tsx
+     * url: [true, 'Please enter a valid website URL']
+     * ```
+     */
+    url?: ValidationRule;
+    /**
+     * Validates that the input can be parsed as a valid date. Uses Date.parse() to validate the string can be converted to a date.
+     *
+     * ```tsx
+     * date: [true, 'Please enter a valid date']
+     * ```
+     */
+    date?: ValidationRule;
+    /**
+     * Validates that the input follows ISO date format (YYYY-MM-DD). Ensures strict compliance with the ISO date standard.
+     *
+     * ```tsx
+     * dateIso: [true, 'Date must be in YYYY-MM-DD format']
+     * ```
+     */
+    dateIso?: ValidationRule;
+    /**
+     * Validates that the input contains a valid numeric value. Ensures the field can be converted to a number without errors.
+     *
+     * ```tsx
+     * number: [true, 'Please enter a number']
+     * ```
+     */
+    number?: ValidationRule;
+    /**
+     * Validates that the input contains only numeric digits (0-9). Rejects inputs containing decimal points, signs, letter characters or spaces.
+     *
+     * ```tsx
+     * digits: [true, 'Please enter only numeric digits']
+     * ```
+     */
+    digits?: ValidationRule;
+    /**
+     * Validates that the input is a valid credit card number. Checks length (13-16 digits) and applies Luhn algorithm validation.
+     *
+     * ```tsx
+     * creditCard: [true, 'Invalid credit card number']
+     * ```
+     */
+    creditCard?: ValidationRule;
+    /**
+     * Validates that a string has at least the specified minimum length. Takes a number as the first parameter in the validation rule.
+     *
+     * ```tsx
+     * minLength: [6, 'Must be at least 6 characters long']
+     * ```
+     */
+    minLength?: ValidationRule;
+    /**
+     * Validates that a string doesn't exceed the specified maximum length. Takes a number as the first parameter in the validation rule.
+     *
+     * ```tsx
+     * maxLength: [100, 'Cannot exceed 100 characters']
+     * ```
+     */
+    maxLength?: ValidationRule;
+    /**
+     * Validates that a string's length falls within the specified range. Takes an array of two numbers [min, max] as the first parameter.
+     *
+     * ```tsx
+     * rangeLength: [[8, 16], 'Must be between 8 and 16 characters']
+     * ```
+     */
+    rangeLength?: ValidationRule;
+    /**
+     * Validates that a numeric value is at least the specified minimum. Takes a number as the first parameter in the validation rule.
+     *
+     * ```tsx
+     * min: [18, 'Value must be at least 18']
+     * ```
+     */
+    min?: ValidationRule;
+    /**
+     * Validates that a numeric value doesn't exceed the specified maximum. Takes a number as the first parameter in the validation rule.
+     *
+     * ```tsx
+     * max: [100, 'Value cannot exceed 100']
+     * ```
+     */
+    max?: ValidationRule;
+    /**
+     * Validates that a numeric value falls within the specified range. Takes an array of two numbers [min, max] as the first parameter.
+     *
+     * ```tsx
+     * range: [[1, 10], 'Value must be between 1 and 10']
+     * ```
+     */
+    range?: ValidationRule;
+    /**
+     * Validates that the input matches the specified regular expression pattern. Takes a RegExp object or a string pattern as the first parameter.
+     *
+     * ```tsx
+     * regex: [/^[A-Z][a-z]+$/, 'Must start with capital letter followed by lowercase letters']
+     * ```
+     */
+    regex?: ValidationRule;
+    /**
+     * Validates that the input conforms to a standard telephone number format. Checks for proper formatting of phone numbers with optional country code.
+     *
+     * ```tsx
+     * tel: [true, 'Please enter a valid phone number']
+     * ```
+     */
+    tel?: ValidationRule;
+    /**
+     * Validates that the field's value exactly matches another field's value. Takes the name of another field as the first parameter.
+     *
+     * ```tsx
+     * equalTo: ['password', 'Passwords must match']
+     * ```
+     */
+    equalTo?: ValidationRule;
+    /**
+     * Allows for completely custom validation logic as a function.
+     *
+     * This function receives the field value and should return either:
+     * - A string containing an error message if validation fails
+     * - null if validation passes
+     *
+     * ```tsx
+     * customValidator: (value) => {
+     *   if (typeof value === 'string' && !value.includes('@company.com')) {
+     *     return 'Email must be a company email';
+     *   }
+     *   return null;
+     * }
+     * ```
+     */
+    customValidator?: (value: FormValueType) => string | null;
+}
+/**
+ * Defines the complete validation schema for a form by mapping field names to their validation rules.
+ *
+ * This interface creates a dictionary where each key is a field name and each value
+ * is an object containing all validation rules that apply to that field. The ValidationRules
+ * object is passed to the Form component to establish the validation criteria for the entire form.
+ *
+ * ```tsx
+ * const validationSchema: ValidationRules = {
+ *   username: {
+ *     required: [true, 'Username is required'],
+ *     minLength: [3, 'Username must be at least 3 characters']
+ *   },
+ *
+ *   email: {
+ *     required: [true, 'Email is required'],
+ *     email: [true, 'Please enter a valid email address']
+ *   }
+ * };
+ * ```
+ */
+export interface ValidationRules {
+    [fieldName: string]: FieldValidationRules;
+}
+/**
+ * Specifies the state and callback properties provided by the Form component.
+ *
+ * The FormState interface provides comprehensive access to the form's state
+ * and behavior through the onFormStateChange callback. It allows parent components
+ * to build custom form UIs with full access to validation state, field values, and form event handlers.
+ */
+export interface FormState {
+    /**
+     * Specifies the current values for all form fields indexed by field name.
+     * Access individual values using: values.fieldName
+     *
+     * ```tsx
+     * const username = formState.values.username;
+     * ```
+     */
+    values: Record<string, FormValueType>;
+    /**
+     * Specifies the current validation errors for all fields indexed by field name.
+     * Fields without errors won't appear in this object.
+     *
+     */
+    errors: Record<string, string>;
+    /**
+     * Specifies which fields in the form are valid (have no validation errors).
+     *
+     */
+    valid: Record<string, boolean>;
+    /**
+     * Specifies if the form can be submitted. True when all fields are valid;
+     * otherwise, all fields are marked as touched when attempted to submit.
+     */
+    allowSubmit: boolean;
+    /**
+     * Specifies if the form has been submitted at least once.
+     * True after a submission attempt regardless of validation result.
+     */
+    submitted: boolean;
+    /**
+     * Specifies which fields in the form have been modified from their initial values.
+     *
+     */
+    modified: Record<string, boolean>;
+    /**
+     * Specifies which fields have been touched (blurred after interaction).
+     * Useful for determining when to display validation messages.
+     *
+     */
+    touched: Record<string, boolean>;
+    /**
+     * Specifies which fields have been visited (received focus).
+     *
+     */
+    visited: Record<string, boolean>;
+    /**
+     * Specifies a dictionary of field names for easy access to form fields.
+     *
+     */
+    fieldNames: Record<string, string>;
+    /**
+     * Specifies the callback function to handle field value changes.
+     * Use this instead of directly modifying input elements.
+     *
+     * @param name - The name of the field to update
+     * @param options - Object containing the new value for the field.
+     * @event onChange
+     */
+    onChange(name: string, options: {
+        value: FormValueType;
+    }): void;
+    /**
+     * Specifies the callback function for when a field loses focus.
+     *
+     * @param fieldName - The name of the field that lost focus.
+     * @event onBlur
+     */
+    onBlur(fieldName: string): void;
+    /**
+     * Specifies the callback function for when a field receives focus.
+     * Records the field as visited.
+     *
+     * @param fieldName - The name of the field that received focus.
+     * @event onFocus
+     */
+    onFocus(fieldName: string): void;
+    /**
+     * Specifies the callback function to reset the form to its initial state.
+     * Clears all values, errors, and interaction states.
+     *
+     * @event onFormReset
+     */
+    onFormReset(): void;
+    /**
+     * Specifies the callback function to submit the form.
+     * Can be used with a submit button's onClick event.
+     *
+     * @param event - The synthetic event from the form submission.
+     * @event onSubmit
+     */
+    onSubmit(event: React.SyntheticEvent): void;
+}
+/**
+ * Specifies initial values for form fields. Maps field names to their default values when the form loads.
+ *
+ * ```tsx
+ * const initialValues: FormInitialValues = {
+ *   username: 'john_doe'
+ * };
+ * ```
+ */
+export interface FormInitialValues {
+    [fieldName: string]: FormValueType;
+}
+/**
+ * Specifies the props interface for the Form component.
+ */
+export interface FormProps {
+    /**
+     * Specifies the validation rules for each form field. This object defines constraints that form fields must satisfy.
+     */
+    rules: ValidationRules;
+    /**
+     * Specifies the callback fired when form is submitted and all validation rules pass.
+     *
+     * @param {Record<string, FormValueType>} data - Specifies the form data containing all field values
+     * @event onSubmit
+     */
+    onSubmit?: (data: Record<string, FormValueType>) => void;
+    /**
+     * Specifies the callback fired when form state changes.
+     * This can be used to access form state from parent components for custom UI rendering.
+     *
+     * @param {FormState} formState - The current state of the form
+     * @event onFormStateChange
+     */
+    onFormStateChange?: (formState: FormState) => void;
+    /**
+     * Specifies the initial values for form fields. These values populate the form.
+     *
+     * @default -
+     */
+    initialValues?: FormInitialValues;
+    /**
+     * Specifies whether to trigger validation on every input change. When true, validation occurs on each keystroke, providing immediate feedback.
+     *
+     * @default false
+     */
+    validateOnChange?: boolean;
+}
+/**
+ * Specifies the FormValidator interface for imperative methods.
+ */
+export interface IFormValidator extends FormProps {
+    /**
+     * Validates the entire form against all defined rules.
+     *
+     * @returns {boolean} - Returns true if the form is valid, false otherwise.
+     */
+    validate(): boolean;
+    /**
+     * Resets the form to its initial state, clearing all values, errors, and interaction states.
+     *
+     * @returns {void}
+     */
+    reset(): void;
+    /**
+     * Validates a specific field against its defined rules.
+     *
+     * @param {string} fieldName - Specifies the name of the field to validate
+     * @returns {boolean} - Returns true if the field is valid, false otherwise
+     */
+    validateField(fieldName: string): boolean;
+    /**
+     * Provides access to the underlying HTML form element.
+     *
+     * @private
+     */
+    element?: HTMLFormElement;
+}
+type FormComponentProps = FormProps & Omit<FormHTMLAttributes<HTMLFormElement>, 'onSubmit'>;
+/**
+ * Provides a form component with built-in validation functionality. Manages form state tracking,
+ * field validation, and submission handling.
+ *
+ * ```typescript
+ * import { Form, FormField, FormState } from '@syncfusion/react-inputs';
+ *
+ * const [formState, setFormState] = useState<FormState>();
+ *
+ * <Form
+ *   rules={{ username: { required: [true, 'Username is required'] } }}
+ *   onSubmit={data => console.log(data)}
+ *   onFormStateChange={setFormState} >
+ *   <FormField name="username">
+ *     <input
+ *       name="username"
+ *       value={(formState?.values.username || '') as string}
+ *       onChange={(e) => formState?.onChange('username', { value: e.target.value })}
+ *       onBlur={() => formState?.onBlur('username')}
+ *       onFocus={() => formState?.onFocus('username')}
+ *     />
+ *     {formState?.errors?.username && (<div className="error">{formState.errors.username}</div>)}
+ *   </FormField>
+ *   <button type="submit">Submit</button>
+ * </Form>
+ * ```
+ */
+export declare const Form: React.ForwardRefExoticComponent<FormComponentProps & React.RefAttributes<IFormValidator>>;
+/**
+ * Specifies the properties for the FormField component.
+ */
+export interface FormFieldProps {
+    /**
+     * Specifies the name of the field that must match a key in the rules object. This is required for proper validation.
+     */
+    name: string;
+    /**
+     * Specifies the children content for the form field. Children should include the actual form control elements like inputs, textarea, etc.
+     */
+    children: React.ReactNode;
+    /**
+     * Specifies field-level validation rules that apply only to this specific field. These rules override any form-level rules
+     * with the same name defined in the Form component's rules. This allows for field-specific validation that takes
+     * precedence over form-wide defaults.
+     *
+     * @default undefined
+     */
+    rules?: FieldValidationRules;
+}
+/**
+ * Specifies a component that connects form inputs with validation rules. The FormField component provides
+ * an easy way to integrate form controls with the Form validation system, handling state management and
+ * validation automatically.
+ *
+ * ```typescript
+ * const [formState, setFormState] = useState<FormState>();
+ *
+ * <Form
+ *   rules={{
+ *     username: { required: [true, 'Username is required'] }
+ *   }}
+ *   onSubmit={data => console.log(data)}
+ *   onFormStateChange={setFormState}
+ * >
+ *   <FormField name="username">
+ *     <input
+ *       name="username"
+ *       value={formState?.values.username || ''}
+ *       onChange={(e) => formState?.onChange('username', { value: e.target.value })}
+ *       onBlur={() => formState?.onBlur('username')}
+ *       onFocus={() => formState?.onFocus('username')}
+ *     />
+ *     {formState?.touched?.username && formState?.errors?.username && (
+ *       <div className="error">{formState.errors.username}</div>
+ *     )}
+ *   </FormField>
+ *   <button type="submit">Submit</button>
+ * </Form>
+ * ```
+ *
+ * @param {IFormFieldProps} props - Specifies the form field configuration properties
+ * @returns {React.ReactNode} - Returns the children with access to form validation context
+ */
+export declare const FormField: React.FC<FormFieldProps>;
+export {};