feat(material-experimental/mdc-core): set up MDC-based elevation (#22397)

Sets up elevation utilities based on top of MDC, similar to the ones we currently have.

Author: crisbeto

src/material-experimental/_index.scss

@@ -1,5 +1,6 @@
 // Structural
 @forward './mdc-helpers/focus-indicators' as mdc-* show mdc-strong-focus-indicators;
+@forward './mdc-core/elevation' show elevation, overridable-elevation;
 
 // Theme bundles
 @forward './mdc-theming/all-theme' show all-mdc-component-themes;

src/material-experimental/mdc-core/_core-theme.scss

@@ -1,15 +1,30 @@
 @use '../../material/core/theming/theming';
 @use './option/option-theme';
 @use './option/optgroup-theme';
+@use './elevation';
 
 // Mixin that renders all of the core styles that depend on the theme.
 @mixin theme($theme-or-color-config) {
   $theme: theming.private-legacy-get-theme($theme-or-color-config);
+
   // Wrap the sub-theme includes in the duplicate theme styles mixin. This ensures that
   // there won't be multiple warnings. e.g. if `mat-mdc-core-theme` reports a warning, then
   // the imported themes (such as `mat-ripple-theme`) should not report again.
   @include theming.private-check-duplicate-theme-styles($theme, 'mat-mdc-core') {
+    $color: theming.get-color-config($theme);
+
     @include option-theme.theme($theme);
     @include optgroup-theme.theme($theme);
+
+    @if $color != null {
+      // Provides external CSS classes for each elevation value. Each CSS class is formatted as
+      // `mat-mdc-elevation-z$zValue` where `$zValue` corresponds to the z-space to which the
+      // element is elevated.
+      @for $zValue from 0 through 24 {
+        .#{elevation.$prefix}#{$zValue} {
+          @include elevation.private-theme-elevation($zValue, $color);
+        }
+      }
+    }
   }
 }

src/material-experimental/mdc-core/_elevation.scss

@@ -0,0 +1,39 @@
+@use 'sass:map';
+@use '@material/elevation/elevation-theme' as mdc-elevation;
+
+// Prefix for elevation-related selectors.
+$prefix: 'mat-mdc-elevation-z';
+
+// The default color for elevation shadows.
+$color: black !default;
+
+// 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 elevation($zValue, $color: $color) {
+  @include mdc-elevation.elevation($zValue, $color);
+}
+
+// Applies the elevation to an element in a manner that allows
+// consumers to override it via the Material elevation classes.
+@mixin overridable-elevation($zValue, $color: $color) {
+  &:not([class*='#{$prefix}']) {
+    @include elevation($zValue, $color);
+  }
+}
+
+@mixin private-theme-elevation($zValue, $config) {
+  @debug $config;
+  $foreground: map.get($config, foreground);
+  $elevation-color: map.get($foreground, elevation);
+  $elevation-color-or-default: if($elevation-color == null, $color, $elevation-color);
+
+  @include elevation($zValue, $elevation-color-or-default);
+}
+
+@mixin private-theme-overridable-elevation($zValue, $config) {
+  $foreground: map.get($config, foreground);
+  $elevation-color: map.get($foreground, elevation);
+  $elevation-color-or-default: if($elevation-color == null, $color, $elevation-color);
+
+  @include overridable-elevation($zValue, $elevation-color-or-default);
+}