@angular/forms 21.1.0-next.4 → 21.1.0

package/types/signals.d.ts

@@ -1,155 +1,16 @@
 /**
- * @license Angular v21.1.0-next.4
- * (c) 2010-2025 Google LLC. https://angular.dev/
+ * @license Angular v21.1.0
+ * (c) 2010-2026 Google LLC. https://angular.dev/
  * License: MIT
  */
 
-import { InputSignal, InputSignalWithTransform, ModelSignal, OutputRef, Signal, ResourceRef } from '@angular/core';
-import { WithOptionalField, ValidationError, DisabledReason, PathKind, SchemaPath, SchemaPathRules, LogicFn, OneOrMany, SchemaPathTree, FieldValidator, FieldContext, TreeValidationResult, TreeValidator, Debouncer } from './_structure-chunk.js';
-export { AsyncValidationResult, ChildFieldContext, CompatFieldState, CompatSchemaPath, CustomValidationError, EmailValidationError, FIELD, Field, FieldState, FieldTree, FormOptions, ItemFieldContext, ItemType, MAX, MAX_LENGTH, MIN, MIN_LENGTH, MaxLengthValidationError, MaxValidationError, MaybeFieldTree, MaybeSchemaPathTree, MetadataKey, MetadataReducer, MetadataSetterType, MinLengthValidationError, MinValidationError, NgValidationError, PATTERN, PatternValidationError, REQUIRED, ReadonlyArrayLike, RequiredValidationError, RootFieldContext, Schema, SchemaFn, SchemaOrSchemaFn, SignalFormsConfig, StandardSchemaValidationError, Subfields, SubmittedStatus, ValidationResult, ValidationSuccess, Validator, WithField, WithoutField, apply, applyEach, applyWhen, applyWhenValue, createManagedMetadataKey, createMetadataKey, customError, emailError, form, maxError, maxLengthError, metadata, minError, minLengthError, patternError, provideSignalFormsConfig, requiredError, schema, standardSchemaError, submit } from './_structure-chunk.js';
+import { Signal, ResourceRef, InputSignal, InputSignalWithTransform, ModelSignal, OutputRef } from '@angular/core';
+import { PathKind, SchemaPath, SchemaPathRules, LogicFn, OneOrMany, ValidationError, SchemaPathTree, FieldValidator, FieldContext, TreeValidationResult, TreeValidator, WithOptionalField, DisabledReason, Debouncer } from './_structure-chunk.js';
+export { AsyncValidationResult, ChildFieldContext, CompatFieldState, CompatSchemaPath, EmailValidationError, FORM_FIELD, FieldState, FieldTree, FormField, FormOptions, ItemFieldContext, ItemType, MAX, MAX_LENGTH, MIN, MIN_LENGTH, MaxLengthValidationError, MaxValidationError, MaybeFieldTree, MaybeSchemaPathTree, MetadataKey, MetadataReducer, MetadataSetterType, MinLengthValidationError, MinValidationError, NgValidationError, PATTERN, PatternValidationError, REQUIRED, ReadonlyArrayLike, RequiredValidationError, RootFieldContext, Schema, SchemaFn, SchemaOrSchemaFn, SignalFormsConfig, StandardSchemaValidationError, Subfields, SubmittedStatus, ValidationResult, ValidationSuccess, Validator, WithField, WithoutField, apply, applyEach, applyWhen, applyWhenValue, createManagedMetadataKey, createMetadataKey, emailError, form, maxError, maxLengthError, metadata, minError, minLengthError, patternError, provideSignalFormsConfig, requiredError, schema, standardSchemaError, submit } from './_structure-chunk.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { HttpResourceRequest, HttpResourceOptions } from '@angular/common/http';
 import '@angular/forms';
 
-/**
- * The base set of properties shared by all form control contracts.
- *
- * @category control
- * @experimental 21.0.0
- */
-interface FormUiControl {
-    /**
-     * An input to receive the errors for the field. If implemented, the `Field` directive will
-     * automatically bind errors from the bound field to this input.
-     */
-    readonly errors?: InputSignal<readonly WithOptionalField<ValidationError>[]> | InputSignalWithTransform<readonly WithOptionalField<ValidationError>[], unknown>;
-    /**
-     * An input to receive the disabled status for the field. If implemented, the `Field` directive
-     * will automatically bind the disabled status from the bound field to this input.
-     */
-    readonly disabled?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
-    /**
-     * An input to receive the reasons for the disablement of the field. If implemented, the `Field`
-     * directive will automatically bind the disabled reason from the bound field to this input.
-     */
-    readonly disabledReasons?: InputSignal<readonly WithOptionalField<DisabledReason>[]> | InputSignalWithTransform<readonly WithOptionalField<DisabledReason>[], unknown>;
-    /**
-     * An input to receive the readonly status for the field. If implemented, the `Field` directive
-     * will automatically bind the readonly status from the bound field to this input.
-     */
-    readonly readonly?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
-    /**
-     * An input to receive the hidden status for the field. If implemented, the `Field` directive
-     * will automatically bind the hidden status from the bound field to this input.
-     */
-    readonly hidden?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
-    /**
-     * An input to receive the invalid status for the field. If implemented, the `Field` directive
-     * will automatically bind the invalid status from the bound field to this input.
-     */
-    readonly invalid?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
-    /**
-     * An input to receive the pending status for the field. If implemented, the `Field` directive
-     * will automatically bind the pending status from the bound field to this input.
-     */
-    readonly pending?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
-    /**
-     * An input to receive the touched status for the field. If implemented, the `Field` directive
-     * will automatically bind the touched status from the bound field to this input.
-     */
-    readonly touched?: ModelSignal<boolean> | InputSignal<boolean> | InputSignalWithTransform<boolean, unknown> | OutputRef<boolean>;
-    /**
-     * An input to receive the dirty status for the field. If implemented, the `Field` directive
-     * will automatically bind the dirty status from the bound field to this input.
-     */
-    readonly dirty?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
-    /**
-     * An input to receive the name for the field. If implemented, the `Field` directive will
-     * automatically bind the name from the bound field to this input.
-     */
-    readonly name?: InputSignal<string> | InputSignalWithTransform<string, unknown>;
-    /**
-     * An input to receive the required status for the field. If implemented, the `Field` directive
-     * will automatically bind the required status from the bound field to this input.
-     */
-    readonly required?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
-    /**
-     * An input to receive the min value for the field. If implemented, the `Field` directive will
-     * automatically bind the min value from the bound field to this input.
-     */
-    readonly min?: InputSignal<number | undefined> | InputSignalWithTransform<number | undefined, unknown>;
-    /**
-     * An input to receive the min length for the field. If implemented, the `Field` directive will
-     * automatically bind the min length from the bound field to this input.
-     */
-    readonly minLength?: InputSignal<number | undefined> | InputSignalWithTransform<number | undefined, unknown>;
-    /**
-     * An input to receive the max value for the field. If implemented, the `Field` directive will
-     * automatically bind the max value from the bound field to this input.
-     */
-    readonly max?: InputSignal<number | undefined> | InputSignalWithTransform<number | undefined, unknown>;
-    /**
-     * An input to receive the max length for the field. If implemented, the `Field` directive will
-     * automatically bind the max length from the bound field to this input.
-     */
-    readonly maxLength?: InputSignal<number | undefined> | InputSignalWithTransform<number | undefined, unknown>;
-    /**
-     * An input to receive the value patterns for the field. If implemented, the `Field` directive
-     * will automatically bind the value patterns from the bound field to this input.
-     */
-    readonly pattern?: InputSignal<readonly RegExp[]> | InputSignalWithTransform<readonly RegExp[], unknown>;
-}
-/**
- * A contract for a form control that edits a `FieldTree` of type `TValue`. Any component that
- * implements this contract can be used with the `Field` directive.
- *
- * Many of the properties declared on this contract are optional. They do not need to be
- * implemented, but if they are will be kept in sync with the field state of the field bound to the
- * `Field` directive.
- *
- * @template TValue The type of `FieldTree` that the implementing component can edit.
- *
- * @category control
- * @experimental 21.0.0
- */
-interface FormValueControl<TValue> extends FormUiControl {
-    /**
-     * The value is the only required property in this contract. A component that wants to integrate
-     * with the `Field` directive via this contract, *must* provide a `model()` that will be kept in
-     * sync with the value of the bound `FieldTree`.
-     */
-    readonly value: ModelSignal<TValue>;
-    /**
-     * The implementing component *must not* define a `checked` property. This is reserved for
-     * components that want to integrate with the `Field` directive as a checkbox.
-     */
-    readonly checked?: undefined;
-}
-/**
- * A contract for a form control that edits a boolean checkbox `FieldTree`. Any component that
- * implements this contract can be used with the `Field` directive.
- *
- * Many of the properties declared on this contract are optional. They do not need to be
- * implemented, but if they are will be kept in sync with the field state of the field bound to the
- * `Field` directive.
- *
- * @category control
- * @experimental 21.0.0
- */
-interface FormCheckboxControl extends FormUiControl {
-    /**
-     * The checked is the only required property in this contract. A component that wants to integrate
-     * with the `Field` directive, *must* provide a `model()` that will be kept in sync with the
-     * value of the bound `FieldTree`.
-     */
-    readonly checked: ModelSignal<boolean>;
-    /**
-     * The implementing component *must not* define a `value` property. This is reserved for
-     * components that want to integrate with the `Field` directive as a standard input.
-     */
-    readonly value?: undefined;
-}
-
 /**
  * Adds logic to a field to conditionally disable it. A disabled field does not contribute to the
  * validation, touched/dirty, or other state of its parent field.
@@ -231,6 +92,7 @@ type BaseValidatorConfig<TValue, TPathKind extends PathKind = PathKind.Root> = {
  *    or a function that receives the `FieldContext` and returns custom validation error(s).
  * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array)
  *
+ * @see [Signal Form Email Validation](guide/forms/signals/validation#email)
  * @category validation
  * @experimental 21.0.0
  */
@@ -249,6 +111,7 @@ declare function email<TPathKind extends PathKind = PathKind.Root>(path: SchemaP
  *    or a function that receives the `FieldContext` and returns custom validation error(s).
  * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array)
  *
+ * @see [Signal Form Max Validation](guide/forms/signals/validation#min-and-max)
  * @category validation
  * @experimental 21.0.0
  */
@@ -268,6 +131,7 @@ declare function max<TPathKind extends PathKind = PathKind.Root>(path: SchemaPat
  * @template TValue The type of value stored in the field the logic is bound to.
  * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array)
  *
+ * @see [Signal Form Max Length Validation](guide/forms/signals/validation#minlength-and-maxlength)
  * @category validation
  * @experimental 21.0.0
  */
@@ -286,6 +150,7 @@ declare function maxLength<TValue extends ValueWithLengthOrSize, TPathKind exten
  *    or a function that receives the `FieldContext` and returns custom validation error(s).
  * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array)
  *
+ * @see [Signal Form Min Validation](guide/forms/signals/validation#min-and-max)
  * @category validation
  * @experimental 21.0.0
  */
@@ -305,6 +170,7 @@ declare function min<TValue extends number | string | null, TPathKind extends Pa
  * @template TValue The type of value stored in the field the logic is bound to.
  * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array)
  *
+ * @see [Signal Form Min Length Validation](guide/forms/signals/validation#minlength-and-maxlength)
  * @category validation
  * @experimental 21.0.0
  */
@@ -322,6 +188,7 @@ declare function minLength<TValue extends ValueWithLengthOrSize, TPathKind exten
  *    or a function that receives the `FieldContext` and returns custom validation error(s).
  * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array)
  *
+ * @see [Signal Form Pattern Validation](guide/forms/signals/validation#pattern)
  * @category validation
  * @experimental 21.0.0
  */
@@ -341,6 +208,7 @@ declare function pattern<TPathKind extends PathKind = PathKind.Root>(path: Schem
  * @template TValue The type of value stored in the field the logic is bound to.
  * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array)
  *
+ * @see [Signal Form Required Validation](guide/forms/signals/validation#required)
  * @category validation
  * @experimental 21.0.0
  */
@@ -377,6 +245,7 @@ type IgnoreUnknownProperties<T> = T extends Record<PropertyKey, unknown> ? {
  *   or a partial of it.
  * @template TValue The type of value stored in the field being validated.
  *
+ * @see [Signal Form Schema Validation](guide/forms/signals/validation#integration-with-schema-validation-libraries)
  * @category validation
  * @experimental 21.0.0
  */
@@ -420,7 +289,7 @@ type MapToErrorsFn<TValue, TResult, TPathKind extends PathKind = PathKind.Root>
  * @template TParams The type of parameters to the resource.
  * @template TResult The type of result returned by the resource
  * @template TPathKind The kind of path being validated (a root path, child path, or item of an array)
- *
+ * @see [Signal Form Async Validation](guide/forms/signals/validation#async-validation)
  * @category validation
  * @experimental 21.0.0
  */
@@ -470,6 +339,7 @@ interface AsyncValidatorOptions<TValue, TParams, TResult, TPathKind extends Path
  * @template TResult The type of result returned by the resource
  * @template TPathKind The kind of path being validated (a root path, child path, or item of an array)
  *
+ * @see [Signal Form Async Validation](guide/forms/signals/validation#async-validation)
  * @category validation
  * @experimental 21.0.0
  */
@@ -527,6 +397,7 @@ interface HttpValidatorOptions<TValue, TResult, TPathKind extends PathKind = Pat
  * @template TResult The type of result returned by the httpResource
  * @template TPathKind The kind of path being validated (a root path, child path, or item of an array)
  *
+ * @see [Signal Form Async Validation](guide/forms/signals/validation#async-validation)
  * @category validation
  * @experimental 21.0.0
  */
@@ -546,6 +417,145 @@ declare function validateHttp<TValue, TResult = unknown, TPathKind extends PathK
  */
 declare function validateTree<TValue, TPathKind extends PathKind = PathKind.Root>(path: SchemaPath<TValue, SchemaPathRules.Supported, TPathKind>, logic: NoInfer<TreeValidator<TValue, TPathKind>>): void;
 
+/**
+ * The base set of properties shared by all form control contracts.
+ *
+ * @category control
+ * @experimental 21.0.0
+ */
+interface FormUiControl {
+    /**
+     * An input to receive the errors for the field. If implemented, the `Field` directive will
+     * automatically bind errors from the bound field to this input.
+     */
+    readonly errors?: InputSignal<readonly WithOptionalField<ValidationError>[]> | InputSignalWithTransform<readonly WithOptionalField<ValidationError>[], unknown>;
+    /**
+     * An input to receive the disabled status for the field. If implemented, the `Field` directive
+     * will automatically bind the disabled status from the bound field to this input.
+     */
+    readonly disabled?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
+    /**
+     * An input to receive the reasons for the disablement of the field. If implemented, the `Field`
+     * directive will automatically bind the disabled reason from the bound field to this input.
+     */
+    readonly disabledReasons?: InputSignal<readonly WithOptionalField<DisabledReason>[]> | InputSignalWithTransform<readonly WithOptionalField<DisabledReason>[], unknown>;
+    /**
+     * An input to receive the readonly status for the field. If implemented, the `Field` directive
+     * will automatically bind the readonly status from the bound field to this input.
+     */
+    readonly readonly?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
+    /**
+     * An input to receive the hidden status for the field. If implemented, the `Field` directive
+     * will automatically bind the hidden status from the bound field to this input.
+     */
+    readonly hidden?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
+    /**
+     * An input to receive the invalid status for the field. If implemented, the `Field` directive
+     * will automatically bind the invalid status from the bound field to this input.
+     */
+    readonly invalid?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
+    /**
+     * An input to receive the pending status for the field. If implemented, the `Field` directive
+     * will automatically bind the pending status from the bound field to this input.
+     */
+    readonly pending?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
+    /**
+     * An input to receive the touched status for the field. If implemented, the `Field` directive
+     * will automatically bind the touched status from the bound field to this input.
+     */
+    readonly touched?: ModelSignal<boolean> | InputSignal<boolean> | InputSignalWithTransform<boolean, unknown> | OutputRef<boolean>;
+    /**
+     * An input to receive the dirty status for the field. If implemented, the `Field` directive
+     * will automatically bind the dirty status from the bound field to this input.
+     */
+    readonly dirty?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
+    /**
+     * An input to receive the name for the field. If implemented, the `Field` directive will
+     * automatically bind the name from the bound field to this input.
+     */
+    readonly name?: InputSignal<string> | InputSignalWithTransform<string, unknown>;
+    /**
+     * An input to receive the required status for the field. If implemented, the `Field` directive
+     * will automatically bind the required status from the bound field to this input.
+     */
+    readonly required?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
+    /**
+     * An input to receive the min value for the field. If implemented, the `Field` directive will
+     * automatically bind the min value from the bound field to this input.
+     */
+    readonly min?: InputSignal<number | undefined> | InputSignalWithTransform<number | undefined, unknown>;
+    /**
+     * An input to receive the min length for the field. If implemented, the `Field` directive will
+     * automatically bind the min length from the bound field to this input.
+     */
+    readonly minLength?: InputSignal<number | undefined> | InputSignalWithTransform<number | undefined, unknown>;
+    /**
+     * An input to receive the max value for the field. If implemented, the `Field` directive will
+     * automatically bind the max value from the bound field to this input.
+     */
+    readonly max?: InputSignal<number | undefined> | InputSignalWithTransform<number | undefined, unknown>;
+    /**
+     * An input to receive the max length for the field. If implemented, the `Field` directive will
+     * automatically bind the max length from the bound field to this input.
+     */
+    readonly maxLength?: InputSignal<number | undefined> | InputSignalWithTransform<number | undefined, unknown>;
+    /**
+     * An input to receive the value patterns for the field. If implemented, the `Field` directive
+     * will automatically bind the value patterns from the bound field to this input.
+     */
+    readonly pattern?: InputSignal<readonly RegExp[]> | InputSignalWithTransform<readonly RegExp[], unknown>;
+}
+/**
+ * A contract for a form control that edits a `FieldTree` of type `TValue`. Any component that
+ * implements this contract can be used with the `Field` directive.
+ *
+ * Many of the properties declared on this contract are optional. They do not need to be
+ * implemented, but if they are will be kept in sync with the field state of the field bound to the
+ * `Field` directive.
+ *
+ * @template TValue The type of `FieldTree` that the implementing component can edit.
+ *
+ * @category control
+ * @experimental 21.0.0
+ */
+interface FormValueControl<TValue> extends FormUiControl {
+    /**
+     * The value is the only required property in this contract. A component that wants to integrate
+     * with the `Field` directive via this contract, *must* provide a `model()` that will be kept in
+     * sync with the value of the bound `FieldTree`.
+     */
+    readonly value: ModelSignal<TValue>;
+    /**
+     * The implementing component *must not* define a `checked` property. This is reserved for
+     * components that want to integrate with the `Field` directive as a checkbox.
+     */
+    readonly checked?: undefined;
+}
+/**
+ * A contract for a form control that edits a boolean checkbox `FieldTree`. Any component that
+ * implements this contract can be used with the `Field` directive.
+ *
+ * Many of the properties declared on this contract are optional. They do not need to be
+ * implemented, but if they are will be kept in sync with the field state of the field bound to the
+ * `Field` directive.
+ *
+ * @category control
+ * @experimental 21.0.0
+ */
+interface FormCheckboxControl extends FormUiControl {
+    /**
+     * The checked is the only required property in this contract. A component that wants to integrate
+     * with the `Field` directive, *must* provide a `model()` that will be kept in sync with the
+     * value of the bound `FieldTree`.
+     */
+    readonly checked: ModelSignal<boolean>;
+    /**
+     * The implementing component *must not* define a `value` property. This is reserved for
+     * components that want to integrate with the `Field` directive as a standard input.
+     */
+    readonly value?: undefined;
+}
+
 /**
  * Configures the frequency at which a form field is updated by UI events.
  *