fix(material-experimental/mdc-menu): implement increasing elevation (#22506)

Previously we didn't implement the feature where nested menus increase their elevation for each level, because we didn't have elevation classes based on MDC. Now that we do, we can implement the feature.

Also adds an extra elevation class that allows us to increase the specificity over the default one from MDC.

Author: crisbeto

scripts/check-mdc-tests-config.ts

@@ -113,13 +113,6 @@ export const config = {
       'should dispatch the selectionChange event when selecting via ctrl + a'
 
     ],
-    'mdc-menu': [
-      // Disabled since we don't have equivalents to our elevation classes in the MDC packages.
-      'should not remove mat-elevation class from overlay when panelClass is changed',
-      'should increase the sub-menu elevation based on its depth',
-      'should update the elevation when the same menu is opened at a different depth',
-      'should not increase the elevation if the user specified a custom one'
-    ],
     'mdc-progress-bar': [
       // These tests are verifying implementation details that are not relevant for MDC.
       'should return the transform attribute for bufferValue and mode',

src/material-experimental/mdc-core/_core-theme.scss

@@ -21,7 +21,10 @@
       // `mat-mdc-elevation-z$zValue` where `$zValue` corresponds to the z-space to which the
       // element is elevated.
       @for $zValue from 0 through 24 {
-        .#{elevation.$prefix}#{$zValue} {
+        $selector: elevation.$prefix + $zValue;
+        // We need the `mat-mdc-elevation-specific`, because some MDC mixins
+        // come with elevation baked in and we don't have a way of removing it.
+        .#{$selector}, .mat-mdc-elevation-specific.#{$selector} {
           @include elevation.private-theme-elevation($zValue, $color);
         }
       }

src/material-experimental/mdc-menu/menu.html

@@ -1,6 +1,6 @@
 <ng-template>
   <div
-    class="mat-mdc-menu-panel mdc-menu-surface mdc-menu-surface--open"
+    class="mat-mdc-menu-panel mdc-menu-surface mdc-menu-surface--open mat-mdc-elevation-specific"
     [id]="panelId"
     [ngClass]="_classList"
     (keydown)="_handleKeydown($event)"

src/material-experimental/mdc-menu/menu.spec.ts

@@ -532,6 +532,29 @@ describe('MDC-based MatMenu', () => {
     expect(panel.classList).toContain('custom-two');
   });
 
+  it('should not remove mat-elevation class from overlay when panelClass is changed', () => {
+    const fixture = createComponent(SimpleMenu, [], [FakeIcon]);
+
+    fixture.componentInstance.panelClass = 'custom-one';
+    fixture.detectChanges();
+    fixture.componentInstance.trigger.openMenu();
+    fixture.detectChanges();
+
+    const panel = overlayContainerElement.querySelector('.mat-mdc-menu-panel')!;
+
+    expect(panel.classList).toContain('custom-one');
+    expect(panel.classList).toContain('mat-mdc-elevation-z8');
+
+    fixture.componentInstance.panelClass = 'custom-two';
+    fixture.detectChanges();
+
+    expect(panel.classList).not.toContain('custom-one');
+    expect(panel.classList).toContain('custom-two');
+    expect(panel.classList).toContain('mat-mdc-elevation-specific');
+    expect(panel.classList)
+        .toContain('mat-mdc-elevation-z8', 'Expected mat-mdc-elevation-z8 not to be removed');
+  });
+
   it('should set the "menu" role on the overlay panel', () => {
     const fixture = createComponent(SimpleMenu, [], [FakeIcon]);
     fixture.detectChanges();
@@ -2050,6 +2073,70 @@ describe('MDC-based MatMenu', () => {
       expect(menuItems[1].classList).not.toContain('mat-mdc-menu-item-submenu-trigger');
     });
 
+    it('should increase the sub-menu elevation based on its depth', () => {
+      compileTestComponent();
+      instance.rootTrigger.openMenu();
+      fixture.detectChanges();
+
+      instance.levelOneTrigger.openMenu();
+      fixture.detectChanges();
+
+      instance.levelTwoTrigger.openMenu();
+      fixture.detectChanges();
+
+      const menus = overlay.querySelectorAll('.mat-mdc-menu-panel');
+
+      expect(menus[0].classList).toContain('mat-mdc-elevation-specific');
+      expect(menus[0].classList)
+        .toContain('mat-mdc-elevation-z8', 'Expected root menu to have base elevation.');
+
+      expect(menus[1].classList).toContain('mat-mdc-elevation-specific');
+      expect(menus[1].classList)
+        .toContain('mat-mdc-elevation-z9', 'Expected first sub-menu to have base elevation + 1.');
+
+      expect(menus[2].classList).toContain('mat-mdc-elevation-specific');
+      expect(menus[2].classList)
+        .toContain('mat-mdc-elevation-z10', 'Expected second sub-menu to have base elevation + 2.');
+    });
+
+    it('should update the elevation when the same menu is opened at a different depth',
+      fakeAsync(() => {
+        compileTestComponent();
+        instance.rootTrigger.openMenu();
+        fixture.detectChanges();
+
+        instance.levelOneTrigger.openMenu();
+        fixture.detectChanges();
+
+        instance.levelTwoTrigger.openMenu();
+        fixture.detectChanges();
+
+        let lastMenu = overlay.querySelectorAll('.mat-mdc-menu-panel')[2];
+
+        expect(lastMenu.classList).toContain('mat-mdc-elevation-specific');
+        expect(lastMenu.classList)
+          .toContain('mat-mdc-elevation-z10', 'Expected menu to have the base elevation plus two.');
+
+        (overlay.querySelector('.cdk-overlay-backdrop')! as HTMLElement).click();
+        fixture.detectChanges();
+        tick(500);
+
+        expect(overlay.querySelectorAll('.mat-mdc-menu-panel').length)
+            .toBe(0, 'Expected no open menus');
+
+        instance.alternateTrigger.openMenu();
+        fixture.detectChanges();
+        tick(500);
+
+        lastMenu = overlay.querySelector('.mat-mdc-menu-panel') as HTMLElement;
+
+        expect(lastMenu.classList).toContain('mat-mdc-elevation-specific');
+        expect(lastMenu.classList).not.toContain('mat-mdc-elevation-z10',
+          'Expected menu not to maintain old elevation.');
+        expect(lastMenu.classList).toContain('mat-mdc-elevation-z8',
+          'Expected menu to have the proper updated elevation.');
+      }));
+
     it('should not change focus origin if origin not specified for trigger', fakeAsync(() => {
       compileTestComponent();
 
@@ -2067,6 +2154,26 @@ describe('MDC-based MatMenu', () => {
       expect(levelTwoTrigger.classList).toContain('cdk-mouse-focused');
     }));
 
+    it('should not increase the elevation if the user specified a custom one', () => {
+      const elevationFixture = createComponent(NestedMenuCustomElevation);
+
+      elevationFixture.detectChanges();
+      elevationFixture.componentInstance.rootTrigger.openMenu();
+      elevationFixture.detectChanges();
+
+      elevationFixture.componentInstance.levelOneTrigger.openMenu();
+      elevationFixture.detectChanges();
+
+      const menuClasses =
+          overlayContainerElement.querySelectorAll('.mat-mdc-menu-panel')[1].classList;
+
+      expect(menuClasses).toContain('mat-mdc-elevation-specific');
+      expect(menuClasses)
+          .toContain('mat-mdc-elevation-z24', 'Expected user elevation to be maintained');
+      expect(menuClasses)
+          .not.toContain('mat-mdc-elevation-z8', 'Expected no stacked elevation.');
+    });
+
     it('should close all of the menus when the root is closed programmatically', fakeAsync(() => {
       compileTestComponent();
       instance.rootTrigger.openMenu();
@@ -2487,6 +2594,26 @@ class NestedMenu {
   showLazy = false;
 }
 
+@Component({
+  template: `
+    <button [matMenuTriggerFor]="root" #rootTrigger="matMenuTrigger">Toggle menu</button>
+
+    <mat-menu #root="matMenu">
+      <button mat-menu-item
+        [matMenuTriggerFor]="levelOne"
+        #levelOneTrigger="matMenuTrigger">One</button>
+    </mat-menu>
+
+    <mat-menu #levelOne="matMenu" class="mat-mdc-elevation-z24">
+      <button mat-menu-item>Two</button>
+    </mat-menu>
+  `
+})
+class NestedMenuCustomElevation {
+  @ViewChild('rootTrigger') rootTrigger: MatMenuTrigger;
+  @ViewChild('levelOneTrigger') levelOneTrigger: MatMenuTrigger;
+}
+
 
 @Component({
   template: `

src/material-experimental/mdc-menu/menu.ts

@@ -58,19 +58,12 @@ export const MAT_MENU_SCROLL_STRATEGY_FACTORY_PROVIDER: Provider = {
   ]
 })
 export class MatMenu extends _MatMenuBase {
+  protected _elevationPrefix = 'mat-mdc-elevation-z';
+  protected _baseElevation = 8;
+
   constructor(_elementRef: ElementRef<HTMLElement>,
               _ngZone: NgZone,
               @Inject(MAT_MENU_DEFAULT_OPTIONS) _defaultOptions: MatMenuDefaultOptions) {
     super(_elementRef, _ngZone, _defaultOptions);
   }
-
-  setElevation(_depth: number) {
-    // TODO(crisbeto): MDC's styles come with elevation already and we haven't mapped our mixins
-    // to theirs. Disable the elevation stacking for now until everything has been mapped.
-    // The following unit tests should be re-enabled:
-    // - should not remove mat-elevation class from overlay when panelClass is changed
-    // - should increase the sub-menu elevation based on its depth
-    // - should update the elevation when the same menu is opened at a different depth
-    // - should not increase the elevation if the user specified a custom one
-  }
 }

src/material/menu/menu.ts

@@ -85,15 +85,9 @@ export function MAT_MENU_DEFAULT_OPTIONS_FACTORY(): MatMenuDefaultOptions {
     backdropClass: 'cdk-overlay-transparent-backdrop',
   };
 }
-/**
- * Start elevation for the menu panel.
- * @docs-private
- */
-const MAT_MENU_BASE_ELEVATION = 4;
 
 let menuPanelUid = 0;
 
-
 /** Reason why the menu was closed. */
 export type MenuCloseReason = void | 'click' | 'keydown' | 'tab';
 
@@ -106,6 +100,8 @@ export class _MatMenuBase implements AfterContentInit, MatMenuPanel<MatMenuItem>
   private _xPosition: MenuPositionX = this._defaultOptions.xPosition;
   private _yPosition: MenuPositionY = this._defaultOptions.yPosition;
   private _previousElevation: string;
+  protected _elevationPrefix: string;
+  protected _baseElevation: number;
 
   /** All items inside the menu. Includes items nested inside another menu. */
   @ContentChildren(MatMenuItem, {descendants: true}) _allItems: QueryList<MatMenuItem>;
@@ -404,9 +400,11 @@ export class _MatMenuBase implements AfterContentInit, MatMenuPanel<MatMenuItem>
   setElevation(depth: number): void {
     // The elevation starts at the base and increases by one for each level.
     // Capped at 24 because that's the maximum elevation defined in the Material design spec.
-    const elevation = Math.min(MAT_MENU_BASE_ELEVATION + depth, 24);
-    const newElevation = `mat-elevation-z${elevation}`;
-    const customElevation = Object.keys(this._classList).find(c => c.startsWith('mat-elevation-z'));
+    const elevation = Math.min(this._baseElevation + depth, 24);
+    const newElevation = `${this._elevationPrefix}${elevation}`;
+    const customElevation = Object.keys(this._classList).find(className => {
+      return className.startsWith(this._elevationPrefix);
+    });
 
     if (!customElevation || customElevation === this._previousElevation) {
       if (this._previousElevation) {
@@ -506,6 +504,9 @@ export class _MatMenuBase implements AfterContentInit, MatMenuPanel<MatMenuItem>
   ]
 })
 export class MatMenu extends _MatMenuBase {
+  protected _elevationPrefix = 'mat-elevation-z';
+  protected _baseElevation = 4;
+
   constructor(elementRef: ElementRef<HTMLElement>, ngZone: NgZone,
       @Inject(MAT_MENU_DEFAULT_OPTIONS) defaultOptions: MatMenuDefaultOptions) {
     super(elementRef, ngZone, defaultOptions);

tools/public_api_guard/material/menu.d.ts

@@ -1,9 +1,11 @@
 export declare class _MatMenuBase implements AfterContentInit, MatMenuPanel<MatMenuItem>, OnInit, OnDestroy {
     _allItems: QueryList<MatMenuItem>;
     readonly _animationDone: Subject<AnimationEvent>;
+    protected _baseElevation: number;
     _classList: {
         [key: string]: boolean;
     };
+    protected _elevationPrefix: string;
     _isAnimating: boolean;
     _panelAnimationState: 'void' | 'enter';
     ariaDescribedby: string;
@@ -69,6 +71,8 @@ export declare const MAT_MENU_PANEL: InjectionToken<MatMenuPanel<any>>;
 export declare const MAT_MENU_SCROLL_STRATEGY: InjectionToken<() => ScrollStrategy>;
 
 export declare class MatMenu extends _MatMenuBase {
+    protected _baseElevation: number;
+    protected _elevationPrefix: string;
     constructor(elementRef: ElementRef<HTMLElement>, ngZone: NgZone, defaultOptions: MatMenuDefaultOptions);
     static ɵcmp: i0.ɵɵComponentDeclaration<MatMenu, "mat-menu", ["matMenu"], {}, {}, never, ["*"]>;
     static ɵfac: i0.ɵɵFactoryDeclaration<MatMenu, never>;