fix(cdk/overlay): detach overlay when portal is destroyed from the outside

Fixes that some of the overlay elements were left behind when the portal is destroyed without going through the overlay API. We need to handle this case, because in many cases users don't have access to the `OverlayRef` (e.g. `MatDialog`) so that they can call `dispose` themselves.

Fixes #25163.

Author: crisbeto

src/cdk/overlay/overlay-ref.ts

@@ -158,6 +158,28 @@ export class OverlayRef implements PortalOutlet, OverlayReference {
     }
 
     this._outsideClickDispatcher.add(this);
+
+    // TODO(crisbeto): the null check is here, because the portal outlet returns `any`.
+    // We should be guaranteed for the result to be `ComponentRef | EmbeddedViewRef`, but
+    // `instanceof EmbeddedViewRef` doesn't appear to work at the moment.
+    if (typeof attachResult?.onDestroy === 'function') {
+      // In most cases we control the portal and we know when it is being detached so that
+      // we can finish the disposal process. The exception is if the user passes in a custom
+      // `ViewContainerRef` that isn't destroyed through the overlay API. Note that we use
+      // `detach` here instead of `dispose`, because we don't know if the user intends to
+      // reattach the overlay at a later point. It also has the advantage of waiting for animations.
+      attachResult.onDestroy(() => {
+        if (this.hasAttached()) {
+          // We have to wrap the `detach` call in `onStable`, because detaching immediately prevents
+          // other destroy hooks from running. This is likely a framework bug similar to
+          // https://github.com/angular/angular/issues/46119
+          this._ngZone.runOutsideAngular(() => {
+            this._ngZone.onStable.pipe(take(1)).subscribe(() => this.detach());
+          });
+        }
+      });
+    }
+
     return attachResult;
   }
 

src/cdk/overlay/overlay.spec.ts

@@ -463,6 +463,36 @@ describe('Overlay', () => {
     expect(() => overlayRef.removePanelClass([''])).not.toThrow();
   });
 
+  it('should detach a component-based overlay when the view is destroyed', () => {
+    const overlayRef = overlay.create();
+    const paneElement = overlayRef.overlayElement;
+
+    overlayRef.attach(componentPortal);
+    viewContainerFixture.detectChanges();
+
+    expect(paneElement.childNodes.length).not.toBe(0);
+
+    viewContainerFixture.destroy();
+    zone.simulateZoneExit();
+
+    expect(paneElement.childNodes.length).toBe(0);
+  });
+
+  it('should detach a template-based overlay when the view is destroyed', () => {
+    const overlayRef = overlay.create();
+    const paneElement = overlayRef.overlayElement;
+
+    overlayRef.attach(templatePortal);
+    viewContainerFixture.detectChanges();
+
+    expect(paneElement.childNodes.length).not.toBe(0);
+
+    viewContainerFixture.destroy();
+    zone.simulateZoneExit();
+
+    expect(paneElement.childNodes.length).toBe(0);
+  });
+
   describe('positioning', () => {
     let config: OverlayConfig;