@angular/forms 21.0.0-next.8 → 21.0.0-rc.0

package/types/signals.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Angular v21.0.0-next.8
+ * @license Angular v21.0.0-rc.0
  * (c) 2010-2025 Google LLC. https://angular.dev/
  * License: MIT
  */
@@ -7,26 +7,60 @@
 import { HttpResourceRequest, HttpResourceOptions } from '@angular/common/http';
 import * as i0 from '@angular/core';
 import { InjectionToken, ɵControl as _Control, ɵCONTROL as _CONTROL, ɵFieldState as _FieldState, Signal, ResourceRef, InputSignal, ModelSignal, OutputRef, WritableSignal, DestroyableInjector, Injector } from '@angular/core';
+import { NgControl, AbstractControl, ValidationErrors, FormControlStatus, ControlValueAccessor, ValidatorFn } from '@angular/forms';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 
+/**
+ * Properties of both NgControl & AbstractControl that are supported by the InteropNgControl.
+ */
+type InteropSharedKeys = 'value' | 'valid' | 'invalid' | 'touched' | 'untouched' | 'disabled' | 'enabled' | 'errors' | 'pristine' | 'dirty' | 'status';
+/**
+ * A fake version of `NgControl` provided by the `Field` directive. This allows interoperability
+ * with a wider range of components designed to work with reactive forms, in particular ones that
+ * inject the `NgControl`. The interop control does not implement *all* properties and methods of
+ * the real `NgControl`, but does implement some of the most commonly used ones that have a clear
+ * equivalent in signal forms.
+ */
+declare class InteropNgControl implements Pick<NgControl, InteropSharedKeys | 'control' | 'valueAccessor'>, Pick<AbstractControl<unknown>, InteropSharedKeys | 'hasValidator'> {
+    protected field: () => FieldState<unknown>;
+    constructor(field: () => FieldState<unknown>);
+    readonly control: AbstractControl<any, any>;
+    get value(): any;
+    get valid(): boolean;
+    get invalid(): boolean;
+    get pending(): boolean | null;
+    get disabled(): boolean;
+    get enabled(): boolean;
+    get errors(): ValidationErrors | null;
+    get pristine(): boolean;
+    get dirty(): boolean;
+    get touched(): boolean;
+    get untouched(): boolean;
+    get status(): FormControlStatus;
+    valueAccessor: ControlValueAccessor | null;
+    hasValidator(validator: ValidatorFn): boolean;
+    updateValueAndValidity(): void;
+}
+
 /**
  * Lightweight DI token provided by the {@link Field} directive.
+ *
+ * @category control
+ * @experimental 21.0.0
  */
 declare const FIELD: InjectionToken<Field<unknown>>;
 /**
  * Binds a form `FieldTree` to a UI control that edits it. A UI control can be one of several things:
  * 1. A native HTML input or textarea
  * 2. A signal forms custom control that implements `FormValueControl` or `FormCheckboxControl`
- * 3. TODO: https://github.com/orgs/angular/projects/60/views/1?pane=issue&itemId=131712274. A
- *    component that provides a ControlValueAccessor. This should only be used to backwards
+ * 3. A component that provides a `ControlValueAccessor`. This should only be used for backwards
  *    compatibility with reactive forms. Prefer options (1) and (2).
  *
  * This directive has several responsibilities:
  * 1. Two-way binds the field's value with the UI control's value
  * 2. Binds additional forms related state on the field to the UI control (disabled, required, etc.)
  * 3. Relays relevant events on the control to the field (e.g. marks field touched on blur)
- * 4. TODO: https://github.com/orgs/angular/projects/60/views/1?pane=issue&itemId=131712274.
- *    Provides a fake `NgControl` that implements a subset of the features available on the
+ * 4. Provides a fake `NgControl` that implements a subset of the features available on the
  *    reactive forms `NgControl`. This is provided to improve interoperability with controls
  *    designed to work with reactive forms. It should not be used by controls written for signal
  *    forms.
@@ -39,125 +73,138 @@ declare class Field<T> implements _Control<T> {
     readonly field: i0.InputSignal<FieldTree<T>>;
     readonly state: i0.Signal<FieldState<T, string | number>>;
     readonly [_CONTROL]: undefined;
-    register(): void;
+    /** 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. */
+    private get controlValueAccessor();
+    get ɵhasInteropControl(): boolean;
+    /** Lazily instantiates a fake `NgControl` for this field. */
+    ɵgetOrCreateNgControl(): InteropNgControl;
+    ɵinteropControlCreate(): void;
+    ɵinteropControlUpdate(): void;
+    ɵ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 a property that may be defined on a field when it is created using a `property` rule
- * in the schema. A particular `Property` can only be defined on a particular field **once**.
+ * 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**.
  *
  * @category logic
  * @experimental 21.0.0
  */
-declare class Property<TValue> {
+declare class MetadataKey<TValue> {
     private brand;
-    /** Use {@link createProperty}. */
+    /** Use {@link createMetadataKey}. */
     private constructor();
 }
 /**
- * Creates a {@link Property}.
+ * Creates a {@link MetadataKey}.
  *
  * @experimental 21.0.0
  */
-declare function createProperty<TValue>(): Property<TValue>;
+declare function createMetadataKey<TValue>(): MetadataKey<TValue>;
 /**
- * Represents a property that is aggregated from multiple parts according to the property's reducer
+ * 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
- * `aggregateProperty` rule in the schema. There may be multiple rules in a schema that contribute
- * values to the same `AggregateProperty` of the same field.
+ * `aggregateMetadata` rule in the schema. There may be multiple rules in a schema that contribute
+ * values to the same `AggregateMetadataKey` of the same field.
  *
  * @experimental 21.0.0
  */
-declare class AggregateProperty<TAcc, TItem> {
+declare class AggregateMetadataKey<TAcc, TItem> {
     readonly reduce: (acc: TAcc, item: TItem) => TAcc;
     readonly getInitial: () => TAcc;
     private brand;
-    /** Use {@link reducedProperty}. */
+    /** Use {@link reducedMetadataKey}. */
     private constructor();
 }
 /**
- * Creates an aggregate property that reduces its individual values into an accumulated value using
- * the given `reduce` and `getInitial` functions.
+ * 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.
  *
  * @experimental 21.0.0
  */
-declare function reducedProperty<TAcc, TItem>(reduce: (acc: TAcc, item: TItem) => TAcc, getInitial: () => TAcc): AggregateProperty<TAcc, TItem>;
+declare function reducedMetadataKey<TAcc, TItem>(reduce: (acc: TAcc, item: TItem) => TAcc, getInitial: () => TAcc): AggregateMetadataKey<TAcc, TItem>;
 /**
- * Creates an aggregate property that reduces its individual values into a list.
+ * Creates an {@link AggregateMetadataKey} that reduces its individual values into a list.
  *
  * @experimental 21.0.0
  */
-declare function listProperty<TItem>(): AggregateProperty<TItem[], TItem | undefined>;
+declare function listMetadataKey<TItem>(): AggregateMetadataKey<TItem[], TItem | undefined>;
 /**
- * Creates an aggregate property that reduces its individual values by taking their min.
+ * Creates {@link AggregateMetadataKey} that reduces its individual values by taking their min.
  *
  * @experimental 21.0.0
  */
-declare function minProperty(): AggregateProperty<number | undefined, number | undefined>;
+declare function minMetadataKey(): AggregateMetadataKey<number | undefined, number | undefined>;
 /**
- * Creates an aggregate property that reduces its individual values by taking their max.
+ * Creates {@link AggregateMetadataKey} that reduces its individual values by taking their max.
  *
  * @experimental 21.0.0
  */
-declare function maxProperty(): AggregateProperty<number | undefined, number | undefined>;
+declare function maxMetadataKey(): AggregateMetadataKey<number | undefined, number | undefined>;
 /**
- * Creates an aggregate property that reduces its individual values by logically or-ing them.
+ * Creates an {@link AggregateMetadataKey} that reduces its individual values by logically or-ing
+ * them.
  *
  * @experimental 21.0.0
  */
-declare function orProperty(): AggregateProperty<boolean, boolean>;
+declare function orMetadataKey(): AggregateMetadataKey<boolean, boolean>;
 /**
- * Creates an aggregate property that reduces its individual values by logically and-ing them.
+ * Creates an {@link AggregateMetadataKey} that reduces its individual values by logically and-ing
+ * them.
  *
  * @experimental 21.0.0
  */
-declare function andProperty(): AggregateProperty<boolean, boolean>;
+declare function andMetadataKey(): AggregateMetadataKey<boolean, boolean>;
 /**
- * An aggregate property representing whether the field is required.
+ * An {@link AggregateMetadataKey} representing whether the field is required.
  *
  * @category validation
  * @experimental 21.0.0
  */
-declare const REQUIRED: AggregateProperty<boolean, boolean>;
+declare const REQUIRED: AggregateMetadataKey<boolean, boolean>;
 /**
- * An aggregate property representing the min value of the field.
+ * An {@link AggregateMetadataKey} representing the min value of the field.
  *
  * @category validation
  * @experimental 21.0.0
  */
-declare const MIN: AggregateProperty<number | undefined, number | undefined>;
+declare const MIN: AggregateMetadataKey<number | undefined, number | undefined>;
 /**
- * An aggregate property representing the max value of the field.
+ * An {@link AggregateMetadataKey} representing the max value of the field.
  *
  * @category validation
  * @experimental 21.0.0
  */
-declare const MAX: AggregateProperty<number | undefined, number | undefined>;
+declare const MAX: AggregateMetadataKey<number | undefined, number | undefined>;
 /**
- * An aggregate property representing the min length of the field.
+ * An {@link AggregateMetadataKey} representing the min length of the field.
  *
  * @category validation
  * @experimental 21.0.0
  */
-declare const MIN_LENGTH: AggregateProperty<number | undefined, number | undefined>;
+declare const MIN_LENGTH: AggregateMetadataKey<number | undefined, number | undefined>;
 /**
- * An aggregate property representing the max length of the field.
+ * An {@link AggregateMetadataKey} representing the max length of the field.
  *
  * @category validation
  * @experimental 21.0.0
  */
-declare const MAX_LENGTH: AggregateProperty<number | undefined, number | undefined>;
+declare const MAX_LENGTH: AggregateMetadataKey<number | undefined, number | undefined>;
 /**
- * An aggregate property representing the patterns the field must match.
+ * An {@link AggregateMetadataKey} representing the patterns the field must match.
  *
  * @category validation
  * @experimental 21.0.0
  */
-declare const PATTERN: AggregateProperty<RegExp[], RegExp | undefined>;
+declare const PATTERN: AggregateMetadataKey<RegExp[], RegExp | undefined>;
 
 /**
  * Options used to create a `ValidationError`.
@@ -339,7 +386,7 @@ declare function standardSchemaError(issue: StandardSchemaV1.Issue, options?: Va
  * @category validation
  * @experimental 21.0.0
  */
-declare function customError<E extends Partial<ValidationError>>(obj: WithField<E>): CustomValidationError;
+declare function customError<E extends Partial<ValidationErrorWithField>>(obj: WithField<E>): CustomValidationError;
 /**
  * Create a custom error
  * @param obj The object to create an error from
@@ -347,11 +394,14 @@ declare function customError<E extends Partial<ValidationError>>(obj: WithField<
  * @category validation
  * @experimental 21.0.0
  */
-declare function customError<E extends Partial<ValidationError>>(obj?: E): WithoutField<CustomValidationError>;
+declare function customError<E extends Partial<ValidationErrorWithField>>(obj?: E): WithoutField<CustomValidationError>;
 /**
  * Common interface for all validation errors.
  *
- * Use the creation functions to create an instance (e.g. `requiredError`, `minError`, etc.).
+ * This can be returned from validators.
+ *
+ * It's also used by the creation functions to create an instance
+ * (e.g. `requiredError`, `minError`, etc.).
  *
  * @category validation
  * @experimental 21.0.0
@@ -359,11 +409,38 @@ declare function customError<E extends Partial<ValidationError>>(obj?: E): Witho
 interface ValidationError {
     /** 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;
 }
+/**
+ * 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 ValidationErrorWithField 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 ValidationErrorWithOptionalField 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 ValidationErrorWithoutField extends ValidationError {
+    /** The field associated with this error. */
+    readonly field?: never;
+}
 /**
  * A custom error that may contain additional properties
  *
@@ -518,15 +595,6 @@ type NgValidationError = RequiredValidationError | MinValidationError | MaxValid
  * Symbol used to retain generic type information when it would otherwise be lost.
  */
 declare const ɵɵTYPE: unique symbol;
-/**
- * Creates a type based on the given type T, but with all readonly properties made writable.
- * @template T The type to create a mutable version of.
- *
- * @experimental 21.0.0
- */
-type Mutable<T> = {
-    -readonly [P in keyof T]: T[P];
-};
 /**
  * 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).
@@ -591,21 +659,6 @@ interface DisabledReason {
  * @experimental 21.0.0
  */
 type ValidationSuccess = null | undefined | void;
-/**
- * The result of running a field validation function.
- *
- * 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 list of {@link ValidationError} without fields to indicate multiple errors on the field
- *    being validated.
- *
- * @template E the type of error (defaults to {@link ValidationError}).
- *
- * @category types
- * @experimental 21.0.0
- */
-type FieldValidationResult<E extends ValidationError = ValidationError> = ValidationSuccess | OneOrMany<WithoutField<E>>;
 /**
  * The result of running a tree validation function.
  *
@@ -620,7 +673,7 @@ type FieldValidationResult<E extends ValidationError = ValidationError> = Valida
  * @category types
  * @experimental 21.0.0
  */
-type TreeValidationResult<E extends ValidationError = ValidationError> = ValidationSuccess | OneOrMany<WithOptionalField<E>>;
+type TreeValidationResult<E extends ValidationErrorWithOptionalField = ValidationErrorWithOptionalField> = ValidationSuccess | OneOrMany<E>;
 /**
  * A validation result where all errors explicitly define their target field.
  *
@@ -719,11 +772,11 @@ interface FieldState<TValue, TKey extends string | number = string | number> ext
      */
     readonly hidden: Signal<boolean>;
     readonly disabledReasons: Signal<readonly DisabledReason[]>;
-    readonly errors: Signal<ValidationError[]>;
+    readonly errors: Signal<ValidationErrorWithField[]>;
     /**
      * A signal containing the {@link errors} of the field and its descendants.
      */
-    readonly errorSummary: Signal<ValidationError[]>;
+    readonly errorSummary: Signal<ValidationErrorWithField[]>;
     /**
      * A signal indicating whether the field's value is currently valid.
      *
@@ -766,19 +819,19 @@ interface FieldState<TValue, TKey extends string | number = string | number> ext
      */
     readonly fieldBindings: Signal<readonly Field<unknown>[]>;
     /**
-     * Reads an aggregate property value from the field.
-     * @param prop The property to read.
+     * Reads an aggregate metadata value from the field.
+     * @param key The metadata key to read.
      */
-    property<M>(prop: AggregateProperty<M, any>): Signal<M>;
+    metadata<M>(key: AggregateMetadataKey<M, any>): Signal<M>;
     /**
-     * Reads a property value from the field.
-     * @param prop The property key to read.
+     * Reads a metadata value from the field.
+     * @param key The metadata key to read.
      */
-    property<M>(prop: Property<M>): M | undefined;
+    metadata<M>(key: MetadataKey<M>): M | undefined;
     /**
      * Checks whether the given metadata key has been defined for this field.
      */
-    hasProperty(key: Property<any> | AggregateProperty<any, any>): boolean;
+    hasMetadata(key: MetadataKey<any> | AggregateMetadataKey<any, any>): boolean;
     /**
      * Resets the {@link touched} and {@link dirty} state of the field and its descendants.
      *
@@ -868,7 +921,7 @@ type LogicFn<TValue, TReturn, TPathKind extends PathKind = PathKind.Root> = (ctx
  * @category validation
  * @experimental 21.0.0
  */
-type FieldValidator<TValue, TPathKind extends PathKind = PathKind.Root> = LogicFn<TValue, FieldValidationResult, TPathKind>;
+type FieldValidator<TValue, TPathKind extends PathKind = PathKind.Root> = LogicFn<TValue, ValidationResult<ValidationErrorWithoutField>, TPathKind>;
 /**
  * A function that takes the `FieldContext` for the field being validated and returns a
  * `TreeValidationResult` indicating errors for the field and its sub-fields.
@@ -985,6 +1038,11 @@ interface AsyncValidatorOptions<TValue, TParams, TResult, TPathKind extends Path
      * @returns A reference to the constructed resource.
      */
     readonly factory: (params: Signal<TParams | undefined>) => ResourceRef<TResult | undefined>;
+    /**
+     * A function to handle errors thrown by httpResource (HTTP errors, network errors, etc.).
+     * Receives the error and the field context, returns a list of validation errors.
+     */
+    readonly onError: (error: unknown, ctx: FieldContext<TValue, TPathKind>) => TreeValidationResult;
     /**
      * A function that takes the resource result, and the current field context and maps it to a list
      * of validation errors.
@@ -996,7 +1054,7 @@ interface AsyncValidatorOptions<TValue, TParams, TResult, TPathKind extends Path
      *   A targeted error will show up as an error on its target field rather than the field being validated.
      *   If a field is not given, the error is assumed to apply to the field being validated.
      */
-    readonly errors: MapToErrorsFn<TValue, TResult, TPathKind>;
+    readonly onSuccess: MapToErrorsFn<TValue, TResult, TPathKind>;
 }
 /**
  * Options that indicate how to create an httpResource for async validation for a field,
@@ -1029,7 +1087,12 @@ interface HttpValidatorOptions<TValue, TResult, TPathKind extends PathKind = Pat
      *   A targeted error will show up as an error on its target field rather than the field being validated.
      *   If a field is not given, the error is assumed to apply to the field being validated.
      */
-    readonly errors: MapToErrorsFn<TValue, TResult, TPathKind>;
+    readonly onSuccess: MapToErrorsFn<TValue, TResult, TPathKind>;
+    /**
+     * A function to handle errors thrown by httpResource (HTTP errors, network errors, etc.).
+     * Receives the error and the field context, returns a list of validation errors.
+     */
+    readonly onError: (error: unknown, ctx: FieldContext<TValue, TPathKind>) => TreeValidationResult;
     /**
      * The options to use when creating the httpResource.
      */
@@ -1278,44 +1341,44 @@ declare function validate<TValue, TPathKind extends PathKind = PathKind.Root>(pa
  */
 declare function validateTree<TValue, TPathKind extends PathKind = PathKind.Root>(path: FieldPath<TValue, TPathKind>, logic: NoInfer<TreeValidator<TValue, TPathKind>>): void;
 /**
- * Adds a value to an `AggregateProperty` of a field.
+ * Adds a value to an {@link AggregateMetadataKey} of a field.
  *
- * @param path The target path to set the aggregate property on.
- * @param prop The aggregate property
- * @param logic A function that receives the `FieldContext` and returns a value to add to the aggregate property.
+ * @param path The target path to set the aggregate metadata on.
+ * @param key The aggregate metadata key
+ * @param logic A function that receives the `FieldContext` and returns a value to add to the aggregate metadata.
  * @template TValue The type of value stored in the field the logic is bound to.
- * @template TPropItem The type of value the property aggregates over.
+ * @template TMetadataItem The type of value the metadata aggregates over.
  * @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 function aggregateProperty<TValue, TPropItem, TPathKind extends PathKind = PathKind.Root>(path: FieldPath<TValue, TPathKind>, prop: AggregateProperty<any, TPropItem>, logic: NoInfer<LogicFn<TValue, TPropItem, TPathKind>>): void;
+declare function aggregateMetadata<TValue, TMetadataItem, TPathKind extends PathKind = PathKind.Root>(path: FieldPath<TValue, TPathKind>, key: AggregateMetadataKey<any, TMetadataItem>, logic: NoInfer<LogicFn<TValue, TMetadataItem, TPathKind>>): void;
 /**
- * Creates a new `Property` and defines the value of the new property for the given field.
+ * Creates a new {@link MetadataKey} and defines the value of the new metadata key for the given field.
  *
- * @param path The path to define the property for.
- * @param factory A factory function that creates the value for the property.
+ * @param path The path to define the metadata for.
+ * @param factory A factory function that creates the value for the metadata.
  *   This function is **not** reactive. It is run once when the field is created.
- * @returns The newly created property
+ * @returns The newly created metadata key
  *
  * @category logic
  * @experimental 21.0.0
  */
-declare function property<TValue, TData, TPathKind extends PathKind = PathKind.Root>(path: FieldPath<TValue, TPathKind>, factory: (ctx: FieldContext<TValue, TPathKind>) => TData): Property<TData>;
+declare function metadata<TValue, TData, TPathKind extends PathKind = PathKind.Root>(path: FieldPath<TValue, TPathKind>, factory: (ctx: FieldContext<TValue, TPathKind>) => TData): MetadataKey<TData>;
 /**
- * Defines the value of a `Property` for a given field.
+ * Defines the value of a {@link MetadataKey} for a given field.
  *
- * @param path The path to define the property for.
- * @param prop  The property to define.
- * @param factory A factory function that creates the value for the property.
+ * @param path The path to define the metadata for.
+ * @param key  The metadata key to define.
+ * @param factory A factory function that creates the value for the metadata.
  *   This function is **not** reactive. It is run once when the field is created.
- * @returns The given property
+ * @returns The given metadata key
  *
  * @category logic
  * @experimental 21.0.0
  */
-declare function property<TValue, TData, TPathKind extends PathKind = PathKind.Root>(path: FieldPath<TValue, TPathKind>, prop: Property<TData>, factory: (ctx: FieldContext<TValue, TPathKind>) => TData): Property<TData>;
+declare function metadata<TValue, TData, TPathKind extends PathKind = PathKind.Root>(path: FieldPath<TValue, TPathKind>, key: MetadataKey<TData>, factory: (ctx: FieldContext<TValue, TPathKind>) => TData): MetadataKey<TData>;
 
 /** Represents a result that should be ignored because its predicate indicates it is not active. */
 declare const IGNORED: unique symbol;
@@ -1429,46 +1492,46 @@ declare class LogicContainer {
     /** Logic that determines if the field is read-only. */
     readonly readonly: BooleanOrLogic;
     /** Logic that produces synchronous validation errors for the field. */
-    readonly syncErrors: ArrayMergeIgnoreLogic<ValidationError, null>;
+    readonly syncErrors: ArrayMergeIgnoreLogic<ValidationErrorWithField, null>;
     /** Logic that produces synchronous validation errors for the field's subtree. */
-    readonly syncTreeErrors: ArrayMergeIgnoreLogic<ValidationError, null>;
+    readonly syncTreeErrors: ArrayMergeIgnoreLogic<ValidationErrorWithField, null>;
     /** Logic that produces asynchronous validation results (errors or 'pending'). */
-    readonly asyncErrors: ArrayMergeIgnoreLogic<ValidationError | 'pending', null>;
-    /** A map of aggregate properties to the `AbstractLogic` instances that compute their values. */
-    private readonly aggregateProperties;
-    /** A map of property keys to the factory functions that create their values. */
-    private readonly propertyFactories;
+    readonly asyncErrors: ArrayMergeIgnoreLogic<ValidationErrorWithField | '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;
     /**
      * 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 property. */
-    hasAggregateProperty(prop: AggregateProperty<unknown, unknown>): boolean;
+    /** Checks whether there is logic for the given aggregate metadata key. */
+    hasAggregateMetadata(key: AggregateMetadataKey<any, any>): boolean;
     /**
-     * Gets an iterable of [aggregate property, logic function] pairs.
-     * @returns An iterable of aggregate property entries.
+     * Gets an iterable of [aggregate metadata, logic function] pairs.
+     * @returns An iterable of aggregate metadata entries.
      */
-    getAggregatePropertyEntries(): MapIterator<[AggregateProperty<unknown, unknown>, AbstractLogic<unknown, unknown>]>;
+    getAggregateMetadataEntries(): MapIterator<[AggregateMetadataKey<unknown, unknown>, AbstractLogic<unknown, unknown>]>;
     /**
-     * Gets an iterable of [property, value factory function] pairs.
-     * @returns An iterable of property factory entries.
+     * Gets an iterable of [metadata, value factory function] pairs.
+     * @returns An iterable of metadata factory entries.
      */
-    getPropertyFactoryEntries(): MapIterator<[Property<unknown>, (ctx: FieldContext<unknown>) => unknown]>;
+    getMetadataFactoryEntries(): MapIterator<[MetadataKey<unknown>, (ctx: FieldContext<unknown>) => unknown]>;
     /**
-     * Retrieves or creates the `AbstractLogic` for a given aggregate property.
-     * @param prop The `AggregateProperty` for which to get the logic.
+     * Retrieves or creates the `AbstractLogic` for a given aggregate metadata key.
+     * @param key The `AggregateMetadataKey` for which to get the logic.
      * @returns The `AbstractLogic` associated with the key.
      */
-    getAggregateProperty<T>(prop: AggregateProperty<unknown, T>): AbstractLogic<T>;
+    getAggregateMetadata<T>(key: AggregateMetadataKey<unknown, T>): AbstractLogic<T>;
     /**
-     * Adds a factory function for a given property.
-     * @param prop The `Property` to associate the factory with.
+     * 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.
      */
-    addPropertyFactory(prop: Property<unknown>, factory: (ctx: FieldContext<unknown>) => unknown): void;
+    addMetadataFactory(key: MetadataKey<unknown>, factory: (ctx: FieldContext<unknown>) => unknown): void;
     /**
      * Merges logic from another `Logic` instance into this one.
      * @param other The `Logic` instance to merge from.
@@ -1500,10 +1563,10 @@ 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 an aggregate property for a field. */
-    abstract addAggregatePropertyRule<M>(key: AggregateProperty<unknown, M>, logic: LogicFn<any, M>): 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 addPropertyFactory<D>(key: Property<D>, factory: (ctx: FieldContext<any>) => D): void;
+    abstract addMetadataFactory<D>(key: MetadataKey<D>, factory: (ctx: FieldContext<any>) => D): void;
     /**
      * Gets a builder for a child node associated with the given property key.
      * @param key The property key of the child.
@@ -1546,11 +1609,11 @@ declare class LogicNodeBuilder extends AbstractLogicNodeBuilder {
     addHiddenRule(logic: LogicFn<any, boolean>): void;
     addDisabledReasonRule(logic: LogicFn<any, DisabledReason | undefined>): void;
     addReadonlyRule(logic: LogicFn<any, boolean>): void;
-    addSyncErrorRule(logic: LogicFn<any, ValidationResult>): void;
-    addSyncTreeErrorRule(logic: LogicFn<any, ValidationResult>): void;
-    addAsyncErrorRule(logic: LogicFn<any, AsyncValidationResult>): void;
-    addAggregatePropertyRule<T>(key: AggregateProperty<unknown, T>, logic: LogicFn<any, T>): void;
-    addPropertyFactory<D>(key: Property<D>, factory: (ctx: FieldContext<any>) => D): void;
+    addSyncErrorRule(logic: LogicFn<any, ValidationResult<ValidationErrorWithField>>): void;
+    addSyncTreeErrorRule(logic: LogicFn<any, ValidationResult<ValidationErrorWithField>>): void;
+    addAsyncErrorRule(logic: LogicFn<any, AsyncValidationResult<ValidationErrorWithField>>): void;
+    addAggregateMetadataRule<T>(key: AggregateMetadataKey<unknown, T>, logic: LogicFn<any, T>): void;
+    addMetadataFactory<D>(key: MetadataKey<D>, factory: (ctx: FieldContext<any>) => D): void;
     getChild(key: PropertyKey): LogicNodeBuilder;
     hasLogic(builder: AbstractLogicNodeBuilder): boolean;
     /**
@@ -1628,8 +1691,10 @@ declare class SchemaImpl {
 declare class FieldPathNode {
     /** The property keys used to navigate from the root path to this path. */
     readonly keys: PropertyKey[];
-    /** The logic builder used to accumulate logic on this path node. */
-    readonly logic: LogicNodeBuilder;
+    /** The parent of this path node. */
+    private readonly parent;
+    /** The key of this node in its parent. */
+    private readonly keyInParent;
     /** The root path node from which this path node is descended. */
     readonly root: FieldPathNode;
     /**
@@ -1641,11 +1706,20 @@ declare class FieldPathNode {
      * A proxy that wraps the path node, allowing navigation to its child paths via property access.
      */
     readonly fieldPathProxy: FieldPath<any>;
+    /**
+     * For a root path node this will contain the root logic builder. For non-root nodes,
+     * they determine their logic builder from their parent so this is undefined.
+     */
+    private readonly logicBuilder;
     protected constructor(
     /** The property keys used to navigate from the root path to this path. */
-    keys: PropertyKey[], 
+    keys: PropertyKey[], root: FieldPathNode | undefined, 
+    /** The parent of this path node. */
+    parent: FieldPathNode | undefined, 
+    /** The key of this node in its parent. */
+    keyInParent: PropertyKey | undefined);
     /** The logic builder used to accumulate logic on this path node. */
-    logic: LogicNodeBuilder, root: FieldPathNode);
+    get builder(): LogicNodeBuilder;
     /**
      * Gets the special path node containing the per-element logic that applies to *all* children paths.
      */
@@ -1668,21 +1742,17 @@ declare class FieldPathNode {
 }
 
 /**
- * Tracks custom properties associated with a `FieldNode`.
+ * Tracks custom metadata associated with a `FieldNode`.
  */
-declare class FieldPropertyState {
+declare class FieldMetadataState {
     private readonly node;
-    /** A map of all `Property` and `AggregateProperty` that have been defined for this field. */
-    private readonly properties;
+    /** A map of all `MetadataKey` and `AggregateMetadataKey` that have been defined for this field. */
+    private readonly metadata;
     constructor(node: FieldNode);
-    /** Gets the value of a `Property` or `AggregateProperty` for the field. */
-    get<T>(prop: Property<T> | AggregateProperty<T, unknown>): T | undefined | Signal<T>;
-    /**
-     * Checks whether the current property state has the given property.
-     * @param prop
-     * @returns
-     */
-    has(prop: Property<unknown> | AggregateProperty<unknown, unknown>): boolean;
+    /** Gets the value of a `MetadataKey` or `AggregateMetadataKey` for the field. */
+    get<T>(key: MetadataKey<T> | AggregateMetadataKey<T, unknown>): T | undefined | Signal<T>;
+    /** Checks whether the current metadata state has the given metadata key. */
+    has(key: MetadataKey<any> | AggregateMetadataKey<any, any>): boolean;
 }
 
 /**
@@ -1793,7 +1863,7 @@ declare class FieldSubmitState {
      */
     readonly selfSubmitting: WritableSignal<boolean>;
     /** Server errors that are associated with this field. */
-    readonly serverErrors: WritableSignal<readonly ValidationError[]>;
+    readonly serverErrors: WritableSignal<readonly ValidationErrorWithField[]>;
     constructor(node: FieldNode);
     /**
      * Whether this form is currently in the process of being submitted.
@@ -1807,14 +1877,14 @@ interface ValidationState {
      * The full set of synchronous tree errors visible to this field. This includes ones that are
      * targeted at a descendant field rather than at this field.
      */
-    rawSyncTreeErrors: Signal<ValidationError[]>;
+    rawSyncTreeErrors: Signal<ValidationErrorWithField[]>;
     /**
      * The full set of synchronous errors for this field, including synchronous tree errors and server
      * errors. Server errors are considered "synchronous" because they are imperatively added. From
      * the perspective of the field state they are either there or not, they are never in a pending
      * state.
      */
-    syncErrors: Signal<ValidationError[]>;
+    syncErrors: Signal<ValidationErrorWithField[]>;
     /**
      * Whether the field is considered valid according solely to its synchronous validators.
      * Errors resulting from a previous submit attempt are also considered for this state.
@@ -1825,21 +1895,21 @@ interface ValidationState {
      * targeted at a descendant field rather than at this field, as well as sentinel 'pending' values
      * indicating that the validator is still running and an error could still occur.
      */
-    rawAsyncErrors: Signal<(ValidationError | 'pending')[]>;
+    rawAsyncErrors: Signal<(ValidationErrorWithField | 'pending')[]>;
     /**
      * The asynchronous tree errors visible to this field that are specifically targeted at this field
      * rather than a descendant. This also includes all 'pending' sentinel values, since those could
      * theoretically result in errors for this field.
      */
-    asyncErrors: Signal<(ValidationError | 'pending')[]>;
+    asyncErrors: Signal<(ValidationErrorWithField | 'pending')[]>;
     /**
      * The combined set of all errors that currently apply to this field.
      */
-    errors: Signal<ValidationError[]>;
+    errors: Signal<ValidationErrorWithField[]>;
     /**
      * The combined set of all errors that currently apply to this field and its descendants.
      */
-    errorSummary: Signal<ValidationError[]>;
+    errorSummary: Signal<ValidationErrorWithField[]>;
     /**
      * Whether this field has any asynchronous validators still pending.
      */
@@ -1907,7 +1977,7 @@ interface ValidationState {
 declare class FieldNode implements FieldState<unknown> {
     readonly structure: FieldNodeStructure;
     readonly validationState: ValidationState;
-    readonly propertyState: FieldPropertyState;
+    readonly metadataState: FieldMetadataState;
     readonly nodeState: FieldNodeState;
     readonly submitState: FieldSubmitState;
     private _context;
@@ -1921,8 +1991,8 @@ declare class FieldNode implements FieldState<unknown> {
     get logicNode(): LogicNode;
     get value(): WritableSignal<unknown>;
     get keyInParent(): Signal<string | number>;
-    get errors(): Signal<ValidationError[]>;
-    get errorSummary(): Signal<ValidationError[]>;
+    get errors(): Signal<ValidationErrorWithField[]>;
+    get errorSummary(): Signal<ValidationErrorWithField[]>;
     get pending(): Signal<boolean>;
     get valid(): Signal<boolean>;
     get invalid(): Signal<boolean>;
@@ -1935,15 +2005,16 @@ declare class FieldNode implements FieldState<unknown> {
     get fieldBindings(): Signal<readonly Field<unknown>[]>;
     get submitting(): Signal<boolean>;
     get name(): Signal<string>;
-    get max(): Signal<number | undefined>;
-    get maxLength(): Signal<number | undefined>;
-    get min(): Signal<number | undefined>;
-    get minLength(): Signal<number | undefined>;
-    get pattern(): Signal<readonly RegExp[]>;
-    get required(): Signal<boolean>;
-    property<M>(prop: AggregateProperty<M, any>): Signal<M>;
-    property<M>(prop: Property<M>): M | undefined;
-    hasProperty(prop: Property<unknown> | AggregateProperty<unknown, any>): boolean;
+    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[]> | undefined;
+    get required(): Signal<boolean> | undefined;
+    metadata<M>(key: AggregateMetadataKey<M, any>): Signal<M>;
+    metadata<M>(key: MetadataKey<M>): M | undefined;
+    hasMetadata(key: MetadataKey<any> | AggregateMetadataKey<any, any>): boolean;
     /**
      * Marks this specific field as touched.
      */
@@ -2485,7 +2556,7 @@ type BaseValidatorConfig<TValue, TPathKind extends PathKind = PathKind.Root> = {
      * Custom validation error(s) to report instead of the default,
      * or a function that receives the `FieldContext` and returns custom validation error(s).
      */
-    error?: OneOrMany<WithoutField<ValidationError>> | LogicFn<TValue, OneOrMany<WithoutField<ValidationError>>, TPathKind>;
+    error?: OneOrMany<ValidationError> | LogicFn<TValue, OneOrMany<ValidationError>, TPathKind>;
     message?: never;
 };
 
@@ -2650,5 +2721,5 @@ type IgnoreUnknownProperties<T> = T extends Record<PropertyKey, unknown> ? {
  */
 declare function validateStandardSchema<TSchema, TValue extends IgnoreUnknownProperties<TSchema>>(path: FieldPath<TValue>, schema: StandardSchemaV1<TSchema>): void;
 
-export { AggregateProperty, CustomValidationError, EmailValidationError, FIELD, Field, MAX, MAX_LENGTH, MIN, MIN_LENGTH, MaxLengthValidationError, MaxValidationError, MinLengthValidationError, MinValidationError, NgValidationError, PATTERN, PathKind, PatternValidationError, Property, REQUIRED, RequiredValidationError, StandardSchemaValidationError, aggregateProperty, andProperty, apply, applyEach, applyWhen, applyWhenValue, createProperty, customError, disabled, email, emailError, form, hidden, listProperty, max, maxError, maxLength, maxLengthError, maxProperty, min, minError, minLength, minLengthError, minProperty, orProperty, pattern, patternError, property, readonly, reducedProperty, required, requiredError, schema, standardSchemaError, submit, validate, validateAsync, validateHttp, validateStandardSchema, validateTree };
-export type { AsyncValidationResult, AsyncValidatorOptions, ChildFieldContext, DisabledReason, FieldContext, FieldPath, FieldState, FieldTree, FieldValidationResult, FieldValidator, FormCheckboxControl, FormOptions, FormUiControl, FormValueControl, HttpValidatorOptions, IgnoreUnknownProperties, ItemFieldContext, LogicFn, MapToErrorsFn, MaybeFieldPath, MaybeFieldTree, Mutable, OneOrMany, ReadonlyArrayLike, RemoveStringIndexUnknownKey, RootFieldContext, Schema, SchemaFn, SchemaOrSchemaFn, Subfields, SubmittedStatus, TreeValidationResult, TreeValidator, ValidationError, ValidationResult, ValidationSuccess, Validator, WithField, WithOptionalField, WithoutField };
+export { AggregateMetadataKey, CustomValidationError, EmailValidationError, FIELD, Field, MAX, MAX_LENGTH, MIN, MIN_LENGTH, MaxLengthValidationError, MaxValidationError, MetadataKey, MinLengthValidationError, MinValidationError, NgValidationError, PATTERN, PathKind, PatternValidationError, REQUIRED, RequiredValidationError, StandardSchemaValidationError, aggregateMetadata, andMetadataKey, apply, applyEach, applyWhen, applyWhenValue, createMetadataKey, customError, disabled, email, emailError, form, hidden, listMetadataKey, max, maxError, maxLength, maxLengthError, maxMetadataKey, metadata, min, minError, minLength, minLengthError, minMetadataKey, orMetadataKey, pattern, patternError, readonly, reducedMetadataKey, required, requiredError, schema, standardSchemaError, submit, validate, validateAsync, validateHttp, validateStandardSchema, validateTree };
+export type { AsyncValidationResult, AsyncValidatorOptions, ChildFieldContext, DisabledReason, FieldContext, FieldPath, FieldState, FieldTree, FieldValidator, FormCheckboxControl, FormOptions, FormUiControl, FormValueControl, HttpValidatorOptions, IgnoreUnknownProperties, ItemFieldContext, LogicFn, MapToErrorsFn, MaybeFieldPath, MaybeFieldTree, OneOrMany, ReadonlyArrayLike, RemoveStringIndexUnknownKey, RootFieldContext, Schema, SchemaFn, SchemaOrSchemaFn, Subfields, SubmittedStatus, TreeValidationResult, TreeValidator, ValidationError, ValidationErrorWithField, ValidationErrorWithOptionalField, ValidationErrorWithoutField, ValidationResult, ValidationSuccess, Validator, WithField, WithOptionalField, WithoutField };