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,15 @@ 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 allow for the id to be overwritten', () => {
     const dialogRef = dialog.open(PizzaMsg, {id: 'pizza'});
@@ -1064,7 +1073,7 @@ describe('MDC-based MatDialog', () => {
          expect(document.activeElement!.id)
              .not.toBe(
                  'dialog-trigger',
-                 'Expcted the focus not to have changed before the animation finishes.');
+                 'Expected the focus not to have changed before the animation finishes.');
 
          flushMicrotasks();
          viewContainerFixture.detectChanges();
@@ -1789,6 +1798,15 @@ describe('MDC-based MatDialog with animations enabled', () => {
        flush();
        expect(dialogRef.getState()).toBe(MatDialogState.CLOSED);
      }));
+
+  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/);
+    });
 });
 
 @Directive({selector: 'dir-with-view-container'})

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

@@ -12,6 +12,7 @@ import {Inject, Injectable, InjectionToken, Injector, Optional, SkipSelf} from '
 import {_MatDialogBase, MatDialogConfig} from '@angular/material/dialog';
 import {MatDialogContainer} from './dialog-container';
 import {MatDialogRef} from './dialog-ref';
+import {ANIMATION_MODULE_TYPE} from '@angular/platform-browser/animations';
 
 /** Injection token that can be used to access the data that was passed in to a dialog. */
 export const MAT_DIALOG_DATA = new InjectionToken<any>('MatMdcDialogData');
@@ -52,9 +53,11 @@ export class MatDialog extends _MatDialogBase<MatDialogContainer> {
       @Optional() location: Location,
       @Optional() @Inject(MAT_DIALOG_DEFAULT_OPTIONS) defaultOptions: MatDialogConfig,
       @Inject(MAT_DIALOG_SCROLL_STRATEGY) scrollStrategy: any,
-      @Optional() @SkipSelf() parentDialog: MatDialog, overlayContainer: OverlayContainer) {
+      @Optional() @SkipSelf() parentDialog: MatDialog, overlayContainer: OverlayContainer,
+      @Optional() @Inject(ANIMATION_MODULE_TYPE) animationMode?: 'NoopAnimations'|
+      'BrowserAnimations') {
     super(
         overlay, injector, defaultOptions, parentDialog, overlayContainer, scrollStrategy,
-        MatDialogRef, MatDialogContainer, MAT_DIALOG_DATA);
+        MatDialogRef, MatDialogContainer, MAT_DIALOG_DATA, animationMode);
   }
 }

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,11 +30,12 @@ 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';
 import {MatDialogRef} from './dialog-ref';
+import {ANIMATION_MODULE_TYPE} from '@angular/platform-browser/animations';
 
 
 /** Injection token that can be used to access the data that was passed in to a dialog. */
@@ -77,6 +78,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: Subscription;
 
   /** Keeps track of the currently-open dialogs. */
   get openDialogs(): MatDialogRef<any>[] {
@@ -111,7 +114,8 @@ export abstract class _MatDialogBase<C extends _MatDialogContainerBase> implemen
       scrollStrategy: any,
       private _dialogRefConstructor: Type<MatDialogRef<any>>,
       private _dialogContainerType: Type<C>,
-      private _dialogDataToken: InjectionToken<any>) {
+      private _dialogDataToken: InjectionToken<any>,
+      private _animationMode?: 'NoopAnimations' | 'BrowserAnimations') {
     this._scrollStrategy = scrollStrategy;
   }
 
@@ -144,9 +148,30 @@ 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);
+    if (this._animationMode !== 'NoopAnimations') {
+      const animationStateSubscription =
+        dialogContainer._animationStateChanged.subscribe((dialogAnimationEvent) => {
+          if (dialogAnimationEvent.state === 'opening') {
+            this._dialogAnimatingOpen = true;
+          }
+          if (dialogAnimationEvent.state === 'opened') {
+            this._dialogAnimatingOpen = false;
+            animationStateSubscription.unsubscribe();
+          }
+        });
+      if (!this._animationStateSubscriptions) {
+        this._animationStateSubscriptions = new Subscription();
+      }
+      this._animationStateSubscriptions.add(animationStateSubscription);
+    }
+
     const dialogRef = this._attachDialogContent<T, R>(componentOrTemplateRef,
                                                       dialogContainer,
                                                       overlayRef,
@@ -188,6 +213,10 @@ 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.
+    if (this._animationStateSubscriptions) {
+      this._animationStateSubscriptions.unsubscribe();
+    }
   }
 
   /**
@@ -392,19 +421,19 @@ export abstract class _MatDialogBase<C extends _MatDialogContainerBase> implemen
 @Injectable()
 export class MatDialog extends _MatDialogBase<MatDialogContainer> {
   constructor(
-      overlay: Overlay,
-      injector: Injector,
+      overlay: Overlay, injector: Injector,
       /**
        * @deprecated `_location` parameter to be removed.
        * @breaking-change 10.0.0
        */
       @Optional() location: Location,
       @Optional() @Inject(MAT_DIALOG_DEFAULT_OPTIONS) defaultOptions: MatDialogConfig,
       @Inject(MAT_DIALOG_SCROLL_STRATEGY) scrollStrategy: any,
-      @Optional() @SkipSelf() parentDialog: MatDialog,
-      overlayContainer: OverlayContainer) {
+      @Optional() @SkipSelf() parentDialog: MatDialog, overlayContainer: OverlayContainer,
+      @Optional() @Inject(ANIMATION_MODULE_TYPE) animationMode?: 'NoopAnimations'|
+      'BrowserAnimations') {
     super(overlay, injector, defaultOptions, parentDialog, overlayContainer, scrollStrategy,
-        MatDialogRef, MatDialogContainer, MAT_DIALOG_DATA);
+        MatDialogRef, MatDialogContainer, MAT_DIALOG_DATA, animationMode);
   }
 }