@angular/material 17.0.0-next.0 → 17.0.0-next.1

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/theming/_inspection.scss

@@ -1,8 +1,7 @@
-// This file contains functions used to inspect Angular Material theme objects.
-
 @use 'sass:list';
 @use 'sass:map';
 @use '../style/validation';
+@use './m2-inspection';
 
 $_internals: _mat-theming-internals-do-not-access;
 
@@ -48,15 +47,19 @@ $_typography-properties: (font, font-family, line-height, font-size, letter-spac
 /// @param {Map} $theme The theme
 /// @return {String} The type of theme (either `light` or `dark`).
 @function get-theme-type($theme) {
-  $err: _validate-theme-object($theme);
-  @if $err {
-    // TODO(mmalerba): implement for old style theme objects.
-    @error #{'get-theme-type does not support legacy theme objects.'};
+  $version: get-theme-version($theme);
+  @if $version == 0 {
+    @return m2-inspection.get-theme-type($theme);
   }
-  @if not theme-has($theme, color) {
-    @error 'Color information is not available on this 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;
   }
-  @return map.get($theme, $_internals, theme-type) or light;
 }
 
 /// Gets a color from a theme object. This function can take 2 or 3 arguments. If 2 arguments are
@@ -70,14 +73,26 @@ $_typography-properties: (font, font-family, line-height, font-size, letter-spac
 ///   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 {
-    @return _get-theme-role-color($theme, $args...);
+  @if $args-count != 1 and $args-count != 2 {
+    @error #{'Expected 2 or 3 arguments. Got:'} $args-count + 1;
   }
-  @else if $args-count == 2 {
-    @return _get-theme-palette-color($theme, $args...);
+
+  @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;
   }
-  @error #{'Expected 2 or 3 arguments. Got:'} $args-count + 1;
 }
 
 /// Gets a role color from a theme object.
@@ -136,45 +151,53 @@ $_typography-properties: (font, font-family, line-height, font-size, letter-spac
 ///   (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) {
-  $err: _validate-theme-object($theme);
-  @if $err {
-    // TODO(mmalerba): implement for old style theme objects.
-    @error #{'get-theme-typography does not support legacy theme objects.'};
-  }
-  @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);
+  $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) {
-  $err: _validate-theme-object($theme);
-  @if $err {
-    // TODO(mmalerba): implement for old style theme objects.
-    @error #{'get-theme-density does not support legacy theme objects.'};
+  $version: get-theme-version($theme);
+  @if $version == 0 {
+    @return m2-inspection.get-theme-density($theme);
   }
-  @if not theme-has($theme, density) {
-    @error 'Density information is not available on this 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;
   }
-  @return map.get($theme, $_internals, density-scale);
 }
 
 /// Checks whether the theme has information about given theming system.
@@ -182,26 +205,30 @@ $_typography-properties: (font, font-family, line-height, font-size, letter-spac
 /// @param {String} $system The system to check
 /// @param {Boolean} Whether the theme has information about the system.
 @function theme-has($theme, $system) {
-  $err: _validate-theme-object($theme);
-  @if $err {
-    // TODO(mmalerba): implement for old style theme objects.
-    @error #{'get-theme-density does not support legacy theme objects.'};
-  }
-  @if $system == base {
-    @return map.get($theme, $_internals, base-tokens) != null;
+  $version: get-theme-version($theme);
+  @if $version == 0 {
+    @return m2-inspection.theme-has($theme, $system);
   }
-  @if $system == color {
-    @return map.get($theme, $_internals, color-tokens) != null and
+  @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;
   }
-  @if $system == typography {
-    @return map.get($theme, $_internals, typography-tokens) != null;
-  }
-  @if $system == density {
-    @return map.get($theme, $_internals, density-scale) != null;
+  @else {
+    @error #{'Unrecognized theme version:'} $version;
   }
-  @error 'Valid systems are: base, color, typography, density. Got:' $system;
 }
 
 /// Gets the set of tokens from the given theme, limited to those affected by the requested theming

package/core/theming/_m2-inspection.scss

@@ -0,0 +1,211 @@
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+@use './theming';
+@use '../typography/property-getters' as typography-getters;
+@use '../typography/versioning' as typography-versioning;
+
+/// Key used to access the Angular Material theme internals.
+$_internals: _mat-theming-internals-do-not-access;
+
+/// Keys that indicate a config object is a color config.
+$_color-keys: (
+  primary,
+  accent,
+  warn,
+  foreground,
+  background,
+  is-dark,
+  color, /* included for themes that incorrectly nest the color config: (color: (color: (....))) */
+);
+
+/// Keys that indicate a config object is a typography config.
+$_typography-keys: (
+  headline-1,
+  headline-2,
+  headline-3,
+  headline-4,
+  headline-5,
+  headline-6,
+  subtitle-1,
+  font-famiy,
+  subtitle-2,
+  body-1,
+  body-2,
+  button,
+  caption,
+  overline,
+);
+
+/// The CSS typography properties supported by the inspection API.
+$_typography-properties: (font, font-family, line-height, font-size, letter-spacing, font-weight);
+
+/// Gets the m2-config from the theme.
+@function _get-m2-config($theme) {
+  // It is possible for a user to pass a "density theme" that is just a number.
+  @if meta.type-of($theme) != 'map' {
+    @return $theme;
+  }
+  $internal: map.get($theme, $_internals, m2-config);
+  $theme: map.remove($theme, $_internals);
+  @return if(_is-error-theme($theme), $internal, $theme);
+}
+
+/// Checks whether the given theme contains error values.
+/// @param {*} $theme The theme to check.
+/// @return {Boolean} true if the theme contains error values, else false.
+@function _is-error-theme($theme) {
+  @if meta.type-of($theme) != 'map' {
+    @return false;
+  }
+  @if map.get($theme, ERROR) {
+    @return true;
+  }
+  @return _is-error-theme(list.nth(map.values($theme), 1));
+}
+
+/// Checks whether the given theme object has any of the given keys.
+/// @param {Map} $theme The theme to check
+/// @param {List} $keys The keys to check for
+/// @return {Boolean} Whether the theme has any of the given keys.
+@function _has-any-key($theme, $keys) {
+  @each $key in $keys {
+    @if map.has-key($theme, $key) {
+      @return true;
+    }
+  }
+  @return false;
+}
+
+/// Checks whether the given theme is a density scale value.
+/// @param {*} $theme The theme to check.
+/// @return {Boolean} true if the theme is a density scale value, else false.
+@function _is-density-value($theme) {
+  @return $theme == minimum or $theme == maximum or meta.type-of($theme) == 'number';
+}
+
+/// 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) {
+  $theme: _get-m2-config($theme);
+  @if not theme-has($theme, color) {
+    @error 'Color information is not available on this theme.';
+  }
+  $colors: theming.get-color-config($theme);
+  // Some apps seem to have mistakenly created nested color themes that somehow work with our old
+  // theme normalization logic. This check allows those apps to keep working.
+  @if theme-has($colors, color) {
+    $colors: theming.get-color-config($colors);
+  }
+  @return if(map.get($colors, is-dark), dark, light);
+}
+
+/// 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} $palette-name 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, $palette-name, $args...) {
+  $theme: _get-m2-config($theme);
+  @if not theme-has($theme, color) {
+    @error 'Color information is not available on this theme.';
+  }
+  $colors: theming.get-color-config($theme);
+  // Some apps seem to have mistakenly created nested color themes that somehow work with our old
+  // theme normalization logic. This check allows those apps to keep working.
+  @if theme-has($colors, color) {
+    $colors: theming.get-color-config($colors);
+  }
+  $palette: map.get($colors, $palette-name);
+  @if not $palette {
+    @error 'Unrecognized palette name:' $palette-name;
+  }
+  @return theming.get-color-from-palette($palette, $args...);
+}
+
+/// 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) {
+  $theme: _get-m2-config($theme);
+  @if not theme-has($theme, typography) {
+    @error 'Typography information is not available on this theme.';
+  }
+  $typography: typography-versioning.private-typography-to-2018-config(
+      theming.get-typography-config($theme));
+  @if $property == font {
+    $font-weight: typography-getters.font-weight($typography, $typescale);
+    $font-size: typography-getters.font-size($typography, $typescale);
+    $line-height: typography-getters.line-height($typography, $typescale);
+    $font-family: typography-getters.font-family($typography, $typescale);
+    @return ($font-weight list.slash($font-size, $line-height) $font-family);
+  }
+  @else if $property == font-family {
+    $result: typography-getters.font-family($typography, $typescale);
+    @return $result or typography-getters.font-family($typography);
+  }
+  @else if $property == font-size {
+    @return typography-getters.font-size($typography, $typescale);
+  }
+  @else if $property == font-weight {
+    @return typography-getters.font-weight($typography, $typescale);
+  }
+  @else if $property == line-height {
+    @return typography-getters.line-height($typography, $typescale);
+  }
+  @else if $property == letter-spacing {
+    @return typography-getters.letter-spacing($typography, $typescale);
+  }
+  @else {
+    @error #{'Valid typography properties are: #{$_typography-properties}. Got:'} $property;
+  }
+}
+
+/// Gets the density scale from a theme object.
+/// @param {Map} $theme The theme
+/// @return {Number} The density scale.
+@function get-theme-density($theme) {
+  $theme: _get-m2-config($theme);
+  @if not theme-has($theme, density) {
+    @error 'Density information is not available on this theme.';
+  }
+  $scale: theming.get-density-config($theme);
+  @return theming.clamp-density($scale, -5);
+}
+
+/// 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) {
+  $theme: _get-m2-config($theme);
+  @if $system == base {
+    @return true;
+  }
+  @if $system == color {
+    $color: theming.get-color-config($theme);
+    @return $color != null and _has-any-key($color, $_color-keys);
+  }
+  @if $system == typography {
+    $typography: theming.get-typography-config($theme);
+    @return $typography != null and _has-any-key($typography, $_typography-keys);
+  }
+  @if $system == density {
+    // Backwards compatibility for the case where an explicit, but invalid density is given
+    // (this was previously treated as density 0).
+    @if meta.type-of($theme) == 'map' and map.get($theme, density) {
+      @return true;
+    }
+    $density: theming.get-density-config($theme);
+    @return $density != null and _is-density-value($density);
+  }
+  @error 'Valid systems are: base, color, typography, density. Got:' $system;
+}

package/core/theming/_theming.scss

@@ -5,6 +5,9 @@
 @use 'palette';
 @use '../density/private/compatibility';
 
+// Whether to enable compatibility with legacy methods for accessing theme information.
+$theme-legacy-inspection-api-compatibility: true !default;
+
 // Whether duplication warnings should be disabled. Warnings enabled by default.
 $theme-ignore-duplication-warnings: false !default;
 
@@ -184,10 +187,10 @@ $_emitted-base: () !default;
   // configuration for the `color` theming part.
   @if $accent != null {
     @warn $_legacy-theme-warning;
-    @return private-create-backwards-compatibility-theme(_mat-validate-theme((
+    @return _internalize-theme(private-create-backwards-compatibility-theme(_mat-validate-theme((
       _is-legacy-theme: true,
       color: _mat-create-light-color-config($primary, $accent, $warn),
-    )));
+    ))));
   }
   // If the map pattern is used (1), we just pass-through the configurations for individual
   // parts of the theming system, but update the `color` configuration if set. As explained
@@ -200,7 +203,8 @@ $_emitted-base: () !default;
     $warn: map.get($color-settings, warn);
     $result: map.merge($result, (color: _mat-create-light-color-config($primary, $accent, $warn)));
   }
-  @return private-create-backwards-compatibility-theme(_mat-validate-theme($result));
+  @return _internalize-theme(
+      private-create-backwards-compatibility-theme(_mat-validate-theme($result)));
 }
 
 // TODO: Remove legacy API and rename below `$primary` to `$config`. Currently it cannot be renamed
@@ -225,10 +229,10 @@ $_emitted-base: () !default;
   // configuration for the `color` theming part.
   @if $accent != null {
     @warn $_legacy-theme-warning;
-    @return private-create-backwards-compatibility-theme(_mat-validate-theme((
+    @return _internalize-theme(private-create-backwards-compatibility-theme(_mat-validate-theme((
       _is-legacy-theme: true,
       color: _mat-create-dark-color-config($primary, $accent, $warn),
-    )));
+    ))));
   }
   // If the map pattern is used (1), we just pass-through the configurations for individual
   // parts of the theming system, but update the `color` configuration if set. As explained
@@ -241,7 +245,8 @@ $_emitted-base: () !default;
     $warn: map.get($color-settings, warn);
     $result: map.merge($result, (color: _mat-create-dark-color-config($primary, $accent, $warn)));
   }
-  @return private-create-backwards-compatibility-theme(_mat-validate-theme($result));
+  @return _internalize-theme(
+      private-create-backwards-compatibility-theme(_mat-validate-theme($result)));
 }
 
 /// Gets the color configuration from the given theme or configuration.
@@ -595,3 +600,51 @@ $_internals: _mat-theming-internals-do-not-access;
   }
   @return $density-scale;
 }
+
+/// Copies the given theme object and nests it within itself under a secret key and replaces the
+/// original map keys with error values. This allows the inspection API which is aware of the secret
+/// key to access the real values, but attempts to directly access the map will result in errors.
+/// @param {Map} $theme The theme map.
+@function _internalize-theme($theme) {
+  @if map.has-key($theme, $_internals) {
+    @return $theme;
+  }
+  $internalized-theme: (
+    $_internals: (
+      theme-version: 0,
+      m2-config: $theme
+    )
+  );
+  @if ($theme-legacy-inspection-api-compatibility) {
+    @return map.merge($theme, $internalized-theme);
+  }
+  $error-theme:
+    _replace-values-with-errors($theme, 'Theme may only be accessed via theme inspection API');
+  @return map.merge($error-theme, $internalized-theme);
+}
+
+/// Replaces concrete CSS values with errors in a theme object.
+/// Errors are represented as a map `(ERROR: <message>)`. Because maps are not valid CSS values,
+/// the Sass will not compile if the user tries to use any of the error theme values in their CSS.
+/// Users will see a message about `(ERROR: <message>)` not being a valid CSS value. Using the
+/// message, that winds up getting shown, we can help explain to users why they're getting the
+/// error.
+/// @param {*} $value The theme value to replace with errors.
+/// @param {String} $message The error message to sow users.
+/// @return {Map} A version of $value where concrete CSS values have been replaced with errors
+@function _replace-values-with-errors($value, $message) {
+  $value-type: meta.type-of($value);
+  @if $value-type == 'map' {
+    @each $k, $v in $value {
+      $value: map.set($value, $k, _replace-values-with-errors($v, $message));
+    }
+    @return $value;
+  }
+  @else if $value-type == 'list' and list.length($value) > 0 {
+    @for $i from 1 through list.length() {
+      $value: list.set-nth($value, $i, _replace-values-with-errors(list.nth($value, $i), $message));
+    }
+    @return $value;
+  }
+  @return (ERROR: $message);
+}