feat(cdk/overlay): Allow passing separate X and Y values for the viewportMargin

The overlay directive now accepts two additional (optional parameters) [viewportMarginX] and [viewportMarginY]. You can use these to pass separate margin values for the viewport.

Author: LukeyBeachBoy

Diff for: src/cdk/overlay/overlay-directives.ts

@@ -177,9 +177,21 @@ export class CdkConnectedOverlay implements OnDestroy, OnChanges {
   /** The custom class to add to the overlay pane element. */
   @Input('cdkConnectedOverlayPanelClass') panelClass: string | string[];
 
-  /** Margin between the overlay and the viewport edges. */
+  /** Margin (both horizontal and vertical) between the overlay and the viewport edges. */
   @Input('cdkConnectedOverlayViewportMargin') viewportMargin: number = 0;
 
+  /** Margin between the overlay and the left viewport edge. */
+  @Input('cdkConnectedOverlayViewportMarginLeft') viewportMarginLeft: number = 0;
+
+  /** Margin between the overlay and the right viewport edge. */
+  @Input('cdkConnectedOverlayViewportMarginRight') viewportMarginRight: number = 0;
+
+  /** Margin between the overlay and the top viewport edge. */
+  @Input('cdkConnectedOverlayViewportMarginTop') viewportMarginTop: number = 0;
+
+  /** Margin between the overlay and the bottom viewport edge. */
+  @Input('cdkConnectedOverlayViewportMarginBottom') viewportMarginBottom: number = 0;
+
   /** Strategy to be used when handling scroll events while the overlay is open. */
   @Input('cdkConnectedOverlayScrollStrategy') scrollStrategy: ScrollStrategy;
 
@@ -378,7 +390,10 @@ export class CdkConnectedOverlay implements OnDestroy, OnChanges {
       .withFlexibleDimensions(this.flexibleDimensions)
       .withPush(this.push)
       .withGrowAfterOpen(this.growAfterOpen)
-      .withViewportMargin(this.viewportMargin)
+      .withViewportMarginTop(this.viewportMarginTop ?? this.viewportMargin ?? 0)
+      .withViewportMarginRight(this.viewportMarginRight ?? this.viewportMargin ?? 0)
+      .withViewportMarginBottom(this.viewportMarginBottom ?? this.viewportMargin ?? 0)
+      .withViewportMarginLeft(this.viewportMarginLeft ?? this.viewportMargin ?? 0)
       .withLockedPosition(this.lockPosition)
       .withTransformOriginOn(this.transformOriginSelector);
   }

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

@@ -1367,6 +1367,53 @@ describe('FlexibleConnectedPositionStrategy', () => {
       expect(Math.floor(overlayRect.top)).toBe(15);
     });
 
+    it('should set separate margins when pushing the overlay into the viewport', () => {
+      originElement.style.top = `${-OVERLAY_HEIGHT}px`;
+      originElement.style.left = `${-OVERLAY_WIDTH / 2}px`;
+
+      positionStrategy
+        .withViewportMarginTop(15)
+        .withViewportMarginBottom(30)
+        .withViewportMarginLeft(10)
+        .withPositions([
+          {
+            originX: 'start',
+            originY: 'bottom',
+            overlayX: 'start',
+            overlayY: 'top',
+          },
+        ]);
+
+      attachOverlay({positionStrategy});
+
+      const overlayRect = overlayRef.overlayElement.getBoundingClientRect();
+      expect(Math.floor(overlayRect.left)).toBe(10);
+      expect(Math.floor(overlayRect.top)).toBe(15);
+      expect(Math.floor(overlayRect.bottom)).toBe(30);
+    });
+
+    it('should only set the margins that were provided when pushing the overlay into the viewport from both axes', () => {
+      originElement.style.top = `${-OVERLAY_HEIGHT / 2}px`;
+      originElement.style.left = `${-OVERLAY_WIDTH / 2}px`;
+
+      positionStrategy.withViewportMarginLeft(30).withPositions([
+        {
+          originX: 'start',
+          originY: 'bottom',
+          overlayX: 'start',
+          overlayY: 'top',
+        },
+      ]);
+
+      attachOverlay({positionStrategy});
+
+      const overlayRect = overlayRef.overlayElement.getBoundingClientRect();
+      expect(Math.floor(overlayRect.left)).toBe(30);
+      expect(Math.floor(overlayRect.right)).toBe(0);
+      expect(Math.floor(overlayRect.top)).toBe(0);
+      expect(Math.floor(overlayRect.bottom)).toBe(0);
+    });
+
     it('should not mess with the left offset when pushing from the top', () => {
       originElement.style.top = `${-OVERLAY_HEIGHT * 2}px`;
       originElement.style.left = '200px';

Diff for: src/cdk/overlay/position/flexible-connected-position-strategy.ts

@@ -88,8 +88,17 @@ export class FlexibleConnectedPositionStrategy implements PositionStrategy {
   /** Cached container dimensions */
   private _containerRect: Dimensions;
 
-  /** Amount of space that must be maintained between the overlay and the edge of the viewport. */
-  private _viewportMargin = 0;
+  /** Amount of space that must be maintained between the overlay and the top edge of the viewport. */
+  private _viewportMarginTop = 0;
+
+  /** Amount of space that must be maintained between the overlay and the bottom edge of the viewport. */
+  private _viewportMarginBottom = 0;
+
+  /** Amount of space that must be maintained between the overlay and the left edge of the viewport. */
+  private _viewportMarginLeft = 0;
+
+  /** Amount of space that must be maintained between the overlay and the right edge of the viewport. */
+  private _viewportMarginRight = 0;
 
   /** The Scrollable containers used to check scrollable view properties on position change. */
   private _scrollables: CdkScrollable[] = [];
@@ -411,11 +420,38 @@ export class FlexibleConnectedPositionStrategy implements PositionStrategy {
   }
 
   /**
-   * Sets a minimum distance the overlay may be positioned to the edge of the viewport.
+   * Sets a minimum distance the overlay may be positioned from the left edge of the viewport.
+   * @param margin Required margin between the overlay and the viewport edge in pixels.
+   */
+  withViewportMarginLeft(margin: number): this {
+    this._viewportMarginLeft = margin;
+    return this;
+  }
+
+  /**
+   * Sets a minimum distance the overlay may be positioned from the right edge of the viewport.
    * @param margin Required margin between the overlay and the viewport edge in pixels.
    */
-  withViewportMargin(margin: number): this {
-    this._viewportMargin = margin;
+  withViewportMarginRight(margin: number): this {
+    this._viewportMarginRight = margin;
+    return this;
+  }
+
+  /**
+   * Sets a minimum distance the overlay may be positioned from the top edge of the viewport.
+   * @param margin Required vertical margin between the overlay and the viewport edge in pixels.
+   */
+  withViewportMarginTop(margin: number): this {
+    this._viewportMarginTop = margin;
+    return this;
+  }
+
+  /**
+   * Sets a minimum distance the overlay may be positioned from the bottom edge of the viewport.
+   * @param margin Required vertical margin between the overlay and the viewport edge in pixels.
+   */
+  withViewportMarginBottom(margin: number): this {
+    this._viewportMarginBottom = margin;
     return this;
   }
 
@@ -682,13 +718,13 @@ export class FlexibleConnectedPositionStrategy implements PositionStrategy {
     if (overlay.width <= viewport.width) {
       pushX = overflowLeft || -overflowRight;
     } else {
-      pushX = start.x < this._viewportMargin ? viewport.left - scrollPosition.left - start.x : 0;
+      pushX = start.x < this._viewportMarginLeft ? viewport.left - scrollPosition.left - start.x : 0;
     }
 
     if (overlay.height <= viewport.height) {
       pushY = overflowTop || -overflowBottom;
     } else {
-      pushY = start.y < this._viewportMargin ? viewport.top - scrollPosition.top - start.y : 0;
+      pushY = start.y < this._viewportMarginTop ? viewport.top - scrollPosition.top - start.y : 0;
     }
 
     this._previousPushAmount = {x: pushX, y: pushY};
@@ -777,13 +813,13 @@ export class FlexibleConnectedPositionStrategy implements PositionStrategy {
     if (position.overlayY === 'top') {
       // Overlay is opening "downward" and thus is bound by the bottom viewport edge.
       top = origin.y;
-      height = viewport.height - top + this._viewportMargin;
+      height = viewport.height - top + this._viewportMarginBottom;
     } else if (position.overlayY === 'bottom') {
       // Overlay is opening "upward" and thus is bound by the top viewport edge. We need to add
       // the viewport margin back in, because the viewport rect is narrowed down to remove the
       // margin, whereas the `origin` position is calculated based on its `DOMRect`.
-      bottom = viewport.height - origin.y + this._viewportMargin * 2;
-      height = viewport.height - bottom + this._viewportMargin;
+      bottom = viewport.height - origin.y + this._viewportMarginTop + this._viewportMarginBottom;
+      height = viewport.height - bottom + this._viewportMarginTop;
     } else {
       // If neither top nor bottom, it means that the overlay is vertically centered on the
       // origin point. Note that we want the position relative to the viewport, rather than
@@ -815,11 +851,11 @@ export class FlexibleConnectedPositionStrategy implements PositionStrategy {
     let width: number, left: number, right: number;
 
     if (isBoundedByLeftViewportEdge) {
-      right = viewport.width - origin.x + this._viewportMargin * 2;
-      width = origin.x - this._viewportMargin;
+      right = viewport.width - origin.x + this._viewportMarginLeft + this._viewportMarginRight;
+      width = origin.x - this._viewportMarginLeft;
     } else if (isBoundedByRightViewportEdge) {
       left = origin.x;
-      width = viewport.right - origin.x;
+      width = viewport.right - origin.x - this._viewportMarginRight;
     } else {
       // If neither start nor end, it means that the overlay is horizontally centered on the
       // origin point. Note that we want the position relative to the viewport, rather than
@@ -1098,12 +1134,12 @@ export class FlexibleConnectedPositionStrategy implements PositionStrategy {
     const scrollPosition = this._viewportRuler.getViewportScrollPosition();
 
     return {
-      top: scrollPosition.top + this._viewportMargin,
-      left: scrollPosition.left + this._viewportMargin,
-      right: scrollPosition.left + width - this._viewportMargin,
-      bottom: scrollPosition.top + height - this._viewportMargin,
-      width: width - 2 * this._viewportMargin,
-      height: height - 2 * this._viewportMargin,
+      top: scrollPosition.top + this._viewportMarginTop,
+      left: scrollPosition.left + this._viewportMarginLeft,
+      right: scrollPosition.left + width - this._viewportMarginRight,
+      bottom: scrollPosition.top + height - this._viewportMarginBottom,
+      width: width - this._viewportMarginLeft - this._viewportMarginRight,
+      height: height - this._viewportMarginTop - this._viewportMarginBottom,
     };
   }