feat(material-experimental/theming): Add support for color variants (#28279)

* feat(material-experimental/theming): Add support for color variants

Adds token infrastructure to be able to support color variants for M3
components. This is accomplished by adding an additional namesapce to
the token map per color variant. For example, if the mat-icon tokens
live in the token map under `(mat, icon): (token-values...)`, and we
want to support a primary color variant, we will add a new namespace
`(mat, icon, primary): (token-value-overrides...)`.

When applying a color or theme mixin for an M3 theme, users can specify
the desired variant as an extra parameter to the mixin:
`@include mat.icon-theme($theme, $color-variant: primary)`. The mixin
will then merge any overrides from the variant namespace into the
default values from the standard namespace to determine the final value
for each CSS variable. Note that the user must provide this a keyword
argument, not a positional argument. This makes the API easier to
maintain should we need to add other options later.

In addition to adding the necessary infrastructure for color variants,
this PR also builds out the color variant supprot for mat-icon to prove
out the infrstructure and serve as an example.

* docs: Update sass doc comments based on feedback

Author: mmalerba

src/dev-app/theme-m3.scss

@@ -2,6 +2,22 @@
 @use '@angular/material' as mat;
 @use '@angular/material-experimental' as matx;
 
+// TODO(mmalerba): Consider adding this as a back-compat API for users who want it, rather than just
+//  a demo thing.
+@mixin color-variants-back-compat($theme) {
+  .mat-primary {
+    &.mat-icon { @include mat.icon-color($theme, $color-variant: primary); }
+  }
+
+  .mat-accent {
+    &.mat-icon { @include mat.icon-color($theme, $color-variant: secondary); }
+  }
+
+  .mat-warn {
+    &.mat-icon { @include mat.icon-color($theme, $color-variant: error); }
+  }
+}
+
 // Add an indicator to make it clear that the app is styled with the experimental M3 theme.
 dev-app {
   &::before {
@@ -79,6 +95,8 @@ html {
   @include mat.tree-theme($light-theme);
 }
 
+@include color-variants-back-compat($light-theme);
+
 // Emit dark theme styles.
 .demo-unicorn-dark-theme {
   // TODO(mmalerba): choose colors from the theming API.
@@ -124,6 +142,8 @@ html {
   @include mat.toolbar-color($dark-theme);
   @include mat.tooltip-color($dark-theme);
   @include mat.tree-color($dark-theme);
+
+  @include color-variants-back-compat($dark-theme);
 }
 
 // Emit density styles for each scale.

src/material-experimental/theming/_custom-tokens.scss

@@ -334,9 +334,23 @@
 /// @param {Boolean} $exclude-hardcoded Whether to exclude hardcoded token values
 /// @return {Map} A set of custom tokens for the mat-icon
 @function icon($systems, $exclude-hardcoded) {
-  @return (
+  @return ((
     color: _hardcode(inherit, $exclude-hardcoded),
-  );
+  ), (
+    // Color variants:
+    primary: (
+      color: map.get($systems, md-sys-color, primary),
+    ),
+    secondary: (
+      color: map.get($systems, md-sys-color, secondary),
+    ),
+    tertiary: (
+      color: map.get($systems, md-sys-color, tertiary),
+    ),
+    error: (
+      color: map.get($systems, md-sys-color, error),
+    )
+  ));
 }
 
 /// Generates custom tokens for the mat-button.

src/material-experimental/theming/_m3-tokens.scss

@@ -1,5 +1,5 @@
-@use 'sass:map';
 @use 'sass:list';
+@use 'sass:map';
 @use 'sass:meta';
 @use '@angular/material' as mat;
 @use '@material/tokens/v0_161' as mdc-tokens;
@@ -51,15 +51,35 @@
 
 /// Gets the MDC tokens for the given prefix, M3 token values, and supported token slots.
 /// @param {List} $prefix The token prefix for the given tokens.
-/// @param {Map} $m3-values A map of M3 token values for the given prefix.
+/// @param {Map|(Map, Map)} $m3-values A map of M3 token values for the given prefix.
+///  This param may also be a tuple of maps, the first one representing the default M3 token values,
+//   and the second containing overrides for different color variants.
+//   Single map example:
+//     (token1: green, token2: 2px)
+//   Tuple example:
+//     (
+//       (token1: green, token2: 2px),
+//       (
+//         secondary: (token1: blue),
+//         error: (token1: red),
+//       )
+//     )
 /// @param {Map} $slots A map of token slots, with null value indicating the token is not supported.
+/// @param {String|null} $variant The name of the variant the token values are for.
 /// @return {Map} A map of fully qualified token names to values, for only the supported tokens.
-@function _namespace-tokens($prefix, $m3-values, $slots) {
+@function _namespace-tokens($prefix, $m3-values, $slots, $variant: null) {
+  $result: ();
+  @if $variant == null and meta.type-of($m3-values) == 'list' and list.length($m3-values == 2) {
+    $variants: list.nth($m3-values, 2);
+    $m3-values: list.nth($m3-values, 1);
+    @each $variant, $overrides in $variants {
+      $result: map.merge($result, _namespace-tokens($prefix, $overrides, $slots, $variant));
+    }
+  }
   $used-token-names: map.keys(_filter-nulls(map.get($slots, $prefix)));
   $used-m3-tokens: _pick(_filter-nulls($m3-values), $used-token-names);
-  @return (
-    $prefix: $used-m3-tokens,
-  );
+  $prefix: if($variant == null, $prefix, list.append($prefix, $variant));
+  @return map.merge($result, ($prefix: $used-m3-tokens));
 }
 
 /// Generates tokens for the given palette with the given prefix.
@@ -394,7 +414,7 @@
   $token-slots: mat.m2-tokens-from-theme($fake-theme);
 
   // TODO(mmalerba): Fill in remaining tokens.
-  $result: mat.private-merge-all(
+  $result: mat.private-deep-merge-all(
     // Add the system color & typography tokens (so we can give users access via an API).
     (
       (mdc, theme): map.get($systems, md-sys-color),

src/material/core/style/_sass-utils.scss

@@ -1,4 +1,5 @@
 @use 'sass:color';
+@use 'sass:list';
 @use 'sass:map';
 @use 'sass:meta';
 
@@ -59,3 +60,21 @@
   $args: meta.keywords($args);
   @return if(meta.type-of($color) == 'color', color.change($color, $args...), $color);
 }
+
+/// Gets the given arguments as a map of keywords and validates that only supported arguments were
+/// passed.
+/// @param {ArgList} $args The arguments to convert to a keywords map.
+/// @param {List} $supported-args The supported argument names.
+/// @return {Map} The $args as a map of argument name to argument value.
+@function validate-keyword-args($args, $supported-args) {
+  @if list.length($args) > 0 {
+    @error #{'Expected keyword args, but got positional args: '}#{$args};
+  }
+  $kwargs: meta.keywords($args);
+  @each $arg, $v in $kwargs {
+    @if list.index($supported-args, $arg) == null {
+      @error #{'Unsupported argument '}#{$arg}#{'. Valid arguments are: '}#{$supported-args};
+    }
+  }
+  @return $kwargs;
+}

src/material/core/tokens/_token-utils.scss

@@ -1,8 +1,10 @@
+@use 'sass:list';
 @use 'sass:map';
 @use '@material/elevation/elevation-theme' as mdc-elevation-theme;
 @use '@material/theme/custom-properties' as mdc-custom-properties;
 @use '@material/theme/theme' as mdc-theme;
 @use '@material/theme/keys' as mdc-keys;
+@use '../style/sass-utils';
 @use '../theming/palette';
 @use '../theming/theming';
 @use '../typography/typography';
@@ -125,3 +127,57 @@ $_component-prefix: null;
     $shadow-color-token: null,
   ));
 }
+
+/// Checks whether a list starts wih a given prefix
+/// @param {List} $list The list value to check the prefix of.
+/// @param {List} $prefix The prefix to check.
+/// @return {Boolean} Whether the list starts with the prefix.
+@function _is-prefix($list, $prefix) {
+  @for $i from 1 through list.length($prefix) {
+    @if list.nth($list, $i) != list.nth($prefix, $i) {
+      @return false;
+    }
+  }
+  @return true;
+}
+
+/// Gets the supported color variants in the given token set for the given prefix.
+/// @param {Map} $tokens The full token map.
+/// @param {List} $prefix The component prefix to get color variants for.
+/// @return {List} The supported color variants.
+@function _supported-color-variants($tokens, $prefix) {
+  $result: ();
+  @each $namespace in map.keys($tokens) {
+    @if list.length($prefix) == list.length($namespace) - 1 and _is-prefix($namespace, $prefix) {
+      $result: list.append($result, list.nth($namespace, list.length($namespace)), comma);
+    }
+  }
+  @return $result;
+}
+
+/// Gets the token values for the given components prefix with the given options.
+/// @param {Map} $tokens The full token map.
+/// @param {List} $prefix The component prefix to get the token values for.
+/// @param {ArgList} Any additional options
+///   Currently the additional supported options are:
+//     - $color-variant (The color variant to use for the component)
+/// @throws If given options are invalid
+/// @return {Map} The token values for the requested component.
+@function get-tokens-for($tokens, $prefix, $options...) {
+  $options: sass-utils.validate-keyword-args($options, (color-variant));
+  @if $tokens == () {
+    @return ();
+  }
+  $values: map.get($tokens, $prefix);
+  $color-variant: map.get($options, color-variant);
+  @if $color-variant == null {
+    @return $values;
+  }
+  $overrides: map.get($tokens, list.append($prefix, $color-variant));
+  @if $overrides == null {
+    @error #{'Invalid color variant: '}#{$color-variant}#{'. Supported color variants are: '}#{
+      _supported-color-variants($tokens, $prefix)
+    }#{'.'};
+  }
+  @return map.merge($values, $overrides);
+}

src/material/icon/_icon-theme.scss

@@ -1,4 +1,3 @@
-@use 'sass:map';
 @use '../core/theming/theming';
 @use '../core/theming/inspection';
 @use '../core/tokens/m2/mat/icon' as tokens-mat-icon;
@@ -11,16 +10,24 @@
   @include token-utils.create-token-values(tokens-mat-icon.$prefix, $tokens);
 }
 
+/// Outputs base theme styles (styles not dependent on the color, typography, or density settings)
+/// for the mat-icon.
+/// @param {Map} $theme The theme to generate base styles for.
 @mixin base($theme) {
   @if inspection.get-theme-version($theme) == 1 {
     @include _theme-from-tokens(inspection.get-theme-tokens($theme, base));
   }
   @else {}
 }
 
-@mixin color($theme) {
+/// Outputs color theme styles for the mat-icon.
+/// @param {Map} $theme The theme to generate color styles for.
+/// @param {ArgList} Additional optional arguments (only supported for M3 themes):
+///   $color-variant: The color variant to use for the icon: primary, secondary, tertiary, or error
+///     (If not specified, default neutral color will be used).
+@mixin color($theme, $options...) {
   @if inspection.get-theme-version($theme) == 1 {
-    @include _theme-from-tokens(inspection.get-theme-tokens($theme, color));
+    @include _theme-from-tokens(inspection.get-theme-tokens($theme, color), $options...);
   }
   @else {
     @include sass-utils.current-selector-or-root() {
@@ -44,24 +51,33 @@
   }
 }
 
+/// Outputs typography theme styles for the mat-icon.
+/// @param {Map} $theme The theme to generate typography styles for.
 @mixin typography($theme) {
   @if inspection.get-theme-version($theme) == 1 {
     @include _theme-from-tokens(inspection.get-theme-tokens($theme, typography));
   }
   @else {}
 }
 
+/// Outputs density theme styles for the mat-icon.
+/// @param {Map} $theme The theme to generate density styles for.
 @mixin density($theme) {
   @if inspection.get-theme-version($theme) == 1 {
     @include _theme-from-tokens(inspection.get-theme-tokens($theme, density));
   }
   @else {}
 }
 
-@mixin theme($theme) {
+/// Outputs all (base, color, typography, and density) theme styles for the mat-icon.
+/// @param {Map} $theme The theme to generate styles for.
+/// @param {ArgList} Additional optional arguments (only supported for M3 themes):
+///   $color-variant: The color variant to use for the icon: primary, secondary, tertiary, or error
+///     (If not specified, default neutral color will be used).
+@mixin theme($theme, $options...) {
   @include theming.private-check-duplicate-theme-styles($theme, 'mat-icon') {
     @if inspection.get-theme-version($theme) == 1 {
-      @include _theme-from-tokens(inspection.get-theme-tokens($theme));
+      @include _theme-from-tokens(inspection.get-theme-tokens($theme), $options...);
     }
     @else {
       @include base($theme);
@@ -78,9 +94,7 @@
   }
 }
 
-@mixin _theme-from-tokens($tokens) {
-  @if ($tokens != ()) {
-    @include token-utils.create-token-values(
-        tokens-mat-icon.$prefix, map.get($tokens, tokens-mat-icon.$prefix));
-  }
+@mixin _theme-from-tokens($tokens, $options...) {
+  $mat-icon-tokens: token-utils.get-tokens-for($tokens, tokens-mat-icon.$prefix, $options...);
+  @include token-utils.create-token-values(tokens-mat-icon.$prefix, $mat-icon-tokens);
 }