fix(material/tabs): allow for tablist aria-label and aria-labelledby …

…to be set (#29562)

According to the [W3C reference implementation](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/), the inner `tablist` can be labelled using `aria-label` or `aria-labelledby`. These changes add an input to allow them to be set.

Fixes #29486.

(cherry picked from commit 1968cc4)

src/material/tabs/tab-group.html

@@ -2,6 +2,8 @@
                 [selectedIndex]="selectedIndex || 0"
                 [disableRipple]="disableRipple"
                 [disablePagination]="disablePagination"
+                [aria-label]="ariaLabel"
+                [aria-labelledby]="ariaLabelledby"
                 (indexFocused)="_focusChanged($event)"
                 (selectFocusedIndex)="selectedIndex = $event">
 

src/material/tabs/tab-group.spec.ts

@@ -409,6 +409,42 @@ describe('MatTabGroup', () => {
 
       expect(tabLabels.map(label => label.getAttribute('tabindex'))).toEqual(['-1', '-1', '0']);
     });
+
+    it('should be able to set the aria-label of the tablist', fakeAsync(() => {
+      fixture.detectChanges();
+      tick();
+
+      const tabList = fixture.nativeElement.querySelector('.mat-mdc-tab-list') as HTMLElement;
+      expect(tabList.hasAttribute('aria-label')).toBe(false);
+
+      fixture.componentInstance.ariaLabel = 'hello';
+      fixture.changeDetectorRef.markForCheck();
+      fixture.detectChanges();
+      expect(tabList.getAttribute('aria-label')).toBe('hello');
+
+      fixture.componentInstance.ariaLabel = '';
+      fixture.changeDetectorRef.markForCheck();
+      fixture.detectChanges();
+      expect(tabList.hasAttribute('aria-label')).toBe(false);
+    }));
+
+    it('should be able to set the aria-labelledby of the tablist', fakeAsync(() => {
+      fixture.detectChanges();
+      tick();
+
+      const tabList = fixture.nativeElement.querySelector('.mat-mdc-tab-list') as HTMLElement;
+      expect(tabList.hasAttribute('aria-labelledby')).toBe(false);
+
+      fixture.componentInstance.ariaLabelledby = 'some-label';
+      fixture.changeDetectorRef.markForCheck();
+      fixture.detectChanges();
+      expect(tabList.getAttribute('aria-labelledby')).toBe('some-label');
+
+      fixture.componentInstance.ariaLabelledby = '';
+      fixture.changeDetectorRef.markForCheck();
+      fixture.detectChanges();
+      expect(tabList.hasAttribute('aria-labelledby')).toBe(false);
+    }));
   });
 
   describe('aria labelling', () => {
@@ -1159,6 +1195,8 @@ describe('MatTabNavBar with a default config', () => {
         [headerPosition]="headerPosition"
         [disableRipple]="disableRipple"
         [contentTabIndex]="contentTabIndex"
+        [aria-label]="ariaLabel"
+        [aria-labelledby]="ariaLabelledby"
         (animationDone)="animationDone()"
         (focusChange)="handleFocus($event)"
         (selectedTabChange)="handleSelection($event)">
@@ -1188,6 +1226,8 @@ class SimpleTabsTestApp {
   disableRipple: boolean = false;
   contentTabIndex: number | null = null;
   headerPosition: MatTabHeaderPosition = 'above';
+  ariaLabel: string;
+  ariaLabelledby: string;
   handleFocus(event: any) {
     this.focusEvent = event;
   }

src/material/tabs/tab-group.ts

@@ -242,6 +242,12 @@ export class MatTabGroup implements AfterContentInit, AfterContentChecked, OnDes
 
   private _backgroundColor: ThemePalette;
 
+  /** Aria label of the inner `tablist` of the group. */
+  @Input('aria-label') ariaLabel: string;
+
+  /** Sets the `aria-labelledby` of the inner `tablist` of the group. */
+  @Input('aria-labelledby') ariaLabelledby: string;
+
   /** Output to enable support for two-way binding on `[(selectedIndex)]` */
   @Output() readonly selectedIndexChange: EventEmitter<number> = new EventEmitter<number>();
 

src/material/tabs/tab-header.html

@@ -22,6 +22,8 @@
     #tabList
     class="mat-mdc-tab-list"
     role="tablist"
+    [attr.aria-label]="ariaLabel || null"
+    [attr.aria-labelledby]="ariaLabelledby || null"
     (cdkObserveContent)="_onContentChanges()">
     <div class="mat-mdc-tab-labels" #tabListInner>
       <ng-content></ng-content>

src/material/tabs/tab-header.ts

@@ -69,6 +69,12 @@ export class MatTabHeader
   @ViewChild('previousPaginator') _previousPaginator: ElementRef<HTMLElement>;
   _inkBar: MatInkBar;
 
+  /** Aria label of the header. */
+  @Input('aria-label') ariaLabel: string;
+
+  /** Sets the `aria-labelledby` of the header. */
+  @Input('aria-labelledby') ariaLabelledby: string;
+
   /** Whether the ripple effect is disabled or not. */
   @Input({transform: booleanAttribute})
   disableRipple: boolean = false;

tools/public_api_guard/material/tabs.md

@@ -259,6 +259,8 @@ export class MatTabGroup implements AfterContentInit, AfterContentChecked, OnDes
     set animationDuration(value: string | number);
     // (undocumented)
     _animationMode?: string | undefined;
+    ariaLabel: string;
+    ariaLabelledby: string;
     // @deprecated
     get backgroundColor(): ThemePalette;
     set backgroundColor(value: ThemePalette);
@@ -320,7 +322,7 @@ export class MatTabGroup implements AfterContentInit, AfterContentChecked, OnDes
     _tabs: QueryList<MatTab>;
     updatePagination(): void;
     // (undocumented)
-    static ɵcmp: i0.ɵɵComponentDeclaration<MatTabGroup, "mat-tab-group", ["matTabGroup"], { "color": { "alias": "color"; "required": false; }; "fitInkBarToContent": { "alias": "fitInkBarToContent"; "required": false; }; "stretchTabs": { "alias": "mat-stretch-tabs"; "required": false; }; "dynamicHeight": { "alias": "dynamicHeight"; "required": false; }; "selectedIndex": { "alias": "selectedIndex"; "required": false; }; "headerPosition": { "alias": "headerPosition"; "required": false; }; "animationDuration": { "alias": "animationDuration"; "required": false; }; "contentTabIndex": { "alias": "contentTabIndex"; "required": false; }; "disablePagination": { "alias": "disablePagination"; "required": false; }; "disableRipple": { "alias": "disableRipple"; "required": false; }; "preserveContent": { "alias": "preserveContent"; "required": false; }; "backgroundColor": { "alias": "backgroundColor"; "required": false; }; }, { "selectedIndexChange": "selectedIndexChange"; "focusChange": "focusChange"; "animationDone": "animationDone"; "selectedTabChange": "selectedTabChange"; }, ["_allTabs"], ["*"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MatTabGroup, "mat-tab-group", ["matTabGroup"], { "color": { "alias": "color"; "required": false; }; "fitInkBarToContent": { "alias": "fitInkBarToContent"; "required": false; }; "stretchTabs": { "alias": "mat-stretch-tabs"; "required": false; }; "dynamicHeight": { "alias": "dynamicHeight"; "required": false; }; "selectedIndex": { "alias": "selectedIndex"; "required": false; }; "headerPosition": { "alias": "headerPosition"; "required": false; }; "animationDuration": { "alias": "animationDuration"; "required": false; }; "contentTabIndex": { "alias": "contentTabIndex"; "required": false; }; "disablePagination": { "alias": "disablePagination"; "required": false; }; "disableRipple": { "alias": "disableRipple"; "required": false; }; "preserveContent": { "alias": "preserveContent"; "required": false; }; "backgroundColor": { "alias": "backgroundColor"; "required": false; }; "ariaLabel": { "alias": "aria-label"; "required": false; }; "ariaLabelledby": { "alias": "aria-labelledby"; "required": false; }; }, { "selectedIndexChange": "selectedIndexChange"; "focusChange": "focusChange"; "animationDone": "animationDone"; "selectedTabChange": "selectedTabChange"; }, ["_allTabs"], ["*"], true, never>;
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<MatTabGroup, [null, null, { optional: true; }, { optional: true; }]>;
 }
@@ -338,6 +340,8 @@ export interface MatTabGroupBaseHeader {
 // @public
 export class MatTabHeader extends MatPaginatedTabHeader implements AfterContentChecked, AfterContentInit, AfterViewInit, OnDestroy {
     constructor(elementRef: ElementRef, changeDetectorRef: ChangeDetectorRef, viewportRuler: ViewportRuler, dir: Directionality, ngZone: NgZone, platform: Platform, animationMode?: string);
+    ariaLabel: string;
+    ariaLabelledby: string;
     disableRipple: boolean;
     // (undocumented)
     _inkBar: MatInkBar;
@@ -360,7 +364,7 @@ export class MatTabHeader extends MatPaginatedTabHeader implements AfterContentC
     // (undocumented)
     _tabListInner: ElementRef;
     // (undocumented)
-    static ɵcmp: i0.ɵɵComponentDeclaration<MatTabHeader, "mat-tab-header", never, { "disableRipple": { "alias": "disableRipple"; "required": false; }; }, {}, ["_items"], ["*"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MatTabHeader, "mat-tab-header", never, { "ariaLabel": { "alias": "aria-label"; "required": false; }; "ariaLabelledby": { "alias": "aria-labelledby"; "required": false; }; "disableRipple": { "alias": "disableRipple"; "required": false; }; }, {}, ["_items"], ["*"], true, never>;
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<MatTabHeader, [null, null, null, { optional: true; }, null, null, { optional: true; }]>;
 }