feat(material-experimental/theming): Support defining M3 theme objects

Adds support for defining a new type of theme object with more
explicitly private internals. This new style theme object will be used
for M3 themes.

Author: mmalerba

.ng-dev/commit-message.mts

@@ -41,6 +41,7 @@ export const commitMessage: CommitMessageConfig = {
     'google-maps',
     'material-experimental/column-resize',
     'material-experimental/theming-next',
+    'material-experimental/theming',
     'material-experimental/menubar',
     'material-experimental/popover-edit',
     'material-experimental/selection',

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

@@ -23,26 +23,9 @@ dev-app {
 
 @include mat.core();
 
-$theme: mat.define-light-theme((
-  color: (
-    primary: mat.define-palette(mat.$indigo-palette),
-    accent: mat.define-palette(mat.$pink-palette),
-  ),
-  typography: mat.define-typography-config(),
-  density: 0,
-));
+$m3-theme: matx.define-theme();
 
-// Apply all tokens (derived from `$theme`) to the `html` element. This ensures that all components
-// on the page will inherit these tokens.
-html {
-  @include matx.theme(
-    matx.token-defaults(matx.get-m3-tokens()),
-    matx.card(),
-    matx.checkbox(),
-  );
-}
+@debug $m3-theme;
 
-// TODO(mmalerba): Figure out a consistent solution for handling dark themes & color palette
-//  variants across M2 & M3 (likely by implementing `matx.system-colors`). As a reference, see the
-//  prior version of this file that showed a possible way to accomplish this in M2:
-//  https://github.com/angular/components/blob/5f5c5160dc20331619fc6729aa2ad78ac84af1c3/src/dev-app/theme-token-api.scss
+// @include mat.checkbox-theme($m3-theme);
+// @include mat.card-theme($m3-theme);

src/material-experimental/BUILD.bazel

@@ -18,16 +18,19 @@ ts_library(
 )
 
 sass_library(
-    name = "theming_next_scss_lib",
+    name = "theming_scss_lib",
     srcs = MATERIAL_EXPERIMENTAL_SCSS_LIBS + [
+        "//src/material-experimental/theming:theming_scss_lib",
         "//src/material-experimental/theming-next:theming_next_scss_lib",
     ],
 )
 
 sass_library(
     name = "sass_lib",
     srcs = ["_index.scss"],
-    deps = [":theming_next_scss_lib"],
+    deps = [
+        ":theming_scss_lib",
+    ],
 )
 
 # Generate the material-experimental `package.json` by adding all MDC dependencies

src/material-experimental/_index.scss

@@ -5,5 +5,8 @@
   popover-edit-typography, popover-edit-density, popover-edit-theme;
 
 // Token-based theming API
+@forward './theming/definition' show define-theme, define-colors, define-typography, define-density;
+@forward './theming/m3-palettes' as m3-* show $m3-red-palette, $m3-orange-palette,
+$m3-yellow-palette, $m3-green-palette, $m3-blue-palette, $m3-indigo-palette, $m3-violet-palette;
 
 // Additional public APIs for individual components

src/material-experimental/theming/BUILD.bazel

@@ -0,0 +1,9 @@
+load("//tools:defaults.bzl", "sass_library")
+
+package(default_visibility = ["//visibility:public"])
+
+sass_library(
+    name = "theming_scss_lib",
+    srcs = glob(["**/_*.scss"]),
+    deps = ["//src/material:sass_lib"],
+)

src/material-experimental/theming/_config-validation.scss

@@ -0,0 +1,101 @@
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+
+/// Validates that the object's type matches any of the expected types.
+/// @param {any} $obj The object to test
+/// @param {List} $types The expected types
+/// @return {String} null if no error, else the unexpected type.
+@function validate-type($obj, $types...) {
+  $result: meta.type-of($obj);
+  // A zero-length list is the same as a zero-length map.
+  @if ($result == list and list.index($types, map) and list.length($obj) == 0) {
+    @return null;
+  }
+  @return if(list.index($types, $result), null, $result);
+}
+
+/// Validates that a map's keys contains only keys from the allowed keys list.
+/// @param {Map} $map The map to test
+/// @param {List} $keys The allowed map keys
+/// @return {List} null if no error, else the list of unexpected keys.
+@function validate-only-keys($map, $keys...) {
+  @each $key in $keys {
+    $map: map.remove($map, $key);
+  }
+  $invalid: map.keys($map);
+  @return if(list.length($invalid) > 0, $invalid, null);
+}
+
+/// Validates a theme config.
+/// @param {Map} $config The config to test.
+/// @return {List} null if no error, else the error message
+@function validate-theme-config($config) {
+  $err: validate-type($config, 'map', 'null');
+  @if $err {
+    @return (#{'$config'} #{'should be a color configuraiton object. Got:'} $config);
+  }
+  $err: validate-only-keys($config or (), color, typography, density);
+  @if $err {
+    @return (#{'$config'} #{'has unexpected properties:'} $err);
+  }
+  $err: validate-color-config(map.get($config, color));
+  @if $err {
+    @return list.set-nth($err, 1, #{'#{list.nth($err, 1)}.color'});
+  }
+  $err: validate-typography-config(map.get($config, typography));
+  @if $err {
+    @return list.set-nth($err, 1, #{'#{list.nth($err, 1)}.typography'});
+  }
+  $err: validate-density-config(map.get($config, density));
+  @if $err {
+    @return list.set-nth($err, 1, #{'#{list.nth($err, 1)}.density'});
+  }
+  @return null;
+}
+
+/// Validates a theme color config.
+/// @param {Map} $config The config to test.
+/// @return {List} null if no error, else the error message
+@function validate-color-config($config) {
+  $err: validate-type($config, 'map', 'null');
+  @if $err {
+    @return (#{'$config'} #{'should be a color configuraiton object. Got:'} $config);
+  }
+  $err: validate-only-keys($config or (), theme-type, primary, secondary, tertiary);
+  @if $err {
+    @return (#{'$config'} #{'has unexpected properties:'} $err);
+  }
+  @return null;
+}
+
+/// Validates a theme typography config.
+/// @param {Map} $config The config to test.
+/// @return {List} null if no error, else the error message
+@function validate-typography-config($config) {
+  $err: validate-type($config, 'map', 'null');
+  @if $err {
+    @return (#{'$config'} #{'should be a typography configuraiton object. Got:'} $config);
+  }
+  $err: validate-only-keys($config or (),
+      brand-family, plain-family, bold-weight, medium-weight, regular-weight);
+  @if $err {
+    @return (#{'$config'} #{'has unexpected properties:'} $err);
+  }
+  @return null;
+}
+
+/// Validates a theme density config.
+/// @param {Map} $config The config to test.
+/// @return {List} null if no error, else the error message
+@function validate-density-config($config) {
+  $err: validate-type($config, 'map', 'null');
+  @if $err {
+    @return (#{'$config'} #{'should be a density configuraiton object. Got:'} $config);
+  }
+  $err: validate-only-keys($config or (), scale);
+  @if $err {
+    @return (#{'$config'} #{'has unexpected properties:'} $err);
+  }
+  @return null;
+}

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

@@ -0,0 +1,31 @@
+@use 'sass:map';
+@use '@angular/material' as mat;
+
+/// Sets all of the standard typography tokens for the given token base name to the given typography
+/// level.
+/// @param {Map} $systems The MDC system tokens
+/// @param {String} $base-name The token base name to get the typography tokens for
+/// @param {String} $typography-level The typography level to base the token values on
+/// @return {Map} A map containing the typography tokens for the given base token name
+@function _generate-typography-tokens($systems, $base-name, $typography-level) {
+  $result: ();
+  @each $prop in (font, line-height, size, tracking, weight) {
+    $result: map.set($result, #{$base-name}-#{$prop},
+        map.get($systems, md-sys-typescale, #{$typography-level}-#{$prop}));
+  }
+  @return $result;
+}
+
+/// Generates custom tokens for the mat-card.
+/// @param {Map} $systems The MDC system tokens
+/// @param {Boolean} $exclude-hardcoded Whether to exclude hardcoded token values
+/// @return {Map} A set of custom tokens for the mat-card
+@function card($systems, $exclude-hardcoded) {
+  @return mat.private-merge-all(
+      _generate-typography-tokens($systems, title-text, title-large),
+      _generate-typography-tokens($systems, subtitle-text, title-medium),
+      (
+        subtitle-text-color: map.get($systems, md-ref-color, on-surface)
+      )
+  );
+}

src/material-experimental/theming/_definition.scss

@@ -0,0 +1,97 @@
+// This file contains functions used to define Angular Material theme objects.
+
+@use 'sass:map';
+@use '@angular/material' as mat;
+@use './m3-palettes';
+@use './m3-tokens';
+@use './config-validation';
+
+/// Map key used to store internals of theme config.
+$internals: _mat-theming-internals-do-not-access;
+/// The theme version of generated themes.
+$theme-version: 1;
+
+/// Defines an Angular Material theme object with color, typography, and density settings.
+/// @param {Map} $config The theme configuration
+/// @return {Map} A theme object
+@function define-theme($config: ()) {
+  $err: config-validation.validate-theme-config($config);
+  @if $err {
+    @error $err;
+  }
+  
+  @return mat.private-deep-merge-all(
+      define-colors(map.get($config, color) or ()),
+      define-typography(map.get($config, typography) or ()),
+      define-density(map.get($config, density) or ()),
+      ($internals: (other-tokens: m3-tokens.generate-other-tokens())),
+  );
+}
+
+/// Defines an Angular Material theme object with color settings.
+/// @param {Map} $config The color configuration
+/// @return {Map} A theme object
+@function define-colors($config: ()) {
+  $err: config-validation.validate-color-config($config);
+  @if $err {
+    @error $err;
+  }
+
+  $type: map.get($config, theme-type) or light;
+  $primary: map.get($config, primary) or m3-palettes.$indigo-palette;
+  $secondary: map.get($config, secondary) or $primary;
+  $tertiary: map.get($config, tertiary) or $secondary;
+
+  @return (
+    $internals: (
+      theme-version: $theme-version,
+      theme-type: $type,
+      color-tokens: m3-tokens.generate-color-tokens($type, $primary, $secondary, $tertiary,
+          m3-palettes.$neutral-palette, m3-palettes.$red-palette)
+    )
+  );
+}
+
+/// Defines an Angular Material theme object with typography settings.
+/// @param {Map} $config The typography configuration
+/// @return {Map} A theme object
+@function define-typography($config: ()) {
+  $err: config-validation.validate-typography-config($config);
+  @if $err {
+    @error $err;
+  }
+
+  $plain: map.get($config, plain-family) or Roboto, sans-serif;
+  $brand: map.get($config, brand-family) or $plain;
+  $bold: map.get($config, bold-weight) or 700;
+  $medium: map.get($config, medium-weight) or 500;
+  $regular: map.get($config, regular-weight) or 400;
+
+  @return (
+    $internals: (
+      theme-version: $theme-version,
+      typography-tokens:
+          m3-tokens.generate-typography-tokens($brand, $plain, $bold, $medium, $regular)
+    )
+  );
+}
+
+/// Defines an Angular Material theme object with density settings.
+/// @param {Map} $config The density configuration
+/// @return {Map} A theme object
+@function define-density($config: ()) {
+  $err: config-validation.validate-density-config($config);
+  @if $err {
+    @error $err;
+  }
+
+  $density-scale: map.get($config, scale) or 0;
+
+  @return (
+    $internals: (
+      theme-version: $theme-version,
+      density-scale: $density-scale,
+      density-tokens: m3-tokens.generate-density-tokens($density-scale)
+    )
+  );
+}