Skip to content
This repository was archived by the owner on Jan 13, 2025. It is now read-only.

Commit b4cfdc4

Browse files
patrickrodeepatrickrodee
authored
feat(elevation): Add elevation overlay mixins (#5249)
Add mixins to set the overlay fill color, opacity, size, parent position, and shadow. BREAKING CHANGE: Functions moved into the _functions.scss file
1 parent 7161170 commit b4cfdc4

File tree

7 files changed

+243
-21
lines changed

7 files changed

+243
-21
lines changed

‎packages/mdc-elevation/README.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,21 @@ However, you can also apply elevation to specific components using `mdc-elevatio
5151
</div>
5252
```
5353

54+
#### Elevation Overlay
55+
56+
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.
57+
58+
```html
59+
<button class="mdc-button mdc-button--raised">
60+
<div class="mdc-elevation-overlay"></div>
61+
<div class="mdc-button__ripple"></div>
62+
<i class="material-icons mdc-button__icon" aria-hidden="true">favorite</i>
63+
<span class="mdc-button__label">Font Icon</span>
64+
</button>
65+
```
66+
67+
This ensures the ripple parts are rendered *above* the overlay.
68+
5469
### Styles
5570

5671
```scss
@@ -76,16 +91,26 @@ CSS Class | Description
7691
Mixin | Description
7792
--- | ---
7893
`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
94+
`mdc-elevation-overlay-common` | Called once per application to setup the universal elevation overlay styles
95+
`mdc-elevation-shadow($box-shadow)` | Sets the `box-shadow` of the closest parent selector
96+
`mdc-elevation-overlay-parent` | Sets the positioning of the overlay's parent element so that the overlay can be appropriately centered
97+
`mdc-elevation-overlay-size($width, $height: $width)` | Sets the width and height of the elevation overlay
98+
`mdc-elevation-overlay-fill-color($color)` | Sets the color of the elevation overlay
99+
`mdc-elevation-overlay-opacity($opacity)` | Sets the opacity of the elevation overlay
100+
79101

80102
Function | Description
81103
--- | ---
82104
`mdc-elevation-transition-value($duration, $easing)` | Returns a value for the `transition` property to transition an element between elevations
105+
`mdc-elevation-overlay-transition-value($duration, $easing)` | Returns a value for the `transition` property to transition the elevation overlay between elevations
83106

84107
Variable | Description
85108
--- | ---
86109
`$mdc-elevation-property` | Default property for elevation transitions
87110
`$mdc-elevation-transition-duration` | Default duration value for elevation transitions
88111
`$mdc-elevation-transition-timing-function` | Default easing value for elevation transitions
112+
`$mdc-elevation-overlay-color` | Default color for the elevation overlay
113+
`$mdc-elevation-overlay-property` | Default property for the elevation overlay transitions
89114

90115
If you need more configurability over your transitions, use the `mdc-elevation-transition-value` function in conjunction with the exported sass variables.
91116

‎packages/mdc-elevation/_functions.scss

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
//
2+
// Copyright 2019 Google Inc.
3+
//
4+
// Permission is hereby granted, free of charge, to any person obtaining a copy
5+
// of this software and associated documentation files (the "Software"), to deal
6+
// in the Software without restriction, including without limitation the rights
7+
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8+
// copies of the Software, and to permit persons to whom the Software is
9+
// furnished to do so, subject to the following conditions:
10+
//
11+
// The above copyright notice and this permission notice shall be included in
12+
// all copies or substantial portions of the Software.
13+
//
14+
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15+
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16+
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17+
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18+
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19+
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
20+
// THE SOFTWARE.
21+
//
22+
23+
@import "./variables";
24+
25+
///
26+
/// Sets the elevation transition value.
27+
///
28+
/// @param {String} $duration - The duration of the transition.
29+
/// @param {String} $easing - The easing function for the transition.
30+
/// @return {String}
31+
///
32+
@function mdc-elevation-transition-value(
33+
$duration: $mdc-elevation-transition-duration,
34+
$easing: $mdc-elevation-transition-timing-function) {
35+
@return #{$mdc-elevation-property} #{$duration} #{$easing};
36+
}
37+
38+
///
39+
/// Sets the elevation overlay transition value.
40+
///
41+
/// @param {String} $duration - The duration of the transition.
42+
/// @param {String} $easing - The easing function for the transition.
43+
/// @return {String}
44+
///
45+
@function mdc-elevation-overlay-transition-value(
46+
$duration: $mdc-elevation-transition-duration,
47+
$easing: $mdc-elevation-transition-timing-function) {
48+
@return #{$mdc-elevation-overlay-property} #{$duration} #{$easing};
49+
}

‎packages/mdc-elevation/_mixins.scss

Lines changed: 130 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,12 @@
2020
// THE SOFTWARE.
2121
//
2222

23+
@import "@material/base/mixins";
2324
@import "@material/feature-targeting/functions";
2425
@import "@material/feature-targeting/mixins";
26+
@import "@material/theme/mixins";
2527
@import "@material/theme/variables";
28+
@import "./functions";
2629
@import "./variables";
2730

2831
@mixin mdc-elevation-core-styles($query: mdc-feature-all()) {
@@ -46,6 +49,112 @@
4649
}
4750
}
4851

52+
///
53+
/// Called once per application to set up the global default elevation styles.
54+
///
55+
@mixin mdc-elevation-overlay-common($query: mdc-feature-all()) {
56+
$feat-animation: mdc-feature-create-target($query, animation);
57+
$feat-structure: mdc-feature-create-target($query, structure);
58+
59+
@include mdc-elevation-overlay-selector_ {
60+
@include mdc-feature-targets($feat-structure) {
61+
@include mdc-base-emit-once("mdc-elevation/common/structure") {
62+
position: absolute;
63+
top: 50%;
64+
/* @noflip */
65+
left: 50%;
66+
transform: translate(-50%, -50%);
67+
border-radius: inherit;
68+
opacity: 0;
69+
pointer-events: none;
70+
}
71+
}
72+
73+
@include mdc-feature-targets($feat-animation) {
74+
@include mdc-base-emit-once("mdc-elevation/common/animation") {
75+
transition: mdc-elevation-overlay-transition-value();
76+
}
77+
}
78+
}
79+
80+
@include mdc-base-emit-once("mdc-elevation/common/color") {
81+
@include mdc-elevation-overlay-fill-color($mdc-elevation-overlay-color, $query: $query);
82+
}
83+
}
84+
85+
///
86+
/// Sets the shadow of the element.
87+
///
88+
/// @param {String} $box-shadow - The shadow to apply to the element.
89+
///
90+
@mixin mdc-elevation-shadow($box-shadow, $query: mdc-feature-all()) {
91+
$feat-color: mdc-feature-create-target($query, color);
92+
93+
@include mdc-feature-targets($feat-color) {
94+
/* @alternate */
95+
box-shadow: $box-shadow;
96+
}
97+
}
98+
99+
///
100+
/// Sets the elevation overlay parent required positioning.
101+
///
102+
@mixin mdc-elevation-overlay-parent($query: mdc-feature-all()) {
103+
$feat-structure: mdc-feature-create-target($query, structure);
104+
105+
@include mdc-feature-targets($feat-structure) {
106+
/* @alternate */
107+
position: relative;
108+
}
109+
}
110+
111+
///
112+
/// Sets the elevation overlay size.
113+
///
114+
/// @param {Number} $width - The width of the elevation overlay.
115+
/// @param {Number} $height [$width] - The height of the elevation overlay.
116+
///
117+
@mixin mdc-elevation-overlay-size($width, $height: $width, $query: mdc-feature-all()) {
118+
$feat-structure: mdc-feature-create-target($query, structure);
119+
120+
@include mdc-elevation-overlay-selector_ {
121+
@include mdc-feature-targets($feat-structure) {
122+
width: $width;
123+
height: $height;
124+
}
125+
}
126+
}
127+
128+
///
129+
/// Sets the elevation overlay fill color.
130+
///
131+
/// @param {Color} $color - The color of the elevation overlay.
132+
///
133+
@mixin mdc-elevation-overlay-fill-color($color, $query: mdc-feature-all()) {
134+
$feat-color: mdc-feature-create-target($query, color);
135+
136+
@include mdc-elevation-overlay-selector_ {
137+
@include mdc-feature-targets($feat-color) {
138+
@include mdc-theme-prop(background-color, $color);
139+
}
140+
}
141+
}
142+
143+
///
144+
/// Sets the elevation overlay opacity.
145+
///
146+
/// @param {Number} $opacity - The opacity of the elevation overlay.
147+
///
148+
@mixin mdc-elevation-overlay-opacity($opacity, $query: mdc-feature-all()) {
149+
$feat-color: mdc-feature-create-target($query, color);
150+
151+
@include mdc-elevation-overlay-selector_ {
152+
@include mdc-feature-targets($feat-color) {
153+
opacity: $opacity;
154+
}
155+
}
156+
}
157+
49158
// Applies the correct CSS rules to an element to give it the elevation specified by $z-value.
50159
// The $z-value must be between 0 and 24.
51160
// If $color has an alpha channel, it will be ignored and overridden. To increase the opacity of the shadow, use
@@ -71,27 +180,27 @@
71180
$penumbra-color: rgba($color, $mdc-elevation-penumbra-opacity + $opacity-boost);
72181
$ambient-color: rgba($color, $mdc-elevation-ambient-opacity + $opacity-boost);
73182

74-
@include mdc-feature-targets($feat-color) {
75-
box-shadow:
76-
#{"#{$umbra-z-value} #{$umbra-color}"},
77-
#{"#{$penumbra-z-value} #{$penumbra-color}"},
78-
#{$ambient-z-value} $ambient-color;
79-
}
183+
$box-shadow: (
184+
#{"#{$umbra-z-value} #{$umbra-color}"},
185+
#{"#{$penumbra-z-value} #{$penumbra-color}"},
186+
#{$ambient-z-value} $ambient-color,
187+
);
188+
189+
@include mdc-elevation-shadow($box-shadow, $query: $query);
80190
}
81191

82-
// Returns a string that can be used as the value for a `transition` property for elevation.
83-
// Calling this function directly is useful in situations where a component needs to transition
84-
// more than one property.
85-
//
86-
// ```scss
87-
// .foo {
88-
// transition: mdc-elevation-transition-value(), opacity 100ms ease;
89-
// will-change: $mdc-elevation-property, opacity;
90-
// }
91-
// ```
92-
@function mdc-elevation-transition-value(
93-
$duration: $mdc-elevation-transition-duration,
94-
$easing: $mdc-elevation-transition-timing-function
95-
) {
96-
@return #{$mdc-elevation-property} #{$duration} #{$easing};
192+
// Private
193+
194+
///
195+
/// Sets the elevation overlay transition value.
196+
///
197+
/// @param {String} $duration - The duration of the transition.
198+
/// @param {String} $easing - The easing function for the transition.
199+
/// @return {String}
200+
/// @access private
201+
///
202+
@mixin mdc-elevation-overlay-selector_ {
203+
.mdc-elevation-overlay {
204+
@content;
205+
}
97206
}

‎packages/mdc-elevation/_variables.scss

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,14 @@ $mdc-elevation-ambient-map: (
116116
// example in a `will-change` rule.
117117
$mdc-elevation-property: box-shadow !default;
118118

119+
// The default color for the elevation overlay.
120+
$mdc-elevation-overlay-color: #fff;
121+
122+
// The css property used for elevation overlay transitions. In most cases this should not be changed. It is exposed
123+
// as a variable for abstraction / easy use when needing to reference the property directly, for
124+
// example in a `will-change` rule.
125+
$mdc-elevation-overlay-property: opacity !default;
126+
119127
// The default duration value for elevation transitions.
120128
$mdc-elevation-transition-duration: 280ms !default;
121129

‎packages/mdc-elevation/common.scss

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

‎packages/mdc-elevation/package.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
},
1616
"dependencies": {
1717
"@material/animation": "^4.0.0",
18+
"@material/base": "^4.0.0",
1819
"@material/feature-targeting": "^4.0.0",
1920
"@material/theme": "^4.0.0"
2021
}

‎test/scss/_feature-targeting-test.scss

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,7 +151,13 @@
151151

152152
// Elevation
153153
@include mdc-elevation-core-styles($query: $query);
154+
@include mdc-elevation-overlay-common($query: $query);
154155
@include mdc-elevation(0, $query: $query);
156+
@include mdc-elevation-shadow(none, $query: $query);
157+
@include mdc-elevation-overlay-parent($query: $query);
158+
@include mdc-elevation-overlay-size(100%, $query: $query);
159+
@include mdc-elevation-overlay-fill-color(red, $query: $query);
160+
@include mdc-elevation-overlay-opacity(99%, $query: $query);
155161

156162
// FAB
157163
@include mdc-fab-core-styles($query: $query);

0 commit comments

Comments
 (0)