docs(material/tabs): Update public documentation with new mat-tab-nav…

…-bar/panel guidance (angular#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

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,
 ];
 

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()">

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>

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