feat(material-experimental/theming): Introduce a facade layer between

user-facing customizable keys and actual MDC token names

This allows us to expose easier to understand names for users, and
decouples us from changes that MDC might make to token names in the
future

Author: mmalerba

src/dev-app/theme-token-api.scss

@@ -60,9 +60,7 @@ html {
     $tokens: mat.m2-tokens-from-theme($dark-theme),
     $components: (
       matx.checkbox((
-        (mdc, checkbox): (
-          selected-checkmark-color: red,
-        )
+        checkmark-color: red,
       )),
     ));
 }

src/material-experimental/_index.scss

@@ -5,6 +5,8 @@
   popover-edit-typography, popover-edit-density, popover-edit-theme;
 
 // Token-based theming API
-@forward './theming/theming' show theme, card, checkbox;
+@forward './theming/theming' show theme, retheme;
+@forward './theming/checkbox' show checkbox;
+@forward './theming/card' show card;
 
 // Additional public APIs for individual components

src/material-experimental/theming/_card.scss

@@ -0,0 +1,93 @@
+@use 'sass:color';
+@use 'sass:meta';
+@use '@angular/material' as mat;
+@use './token-resolution';
+
+// TODO(mmalerba): This should live under material/card when moving out of experimental.
+
+/// Gets tokens for setting the card's shape.
+/// @param {String} $shape The card's shape.
+/// @return {Map} A map of tokens for setting the card's shape.
+// Note: we use a function rather than simple rename, because we want to map a single shape value to
+// multiple tokens, rather than offer separate shape customizations for elevated and outlined cards.
+@function _get-tokens-for-card-shape($shape) {
+  @return (
+      (mdc, elevated-card): (container-shape: $shape),
+      (mdc, outline-card): (container-shape: $shape),
+  );
+}
+
+/// Gets tokens for setting the card's color.
+/// @param {String} $shape The card's shape.
+/// @return {Map} A map of tokens for setting the card's shape.
+@function _get-tokens-for-card-color($color) {
+  @return (
+      (mdc, elevated-card): (container-color: $color),
+      (mdc, outline-card): (container-color: $color),
+  );
+}
+
+/// Gets a map of card token values that are derived from the theme type.
+/// @param {'light' | 'dark'} $theme-type The type of theme.
+/// @return {Map} A map of card token values derived from the given theme type.
+@function _get-tokens-for-theme-type($theme-type) {
+  $is-dark: $theme-type == 'dark';
+  $foreground: if($is-dark, white, black);
+  $card-color: if($is-dark, mat.get-color-from-palette(mat.$gray-palette, 800), white);
+  $outline-color: color.change($foreground, $alpha: 0.12);
+  $subtitle-color: if($is-dark, rgba(white, 0.7), rgba(black, 0.54));
+
+  @return (
+    (mdc, elevated-card): (
+      container-color: $card-color,
+    ),
+    (mdc, outlined-card): (
+      container-color: $card-color,
+      outline-color: $outline-color,
+    ),
+    (mat, card): (
+      subtitle-text-color: $subtitle-color,
+    ),
+  );
+}
+
+/// Resolvers for mat-card customizations.
+$_customization-resolvers: mat.private-merge-all(
+  token-resolution.alias((
+    elevation: container-elevation,
+    shadow-color: container-shadow-color,
+  ), (mdc, elevated-card)),
+  token-resolution.forward((
+    outline-width,
+    outline-color
+  ), (mdc, outlined-card)),
+  token-resolution.alias((
+    title-font: title-text-font,
+    title-line-height: title-text-line-height,
+    title-font-size: title-text-size,
+    title-letter-spacing: title-text-tracking,
+    title-font-weight: title-text-weight,
+    subtitle-font: subtitle-text-font,
+    subtitle-line-height: subtitle-text-line-height,
+    subtitle-font-size: subtitle-text-size,
+    subtitle-letter-spacing: subtitle-text-tracking,
+    subtitle-font-weight: subtitle-text-weight,
+    subtitle-color: subtitle-text-color
+  ), (mat, card)),
+  (
+    background-color: meta.get-function(_get-tokens-for-card-color),
+    border-radius: meta.get-function(_get-tokens-for-card-shape),
+    theme-type: meta.get-function(_get-tokens-for-theme-type),
+  )
+);
+
+/// Configure the mat-card's theme.
+/// @param {Map} $customizations [()] A map of custom values to use when theming mat-card.
+@function card($customizations: ()) {
+  @return (
+    id: 'mat.card',
+    customizations: token-resolution.resolve-customized-tokens(
+        'mat.card', $_customization-resolvers, $customizations),
+    deps: (),
+  );
+}

src/material-experimental/theming/_checkbox.scss

@@ -0,0 +1,109 @@
+@use 'sass:color';
+@use 'sass:map';
+@use 'sass:meta';
+@use '@angular/material' as mat;
+@use '@material/theme/theme-color' as mdc-theme-color;
+@use './token-resolution';
+
+// TODO(mmalerba): This should live under material/checkbox when moving out of experimental.
+
+// Duplicated from core/tokens/m2/mdc/checkbox
+// TODO(mmalerba): Delete duplicated code when this is moved out of experimental.
+@function _contrast-tone($value, $light-color: '#fff', $dark-color: '#000') {
+  @if ($value == 'dark' or $value == 'light' or type-of($value) == 'color') {
+    @return if(mdc-theme-color.contrast-tone($value) == 'dark', $dark-color, $light-color);
+  }
+  @return false
+}
+
+/// Gets a map of checkbox token values that are derived from the given palette.
+/// @param {Map} $palette An Angular Material palette object.
+/// @return {Map} A map of checkbox token values derived from the given palette.
+@function _get-tokens-for-color-palette($palette) {
+  $palette-default-color: mat.get-color-from-palette($palette);
+  $checkmark-color: _contrast-tone($palette-default-color);
+
+  @return (
+    (mdc, checkbox): (
+      selected-checkmark-color: $checkmark-color,
+      selected-focus-icon-color: $palette-default-color,
+      selected-hover-icon-color: $palette-default-color,
+      selected-icon-color: $palette-default-color,
+      selected-pressed-icon-color: $palette-default-color,
+      selected-focus-state-layer-color: $palette-default-color,
+      selected-hover-state-layer-color: $palette-default-color,
+      selected-pressed-state-layer-color: $palette-default-color,
+    )
+  );
+}
+
+/// Gets a map of checkbox token values that are derived from the theme type.
+/// @param {'light' | 'dark'} $theme-type The type of theme.
+/// @return {Map} A map of checkbox token values derived from the given theme type.
+@function _get-tokens-for-theme-type($theme-type) {
+  $is-dark: $theme-type == dark;
+  $foreground: if($is-dark, white, black);
+  $disabled-color: color.change($foreground, $alpha: 0.38);
+  $border-color: color.change($foreground, $alpha: 0.54);
+  $active-border-color: mat.get-color-from-palette(mat.$gray-palette, if($is-dark, 200, 900));
+
+  @return (
+    (mdc, checkbox): (
+      disabled-selected-icon-color: $disabled-color,
+      disabled-unselected-icon-color: $disabled-color,
+      unselected-focus-icon-color: $active-border-color,
+      unselected-hover-icon-color: $active-border-color,
+      unselected-icon-color: $border-color,
+      unselected-pressed-icon-color: $border-color,
+      unselected-focus-state-layer-color: $foreground,
+      unselected-hover-state-layer-color: $foreground,
+      unselected-pressed-state-layer-color: $foreground,
+    )
+  );
+}
+
+/// Resolvers for mat-checkbox customizations.
+$_customization-resolvers: map.merge(
+    token-resolution.alias((
+      checkmark-color: selected-checkmark-color,
+      disabled-checkmark-color: disabled-selected-checkmark-color,
+      selected-focus-ring-opacity: selected-focus-state-layer-opacity,
+      selected-hover-ring-opacity: selected-hover-state-layer-opacity,
+      selected-pressed-ring-opacity: selected-pressed-state-layer-opacity,
+      unselected-focus-ring-opacity: unselected-focus-state-layer-opacity,
+      unselected-hover-ring-opacity: unselected-hover-state-layer-opacity,
+      unselected-pressed-ring-opacity: unselected-pressed-state-layer-opacity,
+      disabled-selected-box-color: disabled-selected-icon-color,
+      disabled-unselected-box-color: disabled-unselected-icon-color,
+      selected-focus-box-color: selected-focus-icon-color,
+      selected-hover-box-color: selected-hover-icon-color,
+      selected-icon-color: selected-box-color,
+      selected-pressed-box-color: selected-pressed-icon-color,
+      unselected-focus-box-color: unselected-focus-icon-color,
+      unselected-hover-box-color: unselected-hover-icon-color,
+      unselected-box-color: unselected-icon-color,
+      unselected-pressed-box-color: unselected-pressed-icon-color,
+      selected-focus-ring-color: selected-focus-state-layer-color,
+      selected-hover-ring-color: selected-hover-state-layer-color,
+      selected-pressed-ring-color: selected-pressed-state-layer-color,
+      unselected-focus-ring-color: unselected-focus-state-layer-color,
+      unselected-hover-ring-color: unselected-hover-state-layer-color,
+      unselected-pressed-ring-color: unselected-pressed-state-layer-color,
+      ripple-size: state-layer-size,
+    ), (mdc, checkbox)),
+    (
+      color-palette: meta.get-function(_get-tokens-for-color-palette),
+      theme-type: meta.get-function(_get-tokens-for-theme-type),
+    )
+);
+
+/// Configure the mat-checkbox's theme.
+/// @param {Map} $customizations [()] A map of custom values to use when theming mat-checkbox.
+@function checkbox($customizations: ()) {
+  @return (
+    id: 'mat.checkbox',
+    customizations: token-resolution.resolve-customized-tokens(
+        'mat.checkbox', $_customization-resolvers, $customizations),
+    deps: (),
+  );
+}

src/material-experimental/theming/_theming.scss

@@ -112,23 +112,3 @@ $_error-on-missing-dep: false;
 @mixin retheme($components) {
   @include _theme((), $components);
 }
-
-/// Configure the mat-card's theme.
-/// @param {Map} $customizations [()] A map of custom token values to use when theming mat-card.
-@function card($customizations: ()) {
-  @return (
-    id: 'mat.card',
-    customizations: $customizations,
-    deps: (),
-  );
-}
-
-/// Configure the mat-checkbox's theme.
-/// @param {Map} $customizations [()] A map of custom token values to use when theming mat-checkbox.
-@function checkbox($customizations: ()) {
-  @return (
-    id: 'mat.checkbox',
-    customizations: $customizations,
-    deps: (),
-  );
-}

src/material-experimental/theming/_token-resolution.scss

@@ -0,0 +1,86 @@
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+
+/// Creates a map of short token names to fully qualified token name under the given namespace.
+/// @param {List} $tokens A list of tokens to forward under the given namespace.
+/// @param {List} $namespace The namespace to use for the forwarded tokens.
+/// @return {Map} A map of the short token name to pairs of (namespace, token-name) representing the
+///     fully-qualified name
+/// @example
+///     forward((token1, token2), (mat, my-comp))
+///     => (
+///       token1: ((mat, my-comp), token1),
+///       token2: ((mat, my-comp), token1)
+///     )
+@function forward($tokens, $namespace) {
+  $result: ();
+  @each $token in $tokens {
+    $result: map.set($result, $token, ($namespace, $token));
+  }
+  @return $result;
+}
+
+// Creates a map of token alias names to fully qualified canonical names under the given namespace.
+/// @param {Map} $tokens A map of aliases to canonical short names for tokens under the given
+///     namespace.
+/// @param {List} $namespace The namespace to use for the canonical tokens.
+/// @return A map of the token alias name to pairs of (namespace, token-name) representing the
+///     fully-qualified canonical name of the token.
+/// @example
+///     alias((alias1: canonical1, alias2: canonical2), (mat, my-comp))
+///     => (
+///       alias1: ((mat, my-comp), canonical1),
+///       alias2: ((mat, my-comp), canonical2)
+///     )
+@function alias($tokens, $namespace) {
+  $result: ();
+  @each $from, $to in $tokens {
+    $result: map.set($result, $from, ($namespace, $to));
+  }
+  @return $result;
+}
+
+/// Gets the full set of customized tokens from a component configuration's customization map.
+/// @param {String} $component-id The id of the component whose customizations are being resolved.
+///     Used for error logging purposes.
+/// @param {Map} $customization-resolvers A map of resolvers that map customization keys to
+///     fully-qualified token names or functions to generate fully-qualified token names.
+/// @param {Map} $customizations A map of values for customization keys
+/// @return {Map} A map of fully-qualified token values
+/// @example
+///     resolve-customized-tokens('mat.checkbox',
+///       forward(my-color, my-size, (mat, my-comp)),
+///       (my-color: red, my-size: 100px)
+///     )
+///     => (
+///       (mat, my-comp): (
+///         my-color: red,
+///         my-size: 100px
+///       )
+///     )
+@function resolve-customized-tokens($component-id, $customization-resolvers, $customizations) {
+  $result: ();
+
+  @each $customization, $value in $customizations {
+    $resolver: map.get($customization-resolvers, $customization);
+    @if not $resolver {
+      @error 'Unrecognized customization for #{$component-id}: #{$customization}';
+    }
+
+    $resolver-type: meta.type-of($resolver);
+    @if $resolver-type == 'list' {
+      // If the resolver is a list, it represents the token namespace and name.
+      $key-and-value: list.append($resolver, $value);
+      $result: map.deep-merge($result, map.set((), $key-and-value...));
+    } @else if $resolver-type == 'function' {
+      // If the resolver is a function, it should take a value and return a token map.
+      $result: map.deep-merge($result, meta.call($resolver, $value))
+    } @else {
+      // Anything else is unexpected.
+      @error 'Invalid customization resolver for `#{$customization}` on #{$component-id}';
+    }
+  }
+
+  @return $result;
+}

src/material/card/_card-theme.scss

@@ -79,11 +79,8 @@
 }
 
 @mixin theme-from-tokens($tokens) {
-  // Add values for card tokens.
-  .mat-mdc-card {
-    @include mdc-elevated-card-theme.theme(map.get($tokens, tokens-mdc-elevated-card.$prefix));
-    @include mdc-outlined-card-theme.theme(map.get($tokens, tokens-mdc-outlined-card.$prefix));
-    @include token-utils.create-token-values(
-        tokens-mat-card.$prefix, map.get($tokens, tokens-mat-card.$prefix));
-  }
+  @include mdc-elevated-card-theme.theme(map.get($tokens, tokens-mdc-elevated-card.$prefix));
+  @include mdc-outlined-card-theme.theme(map.get($tokens, tokens-mdc-outlined-card.$prefix));
+  @include token-utils.create-token-values(
+      tokens-mat-card.$prefix, map.get($tokens, tokens-mat-card.$prefix));
 }

src/material/checkbox/_checkbox-theme.scss

@@ -92,8 +92,5 @@
 @mixin theme-from-tokens($tokens) {
   // TODO(mmalerba): Some of the theme styles above are not represented in terms of tokens,
   //   so this mixin is currently incomplete.
-
-  .mat-mdc-checkbox {
-    @include mdc-checkbox-theme.theme(map.get($tokens, tokens-mdc-checkbox.$prefix));
-  }
+  @include mdc-checkbox-theme.theme(map.get($tokens, tokens-mdc-checkbox.$prefix));
 }

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

@@ -14,6 +14,18 @@
   }
 }
 
+/// A version of the standard `map.merge` function that takes a variable number of arguments.
+/// Each argument is merged into the final result from left to right.
+/// @param {List} $maps The maps to combine with map.merge
+/// @return {Map} The combined result of successively calling map.merge with each parameter.
+@function merge-all($maps...) {
+  $result: ();
+  @each $map in $maps {
+    $result: map.merge($result, $map);
+  }
+  @return $result;
+}
+
 /// A version of the standard `map.deep-merge` function that takes a variable number of arguments.
 /// Each argument is deep-merged into the final result from left to right.
 /// @param {List} $maps The maps to combine with map.deep-merge