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

package/types/_structure-chunk.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Angular v21.1.0-next.3
+ * @license Angular v21.1.0-next.4
  * (c) 2010-2025 Google LLC. https://angular.dev/
  * License: MIT
  */
@@ -311,7 +311,7 @@ type SubmittedStatus = 'unsubmitted' | 'submitted' | 'submitting';
  */
 interface DisabledReason {
     /** The field that is disabled. */
-    readonly field: FieldTree<unknown>;
+    readonly fieldTree: FieldTree<unknown>;
     /** A user-facing message describing the reason for the disablement. */
     readonly message?: string;
 }
@@ -576,9 +576,42 @@ type SchemaPathTree<TModel, TPathKind extends PathKind = PathKind.Root> = ([TMod
  */
 type MaybeSchemaPathTree<TModel, TPathKind extends PathKind = PathKind.Root> = (TModel & undefined) | SchemaPathTree<Exclude<TModel, undefined>, TPathKind>;
 /**
- * Defines logic for a form.
+ * A reusable schema that defines behavior and rules for a form.
  *
- * @template TValue The type of data stored in the form that this schema is attached to.
+ * A `Schema` encapsulates form logic such as validation rules, disabled states, readonly states,
+ * and other field-level behaviors.
+ *
+ * Unlike raw {@link SchemaFn}, a `Schema` is created using
+ * the {@link schema} function and is cached per-form, even when applied to multiple fields.
+ *
+ * ### Creating a reusable schema
+ *
+ * ```typescript
+ * interface Address {
+ *   street: string;
+ *   city: string;
+ * }
+ *
+ * // Create a reusable schema for address fields
+ * const addressSchema = schema<Address>((p) => {
+ *   required(p.street);
+ *   required(p.city);
+ * });
+ *
+ * // Apply the schema to multiple forms
+ * const shippingForm = form(shippingModel, addressSchema, {injector});
+ * const billingForm = form(billingModel, addressSchema, {injector});
+ * ```
+ *
+ * ### Passing a schema to a form
+ *
+ * A schema can also be passed as a second argument to the {@link form} function.
+ *
+ * ```typescript
+ * readonly userForm = form(addressModel, addressSchema);
+ * ```
+ *
+ * @template TModel Data type.
  *
  * @category types
  * @experimental 21.0.0
@@ -587,9 +620,21 @@ type Schema<in TModel> = {
     [ɵɵTYPE]: SchemaFn<TModel, PathKind.Root>;
 };
 /**
- * Function that defines rules for a schema.
+ * A function that receives a {@link SchemaPathTree} and applies rules to fields.
  *
- * @template TModel The type of data stored in the form that this schema function is attached to.
+ * A `SchemaFn` can be passed directly to {@link form} or to the {@link schema} function to create a
+ * cached {@link Schema}.
+ *
+ * ```typescript
+ * const userFormSchema: SchemaFn<User> = (p) => {
+ *   required(p.name);
+ *   disabled(p.email, ({valueOf}) => valueOf(p.name) === '');
+ * };
+ *
+ * const f = form(userModel, userFormSchema, {injector});
+ * ```
+ *
+ * @template TModel Data type.
  * @template TPathKind The kind of path this schema function can be bound to.
  *
  * @category types
@@ -597,7 +642,7 @@ type Schema<in TModel> = {
  */
 type SchemaFn<TModel, TPathKind extends PathKind = PathKind.Root> = (p: SchemaPathTree<TModel, TPathKind>) => void;
 /**
- * A schema or schema definition function.
+ * A {@link Schema} or {@link SchemaFn}.
  *
  * @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.
@@ -671,7 +716,7 @@ interface RootFieldContext<TValue> {
     /** The state of the current field. */
     readonly state: FieldState<TValue>;
     /** The current field. */
-    readonly field: FieldTree<TValue>;
+    readonly fieldTree: 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. */
@@ -734,7 +779,7 @@ interface ValidationErrorOptions {
  * @experimental 21.0.0
  */
 type WithField<T> = T & {
-    field: FieldTree<unknown>;
+    fieldTree: FieldTree<unknown>;
 };
 /**
  * A type that allows the given type `T` to optionally have a `field` property.
@@ -742,8 +787,8 @@ type WithField<T> = T & {
  *
  * @experimental 21.0.0
  */
-type WithOptionalField<T> = Omit<T, 'field'> & {
-    field?: FieldTree<unknown>;
+type WithOptionalField<T> = Omit<T, 'fieldTree'> & {
+    fieldTree?: FieldTree<unknown>;
 };
 /**
  * A type that ensures the given type `T` does not have a `field` property.
@@ -752,7 +797,7 @@ type WithOptionalField<T> = Omit<T, 'field'> & {
  * @experimental 21.0.0
  */
 type WithoutField<T> = T & {
-    field: never;
+    fieldTree: never;
 };
 /**
  * Create a required error associated with the target field
@@ -935,7 +980,7 @@ declare namespace ValidationError {
      */
     interface WithField extends ValidationError {
         /** The field associated with this error. */
-        readonly field: FieldTree<unknown>;
+        readonly fieldTree: FieldTree<unknown>;
     }
     /**
      * Validation error with optional field.
@@ -945,7 +990,7 @@ declare namespace ValidationError {
      */
     interface WithOptionalField extends ValidationError {
         /** The field associated with this error. */
-        readonly field?: FieldTree<unknown>;
+        readonly fieldTree?: FieldTree<unknown>;
     }
     /**
      * Validation error with no field.
@@ -973,7 +1018,7 @@ declare class CustomValidationError implements ValidationError {
     /** Identifies the kind of error. */
     readonly kind: string;
     /** The field associated with this error. */
-    readonly field: FieldTree<unknown>;
+    readonly fieldTree: FieldTree<unknown>;
     /** Human readable error message. */
     readonly message?: string;
     constructor(options?: ValidationErrorOptions);
@@ -990,7 +1035,7 @@ declare abstract class _NgValidationError implements ValidationError {
     /** Identifies the kind of error. */
     readonly kind: string;
     /** The field associated with this error. */
-    readonly field: FieldTree<unknown>;
+    readonly fieldTree: FieldTree<unknown>;
     /** Human readable error message. */
     readonly message?: string;
     constructor(options?: ValidationErrorOptions);
@@ -1115,7 +1160,7 @@ type NgValidationError = RequiredValidationError | MinValidationError | MaxValid
 interface SignalFormsConfig {
     /** A map of CSS class names to predicate functions that determine when to apply them. */
     classes?: {
-        [className: string]: (state: FieldState<unknown>) => boolean;
+        [className: string]: (state: Field<unknown>) => boolean;
     };
 }
 /**

package/types/forms.d.ts

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

package/types/signals-compat.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Angular v21.1.0-next.3
+ * @license Angular v21.1.0-next.4
  * (c) 2010-2025 Google LLC. https://angular.dev/
  * License: MIT
  */
@@ -121,7 +121,7 @@ declare function compatForm<TModel>(model: WritableSignal<TModel>, schema: Schem
 declare class CompatValidationError<T = unknown> implements ValidationError {
     readonly kind: string;
     readonly control: AbstractControl;
-    readonly field: FieldTree<unknown>;
+    readonly fieldTree: FieldTree<unknown>;
     readonly context: T;
     readonly message?: string;
     constructor({ context, kind, control }: {

package/types/signals.d.ts

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