@angular/material 16.2.2 → 17.0.0-next.1

package/core/option/_optgroup-theme.scss

@@ -3,46 +3,36 @@
 @use '../style/sass-utils';
 
 @use '../theming/theming';
+@use '../theming/inspection';
 @use '../typography/typography';
 
-@mixin color($config-or-theme) {
-  $config: theming.get-color-config($config-or-theme);
-
+@mixin color($theme) {
   @include sass-utils.current-selector-or-root() {
     @include token-utils.create-token-values(tokens-mat-optgroup.$prefix,
-      tokens-mat-optgroup.get-color-tokens($config));
+      tokens-mat-optgroup.get-color-tokens($theme));
   }
 }
 
-@mixin typography($config-or-theme) {
-  $config: typography.private-typography-to-2018-config(
-      theming.get-typography-config($config-or-theme));
-
+@mixin typography($theme) {
   @include sass-utils.current-selector-or-root() {
     @include token-utils.create-token-values(tokens-mat-optgroup.$prefix,
-      tokens-mat-optgroup.get-typography-tokens($config));
+      tokens-mat-optgroup.get-typography-tokens($theme));
   }
 }
 
-@mixin density($config-or-theme) {
-  $density-scale: theming.get-density-config($config-or-theme);
+@mixin density($theme) {
 }
 
-@mixin theme($theme-or-color-config) {
-  $theme: theming.private-legacy-get-theme($theme-or-color-config);
+@mixin theme($theme) {
   @include theming.private-check-duplicate-theme-styles($theme, 'mat-optgroup') {
-    $color: theming.get-color-config($theme);
-    $density: theming.get-density-config($theme);
-    $typography: theming.get-typography-config($theme);
-
-    @if $color != null {
-      @include color($color);
+    @if inspection.theme-has($theme, color) {
+      @include color($theme);
     }
-    @if $density != null {
-      @include density($density);
+    @if inspection.theme-has($theme, density) {
+      @include density($theme);
     }
-    @if $typography != null {
-      @include typography($typography);
+    @if inspection.theme-has($theme, typography) {
+      @include typography($theme);
     }
   }
 }

package/core/option/_option-theme.scss

@@ -1,62 +1,48 @@
-@use 'sass:map';
 @use '../tokens/m2/mat/option' as tokens-mat-option;
 @use '../tokens/token-utils';
 @use '../style/sass-utils';
 
 @use '../theming/theming';
+@use '../theming/inspection';
 @use '../typography/typography';
-@use '../mdc-helpers/mdc-helpers';
 
-@mixin color($config-or-theme) {
-  $config: theming.get-color-config($config-or-theme);
-
-  @include mdc-helpers.using-mdc-theme($config) {
-    @include sass-utils.current-selector-or-root() {
-      @include token-utils.create-token-values(tokens-mat-option.$prefix,
-        tokens-mat-option.get-color-tokens($config));
-    }
+@mixin color($theme) {
+  @include sass-utils.current-selector-or-root() {
+    @include token-utils.create-token-values(tokens-mat-option.$prefix,
+      tokens-mat-option.get-color-tokens($theme));
+  }
 
-    .mat-accent {
-      @include token-utils.create-token-values(tokens-mat-option.$prefix,
-        tokens-mat-option.private-get-color-palette-color-tokens(map.get($config, accent)));
-    }
+  .mat-accent {
+    @include token-utils.create-token-values(tokens-mat-option.$prefix,
+      tokens-mat-option.get-color-tokens($theme, accent));
+  }
 
-    .mat-warn {
-      @include token-utils.create-token-values(tokens-mat-option.$prefix,
-        tokens-mat-option.private-get-color-palette-color-tokens(map.get($config, warn)));
-    }
+  .mat-warn {
+    @include token-utils.create-token-values(tokens-mat-option.$prefix,
+      tokens-mat-option.get-color-tokens($theme, warn));
   }
 }
 
-@mixin typography($config-or-theme) {
-  $config: typography.private-typography-to-2018-config(
-      theming.get-typography-config($config-or-theme));
-
+@mixin typography($theme) {
   @include sass-utils.current-selector-or-root() {
     @include token-utils.create-token-values(tokens-mat-option.$prefix,
-      tokens-mat-option.get-typography-tokens($config));
+      tokens-mat-option.get-typography-tokens($theme));
   }
 }
 
-@mixin density($config-or-theme) {
-  $density-scale: theming.get-density-config($config-or-theme);
+@mixin density($theme) {
 }
 
-@mixin theme($theme-or-color-config) {
-  $theme: theming.private-legacy-get-theme($theme-or-color-config);
+@mixin theme($theme) {
   @include theming.private-check-duplicate-theme-styles($theme, 'mat-option') {
-    $color: theming.get-color-config($theme);
-    $density: theming.get-density-config($theme);
-    $typography: theming.get-typography-config($theme);
-
-    @if $color != null {
-      @include color($color);
+    @if inspection.theme-has($theme, color) {
+      @include color($theme);
     }
-    @if $density != null {
-      @include density($density);
+    @if inspection.theme-has($theme, density) {
+      @include density($theme);
     }
-    @if $typography != null {
-      @include typography($typography);
+    @if inspection.theme-has($theme, typography) {
+      @include typography($theme);
     }
   }
 }

package/core/ripple/_ripple-theme.scss

@@ -1,12 +1,10 @@
-@use 'sass:map';
 @use 'sass:meta';
 @use '../theming/theming';
+@use '../theming/inspection';
 
 // Colors for the ripple elements.
-@mixin color($config-or-theme) {
-  $config: theming.get-color-config($config-or-theme);
-  $foreground: map.get($config, foreground);
-  $foreground-base: map.get($foreground, base);
+@mixin color($theme) {
+  $foreground-base: inspection.get-theme-color($theme, foreground, base);
   $color-opacity: 0.1;
 
   .mat-ripple-element {
@@ -22,12 +20,10 @@
   }
 }
 
-@mixin theme($theme-or-color-config) {
-  $theme: theming.private-legacy-get-theme($theme-or-color-config);
+@mixin theme($theme) {
   @include theming.private-check-duplicate-theme-styles($theme, 'mat-ripple') {
-    $color: theming.get-color-config($theme);
-    @if $color != null {
-      @include color($color);
+    @if inspection.theme-has($theme, color) {
+      @include color($theme);
     }
   }
 }

package/core/selection/pseudo-checkbox/_pseudo-checkbox-theme.scss

@@ -1,5 +1,5 @@
-@use 'sass:map';
 @use '../../theming/theming';
+@use '../../theming/inspection';
 
 @mixin _psuedo-checkbox-styles-with-color($text-color, $background) {
   .mat-pseudo-checkbox-checked,
@@ -19,15 +19,13 @@
   }
 }
 
-@mixin color($config-or-theme) {
-  $config: theming.get-color-config($config-or-theme);
-  $is-dark-theme: map.get($config, is-dark);
-
-  $primary: theming.get-color-from-palette(map.get($config, primary));
-  $accent: theming.get-color-from-palette(map.get($config, accent));
-  $warn: theming.get-color-from-palette(map.get($config, warn));
-  $background: theming.get-color-from-palette(map.get($config, background), background);
-  $secondary-text: theming.get-color-from-palette(map.get($config, foreground), secondary-text);
+@mixin color($theme) {
+  $is-dark-theme: inspection.get-theme-type($theme) == dark;
+  $primary: inspection.get-theme-color($theme, primary);
+  $accent: inspection.get-theme-color($theme, accent);
+  $warn: inspection.get-theme-color($theme, warn);
+  $background: inspection.get-theme-color($theme, background, background);
+  $secondary-text: inspection.get-theme-color($theme, foreground, secondary-text);
 
   // NOTE(traviskaufman): While the spec calls for translucent blacks/whites for disabled colors,
   // this does not work well with elements layered on top of one another. To get around this we
@@ -74,25 +72,20 @@
   }
 }
 
-@mixin typography($config-or-theme) {}
+@mixin typography($theme) {}
 
-@mixin _density($config-or-theme) {}
+@mixin _density($theme) {}
 
-@mixin theme($theme-or-color-config) {
-  $theme: theming.private-legacy-get-theme($theme-or-color-config);
+@mixin theme($theme) {
   @include theming.private-check-duplicate-theme-styles($theme, 'mat-pseudo-checkbox') {
-    $color: theming.get-color-config($theme);
-    $density: theming.get-density-config($theme);
-    $typography: theming.get-typography-config($theme);
-
-    @if $color != null {
-      @include color($color);
+    @if inspection.theme-has($theme, color) {
+      @include color($theme);
     }
-    @if $density != null {
-      @include _density($density);
+    @if inspection.theme-has($theme, density) {
+      @include _density($theme);
     }
-    @if $typography != null {
-      @include typography($typography);
+    @if inspection.theme-has($theme, typography) {
+      @include typography($theme);
     }
   }
 }

package/core/style/_private.scss

@@ -1,9 +1,9 @@
 @use 'sass:map';
 @use './elevation';
+@use '../theming/inspection';
 
-@mixin private-theme-elevation($zValue, $config) {
-  $foreground: map.get($config, foreground);
-  $elevation-color: map.get($foreground, elevation);
+@mixin private-theme-elevation($zValue, $theme) {
+  $elevation-color: inspection.get-theme-color($theme, foreground, elevation);
   $elevation-color-or-default: if($elevation-color == null, elevation.$color, $elevation-color);
 
   @include elevation.elevation($zValue, $elevation-color-or-default);

package/core/style/_sass-utils.scss

@@ -1,3 +1,4 @@
+@use 'sass:color';
 @use 'sass:map';
 @use 'sass:meta';
 
@@ -47,3 +48,9 @@
 @function coerce-to-list($value) {
   @return if(meta.type-of($value) != 'list', ($value,), $value);
 }
+
+/// A version of the Sass `color.change` function that is safe ot use with CSS variables.
+@function safe-color-change($color, $args...) {
+  $args: meta.keywords($args);
+  @return if(meta.type-of($color) == 'color', color.change($color, $args...), $color);
+}

package/core/style/_validation.scss

@@ -0,0 +1,43 @@
+@use 'sass:list';
+@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 list contains only values from the allowed list of values.
+/// @param {List} $list The list to test
+/// @param {List} $allowed The allowed values
+/// @return {List} null if no error, else the list of non-allowed values.
+@function validate-allowed-values($list, $allowed...) {
+  $invalid: ();
+  @each $element in $list {
+    @if not list.index($allowed, $element) {
+      $invalid: list.append($invalid, $element);
+    }
+  }
+  @return if(list.length($invalid) > 0, $invalid, null);
+}
+
+/// Validates that a list contains all values from the required list of values.
+/// @param {List} $list The list to test
+/// @param {List} $required The required values
+/// @return {List} null if no error, else the list of missing values.
+@function validate-required-values($list, $required...) {
+  $invalid: ();
+  @each $element in $required {
+    @if not list.index($list, $element) {
+      $invalid: list.append($invalid, $element);
+    }
+  }
+  @return if(list.length($invalid) > 0, $invalid, null);
+}

package/core/theming/_inspection.scss

@@ -0,0 +1,256 @@
+@use 'sass:list';
+@use 'sass:map';
+@use '../style/validation';
+@use './m2-inspection';
+
+$_internals: _mat-theming-internals-do-not-access;
+
+$_m3-typescales: (
+  display-large,
+  display-medium,
+  display-small,
+  headline-large,
+  headline-medium,
+  headline-small,
+  title-large,
+  title-medium,
+  title-small,
+  label-large,
+  label-medium,
+  label-small,
+  body-large,
+  body-medium,
+  body-small,
+);
+
+$_typography-properties: (font, font-family, line-height, font-size, letter-spacing, font-weight);
+
+/// Validates that the given value is a versioned theme object.
+/// @param {Any} $theme The theme object to validate.
+/// @return {Boolean|Null} true if the theme has errors, else null.
+@function _validate-theme-object($theme) {
+  $err: validation.validate-type($theme, 'map') or
+        map.get($theme, $_internals, theme-version) == null;
+  @return if($err, true, null);
+}
+
+/// Gets the version number of a theme object. A theme that is not a valid versioned theme object is
+/// considered to be version 0.
+/// @param {Map} $theme The theme to check the version of
+/// @return {Number} The version number of the theme (0 if unknown).
+@function get-theme-version($theme) {
+  $err: _validate-theme-object($theme);
+  @return if($err, 0, map.get($theme, $_internals, theme-version) or 0);
+}
+
+/// Gets the type of theme represented by a theme object (light or dark).
+/// @param {Map} $theme The theme
+/// @return {String} The type of theme (either `light` or `dark`).
+@function get-theme-type($theme) {
+  $version: get-theme-version($theme);
+  @if $version == 0 {
+    @return m2-inspection.get-theme-type($theme);
+  }
+  @else if $version == 1 {
+    @if not theme-has($theme, color) {
+      @error 'Color information is not available on this theme.';
+    }
+    @return map.get($theme, $_internals, theme-type) or light;
+  }
+  @else {
+    @error #{'Unrecognized theme version:'} $version;
+  }
+}
+
+/// Gets a color from a theme object. This function can take 2 or 3 arguments. If 2 arguments are
+/// passed, the second argument is treated as the name of a color role. If 3 arguments are passed,
+/// the second argument is treated as the name of a color palette (primary, secondary, etc.) and the
+/// third is treated as the palette hue (10, 50, etc.)
+/// @param {Map} $theme The theme
+/// @param {String} $color-role-or-palette-name The name of the color role to get, or the name of a
+///   color palette.
+/// @param {Number} $hue The palette hue to get (passing this argument means the second argument is
+///   interpreted as a palette name).
+/// @return {Color} The requested theme color.
+@function get-theme-color($theme, $args...) {
+  $version: get-theme-version($theme);
+  $args-count: list.length($args);
+  @if $args-count != 1 and $args-count != 2 {
+    @error #{'Expected 2 or 3 arguments. Got:'} $args-count + 1;
+  }
+
+  @if $version == 0 {
+    @return m2-inspection.get-theme-color($theme, $args...);
+  }
+  @else if $version == 1 {
+    @if $args-count == 1 {
+      @return _get-theme-role-color($theme, $args...);
+    }
+    @else if $args-count == 2 {
+      @return _get-theme-palette-color($theme, $args...);
+    }
+  }
+  @else {
+    @error #{'Unrecognized theme version:'} $version;
+  }
+}
+
+/// Gets a role color from a theme object.
+/// @param {Map} $theme The theme
+/// @param {String} $color-role-name The name of the color role to get.
+/// @return {Color} The requested role color.
+@function _get-theme-role-color($theme, $color-role-name) {
+  $err: _validate-theme-object($theme);
+  @if $err {
+    // TODO(mmalerba): implement for old style theme objects.
+    @error #{'get-theme-color does not support legacy theme objects.'};
+  }
+  @if not theme-has($theme, color) {
+    @error 'Color information is not available on this theme.';
+  }
+  $color-roles: map.get($theme, $_internals, color-tokens, (mdc, theme));
+  $result: map.get($color-roles, $color-role-name);
+  @if not $result {
+    @error #{'Valid color roles are: #{map.keys($color-roles)}. Got:'} $color-role-name;
+  }
+  @return $result;
+}
+
+/// Gets a palette color from a theme object.
+/// @param {Map} $theme The theme
+/// @param {String} $palette-name The name of the palette to get the color from.
+/// @param {Number} $hue The hue to read from the palette.
+/// @return {Color} The requested palette color.
+@function _get-theme-palette-color($theme, $palette-name, $hue) {
+  $err: _validate-theme-object($theme);
+  @if $err {
+    // TODO(mmalerba): implement for old style theme objects.
+    @error #{'get-theme-color does not support legacy theme objects.'};
+  }
+  @if not theme-has($theme, color) {
+    @error 'Color information is not available on this theme.';
+  }
+  $palettes: map.get($theme, $_internals, palettes);
+  $palette: map.get($palettes, $palette-name);
+  @if not $palette {
+    $supported-palettes: map.keys($palettes);
+    @error #{'Valid palettes are: #{$supported-palettes}. Got:'} $palette-name;
+  }
+  $result: map.get($palette, $hue);
+  @if not $result {
+    $supported-hues: map.keys($palette);
+    @error #{'Valid hues for'} $palette-name #{'are: #{$supported-hues}. Got:'} $hue;
+  }
+  @return $result;
+}
+
+/// Gets a typography value from a theme object.
+/// @param {Map} $theme The theme
+/// @param {String} $typescale The typescale name.
+/// @param {String} $property The CSS font property to get
+///   (font, font-family, font-size, font-weight, line-height, or letter-spacing).
+/// @return {*} The value of the requested font property.
+@function get-theme-typography($theme, $typescale, $property: font) {
+  $version: get-theme-version($theme);
+  @if $version == 0 {
+    @return m2-inspection.get-theme-typography($theme, $typescale, $property);
+  }
+  @else if $version == 1 {
+    @if not theme-has($theme, typography) {
+      @error 'Typography information is not available on this theme.';
+    }
+    @if not list.index($_m3-typescales, $typescale) {
+      @error #{'Valid typescales are: #{$_m3-typescales}. Got:'} $typescale;
+    }
+    @if not list.index($_typography-properties, $property) {
+      @error #{'Valid typography properties are: #{$_typography-properties}. Got:'} $property;
+    }
+    $property-key: map.get((
+      font: '',
+      font-family: '-font',
+      line-height: '-line-height',
+      font-size: '-size',
+      letter-spacing: '-tracking',
+      font-weight: '-weight'
+    ), $property);
+    $token-name: '#{$typescale}#{$property-key}';
+    @return map.get($theme, $_internals, typography-tokens, (mdc, typography), $token-name);
+  }
+  @else {
+    @error #{'Unrecognized theme version:'} $version;
+  }
+}
+
+/// Gets the density scale from a theme object.
+/// @param {Map} $theme The theme
+/// @return {Number} The density scale.
+@function get-theme-density($theme) {
+  $version: get-theme-version($theme);
+  @if $version == 0 {
+    @return m2-inspection.get-theme-density($theme);
+  }
+  @else if $version == 1 {
+    @if not theme-has($theme, density) {
+      @error 'Density information is not available on this theme.';
+    }
+    @return map.get($theme, $_internals, density-scale);
+  }
+  @else {
+    @error #{'Unrecognized theme version:'} $version;
+  }
+}
+
+/// Checks whether the theme has information about given theming system.
+/// @param {Map} $theme The theme
+/// @param {String} $system The system to check
+/// @param {Boolean} Whether the theme has information about the system.
+@function theme-has($theme, $system) {
+  $version: get-theme-version($theme);
+  @if $version == 0 {
+    @return m2-inspection.theme-has($theme, $system);
+  }
+  @else if $version == 1 {
+    @if $system == base {
+      @return map.get($theme, $_internals, base-tokens) != null;
+    }
+    @if $system == color {
+      @return map.get($theme, $_internals, color-tokens) != null and
+        map.get($theme, $_internals, theme-type) != null and
+        map.get($theme, $_internals, palettes) != null;
+    }
+    @if $system == typography {
+      @return map.get($theme, $_internals, typography-tokens) != null;
+    }
+    @if $system == density {
+      @return map.get($theme, $_internals, density-scale) != null;
+    }
+    @error 'Valid systems are: base, color, typography, density. Got:' $system;
+  }
+  @else {
+    @error #{'Unrecognized theme version:'} $version;
+  }
+}
+
+/// Gets the set of tokens from the given theme, limited to those affected by the requested theming
+/// systems.
+/// @param {Map} $theme The theme to get tokens from.
+/// @param {String...} $systems The theming systems to get tokens for. Valid values are: color,
+///   typography, density, base. If no systems are passed, all tokens will be returned.
+/// @return {Map} The requested tokens for the theme.
+@function get-theme-tokens($theme, $systems...) {
+  $systems: if(list.length($systems) == 0, (color, typography, density, base), $systems);
+  $err: _validate-theme-object($theme);
+  @if $err {
+    @error #{'Expected $theme to be an Angular Material theme object. Got:'} $theme;
+  }
+  $err: validation.validate-allowed-values($systems, color, typography, density, base);
+  @if $err {
+    @error #{'Expected $systems to contain valid system names (color, typography, density, or'}
+    #{'base). Got invalid system names:'} $err;
+  }
+  $result: ();
+  @each $system in $systems {
+    $result: map.deep-merge($result, map.get($theme, $_internals, '#{$system}-tokens'));
+  }
+  @return $result;
+}