feat(material/dialog): add closePredicate option

Adds the `closePredicate` config option to the Material dialog that allows developers to programmatically determine whether the user is allowed to close a dialog.

Fixes #14292.

Author: crisbeto

goldens/material/dialog/index.api.md

@@ -9,6 +9,7 @@ import { ComponentPortal } from '@angular/cdk/portal';
 import { ComponentRef } from '@angular/core';
 import { ComponentType } from '@angular/cdk/overlay';
 import { Dialog } from '@angular/cdk/dialog';
+import { DialogConfig } from '@angular/cdk/dialog';
 import { DialogRef } from '@angular/cdk/dialog';
 import { Direction } from '@angular/cdk/bidi';
 import { EventEmitter } from '@angular/core';
@@ -138,6 +139,7 @@ export class MatDialogConfig<D = any> {
     autoFocus?: AutoFocusTarget | string | boolean;
     backdropClass?: string | string[];
     closeOnNavigation?: boolean;
+    closePredicate?: <Result = unknown, Component = unknown, Config extends DialogConfig = MatDialogConfig>(result: Result | undefined, config: Config, componentInstance: Component | null) => boolean;
     data?: D | null;
     delayFocusTrap?: boolean;
     direction?: Direction;
@@ -203,7 +205,7 @@ export class MatDialogModule {
 
 // @public
 export class MatDialogRef<T, R = any> {
-    constructor(_ref: DialogRef<R, T>, config: MatDialogConfig, _containerInstance: MatDialogContainer);
+    constructor(_ref: DialogRef<R, T>, _config: MatDialogConfig, _containerInstance: MatDialogContainer);
     addPanelClass(classes: string | string[]): this;
     afterClosed(): Observable<R | undefined>;
     afterOpened(): Observable<void>;

goldens/material/dialog/testing/index.api.md

@@ -13,6 +13,7 @@ import { ComponentRef } from '@angular/core';
 import { ComponentType } from '@angular/cdk/overlay';
 import { ContentContainerComponentHarness } from '@angular/cdk/testing';
 import { Dialog } from '@angular/cdk/dialog';
+import { DialogConfig } from '@angular/cdk/dialog';
 import { DialogRef } from '@angular/cdk/dialog';
 import { Direction } from '@angular/cdk/bidi';
 import { EventEmitter } from '@angular/core';

src/material/dialog/dialog-config.ts

@@ -9,6 +9,7 @@
 import {ViewContainerRef, Injector} from '@angular/core';
 import {Direction} from '@angular/cdk/bidi';
 import {ScrollStrategy} from '@angular/cdk/overlay';
+import {DialogConfig} from '@angular/cdk/dialog';
 import {_defaultParams} from './dialog-animations';
 
 /** Options for where to set focus to automatically on dialog open */
@@ -68,6 +69,17 @@ export class MatDialogConfig<D = any> {
   /** Whether the user can use escape or clicking on the backdrop to close the modal. */
   disableClose?: boolean = false;
 
+  /** Function used to determine whether the dialog is allowed to close. */
+  closePredicate?: <
+    Result = unknown,
+    Component = unknown,
+    Config extends DialogConfig = MatDialogConfig,
+  >(
+    result: Result | undefined,
+    config: Config,
+    componentInstance: Component | null,
+  ) => boolean;
+
   /** Width of the dialog. */
   width?: string = '';
 

src/material/dialog/dialog-ref.ts

@@ -66,10 +66,10 @@ export class MatDialogRef<T, R = any> {
 
   constructor(
     private _ref: DialogRef<R, T>,
-    config: MatDialogConfig,
+    private _config: MatDialogConfig,
     public _containerInstance: MatDialogContainer,
   ) {
-    this.disableClose = config.disableClose;
+    this.disableClose = _config.disableClose;
     this.id = _ref.id;
 
     // Used to target panels specifically tied to dialogs.
@@ -121,6 +121,12 @@ export class MatDialogRef<T, R = any> {
    * @param dialogResult Optional result to return to the dialog opener.
    */
   close(dialogResult?: R): void {
+    const closePredicate = this._config.closePredicate;
+
+    if (closePredicate && !closePredicate(dialogResult, this._config, this.componentInstance)) {
+      return;
+    }
+
     this._result = dialogResult;
 
     // Transition the backdrop in parallel to the dialog.

src/material/dialog/dialog.spec.ts

@@ -1022,6 +1022,171 @@ describe('MatDialog', () => {
     );
   });
 
+  describe('closePredicate option', () => {
+    function getDialogs() {
+      return overlayContainerElement.querySelectorAll('mat-dialog-container');
+    }
+
+    it('should determine whether closing via the backdrop is allowed', fakeAsync(() => {
+      let canClose = false;
+      const closedSpy = jasmine.createSpy('closed spy');
+      const ref = dialog.open(PizzaMsg, {
+        closePredicate: () => canClose,
+        viewContainerRef: testViewContainerRef,
+      });
+
+      ref.afterClosed().subscribe(closedSpy);
+      viewContainerFixture.detectChanges();
+
+      expect(getDialogs().length).toBe(1);
+
+      let backdrop = overlayContainerElement.querySelector('.cdk-overlay-backdrop') as HTMLElement;
+      backdrop.click();
+      viewContainerFixture.detectChanges();
+      flush();
+
+      expect(getDialogs().length).toBe(1);
+      expect(closedSpy).not.toHaveBeenCalled();
+
+      canClose = true;
+      backdrop.click();
+      viewContainerFixture.detectChanges();
+      flush();
+
+      expect(getDialogs().length).toBe(0);
+      expect(closedSpy).toHaveBeenCalledTimes(1);
+    }));
+
+    it('should determine whether closing via the escape key is allowed', fakeAsync(() => {
+      let canClose = false;
+      const closedSpy = jasmine.createSpy('closed spy');
+      const ref = dialog.open(PizzaMsg, {
+        closePredicate: () => canClose,
+        viewContainerRef: testViewContainerRef,
+      });
+
+      ref.afterClosed().subscribe(closedSpy);
+      viewContainerFixture.detectChanges();
+
+      expect(getDialogs().length).toBe(1);
+
+      dispatchKeyboardEvent(document.body, 'keydown', ESCAPE);
+      viewContainerFixture.detectChanges();
+      flush();
+
+      expect(getDialogs().length).toBe(1);
+      expect(closedSpy).not.toHaveBeenCalled();
+
+      canClose = true;
+      dispatchKeyboardEvent(document.body, 'keydown', ESCAPE);
+      viewContainerFixture.detectChanges();
+      flush();
+
+      expect(getDialogs().length).toBe(0);
+      expect(closedSpy).toHaveBeenCalledTimes(1);
+    }));
+
+    it('should determine whether closing via the `close` method is allowed', fakeAsync(() => {
+      let canClose = false;
+      const closedSpy = jasmine.createSpy('closed spy');
+      const ref = dialog.open(PizzaMsg, {
+        closePredicate: () => canClose,
+        viewContainerRef: testViewContainerRef,
+      });
+
+      ref.afterClosed().subscribe(closedSpy);
+      viewContainerFixture.detectChanges();
+
+      expect(getDialogs().length).toBe(1);
+
+      ref.close();
+      viewContainerFixture.detectChanges();
+      flush();
+
+      expect(getDialogs().length).toBe(1);
+      expect(closedSpy).not.toHaveBeenCalled();
+
+      canClose = true;
+      ref.close('hello');
+      viewContainerFixture.detectChanges();
+      flush();
+
+      expect(getDialogs().length).toBe(0);
+      expect(closedSpy).toHaveBeenCalledTimes(1);
+      expect(closedSpy).toHaveBeenCalledWith('hello');
+    }));
+
+    it('should not be closed by `closeAll` if not allowed by the predicate', fakeAsync(() => {
+      let canClose = false;
+      const config = {closePredicate: () => canClose};
+      const spy = jasmine.createSpy('afterAllClosed spy');
+      dialog.open(PizzaMsg, config);
+      viewContainerFixture.detectChanges();
+      dialog.open(PizzaMsg, config);
+      viewContainerFixture.detectChanges();
+      dialog.open(PizzaMsg, config);
+      viewContainerFixture.detectChanges();
+
+      const subscription = dialog.afterAllClosed.subscribe(spy);
+      expect(getDialogs().length).toBe(3);
+      expect(dialog.openDialogs.length).toBe(3);
+
+      dialog.closeAll();
+      viewContainerFixture.detectChanges();
+      flush();
+
+      expect(getDialogs().length).toBe(3);
+      expect(dialog.openDialogs.length).toBe(3);
+      expect(spy).not.toHaveBeenCalled();
+
+      canClose = true;
+      dialog.closeAll();
+      viewContainerFixture.detectChanges();
+      flush();
+
+      expect(getDialogs().length).toBe(0);
+      expect(dialog.openDialogs.length).toBe(0);
+      expect(spy).toHaveBeenCalledTimes(1);
+
+      subscription.unsubscribe();
+    }));
+
+    it('should recapture focus to the first tabbable element when clicking on the backdrop while the `closePredicate` is blocking the close sequence', fakeAsync(() => {
+      // When testing focus, all of the elements must be in the DOM.
+      document.body.appendChild(overlayContainerElement);
+
+      dialog.open(PizzaMsg, {
+        closePredicate: () => false,
+        viewContainerRef: testViewContainerRef,
+      });
+
+      viewContainerFixture.detectChanges();
+      flush();
+      viewContainerFixture.detectChanges();
+      flush();
+
+      const backdrop = overlayContainerElement.querySelector(
+        '.cdk-overlay-backdrop',
+      ) as HTMLElement;
+      const input = overlayContainerElement.querySelector('input') as HTMLInputElement;
+
+      expect(document.activeElement)
+        .withContext('Expected input to be focused on open')
+        .toBe(input);
+
+      input.blur(); // Programmatic clicks might not move focus so we simulate it.
+      backdrop.click();
+      viewContainerFixture.detectChanges();
+      flush();
+
+      expect(document.activeElement)
+        .withContext('Expected input to stay focused after click')
+        .toBe(input);
+
+      overlayContainerElement.remove();
+    }));
+  });
+
   it(
     'should recapture focus to the first header when clicking on the backdrop with ' +
       'autoFocus set to "first-heading"',

src/material/dialog/dialog.ts

@@ -141,6 +141,8 @@ export class MatDialog implements OnDestroy {
       positionStrategy: this._overlay.position().global().centerHorizontally().centerVertically(),
       // Disable closing since we need to sync it up to the animation ourselves.
       disableClose: true,
+      // Closing is tied to our animation so the close predicate has to be implemented separately.
+      closePredicate: undefined,
       // Disable closing on destroy, because this service cleans up its open dialogs as well.
       // We want to do the cleanup here, rather than the CDK service, because the CDK destroys
       // the dialogs immediately whereas we want it to wait for the animations to finish.