feat(material/core): move Material 3 support into stable (#28913)

Moves all of the Material 3 theming APIs into stable since they'll be considered stable APIs in v18.

Author: crisbeto

guides/material-3.md

@@ -6,21 +6,17 @@
 system, Material Design. It is the successor to [Material 2 (M2)](https://m2.material.io/), the
 design system which Angular Material has followed.
 
-As of v17.2.0, Angular Material includes experimental support for M3 styling in addition to M2. The
-team plans to stabilize support for M3 after a brief period in experimental in order to get feedback
-on the design and API.
-
 ## How to use Material 3 in your app
 
 M3 is implemented in Angular Material as an alternate Sass theme for the same set of Angular
 Material components already used by many apps. To use M3 with Angular Material, create your theme
-using the `define-theme` function from `@angular/material-experimental`, as opposed to the
+using the `define-theme` function from `@angular/material`, as opposed to the
 `define-light-theme` or `define-dark-theme` from `@angular/material` that are used to create M2
 themes.
 
 ### Defining your theme
 
-The simplest usage of the API, `$theme: matx.define-theme()` defines a theme with default values.
+The simplest usage of the API, `$theme: mat.define-theme()` defines a theme with default values.
 However, like its M2 counterparts, `define-theme` allows you to configure the appearance of your
 Angular Material app along three theming dimensions: color, typography, and density, by passing a
 theme configuration object. The configuration object may have the following properties.
@@ -34,12 +30,12 @@ theme configuration object. The configuration object may have the following prop
 <!-- TODO(mmalerba): Upgrade to embedded example -->
 
 ```scss
-@use '@angular/material-experimental' as matx;
+@use '@angular/material' as mat;
 
-$theme: matx.define-theme((
+$theme: mat.define-theme((
   color: (
     theme-type: dark,
-    primary: matx.$m3-violet-palette,
+    primary: mat.$violet-palette,
   ),
   typography: (
     brand-family: 'Comic Sans',
@@ -63,20 +59,20 @@ more about these terms):
 | `primary`      | [Optional] Specifies the palette to use for the app's primary color palette. (Note: the secondary, neutral, and neutral-variant palettes described in the M3 spec will be automatically chosen based on your primary palette, to ensure a harmonious color combination). |
 | `tertiary`     | [Optional] Specifies the palette to use for the app's tertiary color palette.                                                                                                                                                                                            |
 
-There are a number of color palettes available in `@angular/material-experimental` that can be
+There are a number of color palettes available in `@angular/material` that can be
 used with the `primary` and `tertiary` options:
 
-- `$m3-red-palette`
-- `$m3-green-palette`
-- `$m3-blue-palette`
-- `$m3-yellow-palette`
-- `$m3-cyan-palette`
-- `$m3-magenta-palette`
-- `$m3-orange-palette`
-- `$m3-chartreuse-palette`
-- `$m3-azure-palette`
-- `$m3-violet-palette`
-- `$m3-rose-palette`
+- `$red-palette`
+- `$green-palette`
+- `$blue-palette`
+- `$yellow-palette`
+- `$cyan-palette`
+- `$magenta-palette`
+- `$orange-palette`
+- `$chartreuse-palette`
+- `$azure-palette`
+- `$violet-palette`
+- `$rose-palette`
 
 Alternatively, a theme can be generated with a custom color with the following schematic:
 
@@ -161,9 +157,8 @@ can instead apply color variants by passing the `$color-variant` option to a com
 
 ```scss
 @use '@angular/material' as mat;
-@use '@angular/material-experimental' as matx;
 
-$theme: matx.define-theme();
+$theme: mat.define-theme();
 
 .tertiary-checkbox {
   @include mat.checkbox-color($theme, $color-variant: tertiary);
@@ -231,10 +226,9 @@ overrides on the highest-level selector where they apply.
 
 ```scss
 @use '@angular/material' as mat;
-@use '@angular/material-experimental' as matx;
 
-$light-theme: matx.define-theme();
-$dark-theme: matx.define-theme((
+$light-theme: mat.define-theme();
+$dark-theme: mat.define-theme((
   color: (
     theme-type: dark
   )
@@ -273,7 +267,6 @@ provided by Angular Material to access properties of the theme.
 
 ```scss
 @use '@angular/material' as mat;
-@use '@angular/material-experimental' as matx;
 
 @mixin my-comp-theme($theme) {
   .my-comp {
@@ -410,20 +403,19 @@ We recommend _not_ relying on the `color="primary"`, `color="accent"`, or `color
 that are offered by a number of Angular Material components for M2 themes. However, if you want to
 quickly update to M3 and are willing to accept the extra CSS generated for these variants, you can
 enable backwards compatibility styles that restore the behavior of this API. Call the
-`color-variants-back-compat` mixin from `@angular/material-experimental` with the M3 theme you want
+`color-variants-backwards-compatibility` mixin from `@angular/material` with the M3 theme you want
 to generate color variant styles for.
 
 <!-- TODO(mmalerba): Upgrade to embedded example -->
 
 ```scss
 @use '@angular/material' as mat;
-@use '@angular/material-experimental' as matx;
 
-$theme: matx.define-theme();
+$theme: mat.define-theme();
 
 html {
   @include mat.all-component-themes($theme);
-  @include matx.color-variants-back-compat($theme);
+  @include mat.color-variants-backwards-compatibility($theme);
 }
 ```
 
@@ -441,9 +433,8 @@ styles, pass an additional argument `$back-compat: true` to the mixin.
 
 ```scss
 @use '@angular/material' as mat;
-@use '@angular/material-experimental' as matx;
 
-$theme: matx.define-theme();
+$theme: mat.define-theme();
 
 @include mat.typography-hierarchy($theme, $back-compat: true);
 ```

package.json

@@ -142,6 +142,7 @@
     "@material/textfield": "15.0.0-canary.7f224ddd4.0",
     "@material/theme": "15.0.0-canary.7f224ddd4.0",
     "@material/tooltip": "15.0.0-canary.7f224ddd4.0",
+    "@material/tokens": "15.0.0-canary.7f224ddd4.0",
     "@material/top-app-bar": "15.0.0-canary.7f224ddd4.0",
     "@material/touch-target": "15.0.0-canary.7f224ddd4.0",
     "@material/typography": "15.0.0-canary.7f224ddd4.0",

packages.bzl

@@ -75,6 +75,7 @@ MDC_PACKAGES = [
     "@material/textfield",
     "@material/theme",
     "@material/tooltip",
+    "@material/tokens",
     "@material/top-app-bar",
     "@material/touch-target",
     "@material/typography",

src/dev-app/theme-m3.scss

@@ -1,5 +1,4 @@
 @use '@angular/material' as mat;
-@use '@angular/material-experimental' as matx;
 
 // Plus imports for other components in your app.
 
@@ -8,11 +7,11 @@ mat.$theme-legacy-inspection-api-compatibility: false;
 
 // Create a theme with the specified color type and density.
 @function create-theme($type: light, $density: 0) {
-  @return matx.define-theme((
+  @return mat.define-theme((
     color: (
       theme-type: $type,
-      primary: matx.$m3-azure-palette,
-      tertiary: matx.$m3-blue-palette,
+      primary: mat.$azure-palette,
+      tertiary: mat.$blue-palette,
     ),
     density: (
       scale: $density
@@ -78,11 +77,11 @@ $density-scales: (-1, -2, -3, -4, minimum, maximum);
 
 // Enable back-compat CSS for color="..." API & typography hierarchy.
 .demo-color-api-back-compat {
-  @include matx.color-variants-back-compat($light-theme);
+  @include mat.color-variants-backwards-compatibility($light-theme);
   @include mat.typography-hierarchy($light-theme, $back-compat: true);
 
   &.demo-unicorn-dark-theme {
-    @include matx.color-variants-back-compat($dark-theme);
+    @include mat.color-variants-backwards-compatibility($dark-theme);
   }
 }
 

src/e2e-app/theme.scss

@@ -1,13 +1,12 @@
 @use '@angular/material' as mat;
-@use '@angular/material-experimental' as matx;
 
 @include mat.core();
 
-$theme: matx.define-theme((
+$theme: mat.define-theme((
   color: (
     theme-type: light,
-    primary: matx.$m3-azure-palette,
-    tertiary: matx.$m3-blue-palette,
+    primary: mat.$azure-palette,
+    tertiary: mat.$blue-palette,
   ),
   density: (
     scale: 0,

src/material-experimental/BUILD.bazel

@@ -19,9 +19,7 @@ ts_library(
 
 sass_library(
     name = "theming_scss_lib",
-    srcs = MATERIAL_EXPERIMENTAL_SCSS_LIBS + [
-        "//src/material-experimental/theming:theming_scss_lib",
-    ],
+    srcs = MATERIAL_EXPERIMENTAL_SCSS_LIBS,
 )
 
 sass_library(

src/material-experimental/_index.scss

@@ -4,11 +4,4 @@
 @forward './popover-edit/popover-edit-theme' as popover-edit-* show popover-edit-color,
   popover-edit-typography, popover-edit-density, popover-edit-theme;
 
-// Token-based theming API
-@forward './theming/definition' show define-theme, define-colors, define-typography, define-density;
-@forward './theming/m3-palettes' as m3-* show $m3-red-palette, $m3-green-palette, $m3-blue-palette,
-  $m3-yellow-palette, $m3-cyan-palette, $m3-magenta-palette, $m3-orange-palette,
-  $m3-chartreuse-palette, $m3-azure-palette, $m3-violet-palette, $m3-rose-palette;
-@forward './theming/color-api-back-compat' show color-variants-back-compat;
-
 // Additional public APIs for individual components

src/material-experimental/theming/BUILD.bazel

@@ -4,6 +4,13 @@
 // 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/definition' show define-theme, define-colors, define-typography,
+  define-density;
+@forward './core/theming/palettes' show $red-palette, $green-palette, $blue-palette,
+  $yellow-palette, $cyan-palette, $magenta-palette, $orange-palette,
+  $chartreuse-palette, $azure-palette, $violet-palette, $rose-palette;
+@forward './core/theming/color-api-backwards-compatibility' show
+  color-variants-backwards-compatibility;
 
 @forward './core/theming/theming' show $theme-ignore-duplication-warnings,
   $theme-legacy-inspection-api-compatibility;