From 51963975cafcc641c3f049c1b6dc15f9d9f03698 Mon Sep 17 00:00:00 2001
From: Zack Elliott <zell@google.com>
Date: Sun, 30 Jan 2022 08:04:06 -0800
Subject: [PATCH 1/3] docs(material/tabs): Update public documentation with new
 mat-tab-nav-bar/panel guidance

---
 .../material/tabs/index.ts                    |  3 --
 .../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/material/tabs/tabs.md                     | 32 +++++++------------
 6 files changed, 14 insertions(+), 51 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 60a688c946e5..31a8d026686e 100644
--- a/src/components-examples/material/tabs/index.ts
+++ b/src/components-examples/material/tabs/index.ts
@@ -21,7 +21,6 @@ import {TabGroupPreserveContentExample} from './tab-group-preserve-content/tab-g
 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,
@@ -37,7 +36,6 @@ export {
   TabGroupStretchedExample,
   TabGroupThemeExample,
   TabNavBarBasicExample,
-  TabNavBarWithPanelExample,
   TabGroupPreserveContentExample,
 };
 
@@ -55,7 +53,6 @@ const EXAMPLES = [
   TabGroupStretchedExample,
   TabGroupThemeExample,
   TabNavBarBasicExample,
-  TabNavBarWithPanelExample,
   TabGroupPreserveContentExample,
 ];
 
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/material/tabs/tabs.md b/src/material/tabs/tabs.md
index 08d83e6227c2..142d4cef7760 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
@@ -94,23 +95,14 @@ off-screen tabs in the DOM, you can set the `preserveContent` input to `true`.
 <!-- example(tab-group-preserve-content) -->
 
 ### 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
 

From 0dd8bf9731e3ce61df9ec4c1fef464fc9718ee68 Mon Sep 17 00:00:00 2001
From: Zack Elliott <zell@google.com>
Date: Sun, 30 Jan 2022 08:09:25 -0800
Subject: [PATCH 2/3] docs(material/tabs): Fixed in-page link

---
 src/material/tabs/tabs.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/material/tabs/tabs.md b/src/material/tabs/tabs.md
index 142d4cef7760..f885735fa441 100644
--- a/src/material/tabs/tabs.md
+++ b/src/material/tabs/tabs.md
@@ -49,7 +49,7 @@ provides a tab-like UI for navigating between routes.
 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)).
+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

From f1c856cca0c455613e4217e9b238a7f4fa3a758d Mon Sep 17 00:00:00 2001
From: Zack Elliott <zell@google.com>
Date: Sun, 30 Jan 2022 08:16:03 -0800
Subject: [PATCH 3/3] docs(material/tabs): Fix demo bug

---
 src/dev-app/tabs/tabs-demo.html | 2 --
 1 file changed, 2 deletions(-)

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>