@vuehookform/core 0.4.2 → 0.4.4

package/README.md

@@ -42,12 +42,12 @@ const onSubmit = (data) => {
 <template>
   <form @submit="handleSubmit(onSubmit)">
     <input v-bind="register('email')" type="email" />
-    <span v-if="formState.errors.email">{{ formState.errors.email }}</span>
+    <span v-if="formState.value.errors.email">{{ formState.value.errors.email }}</span>
 
     <input v-bind="register('password')" type="password" />
-    <span v-if="formState.errors.password">{{ formState.errors.password }}</span>
+    <span v-if="formState.value.errors.password">{{ formState.value.errors.password }}</span>
 
-    <button type="submit" :disabled="formState.isSubmitting">Submit</button>
+    <button type="submit" :disabled="formState.value.isSubmitting">Submit</button>
   </form>
 </template>
 ```
@@ -121,12 +121,56 @@ 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>
+import { useForm, useController, type Control } from '@vuehookform/core'
+
+// control comes from useForm (pass it as a prop to child components)
+const { control } = useForm({ schema })
+const { fieldState } = useController({ name: 'email', control })
+// fieldState is a ComputedRef that updates automatically
+</script>
+<template>
+  <span v-if="fieldState.value.error">{{ fieldState.value.error }}</span>
+</template>
+```
 
 ## Contributing
 

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@vuehookform/core",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "TypeScript-first form library for Vue 3, inspired by React Hook Form. Form-level state management with Zod validation.",
   "type": "module",
+  "workspaces": [
+    "e2e"
+  ],
   "main": "./dist/vuehookform.cjs",
   "module": "./dist/vuehookform.js",
   "types": "./dist/index.d.ts",
@@ -34,6 +37,9 @@
     "test": "vitest",
     "test:run": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "e2e:dev": "npm run -w e2e dev",
+    "test:e2e": "npm run build:lib && npm run -w e2e test:e2e:ci",
+    "test:e2e:open": "npm run build:lib && npm run -w e2e test:e2e:open",
     "prepare": "husky"
   },
   "repository": {

package/dist/context.d.ts

@@ -1,37 +0,0 @@
-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

@@ -1,27 +0,0 @@
-import { Ref } from 'vue';
-import { RegisterOptions } from '../types';
-/**
- * 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;
-/**
- * Update a single DOM element with a new value
- *
- * Handles both checkbox and text inputs appropriately.
- *
- * @param el - The DOM input element to update
- * @param value - The value to set
- */
-export declare function updateDomElement(el: HTMLInputElement, value: unknown): void;

package/dist/core/fieldState.d.ts

@@ -1,53 +0,0 @@
-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

@@ -1,117 +0,0 @@
-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: (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 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

@@ -1,8 +0,0 @@
-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

@@ -1,9 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1,24 +0,0 @@
-/**
- * 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, 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';