feat: support showing errors when a control is marked as touched

README.md

@@ -107,7 +107,37 @@ export class AppComponent {
 }
 ```
 
-The directive will show all errors for a form field automatically in two instances - on the field element blur and on form submit.
+### Customize the behavior
+
+By default the directive will show all errors for a form field automatically in two instances: on the field element blur and on form submit.
+
+The default behavior can be overridden globally or on a per control basis.
+
+If you want to override the behavior globally, so that it affects all form controls, you can do so via the `controlErrorsOn` property:
+
+```ts
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideErrorTailorConfig({
+      errors: {
+        useValue: {
+          required: 'This field is required'
+        }
+      },
+      controlErrorsOn: {
+        change: true, // errors are shown/hidden on every change
+        touched: true, // errors are shown/hidden when the controls are marked as touched
+      }
+    })
+  ]
+})
+```
+
+Or you can change the behavior of a single form control by adding the relevant inputs. For example, to only show the errors on submit you can set to `false` both `controlErrorsOnBlur` and `controlErrorsOnAsync`:
+
+```html
+<input [controlErrorsOnBlur]="false" [controlErrorsOnAsync]="false" formControlName="name" />
+```
 
 ## Inputs
 
@@ -216,6 +246,12 @@ One typical case when to use it is radio buttons in the same radio group where i
 <input [controlErrorsOnChange]="true" formControlName="name" />
 ```
 
+- `controlErrorsOnTouched` - To modify the error display behavior to show errors when the control is marked as `touched` via `control.markAsTouched()` or `formGroup.markAllAsTouched()`:
+
+```html
+<input [controlErrorsOnTouched]="true" formControlName="name" />
+```
+
 ## Methods
 
 - `showError()` - Programmatic access to show a control error component (without a blur or a submit event). A validation error should still exist on that element. The key is the published `exportAs` reference of `errorTailor` to a directive instance of `ControlErrorsDirective` and calling its public method `showError()`.
@@ -336,17 +372,29 @@ bootstrapApplication(AppComponent, {
 
   ```
 
-- `controlErrorsOn` - Optional. An object that allows the default behavior for showing the errors to be overridden. (each individual property in the object is optional, so it's possible to override only 1 setting)
+- `controlErrorsOn` - Optional. Allows to override the default behavior for showing the errors. These are the possible properties and their defaults:
 
-```ts
-{
-  controlErrorsOn: {
-    async: true,  // (default: true)
-    blur: true,   // (default: true)
-    change: true, // (default: false)
+  ```ts
+  {
+    controlErrorsOn: {
+      async: true,
+      blur: true,
+      change: false,
+      touched: false,
+    }
   }
-}
-```
+  ```
+
+  The object will be merged with the default configuration object, so you can simply define one or more properties that you wish to override:
+
+  ```ts
+  {
+    controlErrorsOn: {
+      change: true,
+      touched: true,
+    }
+  }
+  ```
 
 ## Recipes
 

projects/ngneat/error-tailor/src/lib/control-error.directive.spec.ts

@@ -10,7 +10,12 @@ import {
   ValidationErrors,
   Validators,
 } from '@angular/forms';
-import { ControlErrorsDirective, errorTailorImports, provideErrorTailorConfig } from '@ngneat/error-tailor';
+import {
+  ControlErrorsDirective,
+  ErrorTailorConfig,
+  errorTailorImports,
+  provideErrorTailorConfig,
+} from '@ngneat/error-tailor';
 import { byPlaceholder, byText, createComponentFactory, Spectator } from '@ngneat/spectator';
 import { map, asyncScheduler, Observable, scheduled } from 'rxjs';
 import { DefaultControlErrorComponent } from './control-error.component';
@@ -64,6 +69,7 @@ describe('ControlErrorDirective', () => {
           <input formControlName="username" placeholder="Username" />
           <input formControlName="onSubmitOnly" placeholder="On submit only" [controlErrorsOnBlur]="false" />
           <input formControlName="onEveryChange" placeholder="On every change" [controlErrorsOnChange]="true" />
+          <input formControlName="onTouchedChange" placeholder="On touched change" [controlErrorsOnTouched]="true" />
           <button type="submit">Submit</button>
         </form>
       `,
@@ -78,6 +84,7 @@ describe('ControlErrorDirective', () => {
         username: ['', Validators.required, this.usernameValidator.bind(this)],
         onSubmitOnly: ['', [Validators.required]],
         onEveryChange: ['', [Validators.required]],
+        onTouchedChange: ['', [Validators.required]],
       });
 
       @ViewChild('explicitErrorTailor', { static: true }) explicitErrorTailor: ControlErrorsDirective;
@@ -137,8 +144,10 @@ describe('ControlErrorDirective', () => {
 
       const onSubmitOnly = spectator.query<HTMLInputElement>(byPlaceholder('On submit only'));
       const onEveryChange = spectator.query<HTMLInputElement>(byPlaceholder('On every change'));
+      const onTouchedChange = spectator.query<HTMLInputElement>(byPlaceholder('On touched change'));
       typeInElementAndFocusOut(spectator, 'test', onSubmitOnly);
       typeInElementAndFocusOut(spectator, 'test', onEveryChange);
+      typeInElementAndFocusOut(spectator, 'test', onTouchedChange);
 
       spectator.click('button');
 
@@ -178,6 +187,16 @@ describe('ControlErrorDirective', () => {
       expect(spectator.query(byText('required error'))).toBeFalsy();
     });
 
+    it('should show errors when the control becomes touched when controlErrorsOnTouched is enabled', () => {
+      const onEveryChange = spectator.query<HTMLInputElement>(byPlaceholder('On touched change'));
+
+      expect(spectator.query(byText('required error'))).toBeFalsy();
+
+      spectator.component.form.markAllAsTouched();
+      spectator.detectComponentChanges();
+      expect(spectator.query(byText('required error'))).toBeTruthy();
+    });
+
     it('should not show errors on interactions', () => {
       const ignoredInput = spectator.query<HTMLInputElement>(byPlaceholder('Ignored'));
 
@@ -500,10 +519,7 @@ describe('ControlErrorDirective', () => {
     })
     class CustomControlErrorComponent extends DefaultControlErrorComponent {}
 
-    function getCustomErrorComponentFactory<C>(
-      component: Type<C>,
-      controlErrorComponentAnchorFn: (hostElem: Element, errorElem: Element) => () => void = null,
-    ) {
+    function getCustomErrorComponentFactory<C>(component: Type<C>, config: Partial<ErrorTailorConfig> = {}) {
       return createComponentFactory({
         component,
         providers: [
@@ -516,10 +532,7 @@ describe('ControlErrorDirective', () => {
             controlErrorsClass: ['global', 'config'],
             controlCustomClass: 'control custom',
             controlErrorComponent: CustomControlErrorComponent,
-            controlErrorComponentAnchorFn,
-            controlErrorsOn: {
-              change: true,
-            },
+            ...config,
           }),
         ],
         imports: [FormsModule, CustomControlErrorComponent, ReactiveFormsModule, errorTailorImports],
@@ -563,17 +576,16 @@ describe('ControlErrorDirective', () => {
       let anchorFnDestroyCalled = false;
 
       let spectator: Spectator<CustomErrorFormGroupComponent>;
-      const createComponent = getCustomErrorComponentFactory(
-        CustomErrorFormGroupComponent,
-        (hostElem: Element, errorElem: Element) => {
+      const createComponent = getCustomErrorComponentFactory(CustomErrorFormGroupComponent, {
+        controlErrorComponentAnchorFn: (hostElem: Element, errorElem: Element) => {
           anchorFnCalled = true;
           expect(hostElem).toBeTruthy();
           expect(errorElem).toBeTruthy();
           return () => {
             anchorFnDestroyCalled = true;
           };
         },
-      );
+      });
 
       beforeEach(() => (spectator = createComponent()));
 
@@ -604,24 +616,47 @@ describe('ControlErrorDirective', () => {
     });
 
     describe('controlErrorsOn', () => {
-      let spectator: Spectator<CustomErrorFormGroupComponent>;
-      const createComponent = getCustomErrorComponentFactory(CustomErrorFormGroupComponent);
+      describe('change', () => {
+        let spectator: Spectator<CustomErrorFormGroupComponent>;
+        const createComponent = getCustomErrorComponentFactory(CustomErrorFormGroupComponent, {
+          controlErrorsOn: { change: true },
+        });
 
-      beforeEach(() => (spectator = createComponent()));
+        beforeEach(() => (spectator = createComponent()));
 
-      it('should override default behavior for showing errors', () => {
-        const input = spectator.query<HTMLInputElement>(byPlaceholder('Name'));
+        it('should show errors on change when overriding default behavior by setting controlErrorsOn.change to true', () => {
+          const input = spectator.query<HTMLInputElement>(byPlaceholder('Name'));
 
-        expect(spectator.query(byText('required error'))).toBeFalsy();
+          expect(spectator.query(byText('required error'))).toBeFalsy();
 
-        spectator.typeInElement('test', input);
-        expect(spectator.query(byText('required error'))).toBeFalsy();
+          spectator.typeInElement('test', input);
+          expect(spectator.query(byText('required error'))).toBeFalsy();
 
-        spectator.typeInElement('', input);
-        expect(spectator.query(byText('required error'))).toBeTruthy();
+          spectator.typeInElement('', input);
+          expect(spectator.query(byText('required error'))).toBeTruthy();
+
+          spectator.typeInElement('t', input);
+          expect(spectator.query(byText('required error'))).toBeFalsy();
+        });
+      });
+
+      describe('touched', () => {
+        let spectator: Spectator<CustomErrorFormGroupComponent>;
+        const createComponent = getCustomErrorComponentFactory(CustomErrorFormGroupComponent, {
+          controlErrorsOn: { touched: true },
+        });
+
+        beforeEach(() => (spectator = createComponent()));
+
+        it('should show errors when control becomes touched when overriding default behavior by setting controlErrorsOn.touched to true', () => {
+          const input = spectator.query<HTMLInputElement>(byPlaceholder('Name'));
+
+          expect(spectator.query(byText('required error'))).toBeFalsy();
 
-        spectator.typeInElement('t', input);
-        expect(spectator.query(byText('required error'))).toBeFalsy();
+          spectator.component.form.markAllAsTouched();
+          spectator.detectComponentChanges();
+          expect(spectator.query(byText('required error'))).toBeTruthy();
+        });
       });
     });
   });

projects/ngneat/error-tailor/src/lib/control-error.directive.ts

@@ -1,6 +1,7 @@
 import {
   ComponentRef,
   Directive,
+  DoCheck,
   ElementRef,
   EmbeddedViewRef,
   Inject,
@@ -27,6 +28,7 @@ import {
   Observable,
   Subject,
   tap,
+  skip,
 } from 'rxjs';
 
 import { ControlErrorAnchorDirective } from './control-error-anchor.directive';
@@ -43,7 +45,7 @@ const errorTailorClass = 'error-tailor-has-error';
     '[formControlName]:not([controlErrorsIgnore]), [formControl]:not([controlErrorsIgnore]), [formGroup]:not([controlErrorsIgnore]), [formGroupName]:not([controlErrorsIgnore]), [formArrayName]:not([controlErrorsIgnore]), [ngModel]:not([controlErrorsIgnore])',
   exportAs: 'errorTailor',
 })
-export class ControlErrorsDirective implements OnInit, OnDestroy {
+export class ControlErrorsDirective implements OnInit, OnDestroy, DoCheck {
   @Input('controlErrors') customErrors: ErrorsMap = {};
   @Input() controlErrorsClass: string | string[] | undefined;
   @Input() controlCustomClass: string | string[] | undefined;
@@ -52,6 +54,7 @@ export class ControlErrorsDirective implements OnInit, OnDestroy {
   @Input() controlErrorsOnBlur: boolean | undefined;
   @Input() controlErrorsOnChange: boolean | undefined;
   @Input() controlErrorsOnStatusChange: boolean | undefined;
+  @Input() controlErrorsOnTouched: boolean | undefined;
   @Input() controlErrorAnchor: ControlErrorAnchorDirective;
 
   private ref: ComponentRef<ControlErrorComponent>;
@@ -62,6 +65,7 @@ export class ControlErrorsDirective implements OnInit, OnDestroy {
   private mergedConfig: ErrorTailorConfig = {};
   private customAnchorDestroyFn: () => void;
   private host: HTMLElement;
+  private touchedChanges$ = new Subject<boolean>();
 
   constructor(
     private vcr: ViewContainerRef,
@@ -91,6 +95,7 @@ export class ControlErrorsDirective implements OnInit, OnDestroy {
     let changesOnBlur$: Observable<any> = EMPTY;
     let changesOnChange$: Observable<any> = EMPTY;
     let changesOnStatusChange$: Observable<any> = EMPTY;
+    let changesOnTouched$: Observable<boolean> = EMPTY;
 
     if (!this.controlErrorsClass || this.controlErrorsClass?.length === 0) {
       if (this.mergedConfig.controlErrorsClass && this.mergedConfig.controlErrorsClass) {
@@ -118,6 +123,11 @@ export class ControlErrorsDirective implements OnInit, OnDestroy {
       changesOnStatusChange$ = statusChanges$;
     }
 
+    if (this.mergedConfig.controlErrorsOn.touched) {
+      // every time the touched property changes, skipping the first emission since it's the initial state
+      changesOnTouched$ = this.touchedChanges$.asObservable().pipe(distinctUntilChanged(), skip(1));
+    }
+
     if (this.isInput && this.mergedConfig.controlErrorsOn.blur) {
       const blur$ = fromEvent(this.host, 'focusout');
       // blurFirstThenUponChange
@@ -144,12 +154,30 @@ export class ControlErrorsDirective implements OnInit, OnDestroy {
       .pipe(takeUntil(this.destroy))
       .subscribe(() => {
         const hasErrors = !!this.control.errors;
+
         if (hasErrors) {
           this.showError();
         } else {
           this.hideError();
         }
       });
+
+    changesOnTouched$.pipe(takeUntil(this.destroy)).subscribe(() => {
+      const hasErrors = !!this.control.errors;
+      const touched = this.mergedConfig.controlErrorsOn.touched ? this.control.touched : true;
+
+      if (hasErrors && touched) {
+        this.showError();
+      } else {
+        this.hideError();
+      }
+    });
+  }
+
+  ngDoCheck(): void {
+    if (this.mergedConfig.controlErrorsOn.touched) {
+      this.touchedChanges$.next(this.control.touched);
+    }
   }
 
   private setError(text: string, error?: ValidationErrors) {
@@ -260,6 +288,7 @@ export class ControlErrorsDirective implements OnInit, OnDestroy {
         blur: this.controlErrorsOnBlur ?? this.config.controlErrorsOn?.blur ?? true,
         change: this.controlErrorsOnChange ?? this.config.controlErrorsOn?.change ?? false,
         status: this.controlErrorsOnStatusChange ?? this.config.controlErrorsOn?.status ?? false,
+        touched: this.controlErrorsOnTouched ?? this.config.controlErrorsOn?.touched ?? false,
       },
     };
   }

projects/ngneat/error-tailor/src/lib/error-tailor.providers.ts

@@ -32,6 +32,7 @@ export type ErrorTailorConfig = {
     blur?: boolean;
     change?: boolean;
     status?: boolean;
+    touched?: boolean;
   };
 };
 

src/app/app.component.html

@@ -1,6 +1,6 @@
 <form [formGroup]="form" errorTailor>
   <div class="form-group">
-    <input class="form-control" formControlName="name" placeholder="Name" />
+    <input class="form-control" formControlName="name" placeholder="Name" [controlErrorsOnTouched]="true" />
   </div>
   <div class="form-check form-group">
     <input class="form-check-input" type="checkbox" formControlName="terms" id="check" [controlErrorAnchor]="anchor" />
@@ -70,6 +70,16 @@
     </span>
   </div>
   <br />
+  <div class="text-right">
+    <span>
+      Showing/hiding errors on name via touched:
+      <button type="button" class="btn btn-success btn-custom" (click)="markNameAsTouched()">Mark as touched</button>
+      <button type="button" class="btn btn-success btn-custom" (click)="markNameAsUntouched()">
+        Mark as untouched
+      </button>
+    </span>
+  </div>
+  <br />
   <div class="text-right"><button class="btn btn-success btn-custom">Submit</button> <br /></div>
 </form>
 <h1>Template</h1>