fix(checkbox): pass aria-describedby through to input (#19495)

Passes the `aria-describedby` attribute value through to the underlying `input` element.

Fixes #19477.

Author: crisbeto

src/material-experimental/mdc-checkbox/checkbox.html

@@ -7,6 +7,7 @@
            [attr.aria-checked]="_getAriaChecked()"
            [attr.aria-label]="ariaLabel || null"
            [attr.aria-labelledby]="ariaLabelledby"
+           [attr.aria-describedby]="ariaDescribedby"
            [attr.name]="name"
            [attr.value]="value"
            [checked]="checked"

src/material-experimental/mdc-checkbox/checkbox.spec.ts

@@ -702,6 +702,32 @@ describe('MDC-based MatCheckbox', () => {
        }));
   });
 
+  describe('with provided aria-describedby ', () => {
+    let checkboxDebugElement: DebugElement;
+    let checkboxNativeElement: HTMLElement;
+    let inputElement: HTMLInputElement;
+
+    it('should use the provided aria-describedby', () => {
+      fixture = createComponent(CheckboxWithAriaDescribedby);
+      checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
+      checkboxNativeElement = checkboxDebugElement.nativeElement;
+      inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');
+
+      fixture.detectChanges();
+      expect(inputElement.getAttribute('aria-describedby')).toBe('some-id');
+    });
+
+    it('should not assign aria-describedby if none is provided', () => {
+      fixture = createComponent(SingleCheckbox);
+      checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
+      checkboxNativeElement = checkboxDebugElement.nativeElement;
+      inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');
+
+      fixture.detectChanges();
+      expect(inputElement.getAttribute('aria-describedby')).toBe(null);
+    });
+  });
+
   describe('with provided tabIndex', () => {
     let checkboxDebugElement: DebugElement;
     let checkboxNativeElement: HTMLElement;
@@ -1111,6 +1137,12 @@ class CheckboxWithAriaLabel {
 class CheckboxWithAriaLabelledby {
 }
 
+/** Simple test component with an aria-describedby set. */
+@Component({
+  template: `<mat-checkbox aria-describedby="some-id"></mat-checkbox>`
+})
+class CheckboxWithAriaDescribedby {}
+
 /** Simple test component with name attribute */
 @Component({template: `<mat-checkbox name="test-name"></mat-checkbox>`})
 class CheckboxWithNameAttribute {

src/material-experimental/mdc-checkbox/checkbox.ts

@@ -86,6 +86,9 @@ export class MatCheckbox implements AfterViewInit, OnDestroy, ControlValueAccess
   /** The `aria-labelledby` attribute to use for the input element. */
   @Input('aria-labelledby') ariaLabelledby: string|null = null;
 
+  /** The 'aria-describedby' attribute is read after the element's label and field type. */
+  @Input('aria-describedby') ariaDescribedby: string;
+
   /** The color palette  for this checkbox ('primary', 'accent', or 'warn'). */
   @Input() color: ThemePalette = 'accent';
 

src/material/checkbox/checkbox.html

@@ -13,6 +13,7 @@
            [attr.aria-label]="ariaLabel || null"
            [attr.aria-labelledby]="ariaLabelledby"
            [attr.aria-checked]="_getAriaChecked()"
+           [attr.aria-describedby]="ariaDescribedby"
            (change)="_onInteractionEvent($event)"
            (click)="_onInputClick($event)">
     <div matRipple class="mat-checkbox-ripple mat-focus-indicator"

src/material/checkbox/checkbox.spec.ts

@@ -784,6 +784,32 @@ describe('MatCheckbox', () => {
     });
   });
 
+  describe('with provided aria-describedby ', () => {
+    let checkboxDebugElement: DebugElement;
+    let checkboxNativeElement: HTMLElement;
+    let inputElement: HTMLInputElement;
+
+    it('should use the provided aria-describedby', () => {
+      fixture = createComponent(CheckboxWithAriaDescribedby);
+      checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
+      checkboxNativeElement = checkboxDebugElement.nativeElement;
+      inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');
+
+      fixture.detectChanges();
+      expect(inputElement.getAttribute('aria-describedby')).toBe('some-id');
+    });
+
+    it('should not assign aria-describedby if none is provided', () => {
+      fixture = createComponent(SingleCheckbox);
+      checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
+      checkboxNativeElement = checkboxDebugElement.nativeElement;
+      inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');
+
+      fixture.detectChanges();
+      expect(inputElement.getAttribute('aria-describedby')).toBe(null);
+    });
+  });
+
   describe('with provided tabIndex', () => {
     let checkboxDebugElement: DebugElement;
     let checkboxNativeElement: HTMLElement;
@@ -1346,6 +1372,12 @@ class CheckboxWithAriaLabel { }
 })
 class CheckboxWithAriaLabelledby {}
 
+/** Simple test component with an aria-describedby set. */
+@Component({
+  template: `<mat-checkbox aria-describedby="some-id"></mat-checkbox>`
+})
+class CheckboxWithAriaDescribedby {}
+
 /** Simple test component with name attribute */
 @Component({
   template: `<mat-checkbox name="test-name"></mat-checkbox>`

src/material/checkbox/checkbox.ts

@@ -146,6 +146,9 @@ export class MatCheckbox extends _MatCheckboxMixinBase implements ControlValueAc
    */
   @Input('aria-labelledby') ariaLabelledby: string | null = null;
 
+  /** The 'aria-describedby' attribute is read after the element's label and field type. */
+  @Input('aria-describedby') ariaDescribedby: string;
+
   private _uniqueId: string = `mat-checkbox-${++nextUniqueId}`;
 
   /** A unique id for the checkbox input. If none is supplied, it will be auto-generated. */

tools/public_api_guard/material/checkbox.d.ts

@@ -17,6 +17,7 @@ export declare class MatCheckbox extends _MatCheckboxMixinBase implements Contro
     _animationMode?: string | undefined;
     _inputElement: ElementRef<HTMLInputElement>;
     _onTouched: () => any;
+    ariaDescribedby: string;
     ariaLabel: string;
     ariaLabelledby: string | null;
     readonly change: EventEmitter<MatCheckboxChange>;
@@ -55,7 +56,7 @@ export declare class MatCheckbox extends _MatCheckboxMixinBase implements Contro
     static ngAcceptInputType_disabled: BooleanInput;
     static ngAcceptInputType_indeterminate: BooleanInput;
     static ngAcceptInputType_required: BooleanInput;
-    static ɵcmp: i0.ɵɵComponentDefWithMeta<MatCheckbox, "mat-checkbox", ["matCheckbox"], { "disableRipple": "disableRipple"; "color": "color"; "tabIndex": "tabIndex"; "ariaLabel": "aria-label"; "ariaLabelledby": "aria-labelledby"; "id": "id"; "required": "required"; "labelPosition": "labelPosition"; "name": "name"; "value": "value"; "checked": "checked"; "disabled": "disabled"; "indeterminate": "indeterminate"; }, { "change": "change"; "indeterminateChange": "indeterminateChange"; }, never, ["*"]>;
+    static ɵcmp: i0.ɵɵComponentDefWithMeta<MatCheckbox, "mat-checkbox", ["matCheckbox"], { "disableRipple": "disableRipple"; "color": "color"; "tabIndex": "tabIndex"; "ariaLabel": "aria-label"; "ariaLabelledby": "aria-labelledby"; "ariaDescribedby": "aria-describedby"; "id": "id"; "required": "required"; "labelPosition": "labelPosition"; "name": "name"; "value": "value"; "checked": "checked"; "disabled": "disabled"; "indeterminate": "indeterminate"; }, { "change": "change"; "indeterminateChange": "indeterminateChange"; }, never, ["*"]>;
     static ɵfac: i0.ɵɵFactoryDef<MatCheckbox, [null, null, null, null, { attribute: "tabindex"; }, { optional: true; }, { optional: true; }, { optional: true; }]>;
 }