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

* 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

Co-authored-by: Zack Elliott <zell@google.com>

Author: devversion

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({

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/components-examples/material/tabs/tab-nav-bar-with-panel/tab-nav-bar-with-panel-example.css

@@ -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/components-examples/material/tabs/tab-nav-bar-with-panel/tab-nav-bar-with-panel-example.html

@@ -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