refactor(cdk/overlay): add opt-in popover behavior

Adds the option for the connected overlay to opt into being rendered into a native popover, instead of the overlay container.

Author: crisbeto

goldens/cdk/overlay/index.api.md

@@ -222,7 +222,14 @@ export function createRepositionScrollStrategy(injector: Injector, config?: Repo
 export class FlexibleConnectedPositionStrategy implements PositionStrategy {
     constructor(connectedTo: FlexibleConnectedPositionStrategyOrigin, _viewportRuler: ViewportRuler, _document: Document, _platform: Platform, _overlayContainer: OverlayContainer);
     apply(): void;
+    asPopover(isPopover: boolean): this;
     attach(overlayRef: OverlayRef): void;
+    attachBackdrop(backdrop: HTMLElement, host: HTMLElement): boolean;
+    attachHost(host: HTMLElement): boolean;
+    createStructure(): {
+        pane: HTMLDivElement;
+        host: HTMLDivElement;
+    } | null;
     // (undocumented)
     detach(): void;
     dispose(): void;
@@ -459,6 +466,12 @@ export interface OverlaySizeConfig {
 export interface PositionStrategy {
     apply(): void;
     attach(overlayRef: OverlayRef): void;
+    attachBackdrop?(backdrop: HTMLElement, host: HTMLElement): boolean;
+    attachHost?(host: HTMLElement): boolean;
+    createStructure?(): {
+        pane: HTMLElement;
+        host: HTMLElement;
+    } | null;
     detach?(): void;
     dispose(): void;
 }

src/cdk/overlay/_index.scss

@@ -185,6 +185,29 @@ $backdrop-animation-timing-function: cubic-bezier(0.25, 0.8, 0.25, 1) !default;
     // block scrolling on a page that doesn't have a scrollbar in the first place.
     overflow-y: scroll;
   }
+
+  .cdk-overlay-popover {
+    background: none;
+    border: none;
+    padding: 0;
+    color: inherit;
+    outline: 0;
+    overflow: visible;
+    position: fixed;
+    pointer-events: none;
+
+    // These are important so the overlay can be measured before it's fully inserted.
+    width: 100%;
+    height: 100%;
+
+    // Chrome sets a user agent style of `inset: 0` which combined
+    // with `align-self` can break the positioning (see #29809).
+    inset: auto;
+
+    .cdk-overlay-backdrop {
+      position: fixed;
+    }
+  }
 }
 
 /// Emits structural styles required for cdk/overlay to function.

src/cdk/overlay/overlay-ref.ts

@@ -117,17 +117,23 @@ export class OverlayRef implements PortalOutlet {
   attach(portal: Portal<any>): any {
     // Insert the host into the DOM before attaching the portal, otherwise
     // the animations module will skip animations on repeat attachments.
-    if (!this._host.parentElement && this._previousHostParent) {
-      this._previousHostParent.appendChild(this._host);
+    if (!this._host.parentElement) {
+      const customIsAttached = this._positionStrategy?.attachHost?.(this._host);
+
+      if (!customIsAttached && this._previousHostParent) {
+        this._previousHostParent.appendChild(this._host);
+      }
     }
 
     const attachResult = this._portalOutlet.attach(portal);
+    this._positionStrategy?.attach(this);
 
-    if (this._positionStrategy) {
-      this._positionStrategy.attach(this);
+    // If the position strategy overrides the attachment behavior,
+    // it's assumed that it'll handle the stacking order as well.
+    if (!this._positionStrategy?.attachHost) {
+      this._updateStackingOrder();
     }
 
-    this._updateStackingOrder();
     this._updateElementSize();
     this._updateElementDirection();
 
@@ -426,9 +432,16 @@ export class OverlayRef implements PortalOutlet {
       this._toggleClasses(this._backdropRef.element, this._config.backdropClass, true);
     }
 
-    // Insert the backdrop before the pane in the DOM order,
-    // in order to handle stacked overlays properly.
-    this._host.parentElement!.insertBefore(this._backdropRef.element, this._host);
+    const strategyAttached = this._positionStrategy?.attachBackdrop?.(
+      this._backdropRef.element,
+      this._host,
+    );
+
+    if (!strategyAttached) {
+      // Insert the backdrop before the pane in the DOM order,
+      // in order to handle stacked overlays properly.
+      this._host.parentElement!.insertBefore(this._backdropRef.element, this._host);
+    }
 
     // Add class to fade-in the backdrop after one frame.
     if (!this._animationsDisabled && typeof requestAnimationFrame !== 'undefined') {

src/cdk/overlay/overlay.ts

@@ -47,17 +47,26 @@ export function createOverlayRef(injector: Injector, config?: OverlayConfig): Ov
   const idGenerator = injector.get(_IdGenerator);
   const appRef = injector.get(ApplicationRef);
   const directionality = injector.get(Directionality);
+  const overlayConfig = new OverlayConfig(config);
+  const customStructure = overlayConfig.positionStrategy?.createStructure?.();
+
+  let pane: HTMLElement;
+  let host: HTMLElement;
 
-  const host = doc.createElement('div');
-  const pane = doc.createElement('div');
+  if (customStructure) {
+    pane = customStructure.pane;
+    host = customStructure.host;
+  } else {
+    host = doc.createElement('div');
+    pane = doc.createElement('div');
+    host.appendChild(pane);
+    overlayContainer.getContainerElement().appendChild(host);
+  }
 
   pane.id = idGenerator.getId('cdk-overlay-');
   pane.classList.add('cdk-overlay-pane');
-  host.appendChild(pane);
-  overlayContainer.getContainerElement().appendChild(host);
 
   const portalOutlet = new DomPortalOutlet(pane, appRef, injector);
-  const overlayConfig = new OverlayConfig(config);
   const renderer =
     injector.get(Renderer2, null, {optional: true}) ||
     injector.get(RendererFactory2).createRenderer(null, null);

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

@@ -33,6 +33,7 @@ describe('FlexibleConnectedPositionStrategy', () => {
   let overlayRef: OverlayRef;
   let viewport: ViewportRuler;
   let injector: Injector;
+  let portal: ComponentPortal<TestOverlay>;
 
   beforeEach(() => {
     injector = TestBed.inject(Injector);
@@ -50,7 +51,8 @@ describe('FlexibleConnectedPositionStrategy', () => {
 
   function attachOverlay(config: OverlayConfig) {
     overlayRef = createOverlayRef(injector, config);
-    overlayRef.attach(new ComponentPortal(TestOverlay));
+    portal = new ComponentPortal(TestOverlay);
+    overlayRef.attach(portal);
     TestBed.inject(ApplicationRef).tick();
   }
 
@@ -125,7 +127,7 @@ describe('FlexibleConnectedPositionStrategy', () => {
     origin.remove();
   });
 
-  it('should for the virtual keyboard offset when positioning the overlay', () => {
+  it('should account for the virtual keyboard offset when positioning the overlay', () => {
     const originElement = createPositionedBlockElement();
     document.body.appendChild(originElement);
 
@@ -2951,6 +2953,70 @@ describe('FlexibleConnectedPositionStrategy', () => {
       expect(overlayClassList).toContain('custom-panel-class');
     });
   });
+
+  describe('DOM location', () => {
+    let positionStrategy: FlexibleConnectedPositionStrategy;
+    let containerElement: HTMLElement;
+    let originElement: HTMLElement;
+
+    beforeEach(() => {
+      containerElement = overlayContainer.getContainerElement();
+      originElement = createPositionedBlockElement();
+      document.body.appendChild(originElement);
+
+      positionStrategy = createFlexibleConnectedPositionStrategy(
+        injector,
+        originElement,
+      ).withPositions([
+        {
+          overlayX: 'start',
+          overlayY: 'top',
+          originX: 'start',
+          originY: 'bottom',
+        },
+      ]);
+    });
+
+    afterEach(() => {
+      originElement.remove();
+    });
+
+    it('should place the overlay inside the overlay container by default', () => {
+      attachOverlay({positionStrategy});
+      expect(containerElement.contains(overlayRef.hostElement)).toBe(true);
+      expect(overlayRef.hostElement.getAttribute('popover')).toBeFalsy();
+    });
+
+    it('should be able to opt into placing the overlay inside an adjacent popover element', () => {
+      if (!('showPopover' in document.body)) {
+        return;
+      }
+
+      positionStrategy.asPopover(true);
+      attachOverlay({positionStrategy});
+
+      expect(containerElement.contains(overlayRef.hostElement)).toBe(false);
+      expect(originElement.nextElementSibling).toBe(overlayRef.hostElement);
+      expect(overlayRef.hostElement.getAttribute('popover')).toBe('manual');
+    });
+
+    it('should re-attach the popover next to the origin element', () => {
+      if (!('showPopover' in document.body)) {
+        return;
+      }
+
+      positionStrategy.asPopover(true);
+      attachOverlay({positionStrategy});
+      expect(originElement.nextElementSibling).toBe(overlayRef.hostElement);
+
+      overlayRef.detach();
+      TestBed.inject(ApplicationRef).tick();
+      expect(overlayRef.hostElement.parentNode).toBeFalsy();
+
+      overlayRef.attach(portal);
+      expect(originElement.nextElementSibling).toBe(overlayRef.hostElement);
+    });
+  });
 });
 
 /** Creates an absolutely positioned, display: block element with a default size. */

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

@@ -95,6 +95,9 @@ export class FlexibleConnectedPositionStrategy implements PositionStrategy {
   /** Whether the overlay position is locked. */
   private _positionLocked = false;
 
+  /** Whether the overlay is using popovers for positioning. */
+  private _popoverEnabled = false;
+
   /** Cached origin dimensions */
   private _originRect: Dimensions;
 
@@ -511,6 +514,67 @@ export class FlexibleConnectedPositionStrategy implements PositionStrategy {
     return this;
   }
 
+  /**
+   * Configures that the overlay should be rendered inside a native popover. This has the benefit
+   * if co-locating the overlay with the trigger and being better for accessibility.
+   * @param isPopover Whether the overlay should be a popover.
+   */
+  asPopover(isPopover: boolean): this {
+    this._popoverEnabled = isPopover && 'showPopover' in this._document.body;
+    return this;
+  }
+
+  /** @docs-private */
+  createStructure() {
+    if (!this._popoverEnabled) {
+      return null;
+    }
+
+    const pane = this._document.createElement('div');
+    const host = this._document.createElement('div');
+    host.setAttribute('popover', 'manual');
+    host.classList.add('cdk-overlay-popover');
+    host.appendChild(pane);
+    this.attachHost(host);
+    return {pane, host};
+  }
+
+  /** @docs-private */
+  attachHost(host: HTMLElement) {
+    if (!this._popoverEnabled) {
+      return false;
+    }
+
+    if (!host.parentNode) {
+      let originEl: Element | null;
+
+      if (this._origin instanceof ElementRef) {
+        originEl = this._origin.nativeElement;
+      } else if (typeof Element !== 'undefined' && this._origin instanceof Element) {
+        originEl = this._origin;
+      } else {
+        originEl = null;
+      }
+
+      if (originEl) {
+        originEl.after(host);
+      } else {
+        document.body.appendChild(host);
+      }
+    }
+
+    host.showPopover();
+    return true;
+  }
+
+  /** @docs-private */
+  attachBackdrop(backdrop: HTMLElement, host: HTMLElement) {
+    if (this._popoverEnabled) {
+      host.prepend(backdrop);
+    }
+    return this._popoverEnabled;
+  }
+
   /**
    * Gets the (x, y) coordinate of a connection point on the origin based on a relative position.
    */

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

@@ -21,4 +21,16 @@ export interface PositionStrategy {
 
   /** Cleans up any DOM modifications made by the position strategy, if necessary. */
   dispose(): void;
+
+  /**
+   * Creates the structure of the overlay. If not provided,
+   * structure will be created inside the overlay container.
+   */
+  createStructure?(): {pane: HTMLElement; host: HTMLElement} | null;
+
+  /** Attaches the host element to the DOM. */
+  attachHost?(host: HTMLElement): boolean;
+
+  /** Attaches the backdrop element to the host. */
+  attachBackdrop?(backdrop: HTMLElement, host: HTMLElement): boolean;
 }