@vuehookform/core 0.1.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,6 +2,8 @@
 
 A TypeScript-first form library for Vue 3, inspired by React Hook Form.
 
+[![npm version](https://img.shields.io/npm/v/@vuehookform/core)](https://www.npmjs.com/package/@vuehookform/core) [![CI](https://img.shields.io/github/actions/workflow/status/vuehookform/core/ci.yml?branch=main&label=CI)](https://github.com/vuehookform/core/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![Coverage](https://img.shields.io/badge/coverage-90%25+-brightgreen)](https://github.com/vuehookform/core)
+
 ## Features
 
 - **TypeScript First** - Perfect type inference with zero manual typing
@@ -87,7 +89,7 @@ const addresses = fields('addresses')
 ```typescript
 useForm({
   schema,
-  mode: 'onSubmit',  // Only validate on submit (default)
+  mode: 'onSubmit', // Only validate on submit (default)
   // mode: 'onBlur',    // Validate when field loses focus
   // mode: 'onChange',  // Validate on every keystroke
   // mode: 'onTouched', // Validate after field is touched
@@ -100,19 +102,19 @@ useForm({
 
 ```typescript
 const {
-  register,      // Register input field
-  handleSubmit,  // Create submit handler with validation
-  formState,     // Reactive form state (errors, isSubmitting, etc.)
-  fields,        // Manage dynamic field arrays
-  setValue,      // Programmatically set field value
-  getValue,      // Get current field value
-  reset,         // Reset form to default values
-  watch,         // Watch field value changes
-  validate,      // Manually trigger validation
+  register, // Register input field
+  handleSubmit, // Create submit handler with validation
+  formState, // Reactive form state (errors, isSubmitting, etc.)
+  fields, // Manage dynamic field arrays
+  setValue, // Programmatically set field value
+  getValue, // Get current field value
+  reset, // Reset form to default values
+  watch, // Watch field value changes
+  validate, // Manually trigger validation
 } = useForm({
-  schema,                    // Zod schema for validation
-  defaultValues: {},         // Initial form values
-  mode: 'onSubmit',          // When to validate
+  schema, // Zod schema for validation
+  defaultValues: {}, // Initial form values
+  mode: 'onSubmit', // When to validate
 })
 ```
 

package/dist/core/formContext.d.ts

@@ -1,12 +1,22 @@
 import { Ref, ShallowRef } from 'vue';
 import { ZodType } from 'zod';
-import { UseFormOptions, FieldErrors, InferSchema, RegisterOptions, FieldArrayItem } from '../types';
+import { UseFormOptions, FieldErrors, FieldErrorValue, InferSchema, RegisterOptions, FieldArrayItem, FieldArrayRules } from '../types';
 /**
  * Internal state for field array management
  */
 export interface FieldArrayState {
     items: Ref<FieldArrayItem[]>;
     values: unknown[];
+    indexCache: Map<string, number>;
+    rules?: FieldArrayRules;
+}
+/**
+ * Cached event handlers for a field to prevent recreation on every render
+ */
+export interface FieldHandlers {
+    onInput: (e: Event) => Promise<void>;
+    onBlur: (e: Event) => Promise<void>;
+    refCallback: (el: unknown) => void;
 }
 /**
  * Shared form context containing all reactive state
@@ -16,16 +26,24 @@ export interface FormContext<FormValues> {
     formData: Record<string, unknown>;
     defaultValues: Record<string, unknown>;
     errors: ShallowRef<FieldErrors<FormValues>>;
-    touchedFields: Ref<Record<string, boolean>>;
-    dirtyFields: Ref<Record<string, boolean>>;
+    touchedFields: ShallowRef<Record<string, boolean>>;
+    dirtyFields: ShallowRef<Record<string, boolean>>;
     isSubmitting: Ref<boolean>;
     isLoading: Ref<boolean>;
     submitCount: Ref<number>;
+    defaultValuesError: Ref<unknown>;
+    isSubmitSuccessful: Ref<boolean>;
+    validatingFields: ShallowRef<Record<string, boolean>>;
+    externalErrors: ShallowRef<FieldErrors<FormValues>>;
+    errorDelayTimers: Map<string, ReturnType<typeof setTimeout>>;
+    pendingErrors: Map<string, FieldErrorValue>;
     fieldRefs: Map<string, Ref<HTMLInputElement | null>>;
     fieldOptions: Map<string, RegisterOptions>;
     fieldArrays: Map<string, FieldArrayState>;
+    fieldHandlers: Map<string, FieldHandlers>;
     debounceTimers: Map<string, ReturnType<typeof setTimeout>>;
     validationRequestIds: Map<string, number>;
+    resetGeneration: Ref<number>;
     options: UseFormOptions<ZodType>;
 }
 /**

package/dist/core/useFieldArray.d.ts

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

package/dist/core/useValidation.d.ts

@@ -4,4 +4,5 @@ import { FormContext } from './formContext';
  */
 export declare function createValidation<FormValues>(ctx: FormContext<FormValues>): {
     validate: (fieldPath?: string) => Promise<boolean>;
+    clearAllPendingErrors: () => void;
 };

package/dist/index.d.ts

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

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import { ComputedRef, Ref } from 'vue';
+import { ComponentPublicInstance, ComputedRef, MaybeRef, Ref } from 'vue';
 import { ZodType, z } from 'zod';
 /**
  * Validation mode determines when validation occurs
@@ -9,17 +9,72 @@ export type ValidationMode = 'onSubmit' | 'onBlur' | 'onChange' | 'onTouched';
  */
 export type InferSchema<T extends ZodType> = z.infer<T>;
 /**
- * Generate all possible paths for a nested object type
- * e.g., { user: { name: string } } => 'user' | 'user.name'
+ * Alias for InferSchema - extracts form value type from schema.
+ * Use this when you need the actual form data type.
+ *
+ * @example
+ * const schema = z.object({ email: z.string(), age: z.number() })
+ * type MyFormValues = FormValues<typeof schema>
+ * // Result: { email: string; age: number }
+ */
+export type FormValues<TSchema extends ZodType> = InferSchema<TSchema>;
+/**
+ * Extract the element type from an array type.
+ * Returns `never` if T is not an array.
+ *
+ * @example
+ * type Item = ArrayElement<string[]>  // string
+ * type Never = ArrayElement<string>   // never
+ */
+export type ArrayElement<T> = T extends Array<infer U> ? U : never;
+/**
+ * Generate all possible dot-notation paths for a nested object type.
+ * Provides IDE autocomplete for valid field names.
+ *
+ * @example
+ * type Form = { user: { name: string; age: number }; tags: string[] }
+ * type FormPaths = Path<Form>
+ * // Result: 'user' | 'user.name' | 'user.age' | 'tags'
+ *
+ * @example Using with register
+ * register('user.name')  // ✅ Valid - autocomplete suggests this
+ * register('user.invalid')  // ❌ TypeScript error
  */
 export type Path<T> = T extends object ? {
     [K in keyof T & (string | number)]: K extends string | number ? `${K}` | `${K}.${Path<T[K]>}` : never;
 }[keyof T & (string | number)] : never;
 /**
- * Get the type at a given path
- * e.g., PathValue<{ user: { name: string } }, 'user.name'> => string
+ * Type alias for valid field paths in a form.
+ * Provides autocomplete for all dot-notation paths.
+ *
+ * @example
+ * type MyPaths = FormPath<typeof schema>
+ * // Use with functions that accept field paths
  */
-export type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? Rest extends Path<T[K]> ? PathValue<T[K], Rest> : never : never : P extends keyof T ? T[P] : never;
+export type FormPath<TSchema extends ZodType> = Path<FormValues<TSchema>>;
+/**
+ * Get array field paths (fields that are arrays).
+ * Useful for the fields() method which only works with array fields.
+ *
+ * @example
+ * type Form = { name: string; addresses: Address[] }
+ * type ArrayFields = ArrayPath<Form>  // 'addresses'
+ */
+export type ArrayPath<T> = {
+    [K in Path<T>]: PathValue<T, K> extends Array<unknown> ? K : never;
+}[Path<T>];
+/**
+ * Extract the value type at a given dot-notation path.
+ * Used internally to ensure setValue/getValue have correct types.
+ * Supports numeric string indices for array access (e.g., 'items.0.name').
+ *
+ * @example
+ * type Form = { user: { name: string }; items: { id: number }[] }
+ * type NameType = PathValue<Form, 'user.name'>    // string
+ * type ItemType = PathValue<Form, 'items.0'>      // { id: number }
+ * type ItemId = PathValue<Form, 'items.0.id'>     // number
+ */
+export type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? PathValue<T[K], Rest> : T extends Array<infer U> ? K extends `${number}` ? PathValue<U, Rest> : never : never : P extends keyof T ? T[P] : T extends Array<infer U> ? P extends `${number}` ? U : never : never;
 /**
  * Single field error with type and message
  */
@@ -32,7 +87,21 @@ export interface FieldError {
     types?: Record<string, string | string[]>;
 }
 /**
- * Field error value - can be a simple string (backward compatible) or structured error
+ * Field error value - supports both simple strings and structured errors.
+ *
+ * - When `criteriaMode: 'firstError'` (default): Errors are typically strings
+ * - When `criteriaMode: 'all'`: Errors are FieldError objects with `types` populated
+ *
+ * Use the `isFieldError()` type guard to safely handle both cases:
+ * @example
+ * const error = formState.value.errors.email
+ * if (isFieldError(error)) {
+ *   // Structured error with type, message, and optional types
+ *   console.log(error.type, error.message)
+ * } else if (typeof error === 'string') {
+ *   // Simple string error
+ *   console.log(error)
+ * }
  */
 export type FieldErrorValue = string | FieldError;
 /**
@@ -58,12 +127,24 @@ export interface FormState<T> {
     isSubmitting: boolean;
     /** Whether async default values are loading */
     isLoading: boolean;
+    /** Whether form is ready (initialization complete, not loading) */
+    isReady: boolean;
+    /** Whether any field is currently being validated */
+    isValidating: boolean;
+    /** Record of fields currently being validated */
+    validatingFields: Record<string, boolean>;
     /** Record of touched field paths */
     touchedFields: Record<string, boolean>;
     /** Record of dirty field paths */
     dirtyFields: Record<string, boolean>;
     /** Number of times form has been submitted */
     submitCount: number;
+    /** Error that occurred while loading async default values */
+    defaultValuesError: unknown;
+    /** Whether form has been submitted at least once */
+    isSubmitted: boolean;
+    /** Whether the last submission was successful */
+    isSubmitSuccessful: boolean;
 }
 /**
  * State of an individual field
@@ -94,6 +175,48 @@ export interface SetFocusOptions {
     /** Whether to select the text in the input */
     shouldSelect?: boolean;
 }
+/**
+ * Options for setValue()
+ */
+export interface SetValueOptions {
+    /** Trigger validation after setting value (default: false) */
+    shouldValidate?: boolean;
+    /** Mark field as dirty (default: true) */
+    shouldDirty?: boolean;
+    /** Mark field as touched (default: false) */
+    shouldTouch?: boolean;
+}
+/**
+ * Options for resetField()
+ * @template TValue - The type of the field value (inferred from field path)
+ */
+export interface ResetFieldOptions<TValue = unknown> {
+    /** Keep validation errors after reset */
+    keepError?: boolean;
+    /** Keep dirty state after reset */
+    keepDirty?: boolean;
+    /** Keep touched state after reset */
+    keepTouched?: boolean;
+    /** New default value (updates stored default) - typed to match field */
+    defaultValue?: TValue;
+}
+/**
+ * Options for unregister()
+ */
+export interface UnregisterOptions {
+    /** Keep the field value in form data */
+    keepValue?: boolean;
+    /** Keep validation errors */
+    keepError?: boolean;
+    /** Keep dirty state */
+    keepDirty?: boolean;
+    /** Keep touched state */
+    keepTouched?: boolean;
+    /** Keep the default value */
+    keepDefaultValue?: boolean;
+    /** Don't re-evaluate isValid */
+    keepIsValid?: boolean;
+}
 /**
  * Options for reset()
  */
@@ -110,36 +233,69 @@ export interface ResetOptions {
     keepDefaultValues?: boolean;
     /** Keep isSubmitting state after reset */
     keepIsSubmitting?: boolean;
+    /** Keep isSubmitSuccessful state after reset */
+    keepIsSubmitSuccessful?: boolean;
 }
 /**
  * Options for registering a field
+ * @template TValue - The type of the field value (inferred from field path)
  */
-export interface RegisterOptions {
+export interface RegisterOptions<TValue = unknown> {
     /** Use controlled mode (v-model) instead of uncontrolled (ref) */
     controlled?: boolean;
     /** Disable validation for this field */
     disabled?: boolean;
-    /** Custom validation function */
-    validate?: (value: unknown) => string | undefined | Promise<string | undefined>;
+    /**
+     * Custom validation function - receives the typed field value.
+     * Return an error message string to indicate validation failure,
+     * or undefined to indicate success.
+     *
+     * @example
+     * register('email', {
+     *   validate: (value) => {
+     *     // value is typed as string (inferred from schema)
+     *     if (!value.includes('@')) return 'Must be a valid email'
+     *   }
+     * })
+     */
+    validate?: (value: TValue) => string | undefined | Promise<string | undefined>;
     /** Debounce time in ms for async validation (default: 0 = no debounce) */
     validateDebounce?: number;
     /** Remove field data when unmounted (overrides global shouldUnregister option) */
     shouldUnregister?: boolean;
+    /** Dependent fields to re-validate when this field changes */
+    deps?: string[];
 }
 /**
- * Return value from register() for binding to inputs
+ * Return value from register() for binding to inputs.
+ * Use object spread to bind all properties to your input element.
+ *
+ * @template TValue - The type of the field value (inferred from field path)
+ *
+ * @example
+ * // Uncontrolled (default) - uses ref for DOM access
+ * <input v-bind="register('email')" />
+ *
+ * @example
+ * // Controlled - uses v-model via value ref
+ * const { value, ...rest } = register('email', { controlled: true })
+ * <input v-model="value" v-bind="rest" />
  */
-export interface RegisterReturn {
+export interface RegisterReturn<TValue = unknown> {
     /** Field name for form data */
     name: string;
-    /** Ref callback for uncontrolled inputs - accepts HTMLInputElement, HTMLSelectElement, HTMLTextAreaElement, or null */
-    ref: (el: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | null | unknown) => void;
+    /**
+     * Ref callback for uncontrolled inputs.
+     * Compatible with Vue's template ref system (v-bind spreads this onto elements).
+     * Internally handles HTMLInputElement, HTMLSelectElement, and HTMLTextAreaElement.
+     */
+    ref: (el: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | Element | ComponentPublicInstance | null, refs?: Record<string, unknown>) => void;
     /** Input handler (fires on every keystroke) */
     onInput: (e: Event) => void;
     /** Blur handler */
     onBlur: (e: Event) => void;
     /** Current value (for controlled mode) - only present when controlled: true */
-    value?: Ref<unknown>;
+    value?: Ref<TValue>;
 }
 /**
  * Field metadata for dynamic arrays
@@ -153,30 +309,79 @@ export interface FieldArrayItem {
     remove: () => void;
 }
 /**
- * API for managing dynamic field arrays
+ * Focus options for field array operations
  */
-export interface FieldArray {
+export interface FieldArrayFocusOptions {
+    /** Whether to focus after operation (default: true for append/prepend/insert) */
+    shouldFocus?: boolean;
+    /** Which item index to focus relative to added items (default: 0 = first added) */
+    focusIndex?: number;
+    /** Field name within the item to focus (e.g., 'name' for items.X.name) */
+    focusName?: string;
+}
+/**
+ * Rules for validating field arrays
+ */
+export interface FieldArrayRules<T = unknown> {
+    /** Minimum number of items required */
+    minLength?: {
+        value: number;
+        message: string;
+    };
+    /** Maximum number of items allowed */
+    maxLength?: {
+        value: number;
+        message: string;
+    };
+    /** Custom validation function - return error message or true if valid */
+    validate?: (items: T[]) => string | true | Promise<string | true>;
+}
+/**
+ * Options for configuring field arrays
+ */
+export interface FieldArrayOptions<T = unknown> {
+    /** Validation rules for the array itself */
+    rules?: FieldArrayRules<T>;
+}
+/**
+ * API for managing dynamic field arrays.
+ * All methods that accept values are typed to match the array item type.
+ *
+ * @template TItem - The type of items in the array (inferred from field path)
+ *
+ * @example
+ * interface Address { street: string; city: string }
+ * const addresses = fields('addresses') // FieldArray<Address>
+ * addresses.append({ street: '123 Main', city: 'NYC' }) // Typed!
+ */
+export interface FieldArray<TItem = unknown> {
     /** Current field items with metadata */
     value: FieldArrayItem[];
-    /** Append item to end of array */
-    append: (value: unknown) => void;
-    /** Prepend item to beginning of array */
-    prepend: (value: unknown) => void;
+    /** Append item(s) to end of array */
+    append: (value: TItem | TItem[], options?: FieldArrayFocusOptions) => void;
+    /** Prepend item(s) to beginning of array */
+    prepend: (value: TItem | TItem[], options?: FieldArrayFocusOptions) => void;
     /** Remove item at index */
     remove: (index: number) => void;
-    /** Insert item at index */
-    insert: (index: number, value: unknown) => void;
+    /** Insert item(s) at index */
+    insert: (index: number, value: TItem | TItem[], options?: FieldArrayFocusOptions) => void;
     /** Swap two items */
     swap: (indexA: number, indexB: number) => void;
     /** Move item from one index to another */
     move: (from: number, to: number) => void;
     /** Update item at index (preserves key/identity) */
-    update: (index: number, value: unknown) => void;
+    update: (index: number, value: TItem) => void;
+    /** Replace all items with new values */
+    replace: (values: TItem[]) => void;
 }
 /**
  * Async default values function type
  */
 export type AsyncDefaultValues<T> = () => Promise<Partial<T>>;
+/**
+ * Criteria mode for error collection
+ */
+export type CriteriaMode = 'firstError' | 'all';
 /**
  * Options for useForm composable
  */
@@ -191,23 +396,52 @@ export interface UseFormOptions<TSchema extends ZodType> {
     reValidateMode?: ValidationMode;
     /** Remove field data when unmounted (default: false) */
     shouldUnregister?: boolean;
+    /** Callback when async default values fail to load */
+    onDefaultValuesError?: (error: unknown) => void;
+    /** Focus first field with error on submit (default: true) */
+    shouldFocusError?: boolean;
+    /** How to collect validation errors: 'firstError' or 'all' (default: 'firstError') */
+    criteriaMode?: CriteriaMode;
+    /** Delay before displaying validation errors in milliseconds (default: 0 = no delay) */
+    delayError?: number;
+    /**
+     * External values to sync to form. Changes update formData without marking dirty.
+     * Useful for server-fetched data or parent component state.
+     */
+    values?: MaybeRef<Partial<InferSchema<TSchema>>>;
+    /**
+     * External/server errors to merge with validation errors.
+     * Useful for server-side validation errors.
+     */
+    errors?: MaybeRef<Partial<FieldErrors<InferSchema<TSchema>>>>;
 }
 /**
- * Return value from useForm composable
+ * Return value from useForm composable.
+ * Provides full type safety with autocomplete for field paths and typed values.
+ *
+ * @template TSchema - The Zod schema type for form validation
  */
 export interface UseFormReturn<TSchema extends ZodType> {
     /**
-     * Register an input field
+     * Register an input field for form management.
+     * Returns props to spread onto your input element.
+     *
      * @param name - Field path (e.g., 'email' or 'user.address.street')
-     * @param options - Registration options
+     * @param options - Registration options (validation, controlled mode, etc.)
+     * @returns Props to bind to the input element
+     *
+     * @example
+     * <input v-bind="register('email')" />
+     * <input v-bind="register('age', { validate: (v) => v >= 0 || 'Must be positive' })" />
      */
-    register: <TPath extends Path<InferSchema<TSchema>>>(name: TPath, options?: RegisterOptions) => RegisterReturn;
+    register: <TPath extends Path<InferSchema<TSchema>>>(name: TPath, options?: RegisterOptions<PathValue<InferSchema<TSchema>, TPath>>) => RegisterReturn<PathValue<InferSchema<TSchema>, TPath>>;
     /**
      * Unregister a field to clean up refs and options
      * Call this when a field is unmounted to prevent memory leaks
      * @param name - Field path to unregister
+     * @param options - Options for what state to preserve
      */
-    unregister: <TPath extends Path<InferSchema<TSchema>>>(name: TPath) => void;
+    unregister: <TPath extends Path<InferSchema<TSchema>>>(name: TPath, options?: UnregisterOptions) => void;
     /**
      * Handle form submission
      * @param onValid - Callback called with valid data
@@ -217,19 +451,29 @@ export interface UseFormReturn<TSchema extends ZodType> {
     /** Reactive form state */
     formState: ComputedRef<FormState<InferSchema<TSchema>>>;
     /**
-     * Manage dynamic field arrays
+     * Manage dynamic field arrays.
+     * Returns a typed API for adding, removing, and reordering array items.
+     *
      * @param name - Array field path
+     * @param options - Optional configuration including validation rules
+     * @returns Typed FieldArray API
+     *
+     * @example
+     * const addresses = fields('addresses')
+     * addresses.append({ street: '', city: '' }) // Typed to Address
      */
-    fields: <TPath extends Path<InferSchema<TSchema>>>(name: TPath) => FieldArray;
+    fields: <TPath extends Path<InferSchema<TSchema>>>(name: TPath, options?: FieldArrayOptions<ArrayElement<PathValue<InferSchema<TSchema>, TPath>>>) => FieldArray<ArrayElement<PathValue<InferSchema<TSchema>, TPath>>>;
     /**
      * Set field value programmatically
      * @param name - Field path
-     * @param value - New value
+     * @param value - New value (typed to match field)
+     * @param options - Options for validation/dirty/touched behavior
      */
-    setValue: <TPath extends Path<InferSchema<TSchema>>>(name: TPath, value: PathValue<InferSchema<TSchema>, TPath>) => void;
+    setValue: <TPath extends Path<InferSchema<TSchema>>>(name: TPath, value: PathValue<InferSchema<TSchema>, TPath>, options?: SetValueOptions) => void;
     /**
      * Get field value
      * @param name - Field path
+     * @returns The field value (typed) or undefined if not set
      */
     getValue: <TPath extends Path<InferSchema<TSchema>>>(name: TPath) => PathValue<InferSchema<TSchema>, TPath> | undefined;
     /**
@@ -238,6 +482,12 @@ export interface UseFormReturn<TSchema extends ZodType> {
      * @param options - Optional reset options
      */
     reset: (values?: Partial<InferSchema<TSchema>>, options?: ResetOptions) => void;
+    /**
+     * Reset an individual field to its default value
+     * @param name - Field path
+     * @param options - Options for what state to preserve (with typed defaultValue)
+     */
+    resetField: <TPath extends Path<InferSchema<TSchema>>>(name: TPath, options?: ResetFieldOptions<PathValue<InferSchema<TSchema>, TPath>>) => void;
     /**
      * Watch field value(s) reactively
      * @param name - Field path or array of paths (optional - watches all if not provided)
@@ -287,3 +537,21 @@ export interface UseFormReturn<TSchema extends ZodType> {
      */
     setFocus: <TPath extends Path<InferSchema<TSchema>>>(name: TPath, options?: SetFocusOptions) => void;
 }
+/**
+ * Type guard to check if an error value is a structured FieldError object.
+ * Use this to safely narrow FieldErrorValue when handling errors.
+ *
+ * @param error - The error value to check (can be string, FieldError, or undefined)
+ * @returns True if the error is a FieldError object with type and message
+ *
+ * @example
+ * const error = formState.value.errors.email
+ * if (isFieldError(error)) {
+ *   // error is FieldError - has .type, .message, and optional .types
+ *   console.log(`${error.type}: ${error.message}`)
+ * } else if (typeof error === 'string') {
+ *   // error is a simple string message
+ *   console.log(error)
+ * }
+ */
+export declare function isFieldError(error: FieldErrorValue | undefined | null): error is FieldError;

package/dist/utils/paths.d.ts

@@ -2,7 +2,7 @@
  * Get value from object using dot notation path
  * @example get({ user: { name: 'John' } }, 'user.name') => 'John'
  */
-export declare function get(obj: Record<string, unknown>, path: string): unknown;
+export declare function get(obj: unknown, path: string): unknown;
 /**
  * Set value in object using dot notation path
  * @example set({}, 'user.name', 'John') => { user: { name: 'John' } }