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

package/types/forms.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Angular v21.2.0-next.1
+ * @license Angular v21.2.0-next.3
  * (c) 2010-2026 Google LLC. https://angular.dev/
  * License: MIT
  */

package/types/signals-compat.d.ts

@@ -1,12 +1,12 @@
 /**
- * @license Angular v21.2.0-next.1
+ * @license Angular v21.2.0-next.3
  * (c) 2010-2026 Google LLC. https://angular.dev/
  * License: MIT
  */
 
-import { WritableSignal } from '@angular/core';
-import { FormOptions, FieldTree, SchemaOrSchemaFn, ValidationError, SignalFormsConfig } from './_structure-chunk.js';
-import { AbstractControl } from '@angular/forms';
+import { WritableSignal, EventEmitter } from '@angular/core';
+import { FormOptions, FieldTree, SchemaOrSchemaFn, ValidationError, SignalFormsConfig, SchemaFn } from './_structure-chunk.js';
+import { AbstractControl, FormControlStatus, FormControlState } from '@angular/forms';
 import '@standard-schema/spec';
 
 /**
@@ -15,7 +15,7 @@ import '@standard-schema/spec';
  * @category interop
  * @experimental 21.0.0
  */
-type CompatFormOptions = Omit<FormOptions, 'adapter'>;
+type CompatFormOptions<TModel> = Omit<FormOptions<TModel>, 'adapter'>;
 /**
  * Creates a compatibility form wrapped around the given model data.
  *
@@ -78,7 +78,7 @@ declare function compatForm<TModel>(model: WritableSignal<TModel>): FieldTree<TM
  * @category interop
  * @experimental 21.0.0
  */
-declare function compatForm<TModel>(model: WritableSignal<TModel>, schemaOrOptions: SchemaOrSchemaFn<TModel> | CompatFormOptions): FieldTree<TModel>;
+declare function compatForm<TModel>(model: WritableSignal<TModel>, schemaOrOptions: SchemaOrSchemaFn<TModel> | CompatFormOptions<TModel>): FieldTree<TModel>;
 /**
  * Creates a compatibility form wrapped around the given model data.
  *
@@ -110,7 +110,7 @@ declare function compatForm<TModel>(model: WritableSignal<TModel>, schemaOrOptio
  * @category interop
  * @experimental 21.0.0
  */
-declare function compatForm<TModel>(model: WritableSignal<TModel>, schema: SchemaOrSchemaFn<TModel>, options: CompatFormOptions): FieldTree<TModel>;
+declare function compatForm<TModel>(model: WritableSignal<TModel>, schema: SchemaOrSchemaFn<TModel>, options: CompatFormOptions<TModel>): FieldTree<TModel>;
 
 /**
  * An error used for compat errors.
@@ -139,5 +139,128 @@ declare class CompatValidationError<T = unknown> implements ValidationError {
  */
 declare const NG_STATUS_CLASSES: SignalFormsConfig['classes'];
 
-export { CompatValidationError, NG_STATUS_CLASSES, compatForm };
+/** Options used to update the control value. */
+type ValueUpdateOptions = {
+    onlySelf?: boolean;
+    emitEvent?: boolean;
+    emitModelToViewChange?: boolean;
+    emitViewToModelChange?: boolean;
+};
+/**
+ * A `FormControl` that is backed by signal forms rules.
+ *
+ * This class provides a bridge between Signal Forms and Reactive Forms, allowing
+ * signal-based controls to be used within a standard `FormGroup` or `FormArray`.
+ *
+ * A control could be created using signal forms, and integrated with an existing FormGroup
+ * propagating all the statuses and validity.
+ *
+ * @usageNotes
+ *
+ * ### Basic usage
+ *
+ * ```angular-ts
+ * const form = new FormGroup({
+ *   // You can create SignalFormControl with signal form rules, and add it to a FormGroup.
+ *   name: new SignalFormControl('Alice', p => {
+ *     required(p);
+ *   }),
+ *   age: new FormControl(25),
+ * });
+ * ```
+ * In the template you can get the underlying `fieldTree` and bind it:
+ *
+ * ```angular-html
+ *  <form [formGroup]="form">
+ *    <input [formField]="nameControl.fieldTree" />
+ *    <input formControlName="age" />
+ *  </form>
+ * ```
+ *
+ * @experimental
+ */
+declare class SignalFormControl<T> extends AbstractControl {
+    /** Source FieldTree. */
+    readonly fieldTree: FieldTree<T>;
+    /** The raw signal driving the control value. */
+    readonly sourceValue: WritableSignal<T>;
+    private readonly fieldState;
+    private readonly initialValue;
+    private pendingParentNotifications;
+    private readonly onChangeCallbacks;
+    private readonly onDisabledChangeCallbacks;
+    readonly valueChanges: EventEmitter<T>;
+    readonly statusChanges: EventEmitter<FormControlStatus>;
+    constructor(value: T, schemaOrOptions?: SchemaFn<T> | FormOptions<T>, options?: FormOptions<T>);
+    /**
+     * Defines properties using closure-safe names to prevent issues with property renaming optimizations.
+     *
+     * AbstractControl have `value` and `errors` as readonly prop, which doesn't allow getters.
+     **/
+    private defineCompatProperties;
+    private emitControlEvent;
+    setValue(value: any, options?: ValueUpdateOptions): void;
+    patchValue(value: any, options?: ValueUpdateOptions): void;
+    private updateValue;
+    registerOnChange(fn: (value?: any, emitModelEvent?: boolean) => void): void;
+    registerOnDisabledChange(fn: (isDisabled: boolean) => void): void;
+    getRawValue(): T;
+    reset(value?: T | FormControlState<T>, options?: ValueUpdateOptions): void;
+    private scheduleParentUpdate;
+    private notifyParentUnlessPending;
+    private updateParentValueAndValidity;
+    private propagateToParent;
+    get status(): FormControlStatus;
+    get valid(): boolean;
+    get invalid(): boolean;
+    get pending(): boolean;
+    get disabled(): boolean;
+    get enabled(): boolean;
+    get dirty(): boolean;
+    set dirty(_: boolean);
+    get pristine(): boolean;
+    set pristine(_: boolean);
+    get touched(): boolean;
+    set touched(_: boolean);
+    get untouched(): boolean;
+    set untouched(_: boolean);
+    markAsTouched(opts?: {
+        onlySelf?: boolean;
+    }): void;
+    markAsDirty(opts?: {
+        onlySelf?: boolean;
+    }): void;
+    markAsPristine(opts?: {
+        onlySelf?: boolean;
+    }): void;
+    markAsUntouched(opts?: {
+        onlySelf?: boolean;
+    }): void;
+    updateValueAndValidity(_opts?: Object): void;
+    disable(_opts?: {
+        onlySelf?: boolean;
+        emitEvent?: boolean;
+    }): void;
+    enable(_opts?: {
+        onlySelf?: boolean;
+        emitEvent?: boolean;
+    }): void;
+    setValidators(_validators: any): void;
+    setAsyncValidators(_validators: any): void;
+    addValidators(_validators: any): void;
+    addAsyncValidators(_validators: any): void;
+    removeValidators(_validators: any): void;
+    removeAsyncValidators(_validators: any): void;
+    clearValidators(): void;
+    clearAsyncValidators(): void;
+    setErrors(_errors: any, _opts?: {
+        emitEvent?: boolean;
+    }): void;
+    markAsPending(_opts?: {
+        onlySelf?: boolean;
+        emitEvent?: boolean;
+    }): void;
+}
+
+export { CompatValidationError, NG_STATUS_CLASSES, SignalFormControl, compatForm };
 export type { CompatFormOptions };

package/types/signals.d.ts

@@ -1,15 +1,16 @@
 /**
- * @license Angular v21.2.0-next.1
+ * @license Angular v21.2.0-next.3
  * (c) 2010-2026 Google LLC. https://angular.dev/
  * License: MIT
  */
 
-import { Signal, ResourceRef, InputSignal, InputSignalWithTransform, ModelSignal, OutputRef } from '@angular/core';
-import { PathKind, SchemaPath, SchemaPathRules, LogicFn, OneOrMany, ValidationError, SchemaPathTree, FieldValidator, FieldContext, TreeValidationResult, TreeValidator, WithOptionalFieldTree, DisabledReason, Debouncer } from './_structure-chunk.js';
-export { AsyncValidationResult, ChildFieldContext, CompatFieldState, CompatSchemaPath, EmailValidationError, FORM_FIELD, FieldState, FieldTree, FormField, FormFieldBindingOptions, 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, ValidationResult, ValidationSuccess, Validator, WithField, WithFieldTree, WithOptionalField, WithoutField, WithoutFieldTree, 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 * as i0 from '@angular/core';
+import { Signal, ResourceRef, InputSignal, InputSignalWithTransform, ModelSignal, OutputRef, WritableSignal } from '@angular/core';
+import { PathKind, SchemaPath, SchemaPathRules, LogicFn, OneOrMany, ValidationError, FieldValidator, FieldContext, TreeValidationResult, TreeValidator, WithOptionalFieldTree, DisabledReason, Debouncer, FieldTree } from './_structure-chunk.js';
+export { AsyncValidationResult, BaseNgValidationError, ChildFieldContext, CompatFieldState, CompatSchemaPath, EmailValidationError, FORM_FIELD, FieldState, FormField, FormFieldBindingOptions, FormOptions, FormSubmitOptions, IgnoreUnknownProperties, ItemFieldContext, ItemType, MAX, MAX_LENGTH, MIN, MIN_LENGTH, MaxLengthValidationError, MaxValidationError, MaybeFieldTree, MaybeSchemaPathTree, MetadataKey, MetadataReducer, MetadataSetterType, MinLengthValidationError, MinValidationError, NgValidationError, PATTERN, PatternValidationError, REQUIRED, ReadonlyArrayLike, RemoveStringIndexUnknownKey, RequiredValidationError, RootFieldContext, Schema, SchemaFn, SchemaOrSchemaFn, SchemaPathTree, SignalFormsConfig, StandardSchemaValidationError, Subfields, ValidationErrorOptions, ValidationResult, ValidationSuccess, Validator, WithField, WithFieldTree, WithOptionalField, WithoutField, WithoutFieldTree, apply, applyEach, applyWhen, applyWhenValue, createManagedMetadataKey, createMetadataKey, emailError, form, maxError, maxLengthError, metadata, minError, minLengthError, patternError, provideSignalFormsConfig, requiredError, schema, standardSchemaError, submit, validateStandardSchema, ɵNgFieldDirective } from './_structure-chunk.js';
 import { HttpResourceRequest, HttpResourceOptions } from '@angular/common/http';
 import '@angular/forms';
+import '@standard-schema/spec';
 
 /**
  * Adds logic to a field to conditionally disable it. A disabled field does not contribute to the
@@ -216,41 +217,6 @@ declare function required<TValue, TPathKind extends PathKind = PathKind.Root>(pa
     when?: NoInfer<LogicFn<TValue, boolean, TPathKind>>;
 }): void;
 
-/**
- * Utility type that removes a string index key when its value is `unknown`,
- * i.e. `{[key: string]: unknown}`. It allows specific string keys to pass through, even if their
- * value is `unknown`, e.g. `{key: unknown}`.
- *
- * @experimental 21.0.0
- */
-type RemoveStringIndexUnknownKey<K, V> = string extends K ? unknown extends V ? never : K : K;
-/**
- * Utility type that recursively ignores unknown string index properties on the given object.
- * We use this on the `TSchema` type in `validateStandardSchema` in order to accommodate Zod's
- * `looseObject` which includes `{[key: string]: unknown}` as part of the type.
- *
- * @experimental 21.0.0
- */
-type IgnoreUnknownProperties<T> = T extends Record<PropertyKey, unknown> ? {
-    [K in keyof T as RemoveStringIndexUnknownKey<K, T[K]>]: IgnoreUnknownProperties<T[K]>;
-} : T;
-/**
- * Validates a field using a `StandardSchemaV1` compatible validator (e.g. a Zod validator).
- *
- * See https://github.com/standard-schema/standard-schema for more about standard schema.
- *
- * @param path The `FieldPath` to the field to validate.
- * @param schema The standard schema compatible validator to use for validation.
- * @template TSchema The type validated by the schema. This may be either the full `TValue` type,
- *   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
- */
-declare function validateStandardSchema<TSchema, TModel extends IgnoreUnknownProperties<TSchema>>(path: SchemaPath<TModel> & SchemaPathTree<TModel>, schema: StandardSchemaV1<TSchema>): void;
-
 /**
  * Adds logic to a field to determine if the field has validation errors.
  *
@@ -504,12 +470,6 @@ interface FormUiControl<TValue> {
      * will automatically bind the value patterns from the bound field to this input.
      */
     readonly pattern?: InputSignal<readonly RegExp[]> | InputSignalWithTransform<readonly RegExp[], unknown>;
-    /**
-     * A signal containing the current parse errors for the control.
-     * This allows the control to communicate to the form that there are additional validation errors
-     * beyond those produced by the schema, due to being unable to parse the user's input.
-     */
-    readonly parseErrors?: Signal<ValidationError.WithoutFieldTree[]>;
     /**
      * Focuses the UI control.
      *
@@ -583,5 +543,104 @@ interface FormCheckboxControl extends FormUiControl<boolean> {
  */
 declare function debounce<TValue, TPathKind extends PathKind = PathKind.Root>(path: SchemaPath<TValue, SchemaPathRules.Supported, TPathKind>, durationOrDebouncer: number | Debouncer<TValue, TPathKind>): void;
 
-export { Debouncer, DisabledReason, FieldContext, FieldValidator, LogicFn, OneOrMany, PathKind, SchemaPath, SchemaPathRules, SchemaPathTree, TreeValidationResult, TreeValidator, ValidationError, WithOptionalFieldTree, debounce, disabled, email, hidden, max, maxLength, min, minLength, pattern, readonly, required, validate, validateAsync, validateHttp, validateStandardSchema, validateTree };
-export type { AsyncValidatorOptions, FormCheckboxControl, FormUiControl, FormValueControl, HttpValidatorOptions, IgnoreUnknownProperties, MapToErrorsFn, RemoveStringIndexUnknownKey };
+/**
+ * Options for `transformedValue`.
+ *
+ * @experimental 21.2.0
+ */
+interface TransformedValueOptions<TValue, TRaw> {
+    /**
+     * Parse the raw value into the model value.
+     *
+     * Should return an object containing the parsed result, which may contain:
+     *   - `value`: The parsed model value. If `undefined`, the model will not be updated.
+     *   - `errors`: Any parse errors encountered. If `undefined`, no errors are reported.
+     */
+    parse: (rawValue: TRaw) => {
+        value?: TValue;
+        errors?: readonly ValidationError.WithoutFieldTree[];
+    };
+    /**
+     * Format the model value into the raw value.
+     */
+    format: (value: TValue) => TRaw;
+}
+/**
+ * A writable signal representing a "raw" UI value that is synchronized with a model signal
+ * via parse/format transformations.
+ *
+ * @category control
+ * @experimental 21.2.0
+ */
+interface TransformedValueSignal<TRaw> extends WritableSignal<TRaw> {
+    /**
+     * The current parse errors resulting from the last transformation.
+     */
+    readonly parseErrors: Signal<readonly ValidationError.WithoutFieldTree[]>;
+}
+/**
+ * Creates a writable signal representing a "raw" UI value that is transformed to/from a model
+ * value via `parse` and `format` functions.
+ *
+ * This utility simplifies the creation of custom form controls that parse a user-facing value
+ * representation into an underlying model value. For example, a numeric input that displays and
+ * accepts string values but stores a number.
+ *
+ * @param value The model signal to synchronize with.
+ * @param options Configuration including `parse` and `format` functions.
+ * @returns A `TransformedValueSignal` representing the raw value with parse error tracking.
+ * @experimental 21.2.0
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   selector: 'number-input',
+ *   template: `<input [value]="rawValue()" (input)="rawValue.set($event.target.value)" />`,
+ * })
+ * export class NumberInput implements FormValueControl<number | null> {
+ *   readonly value = model.required<number | null>();
+ *
+ *   protected readonly rawValue = transformedValue(this.value, {
+ *     parse: (val) => {
+ *       if (val === '') return {value: null};
+ *       const num = Number(val);
+ *       if (Number.isNaN(num)) {
+ *         return {errors: [{kind: 'parse', message: `${val} is not numeric`}]};
+ *       }
+ *       return {value: num};
+ *     },
+ *     format: (val) => val?.toString() ?? '',
+ *   });
+ * }
+ * ```
+ */
+declare function transformedValue<TValue, TRaw>(value: ModelSignal<TValue>, options: TransformedValueOptions<TValue, TRaw>): TransformedValueSignal<TRaw>;
+
+/**
+ * A directive that binds a `FieldTree` to a `<form>` element.
+ *
+ * It automatically:
+ * 1. Sets `novalidate` on the form element to disable browser validation.
+ * 2. Listens for the `submit` event, prevents the default behavior, and calls `submit()` on the
+ * `FieldTree`.
+ *
+ * @usageNotes
+ *
+ * ```html
+ * <form [formRoot]="myFieldTree">
+ *   ...
+ * </form>
+ * ```
+ *
+ * @publicApi
+ * @experimental 21.0.0
+ */
+declare class FormRoot<T> {
+    readonly fieldTree: i0.InputSignal<FieldTree<T>>;
+    protected onSubmit(event: Event): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FormRoot<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<FormRoot<any>, "form[formRoot]", never, { "fieldTree": { "alias": "formRoot"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { Debouncer, DisabledReason, FieldContext, FieldTree, FieldValidator, FormRoot, LogicFn, OneOrMany, PathKind, SchemaPath, SchemaPathRules, TreeValidationResult, TreeValidator, ValidationError, WithOptionalFieldTree, debounce, disabled, email, hidden, max, maxLength, min, minLength, pattern, readonly, required, transformedValue, validate, validateAsync, validateHttp, validateTree };
+export type { AsyncValidatorOptions, FormCheckboxControl, FormUiControl, FormValueControl, HttpValidatorOptions, MapToErrorsFn, TransformedValueOptions, TransformedValueSignal };