feat(elevation): move elevation rules into theme stylesheets

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(8, $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 {
-  @include mat-menu-base(8);
+  @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

@@ -75,7 +75,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);
 
   // Force hardware acceleration.
   transform: translate3d(0, 0, 0);
@@ -84,10 +83,6 @@ $mat-mini-fab-padding: 8px !default;
   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;
   }
@@ -96,7 +91,6 @@ $mat-mini-fab-padding: 8px !default;
 // 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;
@@ -108,10 +102,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,26 @@
   .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);
+    }
+  }
+
+  .mat-fab, .mat-mini-fab {
+    @include mat-theme-overridable-elevation(6, $theme);
+
+    &:not([disabled]):active {
+      @include mat-theme-overridable-elevation(12, $theme);
+    }
+  }
 }
 
 @mixin mat-button-typography($config) {

src/lib/button/button.scss

@@ -27,17 +27,11 @@
 }
 
 .mat-stroked-button {
-  @include mat-overridable-elevation(0);
-
   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,6 +9,7 @@
   $foreground: map-get($theme, foreground);
 
   .mat-card {
+    @include mat-theme-overridable-elevation(2, $theme);
     background: mat-color($background, card);
     color: mat-color($foreground, text);
   }

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;

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

@@ -40,7 +40,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(8, $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(8);
-
   display: block;
   border-radius: 2px;
 
@@ -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;

src/lib/dialog/_dialog-theme.scss

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

src/lib/dialog/dialog.scss

@@ -1,4 +1,3 @@
-@import '../core/style/elevation';
 @import '../core/style/vendor-prefixes';
 @import '../../cdk/a11y/a11y';
 
@@ -9,8 +8,6 @@ $mat-dialog-max-height: 65vh !default;
 $mat-dialog-button-margin: 8px !default;
 
 .mat-dialog-container {
-  @include mat-elevation(24);
-
   display: block;
   padding: $mat-dialog-padding;
   border-radius: $mat-dialog-border-radius;

src/lib/expansion/_expansion-theme.scss

@@ -1,12 +1,14 @@
 @import '../core/theming/palette';
 @import '../core/theming/theming';
+@import '../core/style/elevation';
 @import '../core/typography/typography-utils';
 
 @mixin mat-expansion-panel-theme($theme) {
   $background: map-get($theme, background);
   $foreground: map-get($theme, foreground);
 
   .mat-expansion-panel {
+    @include mat-theme-overridable-elevation(2, $theme);
     background: mat-color($background, card);
     color: mat-color($foreground, text);
   }