fix(dialog): restore focus with the proper focus origin

* Restores the trigger focus upon dialog close with the proper focus origin that caused the dialog closing.

For example, a backdrop click leads to a focus restore via `mouse`. Pressing `escape` leads to a focus restore via `keyboard`. Clicking the `matDialogClose` button will depend on the type of interaction (e.g. `click` or `keyboard`)

References #8420.

Author: devversion

src/material/dialog/BUILD.bazel

@@ -56,6 +56,7 @@ ng_test_library(
     ),
     deps = [
         ":dialog",
+        "//src/cdk/a11y",
         "//src/cdk/bidi",
         "//src/cdk/keycodes",
         "//src/cdk/overlay",

src/material/dialog/dialog-container.ts

@@ -28,7 +28,7 @@ import {
   CdkPortalOutlet,
   TemplatePortal
 } from '@angular/cdk/portal';
-import {FocusTrap, FocusTrapFactory} from '@angular/cdk/a11y';
+import {FocusTrap, FocusMonitor, FocusOrigin, FocusTrapFactory} from '@angular/cdk/a11y';
 import {MatDialogConfig} from './dialog-config';
 
 
@@ -80,6 +80,13 @@ export class MatDialogContainer extends BasePortalOutlet {
   /** Element that was focused before the dialog was opened. Save this to restore upon close. */
   private _elementFocusedBeforeDialogWasOpened: HTMLElement | null = null;
 
+  /**
+   * Type of interaction that led to the dialog being closed. This is used to determine
+   * whether the focus style will be applied when returning focus to its original location
+   * after the dialog is closed.
+   */
+  _closeInteractionType: FocusOrigin = 'program';
+
   /** State of the dialog animation. */
   _state: 'void' | 'enter' | 'exit' = 'enter';
 
@@ -92,14 +99,12 @@ export class MatDialogContainer extends BasePortalOutlet {
   /** ID for the container DOM element. */
   _id: string;
 
-  constructor(
-    private _elementRef: ElementRef,
-    private _focusTrapFactory: FocusTrapFactory,
-    private _changeDetectorRef: ChangeDetectorRef,
-    @Optional() @Inject(DOCUMENT) private _document: any,
-    /** The dialog configuration. */
-    public _config: MatDialogConfig) {
-
+  constructor(private _elementRef: ElementRef,
+              private _focusTrapFactory: FocusTrapFactory,
+              private _changeDetectorRef: ChangeDetectorRef,
+              @Optional() @Inject(DOCUMENT) private _document: any,
+              /** The dialog configuration. */ public _config: MatDialogConfig,
+              private _focusMonitor?: FocusMonitor) {
     super();
     this._ariaLabelledBy = _config.ariaLabelledBy || null;
   }
@@ -151,11 +156,14 @@ export class MatDialogContainer extends BasePortalOutlet {
 
   /** Restores focus to the element that was focused before the dialog opened. */
   private _restoreFocus() {
-    const toFocus = this._elementFocusedBeforeDialogWasOpened;
+    const previousElement = this._elementFocusedBeforeDialogWasOpened;
 
-    // We need the extra check, because IE can set the `activeElement` to null in some cases.
-    if (this._config.restoreFocus && toFocus && typeof toFocus.focus === 'function') {
-      toFocus.focus();
+    if (this._config.restoreFocus && previousElement && previousElement.focus) {
+      if (this._focusMonitor) {
+        this._focusMonitor.focusVia(previousElement, this._closeInteractionType);
+      } else {
+        previousElement.focus();
+      }
     }
 
     if (this._focusTrap) {

src/material/dialog/dialog-content-directives.ts

@@ -28,7 +28,7 @@ let dialogElementUid = 0;
   selector: `button[mat-dialog-close], button[matDialogClose]`,
   exportAs: 'matDialogClose',
   host: {
-    '(click)': 'dialogRef.close(dialogResult)',
+    '(click)': '_onButtonClick($event)',
     '[attr.aria-label]': 'ariaLabel || null',
     'type': 'button', // Prevents accidental form submits.
   }
@@ -65,6 +65,15 @@ export class MatDialogClose implements OnInit, OnChanges {
       this.dialogResult = proxiedChange.currentValue;
     }
   }
+
+  _onButtonClick(event: MouseEvent) {
+    // Determinate the focus origin using the click event, because using the FocusMonitor will
+    // result in incorrect origins. Most of the time, close buttons will be auto focused in the
+    // dialog, and therefore clicking the button won't result in a focus change. This means that
+    // the FocusMonitor won't detect any origin change, and will always output `program`.
+    this.dialogRef._closeVia(
+        event.screenX === 0 && event.screenY === 0 ? 'keyboard' : 'mouse', this.dialogResult);
+  }
 }
 
 /**

src/material/dialog/dialog-ref.ts

@@ -6,6 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
+import {FocusOrigin} from '@angular/cdk/a11y';
 import {ESCAPE, hasModifierKey} from '@angular/cdk/keycodes';
 import {GlobalPositionStrategy, OverlayRef} from '@angular/cdk/overlay';
 import {Location} from '@angular/common';
@@ -83,7 +84,7 @@ export class MatDialogRef<T, R = any> {
       }))
       .subscribe(event => {
         event.preventDefault();
-        this.close();
+        this._closeVia('keyboard');
       });
   }
 
@@ -108,6 +109,12 @@ export class MatDialogRef<T, R = any> {
     this._containerInstance._startExitAnimation();
   }
 
+  /** Closes the dialog with the specified interaction type. */
+  _closeVia(interactionType: FocusOrigin, dialogResult?: R) {
+    this._containerInstance._closeInteractionType = interactionType;
+    this.close(dialogResult);
+  }
+
   /**
    * Gets an observable that is notified when the dialog is finished opening.
    */

src/material/dialog/dialog.spec.ts

@@ -1,12 +1,16 @@
+import {FocusMonitor, FocusOrigin} from '@angular/cdk/a11y';
+import {Directionality} from '@angular/cdk/bidi';
+import {A, ESCAPE} from '@angular/cdk/keycodes';
+import {Overlay, OverlayContainer, ScrollStrategy} from '@angular/cdk/overlay';
+import {ScrollDispatcher} from '@angular/cdk/scrolling';
 import {
-  ComponentFixture,
-  fakeAsync,
-  flushMicrotasks,
-  inject,
-  TestBed,
-  tick,
-  flush,
-} from '@angular/core/testing';
+  createKeyboardEvent,
+  dispatchKeyboardEvent,
+  dispatchMouseEvent,
+  patchElementFocus
+} from '@angular/cdk/testing';
+import {Location} from '@angular/common';
+import {SpyLocation} from '@angular/common/testing';
 import {
   ChangeDetectionStrategy,
   Component,
@@ -18,31 +22,34 @@ import {
   ViewChild,
   ViewContainerRef
 } from '@angular/core';
+import {
+  ComponentFixture,
+  fakeAsync,
+  flush,
+  flushMicrotasks,
+  inject,
+  TestBed,
+  tick,
+} from '@angular/core/testing';
 import {By} from '@angular/platform-browser';
 import {NoopAnimationsModule} from '@angular/platform-browser/animations';
-import {Location} from '@angular/common';
-import {SpyLocation} from '@angular/common/testing';
-import {Directionality} from '@angular/cdk/bidi';
+import {Subject} from 'rxjs';
 import {MatDialogContainer} from './dialog-container';
-import {OverlayContainer, ScrollStrategy, Overlay} from '@angular/cdk/overlay';
-import {ScrollDispatcher} from '@angular/cdk/scrolling';
-import {A, ESCAPE} from '@angular/cdk/keycodes';
-import {dispatchKeyboardEvent, createKeyboardEvent} from '@angular/cdk/testing';
 import {
   MAT_DIALOG_DATA,
+  MAT_DIALOG_DEFAULT_OPTIONS,
   MatDialog,
   MatDialogModule,
-  MatDialogRef,
-  MAT_DIALOG_DEFAULT_OPTIONS
+  MatDialogRef
 } from './index';
-import {Subject} from 'rxjs';
 
 
 describe('MatDialog', () => {
   let dialog: MatDialog;
   let overlayContainer: OverlayContainer;
   let overlayContainerElement: HTMLElement;
   let scrolledSubject = new Subject();
+  let focusMonitor: FocusMonitor;
 
   let testViewContainerRef: ViewContainerRef;
   let viewContainerFixture: ComponentFixture<ComponentWithChildViewContainer>;
@@ -62,13 +69,14 @@ describe('MatDialog', () => {
     TestBed.compileComponents();
   }));
 
-  beforeEach(inject([MatDialog, Location, OverlayContainer],
-    (d: MatDialog, l: Location, oc: OverlayContainer) => {
+  beforeEach(inject([MatDialog, Location, OverlayContainer, FocusMonitor],
+    (d: MatDialog, l: Location, oc: OverlayContainer, fm: FocusMonitor) => {
       dialog = d;
       mockLocation = l as SpyLocation;
       overlayContainer = oc;
       overlayContainerElement = oc.getContainerElement();
-    }));
+      focusMonitor = fm;
+  }));
 
   afterEach(() => {
     overlayContainer.ngOnDestroy();
@@ -1035,6 +1043,148 @@ describe('MatDialog', () => {
       document.body.removeChild(button);
     }));
 
+    it('should re-focus the trigger via keyboard when closed via escape key', fakeAsync(() => {
+      const button = document.createElement('button');
+      let lastFocusOrigin: FocusOrigin = null;
+
+      focusMonitor.monitor(button, false)
+        .subscribe(focusOrigin => lastFocusOrigin = focusOrigin);
+
+      document.body.appendChild(button);
+      button.focus();
+
+      // Patch the element focus after the initial and real focus, because otherwise the
+      // `activeElement` won't be set, and the dialog won't be able to restore focus to an element.
+      patchElementFocus(button);
+
+      dialog.open(PizzaMsg, {viewContainerRef: testViewContainerRef});
+
+      tick(500);
+      viewContainerFixture.detectChanges();
+
+      expect(lastFocusOrigin!).toBeNull('Expected the trigger button to be blurred');
+
+      dispatchKeyboardEvent(document.body, 'keydown', ESCAPE);
+
+      flushMicrotasks();
+      viewContainerFixture.detectChanges();
+      tick(500);
+
+      expect(lastFocusOrigin!)
+        .toBe('keyboard', 'Expected the trigger button to be focused via keyboard');
+
+      focusMonitor.stopMonitoring(button);
+      document.body.removeChild(button);
+    }));
+
+    it('should re-focus the trigger via mouse when backdrop has been clicked', fakeAsync(() => {
+      const button = document.createElement('button');
+      let lastFocusOrigin: FocusOrigin = null;
+
+      focusMonitor.monitor(button, false)
+        .subscribe(focusOrigin => lastFocusOrigin = focusOrigin);
+
+      document.body.appendChild(button);
+      button.focus();
+
+      // Patch the element focus after the initial and real focus, because otherwise the
+      // `activeElement` won't be set, and the dialog won't be able to restore focus to an element.
+      patchElementFocus(button);
+
+      dialog.open(PizzaMsg, {viewContainerRef: testViewContainerRef});
+
+      tick(500);
+      viewContainerFixture.detectChanges();
+
+      const backdrop = overlayContainerElement
+          .querySelector('.cdk-overlay-backdrop') as HTMLElement;
+
+      backdrop.click();
+      viewContainerFixture.detectChanges();
+      tick(500);
+
+      expect(lastFocusOrigin!)
+        .toBe('mouse', 'Expected the trigger button to be focused via mouse');
+
+      focusMonitor.stopMonitoring(button);
+      document.body.removeChild(button);
+    }));
+
+    it('should re-focus via keyboard if the close button has been triggered through keyboard',
+        fakeAsync(() => {
+
+      const button = document.createElement('button');
+      let lastFocusOrigin: FocusOrigin = null;
+
+      focusMonitor.monitor(button, false)
+        .subscribe(focusOrigin => lastFocusOrigin = focusOrigin);
+
+      document.body.appendChild(button);
+      button.focus();
+
+      // Patch the element focus after the initial and real focus, because otherwise the
+      // `activeElement` won't be set, and the dialog won't be able to restore focus to an element.
+      patchElementFocus(button);
+
+      dialog.open(ContentElementDialog, {viewContainerRef: testViewContainerRef});
+
+      tick(500);
+      viewContainerFixture.detectChanges();
+
+      const closeButton = overlayContainerElement
+        .querySelector('button[mat-dialog-close]') as HTMLElement;
+
+      // Fake the behavior of pressing the SPACE key on a button element. Browsers fire a `click`
+      // event with a MouseEvent, which has coordinates that are out of the element boundaries.
+      dispatchMouseEvent(closeButton, 'click', 0, 0);
+
+      viewContainerFixture.detectChanges();
+      tick(500);
+
+      expect(lastFocusOrigin!)
+        .toBe('keyboard', 'Expected the trigger button to be focused via keyboard');
+
+      focusMonitor.stopMonitoring(button);
+      document.body.removeChild(button);
+    }));
+
+    it('should re-focus via mouse if the close button has been clicked', fakeAsync(() => {
+      const button = document.createElement('button');
+      let lastFocusOrigin: FocusOrigin = null;
+
+      focusMonitor.monitor(button, false)
+        .subscribe(focusOrigin => lastFocusOrigin = focusOrigin);
+
+      document.body.appendChild(button);
+      button.focus();
+
+      // Patch the element focus after the initial and real focus, because otherwise the
+      // `activeElement` won't be set, and the dialog won't be able to restore focus to an element.
+      patchElementFocus(button);
+
+      dialog.open(ContentElementDialog, {viewContainerRef: testViewContainerRef});
+
+      tick(500);
+      viewContainerFixture.detectChanges();
+
+      const closeButton = overlayContainerElement
+        .querySelector('button[mat-dialog-close]') as HTMLElement;
+
+      // The dialog close button detects the focus origin by inspecting the click event. If
+      // coordinates of the click are not present, it assumes that the click has been triggered
+      // by keyboard.
+      dispatchMouseEvent(closeButton, 'click', 10, 10);
+
+      viewContainerFixture.detectChanges();
+      tick(500);
+
+      expect(lastFocusOrigin!)
+        .toBe('mouse', 'Expected the trigger button to be focused via mouse');
+
+      focusMonitor.stopMonitoring(button);
+      document.body.removeChild(button);
+    }));
+
     it('should allow the consumer to shift focus in afterClosed', fakeAsync(() => {
       // Create a element that has focus before the dialog is opened.
       let button = document.createElement('button');
@@ -1057,7 +1207,7 @@ describe('MatDialog', () => {
 
       tick(500);
       viewContainerFixture.detectChanges();
-      flushMicrotasks();
+      flush();
 
       expect(document.activeElement!.id).toBe('input-to-be-focused',
           'Expected that the trigger was refocused after the dialog is closed.');

src/material/dialog/dialog.ts

@@ -254,7 +254,7 @@ export class MatDialog implements OnDestroy {
     if (config.hasBackdrop) {
       overlayRef.backdropClick().subscribe(() => {
         if (!dialogRef.disableClose) {
-          dialogRef.close();
+          dialogRef._closeVia('mouse');
         }
       });
     }