fix(cdk/overlay): simplify matching the overlay to the trigger width

The connected overlay directive allows users to control its width using the `cdkConnectedOverlayMatchWidth` input. This can be tricky when it needs to match another element like the trigger.

Since this is a common for cases like dropdowns, these changes add the `cdkConnectedOverlayMatchWidth` input to simplify it.

Author: crisbeto

goldens/cdk/overlay/index.api.md

@@ -55,6 +55,7 @@ export class CdkConnectedOverlay implements OnDestroy, OnChanges {
     hasBackdrop: boolean;
     height: number | string;
     lockPosition: boolean;
+    matchWidth: boolean;
     minHeight: number | string;
     minWidth: number | string;
     // (undocumented)
@@ -68,6 +69,8 @@ export class CdkConnectedOverlay implements OnDestroy, OnChanges {
     // (undocumented)
     static ngAcceptInputType_lockPosition: unknown;
     // (undocumented)
+    static ngAcceptInputType_matchWidth: unknown;
+    // (undocumented)
     static ngAcceptInputType_push: unknown;
     // (undocumented)
     static ngAcceptInputType_usePopover: unknown;
@@ -95,7 +98,7 @@ export class CdkConnectedOverlay implements OnDestroy, OnChanges {
     viewportMargin: ViewportMargin;
     width: number | string;
     // (undocumented)
-    static ɵdir: i0.ɵɵDirectiveDeclaration<CdkConnectedOverlay, "[cdk-connected-overlay], [connected-overlay], [cdkConnectedOverlay]", ["cdkConnectedOverlay"], { "origin": { "alias": "cdkConnectedOverlayOrigin"; "required": false; }; "positions": { "alias": "cdkConnectedOverlayPositions"; "required": false; }; "positionStrategy": { "alias": "cdkConnectedOverlayPositionStrategy"; "required": false; }; "offsetX": { "alias": "cdkConnectedOverlayOffsetX"; "required": false; }; "offsetY": { "alias": "cdkConnectedOverlayOffsetY"; "required": false; }; "width": { "alias": "cdkConnectedOverlayWidth"; "required": false; }; "height": { "alias": "cdkConnectedOverlayHeight"; "required": false; }; "minWidth": { "alias": "cdkConnectedOverlayMinWidth"; "required": false; }; "minHeight": { "alias": "cdkConnectedOverlayMinHeight"; "required": false; }; "backdropClass": { "alias": "cdkConnectedOverlayBackdropClass"; "required": false; }; "panelClass": { "alias": "cdkConnectedOverlayPanelClass"; "required": false; }; "viewportMargin": { "alias": "cdkConnectedOverlayViewportMargin"; "required": false; }; "scrollStrategy": { "alias": "cdkConnectedOverlayScrollStrategy"; "required": false; }; "open": { "alias": "cdkConnectedOverlayOpen"; "required": false; }; "disableClose": { "alias": "cdkConnectedOverlayDisableClose"; "required": false; }; "transformOriginSelector": { "alias": "cdkConnectedOverlayTransformOriginOn"; "required": false; }; "hasBackdrop": { "alias": "cdkConnectedOverlayHasBackdrop"; "required": false; }; "lockPosition": { "alias": "cdkConnectedOverlayLockPosition"; "required": false; }; "flexibleDimensions": { "alias": "cdkConnectedOverlayFlexibleDimensions"; "required": false; }; "growAfterOpen": { "alias": "cdkConnectedOverlayGrowAfterOpen"; "required": false; }; "push": { "alias": "cdkConnectedOverlayPush"; "required": false; }; "disposeOnNavigation": { "alias": "cdkConnectedOverlayDisposeOnNavigation"; "required": false; }; "usePopover": { "alias": "cdkConnectedOverlayUsePopover"; "required": false; }; "_config": { "alias": "cdkConnectedOverlay"; "required": false; }; }, { "backdropClick": "backdropClick"; "positionChange": "positionChange"; "attach": "attach"; "detach": "detach"; "overlayKeydown": "overlayKeydown"; "overlayOutsideClick": "overlayOutsideClick"; }, never, never, true, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<CdkConnectedOverlay, "[cdk-connected-overlay], [connected-overlay], [cdkConnectedOverlay]", ["cdkConnectedOverlay"], { "origin": { "alias": "cdkConnectedOverlayOrigin"; "required": false; }; "positions": { "alias": "cdkConnectedOverlayPositions"; "required": false; }; "positionStrategy": { "alias": "cdkConnectedOverlayPositionStrategy"; "required": false; }; "offsetX": { "alias": "cdkConnectedOverlayOffsetX"; "required": false; }; "offsetY": { "alias": "cdkConnectedOverlayOffsetY"; "required": false; }; "width": { "alias": "cdkConnectedOverlayWidth"; "required": false; }; "height": { "alias": "cdkConnectedOverlayHeight"; "required": false; }; "minWidth": { "alias": "cdkConnectedOverlayMinWidth"; "required": false; }; "minHeight": { "alias": "cdkConnectedOverlayMinHeight"; "required": false; }; "backdropClass": { "alias": "cdkConnectedOverlayBackdropClass"; "required": false; }; "panelClass": { "alias": "cdkConnectedOverlayPanelClass"; "required": false; }; "viewportMargin": { "alias": "cdkConnectedOverlayViewportMargin"; "required": false; }; "scrollStrategy": { "alias": "cdkConnectedOverlayScrollStrategy"; "required": false; }; "open": { "alias": "cdkConnectedOverlayOpen"; "required": false; }; "disableClose": { "alias": "cdkConnectedOverlayDisableClose"; "required": false; }; "transformOriginSelector": { "alias": "cdkConnectedOverlayTransformOriginOn"; "required": false; }; "hasBackdrop": { "alias": "cdkConnectedOverlayHasBackdrop"; "required": false; }; "lockPosition": { "alias": "cdkConnectedOverlayLockPosition"; "required": false; }; "flexibleDimensions": { "alias": "cdkConnectedOverlayFlexibleDimensions"; "required": false; }; "growAfterOpen": { "alias": "cdkConnectedOverlayGrowAfterOpen"; "required": false; }; "push": { "alias": "cdkConnectedOverlayPush"; "required": false; }; "disposeOnNavigation": { "alias": "cdkConnectedOverlayDisposeOnNavigation"; "required": false; }; "usePopover": { "alias": "cdkConnectedOverlayUsePopover"; "required": false; }; "matchWidth": { "alias": "cdkConnectedOverlayMatchWidth"; "required": false; }; "_config": { "alias": "cdkConnectedOverlay"; "required": false; }; }, { "backdropClick": "backdropClick"; "positionChange": "positionChange"; "attach": "attach"; "detach": "detach"; "overlayKeydown": "overlayKeydown"; "overlayOutsideClick": "overlayOutsideClick"; }, never, never, true, never>;
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<CdkConnectedOverlay, never>;
 }

src/cdk/overlay/overlay-directives.spec.ts

@@ -626,6 +626,19 @@ describe('Overlay directives', () => {
 
       expect(target.style.transformOrigin).toContain('left bottom');
     });
+
+    it('should match the trigger width', () => {
+      const trigger = fixture.nativeElement.querySelector('#trigger') as HTMLElement;
+      trigger.style.width = '128px';
+
+      fixture.componentInstance.matchWidth = true;
+      fixture.componentInstance.isOpen = true;
+      fixture.changeDetectorRef.markForCheck();
+      fixture.detectChanges();
+
+      const pane = overlayContainerElement.querySelector('.cdk-overlay-pane') as HTMLElement;
+      expect(pane.style.width).toBe('128px');
+    });
   });
 
   describe('outputs', () => {
@@ -742,11 +755,11 @@ describe('Overlay directives', () => {
 
 @Component({
   template: `
-  <button cdk-overlay-origin id="trigger" #trigger="cdkOverlayOrigin">Toggle menu</button>
-  <button cdk-overlay-origin id="otherTrigger" #otherTrigger="cdkOverlayOrigin">Toggle menu</button>
+  <button cdkOverlayOrigin id="trigger" #trigger="cdkOverlayOrigin">Toggle menu</button>
+  <button cdkOverlayOrigin id="otherTrigger" #otherTrigger="cdkOverlayOrigin">Toggle menu</button>
   <button id="nonDirectiveTrigger" #nonDirectiveTrigger>Toggle menu</button>
 
-  <ng-template cdk-connected-overlay
+  <ng-template cdkConnectedOverlay
             [cdkConnectedOverlayOpen]="isOpen"
             [cdkConnectedOverlayWidth]="width"
             [cdkConnectedOverlayHeight]="height"
@@ -771,7 +784,8 @@ describe('Overlay directives', () => {
             [cdkConnectedOverlayMinWidth]="minWidth"
             [cdkConnectedOverlayMinHeight]="minHeight"
             [cdkConnectedOverlayPositions]="positionOverrides"
-            [cdkConnectedOverlayTransformOriginOn]="transformOriginSelector">
+            [cdkConnectedOverlayTransformOriginOn]="transformOriginSelector"
+            [cdkConnectedOverlayMatchWidth]="matchWidth">
     <p>Menu content</p>
   </ng-template>`,
   imports: [OverlayModule],
@@ -809,12 +823,14 @@ class ConnectedOverlayDirectiveTest {
   detachHandler = jasmine.createSpy('detachHandler');
   attachResult: HTMLElement;
   transformOriginSelector: string;
+  matchWidth = false;
 }
 
 @Component({
   template: `
-  <button cdk-overlay-origin #trigger="cdkOverlayOrigin">Toggle menu</button>
-  <ng-template cdk-connected-overlay>Menu content</ng-template>`,
+    <button cdkOverlayOrigin #trigger="cdkOverlayOrigin">Toggle menu</button>
+    <ng-template cdk-connected-overlay>Menu content</ng-template>
+  `,
   imports: [OverlayModule],
 })
 class ConnectedOverlayPropertyInitOrder {

src/cdk/overlay/overlay-directives.ts

@@ -246,6 +246,10 @@ export class CdkConnectedOverlay implements OnDestroy, OnChanges {
   @Input({alias: 'cdkConnectedOverlayUsePopover', transform: booleanAttribute})
   usePopover: boolean = false;
 
+  /** Whether the overlay should match the trigger's width. */
+  @Input({alias: 'cdkConnectedOverlayMatchWidth', transform: booleanAttribute})
+  matchWidth: boolean = false;
+
   /** Shorthand for setting multiple overlay options at once. */
   @Input('cdkConnectedOverlay')
   set _config(value: string | CdkConnectedOverlayConfig) {
@@ -306,7 +310,7 @@ export class CdkConnectedOverlay implements OnDestroy, OnChanges {
     if (this._position) {
       this._updatePositionStrategy(this._position);
       this._overlayRef?.updateSize({
-        width: this.width,
+        width: this._getWidth(),
         minWidth: this.minWidth,
         height: this.height,
         minHeight: this.minHeight,
@@ -363,10 +367,6 @@ export class CdkConnectedOverlay implements OnDestroy, OnChanges {
       usePopover: this.usePopover,
     });
 
-    if (this.width || this.width === 0) {
-      overlayConfig.width = this.width;
-    }
-
     if (this.height || this.height === 0) {
       overlayConfig.height = this.height;
     }
@@ -444,6 +444,15 @@ export class CdkConnectedOverlay implements OnDestroy, OnChanges {
     return null;
   }
 
+  private _getWidth() {
+    if (this.width) {
+      return this.width;
+    }
+
+    // Null check `getBoundingClientRect` in case this is called during SSR.
+    return this.matchWidth ? this._getOriginElement()?.getBoundingClientRect?.().width : undefined;
+  }
+
   /** Attaches the overlay. */
   attachOverlay() {
     if (!this._overlayRef) {
@@ -454,6 +463,7 @@ export class CdkConnectedOverlay implements OnDestroy, OnChanges {
 
     // Update the overlay size, in case the directive's inputs have changed
     ref.getConfig().hasBackdrop = this.hasBackdrop;
+    ref.updateSize({width: this._getWidth()});
 
     if (!ref.hasAttached()) {
       ref.attach(this._templatePortal);
@@ -517,5 +527,6 @@ 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.matchWidth = config.matchWidth ?? this.matchWidth;
   }
 }