notform 2.2.3 → 2.2.4

package/README.md

@@ -1,14 +1,16 @@
 <div align="center">
 <h1><code>notform</code></h1>
-<p><strong>Headless Form Management, Seamlessly Integrated with Nuxt</strong></p>
+<p><strong>Headless form management for Vue 3</strong></p>
 <p>
-<a href="https://npmx.dev/package/notform"><img src="https://img.shields.io/npm/v/notform.svg?style=plastic&label=NPM%20Version" alt="NPM Version"></a>
-<a href="https://npmx.dev/package/notform"><img src="https://img.shields.io/npm/dt/notform.svg?style=plastic&label=NPM%20Downloads&color=blue" alt="NPM Downloads"></a>
-<a href="https://npmx.dev/package/notform"><img src="https://img.shields.io/npm/unpacked-size/notform?style=plastic&label=NPM%20Unpacked%20Size&color=blue" alt="NPM Unpacked Size"></a>
+<a href="https://npmx.dev/package/notform"><img src="https://img.shields.io/npm/v/notform.svg?style=plastic&label=Version" alt="Version"></a>
+<a href="https://npmx.dev/package/notform"><img src="https://img.shields.io/npm/dm/notform.svg?style=plastic&label=Downloads&color=blue" alt="Downloads"></a>
+<a href="https://npmx.dev/package/notform"><img src="https://img.shields.io/npm/unpacked-size/notform?style=plastic&label=Unpacked%20Size" alt="Unpacked Size"></a>
 </p>
 </div>
 
-`notform` is the core package of the NotForm ecosystem. It provides headless form validation and state management for Vue 3 applications. Built with TypeScript from the ground up, it offers a composable API that integrates perfectly with Vue 3's Composition API and works with any Standard Schema-compatible validator.
+`notform` is the core NotForm package for Vue 3.
+
+It provides reactive form state, schema-based validation, field state, submission handling, and renderless components that work with any UI you choose.
 
 ## Installation
 
@@ -16,35 +18,31 @@
 pnpm add notform
 ```
 
-## How It Works
-
-NotForm follows a **headless, composable-first** approach. Forms are managed through the `useNotForm` composable which handles validation, state, and submission logic in a type-safe manner.
+Install a Standard Schema-compatible validator separately, for example:
 
-Each form consists of:
-
-- **A schema** — Defined using any validation library that supports [Standard Schema](https://standardschema.dev) (Zod, Valibot, ArkType, etc.)
-- **Form state** — Managed reactively with full TypeScript support
-- **Validation** — Automatic validation based on your schema with error messages
-- **Submission handling** — Built-in submission lifecycle with loading states
-- **Your UI** — NotForm renders nothing—you bring your own components
+```bash
+pnpm add zod
+```
 
 ## Basic Usage
 
-Import the components and composable you need:
-
 ```vue
 <script setup lang="ts">
 import { NotField, NotForm, NotMessage, useNotForm } from 'notform'
 import { z } from 'zod'
 
 const schema = z.object({
-  email: z.email('Invalid email'),
-  name: z.string().min(1, 'Name is required'),
+  email: z.email('Enter a valid email address'),
+  name: z.string('Enter a valid name'),
 })
 
 const form = useNotForm({
+  initialValues: {
+    email: '',
+    name: '',
+  },
   onSubmit(values) {
-    console.log('Form:', values)
+    console.log('Submitted:', values)
   },
   schema,
 })
@@ -52,42 +50,48 @@ const form = useNotForm({
 
 <template>
   <NotForm
-    :form
+    :form="form"
     @submit.prevent="form.submit"
     @reset="form.reset()"
   >
     <NotField
-      v-slot="{events,path}"
+      v-slot="{ events, path }"
       path="name"
     >
-      <label :for="path">
-        Name
+      <div>
+        <label :for="path">Name</label>
+
         <input
-          v-bind="events"
           :id="path"
           v-model="form.values.name"
+          v-bind="events"
+          name="name"
           type="text"
+          autocomplete="name"
         >
-      </label>
 
-      <NotMessage :path="path" />
+        <NotMessage :path="path" />
+      </div>
     </NotField>
 
     <NotField
-      v-slot="{events,path}"
+      v-slot="{ events, path }"
       path="email"
     >
-      <label :for="path">
-        Email
+      <div>
+        <label :for="path">Email address</label>
+
         <input
-          v-bind="events"
           :id="path"
           v-model="form.values.email"
+          v-bind="events"
+          name="email"
           type="email"
+          autocomplete="email"
         >
-      </label>
 
-      <NotMessage :path="path" />
+        <NotMessage :path="path" />
+      </div>
     </NotField>
 
     <button type="submit">
@@ -95,116 +99,87 @@ const form = useNotForm({
     </button>
 
     <button type="reset">
-      Reset Form
+      Reset
     </button>
   </NotForm>
 </template>
 ```
 
-## Array Fields
+## API
 
-NotForm includes built-in support for dynamic array fields with add, remove, and reorder operations:
+The core package exports:
 
-```vue
-<script setup lang="ts">
-import { NotArrayField, NotField, NotForm, NotMessage, useNotForm } from 'notform'
-import { z } from 'zod'
+- `useNotForm`
+- `NotForm`
+- `NotField`
+- `NotMessage`
+- `NotArrayField`
 
-const tagSchema = z.string().min(1, 'Tag cannot be empty')
+The form instance manages values, errors, touched and dirty state, validation, submission state, and reset behavior.
 
-const schema = z.object({
-  tags: z.array(tagSchema).min(1, 'At least one tag is required'),
-})
+## Array Fields
 
-const form = useNotForm({
-  schema,
-})
-</script>
+`NotArrayField` provides renderless operations for dynamic arrays while preserving stable item keys during reordering.
 
-<template>
-  <NotForm
-    :form
-    @submit.prevent="form.submit"
+```vue
+<NotArrayField
+  path="tags"
+  v-slot="{ items, append, remove }"
+>
+  <div
+    v-for="(item, index) in items"
+    :key="item.key"
   >
-    <NotArrayField
-      v-slot="{ items, append, remove }"
-      path="tags"
-      :item-schema="tagSchema"
-    >
-      <div
-        v-for="(item, index) in items"
-        :key="item.key"
+    <NotField :path="item.path" v-slot="{ events, path }">
+      <label :for="path">Tag {{ index + 1 }}</label>
+      <input
+        :id="path"
+        v-model="form.values.tags[index]"
+        v-bind="events"
+        :name="path"
+        type="text"
       >
-        <NotField
-          v-slot="{ events }"
-          :path="item.path"
-        >
-          <input
-            v-bind="events"
-            :id="item.path"
-            v-model="form.values.tags[index]"
-            type="text"
-          >
-        </NotField>
-
-        <button
-          type="button"
-          @click="remove(index)"
-        >
-          Remove
-        </button>
-      </div>
+      <NotMessage :path="path" />
+    </NotField>
 
-      <button
-        type="button"
-        @click="append('')"
-      >
-        Add Tag
-      </button>
+    <button type="button" @click="remove(index)">
+      Remove
+    </button>
+  </div>
 
-      <NotMessage path="tags" />
-    </NotArrayField>
-  </NotForm>
-</template>
+  <button type="button" @click="append('')">
+    Add tag
+  </button>
+</NotArrayField>
 ```
 
-## Validation Libraries
-
-NotForm works with any validation library that implements the Standard Schema interface:
+## Type Safety
 
-- **Zod** — TypeScript-first schema validation
-- **Valibot** — Modular and type-safe schema validation
-- **ArkType** — High-performance runtime type checking
-- And any other Standard Schema-compatible library
+Field paths and related APIs are inferred from your schema, including nested paths.
 
-## Components and Composables
-
-### Composables
-
-- `useNotForm` — Main composable for creating form instances
-
-### Components
+```ts
+form.setValue('email', 'jane@example.com')
+await form.validateField('email')
+const errors = form.getFieldErrors('email')
+```
 
-- `NotForm` — Form wrapper component that provides form context
-- `NotField` — Field component for individual form inputs
-- `NotMessage` — Error message display component
-- `NotArrayField` — Array field component for dynamic form arrays
+## Requirements
 
-## Features
+- Vue 3
+- Node.js 24 or later for development in this repository
+- A Standard Schema-compatible validator
 
-- **Headless** — Renders nothing. You bring the UI, NotForm brings the logic.
-- **Schema-agnostic** — Works with any Standard Schema validator (Zod, Valibot, ArkType, etc.)
-- **Type-safe** — Full TypeScript support with inferred types from your schema
-- **Composable** — Built for Vue 3 Composition API with a clean, intuitive API
-- **Lightweight** — Tiny footprint with tree-shaking support
-- **Array fields** — Built-in support for dynamic array fields with add/remove operations
-- **Flexible** — Use with any UI library—native HTML, Nuxt UI, Shadcn, or your own components
+## Development
 
-## Documentation
+From the repository root:
 
-For detailed guides, API reference, and examples, visit:
-**[notformdocs.vercel.app](https://notformdocs.vercel.app/)**
+```bash
+pnpm install
+pnpm --filter notform test
+pnpm --filter notform typecheck
+pnpm --filter notform build
+```
 
 ## License
 
-[MIT](../../LICENSE) &copy; [Favour Emeka](https://github.com/favorodera)
+[MIT](../../LICENSE) © [Favour Emeka](https://github.com/favorodera)

package/dist/index.d.ts

@@ -125,12 +125,14 @@ type NotFormInstance<TSchema extends ObjectSchema> = Raw<{
    *
    * Useful for deeply nested paths or custom inputs that do not use `v-model`.
    * Does **not** trigger validation — the field's event handlers are responsible for that.
+   * @param path The dot-separated path to the field.
+   * @param value The value to set.
    * @example
    * ```ts
    * form.setValue('address.city', 'Lagos')
    * ```
    */
-  setValue: <const TPath extends Paths<StandardSchemaV1.InferInput<TSchema>>>(path: TPath, value: Get<StandardSchemaV1.InferInput<TSchema>, TPath, {
+  setValue: <TPath extends Paths<StandardSchemaV1.InferInput<TSchema>>>(path: TPath, value: Get<StandardSchemaV1.InferInput<TSchema>, TPath, {
     strict: false;
   }>) => void;
   /**
@@ -143,6 +145,11 @@ type NotFormInstance<TSchema extends ObjectSchema> = Raw<{
   /**
    * Marks a field as touched.
    * Called automatically by the field's `onBlur` handler.
+   * @param path The dot-separated path to the field.
+   * @example
+   * ```ts
+   * form.touchField('address.city')
+   * ```
    */
   touchField: (path: Paths<StandardSchemaV1.InferInput<TSchema>>) => void;
   /** The set of field paths whose current value differs from the initial value. */
@@ -152,6 +159,11 @@ type NotFormInstance<TSchema extends ObjectSchema> = Raw<{
   /**
    * Marks a field as dirty.
    * Called automatically when a field value changes.
+   * @param path The dot-separated path to the field.
+   * @example
+   * ```ts
+   * form.dirtyField('address.city')
+   * ```
    */
   dirtyField: (path: Paths<StandardSchemaV1.InferInput<TSchema>>) => void;
   /** The raw validation issues produced by the last validation run. */
@@ -171,14 +183,31 @@ type NotFormInstance<TSchema extends ObjectSchema> = Raw<{
   /**
    * Replaces an existing error for the same path, or appends it if none exists.
    * Useful for setting server-side errors after submission.
+   * @param error The validation issue to set.
+   * @example
+   * ```ts
+   * form.setError({ message: 'Invalid email', path: ['email'] })
+   * ```
    */
   setError: (error: StandardSchemaV1.Issue) => void;
-  /** Replaces all current errors with the provided issues. */
+  /**
+   * Replaces all current errors with the provided issues.
+   * @param errors The validation issues to set.
+   * @example
+   * ```ts
+   * form.setErrors([
+   *   { message: 'Invalid email', path: ['email'] },
+   *   { message: 'Phone number must be at least 11 digits', path: ['phone'] }
+   * ])
+   * ```
+   */
   setErrors: (errors: Array<StandardSchemaV1.Issue>) => void;
   /** Removes all active validation errors. */
   clearErrors: () => void;
   /**
-   * Returns all validation issues for a specific field path.
+   * Get all the validation issues for a specific field path.
+   * @param path The dot-separated path to the field.
+   * @returns An array of validation issues for the given field path.
    * @example
    * ```ts
    * form.getFieldErrors('address.city')
@@ -190,11 +219,18 @@ type NotFormInstance<TSchema extends ObjectSchema> = Raw<{
   /**
    * Validates the entire form against the schema.
    * Replaces all current errors with the result.
+   * @returns A promise that resolves to the result of the validation.
    */
   validate: () => Promise<StandardSchemaV1.Result<StandardSchemaV1.InferOutput<TSchema>>>;
   /**
    * Validates a single field against the schema.
    * Only replaces errors for that field — all other fields are left untouched.
+   * @param path The dot-separated path to the field.
+   * @returns A promise that resolves to the result of the validation.
+   * @example
+   * ```ts
+   * form.validateField('email')
+   * ```
    */
   validateField: (path: Paths<StandardSchemaV1.InferInput<TSchema>>) => Promise<StandardSchemaV1.Result<StandardSchemaV1.InferOutput<TSchema>>>;
   /** Whether the form currently has no validation errors. */
@@ -206,14 +242,8 @@ type NotFormInstance<TSchema extends ObjectSchema> = Raw<{
    *
    * Marks all fields as touched and dirty before validating so all errors surface.
    * If validation fails, submission is aborted.
-   * Bind to the native form's `@submit` event:
-   * @example
-   * ```vue
-   * <template>
-   *   <form v-on:submit="form.submit">
-   *   </form>
-   * </template>
-   * ```
+   * @param event The submit event.
+   * @returns A promise that resolves when the form is submitted.
    */
   submit: (event: SubmitEvent) => Promise<void>;
   /**
@@ -221,13 +251,20 @@ type NotFormInstance<TSchema extends ObjectSchema> = Raw<{
    *
    * Clears all touched and dirty tracking. If `values` or `errors` are passed,
    * they replace the stored baseline so subsequent resets return to the new state.
+   * @param values Optional new values to reset the form to.
+   * @param errors Optional new errors to reset the form to.
    * @example
    * ```ts
    * // Reset to original initial values
    * form.reset()
    *
-   * // Reset to new values (becomes the new baseline)
-   * form.reset({ name: 'Jane' })
+   * // Reset to new values and errors (becomes the new baseline)
+   * form.reset(
+   *  { name: 'Jane' },
+   *  [
+   *    { message: 'Invalid email', path: ['email'] }
+   *  ]
+   * )
    * ```
    */
   reset: (values?: DeepPartial<StandardSchemaV1.InferInput<TSchema>>, errors?: Array<StandardSchemaV1.Issue>) => void;
@@ -254,14 +291,6 @@ interface NotArrayFieldProps<TItemSchema extends StandardSchemaV1 = StandardSche
   /**
    * Schema for a single array item — used purely for type inference.
    * Enables typed `append`, `prepend`, `insert`, and `update` methods in the slot.
-   * @example
-   * ```vue
-   * <template>
-   *   <NotArrayField path="tags" :item-schema="z.string()">
-   *     <!-- append now expects a string -->
-   *   </NotArrayField>
-   * </template>
-   * ```
    */
   itemSchema?: TItemSchema;
   /**
@@ -276,22 +305,9 @@ interface NotArrayFieldProps<TItemSchema extends StandardSchemaV1 = StandardSche
    */
   validateOn?: Partial<Record<Extract<ValidationTrigger, 'onChange' | 'onMount'>, boolean>>;
 }
-/**
- * Represents a single item in the array field.
- * Use `key` for `v-for` tracking and `path` to pass to a nested `NotField`.
- * @example
- * ```vue
- * <template>
- *   <NotArrayField path="tags" v-slot="{ items }">
- *     <NotField v-for="item in items" :key="item.key" :path="item.path" v-slot="{ events }">
- *       <input v-model="form.values.tags[item.index]" v-bind="events" />
- *     </NotField>
- *   </NotArrayField>
- * </template>
- * ```
- */
+/** Represents a single item in the array field. */
 interface NotArrayFieldItem {
-  /** Stable key for `v-for` — does not change when items are reordered. */
+  /** Stable key used for looping — does not change when items are reordered. */
   key: string;
   /** Current index of this item in the array. */
   index: number;
@@ -308,7 +324,7 @@ interface NotArrayFieldSlots<TSchema extends ObjectSchema, TItem = any> {
   default: (props: {
     /** The dot-separated path to this array field. */
     path: string;
-    /** The array items with stable keys and paths for use with `v-for`. */
+    /** The array items with stable keys and paths. */
     items: Array<NotArrayFieldItem>;
     /** All validation issues for this array field from the last validation run. */
     errors: Array<StandardSchemaV1.Issue>;
@@ -329,6 +345,7 @@ interface NotArrayFieldSlots<TSchema extends ObjectSchema, TItem = any> {
     /**
      * Manually triggers validation for this array field.
      * Useful when mutations are performed programmatically outside of the normal flow.
+     * @returns A promise that resolves to the result of the validation.
      */
     validate: () => ReturnType<NotFormInstance<TSchema>['validateField']>;
     /**
@@ -396,27 +413,12 @@ interface NotFieldProps {
   /**
    * Explicit form instance override.
    * Takes priority over the instance provided by a `NotForm` ancestor.
-   * Required when using `NotField` outside of a `NotForm` (singleton fields).
-   * @example
-   * ```vue
-   * <template>
-   *   <NotField :form="form" path="email" v-slot="{ events }">
-   *     <input v-bind="events" />
-   *   </NotField>
-   * </template>
-   * ```
+   * Required when using `NotField` outside of a `NotForm`.
    */
   form?: NotFormInstance<any>;
   /**
    * Per-field validation trigger overrides.
    * Merged over the form-wide `validateOn` — only the keys you specify are overridden.
-   * @example
-   * ```vue
-   * <template>
-   *   <!-- form validates on blur only, but this field also validates on every input -->
-   *   <NotField :validateOn="{ onInput: true }" path="username" />
-   * </template>
-   * ```
    */
   validateOn?: Partial<Record<ValidationTrigger, boolean>>;
   /**
@@ -429,15 +431,6 @@ interface NotFieldProps {
    *
    * Blur- and submit-triggered validation always runs immediately, regardless
    * of this setting, so the field never feels unresponsive when the user leaves.
-   * @example
-   * ```vue
-   * <template>
-   *   <!-- 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>
-   * </template>
-   * ```
    *
    * Omit or set to `0` to disable debouncing (default behaviour).
    */
@@ -471,6 +464,7 @@ interface NotFieldSlots<TSchema extends ObjectSchema> {
     /**
      * Manually triggers validation for this field.
      * Useful for custom inputs that manage their own interaction events.
+     * @returns A promise that resolves to the result of the validation.
      */
     validate: () => ReturnType<NotFormInstance<TSchema>['validateField']>;
     /**
@@ -539,13 +533,7 @@ interface NotMessageProps {
   /**
    * Explicit form instance override.
    * Takes priority over the instance provided by a `NotForm` ancestor.
-   * Required when using `NotMessage` outside of a `NotForm` (singleton fields).
-   * @example
-   * ```vue
-   * <template>
-   *   <NotMessage :form="form" path="email" />
-   * </template>
-   * ```
+   * Required when using `NotMessage` outside of a `NotForm`.
    */
   form?: NotFormInstance<any>;
 }

package/dist/index.js

@@ -184,6 +184,7 @@ var not_array_field_default = /* @__PURE__ */ defineComponent({
 		const props = __props;
 		const form = useNotFormInstance(props.form);
 		const isValidating = ref(false);
+		const validatingCount = ref(0);
 		/** Counter to ensure absolute uniqueness for generated keys. */
 		const keyCounter = ref(0);
 		/** Stable keys per item that survive reorders, removals, and inserts. */
@@ -216,13 +217,31 @@ var not_array_field_default = /* @__PURE__ */ defineComponent({
 			return form.dirtyFields.has(props.path) || [...form.dirtyFields].some((path) => path.startsWith(`${props.path}.`));
 		});
 		/**
+		* Starts a local field validation execution.
+		*/
+		function beginValidation() {
+			validatingCount.value++;
+			isValidating.value = true;
+		}
+		/**
+		* Ends a local field validation execution.
+		*/
+		function endValidation() {
+			validatingCount.value--;
+			if (validatingCount.value === 0) isValidating.value = false;
+		}
+		/**
 		* Generates a unique key string using the field path and counter.
-		* @returns A unique key string
+		* @returns A unique key string.
 		*/
 		function generateKey() {
 			return `${props.path}-${keyCounter.value++}`;
 		}
-		/** Re-aligns itemKeys with current array length (used mostly after external resets) */
+		/**
+		* Re-aligns itemKeys with current array length.
+		*
+		* Used mostly after external resets.
+		*/
 		function syncKeys() {
 			const arrayLength = array.value.length;
 			if (itemKeys.value.length > arrayLength) itemKeys.value.length = arrayLength;
@@ -230,7 +249,7 @@ var not_array_field_default = /* @__PURE__ */ defineComponent({
 		}
 		/**
 		* Applies an array update, syncs form dirty/touched state, and triggers validation.
-		* @param updater Function that modifies the array
+		* @param updater Function that modifies the array.
 		*/
 		function mutate(updater) {
 			const current = [...array.value];
@@ -242,20 +261,20 @@ var not_array_field_default = /* @__PURE__ */ defineComponent({
 			if (validateOn.value.onChange) validate();
 		}
 		/**
-		* Validates the array field
-		* @returns Promise that resolves to the validation result
+		* Validates the array field.
+		* @returns A promise that resolves to the validation result.
 		*/
 		async function validate() {
-			isValidating.value = true;
+			beginValidation();
 			try {
 				return await form.validateField(props.path);
 			} finally {
-				isValidating.value = false;
+				endValidation();
 			}
 		}
 		/**
-		* Appends an item to the array
-		* @param value The value to append
+		* Appends an item to the array.
+		* @param value The value to append.
 		*/
 		function append(value) {
 			itemKeys.value.push(generateKey());
@@ -264,8 +283,8 @@ var not_array_field_default = /* @__PURE__ */ defineComponent({
 			});
 		}
 		/**
-		* Prepends an item to the array
-		* @param value The value to prepend
+		* Prepends an item to the array.
+		* @param value The value to prepend.
 		*/
 		function prepend(value) {
 			itemKeys.value.unshift(generateKey());
@@ -275,8 +294,8 @@ var not_array_field_default = /* @__PURE__ */ defineComponent({
 			});
 		}
 		/**
-		* Removes an item from the array
-		* @param index The index of the item to remove
+		* Removes an item from the array.
+		* @param index The item index to remove.
 		*/
 		function remove(index) {
 			itemKeys.value.splice(index, 1);
@@ -287,9 +306,9 @@ var not_array_field_default = /* @__PURE__ */ defineComponent({
 			mutate((current) => current.splice(index, 1));
 		}
 		/**
-		* Inserts an item at a specific index
-		* @param index The index to insert at
-		* @param value The value to insert
+		* Inserts an item at a specific index.
+		* @param index The insertion index.
+		* @param value The value to insert.
 		*/
 		function insert(index, value) {
 			itemKeys.value.splice(index, 0, generateKey());
@@ -300,9 +319,9 @@ var not_array_field_default = /* @__PURE__ */ defineComponent({
 			mutate((current) => current.splice(index, 0, value));
 		}
 		/**
-		* Updates an item at a specific index
-		* @param index The index to update
-		* @param value The new value
+		* Updates an item at a specific index.
+		* @param index The item index to update.
+		* @param value The new item value.
 		*/
 		function update(index, value) {
 			mutate((current) => {
@@ -310,9 +329,9 @@ var not_array_field_default = /* @__PURE__ */ defineComponent({
 			});
 		}
 		/**
-		* Swaps two items in the array
-		* @param indexA The first index
-		* @param indexB The second index
+		* Swaps two items in the array.
+		* @param indexA The first item index.
+		* @param indexB The second item index.
 		*/
 		function swap(indexA, indexB) {
 			const temporaryKey = itemKeys.value[indexA];
@@ -330,9 +349,9 @@ var not_array_field_default = /* @__PURE__ */ defineComponent({
 			});
 		}
 		/**
-		* Moves an item from one index to another
-		* @param from The source index
-		* @param to The destination index
+		* Moves an item from one index to another.
+		* @param from The source index.
+		* @param to The destination index.
 		*/
 		function move(from, to) {
 			const [movedItemKey] = itemKeys.value.splice(from, 1);
@@ -403,9 +422,10 @@ var not_field_default = /* @__PURE__ */ defineComponent({
 		const props = __props;
 		const form = useNotFormInstance(props.form);
 		const isValidating = ref(false);
+		const validatingCount = ref(0);
 		/** Timer handle for the current pending debounced validation. */
 		const debounceTimer = ref();
-		/** Merges per-field overrides with the form-wide validation config */
+		/** Merges per-field overrides with the form-wide validation config. */
 		const validateOn = computed(() => ({
 			...form.validateOn,
 			...props.validateOn
@@ -415,6 +435,16 @@ var not_field_default = /* @__PURE__ */ defineComponent({
 		const isValid = computed(() => errors.value.length === 0);
 		const isTouched = computed(() => form.touchedFields.has(props.path));
 		const isDirty = computed(() => form.dirtyFields.has(props.path));
+		/** Starts a local field validation execution. */
+		function beginValidation() {
+			validatingCount.value++;
+			isValidating.value = true;
+		}
+		/** Ends a local field validation execution. */
+		function endValidation() {
+			validatingCount.value--;
+			if (validatingCount.value === 0) isValidating.value = false;
+		}
 		/** Cancels pending debounced validation on blur/unmount to prevent rogue execution. */
 		function clearDebounce() {
 			if (debounceTimer.value === void 0) return;
@@ -426,7 +456,7 @@ var not_field_default = /* @__PURE__ */ defineComponent({
 			if (dequal(value.value, getProperty(form.initialValues, props.path))) form.dirtyFields.delete(props.path);
 			else form.dirtyField(props.path);
 		}
-		/** Replaces pending validations with a new timer, or runs synchronously if no debounce. */
+		/** Replaces pending debounced validation with a new timer, or runs immediately when no debounce is configured. */
 		function scheduleValidation() {
 			if (!props.debounce) {
 				validate();
@@ -440,11 +470,11 @@ var not_field_default = /* @__PURE__ */ defineComponent({
 		* @returns A promise that resolves to the validation result.
 		*/
 		async function validate() {
-			isValidating.value = true;
+			beginValidation();
 			try {
 				return await form.validateField(props.path);
 			} finally {
-				isValidating.value = false;
+				endValidation();
 			}
 		}
 		/** Handles the blur event for the field. */
@@ -567,12 +597,6 @@ function useNotForm(config) {
 	const touchedFields = reactive(/* @__PURE__ */ new Set());
 	const dirtyFields = reactive(/* @__PURE__ */ new Set());
 	const isSubmitting = ref(false);
-	const isValidating = ref(false);
-	/**
-	* Tracks concurrent validations to keep `isValidating` true until all finish.
-	* @internal
-	*/
-	let validatingCount = 0;
 	const isValid = computed(() => errors.length === 0);
 	const isDirty = computed(() => dirtyFields.size > 0);
 	const isTouched = computed(() => touchedFields.size > 0);
@@ -585,49 +609,77 @@ function useNotForm(config) {
 		}
 		return result;
 	});
+	/** Whether one or more validation operations are currently running. */
+	const isValidating = ref(false);
+	/** Number of validation operations currently in progress. */
+	const validatingCount = ref(0);
+	/** Identifier of the latest validation cycle. */
+	let validationCycle = 0;
+	/** Identifier of the latest validation cycle for each field. */
+	const fieldValidationCycles = /* @__PURE__ */ new Map();
 	/**
-	* Increments validation counter and activates `isValidating`.
-	* @internal
+	* Starts a validation operation.
+	* @returns The identifier of the new validation cycle.
 	*/
-	function beginValidating() {
-		validatingCount++;
+	function beginValidation() {
+		validatingCount.value++;
 		isValidating.value = true;
+		return ++validationCycle;
 	}
 	/**
-	* Decrements validation counter and deactivates `isValidating` when zero.
-	* @internal
+	* Starts a validation operation for a specific field path.
+	* @param path The field path to start validation for.
+	* @returns The identifier of the new validation cycle.
 	*/
-	function endValidating() {
-		validatingCount--;
-		if (validatingCount === 0) isValidating.value = false;
+	function beginFieldValidation(path) {
+		validatingCount.value++;
+		isValidating.value = true;
+		const key = String(path);
+		const cycle = (fieldValidationCycles.get(key) ?? 0) + 1;
+		fieldValidationCycles.set(key, cycle);
+		return cycle;
+	}
+	/**
+	* Checks if the validation cycle for a specific field path is current.
+	* @param path The field path to check.
+	* @param cycle The validation cycle identifier.
+	* @returns Whether the cycle is still current.
+	*/
+	function isCurrentFieldValidation(path, cycle) {
+		return fieldValidationCycles.get(String(path)) === cycle;
+	}
+	/** Marks a validation operation as finished. */
+	function endValidation() {
+		validatingCount.value--;
+		if (validatingCount.value === 0) isValidating.value = false;
+	}
+	/**
+	* Checks whether a validation cycle is still the latest cycle.
+	* @param cycle The validation cycle identifier.
+	* @returns Whether the cycle is still current.
+	*/
+	function isCurrentValidation(cycle) {
+		return cycle === validationCycle;
 	}
 	/**
 	* Resolves and executes the standard schema validation.
-	* @internal
 	* @returns The validation result containing either `value` or `issues`.
 	*/
 	function runSchema() {
 		return toValue(config.schema)["~standard"].validate(values);
 	}
-	/**
-	* Iterates through deeply nested keys to mark all as touched.
-	* @internal
-	*/
+	/** Iterates through deeply nested keys to mark all as touched. */
 	function touchAllFields() {
 		for (const path of deepKeys(values)) touchedFields.add(path);
 	}
 	/**
 	* Removes a specific field path from the dirty tracking set.
-	* @internal
 	* @param path The field path to mark as clean.
 	*/
 	function unDirtyField(path) {
 		dirtyFields.delete(path);
 	}
-	/**
-	* Iterates through deeply nested keys to mark all as dirty.
-	* @internal
-	*/
+	/** Iterates through deeply nested keys to mark all as dirty. */
 	function dirtyAllFields() {
 		for (const path of deepKeys(values)) dirtyFields.add(path);
 	}
@@ -668,7 +720,7 @@ function useNotForm(config) {
 		else errors[existingIndex] = newIssue;
 	}
 	/**
-	* Sets multiple error issues in the errors array, replacing any existing issues.
+	* Sets multiple error issues in the errors array, replacing all existing issues.
 	* @param newIssues The array of issues to set.
 	*/
 	function setErrors(newIssues) {
@@ -689,31 +741,38 @@ function useNotForm(config) {
 	}
 	/**
 	* Validates the entire form against the schema, updating errors and returning the result.
+	*
+	* Only the latest validation cycle is allowed to mutate form validation state.
 	* @returns An object containing either `value` or `issues` based on validation outcome.
 	*/
 	async function validate() {
-		beginValidating();
+		const cycle = beginValidation();
 		try {
 			const result = await runSchema();
-			if (result?.issues) {
-				setErrors([...result.issues]);
-				return { issues: result.issues };
+			if (!isCurrentValidation(cycle)) return result;
+			if (result.issues) {
+				const issues = [...result.issues];
+				setErrors(issues);
+				return { issues };
 			}
 			clearErrors();
 			return { value: result.value };
 		} finally {
-			endValidating();
+			endValidation();
 		}
 	}
 	/**
 	* Validates a specific field against the schema, updating errors and returning the result.
+	*
+	* Only the latest validation cycle is allowed to mutate form validation state.
 	* @param path The field path to validate.
 	* @returns An object containing either `value` or `issues` based on validation outcome.
 	*/
 	async function validateField(path) {
-		beginValidating();
+		const cycle = beginFieldValidation(path);
 		try {
 			const result = await runSchema();
+			if (!isCurrentFieldValidation(path, cycle)) return result;
 			const pathSegments = parsePath(path);
 			const staleIndices = [];
 			for (const [index, error] of errors.entries()) if (isIssuePathEqual(error.path, pathSegments)) staleIndices.push(index);
@@ -728,23 +787,33 @@ function useNotForm(config) {
 			}
 			return { value: getProperty(result.value, path) };
 		} finally {
-			endValidating();
+			endValidation();
 		}
 	}
 	/**
 	* Submits the form, validating it and executing the submit handler if provided.
+	*
+	* Duplicate submissions are ignored while a submission is already in progress.
 	* @param event The submit event.
 	*/
 	async function submit(event) {
 		event.preventDefault();
+		if (isSubmitting.value) return;
 		isSubmitting.value = true;
+		const cycle = beginValidation();
 		try {
 			touchAllFields();
 			dirtyAllFields();
-			const result = await validate();
-			if (result?.issues) return;
+			const result = await runSchema();
+			if (!isCurrentValidation(cycle)) return;
+			if (result.issues) {
+				setErrors([...result.issues]);
+				return;
+			}
+			clearErrors();
 			if (config.onSubmit) await config.onSubmit(result.value);
 		} finally {
+			endValidation();
 			isSubmitting.value = false;
 		}
 	}
@@ -754,6 +823,7 @@ function useNotForm(config) {
 	* @param newErrors The new errors to reset the form with.
 	*/
 	function reset(newValues, newErrors) {
+		validationCycle++;
 		if (newValues) initialValues = klona(newValues);
 		if (newErrors) initialErrors = klona(newErrors);
 		const freshValues = klona(initialValues);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "notform",
   "type": "module",
-  "version": "2.2.3",
+  "version": "2.2.4",
   "private": false,
   "description": "Vue Forms Without the Friction",
   "author": "Favour Emeka <favorodera@gmail.com>",
@@ -36,11 +36,11 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=22.0.0",
+    "node": ">=24.0.0",
     "pnpm": ">=11.0.0"
   },
   "peerDependencies": {
-    "vue": "^3.0.0"
+    "vue": "^3.5.0"
   },
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
@@ -49,17 +49,17 @@
     "klona": "^2.0.6"
   },
   "devDependencies": {
-    "@favorodera/eslint-config": "^1.1.2",
-    "@types/node": "^26.2.0",
+    "@favorodera/eslint-config": "^1.1.3",
+    "@types/node": "^26.5.0",
     "@vitejs/plugin-vue": "^6.0.8",
     "@vitest/ui": "^4.1.11",
-    "@vue/test-utils": "^2.4.11",
-    "happy-dom": "^20.11.6",
+    "@vue/test-utils": "^2.5.0",
+    "happy-dom": "^20.14.0",
     "tsdown": "^0.22.14",
-    "type-fest": "^5.7.0",
+    "type-fest": "^5.9.0",
     "vite": "^8.2.2",
     "vitest": "^4.1.11",
-    "vue": "^3.0.0",
+    "vue": "^3.5.0",
     "vue-tsc": "^3.3.11"
   },
   "scripts": {