refactor: all-density, all-color and all-typography mixins should accept theme

With initial changes for the new density API, the individual mixins for
`all-color`, `all-density` and `all-typography` started only accepting
configurations for their actual theming system part.

This makes sense conceptually, but in favor of a better developer experience,
we also want to support that actual `$theme` objects can be specified.

The mixins then extract the individual configs from the theme objects.
This allows consumers to easily generate color styles for dark themes. e.g.

```
$my-theme: mat-light-theme((color: $color-config));
$my-dark-theme: mat-dark-theme((color: $color-confi));

// Includes color and default density. Typography is not included
// by default for backwards compatibility.
@include angular-material-theme($my-theme);

.dark-enabled {
  // Note: Using the overall `theme` mixin here would cause
  // density styles to be duplicated unnecessarily.
  @include angular-material-color($my-dark-theme);
}
```

docs: update documentation for new api

refactor: update ng-add schematic

refactor: add color mixin for material-experimental and add theme support in bulk mixins

docs: guide edits

refactor: all-typography mixin should use all-theme to avoid c… (#19021)

As discussed in our team meeting, we want to get rid of the duplication
of individual theme, color, density and typography mixins
(similar to how we did it for all-density and all-color).

We couldn't simplify the all-typography mixin because the `core-theme`
mixin is stored in a file that relies on `all-typography`. This causes
a circular dependency when `all-typography` would then rely on `all-theme`.

To fix this, we split the `mat-core-theme` and `mat-core` mixin into
separate files. This avoids the circular dependency.

Additionally, a test has been created that ensures that the theming
bundle still exposes the necessary mixins/variables as needed.

Author: devversion

.github/CODEOWNERS

@@ -99,6 +99,7 @@
 /src/material-experimental/mdc-card/**             @mmalerba
 /src/material-experimental/mdc-checkbox/**         @mmalerba
 /src/material-experimental/mdc-chips/**            @mmalerba
+/src/material-experimental/mdc-color/**            @jelbourn @devversion
 /src/material-experimental/mdc-density/**          @devversion
 /src/material-experimental/mdc-dialog/**           @devversion
 /src/material-experimental/mdc-form-field/**       @devversion @mmalerba

guides/theming-your-components.md

@@ -3,31 +3,30 @@ In order to style your own components with Angular Material's tooling, the compo
 be defined with Sass.
 
 #### 1. Define all color and typography styles in a "theme file" for the component
-First, create a Sass mixin that accepts an Angular Material theme and outputs the color-specific
-styles for the component. An Angular Material theme definition is a Sass map.
+First, create a Sass mixin that accepts an Angular Material color configuration and
+outputs the color-specific styles for the component. A color configuration is a Sass map.
 
 For example, if building a custom carousel component:
 ```scss
 // Import library functions for theme creation.
 @import '~@angular/material/theming';
 
-// Define a mixin that accepts a theme and outputs the theme-specific styles.
-@mixin candy-carousel-theme($theme) {
+@mixin candy-carousel-color($config) {
   // Extract the palettes you need from the theme definition.
-  $primary: map-get($theme, primary);
-  $accent: map-get($theme, accent);
+  $primary: map-get($config, primary);
+  $accent: map-get($config, accent);
 
   // Define any styles affected by the theme.
   .candy-carousel {
     // Use mat-color to extract individual colors from a palette.
-    background-color: mat-color($primary);
-    border-color: mat-color($accent, A400);
+    background-color: mat-color($config);
+    border-color: mat-color($config, A400);
   }
 }
 ```
 
-Second, create another Sass mixin that accepts an Angular Material typography definition and outputs
-typographic styles. For example:
+Second, create another Sass mixin that accepts an Angular Material typography configuration
+and outputs typographic styles. For example:
 
 ```scss
 @mixin candy-carousel-typography($config) {
@@ -41,6 +40,27 @@ typographic styles. For example:
 }
 ```
 
+Finally, create a mixin that accepts an Angular Material theme, and delegates to the individual
+theming system mixins based on the configurations. A theme consists of configurations for
+individual theming systems (`color` and `typography`).
+
+```scss
+@mixin candy-carousel-theme($theme) {
+  // Extracts the color and typography configurations from the theme.
+  $color: mat-get-color-config($theme);
+  $typography: mat-get-typography-config($theme);
+
+  // Do not generate styles if configurations for individual theming
+  // systems have been explicitly set to `null`.
+  @if $color != null {
+    @include candy-carousel-color($color); 
+  }
+  @if $typography != null {
+    @include candy-carousel-typography($typography);
+  }
+}
+```
+
 See the [typography guide](https://material.angular.io/guide/typography) for more information on
 typographic customization.
 
@@ -63,7 +83,12 @@ including Angular Material's built-in theme mixins.
 // Define your application's custom theme.
 $primary: mat-palette($mat-indigo);
 $accent:  mat-palette($mat-pink, A200, A100, A400);
-$theme: mat-light-theme($primary, $accent);
+$theme: mat-light-theme((
+  color: (
+    primary: $primary,
+    accent: $accent,
+  )
+));
 
 // Include theme styles for Angular Material components.
 @include angular-material-theme($theme);

guides/theming.md

@@ -2,21 +2,26 @@
 
 
 ### What is a theme?
-A **theme** is the set of colors that will be applied to the Angular Material components. The
-library's approach to theming is based on the guidance from the [Material Design spec][1].
 
-In Angular Material, a theme is created by composing multiple palettes. In particular,
-a theme consists of:
+Angular Material's theming system enables you to customize components to
+better reflect your product's brand. A theme consists of configurations for the individual
+`color` and `typography` systems in Angular Material. The library's approach to theming reflects
+the guidance from the [Material Design spec][1].
+
+In Angular Material, you create a color configuration by composing multiple palettes. In
+particular, a color configuration consists of:
+
 * A primary palette: colors most widely used across all screens and components.
 * An accent palette: colors used for the floating action button and interactive elements.
 * A warn palette: colors used to convey error state.
 * A foreground palette: colors for text and icons.
 * A background palette: colors used for element backgrounds.
 
-In Angular Material, all theme styles are generated _statically_ at build-time so that your
-app doesn't have to spend cycles generating theme styles on startup.
+Additionally, in Angular Material, a configuration may optionally include `typography` settings.
+More information on how typography works can be [found in a dedicated guide][3].
 
-[1]: https://material.io/archive/guidelines/style/color.html#color-color-palette
+Angular Material theme styles are generated _statically_ at build-time so that your
+app doesn't have to spend cycles generating theme styles on startup.
 
 ### Using a pre-built theme
 Angular Material comes prepackaged with several pre-built theme css files. These theme files also
@@ -57,10 +62,11 @@ A custom theme file does two things:
 1. Imports the `mat-core()` Sass mixin. This includes all common styles that are used by multiple
 components. **This should only be included once in your application.** If this mixin is included
 multiple times, your application will end up with multiple copies of these common styles.
-2. Defines a **theme** data structure as the composition of multiple palettes. This object can be
-created with either the `mat-light-theme` function or the `mat-dark-theme` function. The output of
-this function is then passed to the  `angular-material-theme` mixin, which will output all of the
-corresponding styles for the theme.
+2. Defines a **theme** data structure as the composition of configurations for the individual
+theming systems (`color` and `typography`). This object can be created with either the
+`mat-light-theme` function or the `mat-dark-theme` function. The output of this function is then
+passed to the `angular-material-theme` mixin, which will output all of the corresponding styles
+for the theme.
 
 
 A typical theme file will look something like this:
@@ -82,8 +88,15 @@ $candy-app-accent:  mat-palette($mat-pink, A200, A100, A400);
 // The warn palette is optional (defaults to red).
 $candy-app-warn:    mat-palette($mat-red);
 
-// Create the theme object (a Sass map containing all of the palettes).
-$candy-app-theme: mat-light-theme($candy-app-primary, $candy-app-accent, $candy-app-warn);
+// Create the theme object. A theme consists of configurations for individual
+// theming systems such as `color` or `typography`.
+$candy-app-theme: mat-light-theme((
+  color: (
+    primary: $candy-app-primary,
+    accent: $candy-app-accent,
+    warn: $candy-app-warn,  
+  )
+));
 
 // Include theme styles for core and each component used in your app.
 // Alternatively, you can import and @include the theme mixins for each component
@@ -135,34 +148,49 @@ theme.
 // Define the default theme (same as the example above).
 $candy-app-primary: mat-palette($mat-indigo);
 $candy-app-accent:  mat-palette($mat-pink, A200, A100, A400);
-$candy-app-theme:   mat-light-theme($candy-app-primary, $candy-app-accent);
-
-// Include the default theme styles.
+$candy-app-theme:   mat-light-theme((
+  color: (
+    primary: $candy-app-primary,
+    accent: $candy-app-accent,
+  )
+));
+
+// Include the default theme styles (color and default density)
 @include angular-material-theme($candy-app-theme);
 
 
 // Define an alternate dark theme.
 $dark-primary: mat-palette($mat-blue-grey);
 $dark-accent:  mat-palette($mat-amber, A200, A100, A400);
 $dark-warn:    mat-palette($mat-deep-orange);
-$dark-theme:   mat-dark-theme($dark-primary, $dark-accent, $dark-warn);
-
-// Include the alternative theme styles inside of a block with a CSS class. You can make this
+$dark-theme:   mat-dark-theme((
+  color: (
+    primary: $dark-primary,
+    accent: $dark-accent,
+    warn: $dark-warn,
+  )
+));
+
+// Include the dark color styles inside of a block with a CSS class. You can make this
 // CSS class whatever you want. In this example, any component inside of an element with
 // `.unicorn-dark-theme` will be affected by this alternate dark theme instead of the default theme.
 .unicorn-dark-theme {
-  @include angular-material-theme($dark-theme);
+  @include angular-material-color($dark-theme);
 }
 ```
 
 In the above example, any component inside of a parent with the `unicorn-dark-theme` class will use
 the dark theme, while other components will fall back to the default `$candy-app-theme`.
 
-You can include as many themes as you like in this manner. You can also `@include` the
-`angular-material-theme` in separate files and then lazily load them based on an end-user
+You can include as many color schemes as you like in this manner. You can also `@include` the
+`angular-material-color` in separate files and then lazily load them based on an end-user
 interaction (how to lazily load the CSS assets will vary based on your application).
 
 It's important to remember, however, that the `mat-core` mixin should only ever be included _once_.
+Similarly, the `angular-material-theme` mixin should not be used multiple times as it generates
+styles for all configured theming system parts. For example, typography styles would be generated
+multiple times, even though the configuration did not change. Instead, use fine-grained mixins such
+as `angular-material-color` that only result in styles being generated for the [color system][2].
 
 ##### Multiple themes and overlay-based components
 Since certain components (e.g. menu, select, dialog, etc.) are inside of a global overlay container,
@@ -203,7 +231,12 @@ the `mat-core-theme` mixin as well, which contains theme-specific styles for com
 // Define the theme.
 $candy-app-primary: mat-palette($mat-indigo);
 $candy-app-accent:  mat-palette($mat-pink, A200, A100, A400);
-$candy-app-theme:   mat-light-theme($candy-app-primary, $candy-app-accent);
+$candy-app-theme:   mat-light-theme((
+  color: (
+    primary: $candy-app-primary,
+    accent: $candy-app-accent,
+  )
+));
 
 // Include the theme styles for only specified components.
 @include mat-core-theme($candy-app-theme);
@@ -251,3 +284,7 @@ function changeTheme(themeName) {
 ### Theming your own components
 For more details about theming your own components,
 see [theming-your-components.md](./theming-your-components.md).
+
+[1]: https://material.io/archive/guidelines/style/color.html#color-color-palette
+[2]: https://material.io/design/color
+[3]: ./typography.md

src/dev-app/theme.scss

@@ -1,3 +1,5 @@
+@import '../material/core/core';
+@import '../material/core/theming/all-theme';
 @import '../material/core/density/all-density';
 @import '../material/core/focus-indicators/focus-indicators';
 @import '../material/core/theming/all-theme';
@@ -82,6 +84,6 @@ $density-scales: (-1, -2, minimum, maximum);
 @each $density in$density-scales {
   .demo-density-#{$density} {
     @include _angular-material-density($density);
-    @include angular-material-density-mdc($density);
+    @include angular-material-mdc-density($density);
   }
 }

src/e2e-app/theme.scss

@@ -1,3 +1,4 @@
+@import '../material/core/core';
 @import '../material/core/theming/all-theme';
 @import '../material-experimental/mdc-theming/all-theme';
 @import '../material-experimental/mdc-typography/all-typography';

src/material-experimental/mdc-color/BUILD.bazel

@@ -0,0 +1,9 @@
+package(default_visibility = ["//visibility:public"])
+
+load("//tools:defaults.bzl", "sass_library")
+
+sass_library(
+    name = "all_color",
+    srcs = ["_all-color.scss"],
+    deps = ["//src/material-experimental/mdc-theming:all_themes"],
+)

src/material-experimental/mdc-color/_all-color.scss

@@ -0,0 +1,18 @@
+@import '../mdc-theming/all-theme';
+
+@mixin angular-material-mdc-color($config-or-theme) {
+  // In case a theme object has been passed instead of a configuration for
+  // the color system, extract the color config from the theme object.
+  $config: if(_mat-is-theme-object($config-or-theme),
+      mat-get-color-config($config-or-theme), $config-or-theme);
+
+  @if $config == null {
+    @error 'No color configuration specified.';
+  }
+
+  @include angular-material-mdc-theme((
+    color: $config,
+    typography: null,
+    density: null,
+  ));
+}

src/material-experimental/mdc-density/_all-density.scss

@@ -1,6 +1,15 @@
 @import '../mdc-theming/all-theme';
 
-@mixin angular-material-density-mdc($config: null) {
+@mixin angular-material-mdc-density($config-or-theme) {
+  // In case a theme object has been passed instead of a configuration for
+  // the density system, extract the density config from the theme object.
+  $config: if(_mat-is-theme-object($config-or-theme),
+      mat-get-density-config($config-or-theme), $config-or-theme);
+
+  @if $config == null {
+    @error 'No density configuration specified.';
+  }
+
   @include angular-material-mdc-theme((
     color: null,
     typography: null,

src/material-experimental/mdc-typography/_all-typography.scss

@@ -1,6 +1,10 @@
 @import '../mdc-theming/all-theme';
 
-@mixin angular-material-mdc-typography($config: null) {
+@mixin angular-material-mdc-typography($config-or-theme: null) {
+  $config: if(_mat-is-theme-object($config-or-theme),
+      mat-get-typography-config($config-or-theme), $config-or-theme);
+
+  // If no actual color configuration has been specified, create a default one.
   @if $config == null {
     $config: mat-typography-config();
   }

src/material/core/_core-theme.scss

@@ -0,0 +1,48 @@
+@import './theming/theming';
+@import './style/elevation';
+@import './ripple/ripple';
+@import './option/option-theme';
+@import './option/optgroup-theme';
+@import './selection/pseudo-checkbox/pseudo-checkbox-theme';
+
+@mixin mat-core-color($config) {
+  // Wrapper element that provides the theme background when the user's content isn't
+  // inside of a `mat-sidenav-container`. Note that we need to exclude the ampersand
+  // selector in case the mixin is included at the top level.
+  .mat-app-background#{if(&, ', &.mat-app-background', '')} {
+    $background: map-get($config, background);
+    $foreground: map-get($config, foreground);
+
+    background-color: mat-color($background, background);
+    color: mat-color($foreground, text);
+  }
+
+  // Provides external CSS classes for each elevation value. Each CSS class is formatted as
+  // `mat-elevation-z$zValue` where `$zValue` corresponds to the z-space to which the element is
+  // elevated.
+  @for $zValue from 0 through 24 {
+    .#{$_mat-elevation-prefix}#{$zValue} {
+      @include _mat-theme-elevation($zValue, $config);
+    }
+  }
+
+  // Marker that is used to determine whether the user has added a theme to their page.
+  @at-root {
+    .mat-theme-loaded-marker {
+      display: none;
+    }
+  }
+}
+
+// Mixin that renders all of the core styles that depend on the theme.
+@mixin mat-core-theme($theme) {
+  @include mat-ripple-theme($theme);
+  @include mat-option-theme($theme);
+  @include mat-optgroup-theme($theme);
+  @include mat-pseudo-checkbox-theme($theme);
+
+  $color: mat-get-color-config($theme);
+  @if $color != null {
+    @include mat-core-color($color);
+  }
+}