feat(material/tabs): Refactor MatTabNav to follow the ARIA tabs pattern

by introducing a new tabpanel component.

Author: zelliott

src/components-examples/material/tabs/index.ts

@@ -20,6 +20,7 @@ import {TabGroupLazyLoadedExample} from './tab-group-lazy-loaded/tab-group-lazy-
 import {TabGroupStretchedExample} from './tab-group-stretched/tab-group-stretched-example';
 import {TabGroupThemeExample} from './tab-group-theme/tab-group-theme-example';
 import {TabNavBarBasicExample} from './tab-nav-bar-basic/tab-nav-bar-basic-example';
+import {TabNavBarWithPanelExample} from './tab-nav-bar-with-panel/tab-nav-bar-with-panel-example';
 
 export {
   TabGroupAlignExample,
@@ -35,6 +36,7 @@ export {
   TabGroupStretchedExample,
   TabGroupThemeExample,
   TabNavBarBasicExample,
+  TabNavBarWithPanelExample,
 };
 
 const EXAMPLES = [
@@ -51,6 +53,7 @@ const EXAMPLES = [
   TabGroupStretchedExample,
   TabGroupThemeExample,
   TabNavBarBasicExample,
+  TabNavBarWithPanelExample,
 ];
 
 @NgModule({

src/components-examples/material/tabs/tab-nav-bar-with-panel/tab-nav-bar-with-panel-example.css

@@ -0,0 +1,4 @@
+.example-action-button {
+  margin-top: 8px;
+  margin-right: 8px;
+}

src/components-examples/material/tabs/tab-nav-bar-with-panel/tab-nav-bar-with-panel-example.html

@@ -0,0 +1,16 @@
+<!-- #docregion mat-tab-nav -->
+<nav mat-tab-nav-bar [backgroundColor]="background" [tabPanel]="tabPanel">
+  <a mat-tab-link *ngFor="let link of links"
+     (click)="activeLink = link"
+     [active]="activeLink == link"> {{link}} </a>
+  <a mat-tab-link disabled>Disabled Link</a>
+</nav>
+<mat-tab-nav-panel #tabPanel></mat-tab-nav-panel>
+<!-- #enddocregion mat-tab-nav -->
+
+<button mat-raised-button class="example-action-button" (click)="toggleBackground()">
+  Toggle background
+</button>
+<button mat-raised-button class="example-action-button" (click)="addLink()">
+  Add link
+</button>

src/components-examples/material/tabs/tab-nav-bar-with-panel/tab-nav-bar-with-panel-example.ts

@@ -0,0 +1,24 @@
+import {Component} from '@angular/core';
+import {ThemePalette} from '@angular/material/core';
+
+/**
+ * @title Use of the tab nav bar with the dedicated panel component.
+ */
+@Component({
+  selector: 'tab-nav-bar-with-panel-example',
+  templateUrl: 'tab-nav-bar-with-panel-example.html',
+  styleUrls: ['tab-nav-bar-with-panel-example.css'],
+})
+export class TabNavBarWithPanelExample {
+  links = ['First', 'Second', 'Third'];
+  activeLink = this.links[0];
+  background: ThemePalette = undefined;
+
+  toggleBackground() {
+    this.background = this.background ? undefined : 'primary';
+  }
+
+  addLink() {
+    this.links.push(`Link ${this.links.length + 1}`);
+  }
+}

src/dev-app/mdc-tabs/mdc-tabs-demo.html

@@ -127,4 +127,13 @@ <h2>Tab nav bar</h2>
       [active]="activeLink == link">{{link}}</a>
     <a mat-tab-link disabled>Disabled Link</a>
   </nav>
+
+  <h2>Tab nav bar with panel</h2>
+  <nav mat-tab-nav-bar [tabPanel]="tabPanel">
+    <a mat-tab-link *ngFor="let link of links"
+      (click)="activeLink = link"
+      [active]="activeLink == link">{{link}}</a>
+    <a mat-tab-link disabled>Disabled Link</a>
+  </nav>
+  <mat-tab-nav-panel #tabPanel></mat-tab-nav-panel>
 </div>

src/dev-app/tabs/tabs-demo.html

@@ -18,5 +18,7 @@ <h3>Tab group stretched</h3>
 <tab-group-stretched-example></tab-group-stretched-example>
 <h3>Tab group theming</h3>
 <tab-group-theme-example></tab-group-theme-example>
-<h3>Tab Navigation Bar basic</h3>
+<h3>Tab navigation bar basic</h3>
 <tab-nav-bar-basic-example></tab-nav-bar-basic-example>
+<h3>Tab navigation bar with panel</h3>
+<tab-nav-bar-with-panel-example></tab-nav-bar-with-panel-example>

src/material-experimental/mdc-tabs/module.ts

@@ -19,7 +19,7 @@ import {MatTabLabelWrapper} from './tab-label-wrapper';
 import {MatTab} from './tab';
 import {MatTabHeader} from './tab-header';
 import {MatTabGroup} from './tab-group';
-import {MatTabNav, MatTabLink} from './tab-nav-bar/tab-nav-bar';
+import {MatTabNav, MatTabNavPanel, MatTabLink} from './tab-nav-bar/tab-nav-bar';
 
 @NgModule({
   imports: [
@@ -37,6 +37,7 @@ import {MatTabNav, MatTabLink} from './tab-nav-bar/tab-nav-bar';
     MatTab,
     MatTabGroup,
     MatTabNav,
+    MatTabNavPanel,
     MatTabLink,
   ],
   declarations: [
@@ -45,6 +46,7 @@ import {MatTabNav, MatTabLink} from './tab-nav-bar/tab-nav-bar';
     MatTab,
     MatTabGroup,
     MatTabNav,
+    MatTabNavPanel,
     MatTabLink,
 
     // Private directives, should not be exported.

src/material-experimental/mdc-tabs/public-api.ts

@@ -15,7 +15,7 @@ export {MatTab} from './tab';
 export {MatInkBar} from './ink-bar';
 export {MatTabHeader} from './tab-header';
 export {MatTabGroup} from './tab-group';
-export {MatTabNav, MatTabLink} from './tab-nav-bar/tab-nav-bar';
+export {MatTabNav, MatTabNavPanel, MatTabLink} from './tab-nav-bar/tab-nav-bar';
 
 export {
   MatTabBodyPositionState,

src/material-experimental/mdc-tabs/tab-nav-bar/tab-nav-bar.ts

@@ -56,6 +56,7 @@ import {takeUntil} from 'rxjs/operators';
   templateUrl: 'tab-nav-bar.html',
   styleUrls: ['tab-nav-bar.css'],
   host: {
+    '[attr.role]': 'panel ? "tablist" : null',
     'class': 'mat-mdc-tab-nav-bar mat-mdc-tab-header',
     '[class.mat-mdc-tab-header-pagination-controls-enabled]': '_showPaginationControls',
     '[class.mat-mdc-tab-header-rtl]': "_getLayoutDirection() == 'rtl'",
@@ -130,12 +131,16 @@ export class MatTabNav extends _MatTabNavBase implements AfterContentInit {
   styleUrls: ['tab-link.css'],
   host: {
     'class': 'mdc-tab mat-mdc-tab-link mat-mdc-focus-indicator',
-    '[attr.aria-current]': 'active ? "page" : null',
+    '[attr.aria-controls]': '_tabNavBar.tabPanel ? _tabNavBar.tabPanel.id : null',
+    '[attr.aria-current]': '(active && !_tabNavBar.tabPanel) ? "page" : null',
     '[attr.aria-disabled]': 'disabled',
-    '[attr.tabIndex]': 'tabIndex',
+    '[attr.aria-selected]': '_tabNavBar.tabPanel ? (active ? "true" : "false") : null',
+    '[attr.id]': 'id',
+    '[attr.tabIndex]': '_getTabIndex()',
     '[class.mat-mdc-tab-disabled]': 'disabled',
     '[class.mdc-tab--active]': 'active',
     '(focus)': '_handleFocus()',
+    '(keydown)': '_handleKeydown($event)',
   },
 })
 export class MatTabLink extends _MatTabLinkBase implements MatInkBarItem, OnInit, OnDestroy {
@@ -170,3 +175,29 @@ export class MatTabLink extends _MatTabLinkBase implements MatInkBarItem, OnInit
     this._foundation.destroy();
   }
 }
+
+// Increasing integer for generating unique ids for tab nav components.
+let nextUniqueId = 0;
+
+/**
+ * Tab panel component associated with MatTabNav.
+ */
+@Component({
+  selector: 'mat-tab-nav-panel',
+  exportAs: 'matTabNavPanel',
+  template: '<ng-content></ng-content>',
+  host: {
+    '[attr.aria-labelledby]': '_activeTabId',
+    '[attr.id]': 'id',
+    'role': 'tabpanel',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class MatTabNavPanel {
+  /** Unique id for the tab panel. */
+  @Input() id = `mat-tab-nav-panel-${nextUniqueId++}`;
+
+  /** Id of the active tab in the nav bar. */
+  _activeTabId?: string;
+}

src/material/tabs/public-api.ts

@@ -20,7 +20,13 @@ export {MatTabHeader, _MatTabHeaderBase} from './tab-header';
 export {MatTabLabelWrapper} from './tab-label-wrapper';
 export {MatTab, MAT_TAB_GROUP} from './tab';
 export {MatTabLabel, MAT_TAB} from './tab-label';
-export {MatTabNav, MatTabLink, _MatTabNavBase, _MatTabLinkBase} from './tab-nav-bar/index';
+export {
+  MatTabNav,
+  MatTabLink,
+  MatTabNavPanel,
+  _MatTabNavBase,
+  _MatTabLinkBase,
+} from './tab-nav-bar/index';
 export {MatTabContent} from './tab-content';
 export {ScrollDirection} from './paginated-tab-header';
 export * from './tabs-animations';

src/material/tabs/tab-nav-bar/tab-nav-bar.ts

@@ -6,6 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 import {FocusableOption, FocusMonitor} from '@angular/cdk/a11y';
+import {SPACE} from '@angular/cdk/keycodes';
 import {Directionality} from '@angular/cdk/bidi';
 import {BooleanInput, coerceBooleanProperty, NumberInput} from '@angular/cdk/coercion';
 import {Platform} from '@angular/cdk/platform';
@@ -50,6 +51,9 @@ import {startWith, takeUntil} from 'rxjs/operators';
 import {MatInkBar} from '../ink-bar';
 import {MatPaginatedTabHeader, MatPaginatedTabHeaderItem} from '../paginated-tab-header';
 
+// Increasing integer for generating unique ids for tab nav components.
+let nextUniqueId = 0;
+
 /**
  * Base class with all of the `MatTabNav` functionality.
  * @docs-private
@@ -60,7 +64,9 @@ export abstract class _MatTabNavBase
   implements AfterContentChecked, AfterContentInit, OnDestroy
 {
   /** Query list of all tab links of the tab navigation. */
-  abstract override _items: QueryList<MatPaginatedTabHeaderItem & {active: boolean}>;
+  abstract override _items: QueryList<
+    MatPaginatedTabHeaderItem & {active: boolean; id: string; index: number}
+  >;
 
   /** Background color of the tab nav. */
   @Input()
@@ -92,6 +98,13 @@ export abstract class _MatTabNavBase
   /** Theme color of the nav bar. */
   @Input() color: ThemePalette = 'primary';
 
+  /**
+   * Associated tab panel controlled by the nav bar. If not provided, then the nav bar
+   * follows the ARIA link / navigation landmark pattern. If provided, it follows the
+   * ARIA tabs design pattern.
+   */
+  @Input() tabPanel?: MatTabNavPanel;
+
   constructor(
     elementRef: ElementRef,
     @Optional() dir: Directionality,
@@ -113,6 +126,7 @@ export abstract class _MatTabNavBase
     // selectedIndex is up-to-date by the time the super class starts looking for it.
     this._items.changes.pipe(startWith(null), takeUntil(this._destroyed)).subscribe(() => {
       this.updateActiveLink();
+      this.updateIndices();
     });
 
     super.ngAfterContentInit();
@@ -130,6 +144,11 @@ export abstract class _MatTabNavBase
       if (items[i].active) {
         this.selectedIndex = i;
         this._changeDetectorRef.markForCheck();
+
+        if (this.tabPanel) {
+          this.tabPanel._activeTabId = items[i].id;
+        }
+
         return;
       }
     }
@@ -138,6 +157,19 @@ export abstract class _MatTabNavBase
     this.selectedIndex = -1;
     this._inkBar.hide();
   }
+
+  /** Updates the indices of the tabs within the nav bar. */
+  updateIndices() {
+    if (!this._items) {
+      return;
+    }
+
+    const items = this._items.toArray();
+
+    for (let i = 0; i < items.length; i++) {
+      items[i].index = i;
+    }
+  }
 }
 
 /**
@@ -151,6 +183,7 @@ export abstract class _MatTabNavBase
   templateUrl: 'tab-nav-bar.html',
   styleUrls: ['tab-nav-bar.css'],
   host: {
+    '[attr.role]': 'panel ? "tablist" : null',
     'class': 'mat-tab-nav-bar mat-tab-header',
     '[class.mat-tab-header-pagination-controls-enabled]': '_showPaginationControls',
     '[class.mat-tab-header-rtl]': "_getLayoutDirection() == 'rtl'",
@@ -240,6 +273,12 @@ export class _MatTabLinkBase
     );
   }
 
+  /** Unique id for the tab. */
+  @Input() id = `mat-tab-link-${nextUniqueId++}`;
+
+  /** Index of the tab within the nav bar. Managed by the nav bar. */
+  index = -1;
+
   constructor(
     private _tabNavBar: _MatTabNavBase,
     /** @docs-private */ public elementRef: ElementRef,
@@ -274,7 +313,26 @@ export class _MatTabLinkBase
   _handleFocus() {
     // Since we allow navigation through tabbing in the nav bar, we
     // have to update the focused index whenever the link receives focus.
-    this._tabNavBar.focusIndex = this._tabNavBar._items.toArray().indexOf(this);
+    this._tabNavBar.focusIndex = this.index;
+  }
+
+  _handleKeydown(event: KeyboardEvent) {
+    if (this._tabNavBar.tabPanel && event.keyCode === SPACE) {
+      this.elementRef.nativeElement.click();
+    }
+  }
+
+  /** Returns the tab's tabindex. */
+  _getTabIndex(): number {
+    if (!this._tabNavBar.tabPanel) {
+      return this.tabIndex;
+    }
+
+    if (!this._tabNavBar._items) {
+      return this._isActive ? 0 : -1;
+    }
+
+    return this._tabNavBar.focusIndex === this.index ? 0 : -1;
   }
 
   static ngAcceptInputType_active: BooleanInput;
@@ -292,12 +350,17 @@ export class _MatTabLinkBase
   inputs: ['disabled', 'disableRipple', 'tabIndex'],
   host: {
     'class': 'mat-tab-link mat-focus-indicator',
-    '[attr.aria-current]': 'active ? "page" : null',
+    '[attr.aria-controls]': '_tabNavBar.tabPanel ? _tabNavBar.tabPanel.id : null',
+    '[attr.aria-current]': '(active && !_tabNavBar.tabPanel) ? "page" : null',
     '[attr.aria-disabled]': 'disabled',
-    '[attr.tabIndex]': 'tabIndex',
+    '[attr.aria-selected]': '_tabNavBar.tabPanel ? (active ? "true" : "false") : null',
+    '[attr.id]': 'id',
+    '[attr.tabIndex]': '_getTabIndex()',
+    '[attr.role]': '_tabNavBar.tabPanel ? "tab" : null',
     '[class.mat-tab-disabled]': 'disabled',
     '[class.mat-tab-label-active]': 'active',
     '(focus)': '_handleFocus()',
+    '(keydown)': '_handleKeydown($event)',
   },
 })
 export class MatTabLink extends _MatTabLinkBase implements OnDestroy {
@@ -324,3 +387,26 @@ export class MatTabLink extends _MatTabLinkBase implements OnDestroy {
     this._tabLinkRipple._removeTriggerEvents();
   }
 }
+
+/**
+ * Tab panel component associated with MatTabNav.
+ */
+@Component({
+  selector: 'mat-tab-nav-panel',
+  exportAs: 'matTabNavPanel',
+  template: '<ng-content></ng-content>',
+  host: {
+    '[attr.aria-labelledby]': '_activeTabId',
+    '[attr.id]': 'id',
+    'role': 'tabpanel',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class MatTabNavPanel {
+  /** Unique id for the tab panel. */
+  @Input() id = `mat-tab-nav-panel-${nextUniqueId++}`;
+
+  /** Id of the active tab in the nav bar. */
+  _activeTabId?: string;
+}