docs(material/dialog): add a11y section about manual focus restoration (#21011)

(cherry picked from commit 9f641d1)

Author: annieyw

src/components-examples/material/dialog/BUILD.bazel

@@ -14,6 +14,7 @@ ng_module(
         "//src/material/button",
         "//src/material/dialog",
         "//src/material/input",
+        "//src/material/menu",
         "@npm//@angular/forms",
     ],
 )

src/components-examples/material/dialog/dialog-from-menu/dialog-from-menu-example-dialog.html

@@ -0,0 +1,6 @@
+<mat-dialog-content>
+  This is a dialog
+</mat-dialog-content>
+<mat-dialog-actions>
+  <button mat-button mat-dialog-close>Okay</button>
+</mat-dialog-actions>

src/components-examples/material/dialog/dialog-from-menu/dialog-from-menu-example.html

@@ -0,0 +1,4 @@
+<button mat-button [matMenuTriggerFor]="menu" #menuTrigger>Menu</button>
+<mat-menu #menu="matMenu">
+  <button mat-menu-item (click)="openDialog()">Open dialog</button>
+</mat-menu>

src/components-examples/material/dialog/dialog-from-menu/dialog-from-menu-example.ts

@@ -0,0 +1,31 @@
+import {Component, ViewChild} from '@angular/core';
+import {MatDialog} from '@angular/material/dialog';
+import {MatMenuTrigger} from '@angular/material/menu';
+/**
+ * @title Dialog launched from a menu
+ */
+@Component({
+  selector: 'dialog-from-menu-example',
+  templateUrl: 'dialog-from-menu-example.html',
+})
+export class DialogFromMenuExample {
+  @ViewChild('menuTrigger') menuTrigger: MatMenuTrigger;
+
+  constructor(public dialog: MatDialog) {}
+
+  openDialog() {
+    // #docregion focus-restoration
+    const dialogRef = this.dialog.open(DialogFromMenuExampleDialog, {restoreFocus: false});
+
+    // Manually restore focus to the menu trigger since the element that
+    // opens the dialog won't be in the DOM any more when the dialog closes.
+    dialogRef.afterClosed().subscribe(() => this.menuTrigger.focus());
+    // #enddocregion focus-restoration
+  }
+}
+
+@Component({
+  selector: 'dialog-from-menu-dialog',
+  templateUrl: 'dialog-from-menu-example-dialog.html',
+})
+export class DialogFromMenuExampleDialog {}

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

@@ -4,6 +4,7 @@ import {FormsModule} from '@angular/forms';
 import {MatButtonModule} from '@angular/material/button';
 import {MatDialogModule} from '@angular/material/dialog';
 import {MatInputModule} from '@angular/material/input';
+import {MatMenuModule} from '@angular/material/menu';
 import {
   DialogContentExample,
   DialogContentExampleDialog
@@ -17,6 +18,10 @@ import {
   DialogOverviewExample,
   DialogOverviewExampleDialog
 } from './dialog-overview/dialog-overview-example';
+import {
+  DialogFromMenuExample,
+  DialogFromMenuExampleDialog
+} from './dialog-from-menu/dialog-from-menu-example';
 
 export {
   DialogContentExample,
@@ -25,6 +30,8 @@ export {
   DialogDataExampleDialog,
   DialogElementsExample,
   DialogElementsExampleDialog,
+  DialogFromMenuExample,
+  DialogFromMenuExampleDialog,
   DialogOverviewExample,
   DialogOverviewExampleDialog,
 };
@@ -36,6 +43,8 @@ const EXAMPLES = [
   DialogDataExampleDialog,
   DialogElementsExample,
   DialogElementsExampleDialog,
+  DialogFromMenuExample,
+  DialogFromMenuExampleDialog,
   DialogOverviewExample,
   DialogOverviewExampleDialog,
 ];
@@ -46,6 +55,7 @@ const EXAMPLES = [
     MatButtonModule,
     MatDialogModule,
     MatInputModule,
+    MatMenuModule,
     FormsModule,
   ],
   declarations: EXAMPLES,

src/material/dialog/dialog.md

@@ -173,6 +173,17 @@ be configured by setting the `cdkFocusInitial` attribute on another focusable el
 Tabbing through the elements of the dialog will keep focus inside of the dialog element,
 wrapping back to the first tabbable element when reaching the end of the tab sequence.
 
+#### Focus Restoration
+Upon closing, the dialog returns focus to the element that had focus when the dialog opened.
+In some cases, however, this previously focused element no longer exists in the DOM, such as
+menu items. To manually restore focus to an appropriate element in such cases, you can disable 
+`restoreFocus` in `MatDialogConfig` and pass it into the `open` method.
+Then you can return focus manually by subscribing to the `afterClosed` observable on `MatDialogRef`.
+
+<!-- example({"example":"dialog-from-menu",
+              "file":"dialog-from-menu-example.ts", 
+              "region":"focus-restoration"}) -->
+
 #### Keyboard interaction
 By default pressing the escape key will close the dialog. While this behavior can
 be turned off via the `disableClose` option, users should generally avoid doing so