@angular/material 18.0.0-next.5 → 18.0.0-rc.0

package/core/theming/_config-validation.scss

@@ -0,0 +1,173 @@
+@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);
+  $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), map.get($config, theme-type)) {
+    @return (
+      #{'Expected $config.theme-type to be one of: light, dark. 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
+  );
+  $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,113 @@
+// 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';
+
+/// 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 sass-utils.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: (base-tokens: m3-tokens.generate-base-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 palettes.$violet-palette;
+  $tertiary: map.get($config, tertiary) or $primary;
+  sass-utils.$use-system-color-variables: map.get($config, use-system-variables) or false;
+
+  @return (
+    $internals: (
+      theme-version: $theme-version,
+      theme-type: $type,
+      palettes: (
+        primary: map.remove($primary, neutral, neutral-variant, secondary),
+        secondary: map.get($primary, secondary),
+        tertiary: map.remove($tertiary, neutral, neutral-variant, secondary),
+        neutral: map.get($primary, neutral),
+        neutral-variant: map.get($primary, neutral-variant),
+        error: map.get($primary, error),
+      ),
+      color-tokens: m3-tokens.generate-color-tokens(
+          $type, $primary, $tertiary, map.get($primary, error))
+    )
+  );
+}
+
+/// 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;
+  sass-utils.$use-system-typography-variables: map.get($config, use-system-variables) or false;
+
+  @return (
+    $internals: (
+      theme-version: $theme-version,
+      font-definition: (
+        plain: $plain,
+        brand: $brand,
+        bold: $bold,
+        medium: $medium,
+        regular: $regular,
+      ),
+      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)
+    )
+  );
+}

package/core/theming/_m2-inspection.scss

@@ -2,7 +2,8 @@
 @use 'sass:map';
 @use 'sass:meta';
 @use './theming';
-@use '../typography/property-getters' as typography-getters;
+@use '../m2/theming' as m2-theming;
+@use '../m2/typography-utils' as m2-typography-utils;
 @use '../typography/versioning' as typography-versioning;
 
 /// Key used to access the Angular Material theme internals.
@@ -92,11 +93,11 @@ $_typography-properties: (font, font-family, line-height, font-size, letter-spac
   @if not theme-has($theme, color) {
     @error 'Color information is not available on this theme.';
   }
-  $colors: theming.get-color-config($theme);
+  $colors: m2-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);
+    $colors: m2-theming.get-color-config($colors);
   }
   @return if(map.get($colors, is-dark), dark, light);
 }
@@ -115,18 +116,18 @@ $_typography-properties: (font, font-family, line-height, font-size, letter-spac
   @if not theme-has($theme, color) {
     @error 'Color information is not available on this theme.';
   }
-  $colors: theming.get-color-config($theme);
+  $colors: m2-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);
+    $colors: m2-theming.get-color-config($colors);
   }
   $palette: map.get($colors, $palette-name);
   @if not $palette {
     @error $palette-name $args $theme;
     @error #{'Unrecognized palette name:'} $palette-name;
   }
-  @return theming.get-color-from-palette($palette, $args...);
+  @return m2-theming.get-color-from-palette($palette, $args...);
 }
 
 /// Gets a typography value from a theme object.
@@ -141,29 +142,29 @@ $_typography-properties: (font, font-family, line-height, font-size, letter-spac
     @error 'Typography information is not available on this theme.';
   }
   $typography: typography-versioning.private-typography-to-2018-config(
-      theming.get-typography-config($theme));
+      m2-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);
+    $font-weight: m2-typography-utils.font-weight($typography, $typescale);
+    $font-size: m2-typography-utils.font-size($typography, $typescale);
+    $line-height: m2-typography-utils.line-height($typography, $typescale);
+    $font-family: m2-typography-utils.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);
+    $result: m2-typography-utils.font-family($typography, $typescale);
+    @return $result or m2-typography-utils.font-family($typography);
   }
   @else if $property == font-size {
-    @return typography-getters.font-size($typography, $typescale);
+    @return m2-typography-utils.font-size($typography, $typescale);
   }
   @else if $property == font-weight {
-    @return typography-getters.font-weight($typography, $typescale);
+    @return m2-typography-utils.font-weight($typography, $typescale);
   }
   @else if $property == line-height {
-    @return typography-getters.line-height($typography, $typescale);
+    @return m2-typography-utils.line-height($typography, $typescale);
   }
   @else if $property == letter-spacing {
-    @return typography-getters.letter-spacing($typography, $typescale);
+    @return m2-typography-utils.letter-spacing($typography, $typescale);
   }
   @else {
     @error #{'Valid typography properties are: #{$_typography-properties}. Got:'} $property;
@@ -178,7 +179,7 @@ $_typography-properties: (font, font-family, line-height, font-size, letter-spac
   @if not theme-has($theme, density) {
     @error 'Density information is not available on this theme.';
   }
-  $scale: theming.get-density-config($theme);
+  $scale: m2-theming.get-density-config($theme);
   @return theming.clamp-density($scale, -5);
 }
 
@@ -192,11 +193,11 @@ $_typography-properties: (font, font-family, line-height, font-size, letter-spac
     @return true;
   }
   @if $system == color {
-    $color: theming.get-color-config($theme);
+    $color: m2-theming.get-color-config($theme);
     @return $color != null and _has-any-key($color, $_color-keys);
   }
   @if $system == typography {
-    $typography: theming.get-typography-config($theme);
+    $typography: m2-theming.get-typography-config($theme);
     @return $typography != null and _has-any-key($typography, $_typography-keys);
   }
   @if $system == density {
@@ -205,7 +206,7 @@ $_typography-properties: (font, font-family, line-height, font-size, letter-spac
     @if meta.type-of($theme) == 'map' and map.get($theme, density) {
       @return true;
     }
-    $density: theming.get-density-config($theme);
+    $density: m2-theming.get-density-config($theme);
     @return $density != null and _is-density-value($density);
   }
   @error 'Valid systems are: base, color, typography, density. Got:' $system;
@@ -247,7 +248,7 @@ $_typography-properties: (font, font-family, line-height, font-size, letter-spac
   $internal: map.get($theme, $_internals, m2-config);
   $theme: map.remove($theme, $_internals);
   @if theme-has($theme, typography) {
-    $typography-config: theming.get-typography-config($theme);
+    $typography-config: m2-theming.get-typography-config($theme);
     // gmat configs have both 2018 and 2014 keys.
     @if (not typography-versioning.private-typography-is-2014-config($typography-config)) or
         (not typography-versioning.private-typography-is-2018-config($typography-config)) {