@ng-matero/extensions 17.1.3 → 17.2.0

package/_index.scss

@@ -23,7 +23,13 @@ split-color, split-typography, split-density, split-base;
 @forward './tooltip/tooltip-theme' as tooltip-* show tooltip-theme,
 tooltip-color, tooltip-typography, tooltip-density, tooltip-base;
 
+@forward './core/tokens/m2' show m2-tokens-from-theme;
+
 @forward './core/theming/all-theme' show all-component-themes, all-component-bases;
 @forward './core/color/all-color' show all-component-colors;
 @forward './core/typography/all-typography' show all-component-typographies;
 @forward './core/density/all-density' show all-component-densities;
+
+// Experimental M3 Token-based theming API
+@forward './core/theming/m3/definition' show define-theme, define-colors, define-typography, define-density;
+@forward './core/theming/m3/color-api-back-compat' show color-variants-back-compat;

package/alert/_alert-theme.scss

@@ -1,11 +1,14 @@
+@use 'sass:map';
 @use '@angular/material' as mat;
 @use '../core/style/sass-utils';
+@use '../core/theming/inspection';
+@use '../core/theming/validation';
 @use '../core/tokens/token-utils';
 @use '../core/tokens/m2/mtx/alert' as tokens-mtx-alert;
 
 @mixin base($theme) {
   @if mat.get-theme-version($theme) == 1 {
-    @include _theme-from-tokens(mat.get-theme-tokens($theme, base));
+    @include _theme-from-tokens(inspection.get-theme-tokens($theme, base));
   }
   @else {
     @include sass-utils.current-selector-or-root() {
@@ -17,7 +20,7 @@
 
 @mixin color($theme) {
   @if mat.get-theme-version($theme) == 1 {
-    @include _theme-from-tokens(mat.get-theme-tokens($theme, color));
+    @include _theme-from-tokens(inspection.get-theme-tokens($theme, color));
   }
   @else {
     @include sass-utils.current-selector-or-root() {
@@ -29,14 +32,14 @@
 
 @mixin typography($theme) {
   @if mat.get-theme-version($theme) == 1 {
-    @include _theme-from-tokens(mat.get-theme-tokens($theme, typography));
+    @include _theme-from-tokens(inspection.get-theme-tokens($theme, typography));
   }
   @else {}
 }
 
 @mixin density($theme) {
   @if mat.get-theme-version($theme) == 1 {
-    @include _theme-from-tokens(mat.get-theme-tokens($theme, density));
+    @include _theme-from-tokens(inspection.get-theme-tokens($theme, density));
   }
   @else {}
 }
@@ -44,7 +47,7 @@
 @mixin theme($theme) {
   @include mat.private-check-duplicate-theme-styles($theme, 'mtx-alert') {
     @if mat.get-theme-version($theme) == 1 {
-      @include _theme-from-tokens(mat.get-theme-tokens($theme));
+      @include _theme-from-tokens(inspection.get-theme-tokens($theme));
     }
     @else {
       @include base($theme);
@@ -62,6 +65,8 @@
 }
 
 @mixin _theme-from-tokens($tokens) {
+  @include validation.selector-defined(
+    'Calls to Angular Material theme mixins with an M3 theme must be wrapped in a selector');
   @if ($tokens != ()) {
     @include token-utils.create-token-values(tokens-mtx-alert.$prefix,
       map.get($tokens, tokens-mtx-alert.$prefix));

package/alert/alert.scss

@@ -6,9 +6,12 @@
   display: block;
   padding: 12px 20px;
   margin-bottom: 16px;
-  border: 1px solid transparent;
 
   @include token-utils.use-tokens(tokens-mtx-alert.$prefix, tokens-mtx-alert.get-token-slots()) {
+    $border-color: token-utils.get-token-variable(outline-color);
+
+    border: 1px solid var($border-color);
+
     @include token-utils.create-token-slot(border-radius, container-shape);
     @include token-utils.create-token-slot(background-color, background-color);
     @include token-utils.create-token-slot(color, text-color);

package/colorpicker/_colorpicker-theme.scss

@@ -2,12 +2,14 @@
 @use 'sass:map';
 @use '@angular/material' as mat;
 @use '../core/style/sass-utils';
+@use '../core/theming/inspection';
+@use '../core/theming/validation';
 @use '../core/tokens/token-utils';
 @use '../core/tokens/m2/mtx/colorpicker' as tokens-mtx-colorpicker;
 
 @mixin base($theme) {
   @if mat.get-theme-version($theme) == 1 {
-    @include _theme-from-tokens(mat.get-theme-tokens($theme, base));
+    @include _theme-from-tokens(inspection.get-theme-tokens($theme, base));
   }
   @else {
     @include sass-utils.current-selector-or-root() {
@@ -19,7 +21,7 @@
 
 @mixin color($theme) {
   @if mat.get-theme-version($theme) == 1 {
-    @include _theme-from-tokens(mat.get-theme-tokens($theme, color));
+    @include _theme-from-tokens(inspection.get-theme-tokens($theme, color));
   }
   @else {
     @include sass-utils.current-selector-or-root() {
@@ -43,14 +45,14 @@
 
 @mixin typography($theme) {
   @if mat.get-theme-version($theme) == 1 {
-    @include _theme-from-tokens(mat.get-theme-tokens($theme, typography));
+    @include _theme-from-tokens(inspection.get-theme-tokens($theme, typography));
   }
   @else {}
 }
 
 @mixin density($theme) {
   @if mat.get-theme-version($theme) == 1 {
-    @include _theme-from-tokens(mat.get-theme-tokens($theme, density));
+    @include _theme-from-tokens(inspection.get-theme-tokens($theme, density));
   }
   @else {}
 }
@@ -58,7 +60,7 @@
 @mixin theme($theme) {
   @include mat.private-check-duplicate-theme-styles($theme, 'mtx-colorpicker') {
     @if mat.get-theme-version($theme) == 1 {
-      @include _theme-from-tokens(mat.get-theme-tokens($theme));
+      @include _theme-from-tokens(inspection.get-theme-tokens($theme));
     }
     @else {
       @include base($theme);
@@ -76,6 +78,8 @@
 }
 
 @mixin _theme-from-tokens($tokens) {
+  @include validation.selector-defined(
+    'Calls to Angular Material theme mixins with an M3 theme must be wrapped in a selector');
   @if ($tokens != ()) {
     @include token-utils.create-token-values(tokens-mtx-colorpicker.$prefix,
       map.get($tokens, tokens-mtx-colorpicker.$prefix));

package/colorpicker/colorpicker.d.ts

@@ -1,7 +1,7 @@
 import { Directionality } from '@angular/cdk/bidi';
 import { Overlay, ScrollStrategy } from '@angular/cdk/overlay';
-import { ChangeDetectorRef, ElementRef, EventEmitter, InjectionToken, NgZone, OnChanges, OnDestroy, TemplateRef, ViewContainerRef } from '@angular/core';
-import { CanColor, ThemePalette } from '@angular/material/core';
+import { ChangeDetectorRef, EventEmitter, InjectionToken, NgZone, OnChanges, OnDestroy, TemplateRef, ViewContainerRef } from '@angular/core';
+import { ThemePalette } from '@angular/material/core';
 import { Subject } from 'rxjs';
 import { ColorEvent } from 'ngx-color';
 import { ColorFormat, MtxColorpickerInput } from './colorpicker-input';
@@ -18,20 +18,15 @@ export declare const MTX_COLORPICKER_SCROLL_STRATEGY_FACTORY_PROVIDER: {
     deps: (typeof Overlay)[];
     useFactory: typeof MTX_COLORPICKER_SCROLL_STRATEGY_FACTORY;
 };
-/** @docs-private */
-declare const _MtxColorpickerContentBase: import("@angular/material/core")._Constructor<CanColor> & import("@angular/material/core")._AbstractConstructor<CanColor> & {
-    new (_elementRef: ElementRef): {
-        _elementRef: ElementRef;
-    };
-};
-export declare class MtxColorpickerContent extends _MtxColorpickerContentBase implements OnDestroy, CanColor {
+export declare class MtxColorpickerContent implements OnDestroy {
     private _changeDetectorRef;
+    color: ThemePalette;
     picker: MtxColorpicker;
     /** Current state of the animation. */
     _animationState: 'enter-dropdown' | 'void';
     /** Emits when an animation has finished. */
     readonly _animationDone: Subject<void>;
-    constructor(elementRef: ElementRef, _changeDetectorRef: ChangeDetectorRef);
+    constructor(_changeDetectorRef: ChangeDetectorRef);
     _startExitAnimation(): void;
     ngOnDestroy(): void;
     getColorString(e: ColorEvent): string;
@@ -129,4 +124,3 @@ export declare class MtxColorpicker implements OnChanges, OnDestroy {
     static ngAcceptInputType_restoreFocus: unknown;
     static ngAcceptInputType_opened: unknown;
 }
-export {};

package/core/style/_sass-utils.scss

@@ -1,4 +1,5 @@
 @use 'sass:color';
+@use 'sass:list';
 @use 'sass:map';
 @use 'sass:meta';
 
@@ -59,3 +60,21 @@
   $args: meta.keywords($args);
   @return if(meta.type-of($color) == 'color', color.change($color, $args...), $color);
 }
+
+/// Gets the given arguments as a map of keywords and validates that only supported arguments were
+/// passed.
+/// @param {ArgList} $args The arguments to convert to a keywords map.
+/// @param {List} $supported-args The supported argument names.
+/// @return {Map} The $args as a map of argument name to argument value.
+@function validate-keyword-args($args, $supported-args) {
+  @if list.length($args) > 0 {
+    @error #{'Expected keyword args, but got positional args: '}#{$args};
+  }
+  $kwargs: meta.keywords($args);
+  @each $arg, $v in $kwargs {
+    @if list.index($supported-args, $arg) == null {
+      @error #{'Unsupported argument '}#{$arg}#{'. Valid arguments are: '}#{$supported-args};
+    }
+  }
+  @return $kwargs;
+}

package/core/theming/_inspection.scss

@@ -0,0 +1,38 @@
+@use 'sass:list';
+@use 'sass:map';
+@use '@angular/material' as mat;
+
+$_internals: _mat-theming-internals-do-not-access;
+
+/// 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: mat.private-validate-type($theme, 'map') or
+        map.get($theme, $_internals, theme-version) == null;
+  @return if($err, true, null);
+}
+
+/// 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: mat.private-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') or ());
+  }
+  @return $result;
+}

package/core/theming/_validation.scss

@@ -0,0 +1,5 @@
+@mixin selector-defined($msg) {
+  @if #{&} == '' {
+    @error $msg;
+  }
+}

package/core/theming/m3/_color-api-back-compat.scss

@@ -0,0 +1,46 @@
+@use '@angular/material' as mat;
+@use '../../../datetimepicker/datetimepicker-theme';
+@use '../../../select/select-theme';
+@use '../../../split/split-theme';
+
+// We want to emit only the overrides, because the backwards compatibility styles are usually
+// emitted after all the tokens have been included once already. This allows us to save ~50kb
+// from the bundle.
+$_overrides-only: true;
+
+@mixin color-variant-styles($theme, $color-variant) {
+  $primary-options: (color-variant: $color-variant, emit-overrides-only: $_overrides-only);
+
+  // Some components use the secondary color rather than primary color for `.mat-primary`.
+  // Those components should use the $secondary-color-variant.
+  $secondary-options: (
+    color-variant: if($color-variant == primary, secondary, $color-variant),
+    emit-overrides-only: $_overrides-only
+  );
+
+  &.mtx-split-gutter {
+    @include split-theme.color($theme, $primary-options...);
+  }
+
+  &.mtx-datetimepicker-content {
+    @include datetimepicker-theme.color($theme, $primary-options...);
+  }
+
+  &.ng-dropdown-panel {
+    @include select-theme.color($theme, $secondary-options...);
+  }
+}
+
+@mixin color-variants-back-compat($theme) {
+  .mat-primary {
+    @include color-variant-styles($theme, primary);
+  }
+
+  .mat-accent {
+    @include color-variant-styles($theme, tertiary);
+  }
+
+  .mat-warn {
+    @include color-variant-styles($theme, error);
+  }
+}

package/core/theming/m3/_config-validation.scss

@@ -0,0 +1,166 @@
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+@use 'sass:string';
+@use '@angular/material' as mat;
+@use '@angular/material-experimental' as matx;
+
+/// 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(matx.$m3-red-palette);
+  @if mat.private-validate-allowed-values($keys, $expected-keys...) or
+      mat.private-validate-required-values($keys, $expected-keys...) {
+    @return true;
+  }
+  $nv-keys: map.keys(map.get($palette, neutral-variant));
+  $expected-nv-keys: map.keys(map.get(matx.$m3-red-palette, neutral-variant));
+  @if mat.private-validate-allowed-values($nv-keys, $expected-nv-keys...) or
+      mat.private-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: mat.private-validate-type($config, 'map', 'null');
+  @if $err {
+    @return (#{'$config should be a configuration object. Got:'} $config);
+  }
+  $allowed: (color, typography, density);
+  $err: mat.private-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: mat.private-validate-type($config, 'map', 'null');
+  @if $err {
+    @return (#{'$config should be a color configuration object. Got:'} $config);
+  }
+  $allowed: (theme-type, primary, tertiary);
+  $err: mat.private-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: mat.private-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);
+  $err: mat.private-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: mat.private-validate-type($config, 'map', 'null');
+  @if $err {
+    @return (#{'$config should be a density configuration object. Got:'} $config);
+  }
+  $err: mat.private-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 mat.private-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;
+}