fix(forms): sort error summary by DOM order

mmalerba · web-flow · commit fb05fc86d0f1 · 2026-01-26T22:29:07.000Z
This will allow users to rely on the `errorSummary` order to implement
features like "focus next error"
diff --git a/packages/forms/signals/src/field/validation.ts b/packages/forms/signals/src/field/validation.ts
@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {computed, Signal, ɵWritable} from '@angular/core';
+import {computed, Signal, untracked, ɵWritable} from '@angular/core';
 import type {ValidationError} from '../api/rules/validation/validation_errors';
 import type {FieldTree, TreeValidationResult, ValidationResult} from '../api/types';
 import {isArray} from '../util/type_guards';
@@ -254,12 +254,17 @@ export class FieldValidationState implements ValidationState {
     ...this.asyncErrors().filter((err) => err !== 'pending'),
   ]);
 
-  readonly errorSummary = computed(() =>
-    this.node.structure.reduceChildren(this.errors(), (child, result) => [
+  readonly errorSummary = computed(() => {
+    const errors = this.node.structure.reduceChildren(this.errors(), (child, result) => [
       ...result,
       ...child.errorSummary(),
-    ]),
-  );
+    ]);
+    // Sort by DOM order on client-side only.
+    if (typeof ngServerMode === 'undefined' || !ngServerMode) {
+      untracked(() => errors.sort(compareErrorPosition));
+    }
+    return errors;
+  });
 
   /**
    * Whether this field has any asynchronous validators still pending.
@@ -382,3 +387,33 @@ export function addDefaultField<E extends ValidationError>(
   }
   return errors as ValidationResult<E & {fieldTree: FieldTree<unknown>}>;
 }
+
+function getFirstBoundElement(error: ValidationError.WithFieldTree) {
+  if (error.formField) return error.formField.element;
+  return error
+    .fieldTree()
+    .formFieldBindings()
+    .reduce<HTMLElement | undefined>((el: HTMLElement | undefined, binding) => {
+      if (!el || !binding.element) return el ?? binding.element;
+      return el.compareDocumentPosition(binding.element) & Node.DOCUMENT_POSITION_PRECEDING
+        ? binding.element
+        : el;
+    }, undefined);
+}
+
+/**
+ * Compares the position of two validation errors by the position of their corresponding field
+ * binding directive in the DOM.
+ * - For errors with multiple field bindings, the earliest one in the DOM will be used for comparison.
+ * - For errors that have no field bindings, they will be considered to come after all other errors.
+ */
+function compareErrorPosition(
+  a: ValidationError.WithFieldTree,
+  b: ValidationError.WithFieldTree,
+): number {
+  const aEl = getFirstBoundElement(a);
+  const bEl = getFirstBoundElement(b);
+  if (aEl === bEl) return 0;
+  if (aEl === undefined || bEl === undefined) return aEl === undefined ? 1 : -1;
+  return aEl.compareDocumentPosition(bEl) & Node.DOCUMENT_POSITION_PRECEDING ? 1 : -1;
+}
diff --git a/packages/forms/signals/test/node/field_node.spec.ts b/packages/forms/signals/test/node/field_node.spec.ts
@@ -6,14 +6,15 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {computed, effect, Injector, signal, WritableSignal} from '@angular/core';
+import {Component, computed, effect, Injector, signal, WritableSignal} from '@angular/core';
 import {TestBed} from '@angular/core/testing';
 import {
   apply,
   applyEach,
   debounce,
   disabled,
   form,
+  FormField,
   hidden,
   readonly,
   required,
@@ -1247,6 +1248,78 @@ describe('FieldNode', () => {
         {kind: 'grandchild', fieldTree: f.child.child},
       ]);
     });
+
+    it('should sort errors by DOM position', async () => {
+      @Component({
+        template: `
+          <input [formField]="f.b" />
+          <input [formField]="f.a" />
+        `,
+        imports: [FormField],
+      })
+      class TestCmp {
+        f = form(signal({a: '', b: ''}), (p) => {
+          validate(p.a, () => ({kind: 'error-a'}));
+          validate(p.b, () => ({kind: 'error-b'}));
+        });
+      }
+
+      const fixture = TestBed.createComponent(TestCmp);
+      const cmp = fixture.componentInstance;
+      fixture.detectChanges();
+
+      expect(cmp.f().errorSummary()).toEqual([
+        jasmine.objectContaining({kind: 'error-b'}),
+        jasmine.objectContaining({kind: 'error-a'}),
+      ]);
+    });
+
+    it('should sort bound errors before unbound errors', () => {
+      @Component({
+        template: ` <input [formField]="f.a" /> `,
+        imports: [FormField],
+      })
+      class TestCmp {
+        f = form(signal({a: '', b: ''}), (p) => {
+          validate(p.a, () => ({kind: 'error-a'}));
+          validate(p.b, () => ({kind: 'error-b'}));
+        });
+      }
+
+      const fixture = TestBed.createComponent(TestCmp);
+      const cmp = fixture.componentInstance;
+      fixture.detectChanges();
+
+      expect(cmp.f().errorSummary()).toEqual([
+        jasmine.objectContaining({kind: 'error-a'}),
+        jasmine.objectContaining({kind: 'error-b'}),
+      ]);
+    });
+
+    it('should sort errors from nested fields by DOM position', () => {
+      @Component({
+        template: `
+          <input [formField]="f.group.child" />
+          <input [formField]="f.other" />
+        `,
+        imports: [FormField],
+      })
+      class TestCmp {
+        f = form(signal({group: {child: ''}, other: ''}), (p) => {
+          validate(p.group.child, () => ({kind: 'child'}));
+          validate(p.other, () => ({kind: 'other'}));
+        });
+      }
+
+      const fixture = TestBed.createComponent(TestCmp);
+      const cmp = fixture.componentInstance;
+      fixture.detectChanges();
+
+      expect(cmp.f().errorSummary()).toEqual([
+        jasmine.objectContaining({kind: 'child'}),
+        jasmine.objectContaining({kind: 'other'}),
+      ]);
+    });
   });
 
   describe('composition', () => {
diff --git a/packages/forms/signals/test/node/parse_errors.spec.ts b/packages/forms/signals/test/node/parse_errors.spec.ts
@@ -20,6 +20,7 @@ import {TestBed} from '@angular/core/testing';
 import {
   form,
   FormField,
+  validate,
   type FieldTree,
   type FormValueControl,
   type ValidationError,
@@ -151,6 +152,67 @@ describe('parse errors', () => {
     expect(cmp.f().errors().length).toBe(1);
     expect(cmp.f().errors()[0]).toEqual(jasmine.objectContaining({kind: 'parse'}));
   });
+
+  it('should sort parse errors mixed with validation errors by DOM position', async () => {
+    @Component({
+      imports: [TestNumberInput, FormField],
+      template: `
+        <test-number-input id="input1" [formField]="f.a" />
+        <test-number-input id="input2" [formField]="f.b" />
+      `,
+    })
+    class TestCmp {
+      state = signal({a: 5, b: 5});
+      f = form(this.state, (p) => {
+        validate(p.b, () => ({kind: 'val-error', message: 'validation error on b'}));
+      });
+    }
+
+    const fix = await act(() => TestBed.createComponent(TestCmp));
+    const comp = fix.componentInstance;
+    const input1: HTMLInputElement = fix.nativeElement.querySelector('#input1 input')!;
+
+    input1.value = 'joe';
+    await act(() => input1.dispatchEvent(new Event('input')));
+
+    // a has parse error "joe is not numeric" (from TestNumberInput logic)
+    // b has validation error "validation error on b"
+    // a is before b in DOM
+    expect(comp.f().errorSummary()).toEqual([
+      jasmine.objectContaining({message: 'joe is not numeric'}),
+      jasmine.objectContaining({message: 'validation error on b'}),
+    ]);
+  });
+
+  it('should sort parse errors mixed with validation errors by DOM position (swapped)', async () => {
+    @Component({
+      imports: [TestNumberInput, FormField],
+      template: `
+        <test-number-input id="input2" [formField]="f.b" />
+        <test-number-input id="input1" [formField]="f.a" />
+      `,
+    })
+    class TestCmp {
+      state = signal({a: 5, b: 5});
+      f = form(this.state, (p) => {
+        validate(p.b, () => ({kind: 'val-error', message: 'validation error on b'}));
+      });
+    }
+
+    const fix = await act(() => TestBed.createComponent(TestCmp));
+    const comp = fix.componentInstance;
+    const input1: HTMLInputElement = fix.nativeElement.querySelector('#input1 input')!;
+
+    input1.value = 'joe';
+    await act(() => input1.dispatchEvent(new Event('input')));
+
+    // b (validation error) is first in DOM
+    // a (parse error) is second
+    expect(comp.f().errorSummary()).toEqual([
+      jasmine.objectContaining({message: 'validation error on b'}),
+      jasmine.objectContaining({message: 'joe is not numeric'}),
+    ]);
+  });
 });
 
 @Component({
