@vuehookform/core 0.3.0 → 0.3.3

package/README.md

@@ -10,7 +10,7 @@ A TypeScript-first form library for Vue 3, inspired by React Hook Form.
 - **Field Arrays** - Dynamic lists with stable keys built-in
 - **Performant** - Minimal re-renders using uncontrolled inputs
 - **Zod Native** - First-class Zod integration for validation
-- **Tiny Bundle** - < 5kb gzipped, tree-shakable
+- **Tiny Bundle** - ~10kb gzipped, tree-shakable
 - **UI Agnostic** - Works with any UI library or custom components
 
 ## Quick Start

package/dist/utils/devWarnings.d.ts

@@ -1,8 +1,4 @@
 import { ZodType } from 'zod';
-/**
- * DEV flag for tree-shaking
- * In production builds, this becomes `false` and all warning code is eliminated
- */
 export declare const __DEV__: boolean;
 /**
  * Warn once per unique message (prevents spam on re-renders)

package/dist/vuehookform.cjs

@@ -53,11 +53,26 @@ function generateId() {
 	const random = Math.random().toString(36).substring(2, 11);
 	return `field_${Date.now()}_${idCounter++}_${random}`;
 }
-const __DEV__ = false;
+var proc = globalThis.process;
+const __DEV__ = proc?.env?.NODE_ENV !== "production";
 var warnedMessages = /* @__PURE__ */ new Set();
-function warnOnce(message, key) {}
-function warn(message) {}
+function warnOnce(message, key) {
+	if (!__DEV__) return;
+	const cacheKey = key ?? message;
+	if (warnedMessages.has(cacheKey)) return;
+	warnedMessages.add(cacheKey);
+	console.warn(`[vue-hook-form] ${message}`);
+}
+function warn(message) {
+	if (!__DEV__) return;
+	console.warn(`[vue-hook-form] ${message}`);
+}
 function validatePathSyntax(path) {
+	if (!__DEV__) return null;
+	if (!path || path.trim() === "") return "Path cannot be empty";
+	if (path.startsWith(".") || path.endsWith(".") || path.includes("..")) return `Invalid path "${path}": contains empty segments`;
+	if (path.includes("[")) return `Invalid path "${path}": use dot notation (e.g., "items.0") instead of bracket notation (e.g., "items[0]")`;
+	if (/\s/.test(path)) return `Invalid path "${path}": paths cannot contain whitespace`;
 	return null;
 }
 function traverseSchemaPath(schema, path) {
@@ -94,16 +109,77 @@ function traverseSchemaPath(schema, path) {
 	return { schema: currentSchema };
 }
 function validatePathAgainstSchema(schema, path) {
-	return { valid: true };
+	if (!__DEV__) return { valid: true };
+	try {
+		const result = traverseSchemaPath(schema, path);
+		if ("error" in result) return {
+			valid: false,
+			reason: result.error,
+			availableFields: result.availableFields
+		};
+		return { valid: true };
+	} catch {
+		return { valid: true };
+	}
 }
 function isArrayFieldInSchema(schema, path) {
-	return null;
+	if (!__DEV__) return null;
+	try {
+		const result = traverseSchemaPath(schema, path);
+		if ("error" in result) return null;
+		return isZodArray(unwrapSchema(result.schema));
+	} catch {
+		return null;
+	}
+}
+function warnInvalidPath(fnName, path, reason) {
+	if (!__DEV__) return;
+	let message = `${fnName}("${path}"): ${reason}`;
+	if (reason.includes("bracket notation")) {
+		const fixedPath = path.replace(/\[(\d+)\]/g, ".$1");
+		message += `\n  FIX: Use dot notation for array indices`;
+		message += `\n  EXAMPLE: ${fnName}("${fixedPath}")`;
+	} else if (reason.includes("empty")) {
+		message += `\n  FIX: Provide a non-empty field path`;
+		message += `\n  EXAMPLE: ${fnName}("email") or ${fnName}("user.address.city")`;
+	} else if (reason.includes("whitespace")) {
+		const fixedPath = path.replace(/\s/g, "");
+		message += `\n  FIX: Remove spaces from the field path`;
+		message += `\n  EXAMPLE: ${fnName}("${fixedPath}")`;
+	} else if (reason.includes("empty segments")) {
+		const fixedPath = path.replace(/\.{2,}/g, ".").replace(/^\./, "").replace(/\.$/, "");
+		message += `\n  FIX: Remove extra dots from the path`;
+		message += `\n  EXAMPLE: ${fnName}("${fixedPath}")`;
+	}
+	warnOnce(message, `invalid-path:${fnName}:${path}`);
+}
+function warnPathNotInSchema(fnName, path, availableFields) {
+	if (!__DEV__) return;
+	let message = `${fnName}("${path}"): Path does not exist in your Zod schema.`;
+	message += `\n  FIX: Check that the path matches your schema definition exactly (case-sensitive)`;
+	if (availableFields && availableFields.length > 0) {
+		const pathLower = path.toLowerCase();
+		const suggestions = availableFields.filter((f) => f.toLowerCase().includes(pathLower) || pathLower.includes(f.toLowerCase()));
+		if (suggestions.length > 0) message += `\n  DID YOU MEAN: ${suggestions.slice(0, 3).map((s) => `"${s}"`).join(", ")}`;
+		message += `\n  AVAILABLE: ${availableFields.slice(0, 8).join(", ")}${availableFields.length > 8 ? "..." : ""}`;
+	}
+	warnOnce(message, `path-not-in-schema:${fnName}:${path}`);
+}
+function warnFieldsOnNonArray(path) {
+	if (!__DEV__) return;
+	warnOnce(`fields("${path}"): Expected an array field, but this path does not point to an array in your schema. The fields() method is only for array fields. Use register() for non-array fields.`, `fields-non-array:${path}`);
+}
+function warnArrayOperationRejected(operation, path, reason, details) {
+	if (!__DEV__) return;
+	warn(`${operation}() on "${path}": ${{
+		maxLength: details ? `Would exceed maxLength (current: ${details.current}, max: ${details.limit})` : "Would exceed maxLength rule",
+		minLength: details ? `Would violate minLength (current: ${details.current}, min: ${details.limit})` : "Would violate minLength rule"
+	}[reason]}. Operation was silently ignored.`);
+}
+function warnArrayIndexOutOfBounds(operation, path, index, length) {
+	if (!__DEV__) return;
+	warn(`${operation}() on "${path}": Index ${index} is out of bounds (array length: ${length}). Operation was silently ignored.`);
 }
-function warnInvalidPath(fnName, path, reason) {}
-function warnPathNotInSchema(fnName, path, availableFields) {}
-function warnFieldsOnNonArray(path) {}
-function warnArrayOperationRejected(operation, path, reason, details) {}
-function warnArrayIndexOutOfBounds(operation, path, index, length) {}
 function getDefProp(schema, prop) {
 	return schema.def[prop];
 }
@@ -369,6 +445,12 @@ function createValidation(ctx) {
 var validationRequestCounter = 0;
 function createFieldRegistration(ctx, validate) {
 	function register(name, registerOptions) {
+		if (__DEV__) {
+			const syntaxError = validatePathSyntax(name);
+			if (syntaxError) warnInvalidPath("register", name, syntaxError);
+			const schemaResult = validatePathAgainstSchema(ctx.options.schema, name);
+			if (!schemaResult.valid) warnPathNotInSchema("register", name, schemaResult.availableFields);
+		}
 		let fieldRef = ctx.fieldRefs.get(name);
 		if (!fieldRef) {
 			fieldRef = (0, vue.ref)(null);
@@ -535,6 +617,13 @@ function createFieldRegistration(ctx, validate) {
 }
 function createFieldArrayManager(ctx, validate, setFocus) {
 	function fields(name, options) {
+		if (__DEV__) {
+			const syntaxError = validatePathSyntax(name);
+			if (syntaxError) warnInvalidPath("fields", name, syntaxError);
+			const schemaResult = validatePathAgainstSchema(ctx.options.schema, name);
+			if (!schemaResult.valid) warnPathNotInSchema("fields", name, schemaResult.availableFields);
+			if (isArrayFieldInSchema(ctx.options.schema, name) === false) warnFieldsOnNonArray(name);
+		}
 		let fieldArray = ctx.fieldArrays.get(name);
 		if (!fieldArray) {
 			const existingValues = get(ctx.formData, name) || [];
@@ -586,7 +675,13 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 			const currentValues = get(ctx.formData, name) || [];
 			const insertIndex = currentValues.length;
 			const rules = fa.rules;
-			if (rules?.maxLength && currentValues.length + values.length > rules.maxLength.value) return false;
+			if (rules?.maxLength && currentValues.length + values.length > rules.maxLength.value) {
+				if (__DEV__) warnArrayOperationRejected("append", name, "maxLength", {
+					current: currentValues.length,
+					limit: rules.maxLength.value
+				});
+				return false;
+			}
 			const newValues = [...currentValues, ...values];
 			set(ctx.formData, name, newValues);
 			const newItems = values.map(() => createItem(generateId()));
@@ -605,7 +700,13 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 			if (values.length === 0) return true;
 			const currentValues = get(ctx.formData, name) || [];
 			const rules = fa.rules;
-			if (rules?.maxLength && currentValues.length + values.length > rules.maxLength.value) return false;
+			if (rules?.maxLength && currentValues.length + values.length > rules.maxLength.value) {
+				if (__DEV__) warnArrayOperationRejected("prepend", name, "maxLength", {
+					current: currentValues.length,
+					limit: rules.maxLength.value
+				});
+				return false;
+			}
 			const newValues = [...values, ...currentValues];
 			set(ctx.formData, name, newValues);
 			const newItems = values.map(() => createItem(generateId()));
@@ -621,7 +722,10 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 		};
 		const update = (index, value) => {
 			const currentValues = get(ctx.formData, name) || [];
-			if (index < 0 || index >= currentValues.length) return false;
+			if (index < 0 || index >= currentValues.length) {
+				if (__DEV__) warnArrayIndexOutOfBounds("update", name, index, currentValues.length);
+				return false;
+			}
 			const newValues = [...currentValues];
 			newValues[index] = value;
 			set(ctx.formData, name, newValues);
@@ -634,9 +738,18 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 		};
 		const removeAt = (index) => {
 			const currentValues = get(ctx.formData, name) || [];
-			if (index < 0 || index >= currentValues.length) return false;
+			if (index < 0 || index >= currentValues.length) {
+				if (__DEV__) warnArrayIndexOutOfBounds("remove", name, index, currentValues.length);
+				return false;
+			}
 			const rules = fa.rules;
-			if (rules?.minLength && currentValues.length - 1 < rules.minLength.value) return false;
+			if (rules?.minLength && currentValues.length - 1 < rules.minLength.value) {
+				if (__DEV__) warnArrayOperationRejected("remove", name, "minLength", {
+					current: currentValues.length,
+					limit: rules.minLength.value
+				});
+				return false;
+			}
 			const newValues = currentValues.filter((_, i) => i !== index);
 			set(ctx.formData, name, newValues);
 			const keyToRemove = fa.items.value[index]?.key;
@@ -654,7 +767,13 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 			if (values.length === 0) return true;
 			const currentValues = get(ctx.formData, name) || [];
 			const rules = fa.rules;
-			if (rules?.maxLength && currentValues.length + values.length > rules.maxLength.value) return false;
+			if (rules?.maxLength && currentValues.length + values.length > rules.maxLength.value) {
+				if (__DEV__) warnArrayOperationRejected("insert", name, "maxLength", {
+					current: currentValues.length,
+					limit: rules.maxLength.value
+				});
+				return false;
+			}
 			const clampedIndex = Math.max(0, Math.min(index, currentValues.length));
 			const newValues = [
 				...currentValues.slice(0, clampedIndex),
@@ -679,7 +798,10 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 		};
 		const swap = (indexA, indexB) => {
 			const currentValues = get(ctx.formData, name) || [];
-			if (indexA < 0 || indexB < 0 || indexA >= currentValues.length || indexB >= currentValues.length) return false;
+			if (indexA < 0 || indexB < 0 || indexA >= currentValues.length || indexB >= currentValues.length) {
+				if (__DEV__) warnArrayIndexOutOfBounds("swap", name, indexA < 0 || indexA >= currentValues.length ? indexA : indexB, currentValues.length);
+				return false;
+			}
 			const newValues = [...currentValues];
 			[newValues[indexA], newValues[indexB]] = [newValues[indexB], newValues[indexA]];
 			set(ctx.formData, name, newValues);
@@ -701,7 +823,10 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 		};
 		const move = (from, to) => {
 			const currentValues = get(ctx.formData, name) || [];
-			if (from < 0 || from >= currentValues.length || to < 0) return false;
+			if (from < 0 || from >= currentValues.length || to < 0) {
+				if (__DEV__) warnArrayIndexOutOfBounds("move", name, from < 0 || from >= currentValues.length ? from : to, currentValues.length);
+				return false;
+			}
 			const newValues = [...currentValues];
 			const [removed] = newValues.splice(from, 1);
 			if (removed !== void 0) {
@@ -738,7 +863,13 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 		};
 		const removeAll = () => {
 			const rules = fa.rules;
-			if (rules?.minLength && rules.minLength.value > 0) return false;
+			if (rules?.minLength && rules.minLength.value > 0) {
+				if (__DEV__) warnArrayOperationRejected("removeAll", name, "minLength", {
+					current: fa.items.value.length,
+					limit: rules.minLength.value
+				});
+				return false;
+			}
 			set(ctx.formData, name, []);
 			fa.items.value = [];
 			rebuildIndexCache();
@@ -755,7 +886,13 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 			if (validIndices.length === 0) return true;
 			const rules = fa.rules;
 			const remainingCount = currentValues.length - validIndices.length;
-			if (rules?.minLength && remainingCount < rules.minLength.value) return false;
+			if (rules?.minLength && remainingCount < rules.minLength.value) {
+				if (__DEV__) warnArrayOperationRejected("removeMany", name, "minLength", {
+					current: currentValues.length,
+					limit: rules.minLength.value
+				});
+				return false;
+			}
 			const sortedIndices = [...new Set(validIndices)].sort((a, b) => b - a);
 			const indicesToRemove = new Set(sortedIndices);
 			const newValues = currentValues.filter((_, i) => !indicesToRemove.has(i));
@@ -829,6 +966,14 @@ function useForm(options) {
 	const { validate, clearAllPendingErrors } = createValidation(ctx);
 	const { register, unregister } = createFieldRegistration(ctx, validate);
 	function setFocus(name, focusOptions) {
+		if (__DEV__) {
+			const syntaxError = validatePathSyntax(name);
+			if (syntaxError) warnInvalidPath("setFocus", name, syntaxError);
+			else {
+				const schemaResult = validatePathAgainstSchema(ctx.options.schema, name);
+				if (!schemaResult.valid) warnPathNotInSchema("setFocus", name, schemaResult.availableFields);
+			}
+		}
 		const fieldRef = ctx.fieldRefs.get(name);
 		if (!fieldRef?.value) return;
 		const el = fieldRef.value;
@@ -891,6 +1036,14 @@ function useForm(options) {
 		};
 	}
 	function setValue(name, value, setValueOptions) {
+		if (__DEV__) {
+			const syntaxError = validatePathSyntax(name);
+			if (syntaxError) warnInvalidPath("setValue", name, syntaxError);
+			else {
+				const schemaResult = validatePathAgainstSchema(ctx.options.schema, name);
+				if (!schemaResult.valid) warnPathNotInSchema("setValue", name, schemaResult.availableFields);
+			}
+		}
 		set(ctx.formData, name, value);
 		if (setValueOptions?.shouldDirty !== false) markFieldDirty(ctx.dirtyFields, name);
 		if (setValueOptions?.shouldTouch) markFieldTouched(ctx.touchedFields, name);
@@ -927,6 +1080,14 @@ function useForm(options) {
 		}
 	}
 	function resetField(name, resetFieldOptions) {
+		if (__DEV__) {
+			const syntaxError = validatePathSyntax(name);
+			if (syntaxError) warnInvalidPath("resetField", name, syntaxError);
+			else {
+				const schemaResult = validatePathAgainstSchema(ctx.options.schema, name);
+				if (!schemaResult.valid) warnPathNotInSchema("resetField", name, schemaResult.availableFields);
+			}
+		}
 		const opts = resetFieldOptions || {};
 		ctx.resetGeneration.value++;
 		const errorTimer = ctx.errorDelayTimers.get(name);
@@ -949,6 +1110,17 @@ function useForm(options) {
 		}
 	}
 	function watch$1(name) {
+		if (__DEV__ && name) {
+			const names = Array.isArray(name) ? name : [name];
+			for (const n of names) {
+				const syntaxError = validatePathSyntax(n);
+				if (syntaxError) warnInvalidPath("watch", n, syntaxError);
+				else {
+					const schemaResult = validatePathAgainstSchema(ctx.options.schema, n);
+					if (!schemaResult.valid) warnPathNotInSchema("watch", n, schemaResult.availableFields);
+				}
+			}
+		}
 		return (0, vue.computed)(() => {
 			if (!name) return ctx.formData;
 			if (Array.isArray(name)) {
@@ -960,6 +1132,18 @@ function useForm(options) {
 		});
 	}
 	function clearErrors(name) {
+		if (__DEV__ && name && !String(name).startsWith("root")) {
+			const names = Array.isArray(name) ? name : [name];
+			for (const n of names) {
+				if (String(n).startsWith("root")) continue;
+				const syntaxError = validatePathSyntax(n);
+				if (syntaxError) warnInvalidPath("clearErrors", n, syntaxError);
+				else {
+					const schemaResult = validatePathAgainstSchema(ctx.options.schema, n);
+					if (!schemaResult.valid) warnPathNotInSchema("clearErrors", n, schemaResult.availableFields);
+				}
+			}
+		}
 		if (name === void 0) {
 			ctx.errors.value = {};
 			return;
@@ -998,6 +1182,17 @@ function useForm(options) {
 		return get(mergedErrors, fieldPath);
 	}
 	function getValues(nameOrNames) {
+		if (__DEV__ && nameOrNames) {
+			const names = Array.isArray(nameOrNames) ? nameOrNames : [nameOrNames];
+			for (const n of names) {
+				const syntaxError = validatePathSyntax(n);
+				if (syntaxError) warnInvalidPath("getValues", n, syntaxError);
+				else {
+					const schemaResult = validatePathAgainstSchema(ctx.options.schema, n);
+					if (!schemaResult.valid) warnPathNotInSchema("getValues", n, schemaResult.availableFields);
+				}
+			}
+		}
 		syncUncontrolledInputs(ctx.fieldRefs, ctx.fieldOptions, ctx.formData);
 		if (nameOrNames === void 0) return { ...ctx.formData };
 		if (Array.isArray(nameOrNames)) {
@@ -1008,6 +1203,14 @@ function useForm(options) {
 		return get(ctx.formData, nameOrNames);
 	}
 	function getFieldState(name) {
+		if (__DEV__) {
+			const syntaxError = validatePathSyntax(name);
+			if (syntaxError) warnInvalidPath("getFieldState", name, syntaxError);
+			else {
+				const schemaResult = validatePathAgainstSchema(ctx.options.schema, name);
+				if (!schemaResult.valid) warnPathNotInSchema("getFieldState", name, schemaResult.availableFields);
+			}
+		}
 		const error = get(ctx.errors.value, name);
 		return {
 			isDirty: ctx.dirtyFields.value[name] === true,
@@ -1017,6 +1220,17 @@ function useForm(options) {
 		};
 	}
 	async function trigger(name) {
+		if (__DEV__ && name) {
+			const names = Array.isArray(name) ? name : [name];
+			for (const n of names) {
+				const syntaxError = validatePathSyntax(n);
+				if (syntaxError) warnInvalidPath("trigger", n, syntaxError);
+				else {
+					const schemaResult = validatePathAgainstSchema(ctx.options.schema, n);
+					if (!schemaResult.valid) warnPathNotInSchema("trigger", n, schemaResult.availableFields);
+				}
+			}
+		}
 		if (name === void 0) return await validate();
 		if (Array.isArray(name)) {
 			let allValid = true;

package/dist/vuehookform.js

@@ -52,7 +52,7 @@ function generateId() {
 	const random = Math.random().toString(36).substring(2, 11);
 	return `field_${Date.now()}_${idCounter++}_${random}`;
 }
-const __DEV__ = typeof import.meta !== "undefined" && false;
+const __DEV__ = globalThis.process?.env?.NODE_ENV !== "production";
 var warnedMessages = /* @__PURE__ */ new Set();
 function warnOnce(message, key) {
 	if (!__DEV__) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vuehookform/core",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "description": "TypeScript-first form library for Vue 3, inspired by React Hook Form. Form-level state management with Zod validation.",
   "type": "module",
   "main": "./dist/vuehookform.cjs",
@@ -21,22 +21,19 @@
     "node": "^20.19.0 || >=22.12.0"
   },
   "scripts": {
-    "dev": "vite",
-    "build": "run-p type-check \"build-only {@}\" --",
-    "build:lib": "run-p type-check build-lib-only",
-    "build-lib-only": "vite build --config vite.config.lib.ts",
-    "preview": "vite preview",
-    "build-only": "vite build",
+    "build:lib": "vite build --config vite.config.lib.ts",
+    "build": "run-p type-check build:lib",
+    "docs": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
     "type-check": "vue-tsc --build",
     "lint:oxlint": "oxlint . --fix -D correctness --ignore-path .gitignore",
     "lint:eslint": "eslint . --fix --cache",
     "lint": "run-s lint:*",
-    "format": "prettier --write --experimental-cli src/ tests/",
+    "format": "prettier --write --experimental-cli lib/ docs/",
     "test": "vitest",
     "test:run": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "prepublishOnly": "npm run build:lib",
-    "postversion": "git push && git push --tags",
     "prepare": "husky"
   },
   "repository": {
@@ -70,7 +67,6 @@
   },
   "devDependencies": {
     "@prettier/plugin-oxc": "^0.0.5",
-    "@tailwindcss/vite": "^4.1.18",
     "@tsconfig/node24": "^24.0.3",
     "@types/node": "^24.10.1",
     "@vitejs/plugin-vue": "^6.0.2",
@@ -85,20 +81,16 @@
     "husky": "^9.1.7",
     "jiti": "^2.6.1",
     "lint-staged": "^16.2.7",
-    "material-icons": "^1.13.14",
-    "material-symbols": "^0.40.2",
     "npm-run-all2": "^8.0.4",
+    "oxc-minify": "^0.105.0",
     "oxlint": "~1.29.0",
-    "pinia": "^3.0.4",
     "prettier": "3.6.2",
-    "tailwindcss": "^4.1.18",
     "typescript": "~5.9.0",
     "vite": "npm:rolldown-vite@latest",
-    "vite-plugin-compression2": "^2.4.0",
     "vite-plugin-dts": "^4.5.4",
+    "vitepress": "^2.0.0-alpha.15",
     "vitest": "^4.0.16",
     "vue": "^3.5.25",
-    "vue-router": "^4.6.3",
     "vue-tsc": "^3.1.5",
     "zod": "^4.2.1"
   },