fix(dialog): don't move focus if it was moved during close animation

Currently we restore focus to the previously-focused element once the dialog's exit animation has completed, however this can override any focus management the consumer might have done while the animation was running. These changes add extra check so that we only move focus if it was inside the dialog at the end of the animation.

Fixes #17296.

Author: crisbeto

src/e2e-app/dialog/dialog-e2e.html

@@ -2,4 +2,7 @@
 <button id="disabled" (click)="openDisabled()">DISABLED</button>
 <button id="template" (click)="openTemplate()">TEMPLATE</button>
 
-<ng-template><div class="my-template-dialog">my template dialog</div></ng-template>
+<ng-template>
+  <div class="my-template-dialog">my template dialog</div>
+  <button>Dummy button</button>
+</ng-template>

src/material/dialog/dialog-container.ts

@@ -71,6 +71,8 @@ export function throwMatDialogContentAlreadyAttachedError() {
   },
 })
 export class MatDialogContainer extends BasePortalOutlet {
+  private _document: Document;
+
   /** The portal outlet inside of this container into which the dialog content will be loaded. */
   @ViewChild(CdkPortalOutlet, {static: true}) _portalOutlet: CdkPortalOutlet;
 
@@ -96,12 +98,13 @@ export class MatDialogContainer extends BasePortalOutlet {
     private _elementRef: ElementRef,
     private _focusTrapFactory: FocusTrapFactory,
     private _changeDetectorRef: ChangeDetectorRef,
-    @Optional() @Inject(DOCUMENT) private _document: any,
+    @Optional() @Inject(DOCUMENT) _document: any,
     /** The dialog configuration. */
     public _config: MatDialogConfig) {
 
     super();
     this._ariaLabelledBy = _config.ariaLabelledBy || null;
+    this._document = _document;
   }
 
   /**
@@ -160,9 +163,14 @@ export class MatDialogContainer extends BasePortalOutlet {
   /** Restores focus to the element that was focused before the dialog opened. */
   private _restoreFocus() {
     const toFocus = 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') {
+    const activeElement = this._document.activeElement;
+
+    // Make sure that focus is still inside the dialog before moving it. It's possible that the
+    // consumer moved it themselves before the animation was done, in which case we shouldn't
+    // do anything. Also note that we need the extra check, because IE can set the `activeElement`
+    // to null in some cases.
+    if ((!activeElement || this._elementRef.nativeElement.contains(activeElement)) &&
+      this._config.restoreFocus && toFocus && typeof toFocus.focus === 'function') {
       toFocus.focus();
     }
 

src/material/dialog/dialog.spec.ts

@@ -1148,6 +1148,43 @@ describe('MatDialog', () => {
       document.body.removeChild(button);
     }));
 
+    it('should not move focus if it was moved outside the dialog while animating', fakeAsync(() => {
+      // Create a element that has focus before the dialog is opened.
+      const button = document.createElement('button');
+      const otherButton = document.createElement('button');
+      const body = document.body;
+      button.id = 'dialog-trigger';
+      otherButton.id = 'other-button';
+      body.appendChild(button);
+      body.appendChild(otherButton);
+      button.focus();
+
+      const dialogRef = dialog.open(PizzaMsg, {viewContainerRef: testViewContainerRef });
+
+      flushMicrotasks();
+      viewContainerFixture.detectChanges();
+      flushMicrotasks();
+
+      expect(document.activeElement!.id)
+          .not.toBe('dialog-trigger', 'Expected the focus to change when dialog was opened.');
+
+      // Start the closing sequence and move focus out of dialog.
+      dialogRef.close();
+      otherButton.focus();
+
+      expect(document.activeElement!.id)
+          .toBe('other-button', 'Expected focus to be on the alternate button.');
+
+      flushMicrotasks();
+      viewContainerFixture.detectChanges();
+      flush();
+
+      expect(document.activeElement!.id)
+          .toBe('other-button', 'Expected focus to stay on the alternate button.');
+
+      body.removeChild(button);
+      body.removeChild(otherButton);
+    }));
 
   });