@formisch/preact 0.11.0 → 0.12.0

package/README.md

@@ -56,7 +56,7 @@ export default function LoginPage() {
 }
 ```
 
-In addition, Formisch offers several functions (we call them "methods") that can be used to read and manipulate the form state. These include `focus`, `getErrors`, `getAllErrors`, `getInput`, `insert`, `move`, `remove`, `replace`, `reset`, `setErrors`, `setInput`, `submit`, `swap` and `validate`. These methods allow you to control the form programmatically.
+In addition, Formisch offers several functions (we call them "methods") that can be used to read and manipulate the form state. These include `focus`, `getDeepErrorEntries`, `getDeepErrors`, `getDirtyInput`, `getDirtyPaths`, `getErrors`, `getInput`, `handleSubmit`, `insert`, `isDirty`, `isEdited`, `isTouched`, `isValid`, `move`, `pickDirty`, `remove`, `replace`, `reset`, `setErrors`, `setInput`, `submit`, `swap` and `validate`. These methods allow you to control the form programmatically.
 
 ## Comparison
 

package/dist/index.d.ts

@@ -4,6 +4,177 @@ import { FocusEventHandler, FormHTMLAttributes, GenericEventHandler, InputEventH
 
 //#region ../../packages/core/dist/index.preact.d.ts
 
+//#region src/types/utils/utils.d.ts
+/**
+* Checks if a type is `any`.
+*/
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/**
+* Checks if a type is `never`.
+*/
+type IsNever<T> = [T] extends [never] ? true : false;
+/**
+* Constructs a type that is maybe a promise.
+*/
+type MaybePromise<T> = T | Promise<T>;
+/**
+* Makes all properties deeply optional.
+*/
+type DeepPartial<TValue> = TValue extends Record<PropertyKey, unknown> | readonly unknown[] ? { [TKey in keyof TValue]?: DeepPartial<TValue[TKey]> | undefined } : TValue | undefined;
+/**
+* Makes all value properties optional.
+*
+* Hint: For dynamic arrays, only plain objects and nested arrays have their
+* values made optional. Primitives and class instances are kept as-is to avoid
+* types like `(string | undefined)[]`.
+*/
+type PartialValues<TValue> = TValue extends readonly (infer TItem)[] ? number extends TValue["length"] ? (TItem extends Record<PropertyKey, unknown> | readonly unknown[] ? { [TKey in keyof TItem]: PartialValues<TItem[TKey]> } : TItem)[] : { [TKey in keyof TValue]: PartialValues<TValue[TKey]> } : TValue extends Record<PropertyKey, unknown> ? { [TKey in keyof TValue]: PartialValues<TValue[TKey]> } : TValue | undefined;
+//#endregion
+//#region src/types/path/path.d.ts
+/**
+* Path key type.
+*/
+type PathKey = string | number;
+/**
+* Path type.
+*/
+type Path = readonly PathKey[];
+/**
+* Required path type.
+*/
+type RequiredPath = readonly [PathKey, ...Path];
+/**
+* Extracts the exact keys of a tuple, array or object. Tuples return their
+* literal numeric indices, dynamic arrays return `number`, objects return
+* their `keyof` keys, and any other input returns `never`.
+*/
+type ExactKeysOf<TValue> = IsAny<TValue> extends true ? never : TValue extends readonly unknown[] ? number extends TValue["length"] ? number : { [TKey in keyof TValue]: TKey extends `${infer TIndex extends number}` ? TIndex : never }[number] : TValue extends Record<PropertyKey, unknown> ? keyof TValue & PathKey : never;
+/**
+* Returns the flat object of all indexable properties of `TValue`. For object
+* unions, properties from every member are merged so that any single property
+* is accessible. For primitives and other non-indexable types, the result is
+* `{}`.
+*
+* Hint: This is necessary to make properties accessible across union members.
+* By default, properties that do not exist in all union options are not
+* accessible and result in "any" when accessed.
+*/
+type PropertiesOf<TValue> = { [TKey in ExactKeysOf<TValue>]: TValue extends Record<TKey, infer TItem> ? TItem : never };
+/**
+* Lazily evaluates only the first valid path segment based on the given value.
+*/
+type LazyPath<TValue, TPathToCheck extends Path, TValidPath extends Path = readonly []> = TPathToCheck extends readonly [] ? TValidPath : TPathToCheck extends readonly [infer TFirstKey extends ExactKeysOf<TValue>, ...infer TPathRest extends Path] ? LazyPath<Required<PropertiesOf<TValue>[TFirstKey]>, TPathRest, readonly [...TValidPath, TFirstKey]> : IsNever<ExactKeysOf<TValue>> extends false ? readonly [...TValidPath, ExactKeysOf<TValue>] : TValidPath;
+/**
+* Returns the path if valid, otherwise the first possible valid path based on
+* the given value.
+*/
+type ValidPath<TValue, TPath extends RequiredPath> = TPath extends LazyPath<Required<TValue>, TPath> ? TPath : LazyPath<Required<TValue>, TPath>;
+/**
+* Detects whether the consuming project is configured with
+* `exactOptionalPropertyTypes: true`.
+*
+* Hint: If `false` the built-in `Required<T>` strips `| undefined` from
+* optional properties, so `Required<{ key?: undefined }>['key']` collapses
+* to `never` — under strict mode the same expression yields `undefined`.
+*/
+type IsExactOptionalProps = Required<{
+  key?: undefined;
+}>["key"] extends never ? false : true;
+/**
+* Like the built-in `Required<T>`, but preserves `| undefined` in two
+* places where `Required<T>` strips it:
+*
+* 1. Optional property values under `exactOptionalPropertyTypes: false`
+*    — without this, input typings for `v.optional`/`v.nullish` schemas
+*    narrow incorrectly (issue #15).
+* 2. Array/tuple element types — e.g. `(string | undefined)[]` stays
+*    `(string | undefined)[]` instead of becoming `string[]`. Arrays
+*    fall through unchanged because they only have a numeric index
+*    signature and don't structurally extend `Record<PropertyKey,
+*    unknown>` (which requires string keys).
+*/
+type ExactRequired<TValue> = TValue extends Record<PropertyKey, unknown> ? IsExactOptionalProps extends true ? Required<TValue> : { [TKey in keyof Required<TValue>]: TValue[TKey] } : TValue;
+/**
+* Extracts the value type at the given path.
+*/
+type PathValue<TValue, TPath extends Path> = TPath extends readonly [infer TKey, ...infer TRest extends Path] ? TKey extends ExactKeysOf<ExactRequired<TValue>> ? PathValue<PropertiesOf<ExactRequired<TValue>>[TKey], TRest> : unknown : TValue;
+/**
+* Checks whether a value is a dynamic array or contains one anywhere in its
+* shape. A fixed-length tuple is not itself a dynamic array, but it counts when
+* it contains one, so paths can still navigate through tuples to reach nested
+* arrays.
+*
+* Hint: The inner conditionals (`TValue extends readonly unknown[]` and
+* `TValue extends Record<PropertyKey, unknown>`) distribute over union members,
+* so the inner expression returns the union of each member's result (e.g.
+* `true | false` when some members contain arrays and others don't).
+* Downstream code uses `IsOrHasArray<T> extends true`, but
+* `boolean extends true` is `false` — so we collapse the result via
+* `true extends ...`, which is `true` whenever at least one union member
+* contributed `true`.
+*/
+type IsOrHasArray<TValue> = true extends (IsAny<TValue> extends true ? false : TValue extends readonly unknown[] ? number extends TValue["length"] ? true : IsOrHasArray<TValue[number]> : TValue extends Record<PropertyKey, unknown> ? { [TKey in keyof TValue]: IsOrHasArray<TValue[TKey]> }[keyof TValue] : false) ? true : false;
+/**
+* Extracts the exact keys of a tuple, array or object that contain arrays.
+*/
+type ExactKeysOfArrayPath<TValue> = IsAny<TValue> extends true ? never : TValue extends readonly (infer TItem)[] ? number extends TValue["length"] ? IsOrHasArray<TItem> extends true ? number : never : { [TKey in keyof TValue]: TKey extends `${infer TIndex extends number}` ? IsOrHasArray<NonNullable<TValue[TKey]>> extends true ? TIndex : never : never }[number] : TValue extends Record<PropertyKey, unknown> ? { [TKey in keyof TValue]: IsOrHasArray<NonNullable<TValue[TKey]>> extends true ? TKey : never }[keyof TValue] & PathKey : never;
+/**
+* Returns the flat object of indexable properties of `TValue` whose values
+* are or contain arrays. Mirrors `PropertiesOf` but keyed by
+* `ExactKeysOfArrayPath` so the lookup is provably valid for array-path
+* navigation in `LazyArrayPath`.
+*/
+type PropertiesOfArrayPath<TValue> = { [TKey in ExactKeysOfArrayPath<TValue>]: TValue extends Record<TKey, infer TItem> ? TItem : never };
+/**
+* Lazily evaluates only the first valid array path segment based on the given value.
+*/
+type LazyArrayPath<TValue, TPathToCheck extends Path, TValidPath extends Path = readonly []> = TPathToCheck extends readonly [] ? TValue extends readonly unknown[] ? number extends TValue["length"] ? TValidPath : IsNever<ExactKeysOfArrayPath<TValue>> extends false ? readonly [...TValidPath, ExactKeysOfArrayPath<TValue>] : never : readonly [...TValidPath, ExactKeysOfArrayPath<TValue>] : TPathToCheck extends readonly [infer TFirstKey extends ExactKeysOfArrayPath<TValue>, ...infer TPathRest extends Path] ? LazyArrayPath<Required<PropertiesOfArrayPath<TValue>[TFirstKey]>, TPathRest, readonly [...TValidPath, TFirstKey]> : IsNever<ExactKeysOfArrayPath<TValue>> extends false ? readonly [...TValidPath, ExactKeysOfArrayPath<TValue>] : never;
+/**
+* Returns the path if valid, otherwise the first possible valid array path
+* based on the given value.
+*/
+type ValidArrayPath<TValue, TPath extends RequiredPath> = TPath extends LazyArrayPath<Required<TValue>, TPath> ? TPath : LazyArrayPath<Required<TValue>, TPath>;
+/**
+* Recursive helper for `DirtyPath` that prepends `TKey` to each deeper path,
+* or falls through to `never` when the child is not an object.
+*/
+type DeepDirtyPath<TChild, TKey$1 extends PathKey, TDepth extends 0[]> = TChild extends Record<PropertyKey, unknown> ? readonly [TKey$1, ...DirtyPath<TChild, [...TDepth, 0]>] : never;
+/**
+* Returns the union of all `RequiredPath`s that `getDirtyPaths` can emit
+* for a given input type. Object fields contribute their own path and the
+* paths of their descendants; arrays and tuples are atomic and contribute
+* only their own path, because dirty arrays are returned as complete units.
+*
+* Narrowing is exact for the first 5 levels of nesting; deeper paths fall
+* back to `RequiredPath` to keep the result a complete superset of any
+* path the runtime can address.
+*
+* Hint: Arrays and tuples are atomic because they don't structurally
+* extend `Record<PropertyKey, unknown>` and so fall through to `never`
+* via `DeepDirtyPath` — no explicit array check is needed. `TDepth` is
+* a tuple-length counter capped at 5 to bound TypeScript instantiation
+* cost.
+*/
+type DirtyPath<TValue, TDepth extends 0[] = []> = TDepth["length"] extends 5 ? RequiredPath : TValue extends Record<PropertyKey, unknown> ? { [TKey in ExactKeysOf<TValue>]: readonly [TKey] | DeepDirtyPath<NonNullable<PropertiesOf<TValue>[TKey]>, TKey, TDepth> }[ExactKeysOf<TValue>] : never;
+/**
+* Recursive helper for `FieldPath` that prepends `TKey` to each deeper field
+* path, or falls through to `never` when the child is a leaf value.
+*/
+type DeepFieldPath<TChild, TKey$1 extends PathKey, TDepth extends 0[]> = TChild extends readonly unknown[] | Record<PropertyKey, unknown> ? readonly [TKey$1, ...FieldPath<TChild, [...TDepth, 0]>] : never;
+/**
+* Returns the union of all `RequiredPath`s that address a field within the
+* given input type. Object and array fields contribute their own path and the
+* paths of their descendants; unlike `DirtyPath`, arrays are recursed into so
+* that fields at any depth, including array items, can be addressed. Leaf
+* values contribute only their own path (emitted by their parent).
+*
+* Narrowing is exact for the first 5 levels of nesting; deeper paths fall
+* back to `RequiredPath` to keep the result a complete superset of any path
+* the runtime can address. `TDepth` is a tuple-length counter capped at 5 to
+* bound TypeScript instantiation cost.
+*/
+type FieldPath<TValue, TDepth extends 0[] = []> = TDepth["length"] extends 5 ? RequiredPath : TValue extends readonly unknown[] | Record<PropertyKey, unknown> ? { [TKey in ExactKeysOf<TValue>]: readonly [TKey] | DeepFieldPath<NonNullable<PropertiesOf<TValue>[TKey]>, TKey, TDepth> }[ExactKeysOf<TValue>] : never;
+//#endregion
 //#region src/types/schema/schema.d.ts
 /**
 * Schema type.
@@ -59,6 +230,10 @@ interface InternalBaseStore {
   */
   name: string;
   /**
+  * The path to the field.
+  */
+  path: Path;
+  /**
   * The schema of the field.
   */
   schema: Schema;
@@ -86,6 +261,15 @@ interface InternalBaseStore {
   */
   isTouched: Signal<boolean>;
   /**
+  * The edited state of the field.
+  *
+  * Hint: Unlike `isTouched`, which is also set when a field is focused, this
+  * is only set when the field's value is changed. Unlike `isDirty`, it stays
+  * `true` even if the value is changed back to its initial value. It is only
+  * reset when the field is reset.
+  */
+  isEdited: Signal<boolean>;
+  /**
   * The dirty state of the field.
   */
   isDirty: Signal<boolean>;
@@ -99,6 +283,14 @@ interface InternalArrayStore extends InternalBaseStore {
   */
   kind: "array";
   /**
+  * Whether the array schema is wrapped in a nullish schema.
+  *
+  * Hint: This indicates whether a missing input should be represented as the
+  * nullish value (`null`/`undefined`) or as a present but empty array
+  * (`true`). It keeps resetting consistent with the initial state.
+  */
+  isNullish: boolean;
+  /**
   * The children of the array field.
   */
   children: InternalFieldStore[];
@@ -151,6 +343,14 @@ interface InternalObjectStore extends InternalBaseStore {
   */
   kind: "object";
   /**
+  * Whether the object schema is wrapped in a nullish schema.
+  *
+  * Hint: This indicates whether a missing input should be represented as the
+  * nullish value (`null`/`undefined`) or as a present but empty object
+  * (`true`). It keeps resetting consistent with the initial state.
+  */
+  isNullish: boolean;
+  /**
   * The children of the object field.
   */
   children: Record<string, InternalFieldStore>;
@@ -214,32 +414,6 @@ type InternalFieldStore = InternalArrayStore | InternalObjectStore | InternalVal
 */
 declare const INTERNAL: "~internal";
 //#endregion
-//#region src/types/utils/utils.d.ts
-/**
-* Checks if a type is `any`.
-*/
-type IsAny<T> = 0 extends 1 & T ? true : false;
-/**
-* Checks if a type is `never`.
-*/
-type IsNever<T> = [T] extends [never] ? true : false;
-/**
-* Constructs a type that is maybe a promise.
-*/
-type MaybePromise<T> = T | Promise<T>;
-/**
-* Makes all properties deeply optional.
-*/
-type DeepPartial<TValue> = TValue extends Record<PropertyKey, unknown> | readonly unknown[] ? { [TKey in keyof TValue]?: DeepPartial<TValue[TKey]> | undefined } : TValue | undefined;
-/**
-* Makes all value properties optional.
-*
-* Hint: For dynamic arrays, only plain objects and nested arrays have their
-* values made optional. Primitives and class instances are kept as-is to avoid
-* types like `(string | undefined)[]`.
-*/
-type PartialValues<TValue> = TValue extends readonly (infer TItem)[] ? number extends TValue["length"] ? (TItem extends Record<PropertyKey, unknown> | readonly unknown[] ? { [TKey in keyof TItem]: PartialValues<TItem[TKey]> } : TItem)[] : { [TKey in keyof TValue]: PartialValues<TValue[TKey]> } : TValue extends Record<PropertyKey, unknown> ? { [TKey in keyof TValue]: PartialValues<TValue[TKey]> } : TValue | undefined;
-//#endregion
 //#region src/types/form/form.d.ts
 /**
 * Validation mode type.
@@ -323,177 +497,138 @@ type SubmitHandler<TSchema extends FormSchema> = (output: v.InferOutput<TSchema>
 */
 type SubmitEventHandler<TSchema extends FormSchema> = (output: v.InferOutput<TSchema>, event: SubmitEvent) => MaybePromise<unknown>;
 //#endregion
-//#region src/types/path/path.d.ts
-/**
-* Path key type.
-*/
-type PathKey = string | number;
-/**
-* Path type.
-*/
-type Path = readonly PathKey[];
+//#region src/array/copyItemState/copyItemState.d.ts
 /**
-* Required path type.
+* Copies the deeply nested state (signal values) from one field store to
+* another. This includes the `elements`, `errors`, `startInput`, `input`,
+* `isTouched`, `isEdited`, `isDirty`, and for arrays `startItems` and `items`
+* properties. Recursively walks through the field stores and copies all signal
+* values.
+*
+* @param fromInternalFieldStore The source field store to copy from.
+* @param toInternalFieldStore The destination field store to copy to.
 */
-type RequiredPath = readonly [PathKey, ...Path];
+//#endregion
+//#region ../../packages/methods/dist/index.preact.d.ts
+//#region src/focus/focus.d.ts
+
 /**
-* Extracts the exact keys of a tuple, array or object. Tuples return their
-* literal numeric indices, dynamic arrays return `number`, objects return
-* their `keyof` keys, and any other input returns `never`.
+* Focus field config interface.
 */
-type ExactKeysOf<TValue> = IsAny<TValue> extends true ? never : TValue extends readonly unknown[] ? number extends TValue["length"] ? number : { [TKey in keyof TValue]: TKey extends `${infer TIndex extends number}` ? TIndex : never }[number] : TValue extends Record<PropertyKey, unknown> ? keyof TValue & PathKey : never;
+interface FocusFieldConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
+  /**
+  * The path to the field to focus.
+  */
+  readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+}
 /**
-* Returns the flat object of all indexable properties of `TValue`. For object
-* unions, properties from every member are merged so that any single property
-* is accessible. For primitives and other non-indexable types, the result is
-* `{}`.
+* Focuses the first focusable input element of a field. This is useful for
+* programmatically setting focus to a specific field, such as after
+* validation errors or user interactions.
 *
-* Hint: This is necessary to make properties accessible across union members.
-* By default, properties that do not exist in all union options are not
-* accessible and result in "any" when accessed.
+* @param form The form store containing the field.
+* @param config The focus field configuration.
 */
-type PropertiesOf<TValue> = { [TKey in ExactKeysOf<TValue>]: TValue extends Record<TKey, infer TItem> ? TItem : never };
+declare function focus<TSchema extends FormSchema, TFieldPath extends RequiredPath>(form: BaseFormStore<TSchema>, config: FocusFieldConfig<TSchema, TFieldPath>): void;
+//#endregion
+//#region src/getDeepErrorEntries/getDeepErrorEntries.d.ts
 /**
-* Lazily evaluates only the first valid path segment based on the given value.
+* Deep error entry interface.
 */
-type LazyPath<TValue, TPathToCheck extends Path, TValidPath extends Path = readonly []> = TPathToCheck extends readonly [] ? TValidPath : TPathToCheck extends readonly [infer TFirstKey extends ExactKeysOf<TValue>, ...infer TPathRest extends Path] ? LazyPath<Required<PropertiesOf<TValue>[TFirstKey]>, TPathRest, readonly [...TValidPath, TFirstKey]> : IsNever<ExactKeysOf<TValue>> extends false ? readonly [...TValidPath, ExactKeysOf<TValue>] : TValidPath;
+interface DeepErrorEntry<TValue = unknown> {
+  /**
+  * The path to the field with errors, or an empty path for form-level errors.
+  */
+  readonly path: unknown extends TValue ? Path : readonly [] | FieldPath<TValue>;
+  /**
+  * The error messages of the field.
+  */
+  readonly errors: [string, ...string[]];
+}
 /**
-* Returns the path if valid, otherwise the first possible valid path based on
-* the given value.
+* Get form deep error entries config interface.
 */
-type ValidPath<TValue, TPath extends RequiredPath> = TPath extends LazyPath<Required<TValue>, TPath> ? TPath : LazyPath<Required<TValue>, TPath>;
+interface GetFormDeepErrorEntriesConfig {
+  /**
+  * The path to a field. Leave undefined to get the entries of the entire form.
+  */
+  readonly path?: undefined;
+}
 /**
-* Detects whether the consuming project is configured with
-* `exactOptionalPropertyTypes: true`.
-*
-* Hint: If `false` the built-in `Required<T>` strips `| undefined` from
-* optional properties, so `Required<{ key?: undefined }>['key']` collapses
-* to `never` — under strict mode the same expression yields `undefined`.
+* Get field deep error entries config interface.
 */
-type IsExactOptionalProps = Required<{
-  key?: undefined;
-}>["key"] extends never ? false : true;
+interface GetFieldDeepErrorEntriesConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
+  /**
+  * The path to the field to retrieve the entries from.
+  */
+  readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+}
 /**
-* Like the built-in `Required<T>`, but preserves `| undefined` in two
-* places where `Required<T>` strips it:
+* Retrieves the errors of a specific field or the entire form as a list of
+* entries, each pairing the path to a field with its error messages. This is
+* useful for building custom error summaries that link each message back to
+* its field. Form-level errors are included with an empty path.
 *
-* 1. Optional property values under `exactOptionalPropertyTypes: false`
-*    — without this, input typings for `v.optional`/`v.nullish` schemas
-*    narrow incorrectly (issue #15).
-* 2. Array/tuple element types — e.g. `(string | undefined)[]` stays
-*    `(string | undefined)[]` instead of becoming `string[]`. Arrays
-*    fall through unchanged because they only have a numeric index
-*    signature and don't structurally extend `Record<PropertyKey,
-*    unknown>` (which requires string keys).
-*/
-type ExactRequired<TValue> = TValue extends Record<PropertyKey, unknown> ? IsExactOptionalProps extends true ? Required<TValue> : { [TKey in keyof Required<TValue>]: TValue[TKey] } : TValue;
-/**
-* Extracts the value type at the given path.
-*/
-type PathValue<TValue, TPath extends Path> = TPath extends readonly [infer TKey, ...infer TRest extends Path] ? TKey extends ExactKeysOf<ExactRequired<TValue>> ? PathValue<PropertiesOf<ExactRequired<TValue>>[TKey], TRest> : unknown : TValue;
-/**
-* Checks whether a value is a dynamic array or contains one anywhere in its
-* shape. A fixed-length tuple is not itself a dynamic array, but it counts when
-* it contains one, so paths can still navigate through tuples to reach nested
-* arrays.
+* @param form The form store to retrieve error entries from.
 *
-* Hint: The inner conditionals (`TValue extends readonly unknown[]` and
-* `TValue extends Record<PropertyKey, unknown>`) distribute over union members,
-* so the inner expression returns the union of each member's result (e.g.
-* `true | false` when some members contain arrays and others don't).
-* Downstream code uses `IsOrHasArray<T> extends true`, but
-* `boolean extends true` is `false` — so we collapse the result via
-* `true extends ...`, which is `true` whenever at least one union member
-* contributed `true`.
+* @returns A list of path and error message entries.
 */
-type IsOrHasArray<TValue> = true extends (IsAny<TValue> extends true ? false : TValue extends readonly unknown[] ? number extends TValue["length"] ? true : IsOrHasArray<TValue[number]> : TValue extends Record<PropertyKey, unknown> ? { [TKey in keyof TValue]: IsOrHasArray<TValue[TKey]> }[keyof TValue] : false) ? true : false;
-/**
-* Extracts the exact keys of a tuple, array or object that contain arrays.
-*/
-type ExactKeysOfArrayPath<TValue> = IsAny<TValue> extends true ? never : TValue extends readonly (infer TItem)[] ? number extends TValue["length"] ? IsOrHasArray<TItem> extends true ? number : never : { [TKey in keyof TValue]: TKey extends `${infer TIndex extends number}` ? IsOrHasArray<NonNullable<TValue[TKey]>> extends true ? TIndex : never : never }[number] : TValue extends Record<PropertyKey, unknown> ? { [TKey in keyof TValue]: IsOrHasArray<NonNullable<TValue[TKey]>> extends true ? TKey : never }[keyof TValue] & PathKey : never;
-/**
-* Returns the flat object of indexable properties of `TValue` whose values
-* are or contain arrays. Mirrors `PropertiesOf` but keyed by
-* `ExactKeysOfArrayPath` so the lookup is provably valid for array-path
-* navigation in `LazyArrayPath`.
-*/
-type PropertiesOfArrayPath<TValue> = { [TKey in ExactKeysOfArrayPath<TValue>]: TValue extends Record<TKey, infer TItem> ? TItem : never };
-/**
-* Lazily evaluates only the first valid array path segment based on the given value.
-*/
-type LazyArrayPath<TValue, TPathToCheck extends Path, TValidPath extends Path = readonly []> = TPathToCheck extends readonly [] ? TValue extends readonly unknown[] ? number extends TValue["length"] ? TValidPath : IsNever<ExactKeysOfArrayPath<TValue>> extends false ? readonly [...TValidPath, ExactKeysOfArrayPath<TValue>] : never : readonly [...TValidPath, ExactKeysOfArrayPath<TValue>] : TPathToCheck extends readonly [infer TFirstKey extends ExactKeysOfArrayPath<TValue>, ...infer TPathRest extends Path] ? LazyArrayPath<Required<PropertiesOfArrayPath<TValue>[TFirstKey]>, TPathRest, readonly [...TValidPath, TFirstKey]> : IsNever<ExactKeysOfArrayPath<TValue>> extends false ? readonly [...TValidPath, ExactKeysOfArrayPath<TValue>] : never;
+declare function getDeepErrorEntries<TSchema extends FormSchema>(form: BaseFormStore<TSchema>): DeepErrorEntry<v.InferInput<TSchema>>[];
 /**
-* Returns the path if valid, otherwise the first possible valid array path
-* based on the given value.
-*/
-type ValidArrayPath<TValue, TPath extends RequiredPath> = TPath extends LazyArrayPath<Required<TValue>, TPath> ? TPath : LazyArrayPath<Required<TValue>, TPath>;
-/**
-* Recursive helper for `DirtyPath` that prepends `TKey` to each deeper path,
-* or falls through to `never` when the child is not an object.
-*/
-type DeepDirtyPath<TChild, TKey$1 extends PathKey, TDepth extends 0[]> = TChild extends Record<PropertyKey, unknown> ? readonly [TKey$1, ...DirtyPath<TChild, [...TDepth, 0]>] : never;
-/**
-* Returns the union of all `RequiredPath`s that `getDirtyPaths` can emit
-* for a given input type. Object fields contribute their own path and the
-* paths of their descendants; arrays and tuples are atomic and contribute
-* only their own path, because dirty arrays are returned as complete units.
+* Retrieves the errors of a specific field or the entire form as a list of
+* entries, each pairing the path to a field with its error messages. This is
+* useful for building custom error summaries that link each message back to
+* its field. Form-level errors are included with an empty path.
 *
-* Narrowing is exact for the first 5 levels of nesting; deeper paths fall
-* back to `RequiredPath` to keep the result a complete superset of any
-* path the runtime can address.
+* @param form The form store to retrieve error entries from.
+* @param config The get deep error entries configuration.
 *
-* Hint: Arrays and tuples are atomic because they don't structurally
-* extend `Record<PropertyKey, unknown>` and so fall through to `never`
-* via `DeepDirtyPath` — no explicit array check is needed. `TDepth` is
-* a tuple-length counter capped at 5 to bound TypeScript instantiation
-* cost.
+* @returns A list of path and error message entries.
 */
-type DirtyPath<TValue, TDepth extends 0[] = []> = TDepth["length"] extends 5 ? RequiredPath : TValue extends Record<PropertyKey, unknown> ? { [TKey in ExactKeysOf<TValue>]: readonly [TKey] | DeepDirtyPath<NonNullable<PropertiesOf<TValue>[TKey]>, TKey, TDepth> }[ExactKeysOf<TValue>] : never;
+declare function getDeepErrorEntries<TSchema extends FormSchema, TFieldPath extends RequiredPath | undefined = undefined>(form: BaseFormStore<TSchema>, config: TFieldPath extends RequiredPath ? GetFieldDeepErrorEntriesConfig<TSchema, TFieldPath> : GetFormDeepErrorEntriesConfig): DeepErrorEntry<v.InferInput<TSchema>>[];
 //#endregion
-//#region src/array/copyItemState/copyItemState.d.ts
+//#region src/getDeepErrors/getDeepErrors.d.ts
 /**
-* Copies the deeply nested state (signal values) from one field store to
-* another. This includes the `elements`, `errors`, `startInput`, `input`,
-* `isTouched`, `isDirty`, and for arrays `startItems` and `items` properties.
-* Recursively walks through the field stores and copies all signal values.
-*
-* @param fromInternalFieldStore The source field store to copy from.
-* @param toInternalFieldStore The destination field store to copy to.
+* Get form deep errors config interface.
 */
-//#endregion
-//#region ../../packages/methods/dist/index.preact.d.ts
-//#region src/focus/focus.d.ts
-
+interface GetFormDeepErrorsConfig {
+  /**
+  * The path to a field. Leave undefined to get the errors of the entire form.
+  */
+  readonly path?: undefined;
+}
 /**
-* Focus field config interface.
+* Get field deep errors config interface.
 */
-interface FocusFieldConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
+interface GetFieldDeepErrorsConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
   /**
-  * The path to the field to focus.
+  * The path to the field to retrieve the errors from.
   */
   readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
 }
 /**
-* Focuses the first focusable input element of a field. This is useful for
-* programmatically setting focus to a specific field, such as after
-* validation errors or user interactions.
+* Retrieves all error messages of a specific field or the entire form by
+* walking through the field store and all its descendants. This is useful for
+* displaying a summary of all validation errors within a section or the whole
+* form. Form-level errors are included.
 *
-* @param form The form store containing the field.
-* @param config The focus field configuration.
+* @param form The form store to retrieve errors from.
+*
+* @returns A non-empty array of error messages, or null if no errors exist.
 */
-declare function focus<TSchema extends FormSchema, TFieldPath extends RequiredPath>(form: BaseFormStore<TSchema>, config: FocusFieldConfig<TSchema, TFieldPath>): void;
-//#endregion
-//#region src/getAllErrors/getAllErrors.d.ts
+declare function getDeepErrors<TSchema extends FormSchema>(form: BaseFormStore<TSchema>): [string, ...string[]] | null;
 /**
-* Retrieves all error messages from all fields in the form by walking through
-* the entire field store tree. This is useful for displaying a summary of all
-* validation errors across the form.
+* Retrieves all error messages of a specific field or the entire form by
+* walking through the field store and all its descendants. This is useful for
+* displaying a summary of all validation errors within a section or the whole
+* form. Form-level errors are included.
 *
 * @param form The form store to retrieve errors from.
+* @param config The get deep errors configuration.
 *
 * @returns A non-empty array of error messages, or null if no errors exist.
 */
-declare function getAllErrors(form: BaseFormStore): [string, ...string[]] | null;
+declare function getDeepErrors<TSchema extends FormSchema, TFieldPath extends RequiredPath | undefined = undefined>(form: BaseFormStore<TSchema>, config: TFieldPath extends RequiredPath ? GetFieldDeepErrorsConfig<TSchema, TFieldPath> : GetFormDeepErrorsConfig): [string, ...string[]] | null;
 //#endregion
 //#region src/getDirtyInput/getDirtyInput.d.ts
 /**
@@ -713,6 +848,172 @@ interface InsertConfig<TSchema extends FormSchema, TFieldArrayPath extends Requi
 */
 declare function insert<TSchema extends FormSchema, TFieldArrayPath extends RequiredPath>(form: BaseFormStore<TSchema>, config: InsertConfig<TSchema, TFieldArrayPath>): void;
 //#endregion
+//#region src/isDirty/isDirty.d.ts
+/**
+* Is form dirty config interface.
+*/
+interface IsFormDirtyConfig {
+  /**
+  * The path to a field. Leave undefined to check the entire form.
+  */
+  readonly path?: undefined;
+}
+/**
+* Is field dirty config interface.
+*/
+interface IsFieldDirtyConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
+  /**
+  * The path to the field to check for dirtiness.
+  */
+  readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+}
+/**
+* Checks whether a specific field or the entire form is dirty by walking
+* through the field store and all its descendants. A field is dirty when its
+* input differs from its initial value.
+*
+* @param form The form store to check for dirtiness.
+*
+* @returns Whether the field or form is dirty.
+*/
+declare function isDirty<TSchema extends FormSchema>(form: BaseFormStore<TSchema>): boolean;
+/**
+* Checks whether a specific field or the entire form is dirty by walking
+* through the field store and all its descendants. A field is dirty when its
+* input differs from its initial value.
+*
+* @param form The form store to check for dirtiness.
+* @param config The is dirty configuration.
+*
+* @returns Whether the field or form is dirty.
+*/
+declare function isDirty<TSchema extends FormSchema, TFieldPath extends RequiredPath | undefined = undefined>(form: BaseFormStore<TSchema>, config: TFieldPath extends RequiredPath ? IsFieldDirtyConfig<TSchema, TFieldPath> : IsFormDirtyConfig): boolean;
+//#endregion
+//#region src/isEdited/isEdited.d.ts
+/**
+* Is form edited config interface.
+*/
+interface IsFormEditedConfig {
+  /**
+  * The path to a field. Leave undefined to check the entire form.
+  */
+  readonly path?: undefined;
+}
+/**
+* Is field edited config interface.
+*/
+interface IsFieldEditedConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
+  /**
+  * The path to the field to check for being edited.
+  */
+  readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+}
+/**
+* Checks whether a specific field or the entire form is edited by walking
+* through the field store and all its descendants. A field is edited once its
+* value has been changed by the user.
+*
+* @param form The form store to check for being edited.
+*
+* @returns Whether the field or form is edited.
+*/
+declare function isEdited<TSchema extends FormSchema>(form: BaseFormStore<TSchema>): boolean;
+/**
+* Checks whether a specific field or the entire form is edited by walking
+* through the field store and all its descendants. A field is edited once its
+* value has been changed by the user.
+*
+* @param form The form store to check for being edited.
+* @param config The is edited configuration.
+*
+* @returns Whether the field or form is edited.
+*/
+declare function isEdited<TSchema extends FormSchema, TFieldPath extends RequiredPath | undefined = undefined>(form: BaseFormStore<TSchema>, config: TFieldPath extends RequiredPath ? IsFieldEditedConfig<TSchema, TFieldPath> : IsFormEditedConfig): boolean;
+//#endregion
+//#region src/isTouched/isTouched.d.ts
+/**
+* Is form touched config interface.
+*/
+interface IsFormTouchedConfig {
+  /**
+  * The path to a field. Leave undefined to check the entire form.
+  */
+  readonly path?: undefined;
+}
+/**
+* Is field touched config interface.
+*/
+interface IsFieldTouchedConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
+  /**
+  * The path to the field to check for being touched.
+  */
+  readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+}
+/**
+* Checks whether a specific field or the entire form is touched by walking
+* through the field store and all its descendants. A field is touched once it
+* has received and lost focus.
+*
+* @param form The form store to check for being touched.
+*
+* @returns Whether the field or form is touched.
+*/
+declare function isTouched<TSchema extends FormSchema>(form: BaseFormStore<TSchema>): boolean;
+/**
+* Checks whether a specific field or the entire form is touched by walking
+* through the field store and all its descendants. A field is touched once it
+* has received and lost focus.
+*
+* @param form The form store to check for being touched.
+* @param config The is touched configuration.
+*
+* @returns Whether the field or form is touched.
+*/
+declare function isTouched<TSchema extends FormSchema, TFieldPath extends RequiredPath | undefined = undefined>(form: BaseFormStore<TSchema>, config: TFieldPath extends RequiredPath ? IsFieldTouchedConfig<TSchema, TFieldPath> : IsFormTouchedConfig): boolean;
+//#endregion
+//#region src/isValid/isValid.d.ts
+/**
+* Is form valid config interface.
+*/
+interface IsFormValidConfig {
+  /**
+  * The path to a field. Leave undefined to check the entire form.
+  */
+  readonly path?: undefined;
+}
+/**
+* Is field valid config interface.
+*/
+interface IsFieldValidConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
+  /**
+  * The path to the field to check for validity.
+  */
+  readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+}
+/**
+* Checks whether a specific field or the entire form is valid by walking
+* through the field store and all its descendants. A field is valid when
+* neither it nor any of its descendants contains an error. Form-level errors
+* are included.
+*
+* @param form The form store to check for validity.
+*
+* @returns Whether the field or form is valid.
+*/
+declare function isValid<TSchema extends FormSchema>(form: BaseFormStore<TSchema>): boolean;
+/**
+* Checks whether a specific field or the entire form is valid by walking
+* through the field store and all its descendants. A field is valid when
+* neither it nor any of its descendants contains an error. Form-level errors
+* are included.
+*
+* @param form The form store to check for validity.
+* @param config The is valid configuration.
+*
+* @returns Whether the field or form is valid.
+*/
+declare function isValid<TSchema extends FormSchema, TFieldPath extends RequiredPath | undefined = undefined>(form: BaseFormStore<TSchema>, config: TFieldPath extends RequiredPath ? IsFieldValidConfig<TSchema, TFieldPath> : IsFormValidConfig): boolean;
+//#endregion
 //#region src/move/move.d.ts
 /**
 * Move array field config interface.
@@ -828,6 +1129,10 @@ interface ResetBaseConfig {
   */
   readonly keepTouched?: boolean | undefined;
   /**
+  * Whether to keep the edited state during reset. Defaults to false.
+  */
+  readonly keepEdited?: boolean | undefined;
+  /**
   * Whether to keep the error messages during reset. Defaults to false.
   */
   readonly keepErrors?: boolean | undefined;
@@ -1078,6 +1383,10 @@ interface FieldStore<TSchema extends FormSchema = FormSchema, TFieldPath extends
   */
   readonly isTouched: ReadonlySignal<boolean>;
   /**
+  * Whether the field value has been edited.
+  */
+  readonly isEdited: ReadonlySignal<boolean>;
+  /**
   * Whether the field input differs from its initial value.
   */
   readonly isDirty: ReadonlySignal<boolean>;
@@ -1115,6 +1424,10 @@ interface FieldArrayStore<TSchema extends FormSchema = FormSchema, TFieldArrayPa
   */
   readonly isTouched: ReadonlySignal<boolean>;
   /**
+  * Whether the field array value has been edited.
+  */
+  readonly isEdited: ReadonlySignal<boolean>;
+  /**
   * Whether the field array input differs from its initial value.
   */
   readonly isDirty: ReadonlySignal<boolean>;
@@ -1146,6 +1459,10 @@ interface FormStore<TSchema extends FormSchema = FormSchema> extends BaseFormSto
   */
   readonly isTouched: ReadonlySignal<boolean>;
   /**
+  * Whether any field in the form has been edited.
+  */
+  readonly isEdited: ReadonlySignal<boolean>;
+  /**
   * Whether any field in the form differs from its initial value.
   */
   readonly isDirty: ReadonlySignal<boolean>;
@@ -1157,7 +1474,7 @@ interface FormStore<TSchema extends FormSchema = FormSchema> extends BaseFormSto
   * The current error messages of the form.
   *
   * Hint: This property only contains validation errors at the root level
-  * of the form. To get all errors from all fields, use `getAllErrors`.
+  * of the form. To get all errors from all fields, use `getDeepErrors`.
   */
   readonly errors: ReadonlySignal<[string, ...string[]] | null>;
 }
@@ -1304,4 +1621,4 @@ declare function useFieldArray<TSchema extends FormSchema, TFieldArrayPath exten
 */
 declare function useForm<TSchema extends FormSchema>(config: FormConfig<TSchema>): FormStore<TSchema>;
 //#endregion
-export { type DeepPartial, Field, FieldArray, FieldArrayProps, FieldArrayStore, type FieldElement, FieldElementProps, FieldProps, FieldStore, FocusFieldConfig, Form, type FormConfig, FormProps, type FormSchema, FormStore, GetFieldDirtyInputConfig, GetFieldDirtyPathsConfig, GetFieldErrorsConfig, GetFieldInputConfig, GetFormDirtyInputConfig, GetFormDirtyPathsConfig, GetFormErrorsConfig, GetFormInputConfig, InsertConfig, MoveConfig, type PartialValues, type PathValue, PickDirtyConfig, RemoveConfig, ReplaceConfig, type RequiredPath, ResetFieldConfig, ResetFormConfig, type Schema, SetFieldErrorsConfig, SetFieldInputConfig, SetFormErrorsConfig, SetFormInputConfig, type SubmitEventHandler, type SubmitHandler, SwapConfig, UseFieldArrayConfig, UseFieldConfig, type ValidArrayPath, type ValidPath, ValidateFormConfig, type ValidationMode, focus, getAllErrors, getDirtyInput, getDirtyPaths, getErrors, getInput, handleSubmit, insert, move, pickDirty, remove, replace, reset, setErrors, setInput, submit, swap, useField, useFieldArray, useForm, validate };
+export { DeepErrorEntry, type DeepPartial, Field, FieldArray, FieldArrayProps, FieldArrayStore, type FieldElement, FieldElementProps, FieldProps, FieldStore, FocusFieldConfig, Form, type FormConfig, FormProps, type FormSchema, FormStore, GetFieldDeepErrorEntriesConfig, GetFieldDeepErrorsConfig, GetFieldDirtyInputConfig, GetFieldDirtyPathsConfig, GetFieldErrorsConfig, GetFieldInputConfig, GetFormDeepErrorEntriesConfig, GetFormDeepErrorsConfig, GetFormDirtyInputConfig, GetFormDirtyPathsConfig, GetFormErrorsConfig, GetFormInputConfig, InsertConfig, IsFieldDirtyConfig, IsFieldEditedConfig, IsFieldTouchedConfig, IsFieldValidConfig, IsFormDirtyConfig, IsFormEditedConfig, IsFormTouchedConfig, IsFormValidConfig, MoveConfig, type PartialValues, type PathValue, PickDirtyConfig, RemoveConfig, ReplaceConfig, type RequiredPath, ResetFieldConfig, ResetFormConfig, type Schema, SetFieldErrorsConfig, SetFieldInputConfig, SetFormErrorsConfig, SetFormInputConfig, type SubmitEventHandler, type SubmitHandler, SwapConfig, UseFieldArrayConfig, UseFieldConfig, type ValidArrayPath, type ValidPath, ValidateFormConfig, type ValidationMode, focus, getDeepErrorEntries, getDeepErrors, getDirtyInput, getDirtyPaths, getErrors, getInput, handleSubmit, insert, isDirty, isEdited, isTouched, isValid, move, pickDirty, remove, replace, reset, setErrors, setInput, submit, swap, useField, useFieldArray, useForm, validate };

package/dist/index.js

@@ -37,11 +37,13 @@ function initializeFieldStore(internalFieldStore, schema, initialInput, path, nu
 	else {
 		internalFieldStore.schema = schema;
 		internalFieldStore.name = JSON.stringify(path);
+		internalFieldStore.path = path;
 		const initialElements = [];
 		internalFieldStore.initialElements = initialElements;
 		internalFieldStore.elements = initialElements;
 		internalFieldStore.errors = createSignal(null);
 		internalFieldStore.isTouched = createSignal(false);
+		internalFieldStore.isEdited = createSignal(false);
 		internalFieldStore.isDirty = createSignal(false);
 		if (schema.type === "array" || schema.type === "loose_tuple" || schema.type === "strict_tuple" || schema.type === "tuple") {
 			if (internalFieldStore.kind && internalFieldStore.kind !== "array") throw new Error(`Store initialized as "${internalFieldStore.kind}" cannot be reinitialized as "array"`);
@@ -51,16 +53,13 @@ function initializeFieldStore(internalFieldStore, schema, initialInput, path, nu
 				if (schema.type === "array") {
 					if (initialInput) for (let index = 0; index < initialInput.length; index++) {
 						internalFieldStore.children[index] = {};
-						path.push(index);
-						initializeFieldStore(internalFieldStore.children[index], schema.item, initialInput[index], path);
-						path.pop();
+						initializeFieldStore(internalFieldStore.children[index], schema.item, initialInput[index], [...path, index]);
 					}
 				} else for (let index = 0; index < schema.items.length; index++) {
 					internalFieldStore.children[index] = {};
-					path.push(index);
-					initializeFieldStore(internalFieldStore.children[index], schema.items[index], initialInput?.[index], path);
-					path.pop();
+					initializeFieldStore(internalFieldStore.children[index], schema.items[index], initialInput?.[index], [...path, index]);
 				}
+				internalFieldStore.isNullish = nullish;
 				const arrayInput = nullish && initialInput == null ? initialInput : true;
 				internalFieldStore.initialInput = createSignal(arrayInput);
 				internalFieldStore.startInput = createSignal(arrayInput);
@@ -77,10 +76,9 @@ function initializeFieldStore(internalFieldStore, schema, initialInput, path, nu
 				internalFieldStore.children ??= {};
 				for (const key in schema.entries) {
 					internalFieldStore.children[key] ??= {};
-					path.push(key);
-					initializeFieldStore(internalFieldStore.children[key], schema.entries[key], initialInput?.[key], path);
-					path.pop();
+					initializeFieldStore(internalFieldStore.children[key], schema.entries[key], initialInput?.[key], [...path, key]);
 				}
+				internalFieldStore.isNullish = nullish;
 				const objectInput = nullish && initialInput == null ? initialInput : true;
 				internalFieldStore.initialInput = createSignal(objectInput);
 				internalFieldStore.startInput = createSignal(objectInput);
@@ -100,8 +98,9 @@ function initializeFieldStore(internalFieldStore, schema, initialInput, path, nu
 /**
 * Copies the deeply nested state (signal values) from one field store to
 * another. This includes the `elements`, `errors`, `startInput`, `input`,
-* `isTouched`, `isDirty`, and for arrays `startItems` and `items` properties.
-* Recursively walks through the field stores and copies all signal values.
+* `isTouched`, `isEdited`, `isDirty`, and for arrays `startItems` and `items`
+* properties. Recursively walks through the field stores and copies all signal
+* values.
 *
 * @param fromInternalFieldStore The source field store to copy from.
 * @param toInternalFieldStore The destination field store to copy to.
@@ -114,19 +113,16 @@ function copyItemState(fromInternalFieldStore, toInternalFieldStore) {
 			toInternalFieldStore.startInput.value = fromInternalFieldStore.startInput.value;
 			toInternalFieldStore.input.value = fromInternalFieldStore.input.value;
 			toInternalFieldStore.isTouched.value = fromInternalFieldStore.isTouched.value;
+			toInternalFieldStore.isEdited.value = fromInternalFieldStore.isEdited.value;
 			toInternalFieldStore.isDirty.value = fromInternalFieldStore.isDirty.value;
 			if (fromInternalFieldStore.kind === "array" && toInternalFieldStore.kind === "array") {
 				const fromItems = fromInternalFieldStore.items.value;
 				toInternalFieldStore.startItems.value = fromInternalFieldStore.startItems.value;
 				toInternalFieldStore.items.value = fromItems;
-				let path;
 				for (let index = 0; index < fromItems.length; index++) {
 					if (!toInternalFieldStore.children[index]) {
-						path ??= JSON.parse(toInternalFieldStore.name);
 						toInternalFieldStore.children[index] = {};
-						path.push(index);
-						initializeFieldStore(toInternalFieldStore.children[index], toInternalFieldStore.schema.item, void 0, path);
-						path.pop();
+						initializeFieldStore(toInternalFieldStore.children[index], toInternalFieldStore.schema.item, void 0, [...toInternalFieldStore.path, index]);
 					}
 					copyItemState(fromInternalFieldStore.children[index], toInternalFieldStore.children[index]);
 				}
@@ -136,10 +132,10 @@ function copyItemState(fromInternalFieldStore, toInternalFieldStore) {
 }
 /**
 * Resets the state of a field store (signal values) deeply nested. Sets
-* `elements` to empty array, `errors` to `null`, `isTouched` and `isDirty` to
-* `false`, and `startInput`, `input`, `startItems`, and `items` to the new
-* input value. Keeps the `initialInput` and `initialItems` state unchanged for
-* form reset functionality.
+* `elements` to empty array, `errors` to `null`, `isTouched`, `isEdited` and
+* `isDirty` to `false`, and `startInput`, `input`, `startItems`, and `items` to
+* the new input value. Keeps the `initialInput` and `initialItems` state
+* unchanged for form reset functionality.
 *
 * @param internalFieldStore The field store to reset.
 * @param input The new input value (can be any type including array or object).
@@ -154,30 +150,32 @@ function resetItemState(internalFieldStore, input, keepStart = false) {
 		internalFieldStore.elements = elements;
 		internalFieldStore.errors.value = null;
 		internalFieldStore.isTouched.value = false;
+		internalFieldStore.isEdited.value = false;
 		internalFieldStore.isDirty.value = false;
 		if (internalFieldStore.kind === "array" || internalFieldStore.kind === "object") {
-			const objectInput = input == null ? input : true;
+			const objectInput = internalFieldStore.isNullish && input == null ? input : true;
 			if (!keepStart) internalFieldStore.startInput.value = objectInput;
 			internalFieldStore.input.value = objectInput;
-			if (internalFieldStore.kind === "array") if (input) {
-				const length = internalFieldStore.schema.type === "array" ? input.length : internalFieldStore.children.length;
-				const newItems = Array.from({ length }, createId);
-				if (!keepStart) internalFieldStore.startItems.value = newItems;
-				internalFieldStore.items.value = newItems;
-				let path;
-				for (let index = 0; index < length; index++) if (internalFieldStore.children[index]) resetItemState(internalFieldStore.children[index], input[index], keepStart);
-				else {
-					path ??= JSON.parse(internalFieldStore.name);
-					internalFieldStore.children[index] = {};
-					path.push(index);
-					initializeFieldStore(internalFieldStore.children[index], internalFieldStore.schema.item, input[index], path);
-					path.pop();
+			if (internalFieldStore.kind === "array") {
+				const isTuple = internalFieldStore.schema.type !== "array";
+				if (input || isTuple) {
+					const length = isTuple ? internalFieldStore.children.length : input.length;
+					const newItems = Array.from({ length }, createId);
+					if (!keepStart) internalFieldStore.startItems.value = newItems;
+					internalFieldStore.items.value = newItems;
+					for (let index = 0; index < length; index++) {
+						const itemInput = input?.[index];
+						if (internalFieldStore.children[index]) resetItemState(internalFieldStore.children[index], itemInput, keepStart);
+						else {
+							internalFieldStore.children[index] = {};
+							initializeFieldStore(internalFieldStore.children[index], internalFieldStore.schema.item, itemInput, [...internalFieldStore.path, index]);
+						}
+					}
+				} else {
+					if (!keepStart) internalFieldStore.startItems.value = [];
+					internalFieldStore.items.value = [];
 				}
-			} else {
-				if (!keepStart) internalFieldStore.startItems.value = [];
-				internalFieldStore.items.value = [];
-			}
-			else for (const key in internalFieldStore.children) resetItemState(internalFieldStore.children[key], input?.[key], keepStart);
+			} else for (const key in internalFieldStore.children) resetItemState(internalFieldStore.children[key], input?.[key], keepStart);
 		} else {
 			if (!keepStart) internalFieldStore.startInput.value = input;
 			internalFieldStore.input.value = input;
@@ -187,8 +185,8 @@ function resetItemState(internalFieldStore, input, keepStart = false) {
 /**
 * Swaps the deeply nested state (signal values) between two field stores. This
 * includes the `elements`, `errors`, `startInput`, `input`, `isTouched`,
-* `isDirty`, and for arrays `startItems` and `items` properties. Recursively
-* walks through the field stores and swaps all signal values.
+* `isEdited`, `isDirty`, and for arrays `startItems` and `items` properties.
+* Recursively walks through the field stores and swaps all signal values.
 *
 * @param firstInternalFieldStore The first field store to swap.
 * @param secondInternalFieldStore The second field store to swap.
@@ -211,6 +209,9 @@ function swapItemState(firstInternalFieldStore, secondInternalFieldStore) {
 			const tempIsTouched = firstInternalFieldStore.isTouched.value;
 			firstInternalFieldStore.isTouched.value = secondInternalFieldStore.isTouched.value;
 			secondInternalFieldStore.isTouched.value = tempIsTouched;
+			const tempIsEdited = firstInternalFieldStore.isEdited.value;
+			firstInternalFieldStore.isEdited.value = secondInternalFieldStore.isEdited.value;
+			secondInternalFieldStore.isEdited.value = tempIsEdited;
 			const tempIsDirty = firstInternalFieldStore.isDirty.value;
 			firstInternalFieldStore.isDirty.value = secondInternalFieldStore.isDirty.value;
 			secondInternalFieldStore.isDirty.value = tempIsDirty;
@@ -223,22 +224,14 @@ function swapItemState(firstInternalFieldStore, secondInternalFieldStore) {
 				firstInternalFieldStore.items.value = secondItems;
 				secondInternalFieldStore.items.value = firstItems;
 				const maxLength = Math.max(firstItems.length, secondItems.length);
-				let firstPath;
-				let secondPath;
 				for (let index = 0; index < maxLength; index++) {
 					if (!firstInternalFieldStore.children[index]) {
-						firstPath ??= JSON.parse(firstInternalFieldStore.name);
 						firstInternalFieldStore.children[index] = {};
-						firstPath.push(index);
-						initializeFieldStore(firstInternalFieldStore.children[index], firstInternalFieldStore.schema.item, void 0, firstPath);
-						firstPath.pop();
+						initializeFieldStore(firstInternalFieldStore.children[index], firstInternalFieldStore.schema.item, void 0, [...firstInternalFieldStore.path, index]);
 					}
 					if (!secondInternalFieldStore.children[index]) {
-						secondPath ??= JSON.parse(secondInternalFieldStore.name);
 						secondInternalFieldStore.children[index] = {};
-						secondPath.push(index);
-						initializeFieldStore(secondInternalFieldStore.children[index], secondInternalFieldStore.schema.item, void 0, secondPath);
-						secondPath.pop();
+						initializeFieldStore(secondInternalFieldStore.children[index], secondInternalFieldStore.schema.item, void 0, [...secondInternalFieldStore.path, index]);
 					}
 					swapItemState(firstInternalFieldStore.children[index], secondInternalFieldStore.children[index]);
 				}
@@ -269,6 +262,29 @@ function focusFieldElement(internalFieldStore) {
 	return false;
 }
 /**
+* Walks through the field store and all nested children, calling the callback
+* for each field store in depth-first order. The callback may return `true` to
+* stop the walk early, in which case `walkFieldStore` returns `true` as well.
+*
+* The walk reads array `items` reactively, so a reactive caller subscribes to
+* structural changes naturally. Imperative callers that must not subscribe
+* (e.g. when invoked inside an effect) should wrap the call in `untrack`.
+*
+* @param internalFieldStore The field store to walk.
+* @param callback The callback to invoke for each field store. Return `true` to stop the walk early.
+*
+* @returns Whether the walk was stopped early by the callback.
+*/
+function walkFieldStore(internalFieldStore, callback) {
+	if (callback(internalFieldStore)) return true;
+	if (internalFieldStore.kind === "array") {
+		for (let index = 0; index < internalFieldStore.items.value.length; index++) if (walkFieldStore(internalFieldStore.children[index], callback)) return true;
+	} else if (internalFieldStore.kind === "object") {
+		for (const key in internalFieldStore.children) if (walkFieldStore(internalFieldStore.children[key], callback)) return true;
+	}
+	return false;
+}
+/**
 * Returns whether the specified boolean property is true for the field store
 * or any of its nested children. Recursively checks arrays and objects.
 *
@@ -279,16 +295,7 @@ function focusFieldElement(internalFieldStore) {
 */
 /* @__NO_SIDE_EFFECTS__ */
 function getFieldBool(internalFieldStore, type) {
-	if (internalFieldStore[type].value) return true;
-	if (internalFieldStore.kind === "array") {
-		for (let index = 0; index < internalFieldStore.items.value.length; index++) if (/* @__PURE__ */ getFieldBool(internalFieldStore.children[index], type)) return true;
-		return false;
-	}
-	if (internalFieldStore.kind == "object") {
-		for (const key in internalFieldStore.children) if (/* @__PURE__ */ getFieldBool(internalFieldStore.children[key], type)) return true;
-		return false;
-	}
-	return false;
+	return walkFieldStore(internalFieldStore, (internalFieldStore$1) => Boolean(internalFieldStore$1[type].value));
 }
 /**
 * Returns only the dirty input of the field store. Arrays are treated as
@@ -406,9 +413,11 @@ function getFieldStore(internalFormStore, path) {
 */
 function setFieldBool(internalFieldStore, type, bool) {
 	batch(() => {
-		internalFieldStore[type].value = bool;
-		if (internalFieldStore.kind === "array") for (let index = 0; index < untrack(() => internalFieldStore.items.value).length; index++) setFieldBool(internalFieldStore.children[index], type, bool);
-		else if (internalFieldStore.kind === "object") for (const key in internalFieldStore.children) setFieldBool(internalFieldStore.children[key], type, bool);
+		untrack(() => {
+			walkFieldStore(internalFieldStore, (internalFieldStore$1) => {
+				internalFieldStore$1[type].value = bool;
+			});
+		});
 	});
 }
 /**
@@ -420,19 +429,17 @@ function setFieldBool(internalFieldStore, type, bool) {
 */
 function setNestedInput(internalFieldStore, input) {
 	internalFieldStore.isTouched.value = true;
+	internalFieldStore.isEdited.value = true;
 	if (internalFieldStore.kind === "array") {
 		const arrayInput = input ?? [];
 		const items = internalFieldStore.items.value;
 		const length = internalFieldStore.schema.type === "array" ? arrayInput.length : internalFieldStore.children.length;
 		if (length < items.length) internalFieldStore.items.value = items.slice(0, length);
 		else if (length > items.length) {
-			const path = JSON.parse(internalFieldStore.name);
 			for (let index = items.length; index < length; index++) if (internalFieldStore.children[index]) resetItemState(internalFieldStore.children[index], arrayInput[index], true);
 			else {
 				internalFieldStore.children[index] = {};
-				path.push(index);
-				initializeFieldStore(internalFieldStore.children[index], internalFieldStore.schema.item, arrayInput[index], path);
-				path.pop();
+				initializeFieldStore(internalFieldStore.children[index], internalFieldStore.schema.item, arrayInput[index], [...internalFieldStore.path, index]);
 			}
 			internalFieldStore.items.value = [...items, ...Array.from({ length: length - items.length }, createId)];
 		}
@@ -483,14 +490,9 @@ function setInitialFieldInput(internalFieldStore, initialInput) {
 			internalFieldStore.initialInput.value = initialInput == null ? initialInput : true;
 			const initialArrayInput = initialInput ?? [];
 			const length = internalFieldStore.schema.type === "array" ? initialArrayInput.length : internalFieldStore.children.length;
-			if (length > internalFieldStore.children.length) {
-				const path = JSON.parse(internalFieldStore.name);
-				for (let index = internalFieldStore.children.length; index < length; index++) {
-					internalFieldStore.children[index] = {};
-					path.push(index);
-					initializeFieldStore(internalFieldStore.children[index], internalFieldStore.schema.item, initialArrayInput[index], path);
-					path.pop();
-				}
+			if (length > internalFieldStore.children.length) for (let index = internalFieldStore.children.length; index < length; index++) {
+				internalFieldStore.children[index] = {};
+				initializeFieldStore(internalFieldStore.children[index], internalFieldStore.schema.item, initialArrayInput[index], [...internalFieldStore.path, index]);
 			}
 			internalFieldStore.initialItems.value = Array.from({ length }, createId);
 			for (let index = 0; index < internalFieldStore.children.length; index++) setInitialFieldInput(internalFieldStore.children[index], initialArrayInput[index]);
@@ -501,18 +503,6 @@ function setInitialFieldInput(internalFieldStore, initialInput) {
 	});
 }
 /**
-* Walks through the field store and all nested children, calling the callback
-* for each field store in depth-first order.
-*
-* @param internalFieldStore The field store to walk.
-* @param callback The callback to invoke for each field store.
-*/
-function walkFieldStore(internalFieldStore, callback) {
-	callback(internalFieldStore);
-	if (internalFieldStore.kind === "array") for (let index = 0; index < untrack(() => internalFieldStore.items.value).length; index++) walkFieldStore(internalFieldStore.children[index], callback);
-	else if (internalFieldStore.kind === "object") for (const key in internalFieldStore.children) walkFieldStore(internalFieldStore.children[key], callback);
-}
-/**
 * Creates a new internal form store from the provided configuration.
 * Initializes the field store hierarchy, sets validation modes, and
 * creates form state signals.
@@ -571,13 +561,15 @@ async function validateFormInput(internalFormStore, config) {
 		}
 		let shouldFocus = config?.shouldFocus ?? false;
 		batch(() => {
-			walkFieldStore(internalFormStore, (internalFieldStore) => {
-				if (internalFieldStore.name === "[]") internalFieldStore.errors.value = rootErrors ?? null;
-				else {
-					const fieldErrors = nestedErrors?.[internalFieldStore.name] ?? null;
-					internalFieldStore.errors.value = fieldErrors;
-					if (shouldFocus && fieldErrors && focusFieldElement(internalFieldStore)) shouldFocus = false;
-				}
+			untrack(() => {
+				walkFieldStore(internalFormStore, (internalFieldStore) => {
+					if (internalFieldStore.path.length === 0) internalFieldStore.errors.value = rootErrors ?? null;
+					else {
+						const fieldErrors = nestedErrors?.[internalFieldStore.name] ?? null;
+						internalFieldStore.errors.value = fieldErrors;
+						if (shouldFocus && fieldErrors && focusFieldElement(internalFieldStore)) shouldFocus = false;
+					}
+				});
 			});
 			internalFormStore.validators--;
 			internalFormStore.isValidating.value = internalFormStore.validators > 0;
@@ -621,25 +613,27 @@ const INTERNAL = "~internal";
 function focus(form, config) {
 	focusFieldElement(getFieldStore(form[INTERNAL], config.path));
 }
-/**
-* Retrieves all error messages from all fields in the form by walking through
-* the entire field store tree. This is useful for displaying a summary of all
-* validation errors across the form.
-*
-* @param form The form store to retrieve errors from.
-*
-* @returns A non-empty array of error messages, or null if no errors exist.
-*/
 /* @__NO_SIDE_EFFECTS__ */
-function getAllErrors(form) {
-	let allErrors = null;
-	walkFieldStore(form[INTERNAL], (internalFieldStore) => {
-		if (internalFieldStore.kind === "array") internalFieldStore.items.value;
+function getDeepErrorEntries(form, config) {
+	const entries = [];
+	walkFieldStore(config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL], (internalFieldStore) => {
 		const errors = internalFieldStore.errors.value;
-		if (errors) if (allErrors) allErrors.push(...errors);
-		else allErrors = [...errors];
+		if (errors) entries.push({
+			path: internalFieldStore.path,
+			errors
+		});
 	});
-	return allErrors;
+	return entries;
+}
+/* @__NO_SIDE_EFFECTS__ */
+function getDeepErrors(form, config) {
+	let deepErrors = null;
+	walkFieldStore(config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL], (internalFieldStore) => {
+		const errors = internalFieldStore.errors.value;
+		if (errors) if (deepErrors) deepErrors.push(...errors);
+		else deepErrors = [...errors];
+	});
+	return deepErrors;
 }
 /* @__NO_SIDE_EFFECTS__ */
 function getDirtyInput(form, config) {
@@ -647,9 +641,8 @@ function getDirtyInput(form, config) {
 }
 /* @__NO_SIDE_EFFECTS__ */
 function getDirtyPaths(form, config) {
-	config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL];
 	const paths = [];
-	config?.path && [...config.path];
+	config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL];
 	return paths;
 }
 /* @__NO_SIDE_EFFECTS__ */
@@ -700,25 +693,38 @@ function insert(form, config) {
 		internalArrayStore.items.value = newItems;
 		for (let index = items.length; index > insertIndex; index--) {
 			if (!internalArrayStore.children[index]) {
-				const path = JSON.parse(internalArrayStore.name);
 				internalArrayStore.children[index] = {};
-				path.push(index);
-				initializeFieldStore(internalArrayStore.children[index], internalArrayStore.schema.item, void 0, path);
+				initializeFieldStore(internalArrayStore.children[index], internalArrayStore.schema.item, void 0, [...internalArrayStore.path, index]);
 			}
 			copyItemState(internalArrayStore.children[index - 1], internalArrayStore.children[index]);
 		}
 		if (!internalArrayStore.children[insertIndex]) {
-			const path = JSON.parse(internalArrayStore.name);
 			internalArrayStore.children[insertIndex] = {};
-			path.push(insertIndex);
-			initializeFieldStore(internalArrayStore.children[insertIndex], internalArrayStore.schema.item, config.initialInput, path);
+			initializeFieldStore(internalArrayStore.children[insertIndex], internalArrayStore.schema.item, config.initialInput, [...internalArrayStore.path, insertIndex]);
 		} else resetItemState(internalArrayStore.children[insertIndex], config.initialInput);
 		internalArrayStore.input.value = true;
 		internalArrayStore.isTouched.value = true;
+		internalArrayStore.isEdited.value = true;
 		internalArrayStore.isDirty.value = true;
 		validateIfRequired(internalFormStore, internalArrayStore, "input");
 	});
 }
+/* @__NO_SIDE_EFFECTS__ */
+function isDirty(form, config) {
+	return getFieldBool(config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL], "isDirty");
+}
+/* @__NO_SIDE_EFFECTS__ */
+function isEdited(form, config) {
+	return getFieldBool(config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL], "isEdited");
+}
+/* @__NO_SIDE_EFFECTS__ */
+function isTouched(form, config) {
+	return getFieldBool(config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL], "isTouched");
+}
+/* @__NO_SIDE_EFFECTS__ */
+function isValid(form, config) {
+	return !getFieldBool(config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL], "errors");
+}
 /**
 * Moves an item from one index to another within a field array. All items
 * between the source and destination indices are shifted accordingly.
@@ -741,6 +747,7 @@ function move(form, config) {
 		else for (let index = config.from; index > config.to; index--) copyItemState(internalArrayStore.children[index - 1], internalArrayStore.children[index]);
 		copyItemState(tempInternalFieldStore, internalArrayStore.children[config.to]);
 		internalArrayStore.isTouched.value = true;
+		internalArrayStore.isEdited.value = true;
 		internalArrayStore.isDirty.value = internalArrayStore.startItems.value.join() !== newItems.join();
 		validateIfRequired(internalFormStore, internalArrayStore, "input");
 	});
@@ -804,6 +811,7 @@ function remove(form, config) {
 		internalArrayStore.items.value = newItems;
 		for (let index = config.at; index < items.length - 1; index++) copyItemState(internalArrayStore.children[index + 1], internalArrayStore.children[index]);
 		internalArrayStore.isTouched.value = true;
+		internalArrayStore.isEdited.value = true;
 		internalArrayStore.isDirty.value = internalArrayStore.startItems.value.join() !== newItems.join();
 		validateIfRequired(internalFormStore, internalArrayStore, "input");
 	});
@@ -824,6 +832,7 @@ function replace(form, config) {
 		internalArrayStore.items.value = newItems;
 		resetItemState(internalArrayStore.children[config.at], config.initialInput);
 		internalArrayStore.isTouched.value = true;
+		internalArrayStore.isEdited.value = true;
 		internalArrayStore.isDirty.value = true;
 		validateIfRequired(internalFormStore, internalArrayStore, "input");
 	});
@@ -838,6 +847,7 @@ function reset(form, config) {
 				internalFieldStore$1.elements = internalFieldStore$1.initialElements;
 				if (!config?.keepErrors) internalFieldStore$1.errors.value = null;
 				if (!config?.keepTouched) internalFieldStore$1.isTouched.value = false;
+				if (!config?.keepEdited) internalFieldStore$1.isEdited.value = false;
 				internalFieldStore$1.startInput.value = internalFieldStore$1.initialInput.value;
 				if (!config?.keepInput) internalFieldStore$1.input.value = internalFieldStore$1.initialInput.value;
 				if (internalFieldStore$1.kind === "array") {
@@ -896,6 +906,7 @@ function swap(form, config) {
 		internalArrayStore.items.value = newItems;
 		swapItemState(internalArrayStore.children[config.at], internalArrayStore.children[config.and]);
 		internalArrayStore.isTouched.value = true;
+		internalArrayStore.isEdited.value = true;
 		internalArrayStore.isDirty.value = internalArrayStore.startItems.value.join() !== newItems.join();
 		validateIfRequired(internalFormStore, internalArrayStore, "input");
 	});
@@ -964,6 +975,7 @@ function useField(form, config) {
 		input: computed(() => getFieldInput(internalFieldStore.value)),
 		errors: computed(() => internalFieldStore.value.errors.value),
 		isTouched: computed(() => getFieldBool(internalFieldStore.value, "isTouched")),
+		isEdited: computed(() => getFieldBool(internalFieldStore.value, "isEdited")),
 		isDirty: computed(() => getFieldBool(internalFieldStore.value, "isDirty")),
 		isValid: computed(() => !getFieldBool(internalFieldStore.value, "errors")),
 		onInput(value) {
@@ -1007,6 +1019,7 @@ function useFieldArray(form, config) {
 		items: computed(() => internalFieldStore.value.items.value),
 		errors: computed(() => internalFieldStore.value.errors.value),
 		isTouched: computed(() => getFieldBool(internalFieldStore.value, "isTouched")),
+		isEdited: computed(() => getFieldBool(internalFieldStore.value, "isEdited")),
 		isDirty: computed(() => getFieldBool(internalFieldStore.value, "isDirty")),
 		isValid: computed(() => !getFieldBool(internalFieldStore.value, "errors"))
 	}), []);
@@ -1024,6 +1037,7 @@ function useForm(config) {
 			isSubmitted: internalFormStore.isSubmitted,
 			isValidating: internalFormStore.isValidating,
 			isTouched: computed(() => getFieldBool(internalFormStore, "isTouched")),
+			isEdited: computed(() => getFieldBool(internalFormStore, "isEdited")),
 			isDirty: computed(() => getFieldBool(internalFormStore, "isDirty")),
 			isValid: computed(() => !getFieldBool(internalFormStore, "errors")),
 			errors: internalFormStore.errors
@@ -1083,4 +1097,4 @@ function Form({ of, onSubmit, ...other }) {
 }
 
 //#endregion
-export { Field, FieldArray, Form, focus, getAllErrors, getDirtyInput, getDirtyPaths, getErrors, getInput, handleSubmit, insert, move, pickDirty, remove, replace, reset, setErrors, setInput, submit, swap, useField, useFieldArray, useForm, validate };
+export { Field, FieldArray, Form, focus, getDeepErrorEntries, getDeepErrors, getDirtyInput, getDirtyPaths, getErrors, getInput, handleSubmit, insert, isDirty, isEdited, isTouched, isValid, move, pickDirty, remove, replace, reset, setErrors, setInput, submit, swap, useField, useFieldArray, useForm, validate };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@formisch/preact",
   "description": "The lightweight, schema-first, and fully type-safe form library for Preact",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "license": "MIT",
   "author": "Fabian Hiller",
   "homepage": "https://formisch.dev",