refactor(cdk/overlay): enhance popover insertion control with new inputs

This commit introduces two new inputs to the CDK overlay, providing more granular control over how popovers are inserted into the DOM:

- : Allows specifying a custom element to be used as the host for the popover. The popover will be inserted after this element in the DOM.

- : A boolean that, when true, attaches the popover as a child of the popover host, rather than as a sibling.

Author: tjshiu

goldens/cdk/overlay/index.api.md

@@ -297,6 +297,8 @@ export class FlexibleConnectedPositionStrategy implements PositionStrategy {
     withGrowAfterOpen(growAfterOpen?: boolean): this;
     withLockedPosition(isLocked?: boolean): this;
     withPopoverLocation(location: FlexibleOverlayPopoverLocation): this;
+    withCustomPopoverHostElement(element: FlexibleConnectedPositionStrategyOrigin): this;
+    withAttachPopoverAsChild(withAttachPopoverAsChild?: boolean): this;
     withPositions(positions: ConnectedPosition[]): this;
     withPush(canPush?: boolean): this;
     withScrollableContainers(scrollables: CdkScrollable[]): this;

src/cdk/overlay/overlay-config.ts

@@ -67,6 +67,13 @@ export class OverlayConfig {
    */
   usePopover?: boolean;
 
+  /**
+   * Whether to attach the popover as a child of the popover host.
+   * If true, the popover will be attached as a child of the host.
+   * If false, the popover will be attached after the host.
+   */
+  attachPopoverAsChild?: boolean;
+
   constructor(config?: OverlayConfig) {
     if (config) {
       // Use `Iterable` instead of `Array` because TypeScript, as of 3.6.3,

src/cdk/overlay/overlay-directives.ts

@@ -129,6 +129,8 @@ export interface CdkConnectedOverlayConfig {
   push?: boolean;
   disposeOnNavigation?: boolean;
   usePopover?: FlexibleOverlayPopoverLocation | null;
+  customPopoverHostElement?: CdkOverlayOrigin | FlexibleConnectedPositionStrategyOrigin | null;
+  attachPopoverAsChild?: boolean;
   matchWidth?: boolean;
 }
 
@@ -259,6 +261,22 @@ export class CdkConnectedOverlay implements OnDestroy, OnChanges {
   @Input({alias: 'cdkConnectedOverlayMatchWidth', transform: booleanAttribute})
   matchWidth: boolean = false;
 
+  /**
+   * A custom element to use as the host for the popover.
+   * The popover will be inserted after this element in the DOM.
+   * If null, the overlay will be inserted after the origin.
+   */
+  @Input({alias: 'cdkCustomPopoverInsertionElement'})
+  customPopoverHostElement: CdkOverlayOrigin | FlexibleConnectedPositionStrategyOrigin | null;
+
+  /**
+   * Whether to attach the popover as a child of the popover host.
+   * If true, the popover will be attached as a child of the host.
+   * If false, the popover will be attached after the host.
+   */
+  @Input({alias: 'cdkAttachPopoverAsChild', transform: booleanAttribute})
+  attachPopoverAsChild: boolean = false;
+
   /** Shorthand for setting multiple overlay options at once. */
   @Input('cdkConnectedOverlay')
   set _config(value: string | CdkConnectedOverlayConfig) {
@@ -338,6 +356,8 @@ export class CdkConnectedOverlay implements OnDestroy, OnChanges {
     }
 
     if (changes['open']) {
+      console.log('changes[open]');
+      console.log(this.open);
       this.open ? this.attachOverlay() : this.detachOverlay();
     }
   }
@@ -381,6 +401,7 @@ export class CdkConnectedOverlay implements OnDestroy, OnChanges {
       hasBackdrop: this.hasBackdrop,
       disposeOnNavigation: this.disposeOnNavigation,
       usePopover: !!this.usePopover,
+      attachPopoverAsChild: this.attachPopoverAsChild,
     });
 
     if (this.height || this.height === 0) {
@@ -427,7 +448,9 @@ export class CdkConnectedOverlay implements OnDestroy, OnChanges {
       .withViewportMargin(this.viewportMargin)
       .withLockedPosition(this.lockPosition)
       .withTransformOriginOn(this.transformOriginSelector)
-      .withPopoverLocation(this.usePopover === 'global' ? 'global' : 'inline');
+      .withPopoverLocation(this.usePopover === 'global' ? 'global' : 'inline')
+      .withCustomPopoverHostElement(this._getCustomPopoverHostElement())
+      .withAttachPopoverAsChild(this.attachPopoverAsChild);
   }
 
   /** Returns the position strategy of the overlay to be set on the overlay config */
@@ -445,6 +468,18 @@ export class CdkConnectedOverlay implements OnDestroy, OnChanges {
     }
   }
 
+  /**
+   * Gets the custom popover host element from the origin input.
+   * @docs-private
+   */
+  private _getCustomPopoverHostElement(): FlexibleConnectedPositionStrategyOrigin | null {
+    if (this.customPopoverHostElement instanceof CdkOverlayOrigin) {
+      return this.customPopoverHostElement.elementRef;
+    } else {
+      return this.customPopoverHostElement;
+    }
+  }
+
   private _getOriginElement(): Element | null {
     if (this.origin instanceof CdkOverlayOrigin) {
       return this.origin.elementRef.nativeElement;
@@ -544,6 +579,9 @@ export class CdkConnectedOverlay implements OnDestroy, OnChanges {
     this.push = config.push ?? this.push;
     this.disposeOnNavigation = config.disposeOnNavigation ?? this.disposeOnNavigation;
     this.usePopover = config.usePopover ?? this.usePopover;
+    this.customPopoverHostElement =
+      config.customPopoverHostElement ?? this.customPopoverHostElement;
+    this.attachPopoverAsChild = config.attachPopoverAsChild ?? this.attachPopoverAsChild;
     this.matchWidth = config.matchWidth ?? this.matchWidth;
   }
 }

src/cdk/overlay/overlay-ref.ts

@@ -410,7 +410,9 @@ export class OverlayRef implements PortalOutlet {
         : null;
 
       if (customInsertionPoint) {
-        customInsertionPoint.after(this._host);
+        this._config.attachPopoverAsChild
+          ? customInsertionPoint.appendChild(this._host)
+          : customInsertionPoint.after(this._host);
       } else {
         this._previousHostParent?.appendChild(this._host);
       }

src/cdk/overlay/overlay.ts

@@ -95,7 +95,11 @@ export function createOverlayRef(injector: Injector, config?: OverlayConfig): Ov
   // it's going to end up at the custom insertion point anyways. We need to do it,
   // because some internal clients depend on the host passing through the container first.
   if (customInsertionPoint) {
-    customInsertionPoint.after(host);
+    if (overlayConfig.attachPopoverAsChild) {
+      customInsertionPoint.appendChild(host);
+    } else {
+      customInsertionPoint.after(host);
+    }
   }
 
   return new OverlayRef(

src/cdk/overlay/position/flexible-connected-position-strategy.spec.ts

@@ -2959,11 +2959,14 @@ describe('FlexibleConnectedPositionStrategy', () => {
     let positionStrategy: FlexibleConnectedPositionStrategy;
     let containerElement: HTMLElement;
     let originElement: HTMLElement;
+    let customHostElement: HTMLElement;
 
     beforeEach(() => {
       containerElement = overlayContainer.getContainerElement();
       originElement = createPositionedBlockElement();
+      customHostElement = createBlockElement('span');
       document.body.appendChild(originElement);
+      document.body.appendChild(customHostElement);
 
       positionStrategy = createFlexibleConnectedPositionStrategy(injector, originElement)
         .withPopoverLocation('inline')
@@ -2979,6 +2982,7 @@ describe('FlexibleConnectedPositionStrategy', () => {
 
     afterEach(() => {
       originElement.remove();
+      customHostElement.remove();
     });
 
     it('should place the overlay inside the overlay container by default', () => {
@@ -3014,6 +3018,32 @@ describe('FlexibleConnectedPositionStrategy', () => {
       overlayRef.attach(portal);
       expect(originElement.nextElementSibling).toBe(overlayRef.hostElement);
     });
+
+    it('should insert the overlay after a custom element', () => {
+      if (!('showPopover' in document.body)) {
+        return;
+      }
+
+      positionStrategy.withCustomPopoverHostElement(customHostElement);
+      attachOverlay({positionStrategy, usePopover: true});
+
+      expect(containerElement.contains(overlayRef.hostElement)).toBe(false);
+      expect(customHostElement.nextElementSibling).toBe(overlayRef.hostElement);
+      expect(overlayRef.hostElement.getAttribute('popover')).toBe('manual');
+    });
+
+    it('should insert the overlay as a child of the origin', () => {
+      if (!('showPopover' in document.body)) {
+        return;
+      }
+
+      console.log(positionStrategy.getPopoverInsertionPoint());
+      attachOverlay({positionStrategy, usePopover: true, attachPopoverAsChild: true});
+
+      expect(containerElement.contains(overlayRef.hostElement)).toBe(false);
+      expect(originElement.contains(overlayRef.hostElement)).toBe(true);
+      expect(overlayRef.hostElement.getAttribute('popover')).toBe('manual');
+    });
   });
 });
 

src/cdk/overlay/position/flexible-connected-position-strategy.ts

@@ -164,6 +164,18 @@ export class FlexibleConnectedPositionStrategy implements PositionStrategy {
   /** Configures where in the DOM to insert the overlay when popovers are enabled. */
   private _popoverLocation: FlexibleOverlayPopoverLocation = 'global';
 
+  /**
+   * Defines a specific host element for the popover content. If provided, the popover will attach
+   * to this element.
+   * */
+  private _customPopoverHostElement: FlexibleConnectedPositionStrategyOrigin | null;
+
+  /**
+   * Whether the popover is attached directly as a child of the popover host element instead of
+   * a sibling element.
+   * */
+  private _attachPopoverAsChild = false;
+
   /** Observable sequence of position changes. */
   positionChanges: Observable<ConnectedOverlayPositionChange> = this._positionChanges;
 
@@ -528,14 +540,26 @@ export class FlexibleConnectedPositionStrategy implements PositionStrategy {
     return this;
   }
 
+  /**
+   * Sets a custom element to use as the host for the popover.
+   * The popover will be inserted after this element in the DOM.
+   * If null, the overlay will be inserted after the origin.
+   * @param element The element to use as the host for the popover.
+   */
+  withCustomPopoverHostElement(element: FlexibleConnectedPositionStrategyOrigin | null): this {
+    this._customPopoverHostElement = element;
+    return this;
+  }
+
   /** @docs-private */
   getPopoverInsertionPoint(): Element | null {
     // Return null so it falls back to inserting into the overlay container.
     if (this._popoverLocation === 'global') {
       return null;
     }
 
-    const origin = this._origin;
+    const origin =
+      this._customPopoverHostElement != null ? this._customPopoverHostElement : this._origin;
 
     if (origin instanceof ElementRef) {
       return origin.nativeElement;
@@ -545,6 +569,17 @@ export class FlexibleConnectedPositionStrategy implements PositionStrategy {
     return null;
   }
 
+  /**
+   * Whether to attach the popover as a child of the popover host.
+   * If true, the popover will be attached as a child of the host.
+   * If false, the popover will be attached after the host.
+   * @param attachPopoverAsChild Whether to attach the popover as a child of the popover host.
+   */
+  withAttachPopoverAsChild(attachPopoverAsChild = false): this {
+    this._attachPopoverAsChild = attachPopoverAsChild;
+    return this;
+  }
+
   /**
    * Gets the (x, y) coordinate of a connection point on the origin based on a relative position.
    */