slimeform/dist/index.d.ts

Form state management and validation for Vue3

import { Ref, UnwrapNestedRefs, ComputedRef, DeepReadonly } from 'vue';

type IgnoredUpdater = (updater: () => void) => void;

interface StatusItem {
    isError: boolean;
    /** Error message */
    message: string;
    /** Field is modified */
    isDirty: boolean;
    /** Manual verify */
    verify: () => boolean;
    init: () => void;
    setError: (message: string, isError?: boolean) => void;
    clearError: () => void;
    _ignoreUpdate: IgnoredUpdater;
}
type FormStatus<FormT> = {
    readonly [K in keyof FormT]: StatusItem;
};

type SubmitFunction<FormT = any, FnReturnT = any> = (formData: Omit<UseFormReturn<FormT>, 'submitter'>) => FnReturnT;
type Submitter<FormT> = <FnT extends SubmitFunction<FormT>>(fn: FnT, options?: CreateSubmitOptions) => CreateSubmitReturn<FnT>;
interface CreateSubmitOptions {
    /**
     * ## Enable Verification
     * Check validation before committing and skip the commit process if it fails
     * @default true
     */
    enableVerify?: boolean;
}
interface CreateSubmitReturn<FnT extends SubmitFunction<any>> {
    submit: () => ReturnType<FnT> | undefined;
    submitting: Ref<boolean>;
}

type UnknownObject = Record<string, unknown>;

type RuleItem<ValueT = any> = ((val: ValueT) => boolean | string);
type UseFormBuilder<Form = UnknownObject> = () => Form;
type UseFormRule<FormT = UnknownObject> = {
    readonly [K in keyof FormT]?: RuleItem<FormT[K]> | RuleItem<FormT[K]>[];
};
type UseFormDefaultMessage = string;
type UseFormLazy = boolean;
interface UseFormParam<FormT> {
    /** Initial form value */
    form: UseFormBuilder<FormT>;
    /** Verification rules */
    rule?: UseFormRule<FormT>;
    /** Default error message */
    defaultMessage?: UseFormDefaultMessage;
    /**
     * Prevent rules from being automatically verified when data changes,
     * Unless `verify()` or `status[fieldName].verify()` is called manually to validate the rule.
     *
     * @default false
     */
    lazy?: UseFormLazy;
    /**
     * If `true`, all rules will be fully validated.
     *
     * @default false
     */
    fullValidation?: boolean;
}
interface ValidateOptions<FullResult extends boolean> {
    fullResult?: FullResult;
}
interface ValidateResult {
    valid: boolean;
    message: string;
}
interface UseFormReturnRuleItem {
    validate: ((value: any) => boolean) & ((value: any, options: ValidateOptions<false>) => boolean) & ((value: any, options: ValidateOptions<true>) => ValidateResult);
}
type UseFormReturnRule<FormT> = Record<keyof UseFormRule<FormT>, UseFormReturnRuleItem>;
interface UseFormReturn<FormT> {
    /** form object */
    form: UnwrapNestedRefs<FormT>;
    /** Form status */
    status: FormStatus<FormT>;
    rule: UseFormReturnRule<FormT>;
    /** A object that only contains the modified `form` fields */
    dirtyFields: ComputedRef<DeepReadonly<UnwrapNestedRefs<Partial<FormT>>>>;
    /** Form is modified */
    isDirty: ComputedRef<boolean>;
    /** Whether any of form fields contain an errored validation result */
    isError: ComputedRef<boolean>;
    /** Manual verify */
    verify: () => boolean;
    /** Clear all errors */
    clearErrors: () => void;
    /**
     * Reset form to initial value
     * @param fields If not specified, all form fields will be reset
     */
    reset: (...fields: (keyof FormT)[]) => void;
    /**
     * Submit form
     * Verify before submitting, and execute callback if passed
     * @deprecated use `submitter` instead of it
     */
    onSubmit: (callback: () => unknown) => unknown;
    /**
     * Define a submit function
     * Returns the wrapped commit function and status variables
     * Verify before submitting, and execute callback if passed
     */
    submitter: Submitter<FormT>;
}

/**
 *  Form state management and rule validation
 * @see https://vueuse.org/useForm
 * @param param Form and Rule object
 * @returns Form and Form Status
 */
declare function useForm<FormT extends {}>(param: UseFormParam<FormT>): UseFormReturn<FormT>;

export { type CreateSubmitOptions, type CreateSubmitReturn, type FormStatus, type RuleItem, type StatusItem, type SubmitFunction, type Submitter, type UseFormBuilder, type UseFormDefaultMessage, type UseFormLazy, type UseFormParam, type UseFormReturn, type UseFormReturnRule, type UseFormReturnRuleItem, type UseFormRule, type ValidateOptions, type ValidateResult, useForm };