feat(elevation): Add elevation overlay mixins (material-components#5249)

Add mixins to set the overlay fill color, opacity, size, parent position, and shadow.

BREAKING CHANGE: Functions moved into the _functions.scss file

packages/mdc-elevation/README.md

@@ -51,6 +51,21 @@ However, you can also apply elevation to specific components using `mdc-elevatio
   </div>
 ```
 
+#### Elevation Overlay
+
+The elevation overlay should appear *above* the component container in the stacking context but *below* the ripple. To accomplish this, the `.mdc-elevation-overlay` element should appear *before* the `.mdc-<component>__ripple` element in the DOM context.  Here's sample markup for a button with a touch target.
+
+```html
+<button class="mdc-button mdc-button--raised">
+  <div class="mdc-elevation-overlay"></div>
+  <div class="mdc-button__ripple"></div>
+  <i class="material-icons mdc-button__icon" aria-hidden="true">favorite</i>
+  <span class="mdc-button__label">Font Icon</span>
+</button>
+```
+
+This ensures the ripple parts are rendered *above* the overlay.
+
 ### Styles
 
 ```scss
@@ -76,16 +91,26 @@ CSS Class | Description
 Mixin | Description
 --- | ---
 `mdc-elevation($z-value, $color, $opacity-boost)` | Sets the elevation to the z-space for that given elevation, and optionally sets the color and/or boosts the opacity of the shadow
+`mdc-elevation-overlay-common` | Called once per application to setup the universal elevation overlay styles
+`mdc-elevation-shadow($box-shadow)` | Sets the `box-shadow` of the closest parent selector
+`mdc-elevation-overlay-parent` | Sets the positioning of the overlay's parent element so that the overlay can be appropriately centered
+`mdc-elevation-overlay-size($width, $height: $width)` | Sets the width and height of the elevation overlay
+`mdc-elevation-overlay-fill-color($color)` | Sets the color of the elevation overlay
+`mdc-elevation-overlay-opacity($opacity)` | Sets the opacity of the elevation overlay
+
 
 Function | Description
 --- | ---
 `mdc-elevation-transition-value($duration, $easing)` | Returns a value for the `transition` property to transition an element between elevations
+`mdc-elevation-overlay-transition-value($duration, $easing)` | Returns a value for the `transition` property to transition the elevation overlay between elevations
 
 Variable | Description
 --- | ---
 `$mdc-elevation-property` | Default property for elevation transitions
 `$mdc-elevation-transition-duration` | Default duration value for elevation transitions
 `$mdc-elevation-transition-timing-function` | Default easing value for elevation transitions
+`$mdc-elevation-overlay-color` | Default color for the elevation overlay
+`$mdc-elevation-overlay-property` | Default property for the elevation overlay transitions
 
 If you need more configurability over your transitions, use the `mdc-elevation-transition-value` function in conjunction with the exported sass variables.
 

packages/mdc-elevation/_functions.scss

@@ -0,0 +1,49 @@
+//
+// Copyright 2019 Google Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+//
+
+@import "./variables";
+
+///
+/// Sets the elevation transition value.
+///
+/// @param {String} $duration - The duration of the transition.
+/// @param {String} $easing - The easing function for the transition.
+/// @return {String}
+///
+@function mdc-elevation-transition-value(
+  $duration: $mdc-elevation-transition-duration,
+  $easing: $mdc-elevation-transition-timing-function) {
+  @return #{$mdc-elevation-property} #{$duration} #{$easing};
+}
+
+///
+/// Sets the elevation overlay transition value.
+///
+/// @param {String} $duration - The duration of the transition.
+/// @param {String} $easing - The easing function for the transition.
+/// @return {String}
+///
+@function mdc-elevation-overlay-transition-value(
+  $duration: $mdc-elevation-transition-duration,
+  $easing: $mdc-elevation-transition-timing-function) {
+  @return #{$mdc-elevation-overlay-property} #{$duration} #{$easing};
+}

packages/mdc-elevation/_mixins.scss

@@ -20,9 +20,12 @@
 // THE SOFTWARE.
 //
 
+@import "@material/base/mixins";
 @import "@material/feature-targeting/functions";
 @import "@material/feature-targeting/mixins";
+@import "@material/theme/mixins";
 @import "@material/theme/variables";
+@import "./functions";
 @import "./variables";
 
 @mixin mdc-elevation-core-styles($query: mdc-feature-all()) {
@@ -46,6 +49,112 @@
   }
 }
 
+///
+/// Called once per application to set up the global default elevation styles.
+///
+@mixin mdc-elevation-overlay-common($query: mdc-feature-all()) {
+  $feat-animation: mdc-feature-create-target($query, animation);
+  $feat-structure: mdc-feature-create-target($query, structure);
+
+  @include mdc-elevation-overlay-selector_ {
+    @include mdc-feature-targets($feat-structure) {
+      @include mdc-base-emit-once("mdc-elevation/common/structure") {
+        position: absolute;
+        top: 50%;
+        /* @noflip */
+        left: 50%;
+        transform: translate(-50%, -50%);
+        border-radius: inherit;
+        opacity: 0;
+        pointer-events: none;
+      }
+    }
+
+    @include mdc-feature-targets($feat-animation) {
+      @include mdc-base-emit-once("mdc-elevation/common/animation") {
+        transition: mdc-elevation-overlay-transition-value();
+      }
+    }
+  }
+
+  @include mdc-base-emit-once("mdc-elevation/common/color") {
+    @include mdc-elevation-overlay-fill-color($mdc-elevation-overlay-color, $query: $query);
+  }
+}
+
+///
+/// Sets the shadow of the element.
+///
+/// @param {String} $box-shadow - The shadow to apply to the element.
+///
+@mixin mdc-elevation-shadow($box-shadow, $query: mdc-feature-all()) {
+  $feat-color: mdc-feature-create-target($query, color);
+
+  @include mdc-feature-targets($feat-color) {
+    /* @alternate */
+    box-shadow: $box-shadow;
+  }
+}
+
+///
+/// Sets the elevation overlay parent required positioning.
+///
+@mixin mdc-elevation-overlay-parent($query: mdc-feature-all()) {
+  $feat-structure: mdc-feature-create-target($query, structure);
+
+  @include mdc-feature-targets($feat-structure) {
+    /* @alternate */
+    position: relative;
+  }
+}
+
+///
+/// Sets the elevation overlay size.
+///
+/// @param {Number} $width - The width of the elevation overlay.
+/// @param {Number} $height [$width] - The height of the elevation overlay.
+///
+@mixin mdc-elevation-overlay-size($width, $height: $width, $query: mdc-feature-all()) {
+  $feat-structure: mdc-feature-create-target($query, structure);
+
+  @include mdc-elevation-overlay-selector_ {
+    @include mdc-feature-targets($feat-structure) {
+      width: $width;
+      height: $height;
+    }
+  }
+}
+
+///
+/// Sets the elevation overlay fill color.
+///
+/// @param {Color} $color - The color of the elevation overlay.
+///
+@mixin mdc-elevation-overlay-fill-color($color, $query: mdc-feature-all()) {
+  $feat-color: mdc-feature-create-target($query, color);
+
+  @include mdc-elevation-overlay-selector_ {
+    @include mdc-feature-targets($feat-color) {
+      @include mdc-theme-prop(background-color, $color);
+    }
+  }
+}
+
+///
+/// Sets the elevation overlay opacity.
+///
+/// @param {Number} $opacity - The opacity of the elevation overlay.
+///
+@mixin mdc-elevation-overlay-opacity($opacity, $query: mdc-feature-all()) {
+  $feat-color: mdc-feature-create-target($query, color);
+
+  @include mdc-elevation-overlay-selector_ {
+    @include mdc-feature-targets($feat-color) {
+      opacity: $opacity;
+    }
+  }
+}
+
 // Applies the correct CSS rules to an element to give it the elevation specified by $z-value.
 // The $z-value must be between 0 and 24.
 // If $color has an alpha channel, it will be ignored and overridden. To increase the opacity of the shadow, use
@@ -71,27 +180,27 @@
   $penumbra-color: rgba($color, $mdc-elevation-penumbra-opacity + $opacity-boost);
   $ambient-color: rgba($color, $mdc-elevation-ambient-opacity + $opacity-boost);
 
-  @include mdc-feature-targets($feat-color) {
-    box-shadow:
-      #{"#{$umbra-z-value} #{$umbra-color}"},
-      #{"#{$penumbra-z-value} #{$penumbra-color}"},
-      #{$ambient-z-value} $ambient-color;
-  }
+  $box-shadow: (
+    #{"#{$umbra-z-value} #{$umbra-color}"},
+    #{"#{$penumbra-z-value} #{$penumbra-color}"},
+    #{$ambient-z-value} $ambient-color,
+  );
+
+  @include mdc-elevation-shadow($box-shadow, $query: $query);
 }
 
-// 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.
-//
-// ```scss
-// .foo {
-//   transition: mdc-elevation-transition-value(), opacity 100ms ease;
-//   will-change: $mdc-elevation-property, opacity;
-// }
-// ```
-@function mdc-elevation-transition-value(
-  $duration: $mdc-elevation-transition-duration,
-  $easing: $mdc-elevation-transition-timing-function
-) {
-  @return #{$mdc-elevation-property} #{$duration} #{$easing};
+// Private
+
+///
+/// Sets the elevation overlay transition value.
+///
+/// @param {String} $duration - The duration of the transition.
+/// @param {String} $easing - The easing function for the transition.
+/// @return {String}
+/// @access private
+///
+@mixin mdc-elevation-overlay-selector_ {
+  .mdc-elevation-overlay {
+    @content;
+  }
 }

packages/mdc-elevation/_variables.scss

@@ -116,6 +116,14 @@ $mdc-elevation-ambient-map: (
 // example in a `will-change` rule.
 $mdc-elevation-property: box-shadow !default;
 
+// The default color for the elevation overlay.
+$mdc-elevation-overlay-color: #fff;
+
+// The css property used for elevation overlay transitions. In most cases this should not be changed. It is exposed
+// as a variable for abstraction / easy use when needing to reference the property directly, for
+// example in a `will-change` rule.
+$mdc-elevation-overlay-property: opacity !default;
+
 // The default duration value for elevation transitions.
 $mdc-elevation-transition-duration: 280ms !default;
 

packages/mdc-elevation/common.scss

@@ -0,0 +1,24 @@
+//
+// Copyright 2019 Google Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+//
+
+@import "./mixins";
+@include mdc-elevation-overlay-common;

packages/mdc-elevation/package.json

@@ -15,6 +15,7 @@
   },
   "dependencies": {
     "@material/animation": "^4.0.0",
+    "@material/base": "^4.0.0",
     "@material/feature-targeting": "^4.0.0",
     "@material/theme": "^4.0.0"
   }

test/scss/_feature-targeting-test.scss

@@ -151,7 +151,13 @@
 
     // Elevation
     @include mdc-elevation-core-styles($query: $query);
+    @include mdc-elevation-overlay-common($query: $query);
     @include mdc-elevation(0, $query: $query);
+    @include mdc-elevation-shadow(none, $query: $query);
+    @include mdc-elevation-overlay-parent($query: $query);
+    @include mdc-elevation-overlay-size(100%, $query: $query);
+    @include mdc-elevation-overlay-fill-color(red, $query: $query);
+    @include mdc-elevation-overlay-opacity(99%, $query: $query);
 
     // FAB
     @include mdc-fab-core-styles($query: $query);