@vuehookform/core 0.4.6 → 0.5.0

package/README.md

@@ -84,13 +84,21 @@ const addresses = fields('addresses')
 
 <template>
   <div v-for="field in addresses.value" :key="field.key">
+    <!-- Option 1: Scoped methods (recommended) - type-safe, cleaner -->
+    <input v-bind="field.register('street')" />
+    <input v-bind="field.register('city')" />
+
+    <!-- Option 2: Manual path building -->
     <input v-bind="register(`addresses.${field.index}.street`)" />
+
     <button @click="field.remove()">Remove</button>
   </div>
   <button @click="addresses.append({ street: '', city: '' })">Add Address</button>
 </template>
 ```
 
+Field array items provide **scoped methods** (`field.register()`, `field.setValue()`, `field.watch()`, etc.) that automatically build the full path with type safety.
+
 ### Validation Modes
 
 ```typescript

package/dist/core/useFieldArray.d.ts

@@ -1,8 +1,23 @@
+import { ComputedRef } from 'vue';
 import { FormContext } from './formContext';
-import { FieldArray, FieldArrayOptions, Path } from '../types';
+import { FieldArray, FieldArrayOptions, Path, RegisterOptions, RegisterReturn, SetValueOptions, FieldState, ErrorOption } from '../types';
+/**
+ * Form methods required by field array for scoped item methods.
+ * Passed from useForm to enable type-safe field access within array items.
+ */
+export interface FieldArrayFormMethods {
+    register: (name: string, options?: RegisterOptions<unknown>) => RegisterReturn<unknown>;
+    setValue: (name: string, value: unknown, options?: SetValueOptions) => void;
+    getValues: (name: string) => unknown;
+    watch: (name: string) => ComputedRef<unknown>;
+    getFieldState: (name: string) => FieldState;
+    trigger: (name?: string | string[]) => Promise<boolean>;
+    clearErrors: (name?: string | string[]) => void;
+    setError: (name: string, error: ErrorOption) => void;
+}
 /**
  * Create field array management functions
  */
-export declare function createFieldArrayManager<FormValues>(ctx: FormContext<FormValues>, validate: (fieldPath?: string) => Promise<boolean>, setFocus: (name: string) => void): {
+export declare function createFieldArrayManager<FormValues>(ctx: FormContext<FormValues>, validate: (fieldPath?: string) => Promise<boolean>, setFocus: (name: string) => void, formMethods: FieldArrayFormMethods): {
     fields: <TPath extends Path<FormValues>>(name: TPath, options?: FieldArrayOptions) => FieldArray;
 };

package/dist/index.d.ts

@@ -17,8 +17,8 @@
 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 { useController, type UseControllerOptions, type UseControllerReturn, type ControllerFieldProps, type LooseControllerOptions, } 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 type { UseFormOptions, UseFormReturn, UseFormReturn as Control, LooseControl, 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';

package/dist/types.d.ts

@@ -363,15 +363,104 @@ export interface RegisterReturn<TValue = unknown> {
     disabled?: boolean;
 }
 /**
- * Field metadata for dynamic arrays
+ * Field metadata for dynamic arrays with scoped methods for type-safe field access.
+ *
+ * Scoped methods provide full type safety when accessing fields within array items,
+ * solving the type inference problem with dynamic paths like `items.${index}.name`.
+ *
+ * @template TItem - The type of items in the array (inferred from field path)
+ *
+ * @example Basic usage
+ * ```ts
+ * const items = fields('items')
+ * items.value.forEach((field) => {
+ *   field.register('name')           // RegisterReturn<string> - fully typed!
+ *   field.setValue('price', 25)      // Type-checked against TItem
+ *   field.watch('price')             // ComputedRef<number>
+ * })
+ * ```
+ *
+ * @example In template with v-for
+ * ```vue
+ * <div v-for="field in items.value" :key="field.key">
+ *   <input v-bind="field.register('name')" />
+ *   <span v-if="field.getFieldState('name').error">
+ *     {{ field.getFieldState('name').error }}
+ *   </span>
+ * </div>
+ * ```
  */
-export interface FieldArrayItem {
+export interface FieldArrayItem<TItem = unknown> {
     /** Stable key for v-for */
     key: string;
     /** Current index in array */
     index: number;
     /** Remove this item */
     remove: () => void;
+    /**
+     * Register a field within this array item.
+     * Automatically builds the full path (e.g., 'items.0.name').
+     *
+     * @param name - Field path relative to the item (e.g., 'name', 'address.city')
+     * @param options - Registration options (validation, controlled mode, etc.)
+     * @returns Props to bind to the input element
+     *
+     * @example
+     * ```vue
+     * <input v-bind="field.register('name')" />
+     * ```
+     */
+    register: <TPath extends Path<TItem>>(name: TPath, options?: RegisterOptions<PathValue<TItem, TPath>>) => RegisterReturn<PathValue<TItem, TPath>>;
+    /**
+     * Set value for a field within this array item.
+     *
+     * @param name - Field path relative to the item
+     * @param value - New value (typed based on path)
+     * @param options - Control side effects (validation, dirty, touched)
+     */
+    setValue: <TPath extends Path<TItem>>(name: TPath, value: PathValue<TItem, TPath>, options?: SetValueOptions) => void;
+    /**
+     * Get current value of a field within this array item.
+     *
+     * @param name - Field path relative to the item
+     * @returns The field's current value
+     */
+    getValue: <TPath extends Path<TItem>>(name: TPath) => PathValue<TItem, TPath>;
+    /**
+     * Watch a field within this array item reactively.
+     *
+     * @param name - Field path relative to the item
+     * @returns ComputedRef that updates when the field changes
+     */
+    watch: <TPath extends Path<TItem>>(name: TPath) => ComputedRef<PathValue<TItem, TPath>>;
+    /**
+     * Get the state of a field within this array item.
+     * Note: Returns a snapshot, not reactive. Use watch() or formState for reactive access.
+     *
+     * @param name - Field path relative to the item
+     * @returns Field state with isDirty, isTouched, invalid, error
+     */
+    getFieldState: <TPath extends Path<TItem>>(name: TPath) => FieldState;
+    /**
+     * Trigger validation for fields within this array item.
+     *
+     * @param name - Optional field path(s) relative to the item. Validates entire item if omitted.
+     * @returns Promise resolving to true if valid
+     */
+    trigger: <TPath extends Path<TItem>>(name?: TPath | TPath[]) => Promise<boolean>;
+    /**
+     * Clear errors for fields within this array item.
+     *
+     * @param name - Optional field path(s) relative to the item. Clears all item errors if omitted.
+     */
+    clearErrors: <TPath extends Path<TItem>>(name?: TPath | TPath[]) => void;
+    /**
+     * Set an error for a field within this array item.
+     *
+     * @param name - Field path relative to the item
+     * @param error - Error option with message
+     */
+    setError: <TPath extends Path<TItem>>(name: TPath, error: ErrorOption) => void;
 }
 /**
  * Focus options for field array operations
@@ -438,7 +527,7 @@ export interface FieldArrayOptions<T = unknown> {
  */
 export interface FieldArray<TItem = unknown> {
     /** Current field items with metadata. Reactive - updates when array methods are called. */
-    value: FieldArrayItem[];
+    value: FieldArrayItem<TItem>[];
     /** Append item(s) to end of array. Returns false if maxLength exceeded. */
     append: (value: TItem | TItem[], options?: FieldArrayFocusOptions) => boolean;
     /** Prepend item(s) to beginning of array. Returns false if maxLength exceeded. */
@@ -693,6 +782,20 @@ export interface UseFormOptions<TSchema extends ZodType> {
      */
     shouldUseNativeValidation?: boolean;
 }
+/**
+ * Loose control type for reusable components where schema type is unknown.
+ * Use this when building form field components that accept any form control.
+ *
+ * @example
+ * ```ts
+ * // Reusable field component
+ * function FormInput(props: { name: string; control: LooseControl }) {
+ *   const { field } = useController(props)  // No cast needed
+ *   return <input v-bind="field" />
+ * }
+ * ```
+ */
+export type LooseControl = UseFormReturn<ZodType<any>>;
 /**
  * Return value from useForm composable.
  * Provides full type safety with autocomplete for field paths and typed values.
@@ -712,14 +815,22 @@ export interface UseFormReturn<TSchema extends ZodType> {
      * <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<PathValue<InferSchema<TSchema>, TPath>>) => RegisterReturn<PathValue<InferSchema<TSchema>, TPath>>;
+    register: {
+        <TPath extends Path<InferSchema<TSchema>>>(name: TPath, options?: RegisterOptions<PathValue<InferSchema<TSchema>, TPath>>): RegisterReturn<PathValue<InferSchema<TSchema>, TPath>>;
+        /** Loose overload for dynamic paths - returns unknown-typed value */
+        (name: string, options?: RegisterOptions<unknown>): RegisterReturn<unknown>;
+    };
     /**
      * 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, options?: UnregisterOptions) => void;
+    unregister: {
+        <TPath extends Path<InferSchema<TSchema>>>(name: TPath, options?: UnregisterOptions): void;
+        /** Loose overload for dynamic paths */
+        (name: string, options?: UnregisterOptions): void;
+    };
     /**
      * Handle form submission
      * @param onValid - Callback called with valid data
@@ -747,7 +858,11 @@ export interface UseFormReturn<TSchema extends ZodType> {
      * @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>, options?: SetValueOptions) => void;
+    setValue: {
+        <TPath extends Path<InferSchema<TSchema>>>(name: TPath, value: PathValue<InferSchema<TSchema>, TPath>, options?: SetValueOptions): void;
+        /** Loose overload for dynamic paths */
+        (name: string, value: unknown, options?: SetValueOptions): void;
+    };
     /**
      * Reset form to default values
      * @param values - Optional new default values
@@ -759,7 +874,11 @@ export interface UseFormReturn<TSchema extends ZodType> {
      * @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;
+    resetField: {
+        <TPath extends Path<InferSchema<TSchema>>>(name: TPath, options?: ResetFieldOptions<PathValue<InferSchema<TSchema>, TPath>>): void;
+        /** Loose overload for dynamic paths */
+        (name: string, options?: ResetFieldOptions<unknown>): void;
+    };
     /**
      * Watch field value(s) reactively
      * @overload Watch all form values
@@ -770,23 +889,39 @@ export interface UseFormReturn<TSchema extends ZodType> {
         (): ComputedRef<InferSchema<TSchema>>;
         <TPath extends Path<InferSchema<TSchema>>>(name: TPath): ComputedRef<PathValue<InferSchema<TSchema>, TPath>>;
         <TPath extends Path<InferSchema<TSchema>>>(names: TPath[]): ComputedRef<Partial<InferSchema<TSchema>>>;
+        /** Loose overload for dynamic paths - returns unknown */
+        (name: string): ComputedRef<unknown>;
+        /** Loose overload for dynamic path arrays */
+        (names: string[]): ComputedRef<Record<string, unknown>>;
     };
     /**
      * Manually trigger validation
      * @param name - Optional field path (validates all if not provided)
      */
-    validate: <TPath extends Path<InferSchema<TSchema>>>(name?: TPath) => Promise<boolean>;
+    validate: {
+        <TPath extends Path<InferSchema<TSchema>>>(name?: TPath): Promise<boolean>;
+        /** Loose overload for dynamic paths */
+        (name?: string): Promise<boolean>;
+    };
     /**
      * Clear errors for specified fields or all errors
      * @param name - Optional field path or array of paths
      */
-    clearErrors: <TPath extends Path<InferSchema<TSchema>>>(name?: TPath | TPath[] | 'root' | `root.${string}`) => void;
+    clearErrors: {
+        <TPath extends Path<InferSchema<TSchema>>>(name?: TPath | TPath[] | 'root' | `root.${string}`): void;
+        /** Loose overload for dynamic paths */
+        (name?: string | string[]): void;
+    };
     /**
      * Set an error for a specific field
      * @param name - Field path or root error
      * @param error - Error option with message
      */
-    setError: <TPath extends Path<InferSchema<TSchema>>>(name: TPath | 'root' | `root.${string}`, error: ErrorOption) => void;
+    setError: {
+        <TPath extends Path<InferSchema<TSchema>>>(name: TPath | 'root' | `root.${string}`, error: ErrorOption): void;
+        /** Loose overload for dynamic paths */
+        (name: string, error: ErrorOption): void;
+    };
     /**
      * Set multiple errors at once. Useful for server-side validation errors
      * or bulk error handling scenarios.
@@ -822,7 +957,11 @@ export interface UseFormReturn<TSchema extends ZodType> {
      *   focusField('email')
      * }
      */
-    hasErrors: <TPath extends Path<InferSchema<TSchema>>>(fieldPath?: TPath | 'root' | `root.${string}`) => boolean;
+    hasErrors: {
+        <TPath extends Path<InferSchema<TSchema>>>(fieldPath?: TPath | 'root' | `root.${string}`): boolean;
+        /** Loose overload for dynamic paths */
+        (fieldPath?: string): boolean;
+    };
     /**
      * Get validation errors for the form or a specific field
      *
@@ -849,24 +988,40 @@ export interface UseFormReturn<TSchema extends ZodType> {
         (): InferSchema<TSchema>;
         <TPath extends Path<InferSchema<TSchema>>>(name: TPath): PathValue<InferSchema<TSchema>, TPath>;
         <TPath extends Path<InferSchema<TSchema>>>(names: TPath[]): Partial<InferSchema<TSchema>>;
+        /** Loose overload for dynamic paths - returns unknown */
+        (name: string): unknown;
+        /** Loose overload for dynamic path arrays */
+        (names: string[]): Record<string, unknown>;
     };
     /**
      * Get the state of an individual field
      * @param name - Field path
      */
-    getFieldState: <TPath extends Path<InferSchema<TSchema>>>(name: TPath) => FieldState;
+    getFieldState: {
+        <TPath extends Path<InferSchema<TSchema>>>(name: TPath): FieldState;
+        /** Loose overload for dynamic paths */
+        (name: string): FieldState;
+    };
     /**
      * 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[], options?: TriggerOptions) => Promise<boolean>;
+    trigger: {
+        <TPath extends Path<InferSchema<TSchema>>>(name?: TPath | TPath[], options?: TriggerOptions): Promise<boolean>;
+        /** Loose overload for dynamic paths */
+        (name?: string | string[], 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;
+    setFocus: {
+        <TPath extends Path<InferSchema<TSchema>>>(name: TPath, options?: SetFocusOptions): void;
+        /** Loose overload for dynamic paths */
+        (name: string, options?: SetFocusOptions): void;
+    };
     /**
      * Form configuration options (mode, reValidateMode).
      * Useful for composables like useController that need to respect validation modes.

package/dist/useController.d.ts

@@ -1,6 +1,6 @@
 import { ComputedRef, Ref } from 'vue';
 import { ZodType } from 'zod';
-import { UseFormReturn, Path, PathValue, InferSchema, FieldState } from './types';
+import { UseFormReturn, Path, PathValue, InferSchema, FieldState, LooseControl } from './types';
 /**
  * Options for useController composable
  */
@@ -36,6 +36,27 @@ export interface UseControllerReturn<TValue> {
     /** Current field state (errors, dirty, touched) */
     fieldState: ComputedRef<FieldState>;
 }
+/**
+ * Loose options for useController when schema type is unknown.
+ * Use this for building reusable field components that work with any form.
+ *
+ * @example
+ * ```ts
+ * // Reusable field component
+ * function FormInput(props: { name: string; control: LooseControl }) {
+ *   const { field, fieldState } = useController(props)
+ *   // field.value is unknown, fieldState is reactive
+ * }
+ * ```
+ */
+export interface LooseControllerOptions {
+    /** Field name/path as a string */
+    name: string;
+    /** Form control from useForm (uses context if not provided) */
+    control?: LooseControl;
+    /** Default value for the field */
+    defaultValue?: unknown;
+}
 /**
  * Hook for controlled components that need fine-grained control over field state
  *
@@ -59,5 +80,14 @@ export interface UseControllerReturn<TValue> {
  * // />
  * // <span v-if="fieldState.value.error">{{ fieldState.value.error }}</span>
  * ```
+ *
+ * @example Reusable component with loose typing
+ * ```ts
+ * // FormInput.vue
+ * const props = defineProps<{ name: string; control: LooseControl }>()
+ * const { field, fieldState } = useController(props)
+ * // No 'as never' cast needed!
+ * ```
  */
+export declare function useController(options: LooseControllerOptions): UseControllerReturn<unknown>;
 export declare function useController<TSchema extends ZodType, TPath extends Path<InferSchema<TSchema>>>(options: UseControllerOptions<TSchema, TPath>): UseControllerReturn<PathValue<InferSchema<TSchema>, TPath>>;

package/dist/vuehookform.cjs

@@ -839,6 +839,7 @@ function createFieldRegistration(ctx, validate) {
 		let handlers = ctx.fieldHandlers.get(name);
 		if (!handlers) {
 			const runCustomValidation = async (fieldName, value, requestId, resetGenAtStart) => {
+				if (!ctx.fieldRefs.has(fieldName)) return;
 				const fieldOpts = ctx.fieldOptions.get(fieldName);
 				if (!fieldOpts?.validate || fieldOpts.disabled) return;
 				const error = await fieldOpts.validate(value);
@@ -1009,7 +1010,7 @@ function createFieldRegistration(ctx, validate) {
 		unregister
 	};
 }
-function createFieldArrayManager(ctx, validate, setFocus) {
+function createFieldArrayManager(ctx, validate, setFocus, formMethods) {
 	function fields(name, options) {
 		if (__DEV__) {
 			const syntaxError = validatePathSyntax(name);
@@ -1053,16 +1054,76 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 				if (item) indexCache.set(item.key, i);
 			}
 		};
-		const createItem = (key) => ({
-			key,
-			get index() {
-				return indexCache.get(key) ?? -1;
-			},
-			remove() {
-				const currentIndex = indexCache.get(key) ?? -1;
-				if (currentIndex !== -1) removeAt(currentIndex);
-			}
-		});
+		const buildPath = (index, subPath) => {
+			return subPath ? `${name}.${index}.${subPath}` : `${name}.${index}`;
+		};
+		const createScopedMethods = (indexGetter) => {
+			return {
+				register: (subPath, options$1) => formMethods.register(buildPath(indexGetter(), subPath), options$1),
+				setValue: (subPath, value, options$1) => formMethods.setValue(buildPath(indexGetter(), subPath), value, options$1),
+				getValue: (subPath) => formMethods.getValues(buildPath(indexGetter(), subPath)),
+				watch: (subPath) => formMethods.watch(buildPath(indexGetter(), subPath)),
+				getFieldState: (subPath) => formMethods.getFieldState(buildPath(indexGetter(), subPath)),
+				trigger: (subPath) => {
+					const index = indexGetter();
+					if (!subPath) return formMethods.trigger(buildPath(index));
+					if (Array.isArray(subPath)) return formMethods.trigger(subPath.map((p) => buildPath(index, p)));
+					return formMethods.trigger(buildPath(index, subPath));
+				},
+				clearErrors: (subPath) => {
+					const index = indexGetter();
+					if (!subPath) {
+						formMethods.clearErrors(buildPath(index));
+						return;
+					}
+					if (Array.isArray(subPath)) {
+						formMethods.clearErrors(subPath.map((p) => buildPath(index, p)));
+						return;
+					}
+					formMethods.clearErrors(buildPath(index, subPath));
+				},
+				setError: (subPath, error) => formMethods.setError(buildPath(indexGetter(), subPath), error)
+			};
+		};
+		const createItem = (key) => {
+			const getIndex = () => indexCache.get(key) ?? -1;
+			let scoped = null;
+			const getScoped = () => scoped ??= createScopedMethods(getIndex);
+			return {
+				key,
+				get index() {
+					return getIndex();
+				},
+				remove() {
+					const currentIndex = getIndex();
+					if (currentIndex !== -1) removeAt(currentIndex);
+				},
+				get register() {
+					return getScoped().register;
+				},
+				get setValue() {
+					return getScoped().setValue;
+				},
+				get getValue() {
+					return getScoped().getValue;
+				},
+				get watch() {
+					return getScoped().watch;
+				},
+				get getFieldState() {
+					return getScoped().getFieldState;
+				},
+				get trigger() {
+					return getScoped().trigger;
+				},
+				get clearErrors() {
+					return getScoped().clearErrors;
+				},
+				get setError() {
+					return getScoped().setError;
+				}
+			};
+		};
 		if (fa.items.value.length === 0 && fa.values.length > 0) {
 			fa.items.value = fa.values.map(() => createItem(generateId()));
 			rebuildIndexCache();
@@ -1071,7 +1132,7 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 			if (!focusOptions?.shouldFocus) return;
 			await (0, vue.nextTick)();
 			const focusItemOffset = focusOptions?.focusIndex ?? 0;
-			let fieldPath = `${name}.${baseIndex + Math.min(focusItemOffset, addedCount - 1)}`;
+			let fieldPath = `${name}.${baseIndex + Math.max(0, Math.min(focusItemOffset, addedCount - 1))}`;
 			if (focusOptions?.focusName) fieldPath = `${fieldPath}.${focusOptions.focusName}`;
 			setFocus(fieldPath);
 		};
@@ -1242,13 +1303,10 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 			set(ctx.formData, name, newValues);
 			const newItems = [...fa.items.value];
 			const itemA = newItems[indexA];
-			const itemB = newItems[indexB];
-			if (itemA && itemB) {
-				newItems[indexA] = itemB;
-				newItems[indexB] = itemA;
-				fa.items.value = newItems;
-				swapInCache(indexA, indexB);
-			}
+			newItems[indexA] = newItems[indexB];
+			newItems[indexB] = itemA;
+			fa.items.value = newItems;
+			swapInCache(indexA, indexB);
 			updateFieldDirtyState(ctx.dirtyFields, ctx.defaultValues, ctx.defaultValueHashes, name, get(ctx.formData, name));
 			validateIfNeeded();
 			return true;
@@ -1268,16 +1326,14 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 			}
 			const newItems = [...fa.items.value];
 			const [removedItem] = newItems.splice(from, 1);
-			if (removedItem) {
-				newItems.splice(to, 0, removedItem);
-				fa.items.value = newItems;
-				const minIdx = Math.min(from, to);
-				const maxIdx = Math.max(from, to);
-				const items = fa.items.value;
-				for (let i = minIdx; i <= maxIdx; i++) {
-					const item = items[i];
-					if (item) indexCache.set(item.key, i);
-				}
+			newItems.splice(to, 0, removedItem);
+			fa.items.value = newItems;
+			const minIdx = Math.min(from, to);
+			const maxIdx = Math.max(from, to);
+			const items = fa.items.value;
+			for (let i = minIdx; i <= maxIdx; i++) {
+				const item = items[i];
+				if (item) indexCache.set(item.key, i);
 			}
 			updateFieldDirtyState(ctx.dirtyFields, ctx.defaultValues, ctx.defaultValueHashes, name, get(ctx.formData, name));
 			validateIfNeeded();
@@ -1384,8 +1440,6 @@ function useForm(options) {
 		el.focus();
 		if (focusOptions?.shouldSelect && el instanceof HTMLInputElement && typeof el.select === "function") el.select();
 	}
-	const setFocusWrapper = (name) => setFocus(name);
-	const { fields } = createFieldArrayManager(ctx, validate, setFocusWrapper);
 	let lastSyncTime = 0;
 	const SYNC_DEBOUNCE_MS = 16;
 	function syncWithDebounce() {
@@ -1529,6 +1583,7 @@ function useForm(options) {
 		Object.assign(ctx.formData, newValues);
 		if (!opts.keepErrors) {
 			ctx.errors.value = {};
+			ctx.externalErrors.value = {};
 			ctx.persistentErrorFields.clear();
 		}
 		if (!opts.keepTouched) ctx.touchedFields.value = {};
@@ -1629,7 +1684,8 @@ function useForm(options) {
 		for (const field of fieldsToClean) {
 			clearFieldErrors(ctx.errors, field);
 			clearFieldErrors(ctx.externalErrors, field);
-			ctx.persistentErrorFields.delete(field);
+			const prefix = `${field}.`;
+			for (const persistentField of ctx.persistentErrorFields) if (persistentField === field || persistentField.startsWith(prefix)) ctx.persistentErrorFields.delete(persistentField);
 		}
 	}
 	function setError(name, error) {
@@ -1723,6 +1779,17 @@ function useForm(options) {
 		}
 		return await validate(name);
 	}
+	const setFocusWrapper = (name) => setFocus(name);
+	const { fields } = createFieldArrayManager(ctx, validate, setFocusWrapper, {
+		register: (name, options$1) => register(name, options$1),
+		setValue: (name, value, options$1) => setValue(name, value, options$1),
+		getValues: (name) => getValues(name),
+		watch: (name) => watch$1(name),
+		getFieldState: (name) => getFieldState(name),
+		trigger: (name) => trigger(name),
+		clearErrors: (name) => clearErrors(name),
+		setError: (name, error) => setError(name, error)
+	});
 	return {
 		register,
 		unregister,

package/dist/vuehookform.js

@@ -837,6 +837,7 @@ function createFieldRegistration(ctx, validate) {
 		let handlers = ctx.fieldHandlers.get(name);
 		if (!handlers) {
 			const runCustomValidation = async (fieldName, value, requestId, resetGenAtStart) => {
+				if (!ctx.fieldRefs.has(fieldName)) return;
 				const fieldOpts = ctx.fieldOptions.get(fieldName);
 				if (!fieldOpts?.validate || fieldOpts.disabled) return;
 				const error = await fieldOpts.validate(value);
@@ -1007,7 +1008,7 @@ function createFieldRegistration(ctx, validate) {
 		unregister
 	};
 }
-function createFieldArrayManager(ctx, validate, setFocus) {
+function createFieldArrayManager(ctx, validate, setFocus, formMethods) {
 	function fields(name, options) {
 		if (__DEV__) {
 			const syntaxError = validatePathSyntax(name);
@@ -1051,16 +1052,76 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 				if (item) indexCache.set(item.key, i);
 			}
 		};
-		const createItem = (key) => ({
-			key,
-			get index() {
-				return indexCache.get(key) ?? -1;
-			},
-			remove() {
-				const currentIndex = indexCache.get(key) ?? -1;
-				if (currentIndex !== -1) removeAt(currentIndex);
-			}
-		});
+		const buildPath = (index, subPath) => {
+			return subPath ? `${name}.${index}.${subPath}` : `${name}.${index}`;
+		};
+		const createScopedMethods = (indexGetter) => {
+			return {
+				register: (subPath, options$1) => formMethods.register(buildPath(indexGetter(), subPath), options$1),
+				setValue: (subPath, value, options$1) => formMethods.setValue(buildPath(indexGetter(), subPath), value, options$1),
+				getValue: (subPath) => formMethods.getValues(buildPath(indexGetter(), subPath)),
+				watch: (subPath) => formMethods.watch(buildPath(indexGetter(), subPath)),
+				getFieldState: (subPath) => formMethods.getFieldState(buildPath(indexGetter(), subPath)),
+				trigger: (subPath) => {
+					const index = indexGetter();
+					if (!subPath) return formMethods.trigger(buildPath(index));
+					if (Array.isArray(subPath)) return formMethods.trigger(subPath.map((p) => buildPath(index, p)));
+					return formMethods.trigger(buildPath(index, subPath));
+				},
+				clearErrors: (subPath) => {
+					const index = indexGetter();
+					if (!subPath) {
+						formMethods.clearErrors(buildPath(index));
+						return;
+					}
+					if (Array.isArray(subPath)) {
+						formMethods.clearErrors(subPath.map((p) => buildPath(index, p)));
+						return;
+					}
+					formMethods.clearErrors(buildPath(index, subPath));
+				},
+				setError: (subPath, error) => formMethods.setError(buildPath(indexGetter(), subPath), error)
+			};
+		};
+		const createItem = (key) => {
+			const getIndex = () => indexCache.get(key) ?? -1;
+			let scoped = null;
+			const getScoped = () => scoped ??= createScopedMethods(getIndex);
+			return {
+				key,
+				get index() {
+					return getIndex();
+				},
+				remove() {
+					const currentIndex = getIndex();
+					if (currentIndex !== -1) removeAt(currentIndex);
+				},
+				get register() {
+					return getScoped().register;
+				},
+				get setValue() {
+					return getScoped().setValue;
+				},
+				get getValue() {
+					return getScoped().getValue;
+				},
+				get watch() {
+					return getScoped().watch;
+				},
+				get getFieldState() {
+					return getScoped().getFieldState;
+				},
+				get trigger() {
+					return getScoped().trigger;
+				},
+				get clearErrors() {
+					return getScoped().clearErrors;
+				},
+				get setError() {
+					return getScoped().setError;
+				}
+			};
+		};
 		if (fa.items.value.length === 0 && fa.values.length > 0) {
 			fa.items.value = fa.values.map(() => createItem(generateId()));
 			rebuildIndexCache();
@@ -1069,7 +1130,7 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 			if (!focusOptions?.shouldFocus) return;
 			await nextTick();
 			const focusItemOffset = focusOptions?.focusIndex ?? 0;
-			let fieldPath = `${name}.${baseIndex + Math.min(focusItemOffset, addedCount - 1)}`;
+			let fieldPath = `${name}.${baseIndex + Math.max(0, Math.min(focusItemOffset, addedCount - 1))}`;
 			if (focusOptions?.focusName) fieldPath = `${fieldPath}.${focusOptions.focusName}`;
 			setFocus(fieldPath);
 		};
@@ -1240,13 +1301,10 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 			set(ctx.formData, name, newValues);
 			const newItems = [...fa.items.value];
 			const itemA = newItems[indexA];
-			const itemB = newItems[indexB];
-			if (itemA && itemB) {
-				newItems[indexA] = itemB;
-				newItems[indexB] = itemA;
-				fa.items.value = newItems;
-				swapInCache(indexA, indexB);
-			}
+			newItems[indexA] = newItems[indexB];
+			newItems[indexB] = itemA;
+			fa.items.value = newItems;
+			swapInCache(indexA, indexB);
 			updateFieldDirtyState(ctx.dirtyFields, ctx.defaultValues, ctx.defaultValueHashes, name, get(ctx.formData, name));
 			validateIfNeeded();
 			return true;
@@ -1266,16 +1324,14 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 			}
 			const newItems = [...fa.items.value];
 			const [removedItem] = newItems.splice(from, 1);
-			if (removedItem) {
-				newItems.splice(to, 0, removedItem);
-				fa.items.value = newItems;
-				const minIdx = Math.min(from, to);
-				const maxIdx = Math.max(from, to);
-				const items = fa.items.value;
-				for (let i = minIdx; i <= maxIdx; i++) {
-					const item = items[i];
-					if (item) indexCache.set(item.key, i);
-				}
+			newItems.splice(to, 0, removedItem);
+			fa.items.value = newItems;
+			const minIdx = Math.min(from, to);
+			const maxIdx = Math.max(from, to);
+			const items = fa.items.value;
+			for (let i = minIdx; i <= maxIdx; i++) {
+				const item = items[i];
+				if (item) indexCache.set(item.key, i);
 			}
 			updateFieldDirtyState(ctx.dirtyFields, ctx.defaultValues, ctx.defaultValueHashes, name, get(ctx.formData, name));
 			validateIfNeeded();
@@ -1382,8 +1438,6 @@ function useForm(options) {
 		el.focus();
 		if (focusOptions?.shouldSelect && el instanceof HTMLInputElement && typeof el.select === "function") el.select();
 	}
-	const setFocusWrapper = (name) => setFocus(name);
-	const { fields } = createFieldArrayManager(ctx, validate, setFocusWrapper);
 	let lastSyncTime = 0;
 	const SYNC_DEBOUNCE_MS = 16;
 	function syncWithDebounce() {
@@ -1527,6 +1581,7 @@ function useForm(options) {
 		Object.assign(ctx.formData, newValues);
 		if (!opts.keepErrors) {
 			ctx.errors.value = {};
+			ctx.externalErrors.value = {};
 			ctx.persistentErrorFields.clear();
 		}
 		if (!opts.keepTouched) ctx.touchedFields.value = {};
@@ -1627,7 +1682,8 @@ function useForm(options) {
 		for (const field of fieldsToClean) {
 			clearFieldErrors(ctx.errors, field);
 			clearFieldErrors(ctx.externalErrors, field);
-			ctx.persistentErrorFields.delete(field);
+			const prefix = `${field}.`;
+			for (const persistentField of ctx.persistentErrorFields) if (persistentField === field || persistentField.startsWith(prefix)) ctx.persistentErrorFields.delete(persistentField);
 		}
 	}
 	function setError(name, error) {
@@ -1721,6 +1777,17 @@ function useForm(options) {
 		}
 		return await validate(name);
 	}
+	const setFocusWrapper = (name) => setFocus(name);
+	const { fields } = createFieldArrayManager(ctx, validate, setFocusWrapper, {
+		register: (name, options$1) => register(name, options$1),
+		setValue: (name, value, options$1) => setValue(name, value, options$1),
+		getValues: (name) => getValues(name),
+		watch: (name) => watch$1(name),
+		getFieldState: (name) => getFieldState(name),
+		trigger: (name) => trigger(name),
+		clearErrors: (name) => clearErrors(name),
+		setError: (name, error) => setError(name, error)
+	});
 	return {
 		register,
 		unregister,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vuehookform/core",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "description": "TypeScript-first form library for Vue 3, inspired by React Hook Form. Form-level state management with Zod validation.",
   "type": "module",
   "workspaces": [