From 4d86a92f31657e05ecd99686a8cfd3bfa9a633ad Mon Sep 17 00:00:00 2001
From: Zack Elliott <zell@google.com>
Date: Mon, 31 Jan 2022 10:02:10 -0800
Subject: [PATCH] docs(material/tabs): Update public documentation with new
 mat-tab-nav-bar/panel guidance (#24316)

* docs(material/tabs): Update public documentation with new mat-tab-nav-bar/panel guidance

* docs(material/tabs): Fixed in-page link

* docs(material/tabs): Fix demo bug
---
 .../material/tabs/index.ts                    |  9 ++----
 .../tab-nav-bar-basic-example.html            |  3 +-
 .../tab-nav-bar-with-panel-example.css        |  4 ---
 .../tab-nav-bar-with-panel-example.html       |  9 ------
 .../tab-nav-bar-with-panel-example.ts         | 14 --------
 src/dev-app/tabs/tabs-demo.html               |  2 --
 src/material/tabs/tabs.md                     | 32 +++++++------------
 7 files changed, 17 insertions(+), 56 deletions(-)
 delete mode 100644 src/components-examples/material/tabs/tab-nav-bar-with-panel/tab-nav-bar-with-panel-example.css
 delete mode 100644 src/components-examples/material/tabs/tab-nav-bar-with-panel/tab-nav-bar-with-panel-example.html
 delete mode 100644 src/components-examples/material/tabs/tab-nav-bar-with-panel/tab-nav-bar-with-panel-example.ts

diff --git a/src/components-examples/material/tabs/index.ts b/src/components-examples/material/tabs/index.ts
index cb5279b3487b..c13644947e89 100644
--- a/src/components-examples/material/tabs/index.ts
+++ b/src/components-examples/material/tabs/index.ts
@@ -1,26 +1,25 @@
 import {CommonModule} from '@angular/common';
-import {NgModule} from '@angular/core';
-import {ReactiveFormsModule} from '@angular/forms';
 import {MatButtonModule} from '@angular/material/button';
 import {MatButtonToggleModule} from '@angular/material/button-toggle';
 import {MatCheckboxModule} from '@angular/material/checkbox';
 import {MatIconModule} from '@angular/material/icon';
 import {MatInputModule} from '@angular/material/input';
 import {MatTabsModule} from '@angular/material/tabs';
+import {NgModule} from '@angular/core';
+import {ReactiveFormsModule} from '@angular/forms';
 import {TabGroupAlignExample} from './tab-group-align/tab-group-align-example';
 import {TabGroupAnimationsExample} from './tab-group-animations/tab-group-animations-example';
 import {TabGroupAsyncExample} from './tab-group-async/tab-group-async-example';
 import {TabGroupBasicExample} from './tab-group-basic/tab-group-basic-example';
 import {TabGroupCustomLabelExample} from './tab-group-custom-label/tab-group-custom-label-example';
+import {TabGroupDynamicExample} from './tab-group-dynamic/tab-group-dynamic-example';
 import {TabGroupDynamicHeightExample} from './tab-group-dynamic-height/tab-group-dynamic-height-example';
 import {TabGroupHarnessExample} from './tab-group-harness/tab-group-harness-example';
-import {TabGroupDynamicExample} from './tab-group-dynamic/tab-group-dynamic-example';
 import {TabGroupHeaderBelowExample} from './tab-group-header-below/tab-group-header-below-example';
 import {TabGroupLazyLoadedExample} from './tab-group-lazy-loaded/tab-group-lazy-loaded-example';
 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,
@@ -36,7 +35,6 @@ export {
   TabGroupStretchedExample,
   TabGroupThemeExample,
   TabNavBarBasicExample,
-  TabNavBarWithPanelExample,
 };
 
 const EXAMPLES = [
@@ -53,7 +51,6 @@ const EXAMPLES = [
   TabGroupStretchedExample,
   TabGroupThemeExample,
   TabNavBarBasicExample,
-  TabNavBarWithPanelExample,
 ];
 
 @NgModule({
diff --git a/src/components-examples/material/tabs/tab-nav-bar-basic/tab-nav-bar-basic-example.html b/src/components-examples/material/tabs/tab-nav-bar-basic/tab-nav-bar-basic-example.html
index e2c4ae4dea71..ff20e1723701 100644
--- a/src/components-examples/material/tabs/tab-nav-bar-basic/tab-nav-bar-basic-example.html
+++ b/src/components-examples/material/tabs/tab-nav-bar-basic/tab-nav-bar-basic-example.html
@@ -1,10 +1,11 @@
 <!-- #docregion mat-tab-nav -->
-<nav mat-tab-nav-bar [backgroundColor]="background">
+<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()">
diff --git a/src/components-examples/material/tabs/tab-nav-bar-with-panel/tab-nav-bar-with-panel-example.css b/src/components-examples/material/tabs/tab-nav-bar-with-panel/tab-nav-bar-with-panel-example.css
deleted file mode 100644
index e7f8daa5cd3b..000000000000
--- a/src/components-examples/material/tabs/tab-nav-bar-with-panel/tab-nav-bar-with-panel-example.css
+++ /dev/null
@@ -1,4 +0,0 @@
-.example-action-button {
-  margin-top: 8px;
-  margin-right: 8px;
-}
diff --git a/src/components-examples/material/tabs/tab-nav-bar-with-panel/tab-nav-bar-with-panel-example.html b/src/components-examples/material/tabs/tab-nav-bar-with-panel/tab-nav-bar-with-panel-example.html
deleted file mode 100644
index 1ab8a3c4da0f..000000000000
--- a/src/components-examples/material/tabs/tab-nav-bar-with-panel/tab-nav-bar-with-panel-example.html
+++ /dev/null
@@ -1,9 +0,0 @@
-<!-- #docregion mat-tab-nav -->
-<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>
-<!-- #enddocregion mat-tab-nav -->
diff --git a/src/components-examples/material/tabs/tab-nav-bar-with-panel/tab-nav-bar-with-panel-example.ts b/src/components-examples/material/tabs/tab-nav-bar-with-panel/tab-nav-bar-with-panel-example.ts
deleted file mode 100644
index b7beb7ae2e2f..000000000000
--- a/src/components-examples/material/tabs/tab-nav-bar-with-panel/tab-nav-bar-with-panel-example.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import {Component} from '@angular/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];
-}
diff --git a/src/dev-app/tabs/tabs-demo.html b/src/dev-app/tabs/tabs-demo.html
index 9531a56be77a..7fd61001693f 100644
--- a/src/dev-app/tabs/tabs-demo.html
+++ b/src/dev-app/tabs/tabs-demo.html
@@ -20,5 +20,3 @@ <h3>Tab group theming</h3>
 <tab-group-theme-example></tab-group-theme-example>
 <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>
diff --git a/src/material/tabs/tabs.md b/src/material/tabs/tabs.md
index 545775a6f989..a42eb6b7b325 100644
--- a/src/material/tabs/tabs.md
+++ b/src/material/tabs/tabs.md
@@ -46,9 +46,10 @@ provides a tab-like UI for navigating between routes.
                "file": "tab-nav-bar-basic-example.html",
                "region": "mat-tab-nav"}) -->
 
-The `tab-nav-bar` is not tied to any particular router; it works with normal `<a>` elements and uses
-the `active` property to determine which tab is currently active. The corresponding
-`<router-outlet>` can be placed anywhere in the view.
+The `mat-tab-nav-bar` is not tied to any particular router; it works with normal `<a>` elements and
+uses the `active` property to determine which tab is currently active. The corresponding
+`<router-outlet>` must be wrapped in an `<mat-tab-nav-panel>` component and should typically be
+placed relatively close to the `mat-tab-nav-bar` (see [Accessibility](#accessibility)).
 
 ### Lazy Loading
 By default, the tab contents are eagerly loaded. Eagerly loaded tabs
@@ -85,23 +86,14 @@ duration can be configured globally using the `MAT_TABS_CONFIG` injection token.
                "region": "slow-animation-duration"}) -->
 
 ### Accessibility
-`MatTabGroup` and `MatTabNavBar` implement different interaction patterns for different use-cases.
-You should choose the component that works best for your application.
-
-`MatTabGroup` combines `tablist`, `tab`, and `tabpanel` into a single component with
-handling for keyboard inputs and focus management. You should use this component for switching
-between content within a single page. 
-
-`MatTabNavBar`, implements a navigation interaction pattern by using a `<nav>` element with anchor
-elements as the "tabs". You should use this component when you want your cross-page navigation to
-look like a tabbed interface. As a rule of thumb, you should consider `MatTabNavBar` if changing
-tabs would change the browser URL. For all navigation, including with `MatTabNavBar`, always move
-browser focus to an element at the beginning of the content to which the user is navigating.
-Furthermore, consider placing your `<router-outlet>` inside of a
-[landmark region](https://www.w3.org/TR/wai-aria-1.1/#dfn-landmark) appropriate to the page.
-
-Avoid mixing both `MatTabGroup` and `MatTabNavBar` in your application. The inconsistent interaction
-patterns applied between the components may confuse users.
+`MatTabGroup` and `MatTabNavBar` both implement the
+[ARIA Tabs design pattern](https://www.w3.org/TR/wai-aria-practices-1.1/#tabpanel). Both components
+compose `tablist`, `tab`, and `tabpanel` elements with handling for keyboard inputs and focus
+management.
+
+When using `MatTabNavBar`, you should place the `<mat-tab-nav-panel>` component relatively close to
+if not immediately adjacent to the `<nav mat-tab-nav-bar>` component so that it's easy for screen
+reader users to identify the association.
 
 #### Labels