@angular/material 16.2.0 → 17.0.0-next.0

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,229 @@
+// This file contains functions used to inspect Angular Material theme objects.
+
+@use 'sass:list';
+@use 'sass:map';
+@use '../style/validation';
+
+$_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) {
+  $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.'};
+  }
+  @if not theme-has($theme, color) {
+    @error 'Color information is not available on this theme.';
+  }
+  @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
+/// 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...) {
+  $args-count: list.length($args);
+  @if $args-count == 1 {
+    @return _get-theme-role-color($theme, $args...);
+  }
+  @else if $args-count == 2 {
+    @return _get-theme-palette-color($theme, $args...);
+  }
+  @error #{'Expected 2 or 3 arguments. Got:'} $args-count + 1;
+}
+
+/// 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) {
+  $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);
+}
+
+/// 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.'};
+  }
+  @if not theme-has($theme, density) {
+    @error 'Density information is not available on this theme.';
+  }
+  @return map.get($theme, $_internals, density-scale);
+}
+
+/// 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) {
+  $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;
+  }
+  @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;
+}
+
+/// 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;
+}

package/core/theming/_theming.scss

@@ -35,6 +35,7 @@ $_disable-color-backwards-compatibility: false;
 $_emitted-color: () !default;
 $_emitted-typography: () !default;
 $_emitted-density: () !default;
+$_emitted-base: () !default;
 
 /// Extracts a color from a palette or throws an error if it doesn't exist.
 /// @param {Map} $palette The palette from which to extract a color.
@@ -71,7 +72,6 @@ $_emitted-density: () !default;
     lighter: _get-color-from-palette($base-palette, $lighter),
     darker: _get-color-from-palette($base-palette, $darker),
     text: _get-color-from-palette($base-palette, $text),
-
     default-contrast: get-contrast-color-from-palette($base-palette, $default),
     lighter-contrast: get-contrast-color-from-palette($base-palette, $lighter),
     darker-contrast: get-contrast-color-from-palette($base-palette, $darker)
@@ -321,6 +321,8 @@ $_emitted-density: () !default;
 // Private APIs
 //
 
+$_internals: _mat-theming-internals-do-not-access;
+
 // Checks if configurations that have been declared in the given theme have been generated
 // before. If so, warnings will be reported. This should notify developers in case duplicate
 // styles are accidentally generated due to wrong usage of the all-theme mixins.
@@ -334,6 +336,111 @@ $_emitted-density: () !default;
 // (e.g. `all-component-themes` and `all-legacy-component-themes`) without causing any
 // style duplication.
 @mixin private-check-duplicate-theme-styles($theme-or-color-config, $id) {
+  // TODO(mmalerba): use get-theme-version for this check when its moved out of experimental.
+  @if map.get($theme-or-color-config, $_internals, theme-version) == 1 {
+    @include _check-duplicate-theme-styles-v1($theme-or-color-config, $id) {
+      // Optionally, consumers of this mixin can wrap contents inside so that nested
+      // duplicate style checks do not report another warning. e.g. if developers include
+      // the `all-component-themes` mixin twice, only the top-level duplicate styles check
+      // should report a warning. Not all individual components should report a warning too.
+      $orig-mat-theme-ignore-duplication-warnings: $theme-ignore-duplication-warnings;
+      $theme-ignore-duplication-warnings: true !global;
+      @content;
+      $theme-ignore-duplication-warnings: $orig-mat-theme-ignore-duplication-warnings !global;
+    }
+  }
+  @else {
+    @include _check-duplicate-theme-styles-v0($theme-or-color-config, $id) {
+      // Optionally, consumers of this mixin can wrap contents inside so that nested
+      // duplicate style checks do not report another warning. e.g. if developers include
+      // the `all-component-themes` mixin twice, only the top-level duplicate styles check
+      // should report a warning. Not all individual components should report a warning too.
+      $orig-mat-theme-ignore-duplication-warnings: $theme-ignore-duplication-warnings;
+      $theme-ignore-duplication-warnings: true !global;
+      @content;
+      $theme-ignore-duplication-warnings: $orig-mat-theme-ignore-duplication-warnings !global;
+    }
+  }
+}
+
+/// Strip out any settings map entries that have empty values (null or ()).
+@function _strip-empty-settings($settings) {
+  $result: ();
+  @each $key, $value in $settings {
+    @if $value != null and $value != () {
+      $result: map.set($result, $key, $value);
+    }
+  }
+  @return if($result == (), null, $result);
+}
+
+// Checks for duplicate styles in a `theme-version: 1` style theme.
+@mixin _check-duplicate-theme-styles-v1($theme-or-color-config, $id) {
+  $color-settings: _strip-empty-settings((
+    theme-type: map.get($theme-or-color-config, $_internals, theme-type),
+    color-tokens: map.get($theme-or-color-config, $_internals, color-tokens),
+  ));
+  $typography-settings: _strip-empty-settings((
+    typography-tokens: map.get($theme-or-color-config, $_internals, typography-tokens),
+  ));
+  $density-settings: _strip-empty-settings((
+    density-scale: map.get($theme-or-color-config, $_internals, density-scale),
+    density-tokens: map.get($theme-or-color-config, $_internals, density-tokens),
+  ));
+  $base-settings: _strip-empty-settings((
+    base-tokens: map.get($theme-or-color-config, $_internals, base-tokens),
+  ));
+  $previous-color-settings: map.get($_emitted-color, $id) or ();
+  $previous-typography-settings: map.get($_emitted-typography, $id) or ();
+  $previous-density-settings: map.get($_emitted-density, $id) or ();
+  $previous-base-settings: map.get($_emitted-base, $id) or ();
+
+  // Check if the color configuration has been generated before.
+  @if $color-settings != null {
+    @if list.index($previous-color-settings, $color-settings) != null and
+        not $theme-ignore-duplication-warnings {
+      @warn 'The same color styles are generated multiple times. ' + $_duplicate-warning;
+    }
+    $previous-color-settings: list.append($previous-color-settings, $color-settings);
+  }
+
+  // Check if the typography configuration has been generated before.
+  @if $typography-settings != null {
+    @if list.index($previous-typography-settings, $typography-settings) != null and
+        not $theme-ignore-duplication-warnings {
+      @warn 'The same typography styles are generated multiple times. ' + $_duplicate-warning;
+    }
+    $previous-typography-settings: list.append($previous-typography-settings, $typography-settings);
+  }
+
+  // Check if the density configuration has been generated before.
+  @if $density-settings != null {
+    @if list.index($previous-density-settings, $density-settings) != null and
+        not $theme-ignore-duplication-warnings {
+      @warn 'The same density styles are generated multiple times. ' + $_duplicate-warning;
+    }
+    $previous-density-settings: list.append($previous-density-settings, $density-settings);
+  }
+
+  // Check if the base configuration has been generated before.
+  @if $base-settings != null {
+    @if list.index($previous-base-settings, $base-settings) != null and
+        not $theme-ignore-duplication-warnings {
+      @warn 'The same base theme styles are generated multiple times. ' + $_duplicate-warning;
+    }
+    $previous-base-settings: list.append($previous-base-settings, $base-settings);
+  }
+
+  $_emitted-color: map.set($_emitted-color, $id, $previous-color-settings) !global;
+  $_emitted-density: map.set($_emitted-density, $id, $previous-density-settings) !global;
+  $_emitted-typography: map.set($_emitted-typography, $id, $previous-typography-settings) !global;
+  $_emitted-base: map.set($_emitted-base, $id, $previous-base-settings) !global;
+
+  @content;
+}
+
+// Checks for duplicate styles in a `theme-version: 0` style theme.
+@mixin _check-duplicate-theme-styles-v0($theme-or-color-config, $id) {
   $theme: private-legacy-get-theme($theme-or-color-config);
   $color-config: get-color-config($theme);
   $density-config: get-density-config($theme);
@@ -383,13 +490,6 @@ $_emitted-density: () !default;
   $_emitted-density: map.merge($_emitted-density, ($id: $previous-density)) !global;
   $_emitted-typography: map.merge($_emitted-typography, ($id: $previous-typography)) !global;
 
-  // Optionally, consumers of this mixin can wrap contents inside so that nested
-  // duplicate style checks do not report another warning. e.g. if developers include
-  // the `all-component-themes` mixin twice, only the top-level duplicate styles check
-  // should report a warning. Not all individual components should report a warning too.
-  $orig-mat-theme-ignore-duplication-warnings: $theme-ignore-duplication-warnings;
-  $theme-ignore-duplication-warnings: true !global;
-
   // If duplicate default density styles would be generated for a legacy constructed theme,
   // we adjust the density generation so that no density styles are generated by default.
   // If no default density styles have been generated yet, we ensure that the styles
@@ -401,7 +501,6 @@ $_emitted-density: () !default;
   compatibility.$private-density-generate-styles: not $duplicate-legacy-density;
 
   @content;
-  $theme-ignore-duplication-warnings: $orig-mat-theme-ignore-duplication-warnings !global;
 
   compatibility.$private-density-generate-at-root: false;
   compatibility.$private-density-generate-styles: true;
@@ -456,7 +555,8 @@ $_emitted-density: () !default;
 // TODO(devversion): remove this in the future. Constructing themes manually is rare,
 // and the code can be easily updated to the new API.
 @function private-legacy-get-theme($theme-or-color-config) {
-  @if private-is-theme-object($theme-or-color-config) {
+  @if private-is-theme-object($theme-or-color-config) or
+      map.get($theme-or-color-config, $_internals, theme-version) == 1 {
     @return $theme-or-color-config;
   }
 

package/core/tokens/m2/mat/_form-field.scss

@@ -1,6 +1,8 @@
 @use 'sass:map';
 @use '../../token-utils';
 @use '../../../style/sass-utils';
+@use '../../../theming/theming';
+@use '../../../theming/palette';
 @use '../../../typography/typography-utils';
 
 // The prefix used to generate the fully qualified name for tokens in this file.
@@ -14,12 +16,43 @@ $prefix: (mat, form-field);
 
 // Tokens that can be configured through Angular Material's color theming API.
 @function get-color-tokens($config) {
+  $warn: map.get($config, warn);
   $is-dark: map.get($config, is-dark);
   $on-surface: if($is-dark, #fff, #000);
+  $color-tokens: private-get-color-palette-color-tokens($config, primary);
 
-  @return (
+  @return map.merge($color-tokens, (
     // MDC has a token for the enabled placeholder, but not for the disabled one.
     disabled-input-text-placeholder-color: rgba($on-surface, 0.38),
+    state-layer-color: rgba($on-surface, 0.87),
+    error-text-color: theming.get-color-from-palette($warn),
+
+    // On dark themes we set the native `select` color to some shade of white,
+    // however the color propagates to all of the `option` elements, which are
+    // always on a white background inside the dropdown, causing them to blend in.
+    // Since we can't change background of the dropdown, we need to explicitly
+    // reset the color of the options to something dark.
+    select-option-text-color: if($is-dark, palette.$dark-primary-text, inherit),
+    // Note the spelling of the `GrayText` here which is a system color. See:
+    // https://developer.mozilla.org/en-US/docs/Web/CSS/system-color
+    select-disabled-option-text-color: if($is-dark, palette.$dark-disabled-text, GrayText),
+
+    // These values are taken from the MDC select implementation:
+    // https://github.com/material-components/material-components-web/blob/master/packages/mdc-select/_select-theme.scss
+    enabled-select-arrow-color: rgba($on-surface, 0.54),
+    disabled-select-arrow-color: rgba($on-surface, 0.38),
+
+    hover-state-layer-opacity: if($is-dark, 0.08, 0.04),
+    focus-state-layer-opacity: if($is-dark, 0.24, 0.12),
+  ));
+}
+
+// Generates the mapping for the properties that change based on the form field color.
+@function private-get-color-palette-color-tokens($config, $palette-name) {
+  $palette: map.get($config, $palette-name);
+
+  @return (
+    focus-select-arrow-color: theming.get-color-from-palette($palette, default, 0.87),
   );
 }
 

package/core/tokens/m2/mat/_slider.scss

@@ -0,0 +1,43 @@
+@use 'sass:map';
+@use '../../token-utils';
+@use '../../../style/sass-utils';
+
+// The prefix used to generate the fully qualified name for tokens in this file.
+$prefix: (mat, slider);
+
+// Tokens that can't be configured through Angular Material's current theming API,
+// but may be in a future version of the theming API.
+@function get-unthemable-tokens() {
+  @return ();
+}
+
+// Tokens that can be configured through Angular Material's color theming API.
+@function get-color-tokens($config) {
+  $is-dark: map.get($config, is-dark);
+
+  @return (
+    // Opacity of value indicator text container
+    value-indicator-opacity: if($is-dark, 0.9, 0.6),
+  );
+}
+
+// Tokens that can be configured through Angular Material's typography theming API.
+@function get-typography-tokens($config) {
+  @return ();
+ }
+
+// Tokens that can be configured through Angular Material's density theming API.
+@function get-density-tokens($config) {
+  @return ();
+}
+
+// Combines the tokens generated by the above functions into a single map with placeholder values.
+// This is used to create token slots.
+@function get-token-slots() {
+  @return sass-utils.deep-merge-all(
+          get-unthemable-tokens(),
+          get-color-tokens(token-utils.$placeholder-color-config),
+          get-typography-tokens(token-utils.$placeholder-typography-config),
+          get-density-tokens(token-utils.$placeholder-density-config)
+  );
+}

package/core/tokens/m2/mdc/_filled-text-field.scss

@@ -134,7 +134,7 @@ $prefix: (mdc, filled-text-field);
   @return $first-color;
 }
 
-// Generates the mapping for the properties that change based on the slide toggle color.
+// Generates the mapping for the properties that change based on the text field color.
 @function private-get-color-palette-color-tokens($config, $palette-name) {
   $palette: map.get($config, $palette-name);
   $palette-color: theming.get-color-from-palette($palette);

package/core/tokens/m2/mdc/_outlined-text-field.scss

@@ -117,7 +117,7 @@ $prefix: (mdc, outlined-text-field);
   ));
 }
 
-// Generates the mapping for the properties that change based on the slide toggle color.
+// Generates the mapping for the properties that change based on the text field color.
 @function private-get-color-palette-color-tokens($config, $palette-name) {
   $palette: map.get($config, $palette-name);
   $palette-color: theming.get-color-from-palette($palette);