feat(theme): emit CSS var() declarations when provided a standalone c…

…ustom prop

BREAKING CHANGE: custom-properties.apply() has been renamed to declaration() to better align with css.declaration()

PiperOrigin-RevId: 355659381

packages/mdc-theme/_custom-properties.scss

@@ -125,23 +125,58 @@
   }
 }
 
-/// Applies a custom property value to the specified property.
+/// Emits a CSS declaration for a custom property. A custom property may either
+/// be provided as the value to a CSS property string to be emitted as a var()
+/// function, or as a standalone value to be emitted as a custom property
+/// declaration.
 ///
-/// @param {String} $property - the name of the CSS property.
-/// @param {Map} $custom-prop - a custom property Map for the property's value.
-/// @param {Map} $gss - optional Map of GSS annotations to set.
-/// @param {Bool} $important - set to true to add an `!important` rule. Defaults
-///     to false.
-@mixin apply($property, $custom-prop, $gss: (), $important: false) {
-  @if not is-custom-prop($custom-prop) {
-    @error "mdc-theme: Invalid custom property: #{$custom-prop}. Must be a Map with 'varname' and 'fallback'.";
-  }
+/// @example - scss
+///   @include declaration(color, create(--foo, teal));
+///   // color: var(--foo, teal);
+///   @include declaration(create(--foo, teal));
+///   // --foo: teal;
+///
+/// Standalone custom properties must have a fallback value to emit as a CSS
+/// declaration.
+///
+/// @see {mixin} css.declaration
+///
+/// @param {String} $property - The CSS property of the declaration or the
+///     custom property Map to emit.
+/// @param {Map} $custom-prop - A custom property Map for the property's value.
+///     Optional if $property is the custom property Map to emit.
+/// @param {Map} $gss - An optional Map of GSS annotations to add.
+/// @param {Bool} $important - If true, add `!important` to the declaration.
+@mixin declaration($property, $custom-prop: null, $gss: (), $important: false) {
+  @if $property {
+    $value: null;
+    $fallback-value: null;
+    @if is-custom-prop($property) {
+      $custom-prop: $property;
+      $property: get-varname($custom-prop);
+      $value: get-fallback($custom-prop, $shallow: true);
+      @if not $value {
+        @error 'Custom property #{$property} does not have a fallback value to emit for a CSS declaration.';
+      }
 
-  @include css.declaration(
-    $property,
-    $value: create-var($custom-prop),
-    $fallback-value: get-fallback($custom-prop),
-    $gss: $gss,
-    $important: $important
-  );
+      @if is-custom-prop($value) {
+        $value: create-var($value);
+      }
+    } @else {
+      @if not is-custom-prop($custom-prop) {
+        @error "Invalid custom property: #{$custom-prop}. Must be a Map with 'varname' and 'fallback'.";
+      }
+
+      $value: create-var($custom-prop);
+      $fallback-value: get-fallback($custom-prop);
+    }
+
+    @include css.declaration(
+      $property,
+      $value,
+      $fallback-value: $fallback-value,
+      $gss: $gss,
+      $important: $important
+    );
+  }
 }

packages/mdc-theme/_theme.scss

@@ -48,13 +48,13 @@
     @if $style != 'background' and $style != 'surface' {
       .mdc-theme--#{$style} {
         @include feature-targeting.targets($feat-color) {
-          @include prop(color, $style, true);
+          @include property(color, $style, $important: true);
         }
       }
     } @else {
       .mdc-theme--#{$style} {
         @include feature-targeting.targets($feat-color) {
-          @include prop(background-color, $style);
+          @include property(background-color, $style);
         }
       }
     }
@@ -64,7 +64,7 @@
   @each $style in ('primary', 'secondary') {
     .mdc-theme--#{$style}-bg {
       @include feature-targeting.targets($feat-color) {
-        @include prop(background-color, $style, true);
+        @include property(background-color, $style, $important: true);
       }
     }
   }
@@ -113,7 +113,7 @@
 ) {
   @if custom-properties.is-custom-prop($value) {
     // $value is a custom property Map
-    @include custom-properties.apply(
+    @include custom-properties.declaration(
       $property,
       $value,
       $gss: $gss,
@@ -122,7 +122,7 @@
   } @else if map.has-key(theme-color.$property-values, $value) {
     // $value is a theme property String
     $custom-prop: theme-color.get-custom-property($value);
-    @include custom-properties.apply(
+    @include custom-properties.declaration(
       $property,
       $custom-prop,
       $gss: $gss,
@@ -131,7 +131,7 @@
   } @else {
     // $value is a standard CSS value
     $fallback: null;
-    @if $replace {
+    @if $replace and $value {
       @if meta.type-of($replace) != 'map' {
         @error 'mdc-theme: Invalid replacement #{$replace}. Must be a Map.';
       }