feat(forms): add error summaries to fields

leonsenft · leonsenft · commit 3d9a89744a4b · 2025-08-08T17:07:26.000-07:00
Add an `errorSummary` signal to `FieldState` which contains all of the
validation errors of a field and its descendants. This can be used to
conveniently collect all form validation errors by reading it from the
root field.
diff --git a/goldens/public-api/forms/experimental/index.api.md b/goldens/public-api/forms/experimental/index.api.md
@@ -151,6 +151,7 @@ export interface FieldState<TValue, TKey extends string | number = string | numb
     readonly disabled: Signal<boolean>;
     readonly disabledReasons: Signal<readonly DisabledReason[]>;
     readonly errors: Signal<ValidationError[]>;
+    readonly errorSummary: Signal<ValidationError[]>;
     readonly hidden: Signal<boolean>;
     readonly invalid: Signal<boolean>;
     readonly keyInParent: Signal<TKey>;
diff --git a/packages/forms/experimental/src/api/types.ts b/packages/forms/experimental/src/api/types.ts
@@ -237,6 +237,10 @@ export interface FieldState<TValue, TKey extends string | number = string | numb
    * A signal containing the current errors for the field.
    */
   readonly errors: Signal<ValidationError[]>;
+  /**
+   * A signal containing the {@link errors} of the field and its descendants.
+   */
+  readonly errorSummary: Signal<ValidationError[]>;
   /**
    * A signal containing the current errors for the field.
    */
diff --git a/packages/forms/experimental/src/field/node.ts b/packages/forms/experimental/src/field/node.ts
@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import type {Signal, WritableSignal} from '@angular/core';
+import {computed, type Signal, type WritableSignal} from '@angular/core';
 import {AggregateProperty, Property} from '../api/property';
 import type {DisabledReason, Field, FieldContext, FieldState} from '../api/types';
 import type {ValidationError} from '../api/validation_errors';
@@ -26,6 +26,7 @@ import {
 } from './structure';
 import {FieldSubmitState} from './submit';
 import {FieldValidationState} from './validation';
+import {reduceChildren} from './util';
 
 /**
  * Internal node in the form tree for a given field.
@@ -109,6 +110,12 @@ export class FieldNode implements FieldState<unknown> {
     return this.validationState.errors;
   }
 
+  get errorSummary(): Signal<ValidationError[]> {
+    return computed(() =>
+      reduceChildren(this, this.errors(), (child, result) => [...result, ...child.errorSummary()]),
+    );
+  }
+
   get pending(): Signal<boolean> {
     return this.validationState.pending;
   }
diff --git a/packages/forms/experimental/test/node/field_node.spec.ts b/packages/forms/experimental/test/node/field_node.spec.ts
@@ -6,12 +6,13 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {computed, Injector, signal} from '@angular/core';
+import {computed, inject, InjectionToken, Injector, signal} from '@angular/core';
 import {TestBed} from '@angular/core/testing';
 import {
   apply,
   applyEach,
   applyWhen,
+  applyWhenValue,
   disabled,
   FieldPath,
   form,
@@ -761,6 +762,72 @@ describe('FieldNode', () => {
     });
   });
 
+  describe('errorSummary', () => {
+    it('should be empty', () => {
+      const data = signal({});
+      const f = form(data, {injector: TestBed.inject(Injector)});
+
+      expect(f().errorSummary()).toEqual([]);
+    });
+
+    it('should contain errors from current field', () => {
+      const data = signal('');
+      const f = form(
+        data,
+        (p) => {
+          required(p);
+        },
+        {injector: TestBed.inject(Injector)},
+      );
+
+      expect(f().errorSummary()).toEqual([ValidationError.required()]);
+    });
+
+    it('should contain errors from child fields', () => {
+      const name = signal({first: '', last: ''});
+      const f = form(
+        name,
+        (p) => {
+          required(p.first);
+          required(p.last);
+        },
+        {injector: TestBed.inject(Injector)},
+      );
+
+      expect(f().errorSummary()).toEqual([ValidationError.required(), ValidationError.required()]);
+    });
+
+    it('should accumulate errors of all descendants', () => {
+      const data = signal({
+        child: {
+          child: {},
+        },
+      });
+      const f = form(
+        data,
+        (p) => {
+          validate(p, () => ValidationError.custom({kind: 'root'}));
+          validate(p.child, () => ValidationError.custom({kind: 'child'}));
+          validate(p.child.child, () => ValidationError.custom({kind: 'grandchild'}));
+        },
+        {injector: TestBed.inject(Injector)},
+      );
+
+      expect(f.child.child().errorSummary()).toEqual([
+        ValidationError.custom({kind: 'grandchild'}),
+      ]);
+      expect(f.child().errorSummary()).toEqual([
+        ValidationError.custom({kind: 'child'}),
+        ValidationError.custom({kind: 'grandchild'}),
+      ]);
+      expect(f().errorSummary()).toEqual([
+        ValidationError.custom({kind: 'root'}),
+        ValidationError.custom({kind: 'child'}),
+        ValidationError.custom({kind: 'grandchild'}),
+      ]);
+    });
+  });
+
   describe('composition', () => {
     it('should apply schema to field', () => {
       interface Address {
