feat(elevation): move elevation rules into theme stylesheets (#11344)

Move all usages of elevation mixins out of component stylesheets and into their respective themes.
This allows the elevation color to be changed based on the theme. Add new `mat-theme-elevation`
and `mat-theme-overridable-elevation` shorthand mixins to apply the current theme's elevation
color. Replace all usages of `mat-elevation` mixins with themed equivalents. Add `elevation`
property to the default `foreground` theme palettes.

Closes #11343

BREAKING CHANGE:

Because `mat-elevation` usages have been moved out of component stylesheets, users who have
not invoked a theme mixin will not see any elevation shadows on Material components.
However, users that have created a custom theme which lacks the `elevation` property will
still see the default black shadows.

Additionally, users who want to use themed elevations in their custom components can create
their own shorthand mixin:

```
@import '~angular/material/theming';

$myTheme: ...

@mixin my-elevation($zValue) {
  @include mat-theme-elevation($zValue, $myTheme);
}

```

and then invoke `angular-material-theme` with the `$myTheme` variable.

Author: benelliott

src/lib/autocomplete/_autocomplete-theme.scss

@@ -1,10 +1,12 @@
+@import '../core/style/elevation';
 @import '../core/theming/theming';
 
 @mixin mat-autocomplete-theme($theme) {
   $foreground: map-get($theme, foreground);
   $background: map-get($theme, background);
 
   .mat-autocomplete-panel {
+    @include _mat-theme-overridable-elevation(4, $theme);
     background: mat-color($background, card);
     color: mat-color($foreground, text);
 

src/lib/autocomplete/autocomplete.scss

@@ -8,7 +8,7 @@ $mat-autocomplete-panel-max-height: 256px !default;
 $mat-autocomplete-panel-border-radius: 4px !default;
 
 .mat-autocomplete-panel {
-  @include mat-menu-base(4);
+  @include mat-menu-base();
 
   visibility: hidden;
   max-width: none;

src/lib/bottom-sheet/_bottom-sheet-theme.scss

@@ -1,3 +1,4 @@
+@import '../core/style/elevation';
 @import '../core/typography/typography-utils';
 @import '../core/theming/palette';
 
@@ -6,6 +7,7 @@
   $foreground: map-get($theme, foreground);
 
   .mat-bottom-sheet-container {
+    @include _mat-theme-elevation(16, $theme);
     background: mat-color($background, dialog);
     color: mat-color($foreground, text);
   }

src/lib/bottom-sheet/bottom-sheet-container.scss

@@ -1,4 +1,3 @@
-@import '../core/style/elevation';
 @import '../../cdk/a11y/a11y';
 
 // The bottom sheet minimum width on larger screen sizes is based
@@ -9,8 +8,6 @@ $mat-bottom-sheet-container-vertical-padding: 8px !default;
 $mat-bottom-sheet-container-horizontal-padding: 16px !default;
 
 .mat-bottom-sheet-container {
-  @include mat-elevation(16);
-
   padding: $mat-bottom-sheet-container-vertical-padding
            $mat-bottom-sheet-container-horizontal-padding;
   min-width: 100vw;

src/lib/button-toggle/_button-toggle-theme.scss

@@ -1,3 +1,4 @@
+@import '../core/style/elevation';
 @import '../core/theming/palette';
 @import '../core/theming/theming';
 @import '../core/typography/typography-utils';
@@ -6,6 +7,10 @@
   $foreground: map-get($theme, foreground);
   $background: map-get($theme, background);
 
+  .mat-button-toggle-standalone, .mat-button-toggle-group {
+    @include _mat-theme-elevation(2, $theme);
+  }
+
   .mat-button-toggle {
     color: mat-color($foreground, hint-text);
 

src/lib/button-toggle/button-toggle.scss

@@ -1,4 +1,3 @@
-@import '../core/style/elevation';
 @import '../core/style/vendor-prefixes';
 @import '../core/style/layout-common';
 @import '../../cdk/a11y/a11y';
@@ -9,7 +8,6 @@ $mat-button-toggle-border-radius: 2px !default;
 
 .mat-button-toggle-standalone,
 .mat-button-toggle-group {
-  @include mat-elevation(2);
   position: relative;
   display: inline-flex;
   flex-direction: row;

src/lib/button/_button-base.scss

@@ -76,7 +76,6 @@ $mat-mini-fab-padding: 8px !default;
 // Applies styles to buttons with backgrounds: raised, fab, and mini-fab
 @mixin mat-raised-button {
   @include mat-button-base;
-  @include mat-overridable-elevation(2);
   @include _noop-animation();
 
   // Force hardware acceleration.
@@ -85,20 +84,11 @@ $mat-mini-fab-padding: 8px !default;
   // Animation.
   transition: background $swift-ease-out-duration $swift-ease-out-timing-function,
               mat-elevation-transition-property-value();
-
-  &:not([disabled]):active {
-    @include mat-overridable-elevation(8);
-  }
-
-  &[disabled] {
-    box-shadow: none;
-  }
 }
 
 // Applies styles to fab and mini-fab button types only
 @mixin mat-fab($size, $padding) {
   @include mat-raised-button;
-  @include mat-overridable-elevation(6);
 
   // Reset the min-width from the button base.
   min-width: 0;
@@ -110,10 +100,6 @@ $mat-mini-fab-padding: 8px !default;
 
   flex-shrink: 0;
 
-  &:not([disabled]):active {
-    @include mat-overridable-elevation(12);
-  }
-
   .mat-button-wrapper {
     padding: $padding 0;
     display: inline-block;

src/lib/button/_button-theme.scss

@@ -1,4 +1,5 @@
 @import '../core/theming/theming';
+@import '../core/style/elevation';
 @import '../core/typography/typography-utils';
 
 // Applies a focus style to an mat-button element for each of the supported palettes.
@@ -106,6 +107,34 @@
   .mat-icon-button {
     @include _mat-button-ripple-color($theme, default, 0.2);
   }
+
+  .mat-stroked-button, .mat-flat-button {
+    @include _mat-theme-overridable-elevation(0, $theme);
+  }
+
+  .mat-raised-button {
+    @include _mat-theme-overridable-elevation(2, $theme);
+
+    &:not([disabled]):active {
+      @include _mat-theme-overridable-elevation(8, $theme);
+    }
+
+    &[disabled] {
+      @include _mat-theme-overridable-elevation(0, $theme);
+    }
+  }
+
+  .mat-fab, .mat-mini-fab {
+    @include _mat-theme-overridable-elevation(6, $theme);
+
+    &:not([disabled]):active {
+      @include _mat-theme-overridable-elevation(12, $theme);
+    }
+
+    &[disabled] {
+      @include _mat-theme-overridable-elevation(0, $theme);
+    }
+  }
 }
 
 @mixin mat-button-typography($config) {

src/lib/button/button.scss

@@ -37,17 +37,11 @@
 }
 
 .mat-stroked-button {
-  @include mat-overridable-elevation(0);
-
-  border: 1px solid currentColor;
+  border:  1px solid currentColor;
   padding: $mat-stroked-button-padding;
   line-height: $mat-stroked-button-line-height;
 }
 
-.mat-flat-button {
-  @include mat-overridable-elevation(0);
-}
-
 .mat-fab {
   @include mat-fab($mat-fab-size, $mat-fab-padding);
 }

src/lib/card/_card-theme.scss

@@ -1,5 +1,6 @@
 @import '../core/theming/palette';
 @import '../core/theming/theming';
+@import '../core/style/elevation';
 @import '../core/typography/typography-utils';
 
 
@@ -8,8 +9,14 @@
   $foreground: map-get($theme, foreground);
 
   .mat-card {
+    @include _mat-theme-overridable-elevation(2, $theme);
     background: mat-color($background, card);
     color: mat-color($foreground, text);
+
+    // Needs extra specificity to be able to override the elevation selectors.
+    &.mat-card-flat {
+      @include _mat-theme-overridable-elevation(0, $theme);
+    }
   }
 
   .mat-card-subtitle {

src/lib/card/card.scss

@@ -10,7 +10,6 @@ $mat-card-header-size: 40px !default;
 
 .mat-card {
   @include mat-elevation-transition;
-  @include mat-overridable-elevation(2);
   display: block;
   position: relative;
   padding: $mat-card-default-padding;
@@ -37,11 +36,6 @@ $mat-card-header-size: 40px !default;
     }
   }
 
-  // Needs extra specificity to be able to override the elevation selectors.
-  &.mat-card-flat {
-    box-shadow: none;
-  }
-
   @include cdk-high-contrast {
     outline: solid 1px;
   }

src/lib/chips/_chips-theme.scss

@@ -1,3 +1,4 @@
+@import '../core/style/elevation';
 @import '../core/theming/palette';
 @import '../core/theming/theming';
 @import '../core/typography/typography-utils';
@@ -39,6 +40,10 @@ $mat-chip-remove-font-size: 18px;
 
   .mat-chip.mat-standard-chip {
     @include mat-chips-color($unselected-foreground, $unselected-background);
+
+    &:focus {
+      @include _mat-theme-elevation(3, $theme);
+    }
   }
 
   .mat-chip.mat-standard-chip.mat-chip-selected {

src/lib/chips/chips.scss

@@ -41,7 +41,6 @@ $mat-chip-remove-size: 18px;
   }
 
   &:focus {
-    @include mat-elevation(3);
     outline: none;
   }
 

src/lib/core/_core.scss

@@ -14,15 +14,6 @@
 
 // Mixin that renders all of the core styles that are not theme-dependent.
 @mixin mat-core($typography-config: null) {
-  // Provides external CSS classes for each elevation value. Each CSS class is formatted as
-  // `mat-elevation-z$zValue` where `$zValue` corresponds to the z-space to which the element is
-  // elevated.
-  @for $zValue from 0 through 24 {
-    .#{$_mat-elevation-prefix}#{$zValue} {
-      @include mat-elevation($zValue);
-    }
-  }
-
   @include angular-material-typography($typography-config);
   @include mat-ripple();
   @include cdk-a11y();
@@ -37,6 +28,15 @@
   @include mat-optgroup-theme($theme);
   @include mat-pseudo-checkbox-theme($theme);
 
+  // Provides external CSS classes for each elevation value. Each CSS class is formatted as
+  // `mat-elevation-z$zValue` where `$zValue` corresponds to the z-space to which the element is
+  // elevated.
+  @for $zValue from 0 through 24 {
+    .#{$_mat-elevation-prefix}#{$zValue} {
+      @include _mat-theme-elevation($zValue, $theme);
+    }
+  }
+
   // Wrapper element that provides the theme background when the user's content isn't
   // inside of a `mat-sidenav-container`. Note that we need to exclude the ampersand
   // selector in case the mixin is included at the top level.

src/lib/core/style/_elevation.scss

@@ -151,6 +151,14 @@ $_mat-elevation-prefix: 'mat-elevation-z';
               #{map-get(_get-ambient-map($color, $opacity), $zValue)};
 }
 
+@mixin _mat-theme-elevation($zValue, $theme, $opacity: $mat-elevation-opacity) {
+  $foreground: map-get($theme, foreground);
+  $elevation-color: map-get($foreground, elevation);
+  $elevation-color-or-default: if($elevation-color == null, $mat-elevation-color, $elevation-color);
+
+  @include mat-elevation($zValue, $elevation-color-or-default, $opacity);
+}
+
 // Applies the elevation to an element in a manner that allows
 // consumers to override it via the Material elevation classes.
 @mixin mat-overridable-elevation(
@@ -162,6 +170,14 @@ $_mat-elevation-prefix: 'mat-elevation-z';
   }
 }
 
+@mixin _mat-theme-overridable-elevation($zValue, $theme, $opacity: $mat-elevation-opacity) {
+  $foreground: map-get($theme, foreground);
+  $elevation-color: map-get($foreground, elevation);
+  $elevation-color-or-default: if($elevation-color == null, $mat-elevation-color, $elevation-color);
+
+  @include mat-overridable-elevation($zValue, $elevation-color-or-default, $opacity);
+}
+
 // Returns a string that can be used as the value for a transition property for elevation.
 // Calling this function directly is useful in situations where a component needs to transition
 // more than one property.

src/lib/core/style/_menu-common.scss

@@ -1,5 +1,4 @@
 @import './variables';
-@import './elevation';
 @import './list-common';
 @import './vendor-prefixes';
 
@@ -14,9 +13,7 @@ $mat-menu-side-padding: 16px !default;
 $mat-menu-icon-margin: 16px !default;
 
 
-@mixin mat-menu-base($default-elevation) {
-  @include mat-overridable-elevation($default-elevation);
-
+@mixin mat-menu-base() {
   min-width: $mat-menu-overlay-min-width;
   max-width: $mat-menu-overlay-max-width;
   overflow: auto;

src/lib/core/theming/_palette.scss

@@ -714,6 +714,7 @@ $mat-light-theme-foreground: (
   disabled:          $dark-disabled-text,
   disabled-button:   rgba(black, 0.26),
   disabled-text:     $dark-disabled-text,
+  elevation:         black,
   hint-text:         $dark-disabled-text,
   secondary-text:    $dark-secondary-text,
   icon:              rgba(black, 0.54),
@@ -732,6 +733,7 @@ $mat-dark-theme-foreground: (
   disabled:          $light-disabled-text,
   disabled-button:   rgba(white, 0.3),
   disabled-text:     $light-disabled-text,
+  elevation:         black,
   hint-text:         $light-disabled-text,
   secondary-text:    $light-secondary-text,
   icon:              white,

src/lib/datepicker/_datepicker-theme.scss

@@ -1,3 +1,4 @@
+@import '../core/style/elevation';
 @import '../core/theming/palette';
 @import '../core/theming/theming';
 @import '../core/typography/typography-utils';
@@ -83,6 +84,7 @@ $mat-calendar-weekday-table-font-size: 11px !default;
   @include _mat-datepicker-color(map-get($theme, primary));
 
   .mat-datepicker-content {
+    @include _mat-theme-elevation(4, $theme);
     background-color: mat-color($background, card);
     color: mat-color($foreground, text);
 
@@ -95,6 +97,10 @@ $mat-calendar-weekday-table-font-size: 11px !default;
     }
   }
 
+  .mat-datepicker-content-touch {
+    @include _mat-theme-elevation(0, $theme);
+  }
+
   .mat-datepicker-toggle-active {
     color: mat-color(map-get($theme, primary));
 

src/lib/datepicker/datepicker-content.scss

@@ -1,6 +1,3 @@
-@import '../core/style/elevation';
-
-
 $mat-datepicker-calendar-padding: 8px;
 $mat-datepicker-non-touch-calendar-cell-size: 40px;
 $mat-datepicker-non-touch-calendar-width:
@@ -25,8 +22,6 @@ $mat-datepicker-touch-max-height: 788px;
 
 
 .mat-datepicker-content {
-  @include mat-elevation(4);
-
   display: block;
   border-radius: 4px;
 
@@ -37,8 +32,6 @@ $mat-datepicker-touch-max-height: 788px;
 }
 
 .mat-datepicker-content-touch {
-  @include mat-elevation(0);
-
   display: block;
   // make sure the dialog scrolls rather than being cropped on ludicrously small screens
   max-height: 80vh;