@asgardeo/react/dist/hooks/useForm.d.ts

React implementation of Asgardeo JavaScript SDK.

/**
 * Copyright (c) 2025, WSO2 LLC. (https://www.wso2.com).
 *
 * WSO2 LLC. licenses this file to you under the Apache License,
 * Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied. See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
/**
 * Generic form field configuration
 */
export interface FormField {
    initialValue?: string;
    name: string;
    required?: boolean;
    validator?: (value: string) => string | null;
}
/**
 * Form validation result
 */
export interface ValidationResult {
    errors: Record<string, string>;
    isValid: boolean;
}
/**
 * Configuration for the useForm hook
 */
export interface UseFormConfig<T extends Record<string, string>> {
    /**
     * Form field definitions
     */
    fields?: FormField[];
    /**
     * Initial form values
     */
    initialValues?: Partial<T>;
    /**
     * Custom required field validation message
     */
    requiredMessage?: string;
    /**
     * Whether to validate on blur (default: true)
     */
    validateOnBlur?: boolean;
    /**
     * Whether to validate on change (default: false)
     */
    validateOnChange?: boolean;
    /**
     * Global form validator function
     */
    validator?: (values: T) => Record<string, string>;
}
/**
 * Return type for the useForm hook
 */
export interface UseFormReturn<T extends Record<string, string>> {
    /**
     * Clear all errors
     */
    clearErrors: () => void;
    /**
     * Current validation errors
     */
    errors: Record<keyof T, string>;
    /**
     * Get field props for easy integration with form components
     */
    getFieldProps: (name: keyof T) => {
        error: string | undefined;
        name: keyof T;
        onBlur: () => void;
        onChange: (value: string) => void;
        required: boolean;
        touched: boolean;
        value: string;
    };
    /**
     * Handle form submission
     */
    handleSubmit: (onSubmit: (values: T) => void | Promise<void>) => (e?: React.FormEvent) => Promise<void>;
    /**
     * Whether the form has been submitted
     */
    isSubmitted: boolean;
    /**
     * Whether the form is currently valid
     */
    isValid: boolean;
    /**
     * Reset the form to initial values
     */
    reset: () => void;
    /**
     * Set a field error
     */
    setError: (name: keyof T, error: string) => void;
    /**
     * Set multiple field errors
     */
    setErrors: (errors: Partial<Record<keyof T, string>>) => void;
    /**
     * Mark a field as touched
     */
    setTouched: (name: keyof T, touched?: boolean) => void;
    /**
     * Mark multiple fields as touched
     */
    setTouchedFields: (touched: Partial<Record<keyof T, boolean>>) => void;
    /**
     * Set a single field value
     */
    setValue: (name: keyof T, value: string) => void;
    /**
     * Set multiple field values
     */
    setValues: (values: Partial<T>) => void;
    /**
     * Mark all fields as touched
     */
    touchAllFields: () => void;
    /**
     * Validate all fields
     */
    validateForm: () => ValidationResult;
    /**
     * Current form values
     */
    values: T;
    /**
     * Validate a single field
     */
    validateField: (name: keyof T) => string | null;
    /**
     * Fields that have been touched by the user
     */
    touched: Record<keyof T, boolean>;
}
/**
 * Generic form hook that provides comprehensive form state management and validation.
 *
 * @template T - The type of form values (must extend Record<string, string>)
 * @param config - Configuration options for the form
 * @returns Form state and methods
 *
 * @example
 * ```tsx
 * interface LoginForm {
 *   username: string;
 *   password: string;
 * }
 *
 * const {
 *   values,
 *   touched,
 *   errors,
 *   isValid,
 *   setValue,
 *   handleSubmit,
 *   getFieldProps
 * } = useForm<LoginForm>({
 *   initialValues: { username: '', password: '' },
 *   fields: [
 *     { name: 'username', required: true },
 *     { name: 'password', required: true }
 *   ]
 * });
 *
 * const onSubmit = handleSubmit((values) => {
 *   console.log('Form submitted:', values);
 * });
 *
 * return (
 *   <form onSubmit={onSubmit}>
 *     <input {...getFieldProps('username')} />
 *     <input {...getFieldProps('password')} type="password" />
 *     <button type="submit" disabled={!isValid}>Submit</button>
 *   </form>
 * );
 * ```
 */
export declare const useForm: <T extends Record<string, string>>(config?: UseFormConfig<T>) => UseFormReturn<T>;
export default useForm;