@angular/forms 21.1.0-next.1 → 21.1.0-next.3

package/types/_structure-chunk.d.ts

@@ -1,11 +1,11 @@
 /**
- * @license Angular v21.1.0-next.1
+ * @license Angular v21.1.0-next.3
  * (c) 2010-2025 Google LLC. https://angular.dev/
  * License: MIT
  */
 
 import * as i0 from '@angular/core';
-import { InjectionToken, ɵControl as _Control, ɵCONTROL as _CONTROL, ɵɵcontrolCreate as __controlCreate, ɵcontrolUpdate as _controlUpdate, ɵInteropControl as _InteropControl, ɵFieldState as _FieldState, Signal, Provider, WritableSignal, DestroyableInjector, Injector } from '@angular/core';
+import { InjectionToken, Injector, ɵCONTROL as _CONTROL, ɵɵcontrolCreate as __controlCreate, ɵcontrolUpdate as _controlUpdate, Signal, ɵFieldState as _FieldState, Provider, WritableSignal, DestroyableInjector } from '@angular/core';
 import * as _angular_forms from '@angular/forms';
 import { NgControl, AbstractControl, ValidationErrors, FormControlStatus, ControlValueAccessor, ValidatorFn } from '@angular/forms';
 import { StandardSchemaV1 } from '@standard-schema/spec';
@@ -68,1007 +68,1044 @@ declare const FIELD: InjectionToken<Field<unknown>>;
  * @category control
  * @experimental 21.0.0
  */
-declare class Field<T> implements _Control<T> {
-    private readonly injector;
-    private config;
-    readonly classes: (readonly [string, i0.Signal<boolean>])[];
+declare class Field<T> {
+    readonly element: HTMLElement;
+    readonly injector: Injector;
     readonly field: i0.InputSignal<FieldTree<T>>;
     readonly state: i0.Signal<[T] extends [_angular_forms.AbstractControl<any, any, any>] ? CompatFieldState<T, string | number> : FieldState<T, string | number>>;
     readonly [_CONTROL]: {
         readonly create: typeof __controlCreate;
         readonly update: typeof _controlUpdate;
     };
+    private config;
     /** Any `ControlValueAccessor` instances provided on the host element. */
     private readonly controlValueAccessors;
     /** A lazily instantiated fake `NgControl`. */
     private interopNgControl;
-    /** A `ControlValueAccessor`, if configured, for the host component. */
-    get ɵinteropControl(): _InteropControl | undefined;
     /** Lazily instantiates a fake `NgControl` for this field. */
     protected getOrCreateNgControl(): InteropNgControl;
-    ɵregister(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<Field<any>, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<Field<any>, "[field]", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 /**
- * Represents metadata that may be defined on a field when it is created using a `metadata` rule
- * in the schema. A particular `MetadataKey` can only be defined on a particular field **once**.
+ * Sets a value for the {@link MetadataKey} for this field.
+ *
+ * This value is combined via a reduce operation defined by the particular key,
+ * since multiple rules in the schema might set values for it.
+ *
+ * @param path The target path to set the metadata for.
+ * @param key The metadata key
+ * @param logic A function that receives the `FieldContext` and returns a value for the metadata.
+ * @template TValue The type of value stored in the field the logic is bound to.
+ * @template TKey The type of metadata key.
+ * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array)
  *
  * @category logic
  * @experimental 21.0.0
  */
-declare class MetadataKey<TValue> {
-    private brand;
-    /** Use {@link createMetadataKey}. */
-    private constructor();
-}
+declare function metadata<TValue, TKey extends MetadataKey<any, any, any>, TPathKind extends PathKind = PathKind.Root>(path: SchemaPath<TValue, SchemaPathRules.Supported, TPathKind>, key: TKey, logic: NoInfer<LogicFn<TValue, MetadataSetterType<TKey>, TPathKind>>): TKey;
 /**
- * Creates a {@link MetadataKey}.
+ * A reducer that determines the accumulated value for a metadata key by reducing the individual
+ * values contributed from `metadata()` rules.
  *
- * @experimental 21.0.0
+ * @template TAcc The accumulated type of the reduce operation.
+ * @template TItem The type of the individual items that are reduced over.
+ * @experimental 21.0.2
  */
-declare function createMetadataKey<TValue>(): MetadataKey<TValue>;
+interface MetadataReducer<TAcc, TItem> {
+    /** The reduce function. */
+    reduce: (acc: TAcc, item: TItem) => TAcc;
+    /** Gets the initial accumulated value. */
+    getInitial: () => TAcc;
+}
+declare const MetadataReducer: {
+    /** Creates a reducer that accumulates a list of its individual item values. */
+    readonly list: <TItem>() => MetadataReducer<TItem[], TItem | undefined>;
+    /** Creates a reducer that accumulates the min of its individual item values. */
+    readonly min: () => MetadataReducer<number | undefined, number | undefined>;
+    /** Creates a reducer that accumulates a the max of its individual item values. */
+    readonly max: () => MetadataReducer<number | undefined, number | undefined>;
+    /** Creates a reducer that logically or's its accumulated value with each individual item value. */
+    readonly or: () => MetadataReducer<boolean, boolean>;
+    /** Creates a reducer that logically and's its accumulated value with each individual item value. */
+    readonly and: () => MetadataReducer<boolean, boolean>;
+    /** Creates a reducer that always takes the next individual item value as the accumulated value. */
+    readonly override: typeof override;
+};
+declare function override<T>(): MetadataReducer<T | undefined, T>;
+declare function override<T>(getInitial: () => T): MetadataReducer<T, T>;
 /**
  * Represents metadata that is aggregated from multiple parts according to the key's reducer
  * function. A value can be contributed to the aggregated value for a field using an
- * `aggregateMetadata` rule in the schema. There may be multiple rules in a schema that contribute
- * values to the same `AggregateMetadataKey` of the same field.
+ * `metadata` rule in the schema. There may be multiple rules in a schema that contribute
+ * values to the same `MetadataKey` of the same field.
+ *
+ * @template TRead The type read from the `FieldState` for this key
+ * @template TWrite The type written to this key using the `metadata()` rule
+ * @template TAcc The type of the reducer's accumulated value.
  *
  * @experimental 21.0.0
  */
-declare class AggregateMetadataKey<TAcc, TItem> {
-    readonly reduce: (acc: TAcc, item: TItem) => TAcc;
-    readonly getInitial: () => TAcc;
+declare class MetadataKey<TRead, TWrite, TAcc> {
+    readonly reducer: MetadataReducer<TAcc, TWrite>;
+    readonly create: ((s: Signal<TAcc>) => TRead) | undefined;
     private brand;
     /** Use {@link reducedMetadataKey}. */
-    private constructor();
+    protected constructor(reducer: MetadataReducer<TAcc, TWrite>, create: ((s: Signal<TAcc>) => TRead) | undefined);
 }
 /**
- * Creates an {@link AggregateMetadataKey} that reduces its individual values into an accumulated
- * value using the given `reduce` and `getInitial` functions.
- * @param reduce The reducer function.
- * @param getInitial A function that gets the initial value for the reduce operation.
+ * Extracts the the type that can be set into the given metadata key type using the `metadata()` rule.
  *
- * @experimental 21.0.0
- */
-declare function reducedMetadataKey<TAcc, TItem>(reduce: (acc: TAcc, item: TItem) => TAcc, getInitial: NoInfer<() => TAcc>): AggregateMetadataKey<TAcc, TItem>;
-/**
- * Creates an {@link AggregateMetadataKey} that reduces its individual values into a list.
+ * @template TKey The `MetadataKey` type
  *
  * @experimental 21.0.0
  */
-declare function listMetadataKey<TItem>(): AggregateMetadataKey<TItem[], TItem | undefined>;
+type MetadataSetterType<TKey> = TKey extends MetadataKey<any, infer TWrite, any> ? TWrite : never;
 /**
- * Creates {@link AggregateMetadataKey} that reduces its individual values by taking their min.
+ * Creates a metadata key used to contain a computed value.
+ * The last value set on a given field tree node overrides any previously set values.
+ *
+ * @template TWrite The type written to this key using the `metadata()` rule
  *
  * @experimental 21.0.0
  */
-declare function minMetadataKey(): AggregateMetadataKey<number | undefined, number | undefined>;
+declare function createMetadataKey<TWrite>(): MetadataKey<Signal<TWrite | undefined>, TWrite, TWrite | undefined>;
 /**
- * Creates {@link AggregateMetadataKey} that reduces its individual values by taking their max.
+ * Creates a metadata key used to contain a computed value.
+ *
+ * @param reducer The reducer used to combine individually set values into the final computed value.
+ * @template TWrite The type written to this key using the `metadata()` rule
+ * @template TAcc The type of the reducer's accumulated value.
  *
  * @experimental 21.0.0
  */
-declare function maxMetadataKey(): AggregateMetadataKey<number | undefined, number | undefined>;
+declare function createMetadataKey<TWrite, TAcc>(reducer: MetadataReducer<TAcc, TWrite>): MetadataKey<Signal<TAcc>, TWrite, TAcc>;
 /**
- * Creates an {@link AggregateMetadataKey} that reduces its individual values by logically or-ing
- * them.
+ * Creates a metadata key that exposes a managed value based on the accumulated result of the values
+ * written to the key. The accumulated value takes the last value set on a given field tree node,
+ * overriding any previously set values.
+ *
+ * @param create A function that receives a signal of the accumulated value and returns the managed
+ *   value based on it. This function runs during the construction of the `FieldTree` node,
+ *   and runs in the injection context of that node.
+ * @template TRead The type read from the `FieldState` for this key
+ * @template TWrite The type written to this key using the `metadata()` rule
  *
  * @experimental 21.0.0
  */
-declare function orMetadataKey(): AggregateMetadataKey<boolean, boolean>;
+declare function createManagedMetadataKey<TRead, TWrite>(create: (s: Signal<TWrite | undefined>) => TRead): MetadataKey<TRead, TWrite, TWrite | undefined>;
 /**
- * Creates an {@link AggregateMetadataKey} that reduces its individual values by logically and-ing
- * them.
+ * Creates a metadata key that exposes a managed value based on the accumulated result of the values
+ * written to the key.
+ *
+ * @param create A function that receives a signal of the accumulated value and returns the managed
+ *   value based on it. This function runs during the construction of the `FieldTree` node,
+ *   and runs in the injection context of that node.
+ * @param reducer The reducer used to combine individual value written to the key,
+ *   this will determine the accumulated value that the create function receives.
+ * @template TRead The type read from the `FieldState` for this key
+ * @template TWrite The type written to this key using the `metadata()` rule
+ * @template TAcc The type of the reducer's accumulated value.
  *
  * @experimental 21.0.0
  */
-declare function andMetadataKey(): AggregateMetadataKey<boolean, boolean>;
+declare function createManagedMetadataKey<TRead, TWrite, TAcc>(create: (s: Signal<TAcc>) => TRead, reducer: MetadataReducer<TAcc, TWrite>): MetadataKey<TRead, TWrite, TAcc>;
 /**
- * An {@link AggregateMetadataKey} representing whether the field is required.
+ * A {@link MetadataKey} representing whether the field is required.
  *
  * @category validation
  * @experimental 21.0.0
  */
-declare const REQUIRED: AggregateMetadataKey<boolean, boolean>;
+declare const REQUIRED: MetadataKey<Signal<boolean>, boolean, boolean>;
 /**
- * An {@link AggregateMetadataKey} representing the min value of the field.
+ * A {@link MetadataKey} representing the min value of the field.
  *
  * @category validation
  * @experimental 21.0.0
  */
-declare const MIN: AggregateMetadataKey<number | undefined, number | undefined>;
+declare const MIN: MetadataKey<Signal<number | undefined>, number | undefined, number | undefined>;
 /**
- * An {@link AggregateMetadataKey} representing the max value of the field.
+ * A {@link MetadataKey} representing the max value of the field.
  *
  * @category validation
  * @experimental 21.0.0
  */
-declare const MAX: AggregateMetadataKey<number | undefined, number | undefined>;
+declare const MAX: MetadataKey<Signal<number | undefined>, number | undefined, number | undefined>;
 /**
- * An {@link AggregateMetadataKey} representing the min length of the field.
+ * A {@link MetadataKey} representing the min length of the field.
  *
  * @category validation
  * @experimental 21.0.0
  */
-declare const MIN_LENGTH: AggregateMetadataKey<number | undefined, number | undefined>;
+declare const MIN_LENGTH: MetadataKey<Signal<number | undefined>, number | undefined, number | undefined>;
 /**
- * An {@link AggregateMetadataKey} representing the max length of the field.
+ * A {@link MetadataKey} representing the max length of the field.
  *
  * @category validation
  * @experimental 21.0.0
  */
-declare const MAX_LENGTH: AggregateMetadataKey<number | undefined, number | undefined>;
+declare const MAX_LENGTH: MetadataKey<Signal<number | undefined>, number | undefined, number | undefined>;
 /**
- * An {@link AggregateMetadataKey} representing the patterns the field must match.
+ * A {@link MetadataKey} representing the patterns the field must match.
  *
  * @category validation
  * @experimental 21.0.0
  */
-declare const PATTERN: AggregateMetadataKey<RegExp[], RegExp | undefined>;
+declare const PATTERN: MetadataKey<Signal<RegExp[]>, RegExp | undefined, RegExp[]>;
 
 /**
- * Options used to create a `ValidationError`.
+ * Symbol used to retain generic type information when it would otherwise be lost.
  */
-interface ValidationErrorOptions {
-    /** Human readable error message. */
-    message?: string;
-}
+declare const ɵɵTYPE: unique symbol;
 /**
- * A type that requires the given type `T` to have a `field` property.
- * @template T The type to add a `field` to.
+ * A type that represents either a single value of type `T` or a readonly array of `T`.
+ * @template T The type of the value(s).
  *
  * @experimental 21.0.0
  */
-type WithField<T> = T & {
-    field: FieldTree<unknown>;
-};
+type OneOrMany<T> = T | readonly T[];
 /**
- * A type that allows the given type `T` to optionally have a `field` property.
- * @template T The type to optionally add a `field` to.
+ * The kind of `FieldPath` (`Root`, `Child` of another `FieldPath`, or `Item` in a `FieldPath` array)
  *
  * @experimental 21.0.0
  */
-type WithOptionalField<T> = Omit<T, 'field'> & {
-    field?: FieldTree<unknown>;
-};
+type PathKind = PathKind.Root | PathKind.Child | PathKind.Item;
+declare namespace PathKind {
+    /**
+     * The `PathKind` for a `FieldPath` that is at the root of its field tree.
+     */
+    interface Root {
+        /**
+         * The `ɵɵTYPE` is constructed to allow the `extends` clause on `Child` and `Item` to narrow the
+         * type. Another way to think about this is, if we have a function that expects this kind of
+         * path, the `ɵɵTYPE` lists the kinds of path we are allowed to pass to it.
+         */
+        [ɵɵTYPE]: 'root' | 'child' | 'item';
+    }
+    /**
+     * The `PathKind` for a `FieldPath` that is a child of another `FieldPath`.
+     */
+    interface Child extends PathKind.Root {
+        [ɵɵTYPE]: 'child' | 'item';
+    }
+    /**
+     * The `PathKind` for a `FieldPath` that is an item in a `FieldPath` array.
+     */
+    interface Item extends PathKind.Child {
+        [ɵɵTYPE]: 'item';
+    }
+}
 /**
- * A type that ensures the given type `T` does not have a `field` property.
- * @template T The type to remove the `field` from.
+ * A status indicating whether a field is unsubmitted, submitted, or currently submitting.
  *
+ * @category types
  * @experimental 21.0.0
  */
-type WithoutField<T> = T & {
-    field: never;
-};
+type SubmittedStatus = 'unsubmitted' | 'submitted' | 'submitting';
 /**
- * Create a required error associated with the target field
- * @param options The validation error options
+ * A reason for a field's disablement.
  *
+ * @category logic
  * @experimental 21.0.0
  */
-declare function requiredError(options: WithField<ValidationErrorOptions>): RequiredValidationError;
+interface DisabledReason {
+    /** The field that is disabled. */
+    readonly field: FieldTree<unknown>;
+    /** A user-facing message describing the reason for the disablement. */
+    readonly message?: string;
+}
 /**
- * Create a required error
- * @param options The optional validation error options
+ * The absence of an error which indicates a successful validation result.
  *
- * @category validation
+ * @category types
  * @experimental 21.0.0
  */
-declare function requiredError(options?: ValidationErrorOptions): WithoutField<RequiredValidationError>;
+type ValidationSuccess = null | undefined | void;
 /**
- * Create a min value error associated with the target field
- * @param min The min value constraint
- * @param options The validation error options
+ * The result of running a tree validation function.
  *
- * @category validation
- * @experimental 21.0.0
- */
-declare function minError(min: number, options: WithField<ValidationErrorOptions>): MinValidationError;
-/**
- * Create a min value error
- * @param min The min value constraint
- * @param options The optional validation error options
+ * The result may be one of the following:
+ * 1. A {@link ValidationSuccess} to indicate no errors.
+ * 2. A {@link ValidationError} without a field to indicate an error on the field being validated.
+ * 3. A {@link ValidationError} with a field to indicate an error on the target field.
+ * 4. A list of {@link ValidationError} with or without fields to indicate multiple errors.
  *
- * @category validation
- * @experimental 21.0.0
- */
-declare function minError(min: number, options?: ValidationErrorOptions): WithoutField<MinValidationError>;
-/**
- * Create a max value error associated with the target field
- * @param max The max value constraint
- * @param options The validation error options
+ * @template E the type of error (defaults to {@link ValidationError}).
  *
- * @category validation
+ * @category types
  * @experimental 21.0.0
  */
-declare function maxError(max: number, options: WithField<ValidationErrorOptions>): MaxValidationError;
+type TreeValidationResult<E extends ValidationError.WithOptionalField = ValidationError.WithOptionalField> = ValidationSuccess | OneOrMany<E>;
 /**
- * Create a max value error
- * @param max The max value constraint
- * @param options The optional validation error options
+ * A validation result where all errors explicitly define their target field.
  *
- * @category validation
- * @experimental 21.0.0
- */
-declare function maxError(max: number, options?: ValidationErrorOptions): WithoutField<MaxValidationError>;
-/**
- * Create a minLength error associated with the target field
- * @param minLength The minLength constraint
- * @param options The validation error options
+ * The result may be one of the following:
+ * 1. A {@link ValidationSuccess} to indicate no errors.
+ * 2. A {@link ValidationError} with a field to indicate an error on the target field.
+ * 3. A list of {@link ValidationError} with fields to indicate multiple errors.
  *
- * @category validation
- * @experimental 21.0.0
- */
-declare function minLengthError(minLength: number, options: WithField<ValidationErrorOptions>): MinLengthValidationError;
-/**
- * Create a minLength error
- * @param minLength The minLength constraint
- * @param options The optional validation error options
+ * @template E the type of error (defaults to {@link ValidationError}).
  *
- * @category validation
+ * @category types
  * @experimental 21.0.0
  */
-declare function minLengthError(minLength: number, options?: ValidationErrorOptions): WithoutField<MinLengthValidationError>;
+type ValidationResult<E extends ValidationError = ValidationError> = ValidationSuccess | OneOrMany<E>;
 /**
- * Create a maxLength error associated with the target field
- * @param maxLength The maxLength constraint
- * @param options The validation error options
+ * An asynchronous validation result where all errors explicitly define their target field.
  *
- * @category validation
- * @experimental 21.0.0
- */
-declare function maxLengthError(maxLength: number, options: WithField<ValidationErrorOptions>): MaxLengthValidationError;
-/**
- * Create a maxLength error
- * @param maxLength The maxLength constraint
- * @param options The optional validation error options
+ * The result may be one of the following:
+ * 1. A {@link ValidationResult} to indicate the result if resolved.
+ * 5. 'pending' if the validation is not yet resolved.
  *
- * @category validation
- * @experimental 21.0.0
- */
-declare function maxLengthError(maxLength: number, options?: ValidationErrorOptions): WithoutField<MaxLengthValidationError>;
-/**
- * Create a pattern matching error associated with the target field
- * @param pattern The violated pattern
- * @param options The validation error options
+ * @template E the type of error (defaults to {@link ValidationError}).
  *
- * @category validation
+ * @category types
  * @experimental 21.0.0
  */
-declare function patternError(pattern: RegExp, options: WithField<ValidationErrorOptions>): PatternValidationError;
+type AsyncValidationResult<E extends ValidationError = ValidationError> = ValidationResult<E> | 'pending';
 /**
- * Create a pattern matching error
- * @param pattern The violated pattern
- * @param options The optional validation error options
+ * An object that represents a tree of fields in a form. This includes both primitive value fields
+ * (e.g. fields that contain a `string` or `number`), as well as "grouping fields" that contain
+ * sub-fields. `FieldTree` objects are arranged in a tree whose structure mimics the structure of the
+ * underlying data. For example a `FieldTree<{x: number}>` has a property `x` which contains a
+ * `FieldTree<number>`. To access the state associated with a field, call it as a function.
  *
- * @category validation
- * @experimental 21.0.0
- */
-declare function patternError(pattern: RegExp, options?: ValidationErrorOptions): WithoutField<PatternValidationError>;
-/**
- * Create an email format error associated with the target field
- * @param options The validation error options
+ * @template TValue The type of the data which the field is wrapped around.
+ * @template TKey The type of the property key which this field resides under in its parent.
  *
- * @category validation
+ * @category types
  * @experimental 21.0.0
  */
-declare function emailError(options: WithField<ValidationErrorOptions>): EmailValidationError;
+type FieldTree<TModel, TKey extends string | number = string | number> = (() => [TModel] extends [AbstractControl] ? CompatFieldState<TModel, TKey> : FieldState<TModel, TKey>) & ([TModel] extends [AbstractControl] ? object : [TModel] extends [Array<infer U>] ? ReadonlyArrayLike<MaybeFieldTree<U, number>> : TModel extends Record<string, any> ? Subfields<TModel> : object);
 /**
- * Create an email format error
- * @param options The optional validation error options
+ * The sub-fields that a user can navigate to from a `FieldTree<TModel>`.
  *
- * @category validation
- * @experimental 21.0.0
- */
-declare function emailError(options?: ValidationErrorOptions): WithoutField<EmailValidationError>;
-/**
- * Create a standard schema issue error associated with the target field
- * @param issue The standard schema issue
- * @param options The validation error options
+ * @template TModel The type of the data which the parent field is wrapped around.
  *
- * @category validation
  * @experimental 21.0.0
  */
-declare function standardSchemaError(issue: StandardSchemaV1.Issue, options: WithField<ValidationErrorOptions>): StandardSchemaValidationError;
+type Subfields<TModel> = {
+    readonly [K in keyof TModel as TModel[K] extends Function ? never : K]: MaybeFieldTree<TModel[K], string>;
+} & {
+    [Symbol.iterator](): Iterator<[string, MaybeFieldTree<TModel[keyof TModel], string>]>;
+};
 /**
- * Create a standard schema issue error
- * @param issue The standard schema issue
- * @param options The optional validation error options
+ * An iterable object with the same shape as a readonly array.
  *
- * @category validation
- * @experimental 21.0.0
- */
-declare function standardSchemaError(issue: StandardSchemaV1.Issue, options?: ValidationErrorOptions): WithoutField<StandardSchemaValidationError>;
-/**
- * Create a custom error associated with the target field
- * @param obj The object to create an error from
+ * @template T The array item type.
  *
- * @category validation
  * @experimental 21.0.0
  */
-declare function customError<E extends Partial<ValidationError.WithField>>(obj: WithField<E>): CustomValidationError;
+type ReadonlyArrayLike<T> = Pick<ReadonlyArray<T>, number | 'length' | typeof Symbol.iterator>;
 /**
- * Create a custom error
- * @param obj The object to create an error from
+ * Helper type for defining `FieldTree`. Given a type `TValue` that may include `undefined`, it extracts
+ * the `undefined` outside the `FieldTree` type.
+ *
+ * For example `MaybeField<{a: number} | undefined, TKey>` would be equivalent to
+ * `undefined | FieldTree<{a: number}, TKey>`.
+ *
+ * @template TModel The type of the data which the field is wrapped around.
+ * @template TKey The type of the property key which this field resides under in its parent.
  *
- * @category validation
  * @experimental 21.0.0
  */
-declare function customError<E extends Partial<ValidationError.WithField>>(obj?: E): WithoutField<CustomValidationError>;
+type MaybeFieldTree<TModel, TKey extends string | number = string | number> = (TModel & undefined) | FieldTree<Exclude<TModel, undefined>, TKey>;
 /**
- * Common interface for all validation errors.
- *
- * This can be returned from validators.
- *
- * It's also used by the creation functions to create an instance
- * (e.g. `requiredError`, `minError`, etc.).
+ * Contains all of the state (e.g. value, statuses, etc.) associated with a `FieldTree`, exposed as
+ * signals.
  *
- * @category validation
+ * @category structure
  * @experimental 21.0.0
  */
-interface ValidationError {
-    /** Identifies the kind of error. */
-    readonly kind: string;
-    /** Human readable error message. */
-    readonly message?: string;
-}
-declare namespace ValidationError {
+interface FieldState<TValue, TKey extends string | number = string | number> extends _FieldState<TValue> {
     /**
-     * Validation error with a field.
+     * A signal indicating whether field value has been changed by user.
+     */
+    readonly dirty: Signal<boolean>;
+    /**
+     * A signal indicating whether a field is hidden.
      *
-     * This is returned from field state, e.g., catField.errors() would be of a list of errors with
-     * `field: catField` bound to state.
+     * When a field is hidden it is ignored when determining the valid, touched, and dirty states.
+     *
+     * Note: This doesn't hide the field in the template, that must be done manually.
+     * ```
+     * @if (!field.hidden()) {
+     *   ...
+     * }
+     * ```
      */
-    interface WithField extends ValidationError {
-        /** The field associated with this error. */
-        readonly field: FieldTree<unknown>;
-    }
+    readonly hidden: Signal<boolean>;
+    readonly disabledReasons: Signal<readonly DisabledReason[]>;
+    readonly errors: Signal<ValidationError.WithField[]>;
     /**
-     * Validation error with optional field.
+     * A signal containing the {@link errors} of the field and its descendants.
+     */
+    readonly errorSummary: Signal<ValidationError.WithField[]>;
+    /**
+     * A signal indicating whether the field's value is currently valid.
      *
-     * This is generally used in places where the result might have a field.
-     * e.g., as a result of a `validateTree`, or when handling form submission.
+     * Note: `valid()` is not the same as `!invalid()`.
+     * - `valid()` is `true` when there are no validation errors *and* no pending validators.
+     * - `invalid()` is `true` when there are validation errors, regardless of pending validators.
+     *
+     * Ex: consider the situation where a field has 3 validators, 2 of which have no errors and 1 of
+     * which is still pending. In this case `valid()` is `false` because of the pending validator.
+     * However `invalid()` is also `false` because there are no errors.
      */
-    interface WithOptionalField extends ValidationError {
-        /** The field associated with this error. */
-        readonly field?: FieldTree<unknown>;
-    }
+    readonly valid: Signal<boolean>;
     /**
-     * Validation error with no field.
+     * A signal indicating whether the field's value is currently invalid.
      *
-     * This is used to strongly enforce that fields are not allowed in validation result.
+     * Note: `invalid()` is not the same as `!valid()`.
+     * - `invalid()` is `true` when there are validation errors, regardless of pending validators.
+     * - `valid()` is `true` when there are no validation errors *and* no pending validators.
+     *
+     * Ex: consider the situation where a field has 3 validators, 2 of which have no errors and 1 of
+     * which is still pending. In this case `invalid()` is `false` because there are no errors.
+     * However `valid()` is also `false` because of the pending validator.
      */
-    interface WithoutField extends ValidationError {
-        /** The field associated with this error. */
-        readonly field?: never;
-    }
+    readonly invalid: Signal<boolean>;
+    /**
+     * Whether there are any validators still pending for this field.
+     */
+    readonly pending: Signal<boolean>;
+    /**
+     * A signal indicating whether the field is currently in the process of being submitted.
+     */
+    readonly submitting: Signal<boolean>;
+    /**
+     * The property key in the parent field under which this field is stored. If the parent field is
+     * array-valued, for example, this is the index of this field in that array.
+     */
+    readonly keyInParent: Signal<TKey>;
+    /**
+     * The {@link Field} directives that bind this field to a UI control.
+     */
+    readonly fieldBindings: Signal<readonly Field<unknown>[]>;
+    /**
+     * Reads a metadata value from the field.
+     * @param key The metadata key to read.
+     */
+    metadata<M>(key: MetadataKey<M, any, any>): M | undefined;
+    /**
+     * Resets the {@link touched} and {@link dirty} state of the field and its descendants.
+     *
+     * Note this does not change the data model, which can be reset directly if desired.
+     *
+     * @param value Optional value to set to the form. If not passed, the value will not be changed.
+     */
+    reset(value?: TValue): void;
 }
 /**
- * A custom error that may contain additional properties
+ * This is FieldState also providing access to the wrapped FormControl.
  *
- * @category validation
+ * @category interop
  * @experimental 21.0.0
  */
-declare class CustomValidationError implements ValidationError {
-    /** Brand the class to avoid Typescript structural matching */
-    private __brand;
+type CompatFieldState<TControl extends AbstractControl, TKey extends string | number = string | number> = FieldState<TControl extends AbstractControl<unknown, infer TValue> ? TValue : never, TKey> & {
+    control: Signal<TControl>;
+};
+/**
+ * Allows declaring whether the Rules are supported for a given path.
+ *
+ * @experimental 21.0.0
+ **/
+type SchemaPathRules = SchemaPathRules.Supported | SchemaPathRules.Unsupported;
+declare namespace SchemaPathRules {
     /**
-     * Allow the user to attach arbitrary other properties.
+     * Used for paths that support settings rules.
      */
-    [key: PropertyKey]: unknown;
-    /** Identifies the kind of error. */
-    readonly kind: string;
-    /** The field associated with this error. */
-    readonly field: FieldTree<unknown>;
-    /** Human readable error message. */
-    readonly message?: string;
-    constructor(options?: ValidationErrorOptions);
+    type Supported = 1;
+    /**
+     * Used for paths that do not support settings rules, e.g., compatPath.
+     */
+    type Unsupported = 2;
 }
 /**
- * Internal version of `NgValidationError`, we create this separately so we can change its type on
- * the exported version to a type union of the possible sub-classes.
+ * An object that represents a location in the `FieldTree` tree structure and is used to bind logic to a
+ * particular part of the structure prior to the creation of the form. Because the `FieldPath`
+ * exists prior to the form's creation, it cannot be used to access any of the field state.
  *
+ * @template TValue The type of the data which the form is wrapped around.
+ * @template TPathKind The kind of path (root field, child field, or item of an array)
+ *
+ * @category types
  * @experimental 21.0.0
  */
-declare abstract class _NgValidationError implements ValidationError {
-    /** Brand the class to avoid Typescript structural matching */
-    private __brand;
-    /** Identifies the kind of error. */
-    readonly kind: string;
-    /** The field associated with this error. */
-    readonly field: FieldTree<unknown>;
-    /** Human readable error message. */
-    readonly message?: string;
-    constructor(options?: ValidationErrorOptions);
-}
+type SchemaPath<TValue, TSupportsRules extends SchemaPathRules = SchemaPathRules.Supported, TPathKind extends PathKind = PathKind.Root> = {
+    [ɵɵTYPE]: {
+        value: () => TValue;
+        supportsRules: TSupportsRules;
+        pathKind: TPathKind;
+    };
+};
 /**
- * An error used to indicate that a required field is empty.
+ * Schema path used if the value is an AbstractControl.
  *
- * @category validation
+ * @category interop
  * @experimental 21.0.0
  */
-declare class RequiredValidationError extends _NgValidationError {
-    readonly kind = "required";
-}
+type CompatSchemaPath<TControl extends AbstractControl, TPathKind extends PathKind = PathKind.Root> = SchemaPath<TControl extends AbstractControl<unknown, infer TValue> ? TValue : never, SchemaPathRules.Unsupported, TPathKind> & {
+    [ɵɵTYPE]: {
+        control: TControl;
+    };
+};
 /**
- * An error used to indicate that a value is lower than the minimum allowed.
+ * Nested schema path.
+ *
+ * It mirrors the structure of a given data structure, and allows applying rules to the appropriate
+ * fields.
  *
- * @category validation
  * @experimental 21.0.0
  */
-declare class MinValidationError extends _NgValidationError {
-    readonly min: number;
-    readonly kind = "min";
-    constructor(min: number, options?: ValidationErrorOptions);
-}
+type SchemaPathTree<TModel, TPathKind extends PathKind = PathKind.Root> = ([TModel] extends [AbstractControl] ? CompatSchemaPath<TModel, TPathKind> : SchemaPath<TModel, SchemaPathRules.Supported, TPathKind>) & (TModel extends AbstractControl ? unknown : TModel extends Array<any> ? unknown : TModel extends Record<string, any> ? {
+    [K in keyof TModel]: MaybeSchemaPathTree<TModel[K], PathKind.Child>;
+} : unknown);
 /**
- * An error used to indicate that a value is higher than the maximum allowed.
+ * Helper type for defining `FieldPath`. Given a type `TValue` that may include `undefined`, it
+ * extracts the `undefined` outside the `FieldPath` type.
+ *
+ * For example `MaybeFieldPath<{a: number} | undefined, PathKind.Child>` would be equivalent to
+ * `undefined | FieldTree<{a: number}, PathKind.child>`.
+ *
+ * @template TValue The type of the data which the field is wrapped around.
+ * @template TPathKind The kind of path (root field, child field, or item of an array)
  *
- * @category validation
  * @experimental 21.0.0
  */
-declare class MaxValidationError extends _NgValidationError {
-    readonly max: number;
-    readonly kind = "max";
-    constructor(max: number, options?: ValidationErrorOptions);
-}
+type MaybeSchemaPathTree<TModel, TPathKind extends PathKind = PathKind.Root> = (TModel & undefined) | SchemaPathTree<Exclude<TModel, undefined>, TPathKind>;
 /**
- * An error used to indicate that a value is shorter than the minimum allowed length.
+ * Defines logic for a form.
  *
- * @category validation
+ * @template TValue The type of data stored in the form that this schema is attached to.
+ *
+ * @category types
  * @experimental 21.0.0
  */
-declare class MinLengthValidationError extends _NgValidationError {
-    readonly minLength: number;
-    readonly kind = "minLength";
-    constructor(minLength: number, options?: ValidationErrorOptions);
-}
+type Schema<in TModel> = {
+    [ɵɵTYPE]: SchemaFn<TModel, PathKind.Root>;
+};
 /**
- * An error used to indicate that a value is longer than the maximum allowed length.
+ * Function that defines rules for a schema.
  *
- * @category validation
+ * @template TModel The type of data stored in the form that this schema function is attached to.
+ * @template TPathKind The kind of path this schema function can be bound to.
+ *
+ * @category types
  * @experimental 21.0.0
  */
-declare class MaxLengthValidationError extends _NgValidationError {
-    readonly maxLength: number;
-    readonly kind = "maxLength";
-    constructor(maxLength: number, options?: ValidationErrorOptions);
-}
+type SchemaFn<TModel, TPathKind extends PathKind = PathKind.Root> = (p: SchemaPathTree<TModel, TPathKind>) => void;
 /**
- * An error used to indicate that a value does not match the required pattern.
+ * A schema or schema definition function.
  *
- * @category validation
+ * @template TModel The type of data stored in the form that this schema function is attached to.
+ * @template TPathKind The kind of path this schema function can be bound to.
+ *
+ * @category types
  * @experimental 21.0.0
  */
-declare class PatternValidationError extends _NgValidationError {
-    readonly pattern: RegExp;
-    readonly kind = "pattern";
-    constructor(pattern: RegExp, options?: ValidationErrorOptions);
-}
+type SchemaOrSchemaFn<TModel, TPathKind extends PathKind = PathKind.Root> = Schema<TModel> | SchemaFn<TModel, TPathKind>;
 /**
- * An error used to indicate that a value is not a valid email.
+ * A function that receives the `FieldContext` for the field the logic is bound to and returns
+ * a specific result type.
  *
- * @category validation
+ * @template TValue The data type for the field the logic is bound to.
+ * @template TReturn The type of the result returned by the logic function.
+ * @template TPathKind The kind of path the logic is applied to (root field, child field, or item of an array)
+ *
+ * @category types
  * @experimental 21.0.0
  */
-declare class EmailValidationError extends _NgValidationError {
-    readonly kind = "email";
-}
+type LogicFn<TValue, TReturn, TPathKind extends PathKind = PathKind.Root> = (ctx: FieldContext<TValue, TPathKind>) => TReturn;
 /**
- * An error used to indicate an issue validating against a standard schema.
+ * A function that takes the `FieldContext` for the field being validated and returns a
+ * `ValidationResult` indicating errors for the field.
+ *
+ * @template TValue The type of value stored in the field being validated
+ * @template TPathKind The kind of path being validated (root field, child field, or item of an array)
  *
  * @category validation
  * @experimental 21.0.0
  */
-declare class StandardSchemaValidationError extends _NgValidationError {
-    readonly issue: StandardSchemaV1.Issue;
-    readonly kind = "standardSchema";
-    constructor(issue: StandardSchemaV1.Issue, options?: ValidationErrorOptions);
-}
+type FieldValidator<TValue, TPathKind extends PathKind = PathKind.Root> = LogicFn<TValue, ValidationResult<ValidationError.WithoutField>, TPathKind>;
 /**
- * The base class for all built-in, non-custom errors. This class can be used to check if an error
- * is one of the standard kinds, allowing you to switch on the kind to further narrow the type.
+ * A function that takes the `FieldContext` for the field being validated and returns a
+ * `TreeValidationResult` indicating errors for the field and its sub-fields.
  *
- * @example
- * ```ts
- * const f = form(...);
- * for (const e of form().errors()) {
- *   if (e instanceof NgValidationError) {
- *     switch(e.kind) {
- *       case 'required':
- *         console.log('This is required!');
- *         break;
- *       case 'min':
- *         console.log(`Must be at least ${e.min}`);
- *         break;
- *       ...
- *     }
- *   }
- * }
- * ```
+ * @template TValue The type of value stored in the field being validated
+ * @template TPathKind The kind of path being validated (root field, child field, or item of an array)
  *
- * @category validation
+ * @category types
  * @experimental 21.0.0
  */
-declare const NgValidationError: abstract new () => NgValidationError;
-type NgValidationError = RequiredValidationError | MinValidationError | MaxValidationError | MinLengthValidationError | MaxLengthValidationError | PatternValidationError | EmailValidationError | StandardSchemaValidationError;
-
+type TreeValidator<TValue, TPathKind extends PathKind = PathKind.Root> = LogicFn<TValue, TreeValidationResult, TPathKind>;
 /**
- * Symbol used to retain generic type information when it would otherwise be lost.
+ * A function that takes the `FieldContext` for the field being validated and returns a
+ * `ValidationResult` indicating errors for the field and its sub-fields. In a `Validator` all
+ * errors must explicitly define their target field.
+ *
+ * @template TValue The type of value stored in the field being validated
+ * @template TPathKind The kind of path being validated (root field, child field, or item of an array)
+ *
+ * @category types
+ * @experimental 21.0.0
  */
-declare const ɵɵTYPE: unique symbol;
+type Validator<TValue, TPathKind extends PathKind = PathKind.Root> = LogicFn<TValue, ValidationResult, TPathKind>;
 /**
- * A type that represents either a single value of type `T` or a readonly array of `T`.
- * @template T The type of the value(s).
+ * Provides access to the state of the current field as well as functions that can be used to look
+ * up state of other fields based on a `FieldPath`.
  *
+ * @category types
  * @experimental 21.0.0
  */
-type OneOrMany<T> = T | readonly T[];
+type FieldContext<TValue, TPathKind extends PathKind = PathKind.Root> = TPathKind extends PathKind.Item ? ItemFieldContext<TValue> : TPathKind extends PathKind.Child ? ChildFieldContext<TValue> : RootFieldContext<TValue>;
 /**
- * The kind of `FieldPath` (`Root`, `Child` of another `FieldPath`, or `Item` in a `FieldPath` array)
+ * The base field context that is available for all fields.
  *
  * @experimental 21.0.0
  */
-type PathKind = PathKind.Root | PathKind.Child | PathKind.Item;
-declare namespace PathKind {
-    /**
-     * The `PathKind` for a `FieldPath` that is at the root of its field tree.
-     */
-    interface Root {
-        /**
-         * The `ɵɵTYPE` is constructed to allow the `extends` clause on `Child` and `Item` to narrow the
-         * type. Another way to think about this is, if we have a function that expects this kind of
-         * path, the `ɵɵTYPE` lists the kinds of path we are allowed to pass to it.
-         */
-        [ɵɵTYPE]: 'root' | 'child' | 'item';
-    }
-    /**
-     * The `PathKind` for a `FieldPath` that is a child of another `FieldPath`.
-     */
-    interface Child extends PathKind.Root {
-        [ɵɵTYPE]: 'child' | 'item';
-    }
-    /**
-     * The `PathKind` for a `FieldPath` that is an item in a `FieldPath` array.
-     */
-    interface Item extends PathKind.Child {
-        [ɵɵTYPE]: 'item';
-    }
+interface RootFieldContext<TValue> {
+    /** A signal containing the value of the current field. */
+    readonly value: Signal<TValue>;
+    /** The state of the current field. */
+    readonly state: FieldState<TValue>;
+    /** The current field. */
+    readonly field: FieldTree<TValue>;
+    /** Gets the value of the field represented by the given path. */
+    valueOf<PValue>(p: SchemaPath<PValue, SchemaPathRules>): PValue;
+    /** Gets the state of the field represented by the given path. */
+    stateOf<PControl extends AbstractControl>(p: CompatSchemaPath<PControl>): CompatFieldState<PControl>;
+    stateOf<PValue>(p: SchemaPath<PValue, SchemaPathRules>): FieldState<PValue>;
+    /** Gets the field represented by the given path. */
+    fieldTreeOf<PModel>(p: SchemaPathTree<PModel>): FieldTree<PModel>;
+    /** The list of keys that lead from the root field to the current field. */
+    readonly pathKeys: Signal<readonly string[]>;
 }
 /**
- * A status indicating whether a field is unsubmitted, submitted, or currently submitting.
+ * Field context that is available for all fields that are a child of another field.
  *
- * @category types
+ * @category structure
  * @experimental 21.0.0
  */
-type SubmittedStatus = 'unsubmitted' | 'submitted' | 'submitting';
+interface ChildFieldContext<TValue> extends RootFieldContext<TValue> {
+    /** The key of the current field in its parent field. */
+    readonly key: Signal<string>;
+}
 /**
- * A reason for a field's disablement.
+ * Field context that is available for all fields that are an item in an array field.
  *
- * @category logic
  * @experimental 21.0.0
  */
-interface DisabledReason {
-    /** The field that is disabled. */
-    readonly field: FieldTree<unknown>;
-    /** A user-facing message describing the reason for the disablement. */
-    readonly message?: string;
+interface ItemFieldContext<TValue> extends ChildFieldContext<TValue> {
+    /** The index of the current field in its parent field. */
+    readonly index: Signal<number>;
 }
 /**
- * The absence of an error which indicates a successful validation result.
+ * Gets the item type of an object that is possibly an array.
  *
- * @category types
  * @experimental 21.0.0
  */
-type ValidationSuccess = null | undefined | void;
+type ItemType<T extends Object> = T extends ReadonlyArray<any> ? T[number] : T[keyof T];
 /**
- * The result of running a tree validation function.
+ * A function that defines custom debounce logic for a field.
  *
- * The result may be one of the following:
- * 1. A {@link ValidationSuccess} to indicate no errors.
- * 2. A {@link ValidationError} without a field to indicate an error on the field being validated.
- * 3. A {@link ValidationError} with a field to indicate an error on the target field.
- * 4. A list of {@link ValidationError} with or without fields to indicate multiple errors.
+ * @param context The field context.
+ * @param abortSignal An `AbortSignal` used to communicate that the debounced operation was aborted.
+ * @returns A `Promise<void>` to debounce an update, or `void` to apply an update immediately.
+ * @template TValue The type of value stored in the field.
+ * @template TPathKind The kind of path the debouncer is applied to (root field, child field, or item of an array).
  *
- * @template E the type of error (defaults to {@link ValidationError}).
+ * @experimental 21.0.0
+ */
+type Debouncer<TValue, TPathKind extends PathKind = PathKind.Root> = (context: FieldContext<TValue, TPathKind>, abortSignal: AbortSignal) => Promise<void> | void;
+
+/**
+ * Options used to create a `ValidationError`.
+ */
+interface ValidationErrorOptions {
+    /** Human readable error message. */
+    message?: string;
+}
+/**
+ * A type that requires the given type `T` to have a `field` property.
+ * @template T The type to add a `field` to.
  *
- * @category types
  * @experimental 21.0.0
  */
-type TreeValidationResult<E extends ValidationError.WithOptionalField = ValidationError.WithOptionalField> = ValidationSuccess | OneOrMany<E>;
+type WithField<T> = T & {
+    field: FieldTree<unknown>;
+};
 /**
- * A validation result where all errors explicitly define their target field.
+ * A type that allows the given type `T` to optionally have a `field` property.
+ * @template T The type to optionally add a `field` to.
  *
- * The result may be one of the following:
- * 1. A {@link ValidationSuccess} to indicate no errors.
- * 2. A {@link ValidationError} with a field to indicate an error on the target field.
- * 3. A list of {@link ValidationError} with fields to indicate multiple errors.
+ * @experimental 21.0.0
+ */
+type WithOptionalField<T> = Omit<T, 'field'> & {
+    field?: FieldTree<unknown>;
+};
+/**
+ * A type that ensures the given type `T` does not have a `field` property.
+ * @template T The type to remove the `field` from.
  *
- * @template E the type of error (defaults to {@link ValidationError}).
+ * @experimental 21.0.0
+ */
+type WithoutField<T> = T & {
+    field: never;
+};
+/**
+ * Create a required error associated with the target field
+ * @param options The validation error options
  *
- * @category types
  * @experimental 21.0.0
  */
-type ValidationResult<E extends ValidationError = ValidationError> = ValidationSuccess | OneOrMany<E>;
+declare function requiredError(options: WithField<ValidationErrorOptions>): RequiredValidationError;
 /**
- * An asynchronous validation result where all errors explicitly define their target field.
+ * Create a required error
+ * @param options The optional validation error options
  *
- * The result may be one of the following:
- * 1. A {@link ValidationResult} to indicate the result if resolved.
- * 5. 'pending' if the validation is not yet resolved.
+ * @category validation
+ * @experimental 21.0.0
+ */
+declare function requiredError(options?: ValidationErrorOptions): WithoutField<RequiredValidationError>;
+/**
+ * Create a min value error associated with the target field
+ * @param min The min value constraint
+ * @param options The validation error options
  *
- * @template E the type of error (defaults to {@link ValidationError}).
+ * @category validation
+ * @experimental 21.0.0
+ */
+declare function minError(min: number, options: WithField<ValidationErrorOptions>): MinValidationError;
+/**
+ * Create a min value error
+ * @param min The min value constraint
+ * @param options The optional validation error options
+ *
+ * @category validation
+ * @experimental 21.0.0
+ */
+declare function minError(min: number, options?: ValidationErrorOptions): WithoutField<MinValidationError>;
+/**
+ * Create a max value error associated with the target field
+ * @param max The max value constraint
+ * @param options The validation error options
  *
- * @category types
+ * @category validation
  * @experimental 21.0.0
  */
-type AsyncValidationResult<E extends ValidationError = ValidationError> = ValidationResult<E> | 'pending';
+declare function maxError(max: number, options: WithField<ValidationErrorOptions>): MaxValidationError;
 /**
- * An object that represents a tree of fields in a form. This includes both primitive value fields
- * (e.g. fields that contain a `string` or `number`), as well as "grouping fields" that contain
- * sub-fields. `FieldTree` objects are arranged in a tree whose structure mimics the structure of the
- * underlying data. For example a `FieldTree<{x: number}>` has a property `x` which contains a
- * `FieldTree<number>`. To access the state associated with a field, call it as a function.
- *
- * @template TValue The type of the data which the field is wrapped around.
- * @template TKey The type of the property key which this field resides under in its parent.
+ * Create a max value error
+ * @param max The max value constraint
+ * @param options The optional validation error options
  *
- * @category types
+ * @category validation
  * @experimental 21.0.0
  */
-type FieldTree<TModel, TKey extends string | number = string | number> = (() => [TModel] extends [AbstractControl] ? CompatFieldState<TModel, TKey> : FieldState<TModel, TKey>) & ([TModel] extends [AbstractControl] ? object : [TModel] extends [Array<infer U>] ? ReadonlyArrayLike<MaybeFieldTree<U, number>> : TModel extends Record<string, any> ? Subfields<TModel> : object);
+declare function maxError(max: number, options?: ValidationErrorOptions): WithoutField<MaxValidationError>;
 /**
- * The sub-fields that a user can navigate to from a `FieldTree<TModel>`.
- *
- * @template TModel The type of the data which the parent field is wrapped around.
+ * Create a minLength error associated with the target field
+ * @param minLength The minLength constraint
+ * @param options The validation error options
  *
+ * @category validation
  * @experimental 21.0.0
  */
-type Subfields<TModel> = {
-    readonly [K in keyof TModel as TModel[K] extends Function ? never : K]: MaybeFieldTree<TModel[K], string>;
-} & {
-    [Symbol.iterator](): Iterator<[string, MaybeFieldTree<TModel[keyof TModel], string>]>;
-};
+declare function minLengthError(minLength: number, options: WithField<ValidationErrorOptions>): MinLengthValidationError;
 /**
- * An iterable object with the same shape as a readonly array.
- *
- * @template T The array item type.
+ * Create a minLength error
+ * @param minLength The minLength constraint
+ * @param options The optional validation error options
  *
+ * @category validation
  * @experimental 21.0.0
  */
-type ReadonlyArrayLike<T> = Pick<ReadonlyArray<T>, number | 'length' | typeof Symbol.iterator>;
+declare function minLengthError(minLength: number, options?: ValidationErrorOptions): WithoutField<MinLengthValidationError>;
 /**
- * Helper type for defining `FieldTree`. Given a type `TValue` that may include `undefined`, it extracts
- * the `undefined` outside the `FieldTree` type.
- *
- * For example `MaybeField<{a: number} | undefined, TKey>` would be equivalent to
- * `undefined | FieldTree<{a: number}, TKey>`.
- *
- * @template TModel The type of the data which the field is wrapped around.
- * @template TKey The type of the property key which this field resides under in its parent.
+ * Create a maxLength error associated with the target field
+ * @param maxLength The maxLength constraint
+ * @param options The validation error options
  *
+ * @category validation
  * @experimental 21.0.0
  */
-type MaybeFieldTree<TModel, TKey extends string | number = string | number> = (TModel & undefined) | FieldTree<Exclude<TModel, undefined>, TKey>;
+declare function maxLengthError(maxLength: number, options: WithField<ValidationErrorOptions>): MaxLengthValidationError;
 /**
- * Contains all of the state (e.g. value, statuses, etc.) associated with a `FieldTree`, exposed as
- * signals.
+ * Create a maxLength error
+ * @param maxLength The maxLength constraint
+ * @param options The optional validation error options
  *
- * @category structure
+ * @category validation
  * @experimental 21.0.0
  */
-interface FieldState<TValue, TKey extends string | number = string | number> extends _FieldState<TValue> {
-    /**
-     * A signal indicating whether field value has been changed by user.
-     */
-    readonly dirty: Signal<boolean>;
-    /**
-     * A signal indicating whether a field is hidden.
-     *
-     * When a field is hidden it is ignored when determining the valid, touched, and dirty states.
-     *
-     * Note: This doesn't hide the field in the template, that must be done manually.
-     * ```
-     * @if (!field.hidden()) {
-     *   ...
-     * }
-     * ```
-     */
-    readonly hidden: Signal<boolean>;
-    readonly disabledReasons: Signal<readonly DisabledReason[]>;
-    readonly errors: Signal<ValidationError.WithField[]>;
-    /**
-     * A signal containing the {@link errors} of the field and its descendants.
-     */
-    readonly errorSummary: Signal<ValidationError.WithField[]>;
-    /**
-     * A signal indicating whether the field's value is currently valid.
-     *
-     * Note: `valid()` is not the same as `!invalid()`.
-     * - `valid()` is `true` when there are no validation errors *and* no pending validators.
-     * - `invalid()` is `true` when there are validation errors, regardless of pending validators.
-     *
-     * Ex: consider the situation where a field has 3 validators, 2 of which have no errors and 1 of
-     * which is still pending. In this case `valid()` is `false` because of the pending validator.
-     * However `invalid()` is also `false` because there are no errors.
-     */
-    readonly valid: Signal<boolean>;
-    /**
-     * A signal indicating whether the field's value is currently invalid.
-     *
-     * Note: `invalid()` is not the same as `!valid()`.
-     * - `invalid()` is `true` when there are validation errors, regardless of pending validators.
-     * - `valid()` is `true` when there are no validation errors *and* no pending validators.
-     *
-     * Ex: consider the situation where a field has 3 validators, 2 of which have no errors and 1 of
-     * which is still pending. In this case `invalid()` is `false` because there are no errors.
-     * However `valid()` is also `false` because of the pending validator.
-     */
-    readonly invalid: Signal<boolean>;
-    /**
-     * Whether there are any validators still pending for this field.
-     */
-    readonly pending: Signal<boolean>;
-    /**
-     * A signal indicating whether the field is currently in the process of being submitted.
-     */
-    readonly submitting: Signal<boolean>;
-    /**
-     * The property key in the parent field under which this field is stored. If the parent field is
-     * array-valued, for example, this is the index of this field in that array.
-     */
-    readonly keyInParent: Signal<TKey>;
-    /**
-     * The {@link Field} directives that bind this field to a UI control.
-     */
-    readonly fieldBindings: Signal<readonly Field<unknown>[]>;
-    /**
-     * Reads an aggregate metadata value from the field.
-     * @param key The metadata key to read.
-     */
-    metadata<M>(key: AggregateMetadataKey<M, any>): Signal<M>;
-    /**
-     * Reads a metadata value from the field.
-     * @param key The metadata key to read.
-     */
-    metadata<M>(key: MetadataKey<M>): M | undefined;
-    /**
-     * Checks whether the given metadata key has been defined for this field.
-     */
-    hasMetadata(key: MetadataKey<any> | AggregateMetadataKey<any, any>): boolean;
-    /**
-     * Resets the {@link touched} and {@link dirty} state of the field and its descendants.
-     *
-     * Note this does not change the data model, which can be reset directly if desired.
-     *
-     * @param value Optional value to set to the form. If not passed, the value will not be changed.
-     */
-    reset(value?: TValue): void;
-}
+declare function maxLengthError(maxLength: number, options?: ValidationErrorOptions): WithoutField<MaxLengthValidationError>;
 /**
- * This is FieldState also providing access to the wrapped FormControl.
+ * Create a pattern matching error associated with the target field
+ * @param pattern The violated pattern
+ * @param options The validation error options
  *
- * @category interop
+ * @category validation
  * @experimental 21.0.0
  */
-type CompatFieldState<TControl extends AbstractControl, TKey extends string | number = string | number> = FieldState<TControl extends AbstractControl<unknown, infer TValue> ? TValue : never, TKey> & {
-    control: Signal<TControl>;
-};
+declare function patternError(pattern: RegExp, options: WithField<ValidationErrorOptions>): PatternValidationError;
 /**
- * Allows declaring whether the Rules are supported for a given path.
+ * Create a pattern matching error
+ * @param pattern The violated pattern
+ * @param options The optional validation error options
  *
+ * @category validation
  * @experimental 21.0.0
- **/
-type SchemaPathRules = SchemaPathRules.Supported | SchemaPathRules.Unsupported;
-declare namespace SchemaPathRules {
-    /**
-     * Used for paths that support settings rules.
-     */
-    type Supported = 1;
-    /**
-     * Used for paths that do not support settings rules, e.g., compatPath.
-     */
-    type Unsupported = 2;
-}
+ */
+declare function patternError(pattern: RegExp, options?: ValidationErrorOptions): WithoutField<PatternValidationError>;
 /**
- * An object that represents a location in the `FieldTree` tree structure and is used to bind logic to a
- * particular part of the structure prior to the creation of the form. Because the `FieldPath`
- * exists prior to the form's creation, it cannot be used to access any of the field state.
- *
- * @template TValue The type of the data which the form is wrapped around.
- * @template TPathKind The kind of path (root field, child field, or item of an array)
+ * Create an email format error associated with the target field
+ * @param options The validation error options
  *
- * @category types
+ * @category validation
  * @experimental 21.0.0
  */
-type SchemaPath<TValue, TSupportsRules extends SchemaPathRules = SchemaPathRules.Supported, TPathKind extends PathKind = PathKind.Root> = {
-    [ɵɵTYPE]: {
-        value: () => TValue;
-        supportsRules: TSupportsRules;
-        pathKind: TPathKind;
-    };
-};
+declare function emailError(options: WithField<ValidationErrorOptions>): EmailValidationError;
 /**
- * Schema path used if the value is an AbstractControl.
+ * Create an email format error
+ * @param options The optional validation error options
  *
- * @category interop
+ * @category validation
  * @experimental 21.0.0
  */
-type CompatSchemaPath<TControl extends AbstractControl, TPathKind extends PathKind = PathKind.Root> = SchemaPath<TControl extends AbstractControl<unknown, infer TValue> ? TValue : never, SchemaPathRules.Unsupported, TPathKind> & {
-    [ɵɵTYPE]: {
-        control: TControl;
-    };
-};
+declare function emailError(options?: ValidationErrorOptions): WithoutField<EmailValidationError>;
 /**
- * Nested schema path.
- *
- * It mirrors the structure of a given data structure, and allows applying rules to the appropriate
- * fields.
+ * Create a standard schema issue error associated with the target field
+ * @param issue The standard schema issue
+ * @param options The validation error options
  *
+ * @category validation
  * @experimental 21.0.0
  */
-type SchemaPathTree<TModel, TPathKind extends PathKind = PathKind.Root> = ([TModel] extends [AbstractControl] ? CompatSchemaPath<TModel, TPathKind> : SchemaPath<TModel, SchemaPathRules.Supported, TPathKind>) & (TModel extends AbstractControl ? unknown : TModel extends Array<any> ? unknown : TModel extends Record<string, any> ? {
-    [K in keyof TModel]: MaybeSchemaPathTree<TModel[K], PathKind.Child>;
-} : unknown);
+declare function standardSchemaError(issue: StandardSchemaV1.Issue, options: WithField<ValidationErrorOptions>): StandardSchemaValidationError;
 /**
- * Helper type for defining `FieldPath`. Given a type `TValue` that may include `undefined`, it
- * extracts the `undefined` outside the `FieldPath` type.
- *
- * For example `MaybeFieldPath<{a: number} | undefined, PathKind.Child>` would be equivalent to
- * `undefined | FieldTree<{a: number}, PathKind.child>`.
- *
- * @template TValue The type of the data which the field is wrapped around.
- * @template TPathKind The kind of path (root field, child field, or item of an array)
+ * Create a standard schema issue error
+ * @param issue The standard schema issue
+ * @param options The optional validation error options
  *
+ * @category validation
  * @experimental 21.0.0
  */
-type MaybeSchemaPathTree<TModel, TPathKind extends PathKind = PathKind.Root> = (TModel & undefined) | SchemaPathTree<Exclude<TModel, undefined>, TPathKind>;
+declare function standardSchemaError(issue: StandardSchemaV1.Issue, options?: ValidationErrorOptions): WithoutField<StandardSchemaValidationError>;
 /**
- * Defines logic for a form.
+ * Create a custom error associated with the target field
+ * @param obj The object to create an error from
  *
- * @template TValue The type of data stored in the form that this schema is attached to.
+ * @category validation
+ * @experimental 21.0.0
+ */
+declare function customError<E extends Partial<ValidationError.WithField>>(obj: WithField<E>): CustomValidationError;
+/**
+ * Create a custom error
+ * @param obj The object to create an error from
  *
- * @category types
+ * @category validation
  * @experimental 21.0.0
  */
-type Schema<in TModel> = {
-    [ɵɵTYPE]: SchemaFn<TModel, PathKind.Root>;
-};
+declare function customError<E extends Partial<ValidationError.WithField>>(obj?: E): WithoutField<CustomValidationError>;
 /**
- * Function that defines rules for a schema.
+ * Common interface for all validation errors.
  *
- * @template TModel The type of data stored in the form that this schema function is attached to.
- * @template TPathKind The kind of path this schema function can be bound to.
+ * This can be returned from validators.
  *
- * @category types
+ * It's also used by the creation functions to create an instance
+ * (e.g. `requiredError`, `minError`, etc.).
+ *
+ * @category validation
  * @experimental 21.0.0
  */
-type SchemaFn<TModel, TPathKind extends PathKind = PathKind.Root> = (p: SchemaPathTree<TModel, TPathKind>) => void;
+interface ValidationError {
+    /** Identifies the kind of error. */
+    readonly kind: string;
+    /** Human readable error message. */
+    readonly message?: string;
+}
+declare namespace ValidationError {
+    /**
+     * Validation error with a field.
+     *
+     * This is returned from field state, e.g., catField.errors() would be of a list of errors with
+     * `field: catField` bound to state.
+     */
+    interface WithField extends ValidationError {
+        /** The field associated with this error. */
+        readonly field: FieldTree<unknown>;
+    }
+    /**
+     * Validation error with optional field.
+     *
+     * This is generally used in places where the result might have a field.
+     * e.g., as a result of a `validateTree`, or when handling form submission.
+     */
+    interface WithOptionalField extends ValidationError {
+        /** The field associated with this error. */
+        readonly field?: FieldTree<unknown>;
+    }
+    /**
+     * Validation error with no field.
+     *
+     * This is used to strongly enforce that fields are not allowed in validation result.
+     */
+    interface WithoutField extends ValidationError {
+        /** The field associated with this error. */
+        readonly field?: never;
+    }
+}
 /**
- * A schema or schema definition function.
- *
- * @template TModel The type of data stored in the form that this schema function is attached to.
- * @template TPathKind The kind of path this schema function can be bound to.
+ * A custom error that may contain additional properties
  *
- * @category types
+ * @category validation
  * @experimental 21.0.0
  */
-type SchemaOrSchemaFn<TModel, TPathKind extends PathKind = PathKind.Root> = Schema<TModel> | SchemaFn<TModel, TPathKind>;
+declare class CustomValidationError implements ValidationError {
+    /** Brand the class to avoid Typescript structural matching */
+    private __brand;
+    /**
+     * Allow the user to attach arbitrary other properties.
+     */
+    [key: PropertyKey]: unknown;
+    /** Identifies the kind of error. */
+    readonly kind: string;
+    /** The field associated with this error. */
+    readonly field: FieldTree<unknown>;
+    /** Human readable error message. */
+    readonly message?: string;
+    constructor(options?: ValidationErrorOptions);
+}
 /**
- * A function that receives the `FieldContext` for the field the logic is bound to and returns
- * a specific result type.
- *
- * @template TValue The data type for the field the logic is bound to.
- * @template TReturn The type of the result returned by the logic function.
- * @template TPathKind The kind of path the logic is applied to (root field, child field, or item of an array)
+ * Internal version of `NgValidationError`, we create this separately so we can change its type on
+ * the exported version to a type union of the possible sub-classes.
  *
- * @category types
  * @experimental 21.0.0
  */
-type LogicFn<TValue, TReturn, TPathKind extends PathKind = PathKind.Root> = (ctx: FieldContext<TValue, TPathKind>) => TReturn;
+declare abstract class _NgValidationError implements ValidationError {
+    /** Brand the class to avoid Typescript structural matching */
+    private __brand;
+    /** Identifies the kind of error. */
+    readonly kind: string;
+    /** The field associated with this error. */
+    readonly field: FieldTree<unknown>;
+    /** Human readable error message. */
+    readonly message?: string;
+    constructor(options?: ValidationErrorOptions);
+}
 /**
- * A function that takes the `FieldContext` for the field being validated and returns a
- * `ValidationResult` indicating errors for the field.
- *
- * @template TValue The type of value stored in the field being validated
- * @template TPathKind The kind of path being validated (root field, child field, or item of an array)
+ * An error used to indicate that a required field is empty.
  *
  * @category validation
  * @experimental 21.0.0
  */
-type FieldValidator<TValue, TPathKind extends PathKind = PathKind.Root> = LogicFn<TValue, ValidationResult<ValidationError.WithoutField>, TPathKind>;
+declare class RequiredValidationError extends _NgValidationError {
+    readonly kind = "required";
+}
 /**
- * A function that takes the `FieldContext` for the field being validated and returns a
- * `TreeValidationResult` indicating errors for the field and its sub-fields.
- *
- * @template TValue The type of value stored in the field being validated
- * @template TPathKind The kind of path being validated (root field, child field, or item of an array)
+ * An error used to indicate that a value is lower than the minimum allowed.
  *
- * @category types
+ * @category validation
  * @experimental 21.0.0
  */
-type TreeValidator<TValue, TPathKind extends PathKind = PathKind.Root> = LogicFn<TValue, TreeValidationResult, TPathKind>;
+declare class MinValidationError extends _NgValidationError {
+    readonly min: number;
+    readonly kind = "min";
+    constructor(min: number, options?: ValidationErrorOptions);
+}
 /**
- * A function that takes the `FieldContext` for the field being validated and returns a
- * `ValidationResult` indicating errors for the field and its sub-fields. In a `Validator` all
- * errors must explicitly define their target field.
- *
- * @template TValue The type of value stored in the field being validated
- * @template TPathKind The kind of path being validated (root field, child field, or item of an array)
+ * An error used to indicate that a value is higher than the maximum allowed.
  *
- * @category types
+ * @category validation
  * @experimental 21.0.0
  */
-type Validator<TValue, TPathKind extends PathKind = PathKind.Root> = LogicFn<TValue, ValidationResult, TPathKind>;
+declare class MaxValidationError extends _NgValidationError {
+    readonly max: number;
+    readonly kind = "max";
+    constructor(max: number, options?: ValidationErrorOptions);
+}
 /**
- * Provides access to the state of the current field as well as functions that can be used to look
- * up state of other fields based on a `FieldPath`.
+ * An error used to indicate that a value is shorter than the minimum allowed length.
  *
- * @category types
+ * @category validation
  * @experimental 21.0.0
  */
-type FieldContext<TValue, TPathKind extends PathKind = PathKind.Root> = TPathKind extends PathKind.Item ? ItemFieldContext<TValue> : TPathKind extends PathKind.Child ? ChildFieldContext<TValue> : RootFieldContext<TValue>;
+declare class MinLengthValidationError extends _NgValidationError {
+    readonly minLength: number;
+    readonly kind = "minLength";
+    constructor(minLength: number, options?: ValidationErrorOptions);
+}
 /**
- * The base field context that is available for all fields.
+ * An error used to indicate that a value is longer than the maximum allowed length.
  *
+ * @category validation
  * @experimental 21.0.0
  */
-interface RootFieldContext<TValue> {
-    /** A signal containing the value of the current field. */
-    readonly value: Signal<TValue>;
-    /** The state of the current field. */
-    readonly state: FieldState<TValue>;
-    /** The current field. */
-    readonly field: FieldTree<TValue>;
-    /** Gets the value of the field represented by the given path. */
-    valueOf<PValue>(p: SchemaPath<PValue, SchemaPathRules>): PValue;
-    /** Gets the state of the field represented by the given path. */
-    stateOf<PControl extends AbstractControl>(p: CompatSchemaPath<PControl>): CompatFieldState<PControl>;
-    stateOf<PValue>(p: SchemaPath<PValue, SchemaPathRules>): FieldState<PValue>;
-    /** Gets the field represented by the given path. */
-    fieldTreeOf<PModel>(p: SchemaPathTree<PModel>): FieldTree<PModel>;
-    /** The list of keys that lead from the root field to the current field. */
-    readonly pathKeys: Signal<readonly string[]>;
+declare class MaxLengthValidationError extends _NgValidationError {
+    readonly maxLength: number;
+    readonly kind = "maxLength";
+    constructor(maxLength: number, options?: ValidationErrorOptions);
 }
 /**
- * Field context that is available for all fields that are a child of another field.
+ * An error used to indicate that a value does not match the required pattern.
  *
- * @category structure
+ * @category validation
  * @experimental 21.0.0
  */
-interface ChildFieldContext<TValue> extends RootFieldContext<TValue> {
-    /** The key of the current field in its parent field. */
-    readonly key: Signal<string>;
+declare class PatternValidationError extends _NgValidationError {
+    readonly pattern: RegExp;
+    readonly kind = "pattern";
+    constructor(pattern: RegExp, options?: ValidationErrorOptions);
 }
 /**
- * Field context that is available for all fields that are an item in an array field.
+ * An error used to indicate that a value is not a valid email.
  *
+ * @category validation
  * @experimental 21.0.0
  */
-interface ItemFieldContext<TValue> extends ChildFieldContext<TValue> {
-    /** The index of the current field in its parent field. */
-    readonly index: Signal<number>;
+declare class EmailValidationError extends _NgValidationError {
+    readonly kind = "email";
 }
 /**
- * Gets the item type of an object that is possibly an array.
+ * An error used to indicate an issue validating against a standard schema.
  *
+ * @category validation
  * @experimental 21.0.0
  */
-type ItemType<T extends Object> = T extends ReadonlyArray<any> ? T[number] : T[keyof T];
+declare class StandardSchemaValidationError extends _NgValidationError {
+    readonly issue: StandardSchemaV1.Issue;
+    readonly kind = "standardSchema";
+    constructor(issue: StandardSchemaV1.Issue, options?: ValidationErrorOptions);
+}
 /**
- * A function that defines custom debounce logic for a field.
+ * The base class for all built-in, non-custom errors. This class can be used to check if an error
+ * is one of the standard kinds, allowing you to switch on the kind to further narrow the type.
  *
- * @param context The field context.
- * @param abortSignal An `AbortSignal` used to communicate that the debounced operation was aborted.
- * @returns A `Promise<void>` to debounce an update, or `void` to apply an update immediately.
- * @template TValue The type of value stored in the field.
- * @template TPathKind The kind of path the debouncer is applied to (root field, child field, or item of an array).
+ * @example
+ * ```ts
+ * const f = form(...);
+ * for (const e of form().errors()) {
+ *   if (e instanceof NgValidationError) {
+ *     switch(e.kind) {
+ *       case 'required':
+ *         console.log('This is required!');
+ *         break;
+ *       case 'min':
+ *         console.log(`Must be at least ${e.min}`);
+ *         break;
+ *       ...
+ *     }
+ *   }
+ * }
+ * ```
  *
+ * @category validation
  * @experimental 21.0.0
  */
-type Debouncer<TValue, TPathKind extends PathKind = PathKind.Root> = (context: FieldContext<TValue, TPathKind>, abortSignal: AbortSignal) => Promise<void> | void;
+declare const NgValidationError: abstract new () => NgValidationError;
+type NgValidationError = RequiredValidationError | MinValidationError | MaxValidationError | MinLengthValidationError | MaxLengthValidationError | PatternValidationError | EmailValidationError | StandardSchemaValidationError;
 
 /**
  * Configuration options for signal forms.
@@ -1205,41 +1242,27 @@ declare class LogicContainer {
     readonly syncTreeErrors: ArrayMergeIgnoreLogic<ValidationError.WithField, null>;
     /** Logic that produces asynchronous validation results (errors or 'pending'). */
     readonly asyncErrors: ArrayMergeIgnoreLogic<ValidationError.WithField | 'pending', null>;
-    /** A map of aggregate metadata keys to the `AbstractLogic` instances that compute their values. */
-    private readonly aggregateMetadataKeys;
-    /** A map of metadata keys to the factory functions that create their values. */
-    private readonly metadataFactories;
+    /** A map of metadata keys to the `AbstractLogic` instances that compute their values. */
+    private readonly metadata;
     /**
      * Constructs a new `Logic` container.
      * @param predicates An array of predicates that must all be true for the logic
      *   functions within this container to be active.
      */
     constructor(predicates: ReadonlyArray<BoundPredicate>);
-    /** Checks whether there is logic for the given aggregate metadata key. */
-    hasAggregateMetadata(key: AggregateMetadataKey<any, any>): boolean;
-    /**
-     * Gets an iterable of [aggregate metadata, logic function] pairs.
-     * @returns An iterable of aggregate metadata entries.
-     */
-    getAggregateMetadataEntries(): MapIterator<[AggregateMetadataKey<unknown, unknown>, AbstractLogic<unknown, unknown>]>;
+    /** Checks whether there is logic for the given metadata key. */
+    hasMetadata(key: MetadataKey<any, any, any>): boolean;
     /**
-     * Gets an iterable of [metadata, value factory function] pairs.
-     * @returns An iterable of metadata factory entries.
+     * Gets an iterable of [metadata key, logic function] pairs.
+     * @returns An iterable of metadata keys.
      */
-    getMetadataFactoryEntries(): MapIterator<[MetadataKey<unknown>, (ctx: FieldContext<unknown>) => unknown]>;
+    getMetadataKeys(): MapIterator<MetadataKey<unknown, unknown, unknown>>;
     /**
-     * Retrieves or creates the `AbstractLogic` for a given aggregate metadata key.
-     * @param key The `AggregateMetadataKey` for which to get the logic.
+     * Retrieves or creates the `AbstractLogic` for a given metadata key.
+     * @param key The `MetadataKey` for which to get the logic.
      * @returns The `AbstractLogic` associated with the key.
      */
-    getAggregateMetadata<T>(key: AggregateMetadataKey<any, T>): AbstractLogic<T>;
-    /**
-     * Adds a factory function for a given metadata key.
-     * @param key The `MetadataKey` to associate the factory with.
-     * @param factory The factory function.
-     * @throws If a factory is already defined for the given key.
-     */
-    addMetadataFactory(key: MetadataKey<unknown>, factory: (ctx: FieldContext<unknown>) => unknown): void;
+    getMetadata<T>(key: MetadataKey<any, T, any>): AbstractLogic<T>;
     /**
      * Merges logic from another `Logic` instance into this one.
      * @param other The `Logic` instance to merge from.
@@ -1271,10 +1294,8 @@ declare abstract class AbstractLogicNodeBuilder {
     abstract addSyncTreeErrorRule(logic: LogicFn<any, ValidationResult>): void;
     /** Adds a rule for asynchronous validation errors for a field. */
     abstract addAsyncErrorRule(logic: LogicFn<any, AsyncValidationResult>): void;
-    /** Adds a rule to compute aggregate metadata for a field. */
-    abstract addAggregateMetadataRule<M>(key: AggregateMetadataKey<unknown, M>, logic: LogicFn<any, M>): void;
-    /** Adds a factory function to produce a data value associated with a field. */
-    abstract addMetadataFactory<D>(key: MetadataKey<D>, factory: (ctx: FieldContext<any>) => D): void;
+    /** Adds a rule to compute metadata for a field. */
+    abstract addMetadataRule<M>(key: MetadataKey<unknown, M, unknown>, logic: LogicFn<any, M>): void;
     /**
      * Gets a builder for a child node associated with the given property key.
      * @param key The property key of the child.
@@ -1320,8 +1341,7 @@ declare class LogicNodeBuilder extends AbstractLogicNodeBuilder {
     addSyncErrorRule(logic: LogicFn<any, ValidationResult<ValidationError.WithField>>): void;
     addSyncTreeErrorRule(logic: LogicFn<any, ValidationResult<ValidationError.WithField>>): void;
     addAsyncErrorRule(logic: LogicFn<any, AsyncValidationResult<ValidationError.WithField>>): void;
-    addAggregateMetadataRule<T>(key: AggregateMetadataKey<any, T>, logic: LogicFn<any, T>): void;
-    addMetadataFactory<D>(key: MetadataKey<D>, factory: (ctx: FieldContext<any>) => D): void;
+    addMetadataRule<T>(key: MetadataKey<unknown, T, any>, logic: LogicFn<any, T>): void;
     getChild(key: PropertyKey): LogicNodeBuilder;
     hasLogic(builder: AbstractLogicNodeBuilder): boolean;
     /**
@@ -1450,13 +1470,13 @@ declare class FieldPathNode {
  */
 declare class FieldMetadataState {
     private readonly node;
-    /** A map of all `MetadataKey` and `AggregateMetadataKey` that have been defined for this field. */
+    /** A map of all `MetadataKey` that have been defined for this field. */
     private readonly metadata;
     constructor(node: FieldNode);
-    /** Gets the value of a `MetadataKey` or `AggregateMetadataKey` for the field. */
-    get<T>(key: MetadataKey<T> | AggregateMetadataKey<T, unknown>): T | undefined | Signal<T>;
+    /** Gets the value of an `MetadataKey` for the field. */
+    get<T>(key: MetadataKey<T, unknown, unknown>): T | undefined;
     /** Checks whether the current metadata state has the given metadata key. */
-    has(key: MetadataKey<any> | AggregateMetadataKey<any, any>): boolean;
+    has(key: MetadataKey<any, any, any>): boolean;
 }
 
 /**
@@ -1695,6 +1715,7 @@ declare class FieldNode implements FieldState<unknown> {
      * Proxy to this node which allows navigation of the form graph below it.
      */
     readonly fieldProxy: FieldTree<any>;
+    private readonly pathNode;
     constructor(options: FieldNodeOptions);
     /**
      * The `AbortController` for the currently debounced sync, or `undefined` if there is none.
@@ -1723,16 +1744,14 @@ declare class FieldNode implements FieldState<unknown> {
     get fieldBindings(): Signal<readonly Field<unknown>[]>;
     get submitting(): Signal<boolean>;
     get name(): Signal<string>;
-    private metadataOrUndefined;
     get max(): Signal<number | undefined> | undefined;
     get maxLength(): Signal<number | undefined> | undefined;
     get min(): Signal<number | undefined> | undefined;
     get minLength(): Signal<number | undefined> | undefined;
     get pattern(): Signal<readonly RegExp[]>;
     get required(): Signal<boolean>;
-    metadata<M>(key: AggregateMetadataKey<M, any>): Signal<M>;
-    metadata<M>(key: MetadataKey<M>): M | undefined;
-    hasMetadata(key: MetadataKey<any> | AggregateMetadataKey<any, any>): boolean;
+    metadata<M>(key: MetadataKey<M, any, any>): M | undefined;
+    hasMetadata(key: MetadataKey<any, any, any>): boolean;
     /**
      * Marks this specific field as touched.
      */
@@ -1772,11 +1791,8 @@ declare class FieldNode implements FieldState<unknown> {
      * Creates a new root field node for a new form.
      */
     static newRoot<T>(fieldManager: FormFieldManager, value: WritableSignal<T>, pathNode: FieldPathNode, adapter: FieldAdapter): FieldNode;
-    /**
-     * Creates a child field node based on the given options.
-     */
-    private static newChild;
     createStructure(options: FieldNodeOptions): RootFieldNodeStructure | ChildFieldNodeStructure;
+    private newChild;
 }
 /**
  * Field node of a field that has children.
@@ -1798,12 +1814,16 @@ interface ParentFieldNode extends FieldNode {
 type TrackingKey = PropertyKey & {
     __brand: 'FieldIdentity';
 };
+type ChildNodeCtor = (key: string, trackingKey: TrackingKey | undefined, isArray: boolean) => FieldNode;
 /** Structural component of a `FieldNode` which tracks its path, parent, and children. */
 declare abstract class FieldNodeStructure {
-    /** The logic to apply to this field. */
-    readonly logic: LogicNode;
-    /** Computed map of child fields, based on the current value of this field. */
-    abstract readonly childrenMap: Signal<Map<TrackingKey, FieldNode> | undefined>;
+    /**
+     * Computed map of child fields, based on the current value of this field.
+     *
+     * This structure reacts to `this.value` and produces a new `ChildrenData` when the
+     * value changes structurally (fields added/removed/moved).
+     */
+    protected abstract readonly childrenMap: Signal<ChildrenData | undefined>;
     /** The field's value. */
     abstract readonly value: WritableSignal<unknown>;
     /**
@@ -1819,33 +1839,60 @@ declare abstract class FieldNodeStructure {
     abstract readonly pathKeys: Signal<readonly string[]>;
     /** The parent field of this field. */
     abstract readonly parent: FieldNode | undefined;
+    readonly logic: LogicNode;
+    readonly node: FieldNode;
+    readonly createChildNode: ChildNodeCtor;
     /** Added to array elements for tracking purposes. */
     readonly identitySymbol: symbol;
     /** Lazily initialized injector. Do not access directly, access via `injector` getter instead. */
     private _injector;
     /** Lazily initialized injector. */
     get injector(): DestroyableInjector;
-    constructor(
-    /** The logic to apply to this field. */
-    logic: LogicNode);
+    constructor(logic: LogicNode, node: FieldNode, createChildNode: ChildNodeCtor);
     /** Gets the child fields of this field. */
     children(): Iterable<FieldNode>;
     /** Retrieve a child `FieldNode` of this node by property key. */
     getChild(key: PropertyKey): FieldNode | undefined;
+    /**
+     * Perform a reduction over a field's children (if any) and return the result.
+     *
+     * Optionally, the reduction is short circuited based on the provided `shortCircuit` function.
+     */
+    reduceChildren<T>(initialValue: T, fn: (child: FieldNode, value: T) => T, shortCircuit?: (value: T) => boolean): T;
     /** Destroys the field when it is no longer needed. */
     destroy(): void;
+    /**
+     * Creates a keyInParent signal for a field node.
+     *
+     * For root nodes, returns ROOT_KEY_IN_PARENT which throws when accessed.
+     * For child nodes, creates a computed that tracks the field's current key in its parent,
+     * with special handling for tracked array elements.
+     *
+     * @param options The field node options
+     * @param identityInParent The tracking identity (only for tracked array children)
+     * @param initialKeyInParent The initial key in parent (only for child nodes)
+     * @returns A signal representing the field's key in its parent
+     */
+    protected createKeyInParent(options: FieldNodeOptions, identityInParent: TrackingKey | undefined, initialKeyInParent: string | undefined): Signal<string>;
+    protected createChildrenMap(): Signal<ChildrenData | undefined>;
+    /**
+     * Creates a "reader" computed for the given key.
+     *
+     * A reader is a computed signal that memoizes the access of the `FieldNode` stored at this key
+     * (or returns `undefined` if no such field exists). Accessing fields via the reader ensures that
+     * reactive consumers aren't notified unless the field at a key actually changes.
+     */
+    private createReader;
 }
 /** The structural component of a `FieldNode` that is the root of its field tree. */
 declare class RootFieldNodeStructure extends FieldNodeStructure {
-    /** The full field node that corresponds to this structure. */
-    private readonly node;
     readonly fieldManager: FormFieldManager;
     readonly value: WritableSignal<unknown>;
     get parent(): undefined;
     get root(): FieldNode;
     get pathKeys(): Signal<readonly string[]>;
     get keyInParent(): Signal<string>;
-    readonly childrenMap: Signal<Map<TrackingKey, FieldNode> | undefined>;
+    protected readonly childrenMap: Signal<ChildrenData | undefined>;
     /**
      * Creates the structure for the root node of a field tree.
      *
@@ -1859,16 +1906,17 @@ declare class RootFieldNodeStructure extends FieldNodeStructure {
      */
     constructor(
     /** The full field node that corresponds to this structure. */
-    node: FieldNode, pathNode: FieldPathNode, logic: LogicNode, fieldManager: FormFieldManager, value: WritableSignal<unknown>, adapter: FieldAdapter, createChildNode: (options: ChildFieldNodeOptions) => FieldNode);
+    node: FieldNode, logic: LogicNode, fieldManager: FormFieldManager, value: WritableSignal<unknown>, createChildNode: ChildNodeCtor);
 }
 /** The structural component of a child `FieldNode` within a field tree. */
 declare class ChildFieldNodeStructure extends FieldNodeStructure {
+    readonly logic: LogicNode;
     readonly parent: ParentFieldNode;
     readonly root: FieldNode;
     readonly pathKeys: Signal<readonly string[]>;
     readonly keyInParent: Signal<string>;
     readonly value: WritableSignal<unknown>;
-    readonly childrenMap: Signal<Map<TrackingKey, FieldNode> | undefined>;
+    readonly childrenMap: Signal<ChildrenData | undefined>;
     get fieldManager(): FormFieldManager;
     /**
      * Creates the structure for a child field node in a field tree.
@@ -1882,7 +1930,7 @@ declare class ChildFieldNodeStructure extends FieldNodeStructure {
      * @param adapter Adapter that knows how to create new fields and appropriate state.
      * @param createChildNode A factory function to create child nodes for this field.
      */
-    constructor(node: FieldNode, pathNode: FieldPathNode, logic: LogicNode, parent: ParentFieldNode, identityInParent: TrackingKey | undefined, initialKeyInParent: string, adapter: FieldAdapter, createChildNode: (options: ChildFieldNodeOptions) => FieldNode);
+    constructor(node: FieldNode, logic: LogicNode, parent: ParentFieldNode, identityInParent: TrackingKey | undefined, initialKeyInParent: string, createChildNode: ChildNodeCtor);
 }
 /** Options passed when constructing a root field node. */
 interface RootFieldNodeOptions {
@@ -1918,6 +1966,38 @@ interface ChildFieldNodeOptions {
 }
 /** Options passed when constructing a field node. */
 type FieldNodeOptions = RootFieldNodeOptions | ChildFieldNodeOptions;
+/**
+ * Derived data regarding child fields for a specific parent field.
+ */
+interface ChildrenData {
+    /**
+     * Tracks `ChildData` for each property key within the parent.
+     */
+    readonly byPropertyKey: ReadonlyMap<string, ChildData>;
+    /**
+     * Tracks the instance of child `FieldNode`s by their tracking key, which is always 1:1 with the
+     * fields, even if they move around in the parent.
+     */
+    readonly byTrackingKey?: ReadonlyMap<TrackingKey, FieldNode>;
+}
+/**
+ * Data for a specific child within a parent.
+ */
+interface ChildData {
+    /**
+     * A computed signal to access the `FieldNode` currently stored at a specific key.
+     *
+     * Because this is a computed, it only updates whenever the `FieldNode` at that key changes.
+     * Because `ChildData` is always associated with a specific key via `ChildrenData.byPropertyKey`,
+     * this computed gives a stable way to watch the field stored for a given property and only
+     * receives notifications when that field changes.
+     */
+    readonly reader: Signal<FieldNode | undefined>;
+    /**
+     * The child `FieldNode` currently stored at this key.
+     */
+    node: FieldNode;
+}
 
 /**
  * Manages the collection of fields associated with a given `form`.
@@ -2264,5 +2344,5 @@ declare function submit<TModel>(form: FieldTree<TModel>, action: (form: FieldTre
  */
 declare function schema<TValue>(fn: SchemaFn<TValue>): Schema<TValue>;
 
-export { AggregateMetadataKey, CustomValidationError, EmailValidationError, FIELD, Field, MAX, MAX_LENGTH, MIN, MIN_LENGTH, MaxLengthValidationError, MaxValidationError, MetadataKey, MinLengthValidationError, MinValidationError, NgValidationError, PATTERN, PathKind, PatternValidationError, REQUIRED, RequiredValidationError, SchemaPathRules, StandardSchemaValidationError, ValidationError, andMetadataKey, apply, applyEach, applyWhen, applyWhenValue, createMetadataKey, customError, emailError, form, listMetadataKey, maxError, maxLengthError, maxMetadataKey, minError, minLengthError, minMetadataKey, orMetadataKey, patternError, provideSignalFormsConfig, reducedMetadataKey, requiredError, schema, standardSchemaError, submit };
-export type { AsyncValidationResult, ChildFieldContext, CompatFieldState, CompatSchemaPath, Debouncer, DisabledReason, FieldContext, FieldState, FieldTree, FieldValidator, FormOptions, ItemFieldContext, ItemType, LogicFn, MaybeFieldTree, MaybeSchemaPathTree, OneOrMany, ReadonlyArrayLike, RootFieldContext, Schema, SchemaFn, SchemaOrSchemaFn, SchemaPath, SchemaPathTree, SignalFormsConfig, Subfields, SubmittedStatus, TreeValidationResult, TreeValidator, ValidationResult, ValidationSuccess, Validator, WithField, WithOptionalField, WithoutField };
+export { CustomValidationError, EmailValidationError, FIELD, Field, MAX, MAX_LENGTH, MIN, MIN_LENGTH, MaxLengthValidationError, MaxValidationError, MetadataKey, MetadataReducer, MinLengthValidationError, MinValidationError, NgValidationError, PATTERN, PathKind, PatternValidationError, REQUIRED, RequiredValidationError, SchemaPathRules, StandardSchemaValidationError, ValidationError, apply, applyEach, applyWhen, applyWhenValue, createManagedMetadataKey, createMetadataKey, customError, emailError, form, maxError, maxLengthError, metadata, minError, minLengthError, patternError, provideSignalFormsConfig, requiredError, schema, standardSchemaError, submit };
+export type { AsyncValidationResult, ChildFieldContext, CompatFieldState, CompatSchemaPath, Debouncer, DisabledReason, FieldContext, FieldState, FieldTree, FieldValidator, FormOptions, ItemFieldContext, ItemType, LogicFn, MaybeFieldTree, MaybeSchemaPathTree, MetadataSetterType, OneOrMany, ReadonlyArrayLike, RootFieldContext, Schema, SchemaFn, SchemaOrSchemaFn, SchemaPath, SchemaPathTree, SignalFormsConfig, Subfields, SubmittedStatus, TreeValidationResult, TreeValidator, ValidationResult, ValidationSuccess, Validator, WithField, WithOptionalField, WithoutField };