feat(cdk/dialog): add closePredicate option

crisbeto · crisbeto · commit 06821d85a0d7 · 2025-04-24T21:26:29.000+02:00
Adds the `closePredicate` config option to the CDK dialog that allows developers to programmatically determine whether the user is allowed to close a dialog.

Also adds some test coverage that we had in the Material dialog, but not the CDK one.
diff --git a/goldens/cdk/dialog/index.api.md b/goldens/cdk/dialog/index.api.md
@@ -121,6 +121,7 @@ export class DialogConfig<D = unknown, R = unknown, C extends BasePortalOutlet =
     closeOnDestroy?: boolean;
     closeOnNavigation?: boolean;
     closeOnOverlayDetachments?: boolean;
+    closePredicate?: <Result = unknown, Component = unknown, Config extends DialogConfig = DialogConfig>(result: Result | undefined, config: Config, componentInstance: Component | null) => boolean;
     container?: Type<C> | {
         type: Type<C>;
         providers: (config: DialogConfig<D, R, C>) => StaticProvider[];
@@ -171,6 +172,7 @@ export class DialogRef<R = unknown, C = unknown> {
     readonly config: DialogConfig<any, DialogRef<R, C>, BasePortalOutlet>;
     readonly containerInstance: BasePortalOutlet & {
         _closeInteractionType?: FocusOrigin;
+        _recaptureFocus?: () => void;
     };
     disableClose: boolean | undefined;
     readonly id: string;
diff --git a/src/cdk/dialog/dialog-config.ts b/src/cdk/dialog/dialog-config.ts
@@ -51,6 +51,17 @@ export class DialogConfig<D = unknown, R = unknown, C extends BasePortalOutlet =
   /** Whether the dialog closes with the escape key or pointer events outside the panel element. */
   disableClose?: boolean = false;
 
+  /** Function used to determine whether the dialog is allowed to close. */
+  closePredicate?: <
+    Result = unknown,
+    Component = unknown,
+    Config extends DialogConfig = DialogConfig,
+  >(
+    result: Result | undefined,
+    config: Config,
+    componentInstance: Component | null,
+  ) => boolean;
+
   /** Width of the dialog. */
   width?: string = '';
 
diff --git a/src/cdk/dialog/dialog-container.ts b/src/cdk/dialog/dialog-container.ts
@@ -13,7 +13,6 @@ import {
   FocusTrapFactory,
   InteractivityChecker,
 } from '../a11y';
-import {OverlayRef} from '../overlay';
 import {Platform, _getFocusedElementPierceShadowDom} from '../platform';
 import {
   BasePortalOutlet,
@@ -79,7 +78,6 @@ export class CdkDialogContainer<C extends DialogConfig = DialogConfig>
   readonly _config: C;
   private _interactivityChecker = inject(InteractivityChecker);
   protected _ngZone = inject(NgZone);
-  private _overlayRef = inject(OverlayRef);
   private _focusMonitor = inject(FocusMonitor);
   private _renderer = inject(Renderer2);
 
@@ -146,7 +144,6 @@ export class CdkDialogContainer<C extends DialogConfig = DialogConfig>
 
   protected _contentAttached() {
     this._initializeFocusTrap();
-    this._handleBackdropClicks();
     this._captureInitialFocus();
   }
 
@@ -348,9 +345,7 @@ export class CdkDialogContainer<C extends DialogConfig = DialogConfig>
   /** Focuses the dialog container. */
   private _focusDialogContainer(options?: FocusOptions) {
     // Note that there is no focus method when rendering on the server.
-    if (this._elementRef.nativeElement.focus) {
-      this._elementRef.nativeElement.focus(options);
-    }
+    this._elementRef.nativeElement.focus?.(options);
   }
 
   /** Returns whether focus is inside the dialog. */
@@ -372,15 +367,4 @@ export class CdkDialogContainer<C extends DialogConfig = DialogConfig>
       }
     }
   }
-
-  /** Sets up the listener that handles clicks on the dialog backdrop. */
-  private _handleBackdropClicks() {
-    // Clicking on the backdrop will move focus out of dialog.
-    // Recapture it if closing via the backdrop is disabled.
-    this._overlayRef.backdropClick().subscribe(() => {
-      if (this._config.disableClose) {
-        this._recaptureFocus();
-      }
-    });
-  }
 }
diff --git a/src/cdk/dialog/dialog-ref.ts b/src/cdk/dialog/dialog-ref.ts
@@ -37,7 +37,10 @@ export class DialogRef<R = unknown, C = unknown> {
   readonly componentRef: ComponentRef<C> | null;
 
   /** Instance of the container that is rendering out the dialog content. */
-  readonly containerInstance: BasePortalOutlet & {_closeInteractionType?: FocusOrigin};
+  readonly containerInstance: BasePortalOutlet & {
+    _closeInteractionType?: FocusOrigin;
+    _recaptureFocus?: () => void;
+  };
 
   /** Whether the user is allowed to close the dialog. */
   disableClose: boolean | undefined;
@@ -78,8 +81,12 @@ export class DialogRef<R = unknown, C = unknown> {
     });
 
     this.backdropClick.subscribe(() => {
-      if (!this.disableClose) {
+      if (!this.disableClose && this._canClose()) {
         this.close(undefined, {focusOrigin: 'mouse'});
+      } else {
+        // Clicking on the backdrop will move focus out of dialog.
+        // Recapture it if closing via the backdrop is disabled.
+        this.containerInstance._recaptureFocus?.();
       }
     });
 
@@ -97,7 +104,7 @@ export class DialogRef<R = unknown, C = unknown> {
    * @param options Additional options to customize the closing behavior.
    */
   close(result?: R, options?: DialogCloseOptions): void {
-    if (this.containerInstance) {
+    if (this._canClose(result)) {
       const closedSubject = this.closed as Subject<R | undefined>;
       this.containerInstance._closeInteractionType = options?.focusOrigin || 'program';
       // Drop the detach subscription first since it can be triggered by the
@@ -139,4 +146,14 @@ export class DialogRef<R = unknown, C = unknown> {
     this.overlayRef.removePanelClass(classes);
     return this;
   }
+
+  /** Whether the dialog is allowed to close. */
+  private _canClose(result?: R): boolean {
+    const config = this.config as DialogConfig<unknown, unknown, BasePortalOutlet>;
+
+    return (
+      !!this.containerInstance &&
+      (!config.closePredicate || config.closePredicate(result, config, this.componentInstance))
+    );
+  }
 }
diff --git a/src/cdk/dialog/dialog.spec.ts b/src/cdk/dialog/dialog.spec.ts
@@ -689,6 +689,35 @@ describe('Dialog', () => {
     expect(dialog.getDialogById('pizza')).toBe(dialogRef);
   });
 
+  it('should recapture focus to the first tabbable element when clicking on the backdrop', fakeAsync(() => {
+    // When testing focus, all of the elements must be in the DOM.
+    document.body.appendChild(overlayContainerElement);
+
+    dialog.open(PizzaMsg, {
+      disableClose: true,
+      viewContainerRef: testViewContainerRef,
+    });
+
+    viewContainerFixture.detectChanges();
+    flushMicrotasks();
+
+    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();
+  }));
+
   describe('disableClose option', () => {
     it('should prevent closing via clicks on the backdrop', fakeAsync(() => {
       dialog.open(PizzaMsg, {
@@ -778,6 +807,169 @@ describe('Dialog', () => {
     );
   });
 
+  describe('closePredicate option', () => {
+    function getDialogs() {
+      return overlayContainerElement.querySelectorAll('cdk-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.closed.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.closed.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.closed.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();
+      flushMicrotasks();
+
+      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();
+    }));
+  });
+
   describe('hasBackdrop option', () => {
     it('should have a backdrop', () => {
       dialog.open(PizzaMsg, {
@@ -1273,6 +1465,10 @@ class PizzaMsg {
     <h2>This is the title</h2>
   `,
   imports: [DialogModule],
+  host: {
+    // Avoids conflicting ID warning
+    'id': 'content-element-dialog',
+  },
 })
 class ContentElementDialog {
   closeButtonAriaLabel: string;
@@ -1299,6 +1495,10 @@ class DialogWithInjectedData {
 @Component({
   template: '<p>Pasta</p>',
   imports: [DialogModule],
+  host: {
+    // Avoids conflicting ID warning
+    'id': 'dialog-without-focusable',
+  },
 })
 class DialogWithoutFocusableElements {}
 
