From ebd21dd18c2d47346548bf0576d7a293399df74b Mon Sep 17 00:00:00 2001
From: Ben Elliott <4996462+benelliott@users.noreply.github.com>
Date: Mon, 16 Apr 2018 18:09:12 +0100
Subject: [PATCH] feat(elevation): add $opacity argument to elevation mixins

Add an argument to mat-elevation and mat-overridable-elevation that allows the opacities of the
elevation shadow components to be scaled proportionately. Add missing $color argument to
mat-overridable-elevation and extract default values into variables. Add documentation
for new argument.
---
 guides/elevation.md                |  18 ++-
 src/lib/core/style/_elevation.scss | 177 +++++++++++++++--------------
 2 files changed, 108 insertions(+), 87 deletions(-)

diff --git a/guides/elevation.md b/guides/elevation.md
index 270913f47c56..646e6f7c7ab3 100644
--- a/guides/elevation.md
+++ b/guides/elevation.md
@@ -22,15 +22,27 @@ achieved by switching elevation classes:
 ### Mixins
 
 Elevations can also be added in CSS via the `mat-elevation` mixin, which takes a number 0-24
-indicating the elevation of the element. In order to use the mixin, you must import
-`~@angular/material/theming`:
+indicating the elevation of the element as well as optional arguments for the elevation shadow's
+color tone and opacity.
+
+Since an elevation shadow consists of multiple shadow components of varying opacities, the
+`$opacity` argument of the mixin is considered a factor by which to scale these initial values
+rather than an absolute value.
+
+In order to use the mixin, you must import `~@angular/material/theming`:
 
 ```scss
 @import '~@angular/material/theming';
 
-.my-class {
+.my-class-with-default-shadow {
+  // Adds a shadow for elevation level 2 with default color and full opacity:
   @include mat-elevation(2);
 }
+
+.my-class-with-custom-shadow {
+  // Adds a shadow for elevation level 2 with color #e91e63 and 80% of the default opacity:
+  @include mat-elevation(2, #e91e63, 0.8);
+}
 ```
 
 For convenience, you can use the `mat-elevation-transition` mixin to add a transition when the
diff --git a/src/lib/core/style/_elevation.scss b/src/lib/core/style/_elevation.scss
index 51fa0afff665..59ffdd50d640 100644
--- a/src/lib/core/style/_elevation.scss
+++ b/src/lib/core/style/_elevation.scss
@@ -31,93 +31,93 @@
 // created by taking a few reference shadow sets created by Google's Designers and interpolating
 // all of the values between them.
 
-@function _get-umbra-map($color) {
+@function _get-umbra-map($color, $opacity) {
   @return (
-    0: '0px 0px 0px 0px #{rgba($color, 0.2)}',
-    1: '0px 2px 1px -1px #{rgba($color, 0.2)}',
-    2: '0px 3px 1px -2px #{rgba($color, 0.2)}',
-    3: '0px 3px 3px -2px #{rgba($color, 0.2)}',
-    4: '0px 2px 4px -1px #{rgba($color, 0.2)}',
-    5: '0px 3px 5px -1px #{rgba($color, 0.2)}',
-    6: '0px 3px 5px -1px #{rgba($color, 0.2)}',
-    7: '0px 4px 5px -2px #{rgba($color, 0.2)}',
-    8: '0px 5px 5px -3px #{rgba($color, 0.2)}',
-    9: '0px 5px 6px -3px #{rgba($color, 0.2)}',
-    10: '0px 6px 6px -3px #{rgba($color, 0.2)}',
-    11: '0px 6px 7px -4px #{rgba($color, 0.2)}',
-    12: '0px 7px 8px -4px #{rgba($color, 0.2)}',
-    13: '0px 7px 8px -4px #{rgba($color, 0.2)}',
-    14: '0px 7px 9px -4px #{rgba($color, 0.2)}',
-    15: '0px 8px 9px -5px #{rgba($color, 0.2)}',
-    16: '0px 8px 10px -5px #{rgba($color, 0.2)}',
-    17: '0px 8px 11px -5px #{rgba($color, 0.2)}',
-    18: '0px 9px 11px -5px #{rgba($color, 0.2)}',
-    19: '0px 9px 12px -6px #{rgba($color, 0.2)}',
-    20: '0px 10px 13px -6px #{rgba($color, 0.2)}',
-    21: '0px 10px 13px -6px #{rgba($color, 0.2)}',
-    22: '0px 10px 14px -6px #{rgba($color, 0.2)}',
-    23: '0px 11px 14px -7px #{rgba($color, 0.2)}',
-    24: '0px 11px 15px -7px #{rgba($color, 0.2)}'
+    0: '0px 0px 0px 0px #{rgba($color, $opacity * 0.2)}',
+    1: '0px 2px 1px -1px #{rgba($color, $opacity * 0.2)}',
+    2: '0px 3px 1px -2px #{rgba($color, $opacity * 0.2)}',
+    3: '0px 3px 3px -2px #{rgba($color, $opacity * 0.2)}',
+    4: '0px 2px 4px -1px #{rgba($color, $opacity * 0.2)}',
+    5: '0px 3px 5px -1px #{rgba($color, $opacity * 0.2)}',
+    6: '0px 3px 5px -1px #{rgba($color, $opacity * 0.2)}',
+    7: '0px 4px 5px -2px #{rgba($color, $opacity * 0.2)}',
+    8: '0px 5px 5px -3px #{rgba($color, $opacity * 0.2)}',
+    9: '0px 5px 6px -3px #{rgba($color, $opacity * 0.2)}',
+    10: '0px 6px 6px -3px #{rgba($color, $opacity * 0.2)}',
+    11: '0px 6px 7px -4px #{rgba($color, $opacity * 0.2)}',
+    12: '0px 7px 8px -4px #{rgba($color, $opacity * 0.2)}',
+    13: '0px 7px 8px -4px #{rgba($color, $opacity * 0.2)}',
+    14: '0px 7px 9px -4px #{rgba($color, $opacity * 0.2)}',
+    15: '0px 8px 9px -5px #{rgba($color, $opacity * 0.2)}',
+    16: '0px 8px 10px -5px #{rgba($color, $opacity * 0.2)}',
+    17: '0px 8px 11px -5px #{rgba($color, $opacity * 0.2)}',
+    18: '0px 9px 11px -5px #{rgba($color, $opacity * 0.2)}',
+    19: '0px 9px 12px -6px #{rgba($color, $opacity * 0.2)}',
+    20: '0px 10px 13px -6px #{rgba($color, $opacity * 0.2)}',
+    21: '0px 10px 13px -6px #{rgba($color, $opacity * 0.2)}',
+    22: '0px 10px 14px -6px #{rgba($color, $opacity * 0.2)}',
+    23: '0px 11px 14px -7px #{rgba($color, $opacity * 0.2)}',
+    24: '0px 11px 15px -7px #{rgba($color, $opacity * 0.2)}'
   );
 }
 
-@function _get-penumbra-map($color) {
+@function _get-penumbra-map($color, $opacity) {
   @return (
-    0: '0px 0px 0px 0px #{rgba($color, 0.14)}',
-    1: '0px 1px 1px 0px #{rgba($color, 0.14)}',
-    2: '0px 2px 2px 0px #{rgba($color, 0.14)}',
-    3: '0px 3px 4px 0px #{rgba($color, 0.14)}',
-    4: '0px 4px 5px 0px #{rgba($color, 0.14)}',
-    5: '0px 5px 8px 0px #{rgba($color, 0.14)}',
-    6: '0px 6px 10px 0px #{rgba($color, 0.14)}',
-    7: '0px 7px 10px 1px #{rgba($color, 0.14)}',
-    8: '0px 8px 10px 1px #{rgba($color, 0.14)}',
-    9: '0px 9px 12px 1px #{rgba($color, 0.14)}',
-    10: '0px 10px 14px 1px #{rgba($color, 0.14)}',
-    11: '0px 11px 15px 1px #{rgba($color, 0.14)}',
-    12: '0px 12px 17px 2px #{rgba($color, 0.14)}',
-    13: '0px 13px 19px 2px #{rgba($color, 0.14)}',
-    14: '0px 14px 21px 2px #{rgba($color, 0.14)}',
-    15: '0px 15px 22px 2px #{rgba($color, 0.14)}',
-    16: '0px 16px 24px 2px #{rgba($color, 0.14)}',
-    17: '0px 17px 26px 2px #{rgba($color, 0.14)}',
-    18: '0px 18px 28px 2px #{rgba($color, 0.14)}',
-    19: '0px 19px 29px 2px #{rgba($color, 0.14)}',
-    20: '0px 20px 31px 3px #{rgba($color, 0.14)}',
-    21: '0px 21px 33px 3px #{rgba($color, 0.14)}',
-    22: '0px 22px 35px 3px #{rgba($color, 0.14)}',
-    23: '0px 23px 36px 3px #{rgba($color, 0.14)}',
-    24: '0px 24px 38px 3px #{rgba($color, 0.14)}'
+    0: '0px 0px 0px 0px #{rgba($color, $opacity * 0.14)}',
+    1: '0px 1px 1px 0px #{rgba($color, $opacity * 0.14)}',
+    2: '0px 2px 2px 0px #{rgba($color, $opacity * 0.14)}',
+    3: '0px 3px 4px 0px #{rgba($color, $opacity * 0.14)}',
+    4: '0px 4px 5px 0px #{rgba($color, $opacity * 0.14)}',
+    5: '0px 5px 8px 0px #{rgba($color, $opacity * 0.14)}',
+    6: '0px 6px 10px 0px #{rgba($color, $opacity * 0.14)}',
+    7: '0px 7px 10px 1px #{rgba($color, $opacity * 0.14)}',
+    8: '0px 8px 10px 1px #{rgba($color, $opacity * 0.14)}',
+    9: '0px 9px 12px 1px #{rgba($color, $opacity * 0.14)}',
+    10: '0px 10px 14px 1px #{rgba($color, $opacity * 0.14)}',
+    11: '0px 11px 15px 1px #{rgba($color, $opacity * 0.14)}',
+    12: '0px 12px 17px 2px #{rgba($color, $opacity * 0.14)}',
+    13: '0px 13px 19px 2px #{rgba($color, $opacity * 0.14)}',
+    14: '0px 14px 21px 2px #{rgba($color, $opacity * 0.14)}',
+    15: '0px 15px 22px 2px #{rgba($color, $opacity * 0.14)}',
+    16: '0px 16px 24px 2px #{rgba($color, $opacity * 0.14)}',
+    17: '0px 17px 26px 2px #{rgba($color, $opacity * 0.14)}',
+    18: '0px 18px 28px 2px #{rgba($color, $opacity * 0.14)}',
+    19: '0px 19px 29px 2px #{rgba($color, $opacity * 0.14)}',
+    20: '0px 20px 31px 3px #{rgba($color, $opacity * 0.14)}',
+    21: '0px 21px 33px 3px #{rgba($color, $opacity * 0.14)}',
+    22: '0px 22px 35px 3px #{rgba($color, $opacity * 0.14)}',
+    23: '0px 23px 36px 3px #{rgba($color, $opacity * 0.14)}',
+    24: '0px 24px 38px 3px #{rgba($color, $opacity * 0.14)}'
   );
 }
 
-@function _get-ambient-map($color) {
+@function _get-ambient-map($color, $opacity) {
   @return (
-    0: '0px 0px 0px 0px #{rgba($color, 0.12)}',
-    1: '0px 1px 3px 0px #{rgba($color, 0.12)}',
-    2: '0px 1px 5px 0px #{rgba($color, 0.12)}',
-    3: '0px 1px 8px 0px #{rgba($color, 0.12)}',
-    4: '0px 1px 10px 0px #{rgba($color, 0.12)}',
-    5: '0px 1px 14px 0px #{rgba($color, 0.12)}',
-    6: '0px 1px 18px 0px #{rgba($color, 0.12)}',
-    7: '0px 2px 16px 1px #{rgba($color, 0.12)}',
-    8: '0px 3px 14px 2px #{rgba($color, 0.12)}',
-    9: '0px 3px 16px 2px #{rgba($color, 0.12)}',
-    10: '0px 4px 18px 3px #{rgba($color, 0.12)}',
-    11: '0px 4px 20px 3px #{rgba($color, 0.12)}',
-    12: '0px 5px 22px 4px #{rgba($color, 0.12)}',
-    13: '0px 5px 24px 4px #{rgba($color, 0.12)}',
-    14: '0px 5px 26px 4px #{rgba($color, 0.12)}',
-    15: '0px 6px 28px 5px #{rgba($color, 0.12)}',
-    16: '0px 6px 30px 5px #{rgba($color, 0.12)}',
-    17: '0px 6px 32px 5px #{rgba($color, 0.12)}',
-    18: '0px 7px 34px 6px #{rgba($color, 0.12)}',
-    19: '0px 7px 36px 6px #{rgba($color, 0.12)}',
-    20: '0px 8px 38px 7px #{rgba($color, 0.12)}',
-    21: '0px 8px 40px 7px #{rgba($color, 0.12)}',
-    22: '0px 8px 42px 7px #{rgba($color, 0.12)}',
-    23: '0px 9px 44px 8px #{rgba($color, 0.12)}',
-    24: '0px 9px 46px 8px #{rgba($color, 0.12)}'
+    0: '0px 0px 0px 0px #{rgba($color, $opacity * 0.12)}',
+    1: '0px 1px 3px 0px #{rgba($color, $opacity * 0.12)}',
+    2: '0px 1px 5px 0px #{rgba($color, $opacity * 0.12)}',
+    3: '0px 1px 8px 0px #{rgba($color, $opacity * 0.12)}',
+    4: '0px 1px 10px 0px #{rgba($color, $opacity * 0.12)}',
+    5: '0px 1px 14px 0px #{rgba($color, $opacity * 0.12)}',
+    6: '0px 1px 18px 0px #{rgba($color, $opacity * 0.12)}',
+    7: '0px 2px 16px 1px #{rgba($color, $opacity * 0.12)}',
+    8: '0px 3px 14px 2px #{rgba($color, $opacity * 0.12)}',
+    9: '0px 3px 16px 2px #{rgba($color, $opacity * 0.12)}',
+    10: '0px 4px 18px 3px #{rgba($color, $opacity * 0.12)}',
+    11: '0px 4px 20px 3px #{rgba($color, $opacity * 0.12)}',
+    12: '0px 5px 22px 4px #{rgba($color, $opacity * 0.12)}',
+    13: '0px 5px 24px 4px #{rgba($color, $opacity * 0.12)}',
+    14: '0px 5px 26px 4px #{rgba($color, $opacity * 0.12)}',
+    15: '0px 6px 28px 5px #{rgba($color, $opacity * 0.12)}',
+    16: '0px 6px 30px 5px #{rgba($color, $opacity * 0.12)}',
+    17: '0px 6px 32px 5px #{rgba($color, $opacity * 0.12)}',
+    18: '0px 7px 34px 6px #{rgba($color, $opacity * 0.12)}',
+    19: '0px 7px 36px 6px #{rgba($color, $opacity * 0.12)}',
+    20: '0px 8px 38px 7px #{rgba($color, $opacity * 0.12)}',
+    21: '0px 8px 40px 7px #{rgba($color, $opacity * 0.12)}',
+    22: '0px 8px 42px 7px #{rgba($color, $opacity * 0.12)}',
+    23: '0px 9px 44px 8px #{rgba($color, $opacity * 0.12)}',
+    24: '0px 9px 46px 8px #{rgba($color, $opacity * 0.12)}'
   );
 }
 
@@ -127,12 +127,18 @@ $mat-elevation-transition-duration: 280ms !default;
 // The default easing value for elevation transitions.
 $mat-elevation-transition-timing-function: $mat-fast-out-slow-in-timing-function;
 
+// The default color for elevation shadows.
+$mat-elevation-color: black !default;
+
+// The default opacity scaling value for elevation shadows.
+$mat-elevation-opacity: 1 !default;
+
 // Prefix for elevation-related selectors.
 $_mat-elevation-prefix: 'mat-elevation-z';
 
 // Applies the correct css rules to an element to give it the elevation specified by $zValue.
 // The $zValue must be between 0 and 24.
-@mixin mat-elevation($zValue, $color: black) {
+@mixin mat-elevation($zValue, $color: $mat-elevation-color, $opacity: $mat-elevation-opacity) {
   @if type-of($zValue) != number or not unitless($zValue) {
     @error '$zValue must be a unitless number';
   }
@@ -140,16 +146,19 @@ $_mat-elevation-prefix: 'mat-elevation-z';
     @error '$zValue must be between 0 and 24';
   }
 
-  box-shadow: #{map-get(_get-umbra-map($color), $zValue)},
-              #{map-get(_get-penumbra-map($color), $zValue)},
-              #{map-get(_get-ambient-map($color), $zValue)};
+  box-shadow: #{map-get(_get-umbra-map($color, $opacity), $zValue)},
+              #{map-get(_get-penumbra-map($color, $opacity), $zValue)},
+              #{map-get(_get-ambient-map($color, $opacity), $zValue)};
 }
 
 // Applies the elevation to an element in a manner that allows
 // consumers to override it via the Material elevation classes.
-@mixin mat-overridable-elevation($zValue) {
+@mixin mat-overridable-elevation(
+    $zValue,
+    $color: $mat-elevation-color,
+    $opacity: $mat-elevation-opacity) {
   &:not([class*='#{$_mat-elevation-prefix}']) {
-    @include mat-elevation($zValue);
+    @include mat-elevation($zValue, $color, $opacity);
   }
 }