@depup/angular__material 21.2.2-depup.19

package/core/theming/_config-validation.scss

@@ -0,0 +1,174 @@
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+@use 'sass:string';
+@use '../style/validation';
+@use './palettes';
+
+/// Creates an error message by finding `$config` in the existing message and appending a suffix to
+/// it.
+/// @param {List|String} $err The error message.
+/// @param {String} $suffix The suffix to add.
+/// @return {List|String} The updated error message.
+@function _create-dollar-config-error-message($err, $suffix) {
+  @if meta.type-of($err) == 'list' {
+    @for $i from 1 through list.length($err) {
+      $err: list.set-nth($err, $i,
+        _create-dollar-config-error-message(list.nth($err, $i), $suffix));
+    }
+  }
+  @else if meta.type-of($err) == 'string' {
+    $start: string.index($err, '$config');
+    @if $start {
+      $err: string.insert($err, $suffix, $start + 7);
+    }
+  }
+  @return $err;
+}
+
+/// Validates that the given object is an M3 palette.
+/// @param {*} $palette The object to test
+/// @return {Boolean|null} null if it is a valid M3 palette, else true.
+@function validate-palette($palette) {
+  @if not meta.type-of($palette) == 'map' {
+    @return true;
+  }
+  $keys: map.keys($palette);
+  $expected-keys: map.keys(palettes.$red-palette);
+  @if validation.validate-allowed-values($keys, $expected-keys...) or
+      validation.validate-required-values($keys, $expected-keys...) {
+    @return true;
+  }
+  $nv-keys: map.keys(map.get($palette, neutral-variant));
+  $expected-nv-keys: map.keys(map.get(palettes.$red-palette, neutral-variant));
+  @if validation.validate-allowed-values($nv-keys, $expected-nv-keys...) or
+      validation.validate-required-values($nv-keys, $expected-nv-keys...) {
+    @return true;
+  }
+  @return 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: validation.validate-type($config, 'map', 'null');
+  @if $err {
+    @return (#{'$config should be a configuration object. Got:'} $config);
+  }
+  $allowed: (color, typography, density);
+  $err: validation.validate-allowed-values(map.keys($config or ()), $allowed...);
+  @if $err {
+    @return (
+      #{'$config has unexpected properties. Valid properties are'}
+      #{'#{$allowed}.'}
+      #{'Found:'}
+      $err
+    );
+  }
+  $err: validate-color-config(map.get($config, color));
+  @if $err {
+    @return _create-dollar-config-error-message($err, '.color');
+  }
+  $err: validate-typography-config(map.get($config, typography));
+  @if $err {
+    @return _create-dollar-config-error-message($err, '.typography');
+  }
+  $err: validate-density-config(map.get($config, density));
+  @if $err {
+    @return _create-dollar-config-error-message($err, '.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: validation.validate-type($config, 'map', 'null');
+  @if $err {
+    @return (#{'$config should be a color configuration object. Got:'} $config);
+  }
+  $allowed: (theme-type, primary, tertiary, use-system-variables, system-variables-prefix);
+  $err: validation.validate-allowed-values(map.keys($config or ()), $allowed...);
+  @if $err {
+    @return (
+      #{'$config has unexpected properties. Valid properties are'}
+      #{'#{$allowed}.'}
+      #{'Found:'}
+      $err
+    );
+  }
+  @if $config and map.has-key($config, theme-type) and
+      not list.index((light, dark, color-scheme), map.get($config, theme-type)) {
+    @return (
+      #{'Expected $config.theme-type to be one of: light, dark, color-scheme. Got:'}
+      map.get($config, theme-type)
+    );
+  }
+  @each $palette in (primary, secondary, tertiary) {
+    @if $config and map.has-key($config, $palette) {
+      $err: validate-palette(map.get($config, $palette));
+      @if $err {
+        @return (
+          #{'Expected $config.#{$palette} to be a valid M3 palette. Got:'}
+          map.get($config, $palette)
+        );
+      }
+    }
+  }
+  @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: validation.validate-type($config, 'map', 'null');
+  @if $err {
+    @return (#{'$config should be a typography configuration object. Got:'} $config);
+  }
+  $allowed: (
+    brand-family,
+    plain-family,
+    bold-weight,
+    medium-weight,
+    regular-weight,
+    use-system-variables,
+    system-variables-prefix
+  );
+  $err: validation.validate-allowed-values(map.keys($config or ()), $allowed...);
+  @if $err {
+    @return (
+      #{'$config has unexpected properties. Valid properties are'}
+      #{'#{$allowed}.'}
+      #{'Found:'}
+      $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: validation.validate-type($config, 'map', 'null');
+  @if $err {
+    @return (#{'$config should be a density configuration object. Got:'} $config);
+  }
+  $err: validation.validate-allowed-values(map.keys($config or ()), scale);
+  @if $err {
+    @return (#{'$config has unexpected properties. Valid properties are: scale. Found:'} $err);
+  }
+  @if $config and map.has-key($config, scale) {
+    $allowed-scales: (0, -1, -2, -3, -4, -5, minimum, maximum);
+    @if validation.validate-allowed-values(map.get($config, scale), $allowed-scales...) {
+      @return (
+        #{'Expected $config.scale to be one of: #{$allowed-scales}. Got:'}
+        map.get($config, scale)
+      );
+    }
+  }
+  @return null;
+}

package/core/theming/_definition.scss

@@ -0,0 +1,141 @@
+// This file contains functions used to define Angular Material theme objects.
+
+@use 'sass:map';
+@use '../style/sass-utils';
+@use './palettes';
+@use '../tokens/m3-tokens';
+@use './config-validation';
+@use '../tokens/m3';
+
+// Prefix used for component token fallback variables, e.g.
+// `color: var(--mat-text-button-label-text-color, var(--mat-sys-primary));`
+$system-fallback-prefix: mat-sys;
+
+// Default system level prefix to use when directly calling the `system-level-*` mixins.
+// Prefix used for component token fallback variables, e.g.
+// `color: var(--mat-text-button-label-text-color, var(--mat-sys-primary));`
+// TODO: Remove this variable after internal clients are migrated from "sys"
+$system-level-prefix: mat-sys;
+
+/// 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;
+  }
+
+  $color-config: map.get($config, color) or ();
+  $typography-config: map.get($config, typography) or ();
+  $density-config: map.get($config, density) or ();
+
+  // colors
+  $type: map.get($color-config, theme-type) or light;
+  $primary: map.get($color-config, primary) or palettes.$violet-palette;
+  $tertiary: map.get($color-config, tertiary) or $primary;
+  $color-system-variables-prefix:
+    map.get($color-config, system-variables-prefix) or $system-level-prefix;
+  sass-utils.$use-system-color-variables: map.get($color-config, use-system-variables) or false;
+
+  $palettes: (
+    primary: map.remove($primary, neutral, neutral-variant, secondary),
+    secondary: map.get($primary, secondary),
+    tertiary: map.remove($tertiary, neutral, neutral-variant, secondary, error),
+    neutral: map.get($primary, neutral),
+    neutral-variant: map.get($primary, neutral-variant),
+    error: map.get($primary, error),
+  );
+
+  // typography
+  $default-plain: (Roboto, sans-serif);
+  $default-brand: $default-plain;
+  $plain: map.get($typography-config, plain-family) or $default-plain;
+  $brand: map.get($typography-config, brand-family) or $default-brand;
+  $bold: map.get($typography-config, bold-weight) or 700;
+  $medium: map.get($typography-config, medium-weight) or 500;
+  $regular: map.get($typography-config, regular-weight) or 400;
+  $typography-system-variables-prefix: map.get($typography-config, system-variables-prefix) or
+    $system-level-prefix;
+  sass-utils.$use-system-typography-variables:
+    map.get($typography-config, use-system-variables) or false;
+  $typography: (
+    plain: $plain,
+    brand: $brand,
+    bold: $bold,
+    medium: $medium,
+    regular: $regular,
+  );
+
+  // density
+  $density-scale: map.get($density-config, scale) or 0;
+
+  $system-maps: (
+    m3-tokens.get-sys-color($type, $palettes, $color-system-variables-prefix),
+    m3.md-sys-elevation-values(),
+    m3.md-sys-motion-values(),
+    m3.md-sys-shape-values(),
+    m3.md-sys-state-values(),
+    (
+      // Form field native select option text color
+      neutral10: map.get($palettes, neutral, 10),
+      // Sidenav scrim (container background shadow when opened),
+      neutral-variant20: map.get($palettes, neutral-variant, 20),
+    ),
+    m3-tokens.get-sys-typeface($typography, $typography-system-variables-prefix),
+  );
+  $system: (
+    density-scale: $density-scale,
+  );
+  @each $sys-map in $system-maps {
+    $system: map.merge($system, $sys-map);
+  }
+
+  @return (
+    _mat-system: $system,
+    $internals: (
+      base-tokens: m3-tokens.generate-base-tokens(),
+      color-system-variables-prefix: $color-system-variables-prefix,
+      color-tokens:
+        m3-tokens.generate-color-tokens($type, $palettes, $color-system-variables-prefix),
+      density-scale: $density-scale,
+      font-definition: $typography,
+      palettes: $palettes,
+      theme-type: $type,
+      theme-version: $theme-version,
+      typography-system-variables-prefix: $typography-system-variables-prefix,
+      typography-tokens:
+          m3-tokens.generate-typography-tokens($typography, $typography-system-variables-prefix),
+    )
+  );
+}
+
+/// Defines an Angular Material theme object with color settings.
+/// @param {Map} $config The color configuration
+/// @return {Map} A theme object
+/// @deprecated Use define-theme with a map using the "color" key
+@function define-colors($config: ()) {
+  @return define-theme((color: $config));
+}
+
+/// Defines an Angular Material theme object with typography settings.
+/// @param {Map} $config The typography configuration
+/// @return {Map} A theme object
+/// @deprecated Use define-theme with a map using the "typography" key
+@function define-typography($config: ()) {
+  @return define-theme((typography: $config));
+}
+
+/// Defines an Angular Material theme object with density settings.
+/// @param {Map} $config The density configuration
+/// @return {Map} A theme object
+/// @deprecated Use define-theme with a map using the "density" key
+@function define-density($config: ()) {
+  @return define-theme((density: $config));
+}

package/core/theming/_inspection.scss

@@ -0,0 +1,289 @@
+@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;
+  @if ($err) {
+    @return true;
+  }
+  @return 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);
+
+  @if ($err) {
+    @return 0;
+  }
+
+  @return 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 take a different amount of arguments depending
+/// on if it's working with an M2 or M3 theme:
+/// - With an M3 theme it accepts either 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.).
+/// - With an M2 theme theme it accepts between 2 and 4 arguments, or the equivalent of calling
+/// the `m2-get-theme-color` function. The first argument is the theme, the second one is the
+/// palette from which to extract the color, the third one is the hue within the palette and the
+/// fourth is the opacity of the returned color.
+/// the second one is the
+/// @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) + 1;
+
+  // M2 theme
+  @if $version == 0 {
+    @if $args-count < 2 or $args-count > 4 {
+      @error 'Expected between 2 and 4 arguments when working with an M2 theme. ' +
+             'Got: #{$args-count}';
+    }
+    @return m2-inspection.get-theme-color($theme, $args...);
+  }
+
+  // M3 theme
+  @if $version == 1 {
+    @if $args-count < 2 or $args-count > 3 {
+      @error 'Expected either 2 or 3 arguments when working with an M3 theme. Got: #{$args-count}';
+    }
+    @if ($args-count == 2) {
+      @return _get-theme-role-color($theme, $args...);
+    }
+    @return _get-theme-palette-color($theme, $args...);
+  }
+
+  @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, (mat, 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, (mat, 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;
+  }
+}
+
+/// Removes the information about the given theming system(s) from the given theme.
+/// @param {Map} $theme The theme to remove information from
+/// @param {String...} $systems The systems to remove
+/// @return {Map} A version of the theme without the removed theming systems.
+@function theme-remove($theme, $systems...) {
+  $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;
+  }
+  $version: get-theme-version($theme);
+  @if $version == 0 {
+    @return m2-inspection.theme-remove($theme, $systems...);
+  }
+  @else if $version == 1 {
+    @each $system in $systems {
+      @if $system == base {
+        $theme: map.deep-remove($theme, $internals, base-tokens);
+      }
+      @else if $system == color {
+        $theme: map.deep-remove($theme, $internals, color-tokens);
+        $theme: map.deep-remove($theme, $internals, theme-type);
+        $theme: map.deep-remove($theme, $internals, palettes);
+      }
+      @else if $system == typography {
+        $theme: map.deep-remove($theme, $internals, typography-tokens);
+      }
+      @else if $system == density {
+        $theme: map.deep-remove($theme, $internals, density-scale);
+        $theme: map.deep-remove($theme, $internals, density-tokens);
+      }
+    }
+    @return $theme;
+  }
+}