feat(material/checkbox): add new aria properties to MatCheckbox (#29457)

* feat(material/checkbox): add new aria properties to MatCheckbox Added three new aria properties to MatCheckbox: `aria-expanded`: Indicates whether the checkbox controls the visibility of another element. This should be a boolean value (true or false). `aria-controls`: Specifies the ID of the element that the checkbox controls. `aria-owns`: Specifies the ID of the element that the checkbox visually owns. These attributes will be added to the generated checkbox element if they are specified and won't be present in the HTML if not provided. Also added a small paragraph at the end of the checkbox.md file. Fixes #28761 * feat(material/checkbox): add new aria properties to MatCheckbox Added three new aria properties to MatCheckbox: `aria-expanded`: Indicates whether the checkbox controls the visibility of another element. This should be a boolean value (true or false). `aria-controls`: Specifies the ID of the element that the checkbox controls. `aria-owns`: Specifies the ID of the element that the checkbox visually owns. These attributes will be added to the generated checkbox element if they are specified and won't be present in the HTML if not provided. Also added a small paragraph at the end of the checkbox.md file. Fixes #28761 * feat(material/checkbox): add new aria properties to MatCheckbox Added three new aria properties to MatCheckbox: `aria-expanded`: Indicates whether the checkbox controls the visibility of another element. This should be a boolean value (true or false). `aria-controls`: Specifies the ID of the element that the checkbox controls. `aria-owns`: Specifies the ID of the element that the checkbox visually owns. These attributes will be added to the generated checkbox element if they are specified and won't be present in the HTML if not provided. Also added a small paragraph at the end of the checkbox.md file. Fixes #28761
angular · Sep 10, 2024 · 9122335 · 9122335
1 parent 3a62ab1
commit 9122335
Show file tree

Hide file tree

Showing 5 changed files with 148 additions and 1 deletion.
diff --git a/src/material/checkbox/checkbox.html b/src/material/checkbox/checkbox.html
@@ -10,7 +10,10 @@
            [attr.aria-labelledby]="ariaLabelledby"
            [attr.aria-describedby]="ariaDescribedby"
            [attr.aria-checked]="indeterminate ? 'mixed' : null"
+           [attr.aria-controls]="ariaControls"
            [attr.aria-disabled]="disabled && disabledInteractive ? true : null"
+           [attr.aria-expanded]="ariaExpanded"
+           [attr.aria-owns]="ariaOwns"
            [attr.name]="name"
            [attr.value]="value"
            [checked]="checked"

diff --git a/src/material/checkbox/checkbox.md b/src/material/checkbox/checkbox.md
@@ -74,3 +74,9 @@ binding these properties, as demonstrated below.
 <mat-checkbox [aria-label]="isSubscribedToEmailsMessage">
 </mat-checkbox>
 ```
+
+Additionally, `MatCheckbox` now supports the following accessibility properties:
+
+- **`aria-expanded`**: Indicates whether the checkbox controls the visibility of another element. This should be a boolean value (`true` or `false`).
+- **`aria-controls`**: Specifies the ID of the element that the checkbox controls.
+- **`aria-owns`**: Specifies the ID of the element that the checkbox visually owns.
diff --git a/src/material/checkbox/checkbox.spec.ts b/src/material/checkbox/checkbox.spec.ts
@@ -807,6 +807,94 @@ describe('MatCheckbox', () => {
     });
   });
 
+  describe('with provided aria-expanded', () => {
+    let checkboxDebugElement: DebugElement;
+    let checkboxNativeElement: HTMLElement;
+    let inputElement: HTMLInputElement;
+
+    it('should use the provided postive aria-expanded', () => {
+      fixture = createComponent(CheckboxWithPositiveAriaExpanded);
+      checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
+      checkboxNativeElement = checkboxDebugElement.nativeElement;
+      inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');
+
+      fixture.detectChanges();
+      expect(inputElement.getAttribute('aria-expanded')).toBe('true');
+    });
+
+    it('should use the provided negative aria-expanded', () => {
+      fixture = createComponent(CheckboxWithNegativeAriaExpanded);
+      checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
+      checkboxNativeElement = checkboxDebugElement.nativeElement;
+      inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');
+
+      fixture.detectChanges();
+      expect(inputElement.getAttribute('aria-expanded')).toBe('false');
+    });
+
+    it('should not assign aria-expanded 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-expanded')).toBe(null);
+    });
+  });
+
+  describe('with provided aria-controls', () => {
+    let checkboxDebugElement: DebugElement;
+    let checkboxNativeElement: HTMLElement;
+    let inputElement: HTMLInputElement;
+
+    it('should use the provided aria-controls', () => {
+      fixture = createComponent(CheckboxWithAriaControls);
+      checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
+      checkboxNativeElement = checkboxDebugElement.nativeElement;
+      inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');
+
+      fixture.detectChanges();
+      expect(inputElement.getAttribute('aria-controls')).toBe('some-id');
+    });
+
+    it('should not assign aria-controls 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-controls')).toBe(null);
+    });
+  });
+
+  describe('with provided aria-owns', () => {
+    let checkboxDebugElement: DebugElement;
+    let checkboxNativeElement: HTMLElement;
+    let inputElement: HTMLInputElement;
+
+    it('should use the provided aria-owns', () => {
+      fixture = createComponent(CheckboxWithAriaOwns);
+      checkboxDebugElement = fixture.debugElement.query(By.directive(MatCheckbox))!;
+      checkboxNativeElement = checkboxDebugElement.nativeElement;
+      inputElement = <HTMLInputElement>checkboxNativeElement.querySelector('input');
+
+      fixture.detectChanges();
+      expect(inputElement.getAttribute('aria-owns')).toBe('some-id');
+    });
+
+    it('should not assign aria-owns 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-owns')).toBe(null);
+    });
+  });
+
   describe('with provided tabIndex', () => {
     let checkboxDebugElement: DebugElement;
     let checkboxNativeElement: HTMLElement;
@@ -1237,6 +1325,38 @@ class CheckboxWithAriaLabelledby {}
 })
 class CheckboxWithAriaDescribedby {}
 
+/** Simple test component with an aria-expanded set with true. */
+@Component({
+  template: `<mat-checkbox aria-expanded="true"></mat-checkbox>`,
+  standalone: true,
+  imports: [MatCheckbox],
+})
+class CheckboxWithPositiveAriaExpanded {}
+
+/** Simple test component with an aria-expanded set with false. */
+@Component({
+  template: `<mat-checkbox aria-expanded="false"></mat-checkbox>`,
+  standalone: true,
+  imports: [MatCheckbox],
+})
+class CheckboxWithNegativeAriaExpanded {}
+
+/** Simple test component with an aria-controls set. */
+@Component({
+  template: `<mat-checkbox aria-controls="some-id"></mat-checkbox>`,
+  standalone: true,
+  imports: [MatCheckbox],
+})
+class CheckboxWithAriaControls {}
+
+/** Simple test component with an aria-owns set. */
+@Component({
+  template: `<mat-checkbox aria-owns="some-id"></mat-checkbox>`,
+  standalone: true,
+  imports: [MatCheckbox],
+})
+class CheckboxWithAriaOwns {}
+
 /** Simple test component with name attribute */
 @Component({
   template: `<mat-checkbox name="test-name"></mat-checkbox>`,

diff --git a/src/material/checkbox/checkbox.ts b/src/material/checkbox/checkbox.ts
@@ -160,6 +160,19 @@ export class MatCheckbox
   /** The 'aria-describedby' attribute is read after the element's label and field type. */
   @Input('aria-describedby') ariaDescribedby: string;
 
+  /**
+   * Users can specify the `aria-expanded` attribute which will be forwarded to the input element
+   */
+  @Input({alias: 'aria-expanded', transform: booleanAttribute}) ariaExpanded: boolean;
+
+  /**
+   * Users can specify the `aria-controls` attribute which will be forwarded to the input element
+   */
+  @Input('aria-controls') ariaControls: string;
+
+  /** Users can specify the `aria-owns` attribute which will be forwarded to the input element */
+  @Input('aria-owns') ariaOwns: string;
+
   private _uniqueId: string;
 
   /** A unique id for the checkbox input. If none is supplied, it will be auto-generated. */

diff --git a/tools/public_api_guard/material/checkbox.md b/tools/public_api_guard/material/checkbox.md
@@ -48,9 +48,12 @@ export class MatCheckbox implements AfterViewInit, OnChanges, ControlValueAccess
     };
     // (undocumented)
     _animationMode?: string | undefined;
+    ariaControls: string;
     ariaDescribedby: string;
+    ariaExpanded: boolean;
     ariaLabel: string;
     ariaLabelledby: string | null;
+    ariaOwns: string;
     readonly change: EventEmitter<MatCheckboxChange>;
     get checked(): boolean;
     set checked(value: boolean);
@@ -78,6 +81,8 @@ export class MatCheckbox implements AfterViewInit, OnChanges, ControlValueAccess
     labelPosition: 'before' | 'after';
     name: string | null;
     // (undocumented)
+    static ngAcceptInputType_ariaExpanded: unknown;
+    // (undocumented)
     static ngAcceptInputType_checked: unknown;
     // (undocumented)
     static ngAcceptInputType_disabled: unknown;
@@ -123,7 +128,7 @@ export class MatCheckbox implements AfterViewInit, OnChanges, ControlValueAccess
     // (undocumented)
     writeValue(value: any): void;
     // (undocumented)
-    static ɵcmp: i0.ɵɵComponentDeclaration<MatCheckbox, "mat-checkbox", ["matCheckbox"], { "ariaLabel": { "alias": "aria-label"; "required": false; }; "ariaLabelledby": { "alias": "aria-labelledby"; "required": false; }; "ariaDescribedby": { "alias": "aria-describedby"; "required": false; }; "id": { "alias": "id"; "required": false; }; "required": { "alias": "required"; "required": false; }; "labelPosition": { "alias": "labelPosition"; "required": false; }; "name": { "alias": "name"; "required": false; }; "value": { "alias": "value"; "required": false; }; "disableRipple": { "alias": "disableRipple"; "required": false; }; "tabIndex": { "alias": "tabIndex"; "required": false; }; "color": { "alias": "color"; "required": false; }; "disabledInteractive": { "alias": "disabledInteractive"; "required": false; }; "checked": { "alias": "checked"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "indeterminate": { "alias": "indeterminate"; "required": false; }; }, { "change": "change"; "indeterminateChange": "indeterminateChange"; }, never, ["*"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MatCheckbox, "mat-checkbox", ["matCheckbox"], { "ariaLabel": { "alias": "aria-label"; "required": false; }; "ariaLabelledby": { "alias": "aria-labelledby"; "required": false; }; "ariaDescribedby": { "alias": "aria-describedby"; "required": false; }; "ariaExpanded": { "alias": "aria-expanded"; "required": false; }; "ariaControls": { "alias": "aria-controls"; "required": false; }; "ariaOwns": { "alias": "aria-owns"; "required": false; }; "id": { "alias": "id"; "required": false; }; "required": { "alias": "required"; "required": false; }; "labelPosition": { "alias": "labelPosition"; "required": false; }; "name": { "alias": "name"; "required": false; }; "value": { "alias": "value"; "required": false; }; "disableRipple": { "alias": "disableRipple"; "required": false; }; "tabIndex": { "alias": "tabIndex"; "required": false; }; "color": { "alias": "color"; "required": false; }; "disabledInteractive": { "alias": "disabledInteractive"; "required": false; }; "checked": { "alias": "checked"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "indeterminate": { "alias": "indeterminate"; "required": false; }; }, { "change": "change"; "indeterminateChange": "indeterminateChange"; }, never, ["*"], true, never>;
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<MatCheckbox, [null, null, null, { attribute: "tabindex"; }, { optional: true; }, { optional: true; }]>;
 }