notform 2.0.0-beta.1 → 2.0.0-beta.2

package/dist/index.d.ts

@@ -260,6 +260,27 @@ type NotFieldProps = {
    * ```
    */
   validateOn?: Partial<Record<ValidationTrigger, boolean>>;
+  /**
+   * Debounce delay in milliseconds for input- and change-triggered validation.
+   *
+   * When set, validation is deferred until the user stops typing for the given
+   * duration. Only the final call within the window runs — earlier ones are
+   * cancelled. Useful for async validators (e.g. username availability checks)
+   * where firing on every keystroke would cause excessive requests.
+   *
+   * Blur- and submit-triggered validation always runs immediately, regardless
+   * of this setting, so the field never feels unresponsive when the user leaves.
+   *
+   * ```vue
+   * <!-- validate 400ms after the user stops typing -->
+   * <NotField path="username" :debounce="400" v-slot="{ events }">
+   *   <input v-model="form.values.username" v-bind="events" />
+   * </NotField>
+   * ```
+   *
+   * Omit or set to `0` to disable debouncing (default behaviour).
+   */
+  debounce?: number;
 };
 /**
  * Everything available inside the `NotField` default slot.

package/dist/index.js

@@ -1,4 +1,4 @@
-import { computed, createBlock, createCommentVNode, createElementBlock, createTextVNode, defineComponent, guardReactiveProps, inject, markRaw, mergeProps, nextTick, normalizeProps, onMounted, openBlock, provide, reactive, ref, renderSlot, resolveDynamicComponent, toDisplayString, toValue, unref, useAttrs, watch, withCtx } from "vue";
+import { computed, createBlock, createCommentVNode, createElementBlock, createTextVNode, defineComponent, guardReactiveProps, inject, markRaw, mergeProps, nextTick, normalizeProps, onMounted, onUnmounted, openBlock, provide, reactive, ref, renderSlot, resolveDynamicComponent, toDisplayString, toValue, unref, useAttrs, watch, withCtx } from "vue";
 import { klona } from "klona/full";
 import { dequal } from "dequal";
 import { deepKeys, deleteProperty, getProperty, hasProperty, parsePath, setProperty } from "dot-prop";
@@ -310,6 +310,10 @@ var not_field_default = /* @__PURE__ */ defineComponent({
 		validateOn: {
 			type: Object,
 			required: false
+		},
+		debounce: {
+			type: Number,
+			required: false
 		}
 	},
 	setup(__props) {
@@ -320,6 +324,36 @@ var not_field_default = /* @__PURE__ */ defineComponent({
 			...props.validateOn
 		}));
 		const isValidating = ref(false);
+		/** Timer handle for the current pending debounced validation, if any. */
+		let debounceTimer;
+		/**
+		* Cancels any pending debounced validation without running it.
+		* Called on blur (so blur's own immediate validation takes over) and on unmount
+		* (to prevent a timer from firing after the component is gone).
+		*/
+		const clearDebounce = () => {
+			if (debounceTimer !== void 0) {
+				clearTimeout(debounceTimer);
+				debounceTimer = void 0;
+			}
+		};
+		/**
+		* Schedules a validation run, respecting the field's `debounce` prop.
+		*
+		* - If `debounce` is `0` or omitted, validation runs synchronously.
+		* - Otherwise, any pending timer is cancelled and a new one is started.
+		*   Only the final call within the window actually validates — useful for
+		*   async checks (availability lookups, server-side rules) where firing on
+		*   every keystroke would be wasteful.
+		*/
+		const scheduleValidation = () => {
+			if (!props.debounce) {
+				validate();
+				return;
+			}
+			clearDebounce();
+			debounceTimer = setTimeout(validate, props.debounce);
+		};
 		const value = computed(() => getProperty(form.values, props.path));
 		const errors = computed(() => form.getFieldErrors(props.path));
 		const isValid = computed(() => errors.value.length === 0);
@@ -343,21 +377,22 @@ var not_field_default = /* @__PURE__ */ defineComponent({
 			}
 		};
 		const onBlur = () => {
+			clearDebounce();
 			form.touchField(props.path);
 			if (validateOn.value.onBlur) validate();
 		};
 		const onInput = () => {
 			updateDirty();
 			if (!validateOn.value.onInput) return;
-			if (form.validationMode.eager && errors.value.length > 0) validate();
+			if (form.validationMode.eager && !isValid.value) scheduleValidation();
 		};
 		const onChange = () => {
 			updateDirty();
 			if (!validateOn.value.onChange) return;
-			if (form.validationMode.eager && errors.value.length > 0) validate();
+			if (form.validationMode.eager && !isValid.value) scheduleValidation();
 		};
 		const onFocus = () => {
-			if (validateOn.value.onFocus) validate();
+			if (validateOn.value.onFocus) scheduleValidation();
 		};
 		const events = computed(() => ({
 			onBlur,
@@ -369,6 +404,7 @@ var not_field_default = /* @__PURE__ */ defineComponent({
 			await nextTick();
 			if (validateOn.value.onMount) validate();
 		});
+		onUnmounted(clearDebounce);
 		const slotProps = computed(() => ({
 			path: props.path,
 			value: value.value,
@@ -497,11 +533,7 @@ var not_array_field_default = /* @__PURE__ */ defineComponent({
 				isValidating.value = false;
 			}
 		};
-		/**
-		* Re-aligns itemKeys with the current array length.
-		* Called at the start of every mutation so keys stay consistent
-		* after external changes (e.g. form.reset()).
-		*/
+		/** Re-aligns itemKeys with the current array length. */
 		const syncKeys = () => {
 			const arrayLength = array.value.length;
 			if (itemKeys.value.length > arrayLength) itemKeys.value.length = arrayLength;
@@ -513,7 +545,6 @@ var not_array_field_default = /* @__PURE__ */ defineComponent({
 		* automatically via the computed above so no explicit dirty call is needed here.
 		*/
 		const mutate = (updater) => {
-			syncKeys();
 			const current = [...array.value];
 			updater(current);
 			setProperty(form.values, props.path, current);
@@ -562,21 +593,16 @@ var not_array_field_default = /* @__PURE__ */ defineComponent({
 			if (validateOn.value.onMount) validate();
 		});
 		/**
-		* Syncs `itemKeys` whenever the underlying array changes outside of this
-		* component's own mutation methods — most commonly after `form.reset()`.
-		*
-		* Without this, `itemKeys` would be stale until the next mutation:
-		* - If the reset shrinks the array, a subsequent `append` would call
-		*   `syncKeys` and regenerate keys for the surviving items, causing
-		*   Vue to remount them unnecessarily.
-		* - If the reset grows the array, items render with `fallback` keys
-		*   until the next mutation, breaking key stability guarantees.
+		* Syncs `itemKeys` when the array length changes outside of this component's
+		* own mutation methods — most commonly after `form.reset()`.
 		*
-		* Our own mutations already manage keys explicitly before writing to
-		* the array, so when this watcher fires after them, `syncKeys` is a
-		* cheap no-op (lengths already match).
+		* Watching `length` rather than the full array avoids unnecessary syncs on
+		* `update()` and `swap()`, which mutate values but never add or remove items.
+		* When our own mutations run, they manage keys explicitly before writing to
+		* the array, so by the time this watcher fires the lengths already match and
+		* `syncKeys` is a cheap no-op.
 		*/
-		watch(array, () => syncKeys());
+		watch(() => array.value.length, syncKeys);
 		const slotProps = computed(() => ({
 			path: props.path,
 			items: items.value,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notform",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.0-beta.2",
   "type": "module",
   "private": false,
   "description": "Vue Forms Without the Friction",