notform 3.0.1 → 4.0.0-alpha.0

package/dist/index.d.ts

@@ -1,560 +1,544 @@
 import { Component, MaybeRefOrGetter } from "vue";
 import { StandardSchemaV1 } from "@standard-schema/spec";
-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';
+import { Get, PartialDeep, Paths } from "type-fest";
 /**
- * Recursively optional version of `TData`, including array items.
- * @template TData Source data type.
+ * A Standard Schema whose input AND output are objects.
+ *
+ * Forms require this because form values are always a keyed object, never a
+ * lone string or number.
  */
-type DeepPartial<TData> = PartialDeep<TData, {
-  allowUndefinedInNonTupleArrays: true;
-  recurseIntoArrays: true;
-}>;
+type FormSchema = StandardSchemaV1 & {
+  '~standard': StandardSchemaV1['~standard'] & {
+    types?: {
+      input: object;
+      output: object;
+    };
+  };
+};
 /**
- * Input type accepted by a Standard Schema.
- * @template TSchema Validation schema.
+ * The data a schema *accepts*: what the user types, before parsing,
+ * transforming or defaults. This is the shape of `form.values`.
+ * @template TSchema - Any Standard Schema compatible schema (Zod, Valibot, ArkType, ...).
+ * @example
+ * // A schema that turns the text '42' into the number 42:
+ * // SchemaInput  -> { age: string }
+ * // SchemaOutput -> { age: number }
  */
-type InferInput<TSchema extends StandardSchemaV1> = StandardSchemaV1.InferInput<TSchema>;
+type SchemaInput<TSchema extends StandardSchemaV1> = StandardSchemaV1.InferInput<TSchema>;
 /**
- * Output type produced by a Standard Schema.
- * @template TSchema Validation schema.
+ * The data a schema *produces* after a successful validation. This is the shape `onSubmit` receives.
+ * @template TSchema - Any Standard Schema compatible schema.
  */
-type InferOutput<TSchema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<TSchema>;
-/** One issue from a Standard Schema validation run. */
-type Issue = StandardSchemaV1.Issue;
+type SchemaOutput<TSchema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<TSchema>;
 /**
- * Dot-notated field paths derived from a schema's input type.
+ * @file
+ * Vocabulary used across the library:
  *
- * 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.
+ * - PATH      A location written as dot-notation text, e.g. 'address.city' or 'tags.0'.
+ * This is what you pass to `form.field()`.
+ *
+ * - SEGMENTS  The same location split into steps, e.g. ['address', 'city'] or ['tags', 0].
+ * Schema libraries report issue locations this way.
+ */
+/**
+ * The item type of an array type. `never` when `TArray` is not an array.
+ * @template TArray - An array type, optionally `null` / `undefined`.
+ * @example
+ * // ArrayItem<string[] | undefined> -> string
+ */
+type ArrayItem<TArray> = NonNullable<TArray> extends readonly (infer TItem)[] ? TItem : never;
+/**
+ * Every valid path into the schema's INPUT data that points at an array.
+ * These are the paths accepted by `form.arrayField()`.
+ * @template TSchema - Any Standard Schema compatible schema.
+ */
+type InputArrayPath<TSchema extends StandardSchemaV1> = ValueArrayPath<SchemaInput<TSchema>>;
+/**
+ * Every valid path into the schema's INPUT data (the shape of `form.values`).
+ * These are the paths accepted by `form.field()` and `form.setValue()`.
+ * @template TSchema - Any Standard Schema compatible schema.
+ * @example
+ * // For z.object({ email: z.string(), tags: z.array(z.string()) }):
+ * // 'email' | 'tags' | `tags.${number}`
+ */
+type InputPath<TSchema extends StandardSchemaV1> = ValuePath<SchemaInput<TSchema>>;
+/**
+ * The type of the INPUT value found at `TPath`.
+ * @template TSchema - Any Standard Schema compatible schema.
+ * @template TPath - Dot-notation path, e.g. `'address.city'`.
+ */
+type InputPathValue<TSchema extends StandardSchemaV1, TPath extends string> = ValuePathValue<SchemaInput<TSchema>, TPath>;
+/**
+ * Every valid path into the schema's OUTPUT data (the shape `onSubmit` receives).
+ * @template TSchema - Any Standard Schema compatible schema.
+ */
+type OutputPath<TSchema extends StandardSchemaV1> = ValuePath<SchemaOutput<TSchema>>;
+/**
+ * The type of the OUTPUT value found at `TPath`.
+ * @template TSchema - Any Standard Schema compatible schema.
+ * @template TPath - Dot-notation path.
+ */
+type OutputPathValue<TSchema extends StandardSchemaV1, TPath extends string> = ValuePathValue<SchemaOutput<TSchema>, TPath>;
+/**
+ * Every dot-notation path inside `TValue` that points at an array.
+ * @template TValue - The object type to look into.
  */
-type Paths$1<TSchema extends StandardSchemaV1> = Extract<Paths<InferInput<TSchema>, {
+type ValueArrayPath<TValue> = Extract<ArrayPathsOf<TValue, ValuePath<TValue>>, string>;
+/**
+ * Every dot-notation path inside `TValue`.
+ * @template TValue - The object type to look into.
+ * @remarks Recursion is capped at depth 10 to keep TypeScript fast.
+ */
+type ValuePath<TValue> = Extract<Paths<TValue, {
   maxRecursionDepth: 10;
-}>, string> | (string & {});
+}>, string>;
 /**
- * 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}
+ * The type found at `TPath` inside `TValue`.
+ * @template TValue - The object type to look into.
+ * @template TPath - Dot-notation path.
  */
-type ObjectSchema = StandardSchemaV1 & {
-  '~standard': StandardSchemaV1['~standard'] & {
-    types?: {
-      input: object;
-    };
-  };
-};
-//#endregion
-//#region src/types/not-form-instance.d.ts
+type ValuePathValue<TValue, TPath extends string> = Get<TValue, TPath, {
+  strict: false;
+}>;
+/** Keeps only the paths whose value is an array (distributes over the path union). */
+type ArrayPathsOf<TValue, TPath extends string> = TPath extends unknown ? NonNullable<ValuePathValue<TValue, TPath>> extends readonly unknown[] ? TPath : never : never;
 /**
- * Full form instance used by field components. `useNotForm` returns {@linkcode NotFormAPI}.
- * @template TSchema The form schema.
+ * A single validation problem reported by a schema: a human-readable `message`
+ * and an optional `path` (in segments). An issue without a `path` applies to the whole form.
  */
-interface NotFormInstance<TSchema extends ObjectSchema> {
-  /** Live field values. */
-  values: InferInput<TSchema>;
+type ValidationIssue = StandardSchemaV1.Issue;
+/**
+ * The raw Standard Schema result: `{ value }` on success, `{ issues }` on failure.
+ * @template TValue - Type of the validated value on success.
+ */
+type ValidationResult<TValue> = StandardSchemaV1.Result<TValue>;
+/**
+ * Per-field behavior, passed as the second argument of `form.field()` / `form.arrayField()`.
+ * @remarks Read once, when the field is first created.
+ * @example
+ * form.field('email', { debounce: 300, validateOn: { input: true } })
+ */
+type FieldConfig = {
+  /** Milliseconds to wait after the last `input` / `change` before validating. `blur` always validates immediately. */
+  debounce?: number;
+  /** Which events trigger validation. Omitted events keep their defaults (`blur` and `change` on, `input` off). */
+  validateOn?: Partial<Record<FieldValidationEvent, boolean>>;
   /**
-   * 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.
+   * - `'eager'`: once the field has errors, every `input` and `change` re-validates it,
+   * so the error disappears as soon as the value is fixed.
+   *
+   * - `'lazy'`: only the events enabled in `validateOn` validate.
+   * @default 'eager'
    */
-  setValue: <TPath extends Paths$1<TSchema>>(path: TPath, value: Get<InferInput<TSchema>, TPath, {
-    strict: false;
-  }>) => void;
-  /** Whether any field is touched. */
+  validationMode?: 'eager' | 'lazy';
+};
+/** Handlers to spread onto an input: `<input v-bind="field.events">`. */
+type FieldEvents = Record<`on${Capitalize<FieldValidationEvent>}`, () => void>;
+/**
+ * A single form field, bound to one value inside the form.
+ *
+ * Created by `form.field('some.path')`. The instance is cached, so asking for the
+ * same path again returns the same field with the same `id`.
+ * @template TValue - Type of the value this field holds.
+ */
+type FieldInstance<TValue> = {
+  /** Issues reported exactly at this field's path (not those of nested fields). */
+  errors: ValidationIssue[];
+  /** Handlers for `blur` / `change` / `input`; they mark the field touched and trigger validation. */
+  events: FieldEvents;
+  /** Stable identity. Safe as a `v-for` key; does not change when the field's path does. */
+  id: symbol;
+  /** `true` when the value differs (deep comparison) from the initial value at the field's path. */
+  isDirty: boolean;
+  /** `true` once the field was blurred, or the form was submitted. */
   isTouched: boolean;
+  /** `true` when {@link FieldInstance.errors} is empty. */
+  isValid: boolean;
+  /** `true` while this field, a field nested in it, or the whole form is being validated. */
+  isValidating: boolean;
+  /** The field's value. Assign to it (or `v-model` it) to write straight into `form.values`. */
+  model: TValue;
+  /** Current dot-notation location, e.g. `'address.city'`. Follows the field when array items move. */
+  path: string;
   /**
-   * Touched field paths.
-   * @internal
+   * Validates this field now, skipping any pending debounce.
+   * @returns `{ value }` with the current value, or `{ issues }` for this field.
    */
-  touchedFields: Set<Paths$1<TSchema>>;
+  validate: () => Promise<ValidationResult<TValue>>;
+};
+/**
+ * Props of the `<Field>` component.
+ * @template TValue - Type of the value the field holds.
+ */
+type FieldProps<TValue> = {
+  /** The field created by `form.field('some.path')`, or an array item. */
+  field: FieldInstance<TValue>;
+};
+/**
+ * Slots of the `<Field>` component.
+ * @template TValue - Type of the value the field holds.
+ */
+type FieldSlots<TValue> = {
+  /** Receives the `field`. Extra attributes set on `<Field>` arrive as additional slot props. */
+  default?: (props: {
+    field: FieldInstance<TValue>;
+  }) => void;
+};
+/** Events that can trigger a field's validation. See {@link FieldConfig.validateOn}. */
+type FieldValidationEvent = 'blur' | 'change' | 'input';
+/**
+ * A field for an array: the usual field state for the array itself (`errors` are
+ * array-level issues such as "at least one item"), plus the list of items and
+ * the mutations to change it.
+ *
+ * Mutate through this object (not `values.list.push()`) so items keep their identity,
+ * touched state and errors. Inserted values are deep-cloned.
+ * @template TItem - Type of one array item.
+ */
+type ArrayFieldInstance<TItem> = FieldInstance<TItem[]> & {
   /**
-   * Marks a field as touched.
-   * @internal
-   * @param path Dot path.
+   * Adds an item at the end.
+   * @param value The new item.
    */
-  markFieldAsTouched: (path: Paths$1<TSchema>) => void;
+  append: (value: TItem) => void;
   /**
-   * 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
+   * Adds an item at `index`; later items shift up.
+   * @param index Where to insert. Clamped into `0..length`.
+   * @param value The new item.
    */
-  markAllFieldsAsTouched: () => void;
+  insert: (index: number, value: TItem) => void;
+  /** One entry per array item, in order. Use `item.id` as the `v-for` key. */
+  items: ArrayItemInstance<TItem>[];
   /**
-   * Clears touched state for one field.
-   * @internal
-   * @param path Dot path.
+   * Moves an item to another position. Ignored if an index is out of range.
+   * @param from Current index of the item.
+   * @param to Index it should end up at.
    */
-  unmarkFieldAsTouched: (path: Paths$1<TSchema>) => void;
+  move: (from: number, to: number) => void;
   /**
-   * Clears touched state for all fields.
-   * @internal
+   * Adds an item at the start.
+   * @param value The new item.
    */
-  unmarkAllFieldsAsTouched: () => void;
+  prepend: (value: TItem) => void;
   /**
-   * Paths whose value differs from the baseline.
-   * @internal
+   * Removes an item. Ignored if `index` is out of range.
+   * @param index Index of the item.
    */
-  dirtyFields: Set<Paths$1<TSchema>>;
-  /** Whether any field is dirty. */
-  isDirty: boolean;
+  remove: (index: number) => void;
   /**
-   * Updates dirty state by comparing current and baseline values.
-   * @internal
-   * @param path Dot path.
+   * Swaps two items. Ignored if an index is out of range.
+   * @param indexA Index of the first item.
+   * @param indexB Index of the second item.
    */
-  syncDirtyState: (path: Paths$1<TSchema>) => void;
+  swap: (indexA: number, indexB: number) => void;
   /**
-   * Updates dirty state for every current leaf field. Subject to the same
-   * "current shape only" caveat as {@linkcode markAllFieldsAsTouched}.
-   * @internal
+   * Replaces an item in place. The item keeps its id and touched state; its old errors are dropped.
+   * Ignored if `index` is out of range.
+   * @param index Index of the item.
+   * @param value The new value.
    */
-  syncAllDirtyStates: () => void;
+  update: (index: number, value: TItem) => void;
+};
+/**
+ * Props of the `<ArrayField>` component.
+ * @template TItem - Type of one array item.
+ */
+type ArrayFieldProps<TItem> = {
+  /** The array field created by `form.arrayField('some.path')`. */
+  arrayField: ArrayFieldInstance<TItem>;
+};
+/**
+ * Slots of the `<ArrayField>` component.
+ * @template TItem - Type of one array item.
+ */
+type ArrayFieldSlots<TItem> = {
+  /** Receives the `arrayField`. Extra attributes set on `<ArrayField>` arrive as additional slot props. */
+  default?: (props: {
+    arrayField: ArrayFieldInstance<TItem>;
+  }) => void;
+};
+/**
+ * One item of an array field. It is a regular field for the item's value (pass it
+ * straight to `<Field>`), plus its position and shortcuts to change it.
+ *
+ * Its `id` never changes; `index` and `path` follow the item when the array is reordered.
+ * @template TItem - Type of the item.
+ */
+type ArrayItemInstance<TItem> = FieldInstance<TItem> & {
   /**
-   * Forces a field dirty.
-   * @internal
-   * @param path Dot path.
+   * Creates an array field nested in this item (e.g. a `tags` list inside a contact).
+   * Cached per path; follows the item when it moves.
+   * @param path Path relative to the item, e.g. `'tags'`.
+   * @param config Optional per-field behavior.
+   * @returns The nested array field.
    */
-  markFieldAsDirty: (path: Paths$1<TSchema>) => void;
+  arrayField: <TPath extends ValueArrayPath<TItem>>(path: TPath, config?: FieldConfig) => ArrayFieldInstance<ArrayItem<ValuePathValue<TItem, TPath>>>;
   /**
-   * Forces every current leaf field dirty. Subject to the same
-   * "current shape only" caveat as {@linkcode markAllFieldsAsTouched}.
-   * @internal
+   * Creates a field nested in this item (e.g. `'email'` inside a contact).
+   * Cached per path; follows the item when it moves.
+   * @param path Path relative to the item, e.g. `'email'`.
+   * @param config Optional per-field behavior.
+   * @returns The nested field.
    */
-  markAllFieldsAsDirty: () => void;
+  field: <TPath extends ValuePath<TItem>>(path: TPath, config?: FieldConfig) => FieldInstance<ValuePathValue<TItem, TPath>>;
+  /** Current position in the array. */
+  index: number;
+};
+declare const __VLS_export$3: <TItem>(__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<ArrayFieldProps<TItem>> & (typeof globalThis extends {
+    __VLS_PROPS_FALLBACK: infer P;
+  } ? P : {});
+  expose: (exposed: {}) => void;
+  attrs: any;
+  slots: ArrayFieldSlots<TItem>;
+  emit: {};
+}>) => import("vue").VNode & {
+  __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
+};
+declare const _default: typeof __VLS_export$3;
+type __VLS_PrettifyLocal$2<T> = (T extends any ? { [K in keyof T]: T[K]; } : { [K in keyof T as K]: T[K]; }) & {};
+/** Props of the `<FieldError>` component. */
+type FieldErrorProps = {
   /**
-   * Clears dirty state for one field.
-   * @internal
-   * @param path Dot path.
+   * HTML tag name or Vue component used to render the message.
+   * @default 'span'
    */
-  unmarkFieldAsDirty: (path: Paths$1<TSchema>) => void;
+  as?: Component | string;
+  /** A list of issues, or anything that has one (a field, an array field, an array item). Only the first message is shown. */
+  errors: ValidationIssue[] | {
+    readonly errors: ValidationIssue[];
+  };
+};
+/** Slots of the `<FieldError>` component. */
+type FieldErrorSlots = {
+  /** Receives the `message` to display. */
+  default?: (props: {
+    message?: string;
+  }) => void;
+};
+type __VLS_Slots = FieldErrorSlots;
+declare const __VLS_base: import("vue").DefineComponent<FieldErrorProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<FieldErrorProps> & Readonly<{}>, {
+  as: string | import("vue").Component;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export$2: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default$2: typeof __VLS_export$2;
+type __VLS_WithSlots<T, S> = T & {
+  new (): {
+    $slots: S;
+  };
+};
+declare const __VLS_export$1: <TValue>(__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<FieldProps<TValue>> & (typeof globalThis extends {
+    __VLS_PROPS_FALLBACK: infer P;
+  } ? P : {});
+  expose: (exposed: {}) => void;
+  attrs: any;
+  slots: FieldSlots<TValue>;
+  emit: {};
+}>) => import("vue").VNode & {
+  __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
+};
+declare const _default$1: 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]; }) & {};
+/**
+ * Makes every property optional, at every depth (including items inside arrays).
+ *
+ * Used for initial form values: a form can start empty or half-filled even
+ * though the schema eventually demands complete data.
+ * @template TValue - The type to make deeply optional.
+ */
+type DeepPartial<TValue> = PartialDeep<TValue, {
+  allowUndefinedInNonTupleArrays: true;
+  recurseIntoArrays: true;
+}>;
+/**
+ * Options accepted by `useForm()`.
+ * @template TSchema - The schema describing the form's data (must be an object schema).
+ */
+type FormConfig<TSchema extends FormSchema> = {
+  /** Errors to show from the start (e.g. returned by the server). */
+  initialErrors?: ValidationIssue[];
+  /** Values to start with. May be partial; the schema is only enforced on validation. */
+  initialValues?: DeepPartial<SchemaInput<TSchema>>;
+  /** Called with the validated, parsed data after a successful submit. */
+  onSubmit?: (data: SchemaOutput<TSchema>) => Promise<void> | void;
+  /** The schema to validate against. Accepts a value, a ref, or a getter, so it can change reactively. */
+  schema: MaybeRefOrGetter<TSchema>;
+};
+/**
+ * A reactive form: its values, errors, state flags, and the actions to change them.
+ * @template TSchema - The schema describing the form's data (must be an object schema).
+ */
+type FormInstance<TSchema extends FormSchema> = {
   /**
-   * Clears dirty state for all fields.
-   * @internal
+   * Gets or creates the array field at `path`. Cached: the same path always returns the same field.
+   * @param path Dot-notation path to an array, e.g. `'tags'`.
+   * @param config Optional per-field behavior, read when the field is first created.
+   * @returns A reactive array field to pass to `<ArrayField>`.
    */
-  unmarkAllFieldsAsDirty: () => void;
-  /** Issues from the last validation that wrote errors. */
-  errors: Array<Issue>;
+  arrayField: <TPath extends InputArrayPath<TSchema>>(path: TPath, config?: FieldConfig) => ArrayFieldInstance<ArrayItem<InputPathValue<TSchema, TPath>>>;
+  /** Removes every error from the form. */
+  clearErrors: () => void;
+  /** Current validation errors of the whole form. Empty when everything is valid. */
+  errors: ValidationIssue[];
   /**
-   * Upserts an issue at the same path, or appends it.
-   * @param error Issue to set.
+   * Gets or creates the field at `path`. Cached: the same path always returns the
+   * same field (same `id`, same touched state), so it is safe to call inside a template.
+   * @param path Dot-notation path to the value, e.g. `'address.city'`.
+   * @param config Optional per-field behavior, read when the field is first created.
+   * @returns A reactive field to pass to `<Field>`.
    */
-  setError: (error: Issue) => void;
+  field: <TPath extends InputPath<TSchema>>(path: TPath, config?: FieldConfig) => FieldInstance<InputPathValue<TSchema, TPath>>;
   /**
-   * Replaces the entire error list.
-   * @internal
-   * @param errors Replacement issues.
+   * Reads the issues reported exactly at `path`.
+   * @param path Dot-notation path.
+   * @returns The matching issues.
    */
-  replaceErrors: (errors: Array<Issue>) => void;
+  getFieldErrors: <TPath extends InputPath<TSchema>>(path: TPath) => ValidationIssue[];
   /**
-   * Removes every issue.
-   * @internal
+   * Reads the live value at `path`.
+   * @param path Dot-notation path.
+   * @returns The current value.
    */
-  clearErrors: () => void;
+  getValue: <TPath extends InputPath<TSchema>>(path: TPath) => InputPathValue<TSchema, TPath>;
+  /** The errors the form started with. Replaced as a whole by `reset(values, errors)`. */
+  initialErrors: ValidationIssue[];
+  /** The values the form started with; `isDirty` compares against them. Replaced as a whole by `reset(values)`. */
+  initialValues: DeepPartial<SchemaInput<TSchema>>;
+  /** `true` when `values` differ (deep comparison) from `initialValues`. */
+  isDirty: boolean;
   /**
-   * 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.
+   * Tells whether a validation concerning `path` is running: a whole-form run, a run on
+   * the path itself, or a run on a field nested inside it.
+   * @param path Dot-notation path.
+   * @returns `true` while one is running.
    */
-  getFieldErrors: (path: Paths$1<TSchema>) => Array<Issue>;
-  /** Whether any validation is in flight. */
-  isValidating: boolean;
-  /** Whether there are zero issues. */
+  isFieldValidating: <TPath extends InputPath<TSchema>>(path: TPath) => boolean;
+  /** `true` once a submit was attempted, even if validation failed. */
+  isSubmitted: boolean;
+  /** `true` while a submit is running (validating, or waiting for `onSubmit`). */
+  isSubmitting: boolean;
+  /** `true` once any field was blurred or a submit was attempted. */
+  isTouched: boolean;
+  /** `true` when there are no errors. Reflects the last validation; reading it does not validate. */
   isValid: boolean;
+  /** `true` while any validation is running. */
+  isValidating: boolean;
   /**
-   * Paths currently validating.
-   * @internal
+   * Replaces all current errors.
+   * @param nextErrors The errors the form should now show (e.g. from the server).
    */
-  validatingFields: Set<Paths$1<TSchema>>;
+  replaceErrors: (nextErrors: ValidationIssue[]) => void;
   /**
-   * 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.
+   * Resets values, errors, touched state and submit state, and cancels pending validations.
+   * Array items get fresh identities.
+   * @param nextValues New starting values. Omit to go back to the current `initialValues`.
+   * @param nextErrors New starting errors. Omit to go back to the current `initialErrors`.
    */
-  validate: () => Promise<StandardSchemaV1.Result<InferOutput<TSchema>>>;
+  reset: {
+    (nextValues?: DeepPartial<SchemaInput<TSchema>>, nextErrors?: ValidationIssue[]): void;
+    /** Overload so it can be used directly as an event handler: `@reset.prevent="form.reset"`. */
+    (event: Event): void;
+  };
+  /** How many times the form was reset. Handy as a `:key` to remount inputs. */
+  resetCount: number;
   /**
-   * 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.
-   *
-   * 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.
+   * Sets an error. Replaces the errors already on the same path.
+   * @param error The issue to show. Without a `path` it is a form-level error.
    */
-  validateField: (path: Paths$1<TSchema>) => Promise<StandardSchemaV1.Result<InferOutput<TSchema>>>;
-  /** Whether `onSubmit` is running. */
-  isSubmitting: boolean;
+  setError: (error: ValidationIssue) => void;
   /**
-   * 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.
+   * Writes `value` into the form at `path`.
+   * @param path Dot-notation path.
+   * @param value The new value (typed from the schema).
    */
-  submit: (event?: SubmitEvent) => Promise<void>;
+  setValue: <TPath extends InputPath<TSchema>>(path: TPath, value: InputPathValue<TSchema, TPath>) => void;
   /**
-   * Restores values/errors to the baseline. Optional arguments become the
-   * new baseline, and reset to it immediately.
-   *
-   * `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.
-   *
-   * 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.
+   * Validates the whole form and, if valid, calls `onSubmit`. Safe to use as a `<form v-on:submit>` handler.
+   * Ignored while a submit is already running.
+   * @param event The browser submit event; its default page reload is prevented.
+   * @returns Resolves when the submit finished. Rejects with whatever `onSubmit` throws.
    */
-  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
-/**
- * One array item from `<NotArrayField>`'s default slot.
- * @template TSchema The form schema.
- */
-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>;
-  /**
-   * 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;
-  /** Form instance. Overrides `<NotForm>` inject. Required outside `<NotForm>`. */
-  form?: NotFormAPI<TSchema>;
-}
-/**
- * Slot props for `<NotArrayField>`.
- * @template TSchema The form schema.
- * @template TItemSchema Item schema used only to type mutation helpers.
- */
-interface NotArrayFieldSlots<TSchema extends ObjectSchema, TItemSchema extends StandardSchemaV1 = StandardSchemaV1> {
-  default?: (props: {
-    /** Dot path of the array field. */
-    path: string;
-    /** 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 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 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 the array field's own path, or any path nested underneath it, is currently validating.
-     *
-     * Recurses the same way as {@linkcode isValid}.
-     */
-    isValidating: boolean;
-    /**
-     * Appends a value at the end.
-     * @param value Value to append.
-     */
-    append: (value: InferInput<TItemSchema>) => void;
-    /**
-     * 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: InferInput<TItemSchema>) => void;
-    /**
-     * 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.
-     */
-    insert: (index: number, value: InferInput<TItemSchema>) => void;
-    /**
-     * 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.
-     */
-    remove: (index: number) => void;
-    /**
-     * Replaces the value at `index` without changing its key.
-     * @param index Index to update.
-     * @param value New value.
-     */
-    update: (index: number, value: InferInput<TItemSchema>) => void;
-    /**
-     * 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 `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;
-  }) => void;
-}
-//#endregion
-//#region src/components/not-array-field.vue.d.ts
-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, TItemSchema>;
-  emit: {};
-}>) => import("vue").VNode & {
-  __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
-};
-declare const _default: typeof __VLS_export$3;
-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 `<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>;
+  submit: (event?: SubmitEvent) => Promise<void>;
+  /** How many times a submit was attempted. */
+  submitCount: number;
   /**
-   * 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 }
+   * Validates the whole form and replaces all errors with the outcome. Does not call `onSubmit`.
+   * @returns `{ value }` (the parsed output) when valid, otherwise `{ issues }`.
    */
-  validateOn?: Partial<Record<ValidationTrigger, boolean>>;
+  validate: () => Promise<ValidationResult<SchemaOutput<TSchema>>>;
   /**
-   * `lazy` — blur/submit only. `eager` — also revalidate on change/input while invalid.
-   * @default 'eager'
+   * Validates the whole form against the schema but updates only the errors at `path`.
+   * @param path Dot-notation path.
+   * @returns `{ value }` (the current input value) when the field is valid, otherwise `{ issues }`
+   * for that field. A result made obsolete by a newer run is returned but not applied.
    */
-  validationMode?: 'eager' | 'lazy';
-  /** Debounce in ms for input/change validation. Blur always runs immediately. */
-  debounce?: number;
-}
-/** Slot props for `<NotField>`. */
-interface NotFieldSlots {
-  default?: (props: {
-    /** Issues for this field path. */
-    errors: Array<Issue>;
-    /**
-     * Handlers to bind to the input. `onMount` is deliberately excluded —
-     * see the note on `validateOn` prop for why.
-     */
-    events: Record<ExcludeStrict<ValidationTrigger, 'onMount'>, () => void>;
-    /** Whether the value differs from the baseline. */
-    isDirty: boolean;
-    /** 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;
-    /** 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$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;
-  emit: {};
-}>) => import("vue").VNode & {
-  __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
+  validateField: <TPath extends InputPath<TSchema>>(path: TPath) => Promise<ValidationResult<InputPathValue<TSchema, TPath>>>;
+  /** The live form data. Edit it directly, through `setValue`, or through field models. */
+  values: SchemaInput<TSchema>;
 };
-declare const _default$1: typeof __VLS_export$2;
-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.
+ * Props of the `<Form>` component.
+ * @template TSchema - The schema describing the form's data.
  */
-interface NotFormProps<TSchema extends ObjectSchema> {
-  /** Form instance provided to descendant field components. */
-  form: NotFormAPI<TSchema>;
-}
-/** Slot props for `<NotForm>`. */
-interface NotFormSlots {
+type FormProps<TSchema extends FormSchema> = {
+  /** The form returned by `useForm()`. */
+  form: UseFormInstance<TSchema>;
+};
+/** Slots of the `<Form>` component. */
+type FormSlots = {
+  /** The form's contents (fields, buttons, ...). */
   default?: () => void;
-}
-//#endregion
-//#region src/components/not-form.vue.d.ts
-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 `<NotMessage>`.
- * @template TSchema The form schema.
+ * A subset of `FormInstance` that is safe to expose to consumers of `useForm()`.
+ * It omits internal methods that change the form's state, so they cannot be called from outside.
+ * @template TSchema - The schema describing the form's data.
  */
-interface NotMessageProps<TSchema extends ObjectSchema> {
-  /**
-   * 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;
-  /** Field path whose first error message is shown. */
-  path: Paths$1<TSchema>;
-  /** Form instance. Overrides `<NotForm>` inject. Required outside `<NotForm>`. */
-  form?: NotFormAPI<TSchema>;
-}
-/** Slot props for `<NotMessage>`. */
-interface NotMessageSlots {
-  default?: (props: {
-    /** First active error message for `path`. */
-    message?: string;
-  }) => void;
-}
-//#endregion
-//#region src/components/not-message.vue.d.ts
-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 {
+type UseFormInstance<TSchema extends FormSchema> = Pick<FormInstance<TSchema>, 'arrayField' | 'errors' | 'field' | 'isDirty' | 'isSubmitted' | 'isSubmitting' | 'isTouched' | 'isValid' | 'isValidating' | 'reset' | 'resetCount' | 'setError' | 'setValue' | 'submit' | 'submitCount' | 'validate' | 'values'>;
+declare const __VLS_export: <TSchema extends FormSchema>(__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<FormProps<TSchema>> & (typeof globalThis extends {
     __VLS_PROPS_FALLBACK: infer P;
   } ? P : {});
   expose: (exposed: {}) => void;
   attrs: any;
-  slots: NotMessageSlots;
+  slots: FormSlots;
   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 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>`.
+ * Creates a reactive, schema-validated form. Call it inside `setup()`, so its
+ * watchers and pending timers are cleaned up when the component unmounts.
+ * @template TSchema - A Standard Schema (Zod, Valibot, ArkType, ...) describing the form's data. Must be an object schema.
+ * @param config The schema, optional starting values/errors, and an optional submit handler.
+ * @returns The form. Pass it to `<Form :form />` and use `form.field(path)` / `form.arrayField(path)` to create fields.
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { z } from 'zod'
+ * import { Field, Form, useForm } from 'notform'
+ *
+ * const form = useForm({
+ *   schema: z.object({ email: z.email() }),
+ *   initialValues: { email: '' },
+ *   onSubmit: async (data) => {
+ *     await api.signUp(data) // `data` is the validated output
+ *   },
+ * })
+ * </script>
+ *
+ * <template>
+ *   <Form :form>
+ *     <Field v-slot="{ field }" :field="form.field('email')">
+ *       <input v-model="field.model" v-bind="field.events" type="email">
+ *     </Field>
+ *     <button type="submit" :disabled="form.isSubmitting">Sign up</button>
+ *   </Form>
+ * </template>
+ * ```
  */
-declare function useNotForm<TSchema extends ObjectSchema>(config: UseNotFormConfig<TSchema>): NotFormAPI<TSchema>;
-//#endregion
-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 };
+export declare function useForm<TSchema extends FormSchema>(config: FormConfig<TSchema>): UseFormInstance<TSchema>;
+export { _default as ArrayField, type ArrayFieldInstance, type ArrayFieldProps, type ArrayFieldSlots, type ArrayItem, type ArrayItemInstance, _default$1 as Field, type FieldConfig, _default$2 as FieldError, type FieldErrorProps, type FieldErrorSlots, type FieldEvents, type FieldInstance, type FieldProps, type FieldSlots, type FieldValidationEvent, _default$3 as Form, type FormConfig, type FormInstance, type FormProps, type FormSchema, type FormSlots, type InputArrayPath, type InputPath, type InputPathValue, type OutputPath, type OutputPathValue, type SchemaInput, type SchemaOutput, type UseFormInstance, type ValidationIssue, type ValidationResult };