refactor(forms): loosen the error and disabled type on FormUiControl (angular#63455)

This allows passing errors and disabled reasons that did not originate
from `@angular/forms/signals` in case the the control is being used
separately from the forms system

PR Close angular#63455

Author: mmalerba

goldens/public-api/forms/signals/index.api.md

@@ -88,14 +88,18 @@ export class Control<T> {
 export function createProperty<TValue>(): Property<TValue>;
 
 // @public
-export function customError<E extends Omit<Partial<ValidationError>, typeof BRAND>>(obj: WithField<E>): CustomValidationError;
+export function customError<E extends Partial<ValidationError>>(obj: WithField<E>): CustomValidationError;
 
 // @public
-export function customError<E extends Omit<Partial<ValidationError>, typeof BRAND>>(obj?: E): WithoutField<CustomValidationError>;
+export function customError<E extends Partial<ValidationError>>(obj?: E): WithoutField<CustomValidationError>;
 
 // @public
-export class CustomValidationError extends ValidationError {
+export class CustomValidationError implements ValidationError {
+    constructor(options?: ValidationErrorOptions);
     [key: PropertyKey]: unknown;
+    readonly field: Field<unknown>;
+    readonly kind: string;
+    readonly message?: string;
 }
 
 // @public
@@ -194,8 +198,8 @@ export interface FormOptions {
 export interface FormUiControl {
     readonly dirty?: InputSignal<boolean>;
     readonly disabled?: InputSignal<boolean>;
-    readonly disabledReasons?: InputSignal<readonly DisabledReason[]>;
-    readonly errors?: InputSignal<readonly ValidationError[]>;
+    readonly disabledReasons?: InputSignal<readonly WithOptionalField<DisabledReason>[]>;
+    readonly errors?: InputSignal<readonly WithOptionalField<ValidationError>[]>;
     readonly hidden?: InputSignal<boolean>;
     readonly invalid?: InputSignal<boolean>;
     readonly max?: InputSignal<number | undefined>;
@@ -542,9 +546,7 @@ export function validateHttp<TValue, TResult = unknown, TPathKind extends PathKi
 export function validateTree<TValue, TPathKind extends PathKind = PathKind.Root>(path: FieldPath<TValue, TPathKind>, logic: NoInfer<TreeValidator<TValue, TPathKind>>): void;
 
 // @public
-export abstract class ValidationError {
-    [BRAND]: undefined;
-    constructor(options?: ValidationErrorOptions);
+export interface ValidationError {
     readonly field: Field<unknown>;
     readonly kind: string;
     readonly message?: string;
@@ -565,7 +567,7 @@ export type WithField<T> = T & {
 };
 
 // @public
-export type WithOptionalField<T> = T & {
+export type WithOptionalField<T> = Omit<T, 'field'> & {
     field?: Field<unknown>;
 };
 

packages/forms/signals/src/api/control.ts

@@ -8,7 +8,7 @@
 
 import {InputSignal, ModelSignal, OutputRef} from '@angular/core';
 import type {DisabledReason} from './types';
-import {ValidationError} from './validation_errors';
+import {ValidationError, type WithOptionalField} from './validation_errors';
 
 /** The base set of properties shared by all form control contracts. */
 export interface FormUiControl {
@@ -20,7 +20,7 @@ export interface FormUiControl {
    * An input to receive the errors for the field. If implemented, the `Control` directive will
    * automatically bind errors from the bound field to this input.
    */
-  readonly errors?: InputSignal<readonly ValidationError[]>;
+  readonly errors?: InputSignal<readonly WithOptionalField<ValidationError>[]>;
   /**
    * An input to receive the disabled status for the field. If implemented, the `Control` directive
    * will automatically bind the disabled status from the bound field to this input.
@@ -30,7 +30,7 @@ export interface FormUiControl {
    * An input to receive the reasons for the disablement of the field. If implemented, the `Control`
    * directive will automatically bind the disabled reason from the bound field to this input.
    */
-  readonly disabledReasons?: InputSignal<readonly DisabledReason[]>;
+  readonly disabledReasons?: InputSignal<readonly WithOptionalField<DisabledReason>[]>;
   /**
    * An input to receive the readonly status for the field. If implemented, the `Control` directive
    * will automatically bind the readonly status from the bound field to this input.

packages/forms/signals/src/api/validation_errors.ts

@@ -9,9 +9,6 @@
 import type {StandardSchemaV1} from '@standard-schema/spec';
 import {Field} from './types';
 
-/** Internal symbol used for class branding. */
-const BRAND = Symbol();
-
 /**
  * Options used to create a `ValidationError`.
  */
@@ -30,7 +27,7 @@ export type WithField<T> = T & {field: Field<unknown>};
  * A type that allows the given type `T` to optionally have a `field` property.
  * @template T The type to optionally add a `field` to.
  */
-export type WithOptionalField<T> = T & {field?: Field<unknown>};
+export type WithOptionalField<T> = Omit<T, 'field'> & {field?: Field<unknown>};
 
 /**
  * A type that ensures the given type `T` does not have a `field` property.
@@ -226,17 +223,17 @@ export function standardSchemaError(
  * Create a custom error associated with the target field
  * @param obj The object to create an error from
  */
-export function customError<E extends Omit<Partial<ValidationError>, typeof BRAND>>(
+export function customError<E extends Partial<ValidationError>>(
   obj: WithField<E>,
 ): CustomValidationError;
 /**
  * Create a custom error
  * @param obj The object to create an error from
  */
-export function customError<E extends Omit<Partial<ValidationError>, typeof BRAND>>(
+export function customError<E extends Partial<ValidationError>>(
   obj?: E,
 ): WithoutField<CustomValidationError>;
-export function customError<E extends Omit<Partial<ValidationError>, typeof BRAND>>(
+export function customError<E extends Partial<ValidationError>>(
   obj?: E,
 ): WithOptionalField<CustomValidationError> {
   return new CustomValidationError(obj);
@@ -247,9 +244,26 @@ export function customError<E extends Omit<Partial<ValidationError>, typeof BRAN
  *
  * Use the creation functions to create an instance (e.g. `requiredError`, `minError`, etc.).
  */
-export abstract class ValidationError {
+export interface ValidationError {
+  /** Identifies the kind of error. */
+  readonly kind: string;
+  /** The field associated with this error. */
+  readonly field: Field<unknown>;
+  /** Human readable error message. */
+  readonly message?: string;
+}
+
+/**
+ * A custom error that may contain additional properties
+ */
+export class CustomValidationError implements ValidationError {
   /** Brand the class to avoid Typescript structural matching */
-  [BRAND] = undefined;
+  private __brand = undefined;
+
+  /**
+   * Allow the user to attach arbitrary other properties.
+   */
+  [key: PropertyKey]: unknown;
 
   /** Identifies the kind of error. */
   readonly kind: string = '';
@@ -267,21 +281,29 @@ export abstract class ValidationError {
   }
 }
 
-/**
- * A custom error that may contain additional properties
- */
-export class CustomValidationError extends ValidationError {
-  /**
-   * Allow the user to attach arbitrary other properties.
-   */
-  [key: PropertyKey]: unknown;
-}
-
 /**
  * Internal version of `NgValidationError`, we create this separately so we can change its type on
  * the exported version to a type union of the possible sub-classes.
  */
-abstract class _NgValidationError extends ValidationError {}
+abstract class _NgValidationError implements ValidationError {
+  /** Brand the class to avoid Typescript structural matching */
+  private __brand = undefined;
+
+  /** Identifies the kind of error. */
+  readonly kind: string = '';
+
+  /** The field associated with this error. */
+  readonly field!: Field<unknown>;
+
+  /** Human readable error message. */
+  readonly message?: string;
+
+  constructor(options?: ValidationErrorOptions) {
+    if (options) {
+      Object.assign(this, options);
+    }
+  }
+}
 
 /**
  * An error used to indicate that a required field is empty.

packages/forms/signals/test/web/control_directive.spec.ts

@@ -34,6 +34,8 @@ import {
   type Field,
   type FormCheckboxControl,
   type FormValueControl,
+  type ValidationError,
+  type WithOptionalField,
 } from '../../public_api';
 
 @Component({
@@ -459,7 +461,7 @@ describe('control directive', () => {
     })
     class CustomInput implements FormValueControl<string> {
       value = model('');
-      disabledReasons = input<readonly DisabledReason[]>([]);
+      disabledReasons = input<readonly WithOptionalField<DisabledReason>[]>([]);
     }
 
     @Component({
@@ -523,6 +525,53 @@ describe('control directive', () => {
     act(() => field().reset());
     expect(myInput.touched()).toBe(false);
   });
+
+  it('should allow binding error and disabled messages through control or manually', () => {
+    @Component({
+      selector: 'my-input',
+      template: `
+        <input #i [value]="value()" (input)="value.set(i.value)" />
+        @for (reason of disabledReasons(); track $index) {
+          <p class="disabled-reason">{{reason.message}}</p>
+        }
+        @for (error of errors(); track $index) {
+          <p class="error">{{error.message}}</p>
+        }
+      `,
+    })
+    class CustomInput implements FormValueControl<string> {
+      value = model('');
+      disabledReasons = input<readonly WithOptionalField<DisabledReason>[]>([]);
+      errors = input<readonly WithOptionalField<ValidationError>[]>([]);
+    }
+
+    @Component({
+      imports: [Control, CustomInput],
+      template: `
+        <my-input [(value)]="model" [disabledReasons]="disabledReasons" [errors]="errors" />
+        <my-input [control]="f" />
+      `,
+    })
+    class TestCmp {
+      model = signal('');
+      f = form(this.model, (p) => {
+        required(p, {message: 'schema error'});
+        disabled(p, ({value}) => (value() === 'disabled' ? 'schema disabled' : false));
+      });
+      disabledReasons = [{message: 'manual disabled'}];
+      errors = [{kind: 'error', message: 'manual error'}];
+    }
+
+    const fix = act(() => TestBed.createComponent(TestCmp));
+    expect([...fix.nativeElement.querySelectorAll('.error')].map((e) => e.textContent)).toEqual([
+      'manual error',
+      'schema error',
+    ]);
+    act(() => fix.componentInstance.model.set('disabled'));
+    expect(
+      [...fix.nativeElement.querySelectorAll('.disabled-reason')].map((e) => e.textContent),
+    ).toEqual(['manual disabled', 'schema disabled']);
+  });
 });
 
 function setupRadioGroup() {