@explita/daily-toolset-form/dist/types.d.ts

A lightweight form toolkit for React built with developer ergonomics in mind. Includes a flexible Form component, useForm, useField, and useFormContext hooks for managing form state and validation with ease. Designed to simplify complex forms while remain

import { ZodObject } from "zod";
export type InputValue = string | undefined;
export type InputEvent = React.FormEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | HTMLButtonElement>;
export type InputChangeEvent = React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | HTMLButtonElement> | React.FormEvent<HTMLButtonElement>;
export type RegisteredField<T> = {
    name?: keyof T;
    id?: string;
    value?: InputValue;
    defaultValue?: T[keyof T];
    defaultChecked?: boolean;
    onCheckedChange?: (val: boolean) => void;
    onValueChange?: (val: string) => void;
    onChange?: (e: InputChangeEvent) => void;
    onInput?: (e: InputEvent) => void;
    onBlur?: () => void;
    "data-input-error"?: boolean;
};
type InputMeta = {
    value: InputValue;
    error?: string;
    hasError: boolean;
};
export type FieldProps<T extends Record<string, any>> = {
    name?: string;
    label?: string;
    as?: "checkbox" | "input" | "select" | "date";
    isRequired?: boolean;
    hideError?: boolean;
    className?: string;
    children: (props: RegisteredField<T>, meta: InputMeta) => React.ReactNode;
};
export type FieldContextType = {
    name?: string;
    label?: string;
    isRequired?: boolean;
    hasError: boolean;
};
/**
 * The UseFormHook provides a set of utilities for managing form state and
 * validation within a React application. It includes methods for setting and
 * retrieving form values, setting validation schemas, handling form submission,
 * and managing form errors. The hook can be used with any schema type that
 * extends the Record<string, any>, providing a flexible and type-safe way to work
 * with forms. Additionally, it supports both controlled and uncontrolled form
 * modes, making it adaptable to various use cases.
 */
export type UseFormHook<T extends Record<string, any> = Record<string, any>, TData = any> = {
    /**
     * Indicates whether the form is validated.
     */
    isValidated: boolean;
    /**
     * The current values of the form.
     */
    values: T;
    /**
     * The current errors of the form fields.
     */
    errors: Partial<Record<keyof T, string | undefined>>;
    /**
     * Set the schema for the form.
     * @param {ZodObject} newSchema The new schema for the form.
     */
    setSchema: (newSchema?: ZodObject<any>) => 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?: keyof T, 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?: keyof T, 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: Partial<T>, options?: {
        overwrite?: boolean;
    }) => void;
    /**
     * Retrieves the value of a single form field.
     */
    getValue: (name: keyof T) => T[keyof T];
    /**
     * 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: Partial<Record<keyof T, 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: T) => void) => (event: React.FormEvent<HTMLFormElement>) => void | Promise<void>;
    /**
     * A utility function to register a form field.
     *
     * @param name - The name of the form field to register.
     * @returns An object containing the form field properties.
     */
    register: <K extends keyof T>(name?: K) => RegisteredField<T>;
    /**
     * Indicates whether the form is currently submitting.
     */
    isSubmitting: boolean;
    /**
     * Form state, only available when you pass onSubmit to useForm
     */
    state: TData;
};
export {};