feat(material/core): namespace m2-specific theming APIs (#28892)

These changes rename the theming APIs that are specific to M2 to be prefixed with `m2-`. Subsequent changes will move the M3 APIs out of `experimental` and introduce a schematic to automatically migrate users.

BREAKING CHANGE:
The following APIs have been renamed. If you update using `ng update`, your app will be fixed automatically.
* `define-light-theme` to `m2-define-light-theme`
* `define-dark-theme` to `m2-define-dark-theme`
* `define-palette` to `m2-define-palette`
* `get-contrast-color-from-palette` to `m2-get-contrast-color-from-palette`
* `get-color-from-palette` to `m2-get-color-from-palette`
* `get-color-config` to `m2-get-color-config`
* `get-typography-config` to `m2-get-typography-config`
* `get-density-config` to `m2-get-density-config`
* `$red-palette` to `$m2-red-palette`
* `$pink-palette` to `$m2-pink-palette`
* `$indigo-palette` to `$m2-indigo-palette`
* `$purple-palette` to `$m2-purple-palette`
* `$deep-purple-palette` to `$m2-deep-purple-palette`
* `$blue-palette` to `$m2-blue-palette`
* `$light-blue-palette` to `$m2-light-blue-palette`
* `$cyan-palette` to `$m2-cyan-palette`
* `$teal-palette` to `$m2-teal-palette`
* `$green-palette` to `$m2-green-palette`
* `$light-green-palette` to `$m2-light-green-palette`
* `$lime-palette` to `$m2-lime-palette`
* `$yellow-palette` to `$m2-yellow-palette`
* `$amber-palette` to `$m2-amber-palette`
* `$orange-palette` to `$m2-orange-palette`
* `$deep-orange-palette` to `$m2-deep-orange-palette`
* `$brown-palette` to `$m2-brown-palette`
* `$grey-palette` to `$m2-grey-palette`
* `$gray-palette` to `$m2-gray-palette`
* `$blue-grey-palette` to `$m2-blue-grey-palette`
* `$blue-gray-palette` to `$m2-blue-gray-palette`
* `$light-theme-background-palette` to `$m2-light-theme-background-palette`
* `$dark-theme-background-palette` to `$m2-dark-theme-background-palette`
* `$light-theme-foreground-palette` to `$m2-light-theme-foreground-palette`
* `$dark-theme-foreground-palette` to `$m2-dark-theme-foreground-palette`
* `define-typography-level` to `m2-define-typography-level`
* `define-rem-typography-config` to `m2-define-rem-typography-config`
* `define-typography-config` to `m2-define-typography-config`
* `define-legacy-typography-config` to `m2-define-legacy-typography-config`
* `typography-level` to `m2-typography-level`
* `font-size` to `m2-font-size`
* `line-height` to `m2-line-height`
* `font-weight` to `m2-font-weight`
* `letter-spacing` to `m2-letter-spacing`
* `font-family` to `m2-font-family`
* `font-shorthand` to `m2-font-shorthand`

integration/yarn-pnp-compat/src/styles.scss

@@ -1,10 +1,10 @@
 @use '@angular/material' as mat;
 
-$primary: mat.define-palette(mat.$blue-palette);
-$accent: mat.define-palette(mat.$grey-palette);
-$theme: mat.define-light-theme((
+$primary: mat.m2-define-palette(mat.$m2-blue-palette);
+$accent: mat.m2-define-palette(mat.$m2-grey-palette);
+$theme: mat.m2-define-light-theme((
   color: (primary: $primary, accent: $accent),
-  typography: mat.define-typography-config(),
+  typography: mat.m2-define-typography-config(),
   density: 0
 ));
 

src/dev-app/theme.scss

@@ -7,16 +7,16 @@
 mat.$theme-legacy-inspection-api-compatibility: false;
 
 // Define the default (light) theme.
-$candy-app-primary: mat.define-palette(mat.$indigo-palette);
-$candy-app-accent: mat.define-palette(mat.$pink-palette, A200, A100, A400);
-$candy-app-theme: mat.define-light-theme((
+$candy-app-primary: mat.m2-define-palette(mat.$m2-indigo-palette);
+$candy-app-accent: mat.m2-define-palette(mat.$m2-pink-palette, A200, A100, A400);
+$candy-app-theme: mat.m2-define-light-theme((
   // Define the default colors for our app.
   color: (
     primary: $candy-app-primary,
     accent: $candy-app-accent
   ),
   // Define the default typography for our app.
-  typography: mat.define-typography-config(),
+  typography: mat.m2-define-typography-config(),
   // Define the default density level for our app.
   density: 0,
 ));
@@ -46,18 +46,18 @@ $candy-app-theme: mat.define-light-theme((
 // default theme.
 .demo-unicorn-dark-theme {
   // Create the color palettes used in our dark theme.
-  $dark-primary: mat.define-palette(mat.$blue-grey-palette);
-  $dark-accent: mat.define-palette(mat.$amber-palette, A200, A100, A400);
-  $dark-warn: mat.define-palette(mat.$deep-orange-palette);
-  $dark-colors: mat.define-dark-theme(
+  $dark-primary: mat.m2-define-palette(mat.$m2-blue-grey-palette);
+  $dark-accent: mat.m2-define-palette(mat.$m2-amber-palette, A200, A100, A400);
+  $dark-warn: mat.m2-define-palette(mat.$m2-deep-orange-palette);
+  $dark-colors: mat.m2-define-dark-theme(
       (
         color: (
           primary: $dark-primary,
           accent: $dark-accent,
           warn: $dark-warn
         ),
         density: 0,
-        typography: mat.define-typography-config(),
+        typography: mat.m2-define-typography-config(),
       )
   );
 

src/material-experimental/theming/_m3-tokens.scss

@@ -508,13 +508,13 @@
   // TODO(mmalerba): Refactor this to not depend on the legacy theme when moving out of
   //  material-experimental. This is a hack for now because there is no good way to get the token
   //  slots in material-experimental without exposing them all from material.
-  $fake-theme: mat.define-light-theme((
+  $fake-theme: mat.m2-define-light-theme((
     color: (
-      primary: mat.define-palette(mat.$red-palette),
-      accent: mat.define-palette(mat.$red-palette),
-      warn: mat.define-palette(mat.$red-palette),
+      primary: mat.m2-define-palette(mat.$m2-red-palette),
+      accent: mat.m2-define-palette(mat.$m2-red-palette),
+      warn: mat.m2-define-palette(mat.$m2-red-palette),
     ),
-    typography: mat.define-typography-config(),
+    typography: mat.m2-define-typography-config(),
     density: 0
   ));
   $token-slots: mat.m2-tokens-from-theme($fake-theme);

src/material/_index.scss

@@ -1,19 +1,14 @@
-// Theming APIs
-@forward './core/theming/theming' show define-light-theme, define-dark-theme,
-  define-palette, get-contrast-color-from-palette, get-color-from-palette,
-  get-color-config, get-typography-config, get-density-config,
-  $theme-ignore-duplication-warnings, $theme-legacy-inspection-api-compatibility;
+// Expose the M2 APIs under an `m2-` prefix in order to distinguish them from the M3 APIs.
+@forward './core/m2' as m2-*;
+
+// New theming APIs
+@forward './core/theming/inspection' show get-theme-version, get-theme-type, get-theme-color,
+  get-theme-typography, get-theme-density, theme-has, theme-remove;
+
+@forward './core/theming/theming' show $theme-ignore-duplication-warnings,
+  $theme-legacy-inspection-api-compatibility;
 @forward './core/theming/theming' as private-* show private-clamp-density;
-@forward './core/theming/palette' show $red-palette, $pink-palette, $indigo-palette,
-  $purple-palette, $deep-purple-palette, $blue-palette, $light-blue-palette, $cyan-palette,
-  $teal-palette, $green-palette, $light-green-palette, $lime-palette, $yellow-palette,
-  $amber-palette, $orange-palette, $deep-orange-palette, $brown-palette, $grey-palette,
-  $gray-palette, $blue-grey-palette, $blue-gray-palette, $light-theme-background-palette,
-  $dark-theme-background-palette, $light-theme-foreground-palette, $dark-theme-foreground-palette;
-@forward './core/typography/typography' show define-typography-level, define-rem-typography-config,
-  define-typography-config, typography-hierarchy, define-legacy-typography-config;
-@forward './core/typography/typography-utils' show typography-level,
-  font-size, line-height, font-weight, letter-spacing, font-family, font-shorthand;
+@forward './core/typography/typography' show typography-hierarchy;
 @forward './core/tokens/m2' show m2-tokens-from-theme;
 
 // Private/Internal
@@ -131,7 +126,3 @@
   tooltip-typography, tooltip-density, tooltip-base;
 @forward './tree/tree-theme' as tree-* show tree-theme, tree-color, tree-typography, tree-density,
   tree-base;
-
-// New theming APIs
-@forward './core/theming/inspection' show get-theme-version, get-theme-type, get-theme-color,
-  get-theme-typography, get-theme-density, theme-has, theme-remove;

src/material/core/_m2.scss

@@ -0,0 +1,54 @@
+// M2-specific theming APIs which are separated out into this file so they
+// can be renamed conditionally depending on whether we're in 1P or 3P.
+@forward './theming/theming' show
+  define-light-theme,
+  define-dark-theme,
+  define-palette,
+  get-contrast-color-from-palette,
+  get-color-from-palette,
+  get-color-config,
+  get-typography-config,
+  get-density-config;
+
+@forward './theming/palette' show
+  $red-palette,
+  $pink-palette,
+  $indigo-palette,
+  $purple-palette,
+  $deep-purple-palette,
+  $blue-palette,
+  $light-blue-palette,
+  $cyan-palette,
+  $teal-palette,
+  $green-palette,
+  $light-green-palette,
+  $lime-palette,
+  $yellow-palette,
+  $amber-palette,
+  $orange-palette,
+  $deep-orange-palette,
+  $brown-palette,
+  $grey-palette,
+  $gray-palette,
+  $blue-grey-palette,
+  $blue-gray-palette,
+  $light-theme-background-palette,
+  $dark-theme-background-palette,
+  $light-theme-foreground-palette,
+  $dark-theme-foreground-palette;
+
+
+@forward './typography/typography' show
+  define-typography-level,
+  define-rem-typography-config,
+  define-typography-config,
+  define-legacy-typography-config;
+
+@forward './typography/typography-utils' show
+  typography-level,
+  font-size,
+  line-height,
+  font-weight,
+  letter-spacing,
+  font-family,
+  font-shorthand;

src/material/core/theming/tests/test-theming-bundle.scss

@@ -11,16 +11,16 @@ mat.$theme-ignore-duplication-warnings: true;
 // test will be reported as failing.
 
 // Theme creation functions.
-$theme: mat.define-light-theme((
+$theme: mat.m2-define-light-theme((
     color: (
-        primary: mat.define-palette(mat.$red-palette),
-        accent: mat.define-palette(mat.$blue-palette),
+        primary: mat.m2-define-palette(mat.$m2-red-palette),
+        accent: mat.m2-define-palette(mat.$m2-blue-palette),
     ),
-    typography: mat.define-typography-config(),
+    typography: mat.m2-define-typography-config(),
     density: -2,
 ));
-$dark-theme: mat.define-dark-theme($theme);
-$rem-typography: mat.define-rem-typography-config();
+$dark-theme: mat.m2-define-dark-theme($theme);
+$rem-typography: mat.m2-define-rem-typography-config();
 
 // All-* mixins.
 @include mat.all-component-themes($theme);

src/material/core/theming/tests/theming-definition-api.spec.ts

@@ -240,7 +240,7 @@ describe('theming definition api', () => {
 
     it('should throw for invalid palette', () => {
       expect(() =>
-        transpile(`$theme: matx.define-theme((color: (tertiary: mat.$red-palette)))`),
+        transpile(`$theme: matx.define-theme((color: (tertiary: mat.$m2-red-palette)))`),
       ).toThrowError(/Expected \$config\.color\.tertiary to be a valid M3 palette\. Got:/);
     });
 

src/material/core/theming/tests/theming-inspection-api.spec.ts

@@ -45,13 +45,13 @@ describe('theming inspection api', () => {
     it('should get theme version', () => {
       expect(
         transpile(`
-          $theme: mat.define-light-theme((
+          $theme: mat.m2-define-light-theme((
             color: (
-              primary: mat.define-palette(mat.$red-palette),
-              accent: mat.define-palette(mat.$red-palette),
-              warn: mat.define-palette(mat.$red-palette),
+              primary: mat.m2-define-palette(mat.$m2-red-palette),
+              accent: mat.m2-define-palette(mat.$m2-red-palette),
+              warn: mat.m2-define-palette(mat.$m2-red-palette),
             ),
-            typography: mat.define-typography-config(),
+            typography: mat.m2-define-typography-config(),
             density: 0,
           ));
           div {
@@ -64,10 +64,10 @@ describe('theming inspection api', () => {
     it('should get theme type', () => {
       expect(
         transpile(`
-          $theme: mat.define-dark-theme((
+          $theme: mat.m2-define-dark-theme((
             color: (
-              primary: mat.define-palette(mat.$red-palette),
-              accent: mat.define-palette(mat.$red-palette),
+              primary: mat.m2-define-palette(mat.$m2-red-palette),
+              accent: mat.m2-define-palette(mat.$m2-red-palette),
             ),
           ));
           div {
@@ -80,10 +80,10 @@ describe('theming inspection api', () => {
     it('should get role color', () => {
       expect(
         transpile(`
-          $theme: mat.define-light-theme((
+          $theme: mat.m2-define-light-theme((
             color: (
-              primary: mat.define-palette(mat.$red-palette),
-              accent: mat.define-palette(mat.$green-palette)
+              primary: mat.m2-define-palette(mat.$m2-red-palette),
+              accent: mat.m2-define-palette(mat.$m2-green-palette)
             )
           ));
           div {
@@ -96,10 +96,10 @@ describe('theming inspection api', () => {
     it('should get palette color', () => {
       expect(
         transpile(`
-          $theme: mat.define-light-theme((
+          $theme: mat.m2-define-light-theme((
             color: (
-              primary: mat.define-palette(mat.$red-palette),
-              accent: mat.define-palette(mat.$green-palette)
+              primary: mat.m2-define-palette(mat.$m2-red-palette),
+              accent: mat.m2-define-palette(mat.$m2-green-palette)
             )
           ));
           div {
@@ -111,8 +111,8 @@ describe('theming inspection api', () => {
 
     it('should get typography properties from theme', () => {
       const css = transpile(`
-        $theme: mat.define-light-theme((
-          typography: mat.define-typography-config()
+        $theme: mat.m2-define-light-theme((
+          typography: mat.m2-define-typography-config()
         ));
         div {
           font: mat.get-theme-typography($theme, headline-1);
@@ -134,7 +134,7 @@ describe('theming inspection api', () => {
     it('should get density scale', () => {
       expect(
         transpile(`
-          $theme: mat.define-light-theme((
+          $theme: mat.m2-define-light-theme((
             density: -1
           ));
           div {
@@ -146,28 +146,28 @@ describe('theming inspection api', () => {
 
     it('should check what information the theme has', () => {
       const css = transpile(`
-        $theme: mat.define-light-theme((
+        $theme: mat.m2-define-light-theme((
           color: (
-            primary: mat.define-palette(mat.$red-palette),
-            accent: mat.define-palette(mat.$red-palette),
+            primary: mat.m2-define-palette(mat.$m2-red-palette),
+            accent: mat.m2-define-palette(mat.$m2-red-palette),
           ),
-          typography: mat.define-typography-config(),
+          typography: mat.m2-define-typography-config(),
           density: -1,
         ));
-        $color-only: mat.define-light-theme((
+        $color-only: mat.m2-define-light-theme((
           color: (
-            primary: mat.define-palette(mat.$red-palette),
-            accent: mat.define-palette(mat.$red-palette),
+            primary: mat.m2-define-palette(mat.$m2-red-palette),
+            accent: mat.m2-define-palette(mat.$m2-red-palette),
           ),
           typography: null,
           density: null,
         ));
-        $typography-only: mat.define-light-theme((
+        $typography-only: mat.m2-define-light-theme((
           color: null,
-          typography: mat.define-typography-config(),
+          typography: mat.m2-define-typography-config(),
           density: null,
         ));
-        $density-only: mat.define-light-theme((
+        $density-only: mat.m2-define-light-theme((
           color: null,
           typography: null,
           density: -1,
@@ -209,10 +209,10 @@ describe('theming inspection api', () => {
       expect(
         transpile(`
           mat.$theme-legacy-inspection-api-compatibility: false;
-          $theme: mat.define-dark-theme((
+          $theme: mat.m2-define-dark-theme((
             color: (
-              primary: mat.define-palette(mat.$red-palette),
-              accent: mat.define-palette(mat.$red-palette),
+              primary: mat.m2-define-palette(mat.$m2-red-palette),
+              accent: mat.m2-define-palette(mat.$m2-red-palette),
             )
           ));
           div {
@@ -226,10 +226,10 @@ describe('theming inspection api', () => {
       expect(() =>
         transpile(`
           mat.$theme-legacy-inspection-api-compatibility: false;
-          $theme: mat.define-dark-theme((
+          $theme: mat.m2-define-dark-theme((
             color: (
-              primary: mat.define-palette(mat.$red-palette),
-              accent: mat.define-palette(mat.$red-palette),
+              primary: mat.m2-define-palette(mat.$red-palette),
+              accent: mat.m2-define-palette(mat.$red-palette),
             )
           ));
           $color-config: mat.get-color-config($theme);