@vuehookform/core 0.4.1 → 0.4.3

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/README.md

@@ -121,12 +121,52 @@ const { value, ...bindings } = register('field', { controlled: true })
 
 ### Common Mistakes
 
-| Wrong                    | Right                    |
-| ------------------------ | ------------------------ |
-| `items[0].name`          | `items.0.name`           |
-| `:key="index"`           | `:key="field.key"`       |
-| `formState.errors`       | `formState.value.errors` |
-| `v-model` + `register()` | Either one, not both     |
+| Wrong                                | Right                                     | Why                                          |
+| ------------------------------------ | ----------------------------------------- | -------------------------------------------- |
+| `items[0].name`                      | `items.0.name`                            | Always use dot notation for paths            |
+| `:key="index"`                       | `:key="field.key"`                        | Index can change during reordering           |
+| `formState.errors`                   | `formState.value.errors`                  | formState is a Ref, must access `.value`     |
+| `v-model` + `register()`             | Either one, not both                      | Causes double binding conflict               |
+| `const state = getFieldState('x')`   | `formState.value.errors.x`                | getFieldState returns snapshot, not reactive |
+| `<CustomInput v-bind="register()"/>` | Use `controlled: true` or `useController` | Custom components need controlled mode       |
+
+#### ⚠️ Critical: `getFieldState()` is NOT Reactive
+
+**Problem:** Calling `getFieldState()` once returns a snapshot that never updates.
+
+```vue
+<!-- ❌ WRONG - Error will persist even after fixing the input -->
+<script setup>
+const emailState = getFieldState('email')
+</script>
+<template>
+  <span v-if="emailState.error">{{ emailState.error }}</span>
+</template>
+```
+
+**Solutions:**
+
+```vue
+<!-- ✅ Option 1: Use formState (always reactive) -->
+<span v-if="formState.value.errors.email">{{ formState.value.errors.email }}</span>
+
+<!-- ✅ Option 2: Use computed for specific field -->
+<script setup>
+const emailError = computed(() => formState.value.errors.email)
+</script>
+<template>
+  <span v-if="emailError">{{ emailError }}</span>
+</template>
+
+<!-- ✅ Option 3: Use useController for reusable components -->
+<script setup>
+const { fieldState } = useController({ name: 'email', control })
+// fieldState is a ComputedRef that updates automatically
+</script>
+<template>
+  <span v-if="fieldState.error">{{ fieldState.error }}</span>
+</template>
+```
 
 ## Contributing
 

package/dist/core/domSync.d.ts

@@ -1,22 +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<HTMLInputElement | null>>, fieldOptions: Map<string, RegisterOptions>, formData: Record<string, unknown>): void;
+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 el - The DOM input element to update
+ * @param refValue - The ref value (HTMLInputElement, Vue component, or null)
  * @param value - The value to set
  */
-export declare function updateDomElement(el: HTMLInputElement, value: unknown): void;
+export declare function updateDomElement(refValue: unknown, value: unknown): void;

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>;
-    onBlur: (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 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()
  */
@@ -341,7 +356,7 @@ export interface RegisterReturn<TValue = unknown> {
     /** Input handler (fires on every keystroke) */
     onInput: (e: Event) => void;
     /** Blur handler */
-    onBlur: (e: Event) => void;
+    onBlur: () => void;
     /** Current value (for controlled mode) - only present when controlled: true */
     value?: Ref<TValue>;
     /** Disabled state from form-level disabled option */
@@ -403,6 +418,10 @@ export interface FieldArrayOptions<T = unknown> {
  * - minLength rule would be violated (remove, removeAll, removeMany)
  * - Index is out of bounds (remove, update, swap, move)
  *
+ * **Reactivity:** The `value` property is fully reactive - it automatically
+ * updates when array methods (append, remove, swap, etc.) are called.
+ * Your template will re-render when items change.
+ *
  * @template TItem - The type of items in the array (inferred from field path)
  *
  * @example
@@ -418,7 +437,7 @@ export interface FieldArrayOptions<T = unknown> {
  * }
  */
 export interface FieldArray<TItem = unknown> {
-    /** Current field items with metadata */
+    /** Current field items with metadata. Reactive - updates when array methods are called. */
     value: FieldArrayItem[];
     /** Append item(s) to end of array. Returns false if maxLength exceeded. */
     append: (value: TItem | TItem[], options?: FieldArrayFocusOptions) => boolean;
@@ -839,14 +858,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/useForm.d.ts

@@ -1,5 +1,11 @@
 import { ZodType } from 'zod';
 import { UseFormOptions, UseFormReturn } from './types';
+/**
+ * Set the internal flag to suppress getFieldState warnings.
+ * Used by useController before calling getFieldState inside computed().
+ * @internal
+ */
+export declare function setCalledFromController(value: boolean): void;
 /**
  * Main form management composable
  *

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;