notform 2.2.5 → 3.0.0

package/dist/index.d.ts

@@ -1,40 +1,50 @@
-import { Component, ComputedRef, MaybeRefOrGetter, Raw, Ref } from "vue";
+import { Component, MaybeRefOrGetter } from "vue";
 import { StandardSchemaV1 } from "@standard-schema/spec";
-import { Get, PartialDeep, Paths as Paths$1 } from "type-fest";
+import { ExcludeStrict, Get, PartialDeep, Paths } from "type-fest";
 //#region src/types/shared.d.ts
+/** Events that can trigger field validation. */
+type ValidationTrigger = 'onBlur' | 'onChange' | 'onInput' | 'onMount';
 /**
- * The validation mode determines when validation occurs.
- * - `lazy`: Validates on blur or submission.
- * - `eager`: Validates on blur, then on every change if an error exists.
- */
-type ValidationMode = 'eager' | 'lazy';
-/**
- * Interaction events that can trigger a validation check for a field.
- * - onBlur: Trigger validation when the field loses focus.
- * - onChange: Trigger validation when the field value is committed.
- * - onInput: Trigger validation on every keystroke.
- * - onMount: Trigger validation when the field is mounted.
- * - onFocus: Trigger validation when the field gains focus.
- */
-type ValidationTrigger = 'onBlur' | 'onChange' | 'onFocus' | 'onInput' | 'onMount';
-/**
- * Constructs a type where all properties of the input type are optional recursively.
- * @template TData The base data structure to transform.
+ * Recursively optional version of `TData`, including array items.
+ * @template TData Source data type.
  */
 type DeepPartial<TData> = PartialDeep<TData, {
   allowUndefinedInNonTupleArrays: true;
   recurseIntoArrays: true;
 }>;
 /**
- * Constructs a type representing all possible dot-separated paths within an object.
- * @template TReference The object type for which to generate paths.
+ * Input type accepted by a Standard Schema.
+ * @template TSchema Validation schema.
+ */
+type InferInput<TSchema extends StandardSchemaV1> = StandardSchemaV1.InferInput<TSchema>;
+/**
+ * Output type produced by a Standard Schema.
+ * @template TSchema Validation schema.
  */
-type Paths<TReference> = Extract<Paths$1<TReference, {
+type InferOutput<TSchema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<TSchema>;
+/** One issue from a Standard Schema validation run. */
+type Issue = StandardSchemaV1.Issue;
+/**
+ * Dot-notated field paths derived from a schema's input type.
+ *
+ * The `| (string & {})` union member is deliberate: it keeps editor
+ * autocomplete suggesting the schema's real paths, while still letting any
+ * arbitrary string through the type checker — needed because a dynamically
+ * built path (e.g. `` `${item.path}.name` ``) can't always be proven to match
+ * the literal union `TypeFestPaths` computes.
+ * @template TSchema Validation schema.
+ */
+type Paths$1<TSchema extends StandardSchemaV1> = Extract<Paths<InferInput<TSchema>, {
   maxRecursionDepth: 10;
 }>, string> | (string & {});
 /**
- * Represents a validation schema for object-based data structures.
- * Complies with the Standard Schema specification.
+ * Standard Schema constrained to object input.
+ *
+ * The `~standard.types.input` check exists purely at the type level, so that
+ * `useNotForm`'s `TSchema` is only inferred when the schema's input type is
+ * actually an `object` — this is what makes passing a non-object schema
+ * (e.g. `z.string()`) a compile-time error rather than a runtime surprise.
+ * @see {@linkcode https://github.com/standard-schema/standard-schema Standard Schema spec}
  */
 type ObjectSchema = StandardSchemaV1 & {
   '~standard': StandardSchemaV1['~standard'] & {
@@ -43,529 +53,508 @@ type ObjectSchema = StandardSchemaV1 & {
     };
   };
 };
-/**
- * Represents a segment of a validation path.
- * It can be either a string (for object properties) or a number (for array indices).
- */
-type Segment = PropertyKey | StandardSchemaV1.PathSegment;
-/**
- * Maps the index an array item occupied before a mutation to the index it
- * occupies after that mutation, or to `undefined` when the mutation removed the
- * item entirely.
- *
- * Each array mutation in `NotArrayField` (`prepend`, `remove`, `insert`,
- * `swap`, `move`) builds one of these to describe exactly how it reshuffles
- * indices, then passes it to `remapArrayFieldState`.
- * @param previousIndex The index the item occupied before the mutation.
- * @returns The index the item occupies after the mutation, or `undefined` if the item was removed.
- */
-type ArrayItemIndexMap = (previousIndex: number) => number | undefined;
 //#endregion
-//#region src/types/use-not-form.d.ts
+//#region src/types/not-form-instance.d.ts
 /**
- * Configuration options for initializing a new form instance.
+ * Full form instance used by field components. `useNotForm` returns {@linkcode NotFormAPI}.
  * @template TSchema The form schema.
  */
-interface UseNotFormConfig<TSchema extends ObjectSchema> {
-  /** The validation schema used to parse and validate form data */
-  schema: MaybeRefOrGetter<TSchema>;
-  /** The initial values of the form */
-  initialValues?: DeepPartial<StandardSchemaV1.InferInput<TSchema>>;
-  /** The initial errors of the form */
-  initialErrors?: Array<StandardSchemaV1.Issue>;
+interface NotFormInstance<TSchema extends ObjectSchema> {
+  /** Live field values. */
+  values: InferInput<TSchema>;
   /**
-   * The validation triggers of the form.
-   * @default { onBlur: true, onChange: true, onInput: true }
+   * Sets a field value by path. Does not validate — validation still only
+   * runs through a field's own configured triggers, or an explicit
+   * {@linkcode validate}/{@linkcode validateField} call.
+   * @template TPath Field path.
+   * @param path Dot path.
+   * @param value Value to assign.
    */
-  validateOn?: Partial<Record<ValidationTrigger, boolean>>;
+  setValue: <TPath extends Paths$1<TSchema>>(path: TPath, value: Get<InferInput<TSchema>, TPath, {
+    strict: false;
+  }>) => void;
+  /** Whether any field is touched. */
+  isTouched: boolean;
   /**
-   * The validation mode of the form.
-   * @default 'eager'
+   * Touched field paths.
+   * @internal
    */
-  validationMode?: ValidationMode;
+  touchedFields: Set<Paths$1<TSchema>>;
   /**
-   * Callback triggered when form validation passes and the form is submitted.
-   * @param values The validated output data from the schema.
+   * Marks a field as touched.
+   * @internal
+   * @param path Dot path.
    */
-  onSubmit?: (values: StandardSchemaV1.InferOutput<TSchema>) => Promise<void> | void;
-}
-//#endregion
-//#region src/types/not-form.d.ts
-/**
- * The complete state and API of a form instance returned by `useNotForm`.
- * @template TSchema The form schema.
- */
-type NotFormInstance<TSchema extends ObjectSchema> = Raw<{
-  /** The values the form was initialised or last reset with. */
-  readonly initialValues: UseNotFormConfig<TSchema>['initialValues'];
-  /** The errors the form was initialised or last reset with. */
-  readonly initialErrors: UseNotFormConfig<TSchema>['initialErrors'];
-  /** The resolved validation triggers for this form. */
-  readonly validateOn: Required<NonNullable<UseNotFormConfig<TSchema>['validateOn']>>;
-  /** The resolved validation mode for this form. */
-  readonly validationMode: Required<NonNullable<UseNotFormConfig<TSchema>['validationMode']>>;
+  markFieldAsTouched: (path: Paths$1<TSchema>) => void;
   /**
-   * Deeply reactive object of field values.
-   * @example
-   * - Access directly — no `.value` needed:
-   * ```ts
-   * form.values.email
-   * ```
-   *
-   * - Use with `v-model` for two-way binding:
-   * ```vue
-   * <template>
-   *   <input v-model="form.values.email" />
-   * </template>
-   * ```
+   * Marks every current leaf field as touched. "Current" matters for arrays:
+   * an empty array contributes no leaf paths, so an item appended afterward
+   * (e.g. via `<NotArrayField>`'s `append`) starts untouched even though
+   * this was already called.
+   * @internal
    */
-  values: StandardSchemaV1.InferInput<TSchema>;
+  markAllFieldsAsTouched: () => void;
   /**
-   * Sets a field value by dot-separated path.
-   *
-   * 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')
-   * ```
+   * Clears touched state for one field.
+   * @internal
+   * @param path Dot path.
    */
-  setValue: <TPath extends Paths<StandardSchemaV1.InferInput<TSchema>>>(path: TPath, value: Get<StandardSchemaV1.InferInput<TSchema>, TPath, {
-    strict: false;
-  }>) => void;
+  unmarkFieldAsTouched: (path: Paths$1<TSchema>) => void;
   /**
-   * The set of field paths the user has interacted with.
-   * Populated for all paths when the form is submitted.
+   * Clears touched state for all fields.
+   * @internal
    */
-  touchedFields: Set<Paths<StandardSchemaV1.InferInput<TSchema>>>;
-  /** Whether any field has been touched. */
-  isTouched: ComputedRef<boolean>;
+  unmarkAllFieldsAsTouched: () => void;
   /**
-   * 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')
-   * ```
+   * Paths whose value differs from the baseline.
+   * @internal
    */
-  touchField: (path: Paths<StandardSchemaV1.InferInput<TSchema>>) => void;
-  /** The set of field paths whose current value differs from the initial value. */
-  dirtyFields: Set<Paths<StandardSchemaV1.InferInput<TSchema>>>;
-  /** Whether any field value differs from its initial value. */
-  isDirty: ComputedRef<boolean>;
+  dirtyFields: Set<Paths$1<TSchema>>;
+  /** Whether any field is dirty. */
+  isDirty: boolean;
   /**
-   * 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')
-   * ```
+   * Updates dirty state by comparing current and baseline values.
+   * @internal
+   * @param path Dot path.
    */
-  dirtyField: (path: Paths<StandardSchemaV1.InferInput<TSchema>>) => void;
-  /** The raw validation issues produced by the last validation run. */
-  errors: Array<StandardSchemaV1.Issue>;
+  syncDirtyState: (path: Paths$1<TSchema>) => void;
   /**
-   * A flat map of field path to its first error message.
-   *
-   * Convenient for direct template access without calling `getFieldErrors`
-   * @example
-   * ```vue
-   * <template>
-   *   <p>{{ form.errorsMap['address.city'] }}</p>
-   * </template>
-   * ```
+   * Updates dirty state for every current leaf field. Subject to the same
+   * "current shape only" caveat as {@linkcode markAllFieldsAsTouched}.
+   * @internal
+   */
+  syncAllDirtyStates: () => void;
+  /**
+   * Forces a field dirty.
+   * @internal
+   * @param path Dot path.
+   */
+  markFieldAsDirty: (path: Paths$1<TSchema>) => void;
+  /**
+   * Forces every current leaf field dirty. Subject to the same
+   * "current shape only" caveat as {@linkcode markAllFieldsAsTouched}.
+   * @internal
+   */
+  markAllFieldsAsDirty: () => void;
+  /**
+   * Clears dirty state for one field.
+   * @internal
+   * @param path Dot path.
    */
-  errorsMap: ComputedRef<Partial<Record<Paths<StandardSchemaV1.InferInput<TSchema>>, string>>>;
+  unmarkFieldAsDirty: (path: Paths$1<TSchema>) => void;
   /**
-   * 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'] })
-   * ```
+   * Clears dirty state for all fields.
+   * @internal
    */
-  setError: (error: StandardSchemaV1.Issue) => void;
+  unmarkAllFieldsAsDirty: () => void;
+  /** Issues from the last validation that wrote errors. */
+  errors: Array<Issue>;
   /**
-   * 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'] }
-   * ])
-   * ```
+   * Upserts an issue at the same path, or appends it.
+   * @param error Issue to set.
+   */
+  setError: (error: Issue) => void;
+  /**
+   * Replaces the entire error list.
+   * @internal
+   * @param errors Replacement issues.
+   */
+  replaceErrors: (errors: Array<Issue>) => void;
+  /**
+   * Removes every issue.
+   * @internal
    */
-  setErrors: (errors: Array<StandardSchemaV1.Issue>) => void;
-  /** Removes all active validation errors. */
   clearErrors: () => void;
   /**
-   * 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')
-   * ```
+   * Issues whose path exactly equals `path` — not issues nested underneath it.
+   *
+   * `getFieldErrors('groups.0')` will not return an issue reported at
+   * `groups.0.name`.
+   *
+   * `<NotArrayField>`'s `isValid`/`isTouched`/`isDirty`/
+   * `isValidating` aggregate recursively instead, for exactly this reason.
+   * @param path Dot path.
+   * @returns Matching issues.
    */
-  getFieldErrors: (path: Paths<StandardSchemaV1.InferInput<TSchema>>) => Array<StandardSchemaV1.Issue>;
-  /** Whether a validation run is currently in progress. */
-  isValidating: Ref<boolean>;
+  getFieldErrors: (path: Paths$1<TSchema>) => Array<Issue>;
+  /** Whether any validation is in flight. */
+  isValidating: boolean;
+  /** Whether there are zero issues. */
+  isValid: boolean;
   /**
-   * 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.
+   * Paths currently validating.
+   * @internal
    */
-  validate: () => Promise<StandardSchemaV1.Result<StandardSchemaV1.InferOutput<TSchema>>>;
+  validatingFields: Set<Paths$1<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')
-   * ```
+   * Validates the whole form and replaces all errors.
+   *
+   * Concurrent calls are last-write-wins: each call still resolves with its
+   * own result, but only the most recently started call's result is written
+   * to `errors` — an older call that resolves later has its result silently
+   * discarded from shared state.
+   * @returns Standard Schema result.
    */
-  validateField: (path: Paths<StandardSchemaV1.InferInput<TSchema>>) => Promise<StandardSchemaV1.Result<StandardSchemaV1.InferOutput<TSchema>>>;
-  /** Whether the form currently has no validation errors. */
-  isValid: ComputedRef<boolean>;
-  /** Whether the form is currently running its submit handler. */
-  isSubmitting: Ref<boolean>;
+  validate: () => Promise<StandardSchemaV1.Result<InferOutput<TSchema>>>;
   /**
-   * Validates the form and runs `onSubmit` if it passes.
+   * Validates the form and writes issues only for `path`.
+   *
+   * `path` can be any granularity — a leaf field, an entire array field, or
+   * a specific item inside one; `<NotField>` and `<NotArrayField>` both call
+   * this with their own `path` internally.
    *
-   * Marks all fields as touched and dirty before validating so all errors surface.
-   * If validation fails, submission is aborted.
-   * @param event The submit event.
-   * @returns A promise that resolves when the form is submitted.
+   * Concurrent calls for the same `path` are last-write-wins, the same as
+   * {@linkcode validate}; a call started after this one, or a whole-form
+   * {@linkcode validate} call, supersedes it.
+   * @param path Dot path.
+   * @returns Standard Schema result.
+   */
+  validateField: (path: Paths$1<TSchema>) => Promise<StandardSchemaV1.Result<InferOutput<TSchema>>>;
+  /** Whether `onSubmit` is running. */
+  isSubmitting: boolean;
+  /**
+   * Touches all fields, validates, then runs `onSubmit` when valid.
+   * @param event Optional submit event. When given, `event.preventDefault()`
+   * is called immediately, before anything else — including before checking
+   * whether a submission is already in flight or whether validation passes.
    */
-  submit: (event: SubmitEvent) => Promise<void>;
+  submit: (event?: SubmitEvent) => Promise<void>;
   /**
-   * Resets the form to its initial state, or to new values and errors if provided.
+   * Restores values/errors to the baseline. Optional arguments become the
+   * new baseline, and reset to it immediately.
    *
-   * 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()
+   * `values`/`errors`, when given, fully replace the previous baseline —
+   * they are not merged with it. Any top-level key present in the old
+   * baseline but missing from `values` is simply gone afterward, the same
+   * way `initialValues`/`initialErrors` passed to `useNotForm` become the
+   * literal starting baseline rather than defaults merged with something
+   * else.
    *
-   * // Reset to new values and errors (becomes the new baseline)
-   * form.reset(
-   *  { name: 'Jane' },
-   *  [
-   *    { message: 'Invalid email', path: ['email'] }
-   *  ]
-   * )
-   * ```
+   * Also bumps the internal validation generation, so any `validate()`/
+   * `validateField()` call already in flight when this runs will still
+   * resolve with its own result, but will not write its issues to `errors`.
+   * @param values New baseline values.
+   * @param errors New baseline issues.
    */
-  reset: (values?: DeepPartial<StandardSchemaV1.InferInput<TSchema>>, errors?: Array<StandardSchemaV1.Issue>) => void;
-}>;
-/** Props for the `NotForm` component. */
-interface NotFormProps {
-  /** The form instance to provide to all descendant `NotField` components. */
-  form: NotFormInstance<any>;
-}
-/** Slots for the `NotForm` component. */
-interface NotFormSlots {
-  /** The default slot receives the full form instance */
-  default?: () => any;
+  reset: (values?: DeepPartial<InferInput<TSchema>>, errors?: Array<Issue>) => void;
 }
 //#endregion
+//#region src/types/not-form-api.d.ts
+/**
+ * Public API from `useNotForm`: {@linkcode NotFormInstance} without `@internal` members.
+ *
+ * The excluded members are the path-set accessors and mutation helpers that
+ * `<NotField>` and `<NotArrayField>` use directly — `touchedFields`,
+ * `markFieldAsTouched`, `dirtyFields`, `syncDirtyState`, `validatingFields`,
+ * `replaceErrors`, `clearErrors`, and their siblings. Application code
+ * normally reaches the same information through `isTouched`/`isDirty`/
+ * `isValidating`, or through a specific field's own slot props, rather than
+ * these lower-level sets and setters directly.
+ * @template TSchema The form schema.
+ */
+type NotFormAPI<TSchema extends ObjectSchema> = Pick<NotFormInstance<TSchema>, 'errors' | 'getFieldErrors' | 'isDirty' | 'isSubmitting' | 'isTouched' | 'isValid' | 'isValidating' | 'reset' | 'setError' | 'setValue' | 'submit' | 'validate' | 'validateField' | 'values'>;
+//#endregion
 //#region src/types/not-array-field.d.ts
 /**
- * Props for the `NotArrayField` component.
- * @template TItemSchema The schema for a single array item.
+ * One array item from `<NotArrayField>`'s default slot.
+ * @template TSchema The form schema.
  */
-interface NotArrayFieldProps<TItemSchema extends StandardSchemaV1 = StandardSchemaV1> {
-  /** Dot-separated path to the array within the form values. */
-  path: string;
+interface NotArrayFieldItem<TSchema extends ObjectSchema> {
+  /** Stable identity for `v-for` `:key`. Independent of the current index. */
+  key: string;
+  /** Dot path of this item at its **current** index. */
+  path: Paths$1<TSchema>;
+  /** Current position in the array. */
+  index: number;
+}
+/**
+ * Props for `<NotArrayField>`.
+ * @template TSchema The form schema.
+ * @template TItemSchema Item schema used only to type mutation helpers.
+ */
+interface NotArrayFieldProps<TSchema extends ObjectSchema, TItemSchema extends StandardSchemaV1 = StandardSchemaV1> {
+  /** Dot path of the array field. */
+  path: Paths$1<TSchema>;
   /**
-   * Schema for a single array item — used purely for type inference.
-   * Enables typed `append`, `prepend`, `insert`, and `update` methods in the slot.
+   * Item schema for type inference only; never read at runtime. Does not
+   * validate items — array items are still validated through the form's
+   * own schema, the same as any other field.
    */
   itemSchema?: TItemSchema;
-  /**
-   * Explicit form instance override.
-   * Takes priority over the instance provided by a `NotForm` ancestor.
-   * Required when using `NotArrayField` outside of a `NotForm`.
-   */
-  form?: NotFormInstance<any>;
-  /**
-   * Per-field validation trigger overrides applied to the array as a whole.
-   * Merged over the form-wide `validateOn` — only the keys you specify are overridden.
-   */
-  validateOn?: Partial<Record<Extract<ValidationTrigger, 'onChange' | 'onMount'>, boolean>>;
-}
-/** Represents a single item in the array field. */
-interface NotArrayFieldItem {
-  /** Stable key used for looping — does not change when items are reordered. */
-  key: string;
-  /** Current index of this item in the array. */
-  index: number;
-  /** Full dot-separated path to this item — pass directly to `NotField`. */
-  path: string;
+  /** Form instance. Overrides `<NotForm>` inject. Required outside `<NotForm>`. */
+  form?: NotFormAPI<TSchema>;
 }
 /**
- * Slots for the `NotArrayField` component.
+ * Slot props for `<NotArrayField>`.
  * @template TSchema The form schema.
- * @template TItem An array field item.
+ * @template TItemSchema Item schema used only to type mutation helpers.
  */
-interface NotArrayFieldSlots<TSchema extends ObjectSchema, TItem = any> {
-  /** The default slot receives the full array state and manipulation methods. */
-  default: (props: {
-    /** The dot-separated path to this array field. */
+interface NotArrayFieldSlots<TSchema extends ObjectSchema, TItemSchema extends StandardSchemaV1 = StandardSchemaV1> {
+  default?: (props: {
+    /** Dot path of the array field. */
     path: string;
-    /** 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>;
-    /** Whether this array field currently has no validation errors. */
+    /** Current items, each with a stable key and current path. */
+    items: Array<NotArrayFieldItem<TSchema>>;
+    /**
+     * Issues reported exactly at the array field's own path — not issues
+     * from individual items.
+     *
+     * The same exact-match behavior as `<NotField>`'s `errors`.
+     *
+     * See {@linkcode isValid} for the aggregate that also accounts for item-level issues.
+     */
+    errors: Array<Issue>;
+    /**
+     * Whether the array field's own path, and every path nested underneath
+     * it, have no issues — an item's own value, a field inside an object
+     * item, or an item inside a nested array, at any depth.
+     *
+     * Unlike {@linkcode errors}, this recurses.
+     */
     isValid: boolean;
     /**
-     * Whether any item in this array has been touched.
-     * Derived from the form's `touchedFields` set.
+     * Whether the array field's own path, or any path nested underneath it, has been touched.
+     *
+     * Recurses the same way as {@linkcode isValid}.
      */
     isTouched: boolean;
     /**
-     * Whether any item in this array differs from its initial value.
-     * Derived from the form's `dirtyFields` set.
+     * Whether the array field's own path, or any path nested underneath it, differs from the baseline.
+     *
+     * Recurses the same way as {@linkcode isValid}.
      */
     isDirty: boolean;
-    /** Whether validation is currently running for this array field. */
-    isValidating: boolean;
     /**
-     * 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.
+     * Whether the array field's own path, or any path nested underneath it, is currently validating.
+     *
+     * Recurses the same way as {@linkcode isValid}.
      */
-    validate: () => ReturnType<NotFormInstance<TSchema>['validateField']>;
+    isValidating: boolean;
     /**
-     * Appends a new item to the end of the array.
-     * @param value The value to append.
+     * Appends a value at the end.
+     * @param value Value to append.
      */
-    append: (value: TItem) => void;
+    append: (value: InferInput<TItemSchema>) => void;
     /**
-     * Prepends a new item to the beginning of the array.
-     * @param value The value to prepend.
+     * Inserts a value at the start. Shifts every existing item's own
+     * state — at any depth underneath it — forward by one position along
+     * with it.
+     * @param value Value to prepend.
      */
-    prepend: (value: TItem) => void;
+    prepend: (value: InferInput<TItemSchema>) => void;
     /**
-     * Removes the item at the given index.
-     * @param index The index of the item to remove.
+     * Inserts a value at `index`, shifting later items — and their own
+     * state, at any depth underneath them — back by one position.
+     * @param index Insertion index.
+     * @param value Value to insert.
      */
-    remove: (index: number) => void;
+    insert: (index: number, value: InferInput<TItemSchema>) => void;
     /**
-     * Inserts a new item at the given index, shifting subsequent items forward.
-     * @param index The index to insert the item at.
-     * @param value The value to insert.
+     * Removes the item at `index`. That item's own state — at any depth
+     * underneath it — is discarded along with it; every later item's state
+     * shifts back by one position to follow it to its new index.
+     * @param index Index to remove.
      */
-    insert: (index: number, value: TItem) => void;
+    remove: (index: number) => void;
     /**
-     * Replaces the value at the given index.
-     * @param index The index of the item to replace.
-     * @param value The value to replace with.
+     * Replaces the value at `index` without changing its key.
+     * @param index Index to update.
+     * @param value New value.
      */
-    update: (index: number, value: TItem) => void;
+    update: (index: number, value: InferInput<TItemSchema>) => void;
     /**
-     * Swaps the positions of two items in the array.
-     * @param indexA The index of the first item.
-     * @param indexB The index of the second item.
+     * Swaps two items, moving keys and form state — at any depth
+     * underneath each item — with them.
+     * @param indexA First index.
+     * @param indexB Second index.
      */
     swap: (indexA: number, indexB: number) => void;
     /**
-     * Moves an item from one index to another, shifting items between them.
-     * @param from The current index of the item.
-     * @param to The target index.
+     * Moves an item from `from` to `to`, moving keys and form state — at
+     * any depth underneath it — with it.
+     * @param from Current index.
+     * @param to Destination index.
      */
     move: (from: number, to: number) => void;
-  }) => any;
+  }) => void;
 }
 //#endregion
 //#region src/components/not-array-field.vue.d.ts
-declare const __VLS_export$3: <TSchema extends ObjectSchema, TItemSchema extends StandardSchemaV1 = StandardSchemaV1, TItem = StandardSchemaV1.InferInput<TItemSchema>>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal$1<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
-  props: import("vue").PublicProps & __VLS_PrettifyLocal$1<NotArrayFieldProps<TItemSchema>> & (typeof globalThis extends {
+declare const __VLS_export$3: <TSchema extends ObjectSchema, TItemSchema extends StandardSchemaV1 = StandardSchemaV1>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal$3<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+  props: import("vue").PublicProps & __VLS_PrettifyLocal$3<NotArrayFieldProps<TSchema, TItemSchema>> & (typeof globalThis extends {
     __VLS_PROPS_FALLBACK: infer P;
   } ? P : {});
   expose: (exposed: {}) => void;
   attrs: any;
-  slots: NotArrayFieldSlots<TSchema, TItem>;
+  slots: NotArrayFieldSlots<TSchema, TItemSchema>;
   emit: {};
 }>) => import("vue").VNode & {
   __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
 };
 declare const _default: typeof __VLS_export$3;
-type __VLS_PrettifyLocal$1<T> = (T extends any ? { [K in keyof T]: T[K]; } : { [K in keyof T as K]: T[K]; }) & {};
+type __VLS_PrettifyLocal$3<T> = (T extends any ? { [K in keyof T]: T[K]; } : { [K in keyof T as K]: T[K]; }) & {};
 //#endregion
 //#region src/types/not-field.d.ts
-/** Props for the `NotField` component. */
-interface NotFieldProps {
-  /** Dot-separated path to this field within the form values. */
-  path: string;
-  /**
-   * Explicit form instance override.
-   * Takes priority over the instance provided by a `NotForm` ancestor.
-   * Required when using `NotField` outside of a `NotForm`.
-   */
-  form?: NotFormInstance<any>;
+/**
+ * Props for `<NotField>`.
+ * @template TSchema The form schema.
+ */
+interface NotFieldProps<TSchema extends ObjectSchema> {
+  /** Dot path of this field. */
+  path: Paths$1<TSchema>;
+  /** Form instance. Overrides `<NotForm>` inject. Required outside `<NotForm>`. */
+  form?: NotFormAPI<TSchema>;
   /**
-   * Per-field validation trigger overrides.
-   * Merged over the form-wide `validateOn` — only the keys you specify are overridden.
+   * Validation triggers merged over `{ onBlur: true, onChange: true }`.
+   *
+   * `onMount` is also a valid trigger here, even though it has no matching
+   * entry in `events` slot prop — there's no DOM event to bind for "the field
+   * just appeared," so it runs automatically, once, when the field mounts.
+   * @default { onBlur: true, onChange: true }
    */
   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.
-   *
-   * Omit or set to `0` to disable debouncing (default behaviour).
+   * `lazy` — blur/submit only. `eager` — also revalidate on change/input while invalid.
+   * @default 'eager'
    */
+  validationMode?: 'eager' | 'lazy';
+  /** Debounce in ms for input/change validation. Blur always runs immediately. */
   debounce?: number;
 }
-/**
- * Slots for the `NotField` component.
- * @template TSchema The form schema.
- */
-interface NotFieldSlots<TSchema extends ObjectSchema> {
-  /** The default slot receives the full field state and event handlers. */
+/** Slot props for `<NotField>`. */
+interface NotFieldSlots {
   default?: (props: {
-    /** The dot-separated path to this field. */
-    path: string;
+    /** Issues for this field path. */
+    errors: Array<Issue>;
     /**
-     * The current value of this field — read-only snapshot for display purposes.
-     * Do not mutate directly or use with `v-model`.
-     * For two-way binding use `v-model="form.values.fieldName"` instead.
+     * Handlers to bind to the input. `onMount` is deliberately excluded —
+     * see the note on `validateOn` prop for why.
      */
-    value: any;
-    /** All validation issues for this field from the last validation run. */
-    errors: Array<StandardSchemaV1.Issue>;
-    /** Whether this field currently has no validation errors. */
-    isValid: boolean;
-    /** Whether the user has interacted with this field, or the form has been submitted. */
-    isTouched: boolean;
-    /** Whether this field's current value differs from its initial value. */
+    events: Record<ExcludeStrict<ValidationTrigger, 'onMount'>, () => void>;
+    /** Whether the value differs from the baseline. */
     isDirty: boolean;
-    /** Whether an async validator is currently running for this field. */
+    /** Whether the user has interacted with this field. */
+    isTouched: boolean;
+    /** Whether this field has no issues. */
+    isValid: boolean;
+    /** Whether this field is currently validating. */
     isValidating: boolean;
-    /**
-     * 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']>;
-    /**
-     * Native DOM event handlers exposed by a field.
-     * Spread onto a native input or bind individually to custom components.
-     * @example
-     * ```vue
-     * <template>
-     *   <!-- spread -->
-     *   <input v-bind="events" />
-     *
-     *   <!-- individual -->
-     *   <CustomCombobox v-on:focusout="events.onBlur" v-on:pick="events.onChange" />
-     * </template>
-     * ```
-     */
-    events: {
-      /** Triggered when the field loses focus. */
-      onBlur: () => void;
-      /** Triggered on every keystroke or value change. */
-      onInput: () => void;
-      /** Triggered when the field value is committed. */
-      onChange: () => void;
-      /** Triggered when the field gains focus. */
-      onFocus: () => void;
-    };
-  }) => any;
+    /** Dot path of this field. */
+    path: string;
+  }) => void;
 }
 //#endregion
 //#region src/components/not-field.vue.d.ts
-declare const __VLS_export$2: <TSchema extends ObjectSchema>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
-  props: import("vue").PublicProps & __VLS_PrettifyLocal<NotFieldProps> & (typeof globalThis extends {
+declare const __VLS_export$2: <TSchema extends ObjectSchema>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal$2<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+  props: import("vue").PublicProps & __VLS_PrettifyLocal$2<NotFieldProps<TSchema>> & (typeof globalThis extends {
     __VLS_PROPS_FALLBACK: infer P;
   } ? P : {});
   expose: (exposed: {}) => void;
   attrs: any;
-  slots: NotFieldSlots<TSchema>;
+  slots: NotFieldSlots;
   emit: {};
 }>) => import("vue").VNode & {
   __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
 };
 declare const _default$1: typeof __VLS_export$2;
-type __VLS_PrettifyLocal<T> = (T extends any ? { [K in keyof T]: T[K]; } : { [K in keyof T as K]: T[K]; }) & {};
+type __VLS_PrettifyLocal$2<T> = (T extends any ? { [K in keyof T]: T[K]; } : { [K in keyof T as K]: T[K]; }) & {};
+//#endregion
+//#region src/types/not-form.d.ts
+/**
+ * Props for `<NotForm>`.
+ * @template TSchema The form schema.
+ */
+interface NotFormProps<TSchema extends ObjectSchema> {
+  /** Form instance provided to descendant field components. */
+  form: NotFormAPI<TSchema>;
+}
+/** Slot props for `<NotForm>`. */
+interface NotFormSlots {
+  default?: () => void;
+}
 //#endregion
 //#region src/components/not-form.vue.d.ts
-type __VLS_Slots$1 = NotFormSlots;
-declare const __VLS_base$1: import("vue").DefineComponent<NotFormProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<NotFormProps> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
-declare const __VLS_export$1: __VLS_WithSlots$1<typeof __VLS_base$1, __VLS_Slots$1>;
-declare const _default$2: typeof __VLS_export$1;
-type __VLS_WithSlots$1<T, S> = T & {
-  new (): {
-    $slots: S;
-  };
+declare const __VLS_export$1: <TSchema extends ObjectSchema>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal$1<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+  props: import("vue").PublicProps & __VLS_PrettifyLocal$1<NotFormProps<TSchema>> & (typeof globalThis extends {
+    __VLS_PROPS_FALLBACK: infer P;
+  } ? P : {});
+  expose: (exposed: {}) => void;
+  attrs: any;
+  slots: NotFormSlots;
+  emit: {};
+}>) => import("vue").VNode & {
+  __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
 };
+declare const _default$2: typeof __VLS_export$1;
+type __VLS_PrettifyLocal$1<T> = (T extends any ? { [K in keyof T]: T[K]; } : { [K in keyof T as K]: T[K]; }) & {};
 //#endregion
 //#region src/types/not-message.d.ts
-/** Props for the `NotMessage` component. */
-interface NotMessageProps {
+/**
+ * Props for `<NotMessage>`.
+ * @template TSchema The form schema.
+ */
+interface NotMessageProps<TSchema extends ObjectSchema> {
   /**
-   * HTML Tag or component to render as
-   * @default span
+   * Root element or component. When a component is given, the message is
+   * passed to it as **default slot content**, not as a prop — a component
+   * expecting a `message` prop instead will render with no visible text.
+   * @default 'span'
    */
   as?: Component | string;
-  /** The name/path of the field whose error message should be displayed */
-  path: string;
-  /**
-   * Explicit form instance override.
-   * Takes priority over the instance provided by a `NotForm` ancestor.
-   * Required when using `NotMessage` outside of a `NotForm`.
-   */
-  form?: NotFormInstance<any>;
+  /** Field path whose first error message is shown. */
+  path: Paths$1<TSchema>;
+  /** Form instance. Overrides `<NotForm>` inject. Required outside `<NotForm>`. */
+  form?: NotFormAPI<TSchema>;
 }
-/** Slots for the `NotMessage` component. */
+/** Slot props for `<NotMessage>`. */
 interface NotMessageSlots {
-  /** The default slot receives the error message context for custom rendering */
   default?: (props: {
-    /** The first active validation error message for the specified field */
+    /** First active error message for `path`. */
     message?: string;
-  }) => any;
+  }) => void;
 }
 //#endregion
 //#region src/components/not-message.vue.d.ts
-type __VLS_Slots = NotMessageSlots;
-declare const __VLS_base: import("vue").DefineComponent<NotMessageProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<NotMessageProps> & Readonly<{}>, {
-  as: import("vue").Component | string;
-}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
-declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
-declare const _default$3: typeof __VLS_export;
-type __VLS_WithSlots<T, S> = T & {
-  new (): {
-    $slots: S;
-  };
+declare const __VLS_export: <TSchema extends ObjectSchema>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+  props: import("vue").PublicProps & __VLS_PrettifyLocal<NotMessageProps<TSchema>> & (typeof globalThis extends {
+    __VLS_PROPS_FALLBACK: infer P;
+  } ? P : {});
+  expose: (exposed: {}) => void;
+  attrs: any;
+  slots: NotMessageSlots;
+  emit: {};
+}>) => import("vue").VNode & {
+  __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
 };
+declare const _default$3: typeof __VLS_export;
+type __VLS_PrettifyLocal<T> = (T extends any ? { [K in keyof T]: T[K]; } : { [K in keyof T as K]: T[K]; }) & {};
+//#endregion
+//#region src/types/not-form-config.d.ts
+/**
+ * Options passed to `useNotForm`.
+ * @template TSchema Validation schema.
+ */
+interface UseNotFormConfig<TSchema extends ObjectSchema> {
+  /** Schema used to parse and validate values. */
+  schema: MaybeRefOrGetter<TSchema>;
+  /** Starting values; deep-cloned before use. */
+  initialValues?: DeepPartial<InferInput<TSchema>>;
+  /** Issues shown before the first validation run. */
+  initialErrors?: Array<Issue>;
+  /**
+   * Called after a successful submit validation.
+   * @param data Validated output.
+   */
+  onSubmit?: (data: InferOutput<TSchema>) => Promise<void> | void;
+}
 //#endregion
 //#region src/composables/use-not-form.d.ts
 /**
- * Creates a reactive NotFormInstance for managing form state and validation.
- * @template TSchema The standard schema type.
- * @param config Configuration object.
- * @returns A reactive NotFormInstance.
+ * Creates a form instance and returns the public {@linkcode NotFormAPI}.
+ * @template TSchema The form schema.
+ * @param config Schema, initial values/errors, and submit handler.
+ * @returns Public form API. Child components still inject the full instance via `<NotForm>`.
  */
-declare function useNotForm<TSchema extends ObjectSchema>(config: UseNotFormConfig<TSchema>): NotFormInstance<TSchema>;
+declare function useNotForm<TSchema extends ObjectSchema>(config: UseNotFormConfig<TSchema>): NotFormAPI<TSchema>;
 //#endregion
-export { type ArrayItemIndexMap, type DeepPartial, _default as NotArrayField, type NotArrayFieldItem, type NotArrayFieldProps, type NotArrayFieldSlots, _default$1 as NotField, type NotFieldProps, type NotFieldSlots, _default$2 as NotForm, type NotFormInstance, type NotFormProps, type NotFormSlots, _default$3 as NotMessage, type NotMessageProps, type NotMessageSlots, type ObjectSchema, type Paths, type Segment, type UseNotFormConfig, type ValidationMode, type ValidationTrigger, useNotForm };
+export { _default as NotArrayField, type NotArrayFieldItem, type NotArrayFieldProps, type NotArrayFieldSlots, _default$1 as NotField, type NotFieldProps, type NotFieldSlots, _default$2 as NotForm, type NotFormAPI, type NotFormProps, type NotFormSlots, _default$3 as NotMessage, type NotMessageProps, type NotMessageSlots, type UseNotFormConfig, useNotForm };