@vuehookform/core 0.5.0 → 0.7.0

package/dist/core/useFieldRegistration.d.ts

@@ -1,9 +1,16 @@
 import { FormContext } from './formContext';
-import { RegisterOptions, RegisterReturn, UnregisterOptions, Path } from '../types';
+import { RegisterOptions, RegisterReturn, UnregisterOptions, SetValueOptions, Path } from '../types';
+/**
+ * Helpers object for onChange callbacks.
+ * Populated after useForm's setValue is defined (mutable reference pattern).
+ */
+export interface OnChangeHelpers {
+    setValue: (name: string, value: unknown, options?: SetValueOptions) => void;
+}
 /**
  * Create field registration functions
  */
-export declare function createFieldRegistration<FormValues>(ctx: FormContext<FormValues>, validate: (fieldPath?: string) => Promise<boolean>): {
+export declare function createFieldRegistration<FormValues>(ctx: FormContext<FormValues>, validate: (fieldPath?: string) => Promise<boolean>, onChangeHelpers?: OnChangeHelpers): {
     register: <TPath extends Path<FormValues>>(name: TPath, registerOptions?: RegisterOptions) => RegisterReturn;
     unregister: <TPath extends Path<FormValues>>(name: TPath, options?: UnregisterOptions) => void;
 };

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export { provideForm, useFormContext, FormContextKey } from './context';
 export { useWatch, type UseWatchOptions } from './useWatch';
 export { useController, type UseControllerOptions, type UseControllerReturn, type ControllerFieldProps, type LooseControllerOptions, } from './useController';
 export { useFormState, type UseFormStateOptions, type FormStateKey } from './useFormState';
+export { useFieldError, type UseFieldErrorOptions, type LooseFieldErrorOptions, } from './useFieldError';
 export { isFieldError } 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

@@ -186,6 +186,10 @@ export interface FormState<T> {
     isSubmitSuccessful: boolean;
     /** Whether the form is disabled */
     disabled: boolean;
+    /** Whether form values match default values (opposite of isDirty) */
+    isPristine: boolean;
+    /** Whether the form can be submitted (isValid && !isSubmitting && !isLoading && !disabled) */
+    canSubmit: boolean;
 }
 /**
  * State of an individual field
@@ -328,6 +332,26 @@ export interface RegisterOptions<TValue = unknown> {
     shouldUnregister?: boolean;
     /** Dependent fields to re-validate when this field changes */
     deps?: string[];
+    /**
+     * Called after the field value changes via user input.
+     * Use for side effects like resetting dependent fields.
+     * Does NOT fire on programmatic setValue() calls.
+     *
+     * @param value - The new field value (typed based on field path)
+     * @param helpers - Helper functions for triggering side effects
+     *
+     * @example Reset dependent field when parent changes
+     * ```ts
+     * register('country', {
+     *   onChange: (country, { setValue }) => {
+     *     setValue('province', '')  // Reset province when country changes
+     *   },
+     * })
+     * ```
+     */
+    onChange?: (value: TValue, helpers: {
+        setValue: (name: string, value: unknown, options?: SetValueOptions) => void;
+    }) => void;
 }
 /**
  * Return value from register() for binding to inputs.

package/dist/useFieldError.d.ts

@@ -0,0 +1,54 @@
+import { ComputedRef } from 'vue';
+import { ZodType } from 'zod';
+import { UseFormReturn, Path, InferSchema, LooseControl } from './types';
+/**
+ * Options for useFieldError composable
+ */
+export interface UseFieldErrorOptions<TSchema extends ZodType, TPath extends Path<InferSchema<TSchema>>> {
+    /** Field path to get the error for */
+    name: TPath;
+    /** Form control from useForm (uses context if not provided) */
+    control?: UseFormReturn<TSchema>;
+}
+/**
+ * Loose options for useFieldError when schema type is unknown.
+ */
+export interface LooseFieldErrorOptions {
+    /** Field path as a string */
+    name: string;
+    /** Form control from useForm (uses context if not provided) */
+    control?: LooseControl;
+}
+/**
+ * Get a reactive error message for a single field.
+ *
+ * Returns a ComputedRef that automatically updates when the field's
+ * error state changes. Normalizes both string errors and structured
+ * FieldError objects to a plain string message.
+ *
+ * For field array paths with per-item errors (not a single array-level error),
+ * returns `undefined`. Use `formState.value.errors` directly for item-level errors.
+ *
+ * @example Basic usage with context
+ * ```vue
+ * <script setup>
+ * const emailError = useFieldError({ name: 'email' })
+ * </script>
+ * <template>
+ *   <span v-if="emailError" class="error">{{ emailError }}</span>
+ * </template>
+ * ```
+ *
+ * @example With explicit control
+ * ```ts
+ * const form = useForm({ schema })
+ * const emailError = useFieldError({ name: 'email', control: form })
+ * ```
+ *
+ * @example Nested path
+ * ```ts
+ * const cityError = useFieldError({ name: 'user.address.city' })
+ * ```
+ */
+export declare function useFieldError(options: LooseFieldErrorOptions): ComputedRef<string | undefined>;
+export declare function useFieldError<TSchema extends ZodType, TPath extends Path<InferSchema<TSchema>>>(options: UseFieldErrorOptions<TSchema, TPath>): ComputedRef<string | undefined>;

package/dist/useFormState.d.ts

@@ -23,17 +23,16 @@ export interface UseFormStateOptions<TSchema extends ZodType> {
  * @example
  * ```ts
  * // Subscribe to all form state
- * const formState = useFormState({})
+ * const state = useFormState({})
+ * // Access: state.value.errors, state.value.isDirty, etc.
  *
  * // Subscribe to specific properties
- * const { isSubmitting, errors } = useFormState({ name: ['isSubmitting', 'errors'] })
- *
- * // Subscribe to single property
- * const isDirty = useFormState({ name: 'isDirty' })
+ * const state = useFormState({ name: ['isSubmitting', 'errors'] })
+ * // Access: state.value.isSubmitting, state.value.errors
  *
  * // With explicit control
  * const { control } = useForm({ schema })
- * const formState = useFormState({ control })
+ * const state = useFormState({ control })
  * ```
  */
 export declare function useFormState<TSchema extends ZodType>(options?: UseFormStateOptions<TSchema>): ComputedRef<Partial<FormState<InferSchema<TSchema>>>>;

package/dist/useWatch.d.ts

@@ -10,7 +10,7 @@ export interface UseWatchOptions<TSchema extends ZodType, TPath extends Path<Inf
     /** Field path or array of paths to watch (watches all if not provided) */
     name?: TPath | TPath[];
     /** Default value when field is undefined */
-    defaultValue?: unknown;
+    defaultValue?: PathValue<InferSchema<TSchema>, TPath>;
 }
 /**
  * Watch form field values reactively without the full form instance

package/dist/vuehookform.cjs

@@ -541,14 +541,15 @@ function clearFieldTouched(touchedFields, fieldName) {
 }
 function clearFieldErrors(errors, fieldName) {
 	const currentErrors = errors.value;
-	const keys = Object.keys(currentErrors);
-	if (keys.length === 0) return;
+	if (Object.keys(currentErrors).length === 0) return;
+	const nestedError = get(currentErrors, fieldName);
 	const prefix = `${fieldName}.`;
-	const keysToDelete = [];
-	for (const key of keys) if (key === fieldName || key.startsWith(prefix)) keysToDelete.push(key);
-	if (keysToDelete.length === 0) return;
+	const flatKeysToDelete = [];
+	for (const key of Object.keys(currentErrors)) if (key === fieldName || key.startsWith(prefix)) flatKeysToDelete.push(key);
+	if (nestedError === void 0 && flatKeysToDelete.length === 0) return;
 	const newErrors = { ...currentErrors };
-	for (const key of keysToDelete) delete newErrors[key];
+	for (const key of flatKeysToDelete) delete newErrors[key];
+	if (nestedError !== void 0) unset(newErrors, fieldName);
 	errors.value = newErrors;
 }
 function updateFieldDirtyState(dirtyFields, defaultValues, defaultValueHashes, fieldName, currentValue) {
@@ -592,7 +593,6 @@ function createFieldError(errors, criteriaMode = "firstError") {
 	const firstError = errors[0];
 	if (!firstError) return "";
 	if (criteriaMode === "firstError") return firstError.message;
-	if (errors.length === 1) return firstError.message;
 	const types = {};
 	for (const err of errors) {
 		const existing = types[err.type];
@@ -818,7 +818,7 @@ function shouldValidateOnBlur(mode, hasSubmitted, reValidateMode) {
 	return mode === "onBlur" || mode === "onTouched" || hasSubmitted && (reValidateMode === "onBlur" || reValidateMode === "onTouched");
 }
 var validationRequestCounter = 0;
-function createFieldRegistration(ctx, validate) {
+function createFieldRegistration(ctx, validate, onChangeHelpers) {
 	function register(name, registerOptions) {
 		if (__DEV__) {
 			const syntaxError = validatePathSyntax(name);
@@ -845,13 +845,13 @@ function createFieldRegistration(ctx, validate) {
 				const error = await fieldOpts.validate(value);
 				if (requestId !== ctx.validationRequestIds.get(fieldName)) return;
 				if (ctx.resetGeneration.value !== resetGenAtStart) return;
-				if (error) ctx.errors.value = {
-					...ctx.errors.value,
-					[fieldName]: error
-				};
-				else {
+				if (error) {
+					const newErrors = { ...ctx.errors.value };
+					set(newErrors, fieldName, error);
+					ctx.errors.value = newErrors;
+				} else {
 					const newErrors = { ...ctx.errors.value };
-					delete newErrors[fieldName];
+					unset(newErrors, fieldName);
 					ctx.errors.value = newErrors;
 				}
 			};
@@ -864,6 +864,11 @@ function createFieldRegistration(ctx, validate) {
 				set(ctx.formData, name, value);
 				updateFieldDirtyState(ctx.dirtyFields, ctx.defaultValues, ctx.defaultValueHashes, name, value);
 				const fieldOpts = ctx.fieldOptions.get(name);
+				if (fieldOpts?.onChange && onChangeHelpers?.setValue) try {
+					fieldOpts.onChange(value, { setValue: onChangeHelpers.setValue });
+				} catch (err) {
+					if (__DEV__) console.error(`[vue-hook-form] Error in onChange callback for field '${name}':`, err);
+				}
 				if (shouldValidateOnChange(ctx.options.mode ?? "onSubmit", ctx.touchedFields.value[name] === true, ctx.submitCount.value > 0, ctx.options.reValidateMode)) {
 					const validationDebounceMs = ctx.options.validationDebounce || 0;
 					if (validationDebounceMs > 0) {
@@ -1423,7 +1428,8 @@ function useForm(options) {
 		ctx.cleanup();
 	});
 	const { validate, clearAllPendingErrors } = createValidation(ctx);
-	const { register, unregister } = createFieldRegistration(ctx, validate);
+	const onChangeHelpers = { setValue: null };
+	const { register, unregister } = createFieldRegistration(ctx, validate, onChangeHelpers);
 	function setFocus(name, focusOptions) {
 		if (__DEV__) {
 			const syntaxError = validatePathSyntax(name);
@@ -1514,6 +1520,12 @@ function useForm(options) {
 		},
 		get disabled() {
 			return ctx.isDisabled.value;
+		},
+		get isPristine() {
+			return !isDirtyComputed.value;
+		},
+		get canSubmit() {
+			return isValidComputed.value && !ctx.isSubmitting.value && !ctx.isLoading.value && !ctx.isDisabled.value;
 		}
 	});
 	const formState = (0, vue.computed)(() => formStateInternal);
@@ -1529,7 +1541,7 @@ function useForm(options) {
 			try {
 				syncWithDebounce();
 				if (await validate()) {
-					await onValid(ctx.formData);
+					await onValid(deepClone(ctx.formData));
 					ctx.isSubmitSuccessful.value = true;
 				} else {
 					onInvalid?.(formState.value.errors);
@@ -1563,6 +1575,7 @@ function useForm(options) {
 		}
 		if (setValueOptions?.shouldValidate) validate(name);
 	}
+	onChangeHelpers.setValue = setValue;
 	function reset(values, resetOptions) {
 		const opts = resetOptions || {};
 		ctx.validationCache.clear();
@@ -1611,7 +1624,6 @@ function useForm(options) {
 			}
 		}
 		const opts = resetFieldOptions || {};
-		ctx.resetGeneration.value++;
 		ctx.validationCache.delete(`${name}:partial`);
 		ctx.validationCache.delete(`${name}:full`);
 		const errorTimer = ctx.errorDelayTimers.get(name);
@@ -1620,6 +1632,11 @@ function useForm(options) {
 			ctx.errorDelayTimers.delete(name);
 		}
 		ctx.pendingErrors.delete(name);
+		const schemaTimer = ctx.schemaValidationTimers.get(name);
+		if (schemaTimer) {
+			clearTimeout(schemaTimer);
+			ctx.schemaValidationTimers.delete(name);
+		}
 		let defaultValue = opts.defaultValue;
 		if (defaultValue === void 0) defaultValue = get(ctx.defaultValues, name);
 		else {
@@ -1732,13 +1749,13 @@ function useForm(options) {
 			}
 		}
 		syncWithDebounce();
-		if (nameOrNames === void 0) return { ...ctx.formData };
+		if (nameOrNames === void 0) return deepClone(ctx.formData);
 		if (Array.isArray(nameOrNames)) {
 			const result = {};
-			for (const fieldName of nameOrNames) result[fieldName] = get(ctx.formData, fieldName);
+			for (const fieldName of nameOrNames) result[fieldName] = deepClone(get(ctx.formData, fieldName));
 			return result;
 		}
-		return get(ctx.formData, nameOrNames);
+		return deepClone(get(ctx.formData, nameOrNames));
 	}
 	function getFieldState(name) {
 		if (__DEV__) {
@@ -1772,11 +1789,7 @@ function useForm(options) {
 		}
 		if (options$1?.markAsSubmitted) ctx.submitCount.value++;
 		if (name === void 0) return await validate();
-		if (Array.isArray(name)) {
-			let allValid = true;
-			for (const fieldName of name) if (!await validate(fieldName)) allValid = false;
-			return allValid;
-		}
+		if (Array.isArray(name)) return (await Promise.all(name.map((fieldName) => validate(fieldName)))).every((isValid) => isValid);
 		return await validate(name);
 	}
 	const setFocusWrapper = (name) => setFocus(name);
@@ -1828,25 +1841,28 @@ function useFormContext() {
 function useWatch(options = {}) {
 	const { control, name, defaultValue } = options;
 	const form = control ?? useFormContext();
-	return (0, vue.computed)(() => {
-		if (name === void 0) return form.getValues();
-		if (Array.isArray(name)) {
-			const result = {};
-			for (const fieldName of name) result[fieldName] = get(form.getValues(), fieldName) ?? defaultValue;
+	if (name === void 0) return form.watch();
+	if (Array.isArray(name)) {
+		const watched$1 = form.watch(name);
+		if (defaultValue === void 0) return watched$1;
+		return (0, vue.computed)(() => {
+			const result = { ...watched$1.value };
+			for (const fieldName of name) if (result[fieldName] === void 0) result[fieldName] = defaultValue;
 			return result;
-		}
-		return get(form.getValues(), name) ?? defaultValue;
-	});
+		});
+	}
+	const watched = form.watch(name);
+	if (defaultValue === void 0) return watched;
+	return (0, vue.computed)(() => watched.value ?? defaultValue);
 }
 function useController(options) {
 	const { name, control, defaultValue } = options;
 	const form = control ?? useFormContext();
 	const elementRef = (0, vue.ref)(null);
 	if (defaultValue !== void 0 && form.getValues(name) === void 0) form.setValue(name, defaultValue);
+	const watchedValue = form.watch(name);
 	const value = (0, vue.computed)({
-		get: () => {
-			return form.getValues(name) ?? defaultValue;
-		},
+		get: () => watchedValue.value ?? defaultValue,
 		set: (newValue) => {
 			form.setValue(name, newValue);
 		}
@@ -1905,6 +1921,19 @@ function useFormState(options = {}) {
 		return { [name]: fullState[name] };
 	});
 }
+function useFieldError(options) {
+	const form = options.control ?? useFormContext();
+	return (0, vue.computed)(() => {
+		const error = get(form.formState.value.errors, options.name);
+		if (!error) return void 0;
+		if (typeof error === "string") return error;
+		if (Array.isArray(error)) {
+			if (__DEV__) console.warn(`[vue-hook-form] useFieldError('${options.name}') resolved to an array of per-item errors.\nuseFieldError only returns scalar error messages. Use formState.value.errors['${options.name}'] directly for item-level errors.`);
+			return;
+		}
+		if (typeof error === "object" && "message" in error) return error.message;
+	});
+}
 function isFieldError(error) {
 	return typeof error === "object" && error !== null && "type" in error && "message" in error && typeof error.type === "string" && typeof error.message === "string";
 }
@@ -1916,7 +1945,10 @@ exports.provideForm = provideForm;
 exports.set = set;
 exports.unset = unset;
 exports.useController = useController;
+exports.useFieldError = useFieldError;
 exports.useForm = useForm;
 exports.useFormContext = useFormContext;
 exports.useFormState = useFormState;
 exports.useWatch = useWatch;
+
+//# sourceMappingURL=vuehookform.cjs.map