fix(material/checkbox): move required validation into component

Currently required validation is implemented as a separate directive. This is problematic, because with standalone users would have to add two imports.

These changes move the required validation into the checkbox and deprecate the old module.

Author: crisbeto

src/material/checkbox/checkbox-required-validator.ts

@@ -9,18 +9,23 @@
 import {Directive, forwardRef, Provider} from '@angular/core';
 import {CheckboxRequiredValidator, NG_VALIDATORS} from '@angular/forms';
 
+/**
+ * @deprecated No longer used, `MatCheckbox` implements required validation directly.
+ * @breaking-change 19.0.0
+ */
 export const MAT_CHECKBOX_REQUIRED_VALIDATOR: Provider = {
   provide: NG_VALIDATORS,
   useExisting: forwardRef(() => MatCheckboxRequiredValidator),
   multi: true,
 };
 
-// TODO(crisbeto): this should be deprecated and moved into `MatCheckbox`.
-
 /**
  * Validator for Material checkbox's required attribute in template-driven checkbox.
  * Current CheckboxRequiredValidator only work with `input type=checkbox` and does not
  * work with `mat-checkbox`.
+ *
+ * @deprecated No longer used, `MatCheckbox` implements required validation directly.
+ * @breaking-change 19.0.0
  */
 @Directive({
   selector: `mat-checkbox[required][formControlName],

src/material/checkbox/checkbox.spec.ts

@@ -10,7 +10,6 @@ import {
   MatCheckbox,
   MatCheckboxChange,
   MatCheckboxModule,
-  MatCheckboxRequiredValidator,
 } from './index';
 
 describe('MDC-based MatCheckbox', () => {
@@ -1100,7 +1099,7 @@ class SingleCheckbox {
   template: `<mat-checkbox [required]="isRequired" [(ngModel)]="isGood"
                            [disabled]="isDisabled">Be good</mat-checkbox>`,
   standalone: true,
-  imports: [MatCheckbox, MatCheckboxRequiredValidator, FormsModule],
+  imports: [MatCheckbox, FormsModule],
 })
 class CheckboxWithNgModel {
   isGood: boolean = false;

src/material/checkbox/checkbox.ts

@@ -20,12 +20,21 @@ import {
   Input,
   NgZone,
   numberAttribute,
+  OnChanges,
   Optional,
   Output,
+  SimpleChanges,
   ViewChild,
   ViewEncapsulation,
 } from '@angular/core';
-import {ControlValueAccessor, NG_VALUE_ACCESSOR} from '@angular/forms';
+import {
+  AbstractControl,
+  ControlValueAccessor,
+  NG_VALIDATORS,
+  NG_VALUE_ACCESSOR,
+  ValidationErrors,
+  Validator,
+} from '@angular/forms';
 import {MatRipple} from '@angular/material/core';
 import {ANIMATION_MODULE_TYPE} from '@angular/platform-browser/animations';
 import {FocusableOption} from '@angular/cdk/a11y';
@@ -50,6 +59,10 @@ export enum TransitionCheckState {
   Indeterminate,
 }
 
+/**
+ * @deprecated Will stop being exported.
+ * @breaking-change 19.0.0
+ */
 export const MAT_CHECKBOX_CONTROL_VALUE_ACCESSOR: any = {
   provide: NG_VALUE_ACCESSOR,
   useExisting: forwardRef(() => MatCheckbox),
@@ -87,14 +100,23 @@ const defaults = MAT_CHECKBOX_DEFAULT_OPTIONS_FACTORY();
     '[class.mat-mdc-checkbox-checked]': 'checked',
     '[class]': 'color ? "mat-" + color : "mat-accent"',
   },
-  providers: [MAT_CHECKBOX_CONTROL_VALUE_ACCESSOR],
+  providers: [
+    MAT_CHECKBOX_CONTROL_VALUE_ACCESSOR,
+    {
+      provide: NG_VALIDATORS,
+      useExisting: MatCheckbox,
+      multi: true,
+    },
+  ],
   exportAs: 'matCheckbox',
   encapsulation: ViewEncapsulation.None,
   changeDetection: ChangeDetectionStrategy.OnPush,
   standalone: true,
   imports: [MatRipple],
 })
-export class MatCheckbox implements AfterViewInit, ControlValueAccessor, FocusableOption {
+export class MatCheckbox
+  implements AfterViewInit, OnChanges, ControlValueAccessor, Validator, FocusableOption
+{
   /** Focuses the checkbox. */
   focus() {
     this._inputElement.nativeElement.focus();
@@ -197,10 +219,9 @@ export class MatCheckbox implements AfterViewInit, ControlValueAccessor, Focusab
   _onTouched: () => any = () => {};
 
   private _currentAnimationClass: string = '';
-
   private _currentCheckState: TransitionCheckState = TransitionCheckState.Init;
-
   private _controlValueAccessorChangeFn: (value: any) => void = () => {};
+  private _validatorChangeFn = () => {};
 
   constructor(
     public _elementRef: ElementRef<HTMLElement>,
@@ -216,6 +237,12 @@ export class MatCheckbox implements AfterViewInit, ControlValueAccessor, Focusab
     this.id = this._uniqueId = `mat-mdc-checkbox-${++nextUniqueId}`;
   }
 
+  ngOnChanges(changes: SimpleChanges) {
+    if (changes['required']) {
+      this._validatorChangeFn();
+    }
+  }
+
   ngAfterViewInit() {
     this._syncIndeterminate(this._indeterminate);
   }
@@ -309,6 +336,16 @@ export class MatCheckbox implements AfterViewInit, ControlValueAccessor, Focusab
     this.disabled = isDisabled;
   }
 
+  // Implemented as a part of Validator.
+  validate(control: AbstractControl<boolean>): ValidationErrors | null {
+    return this.required && control.value !== true ? {'required': true} : null;
+  }
+
+  // Implemented as a part of Validator.
+  registerOnValidatorChange(fn: () => void): void {
+    this._validatorChangeFn = fn;
+  }
+
   private _transitionCheckState(newState: TransitionCheckState) {
     let oldState = this._currentCheckState;
     let element = this._getAnimationTargetElement();

src/material/checkbox/module.ts

@@ -7,19 +7,22 @@
  */
 
 import {NgModule} from '@angular/core';
-import {MatCommonModule, MatRippleModule} from '@angular/material/core';
+import {MatCommonModule} from '@angular/material/core';
 import {MatCheckbox} from './checkbox';
 import {MatCheckboxRequiredValidator} from './checkbox-required-validator';
 
-/** This module is used by both original and MDC-based checkbox implementations. */
+/**
+ * @deprecated No longer used, `MatCheckbox` implements required validation directly.
+ * @breaking-change 19.0.0
+ */
 @NgModule({
   imports: [MatCheckboxRequiredValidator],
   exports: [MatCheckboxRequiredValidator],
 })
 export class _MatCheckboxRequiredValidatorModule {}
 
 @NgModule({
-  imports: [MatCommonModule, MatRippleModule, _MatCheckboxRequiredValidatorModule, MatCheckbox],
-  exports: [MatCheckbox, MatCommonModule, _MatCheckboxRequiredValidatorModule],
+  imports: [MatCheckbox, MatCommonModule],
+  exports: [MatCheckbox, MatCommonModule],
 })
 export class MatCheckboxModule {}

tools/public_api_guard/material/checkbox.md

@@ -4,6 +4,7 @@
 
 ```ts
 
+import { AbstractControl } from '@angular/forms';
 import { AfterViewInit } from '@angular/core';
 import { ChangeDetectorRef } from '@angular/core';
 import { CheckboxRequiredValidator } from '@angular/forms';
@@ -12,14 +13,18 @@ import { ElementRef } from '@angular/core';
 import { EventEmitter } from '@angular/core';
 import { FocusableOption } from '@angular/cdk/a11y';
 import * as i0 from '@angular/core';
-import * as i2 from '@angular/material/core';
+import * as i3 from '@angular/material/core';
 import { InjectionToken } from '@angular/core';
 import { MatRipple } from '@angular/material/core';
 import { NgZone } from '@angular/core';
+import { OnChanges } from '@angular/core';
 import { Provider } from '@angular/core';
+import { SimpleChanges } from '@angular/core';
 import { ThemePalette } from '@angular/material/core';
+import { ValidationErrors } from '@angular/forms';
+import { Validator } from '@angular/forms';
 
-// @public (undocumented)
+// @public @deprecated (undocumented)
 export const MAT_CHECKBOX_CONTROL_VALUE_ACCESSOR: any;
 
 // @public
@@ -28,11 +33,11 @@ export const MAT_CHECKBOX_DEFAULT_OPTIONS: InjectionToken<MatCheckboxDefaultOpti
 // @public
 export function MAT_CHECKBOX_DEFAULT_OPTIONS_FACTORY(): MatCheckboxDefaultOptions;
 
-// @public (undocumented)
+// @public @deprecated (undocumented)
 export const MAT_CHECKBOX_REQUIRED_VALIDATOR: Provider;
 
 // @public (undocumented)
-export class MatCheckbox implements AfterViewInit, ControlValueAccessor, FocusableOption {
+export class MatCheckbox implements AfterViewInit, OnChanges, ControlValueAccessor, Validator, FocusableOption {
     constructor(_elementRef: ElementRef<HTMLElement>, _changeDetectorRef: ChangeDetectorRef, _ngZone: NgZone, tabIndex: string, _animationMode?: string | undefined, _options?: MatCheckboxDefaultOptions | undefined);
     protected _animationClasses: {
         uncheckedToChecked: string;
@@ -87,6 +92,8 @@ export class MatCheckbox implements AfterViewInit, ControlValueAccessor, Focusab
     // (undocumented)
     ngAfterViewInit(): void;
     // (undocumented)
+    ngOnChanges(changes: SimpleChanges): void;
+    // (undocumented)
     _onBlur(): void;
     // (undocumented)
     _onInputClick(): void;
@@ -101,13 +108,17 @@ export class MatCheckbox implements AfterViewInit, ControlValueAccessor, Focusab
     registerOnChange(fn: (value: any) => void): void;
     // (undocumented)
     registerOnTouched(fn: any): void;
+    // (undocumented)
+    registerOnValidatorChange(fn: () => void): void;
     required: boolean;
     // @deprecated
     ripple: MatRipple;
     // (undocumented)
     setDisabledState(isDisabled: boolean): void;
     tabIndex: number;
     toggle(): void;
+    // (undocumented)
+    validate(control: AbstractControl<boolean>): ValidationErrors | null;
     value: string;
     // (undocumented)
     writeValue(value: any): void;
@@ -139,18 +150,18 @@ export class MatCheckboxModule {
     // (undocumented)
     static ɵinj: i0.ɵɵInjectorDeclaration<MatCheckboxModule>;
     // (undocumented)
-    static ɵmod: i0.ɵɵNgModuleDeclaration<MatCheckboxModule, never, [typeof i2.MatCommonModule, typeof i2.MatRippleModule, typeof _MatCheckboxRequiredValidatorModule, typeof i3.MatCheckbox], [typeof i3.MatCheckbox, typeof i2.MatCommonModule, typeof _MatCheckboxRequiredValidatorModule]>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<MatCheckboxModule, never, [typeof i2.MatCheckbox, typeof i3.MatCommonModule], [typeof i2.MatCheckbox, typeof i3.MatCommonModule]>;
 }
 
-// @public
+// @public @deprecated
 export class MatCheckboxRequiredValidator extends CheckboxRequiredValidator {
     // (undocumented)
     static ɵdir: i0.ɵɵDirectiveDeclaration<MatCheckboxRequiredValidator, "mat-checkbox[required][formControlName],             mat-checkbox[required][formControl], mat-checkbox[required][ngModel]", never, {}, {}, never, never, true, never>;
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<MatCheckboxRequiredValidator, never>;
 }
 
-// @public
+// @public @deprecated (undocumented)
 export class _MatCheckboxRequiredValidatorModule {
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<_MatCheckboxRequiredValidatorModule, never>;