@explita/daily-toolset-components/dist/form.hook.type.d.ts

A lightweight and versatile collection of TypeScript utility functions and form components, inspired by ShadCN UI, designed for seamless everyday development. Enhance your Node.js, React, and Next.js projects with a well-structured suite of helpers for st

import { ZodTypeAny } from "zod";
export type DefaultSchema = Record<string, any>;
/**
 * The hook returned by useForm. This hook contains the form state and methods to
 * update the form state. The hook is generic and can be used with any schema type.
 *
 * @typedef {Object} UseFormHook
 * @property {boolean} isValidated - Indicates whether the form is validated.
 * @property {S} values - The current values of the form.
 * @property {Partial<Record<keyof S, string>>} errors - The current errors of the form fields.
 * @property {(newSchema: ZodTypeAny) => void} setSchema - Set the schema for the form.
 * @property {(name: string | undefined, value: any) => void} validateValue - Validates a specific form field
 * value using the provided schema. If validation fails, the error is parsed and set in the form errors.
 * @property {(name: string | undefined, value: any) => void} setValue - Updates the value of a specific form field.
 * If the form is in uncontrolled mode or the field name is not provided, the function exits without making changes.
 * @property {(
 *   values: Record<string, any>,
 *   options?: { overwrite?: boolean }
 * ) => void} setValues - Merges the provided values into the current form values. This function does not update values
 * in uncontrolled mode.
 * @property {(name: keyof S) => any} getValue - Retrieves the value of a single form field.
 * @property {(errors: Record<string, string | undefined>) => void} setErrors - Updates the form errors with the
 * provided errors. If the form is in uncontrolled mode or the field name is not provided, the function exits without
 * making changes.
 * @property {() => void} clearStorage - Clears the form values and errors, and if persistKey is provided, it will also
 * remove the persisted state from localStorage.
 */
export type UseFormHook<S> = {
    /**
     * Indicates whether the form is validated.
     */
    isValidated: boolean;
    /**
     * The current values of the form.
     */
    values: S;
    /**
     * The current errors of the form fields.
     */
    errors: Partial<Record<keyof S, string>>;
    /**
     * Set the schema for the form.
     * @param {ZodTypeAny} newSchema The new schema for the form.
     */
    setSchema: (newSchema: ZodTypeAny) => void;
    /**
     * Validates a specific form field value using the provided schema. If validation fails,
     * the error is parsed and set in the form errors. The function is debounced to prevent
     * excessive validation calls.
     *
     * @param name - The name of the form field to validate.
     * @param inputValue - The value of the form field to be validated.
     */
    validateValue: (name: string | undefined, value: any) => void;
    /**
     * Updates the value of a specific form field. If the form is in uncontrolled mode
     * or the field name is not provided, the function exits without making changes.
     *
     * @param name - The name of the form field to update.
     * @param value - The new value to set for the specified form field.
     */
    setValue: (name: string | undefined, value: any) => void;
    /**
     * Merges the provided values into the current form values. This function does not
     * update values in uncontrolled mode.
     *
     * @param values - An object containing key-value pairs to update the form with.
     */
    setValues: (values: Record<string, any>, options?: {
        overwrite?: boolean;
    }) => void;
    /**
     * Retrieves the value of a single form field.
     */
    getValue: (name: keyof S) => any;
    /**
     * Updates the form errors with the provided errors. If the form is in uncontrolled mode
     * or the field name is not provided, the function exits without making changes.
     *
     * @param errors - The errors to set for the form.
     */
    setErrors: (errors: Record<string, string | undefined>) => void;
    /**
     * Clears the form values and errors, and if persistKey is provided, it will
     * also remove the persisted state from localStorage.
     * @param empty If true, the form values will be set to an empty object. If
     * false, the form values will be set to the default values provided in the
     * useForm hook. Defaults to false.
     */
    reset: () => void;
    /**
     * A utility function to be used as a form's `onSubmit` handler.
     *
     * When called, it will validate the form using the current schema.
     * If the form is valid, it will call the `onValid` function with the validated form values.
     * If the form is invalid, it will set the `isValidated` state to `false` and update the `formErrors` state.
     *
     * If no schema is provided, it will simply call the `onValid` function with the current `formValues`.
     *
     * @param onValid - A function that will be called with the validated form values if the form is valid.
     * @returns A function that can be used as a form's `onSubmit` handler.
     */
    handleSubmit: (onValid: (data: S) => void) => (event: React.FormEvent<HTMLFormElement>) => void | Promise<void>;
};