reactjs-use-form/dist/index.d.ts

Reactive form management and input field validation hook

import { ChangeEvent, FormEvent } from 'react';
/**
 * A comprehensive React hook for form management with validation, submission handling, and state tracking.
 *
 * This hook provides a complete form management solution that includes:
 * - Real-time field validation with custom validators
 * - Form submission handling with loading states
 * - Dirty/touched state tracking for better UX
 * - Form and field reset utilities
 * - TypeScript support with generic types
 * - Optimized performance with memoization and shallow comparisons
 *
 * @template T - The shape of the form values object
 * @param {FormModelType<T>} formModel - Configuration object defining form fields, initial values, validation rules, and required fields
 * @param {function} formSubmitCallback - Async callback function executed on successful form submission
 * @returns {useFormType<T>} Object containing form state, handlers, and utility functions
 *
 * @example
 * ```typescript
 * const formModel = {
 *   email: { value: '', required: true, validator: (value) => !value.includes('@') ? 'Invalid email' : '' },
 *   password: { value: '', required: true }
 * };
 *
 * const form = useForm(formModel, async (values) => {
 *   await api.submitForm(values);
 * });
 *
 * // Usage in component
 * <form onSubmit={form.handleOnSubmit}>
 *   <input name="email" value={form.values.email} onChange={form.handleOnChange} />
 *   {form.errors.email.hasError && <span>{form.errors.email.message}</span>}
 * </form>
 * ```
 */
export declare function useForm<T extends Record<string, any> = Record<string, any>>(formModel: FormModelType<T>, formSubmitCallback: (values: T) => void | Promise<void>): useFormType<T>;
/** Type for form field values (currently only supports strings) */
export type ValueType = string;
/**
 * Type for form values object (generic version).
 * @template T - The shape of the form values object
 */
export type ValuesType<T extends Record<string, any> = Record<string, any>> = T;
/**
 * Type defining the structure of field error objects.
 */
export type ErrorType = {
    /** Whether the field has an error */
    hasError: boolean;
    /** Error message to display */
    message: string;
};
/**
 * Type defining the structure of the errors object for all form fields.
 * @template T - The shape of the form values object
 */
export type ErrorsType<T extends Record<string, any> = Record<string, any>> = {
    [K in keyof T]: ErrorType;
};
/**
 * Type for validator functions that validate field values.
 * @template T - The shape of the form values object
 */
type ValidatorFuncType<T extends Record<string, any> = Record<string, any>> = (value: ValueType, values?: T) => string;
/**
 * Type defining the configuration for a single form input field.
 * @template T - The shape of the form values object
 */
export type FormInputType<T extends Record<string, any> = Record<string, any>> = {
    /** Initial value for the field */
    value: ValueType;
    /** Whether the field is required */
    required: boolean;
    /** Optional validator function */
    validator?: ValidatorFuncType<T>;
};
/**
 * Type defining the structure of a form model configuration.
 * @template T - The shape of the form values object
 */
export type FormModelType<T extends Record<string, any> = Record<string, any>> = {
    [K in keyof T]: FormInputType<T>;
};
/** Type for the onChange event handler */
type HandleOnChangeType = (event: ChangeEvent<HTMLInputElement>) => void;
/** Type for the onSubmit event handler */
type HandleOnSubmitType = (event: FormEvent<HTMLFormElement>) => void;
/**
 * Return type of the useForm hook containing all form state and handlers.
 * @template T - The shape of the form values object
 */
export type useFormType<T extends Record<string, any> = Record<string, any>> = {
    /** Handler for input field changes */
    handleOnChange: HandleOnChangeType;
    /** Handler for form submission */
    handleOnSubmit: HandleOnSubmitType;
    /** Current form values */
    values: T;
    /** Current form errors */
    errors: ErrorsType<T>;
    /** Whether form has been successfully submitted */
    isSubmitted: boolean;
    /** Whether form is currently being submitted */
    isSubmitting: boolean;
    /** Whether form submit button should be disabled */
    isDisabled: boolean;
    /** Whether any form field has been modified */
    isDirty: boolean;
    /** Function to reset entire form */
    resetForm: () => void;
    /** Function to reset specific field */
    resetField: (fieldName: keyof T) => void;
};
export {};
//# sourceMappingURL=index.d.ts.map