@vuehookform/core 0.4.4 → 0.4.6

package/dist/context.d.ts

@@ -0,0 +1,37 @@
+import { InjectionKey } from 'vue';
+import { UseFormReturn } from './types';
+import { ZodType } from 'zod';
+/**
+ * Injection key for form context
+ */
+export declare const FormContextKey: InjectionKey<UseFormReturn<ZodType>>;
+/**
+ * Provide form methods to child components via Vue's dependency injection.
+ *
+ * Call this in a parent component's setup function after calling useForm().
+ *
+ * @example
+ * ```ts
+ * // Parent component
+ * const form = useForm({ schema })
+ * provideForm(form)
+ * ```
+ *
+ * @param methods - The return value from useForm()
+ */
+export declare function provideForm<TSchema extends ZodType>(methods: UseFormReturn<TSchema>): void;
+/**
+ * Access form methods in a child component via Vue's dependency injection.
+ *
+ * Must be used within a component tree where provideForm() has been called.
+ *
+ * @example
+ * ```ts
+ * // Child component
+ * const { register, formState } = useFormContext()
+ * ```
+ *
+ * @returns The form methods from the parent component's useForm() call
+ * @throws Error if used outside of a FormProvider context
+ */
+export declare function useFormContext<TSchema extends ZodType>(): UseFormReturn<TSchema>;

package/dist/core/domSync.d.ts

@@ -0,0 +1,48 @@
+import { Ref } from 'vue';
+import { RegisterOptions } from '../types';
+/**
+ * Extract the actual HTMLInputElement from a ref value.
+ * Handles both native elements and Vue component instances (PrimeVue, Vuetify, etc.)
+ *
+ * Vue component libraries typically expose:
+ * - $el: The root DOM element of the component
+ * - Some components wrap inputs in divs, so we may need to query for the input
+ *
+ * @param refValue - The value from fieldRef.value (HTMLInputElement, Component, or null)
+ * @returns The underlying HTMLInputElement, or null if not found
+ */
+export declare function getInputElement(refValue: unknown): HTMLInputElement | null;
+/**
+ * Get a focusable element from a ref value.
+ * Works with both native elements and Vue component instances.
+ *
+ * @param refValue - The value from fieldRef.value
+ * @returns The focusable HTMLElement, or null if not found
+ */
+export declare function getFocusableElement(refValue: unknown): HTMLElement | null;
+/**
+ * Sync values from uncontrolled DOM inputs to form data
+ *
+ * This reads the current DOM state from uncontrolled inputs and updates
+ * the formData object. Used before form submission and when getting values.
+ *
+ * Handles type coercion for:
+ * - checkbox: returns boolean (el.checked)
+ * - number/range: returns number (el.valueAsNumber)
+ * - all other types: returns string (el.value)
+ *
+ * @param fieldRefs - Map of field names to their DOM element refs
+ * @param fieldOptions - Map of field names to their registration options
+ * @param formData - The reactive form data object to update
+ */
+export declare function syncUncontrolledInputs(fieldRefs: Map<string, Ref<unknown>>, fieldOptions: Map<string, RegisterOptions>, formData: Record<string, unknown>): void;
+/**
+ * Update a single DOM element with a new value
+ *
+ * Handles both checkbox and text inputs appropriately.
+ * Supports both native elements and Vue component instances.
+ *
+ * @param refValue - The ref value (HTMLInputElement, Vue component, or null)
+ * @param value - The value to set
+ */
+export declare function updateDomElement(refValue: unknown, value: unknown): void;

package/dist/core/fieldState.d.ts

@@ -0,0 +1,53 @@
+import { ShallowRef } from 'vue';
+/**
+ * Mark a field as dirty (value has changed from default).
+ * Optimized to skip clone if already dirty.
+ *
+ * @param dirtyFields - The reactive dirty fields record
+ * @param fieldName - Name of the field to mark as dirty
+ */
+export declare function markFieldDirty(dirtyFields: ShallowRef<Record<string, boolean>>, fieldName: string): void;
+/**
+ * Mark a field as touched (user has interacted with it).
+ * Optimized to skip clone if already touched.
+ *
+ * @param touchedFields - The reactive touched fields record
+ * @param fieldName - Name of the field to mark as touched
+ */
+export declare function markFieldTouched(touchedFields: ShallowRef<Record<string, boolean>>, fieldName: string): void;
+/**
+ * Clear dirty state for a field.
+ *
+ * @param dirtyFields - The reactive dirty fields record
+ * @param fieldName - Name of the field to clear
+ */
+export declare function clearFieldDirty(dirtyFields: ShallowRef<Record<string, boolean>>, fieldName: string): void;
+/**
+ * Clear touched state for a field.
+ *
+ * @param touchedFields - The reactive touched fields record
+ * @param fieldName - Name of the field to clear
+ */
+export declare function clearFieldTouched(touchedFields: ShallowRef<Record<string, boolean>>, fieldName: string): void;
+/**
+ * Clear errors for a field and its nested paths.
+ * Optimized with early exit if nothing to delete.
+ *
+ * @param errors - The reactive errors record
+ * @param fieldName - Name of the field (clears exact match and all nested paths)
+ */
+export declare function clearFieldErrors<T>(errors: ShallowRef<Record<string, T>>, fieldName: string): void;
+/**
+ * Update field dirty state based on value comparison with default.
+ * Field is dirty only if current value differs from default value.
+ *
+ * Uses lazy hash computation - default hashes are computed on first access
+ * and cached for subsequent comparisons.
+ *
+ * @param dirtyFields - The reactive dirty fields record
+ * @param defaultValues - The original default values
+ * @param defaultValueHashes - Cache of hashed default values
+ * @param fieldName - Name of the field to check
+ * @param currentValue - The current value to compare against default
+ */
+export declare function updateFieldDirtyState(dirtyFields: ShallowRef<Record<string, boolean>>, defaultValues: Record<string, unknown>, defaultValueHashes: Map<string, string>, fieldName: string, currentValue: unknown): void;

package/dist/core/formContext.d.ts

@@ -0,0 +1,117 @@
+import { Ref, ShallowRef } from 'vue';
+import { ZodType } from 'zod';
+import { UseFormOptions, FieldErrors, FieldErrorValue, InferSchema, RegisterOptions, FieldArrayItem, FieldArrayRules } from '../types';
+/**
+ * Internal state for field array management.
+ * Tracks items, their indices, and array-level validation rules.
+ *
+ * @internal This interface is used internally by useFieldArray and should not be
+ * directly instantiated by consumers.
+ */
+export interface FieldArrayState {
+    /** Reactive list of field array items with stable keys for Vue reconciliation */
+    items: Ref<FieldArrayItem[]>;
+    /** Raw array values (kept in sync with formData) */
+    values: unknown[];
+    /** O(1) lookup cache mapping item keys to their current indices */
+    indexCache: Map<string, number>;
+    /** Optional validation rules for the array itself (minLength, maxLength, custom) */
+    rules?: FieldArrayRules;
+}
+/**
+ * Cached event handlers for a field.
+ * These are created once per field registration and reused to prevent
+ * unnecessary re-renders and closure recreation.
+ *
+ * @internal This interface is used internally by useFieldRegistration and should not be
+ * directly instantiated by consumers.
+ */
+export interface FieldHandlers {
+    /** Handler for input events, triggers validation based on mode */
+    onInput: (e: Event) => Promise<void>;
+    /** Handler for blur events, marks field as touched and may trigger validation */
+    onBlur: () => Promise<void>;
+    /** Ref callback to capture the DOM element reference */
+    refCallback: (el: unknown) => void;
+}
+/**
+ * Shared form context containing all reactive state.
+ * This is the central state container passed to sub-modules via dependency injection.
+ *
+ * The context is organized into several categories:
+ * - **Form Data**: Raw form values and their defaults
+ * - **Form State**: Validation errors, touched/dirty tracking, submission state
+ * - **Field Tracking**: DOM refs, registration options, field arrays
+ * - **Validation**: Caching, debouncing, and async validation coordination
+ * - **Configuration**: Form options and disabled state
+ *
+ * @typeParam FormValues - The inferred type from the Zod schema
+ *
+ * @internal This interface is used internally by useForm and its sub-modules.
+ * Consumers should use the public API returned by useForm() instead.
+ */
+export interface FormContext<FormValues> {
+    /** Reactive form data object containing current field values */
+    formData: Record<string, unknown>;
+    /** Original default values used for reset() and dirty detection */
+    defaultValues: Record<string, unknown>;
+    /** Current validation errors keyed by field path */
+    errors: ShallowRef<FieldErrors<FormValues>>;
+    /** Record of field paths that have been touched (blurred) */
+    touchedFields: ShallowRef<Record<string, boolean>>;
+    /** Record of field paths that differ from default values */
+    dirtyFields: ShallowRef<Record<string, boolean>>;
+    /** Whether the form is currently being submitted */
+    isSubmitting: Ref<boolean>;
+    /** Whether async default values are being loaded */
+    isLoading: Ref<boolean>;
+    /** Number of times the form has been submitted */
+    submitCount: Ref<number>;
+    /** Error that occurred while loading async default values */
+    defaultValuesError: Ref<unknown>;
+    /** Whether the last submission completed successfully */
+    isSubmitSuccessful: Ref<boolean>;
+    /** Set of field paths currently being validated (for isValidating state) */
+    validatingFields: ShallowRef<Set<string>>;
+    /** External errors (e.g., from server) merged with validation errors */
+    externalErrors: ShallowRef<FieldErrors<FormValues>>;
+    /** Timers for delayed error display per field */
+    errorDelayTimers: Map<string, ReturnType<typeof setTimeout>>;
+    /** Pending errors waiting for delay timer to complete */
+    pendingErrors: Map<string, FieldErrorValue>;
+    /** DOM element refs for registered uncontrolled fields */
+    fieldRefs: Map<string, Ref<HTMLInputElement | null>>;
+    /** Registration options per field path */
+    fieldOptions: Map<string, RegisterOptions>;
+    /** Field array state for array fields managed by fields() */
+    fieldArrays: Map<string, FieldArrayState>;
+    /** Cached event handlers to prevent recreation on re-render */
+    fieldHandlers: Map<string, FieldHandlers>;
+    /** Debounce timers for custom async validation per field */
+    debounceTimers: Map<string, ReturnType<typeof setTimeout>>;
+    /** Request IDs for canceling stale async validation results */
+    validationRequestIds: Map<string, number>;
+    /** Generation counter incremented on reset to cancel in-flight validations */
+    resetGeneration: Ref<number>;
+    /** Cache of validation results keyed by field path and value hash */
+    validationCache: Map<string, {
+        hash: string;
+        isValid: boolean;
+    }>;
+    /** Debounce timers for schema validation per field */
+    schemaValidationTimers: Map<string, ReturnType<typeof setTimeout>>;
+    /** Set of field paths with persistent errors (survive validation cycles) */
+    persistentErrorFields: Set<string>;
+    /** Hashed default values for value-comparison dirty detection */
+    defaultValueHashes: Map<string, string>;
+    /** Whether the entire form is disabled */
+    isDisabled: Ref<boolean>;
+    /** Original options passed to useForm() */
+    options: UseFormOptions<ZodType>;
+    /** Cleanup function to stop all watchers and prevent memory leaks */
+    cleanup: () => void;
+}
+/**
+ * Create a new form context with all reactive state initialized
+ */
+export declare function createFormContext<TSchema extends ZodType>(options: UseFormOptions<TSchema>): FormContext<InferSchema<TSchema>>;

package/dist/core/useFieldArray.d.ts

@@ -0,0 +1,8 @@
+import { FormContext } from './formContext';
+import { FieldArray, FieldArrayOptions, Path } from '../types';
+/**
+ * Create field array management functions
+ */
+export declare function createFieldArrayManager<FormValues>(ctx: FormContext<FormValues>, validate: (fieldPath?: string) => Promise<boolean>, setFocus: (name: string) => void): {
+    fields: <TPath extends Path<FormValues>>(name: TPath, options?: FieldArrayOptions) => FieldArray;
+};

package/dist/core/useFieldRegistration.d.ts

@@ -0,0 +1,9 @@
+import { FormContext } from './formContext';
+import { RegisterOptions, RegisterReturn, UnregisterOptions, Path } from '../types';
+/**
+ * Create field registration functions
+ */
+export declare function createFieldRegistration<FormValues>(ctx: FormContext<FormValues>, validate: (fieldPath?: string) => Promise<boolean>): {
+    register: <TPath extends Path<FormValues>>(name: TPath, registerOptions?: RegisterOptions) => RegisterReturn;
+    unregister: <TPath extends Path<FormValues>>(name: TPath, options?: UnregisterOptions) => void;
+};

package/dist/core/useValidation.d.ts

@@ -0,0 +1,8 @@
+import { FormContext } from './formContext';
+/**
+ * Create validation functions for form
+ */
+export declare function createValidation<FormValues>(ctx: FormContext<FormValues>): {
+    validate: (fieldPath?: string) => Promise<boolean>;
+    clearAllPendingErrors: () => void;
+};

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Vue Hook Form - TypeScript-first form library for Vue 3
+ *
+ * @example
+ * ```ts
+ * import { useForm } from './lib'
+ * import { z } from 'zod'
+ *
+ * const schema = z.object({
+ *   email: z.email(),
+ *   name: z.string().min(2)
+ * })
+ *
+ * const { register, handleSubmit, formState } = useForm({ schema })
+ * ```
+ */
+export { useForm } from './useForm';
+export { provideForm, useFormContext, FormContextKey } from './context';
+export { useWatch, type UseWatchOptions } from './useWatch';
+export { useController, type UseControllerOptions, type UseControllerReturn, type ControllerFieldProps, } from './useController';
+export { useFormState, type UseFormStateOptions, type FormStateKey } from './useFormState';
+export { isFieldError } from './types';
+export type { UseFormOptions, UseFormReturn, UseFormReturn as Control, RegisterOptions, RegisterReturn, FormState, FieldState, FieldErrors, FieldError, FieldErrorValue, ErrorOption, SetErrorsOptions, FieldArray, FieldArrayItem, FieldArrayOptions, FieldArrayRules, FieldArrayFocusOptions, InferSchema, FormValues, FormPath, Path, PathValue, ArrayElement, ArrayPath, FieldPath, ValidationMode, SetFocusOptions, ResetOptions, ResetFieldOptions, AsyncDefaultValues, TriggerOptions, SetValueOptions, UnregisterOptions, CriteriaMode, } from './types';
+export { get, set, unset, clearPathCache } from './utils/paths';