@vuehookform/core 0.4.0 → 0.4.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 vuehookform
+Copyright (c) 2026 vuehookform
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/core/domSync.d.ts

@@ -6,6 +6,11 @@ import { RegisterOptions } from '../types';
  * 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

package/dist/core/fieldState.d.ts

@@ -1,42 +1,34 @@
-import { Ref, ShallowRef } from 'vue';
+import { ShallowRef } from 'vue';
 /**
  * Mark a field as dirty (value has changed from default).
  * Optimized to skip clone if already dirty.
- * Maintains O(1) dirty field count for performance.
  *
  * @param dirtyFields - The reactive dirty fields record
- * @param dirtyFieldCount - Counter for O(1) isDirty checks
  * @param fieldName - Name of the field to mark as dirty
  */
-export declare function markFieldDirty(dirtyFields: ShallowRef<Record<string, boolean>>, dirtyFieldCount: Ref<number>, fieldName: string): void;
+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.
- * Maintains O(1) touched field count for performance.
  *
  * @param touchedFields - The reactive touched fields record
- * @param touchedFieldCount - Counter for O(1) touched checks
  * @param fieldName - Name of the field to mark as touched
  */
-export declare function markFieldTouched(touchedFields: ShallowRef<Record<string, boolean>>, touchedFieldCount: Ref<number>, fieldName: string): void;
+export declare function markFieldTouched(touchedFields: ShallowRef<Record<string, boolean>>, fieldName: string): void;
 /**
  * Clear dirty state for a field.
- * Maintains O(1) dirty field count for performance.
  *
  * @param dirtyFields - The reactive dirty fields record
- * @param dirtyFieldCount - Counter for O(1) isDirty checks
  * @param fieldName - Name of the field to clear
  */
-export declare function clearFieldDirty(dirtyFields: ShallowRef<Record<string, boolean>>, dirtyFieldCount: Ref<number>, fieldName: string): void;
+export declare function clearFieldDirty(dirtyFields: ShallowRef<Record<string, boolean>>, fieldName: string): void;
 /**
  * Clear touched state for a field.
- * Maintains O(1) touched field count for performance.
  *
  * @param touchedFields - The reactive touched fields record
- * @param touchedFieldCount - Counter for O(1) touched checks
  * @param fieldName - Name of the field to clear
  */
-export declare function clearFieldTouched(touchedFields: ShallowRef<Record<string, boolean>>, touchedFieldCount: Ref<number>, fieldName: string): void;
+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.
@@ -45,3 +37,17 @@ export declare function clearFieldTouched(touchedFields: ShallowRef<Record<strin
  * @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

@@ -2,57 +2,114 @@ 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
+ * 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 to prevent recreation on every render
+ * 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: (e: Event) => Promise<void>;
+    /** Ref callback to capture the DOM element reference */
     refCallback: (el: unknown) => void;
 }
 /**
- * Shared form context containing all reactive state
- * This is passed to sub-modules via dependency injection
+ * 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>;
-    isDisabled: Ref<boolean>;
-    dirtyFieldCount: Ref<number>;
-    touchedFieldCount: 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

package/dist/index.d.ts

@@ -20,4 +20,5 @@ 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, RegisterOptions, RegisterReturn, FormState, FieldState, FieldErrors, FieldError, FieldErrorValue, ErrorOption, SetErrorsOptions, FieldArray, FieldArrayItem, InferSchema, FormValues, FormPath, Path, PathValue, ArrayElement, ArrayPath, FieldPath, ValidationMode, SetFocusOptions, ResetOptions, ResetFieldOptions, AsyncDefaultValues, } from './types';
+export type { UseFormOptions, UseFormReturn, 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, generateId, clearPathCache } from './utils/paths';

package/dist/types.d.ts

@@ -7,7 +7,7 @@ export type ValidationMode = 'onSubmit' | 'onBlur' | 'onChange' | 'onTouched';
 /**
  * Extract the inferred type from a Zod schema
  */
-export type InferSchema<T extends ZodType> = z.infer<T>;
+export type InferSchema<TSchema extends ZodType> = z.infer<TSchema>;
 /**
  * Alias for InferSchema - extracts form value type from schema.
  * Use this when you need the actual form data type.
@@ -198,7 +198,7 @@ export interface FieldState {
     /** Whether field has a validation error */
     invalid: boolean;
     /** The error (string for backward compatibility, or FieldError for structured errors) */
-    error?: string | FieldError;
+    error?: FieldErrorValue;
 }
 /**
  * Error option for setError()
@@ -208,6 +208,11 @@ export interface ErrorOption {
     type?: string;
     /** Error message to display */
     message: string;
+    /**
+     * If true, the error will not be cleared by subsequent validations.
+     * Useful for server-side validation errors that should persist until explicitly cleared.
+     */
+    persistent?: boolean;
 }
 /**
  * Options for setFocus()
@@ -241,6 +246,16 @@ export interface ResetFieldOptions<TValue = unknown> {
     /** New default value (updates stored default) - typed to match field */
     defaultValue?: TValue;
 }
+/**
+ * Options for trigger()
+ */
+export interface TriggerOptions {
+    /**
+     * If true, increments submitCount to activate reValidateMode behavior.
+     * Useful when you want manual validation to trigger reValidation on subsequent changes.
+     */
+    markAsSubmitted?: boolean;
+}
 /**
  * Options for unregister()
  */
@@ -839,14 +854,20 @@ export interface UseFormReturn<TSchema extends ZodType> {
     /**
      * Manually trigger validation for specific fields or entire form
      * @param name - Optional field path or array of paths
+     * @param options - Optional trigger options (e.g., markAsSubmitted)
      */
-    trigger: <TPath extends Path<InferSchema<TSchema>>>(name?: TPath | TPath[]) => Promise<boolean>;
+    trigger: <TPath extends Path<InferSchema<TSchema>>>(name?: TPath | TPath[], options?: TriggerOptions) => Promise<boolean>;
     /**
      * Programmatically focus a field
      * @param name - Field path
      * @param options - Focus options
      */
     setFocus: <TPath extends Path<InferSchema<TSchema>>>(name: TPath, options?: SetFocusOptions) => void;
+    /**
+     * Form configuration options (mode, reValidateMode).
+     * Useful for composables like useController that need to respect validation modes.
+     */
+    options: Pick<UseFormOptions<TSchema>, 'mode' | 'reValidateMode'>;
 }
 /**
  * Type guard to check if an error value is a structured FieldError object.

package/dist/utils/clone.d.ts

@@ -8,12 +8,12 @@
  * - Arrays (recursive clone)
  * - Date objects (new Date instance)
  * - null/undefined (pass-through)
+ * - Circular references (recreates the circular structure in the clone)
  *
  * Does NOT handle (by design, not needed for form data):
- * - Circular references
  * - Map/Set/WeakMap/WeakSet
  * - Functions
  * - Symbols
  * - Class instances (cloned as plain objects)
  */
-export declare function deepClone<T>(obj: T): T;
+export declare function deepClone<T>(obj: T, seen?: Map<object, unknown>): T;

package/dist/utils/hash.d.ts

@@ -2,5 +2,8 @@
  * Fast value hashing for validation cache.
  * Uses JSON.stringify for objects/arrays, direct conversion for primitives.
  * Returns a string that can be compared for equality.
+ *
+ * Handles circular references by assigning stable IDs via WeakMap,
+ * ensuring the same object always produces the same hash.
  */
 export declare function hashValue(value: unknown): string;

package/dist/utils/modeChecks.d.ts

@@ -0,0 +1,22 @@
+import { ValidationMode } from '../types';
+/**
+ * Determines if validation should occur on change event.
+ * Used by useController and register for consistent mode handling.
+ *
+ * @param mode - The form's validation mode
+ * @param isTouched - Whether the field has been touched
+ * @param reValidateMode - The form's reValidateMode (used after first submit)
+ * @param hasSubmitted - Whether the form has been submitted at least once (optional, for reValidateMode)
+ * @returns true if validation should be triggered
+ */
+export declare function shouldValidateOnChange(mode: ValidationMode, isTouched: boolean, reValidateMode?: ValidationMode, hasSubmitted?: boolean): boolean;
+/**
+ * Determines if validation should occur on blur event.
+ * Used by useController and register for consistent mode handling.
+ *
+ * @param mode - The form's validation mode
+ * @param hasSubmitted - Whether the form has been submitted at least once
+ * @param reValidateMode - The form's reValidateMode (used after first submit)
+ * @returns true if validation should be triggered
+ */
+export declare function shouldValidateOnBlur(mode: ValidationMode, hasSubmitted: boolean, reValidateMode?: ValidationMode): boolean;

package/dist/utils/paths.d.ts

@@ -1,6 +1,10 @@
 /**
- * Clear the path cache. Useful for testing or when paths change significantly.
- * @internal
+ * Clear the path segment cache.
+ * Call this between SSR requests to prevent memory accumulation,
+ * or in tests to reset state.
+ *
+ * The cache is bounded to 256 entries, so clearing is optional
+ * for client-side only applications.
  */
 export declare function clearPathCache(): void;
 /**
@@ -19,7 +23,15 @@ export declare function set(obj: Record<string, unknown>, path: string, value: u
  */
 export declare function unset(obj: Record<string, unknown>, path: string): void;
 /**
- * Check if path exists in object
+ * Check if path exists in object.
+ * Unlike `get(obj, path) !== undefined`, this properly distinguishes between
+ * a missing path and a path that exists with an `undefined` value.
+ *
+ * @example
+ * has({ name: undefined }, 'name') // true - path exists
+ * has({ }, 'name') // false - path doesn't exist
+ * has({ user: { name: 'John' } }, 'user.name') // true
+ * has({ user: { name: 'John' } }, 'user.age') // false
  */
 export declare function has(obj: Record<string, unknown>, path: string): boolean;
 export declare function generateId(): string;