fix(material/dialog): improve screen reader support when opened

- notify screen reader users that they have entered a dialog
- previously only the focused element would be read
  i.e. "Close Button Press Search plus Space to activate"
- now the screen reader user gets the normal dialog behavior, which is to
  read the dialog title, role, content, and then tell the user about the
  focused element
  - this matches the guidance here:
    https://www.w3.org/TR/wai-aria-practices-1.1/examples/dialog-modal/dialog.html
- add flushes to mdc-dialog tests to allow dialogs to animate open

Fixes #21840

Author: Splaktar

src/material-experimental/mdc-dialog/dialog.spec.ts

@@ -383,6 +383,7 @@ describe('MDC-based MatDialog', () => {
 
   it('should notify the observers if all open dialogs have finished closing', fakeAsync(() => {
        const ref1 = dialog.open(PizzaMsg, {viewContainerRef: testViewContainerRef});
+       flush();
        const ref2 = dialog.open(ContentElementDialog, {viewContainerRef: testViewContainerRef});
        const spy = jasmine.createSpy('afterAllClosed spy');
 
@@ -615,7 +616,9 @@ describe('MDC-based MatDialog', () => {
 
   it('should close all of the dialogs', fakeAsync(() => {
        dialog.open(PizzaMsg);
+       flush();
        dialog.open(PizzaMsg);
+       flush();
        dialog.open(PizzaMsg);
 
        expect(overlayContainerElement.querySelectorAll('mat-dialog-container').length).toBe(3);
@@ -629,6 +632,7 @@ describe('MDC-based MatDialog', () => {
 
   it('should close all dialogs when the user goes forwards/backwards in history', fakeAsync(() => {
        dialog.open(PizzaMsg);
+       flush();
        dialog.open(PizzaMsg);
 
        expect(overlayContainerElement.querySelectorAll('mat-dialog-container').length).toBe(2);
@@ -642,6 +646,7 @@ describe('MDC-based MatDialog', () => {
 
   it('should close all open dialogs when the location hash changes', fakeAsync(() => {
        dialog.open(PizzaMsg);
+       flush();
        dialog.open(PizzaMsg);
 
        expect(overlayContainerElement.querySelectorAll('mat-dialog-container').length).toBe(2);
@@ -655,7 +660,9 @@ describe('MDC-based MatDialog', () => {
 
   it('should close all of the dialogs when the injectable is destroyed', fakeAsync(() => {
        dialog.open(PizzaMsg);
+       flush();
        dialog.open(PizzaMsg);
+       flush();
        dialog.open(PizzaMsg);
 
        expect(overlayContainerElement.querySelectorAll('mat-dialog-container').length).toBe(3);
@@ -685,6 +692,7 @@ describe('MDC-based MatDialog', () => {
 
   it('should allow the consumer to disable closing a dialog on navigation', fakeAsync(() => {
        dialog.open(PizzaMsg);
+       flush();
        dialog.open(PizzaMsg, {closeOnNavigation: false});
 
        expect(overlayContainerElement.querySelectorAll('mat-dialog-container').length).toBe(2);
@@ -772,14 +780,24 @@ describe('MDC-based MatDialog', () => {
        expect(dialogRef.componentInstance).toBeFalsy('Expected reference to have been cleared.');
      }));
 
-  it('should assign a unique id to each dialog', () => {
+  it('should assign a unique id to each dialog', fakeAsync(() => {
     const one = dialog.open(PizzaMsg);
+    flush();
     const two = dialog.open(PizzaMsg);
 
     expect(one.id).toBeTruthy();
     expect(two.id).toBeTruthy();
     expect(one.id).not.toBe(two.id);
-  });
+  }));
+
+  it('should not allow another dialog to open until the previous dialog finished animating open',
+     () => {
+       const openTwoDialogs = () => {
+         dialog.open(PizzaMsg);
+         dialog.open(PizzaMsg);
+       };
+       expect(openTwoDialogs).toThrowError(/Ignoring attempt to open dialog/);
+     });
 
   it('should allow for the id to be overwritten', () => {
     const dialogRef = dialog.open(PizzaMsg, {id: 'pizza'});

src/material/dialog/dialog-container.ts

@@ -105,9 +105,6 @@ export abstract class _MatDialogContainerBase extends BasePortalOutlet {
     // Save the previously focused element. This element will be re-focused
     // when the dialog closes.
     this._capturePreviouslyFocusedElement();
-    // Move focus onto the dialog immediately in order to prevent the user
-    // from accidentally opening multiple dialogs at the same time.
-    this._focusDialogContainer();
   }
 
   /**
@@ -154,7 +151,7 @@ export abstract class _MatDialogContainerBase extends BasePortalOutlet {
       const focusContainer = !this._config.autoFocus || !this._focusTrap.focusInitialElement();
 
       if (focusContainer) {
-        this._elementRef.nativeElement.focus();
+        this._focusDialogContainer();
       }
     }
   }
@@ -165,14 +162,20 @@ export abstract class _MatDialogContainerBase extends BasePortalOutlet {
     // ready in instances where change detection has to run first. To deal with this, we simply
     // wait for the microtask queue to be empty.
     if (this._config.autoFocus) {
-      this._focusTrap.focusInitialElementWhenReady();
+      this._focusTrap.focusInitialElementWhenReady().then(focusedSuccessfully => {
+        // If we weren't able to find a focusable element in the dialog, then focus the dialog
+        // container instead.
+        if (!focusedSuccessfully) {
+          this._focusDialogContainer();
+        }
+      });
     } else if (!this._containsFocus()) {
       // Otherwise ensure that focus is on the dialog container. It's possible that a different
       // component tried to move focus while the open animation was running. See:
       // https://github.com/angular/components/issues/16215. Note that we only want to do this
       // if the focus isn't inside the dialog already, because it's possible that the consumer
       // turned off `autoFocus` in order to move focus themselves.
-      this._elementRef.nativeElement.focus();
+      this._focusDialogContainer();
     }
   }
 

src/material/dialog/dialog.spec.ts

@@ -1227,7 +1227,7 @@ describe('MatDialog', () => {
 
       tick(500);
       viewContainerFixture.detectChanges();
-      expect(lastFocusOrigin!).toBeNull('Expected the trigger button to be blurred');
+      expect(lastFocusOrigin!).toBe('program');
 
       dispatchKeyboardEvent(document.body, 'keydown', ESCAPE);
 
@@ -1260,7 +1260,7 @@ describe('MatDialog', () => {
 
       tick(500);
       viewContainerFixture.detectChanges();
-      expect(lastFocusOrigin!).toBeNull('Expected the trigger button to be blurred');
+      expect(lastFocusOrigin!).toBe('program');
 
       const backdrop = overlayContainerElement
           .querySelector('.cdk-overlay-backdrop') as HTMLElement;
@@ -1296,7 +1296,7 @@ describe('MatDialog', () => {
 
       tick(500);
       viewContainerFixture.detectChanges();
-      expect(lastFocusOrigin!).toBeNull('Expected the trigger button to be blurred');
+      expect(lastFocusOrigin!).toBe('program');
 
       const closeButton = overlayContainerElement
         .querySelector('button[mat-dialog-close]') as HTMLElement;
@@ -1333,7 +1333,7 @@ describe('MatDialog', () => {
 
       tick(500);
       viewContainerFixture.detectChanges();
-      expect(lastFocusOrigin!).toBeNull('Expected the trigger button to be blurred');
+      expect(lastFocusOrigin!).toBe('program');
 
       const closeButton = overlayContainerElement
         .querySelector('button[mat-dialog-close]') as HTMLElement;

src/material/dialog/dialog.ts

@@ -30,7 +30,7 @@ import {
   TemplateRef,
   Type,
 } from '@angular/core';
-import {defer, Observable, of as observableOf, Subject} from 'rxjs';
+import {defer, Observable, of as observableOf, Subject, Subscription} from 'rxjs';
 import {startWith} from 'rxjs/operators';
 import {MatDialogConfig} from './dialog-config';
 import {MatDialogContainer, _MatDialogContainerBase} from './dialog-container';
@@ -77,6 +77,8 @@ export abstract class _MatDialogBase<C extends _MatDialogContainerBase> implemen
   private readonly _afterOpenedAtThisLevel = new Subject<MatDialogRef<any>>();
   private _ariaHiddenElements = new Map<Element, string|null>();
   private _scrollStrategy: () => ScrollStrategy;
+  private _dialogAnimatingOpen = false;
+  private _animationStateSubscriptions = new Subscription();
 
   /** Keeps track of the currently-open dialogs. */
   get openDialogs(): MatDialogRef<any>[] {
@@ -144,9 +146,25 @@ export abstract class _MatDialogBase<C extends _MatDialogContainerBase> implemen
       (typeof ngDevMode === 'undefined' || ngDevMode)) {
       throw Error(`Dialog with id "${config.id}" exists already. The dialog id must be unique.`);
     }
+    if (this._dialogAnimatingOpen) {
+      throw Error(`Ignoring attempt to open dialog with id "${
+        config.id}" since another dialog is currently animating open.`);
+    }
 
     const overlayRef = this._createOverlay(config);
     const dialogContainer = this._attachDialogContainer(overlayRef, config);
+    const animationStateSubscription =
+        dialogContainer._animationStateChanged.subscribe((dialogAnimationEvent) => {
+          if (dialogAnimationEvent.state === 'opening') {
+            this._dialogAnimatingOpen = true;
+          }
+          if (dialogAnimationEvent.state === 'opened') {
+            this._dialogAnimatingOpen = false;
+            animationStateSubscription.unsubscribe();
+          }
+        });
+    this._animationStateSubscriptions.add(animationStateSubscription);
+
     const dialogRef = this._attachDialogContent<T, R>(componentOrTemplateRef,
                                                       dialogContainer,
                                                       overlayRef,
@@ -188,6 +206,8 @@ export abstract class _MatDialogBase<C extends _MatDialogContainerBase> implemen
     this._closeDialogs(this._openDialogsAtThisLevel);
     this._afterAllClosedAtThisLevel.complete();
     this._afterOpenedAtThisLevel.complete();
+    // Clean up any subscriptions to dialogs that never finished opening.
+    this._animationStateSubscriptions.unsubscribe();
   }
 
   /**