fix(dialog): don't move focus if it was moved during close ani… (#17300)

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.

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;
   }
 
   /**
@@ -163,7 +166,17 @@ export class MatDialogContainer extends BasePortalOutlet {
 
     // 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();
+      const activeElement = this._document.activeElement;
+      const element = this._elementRef.nativeElement;
+
+      // Make sure that focus is still inside the dialog or is on the body (usually because a
+      // non-focusable element like the backdrop was clicked) 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.
+      if (!activeElement || activeElement === this._document.body || activeElement === element ||
+        element.contains(activeElement)) {
+        toFocus.focus();
+      }
     }
 
     if (this._focusTrap) {

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);
+    }));
 
   });