docs: switch remaining docs to @use (#22527)

Updates all of the remaining docs to go through the new `@use` API instead of `@import`.

**Note:** does not include the `mdc-button` readme, because the necessary mixins aren't exported yet. See #22449.

(cherry picked from commit 1def768)

Author: crisbeto

src/cdk/text-field/text-field.md

@@ -32,26 +32,26 @@ changes.
 
 Note: This service requires some CSS to install animation hooks when the autofill statechanges. If
 you are using Angular Material, this CSS is included as part of the `mat-core` mixin. If you are not
-using Angular Material, you should include this CSS with the `cdk-text-field` mixin.
+using Angular Material, you should include this CSS with the `text-field-autofill` mixin.
 
 ```scss
-@import '~@angular/cdk/text-field/text-field'; 
+@use '~@angular/cdk';
 
-@include cdk-text-field();
+@include cdk.text-field-autofill();
 ```
 
 ### Styling the autofill state of an `<input>`
 
 It can be difficult to override the browser default `background` and `color` properties on an
-autofilled `<input>`. To make this simpler, the CDK includes a mixin `cdk-text-field-autofill-color`
+autofilled `<input>`. To make this simpler, the CDK includes a mixin `text-field-autofill-color`
 which can be used to set these properties. It takes a `background` value as the first parameter and
 an optional `color` value as the second parameter.
 
 ```scss
-@import '~@angular/cdk/text-field/text-field'; 
+@use '~@angular/cdk';
 
-// Set custom-autofill inputs to have no background and red text.
+// Set custom autofill inputs to have no background and red text.
 input.custom-autofill {
-  @include cdk-text-field-autofill-color(transparent, red);
+  @include cdk.text-field-autofill-color(transparent, red);
 }
 ```

src/material-experimental/README.md

@@ -29,7 +29,7 @@ component by following these steps:
    },
    ...
    ```
-   
+
 3. Import the `NgModule` for the component you want to use. For example, the checkbox:
 ```ts
   import {MatCheckboxModule} from '@angular/material-experimental/mdc-checkbox';
@@ -42,7 +42,7 @@ component by following these steps:
 ```
 
 4. Add use the components just as you would the normal Angular Material components. For example,
-the checkbox: 
+the checkbox:
 ```html
   <mat-checkbox [checked]="isChecked">Check me</mat-checkbox>
 ```
@@ -52,23 +52,23 @@ mixins except that they are suffixed with `-mdc`. Some experimental components m
 be included in the pre-built CSS mixin and will need to be explicitly included.
 
 ```scss
-  @import '~@angular/material/theming';
-  @import '~@angular/material-experimental/mdc-theming/all-theme';
-  
-  $my-primary: mat-palette($mat-indigo);
-  $my-accent:  mat-palette($mat-pink, A200, A100, A400);
-  $my-theme:   mat-light-theme((
+  @use '~@angular/material' as mat;
+  @use '~@angular/material-experimental' as mat-experimental;
+
+  $my-primary: mat.define-palette(mat.$indigo-palette);
+  $my-accent: mat.define-palette(mat.$pink-palette, A200, A100, A400);
+  $my-theme: mat.define-light-theme((
     color: (
-      primary: $my-primary, 
+      primary: $my-primary,
       accent: $my-accent
     ),
-    // Using `mat-mdc-typography-config` rather than `mat-typography-config` generates a typography
-    // config directly from the official Material Design styles. This includes using `rem`-based
-    // measurements rather than `px`-based ones as the spec recommends. 
-    typography: mat-mdc-typography-config(),
+    // Using `define-mdc-typography-config` rather than `define-typography-config` generates a
+    // typography config directly from the official Material Design styles. This includes using
+    // `rem`-based measurements rather than `px`-based ones as the spec recommends.
+    typography: mat-experimental.define-mdc-typography-config(),
     // The density level to use in this theme, defaults to 0 if not specified.
     density: 0
   ));
 
-  @include angular-material-mdc-theme($my-theme);
+  @include mat-experimental.all-mdc-component-themes($my-theme);
 ```

src/material-experimental/mdc-autocomplete/README.md

@@ -57,20 +57,20 @@ component by following these steps:
    the experimental `<mat-autocomplete>`):
 
    ```scss
-   @import '~@angular/material/theming';
-   @import '~@angular/material-experimental/mdc-autocomplete/autocomplete-theme';
+   @use '~@angular/material' as mat;
+   @use '~@angular/material-experimental' as mat-experimental;
 
-   $my-primary: mat-palette($mat-indigo);
-   $my-accent:  mat-palette($mat-pink, A200, A100, A400);
-   $my-theme:   mat-light-theme((
+   $my-primary: mat.define-palette(mat.$indigo-palette);
+   $my-accent: mat.define-palette(mat.$pink-palette, A200, A100, A400);
+   $my-theme: mat.define-light-theme((
      color: (
        primary: $my-primary,
        accent: $my-accent
      )
    ));
 
-   @include mat-mdc-autocomplete-theme($my-theme);
-   @include mat-mdc-autocomplete-typography($my-theme);
+   @include mat-experimental.mdc-autocomplete-theme($my-theme);
+   @include mat-experimental.mdc-autocomplete-typography($my-theme);
    ```
 
 ## API differences

src/material-experimental/mdc-card/README.md

@@ -3,7 +3,7 @@ This is a prototype of an alternate version of `MatCard` built on top of
 experimental and should not be used in production.
 
 ## How to use
-Assuming your application is already up and running using Angular Material, you can add this 
+Assuming your application is already up and running using Angular Material, you can add this
 component by following these steps:
 
 1. Install `@angular/material-experimental` and MDC Web:
@@ -41,8 +41,8 @@ component by following these steps:
    ```
 
 4. Use the card in your component's template:
-   
-   ```html   
+
+   ```html
    <mat-card>
      <mat-card-title> My Card Title </mat-card-title>
      <mat-card-content>
@@ -53,25 +53,25 @@ component by following these steps:
        <button> Share </button>
      </mat-card-actions>
    </mat-card>
-   ``` 
-   
+   ```
+
 5. Add the theme and typography mixins to your Sass:
 
    ```scss
-   @import '~@angular/material/theming';
-   @import '~@angular/material-experimental/mdc-card/card-theme';
+   @use '~@angular/material' as mat;
+   @use '~@angular/material-experimental' as mat-experimental;
 
-   $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: 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((
      color: (
        primary: $candy-app-primary,
        accent: $candy-app-accent,
      )
    ));
 
 
-   @include mat-mdc-card-theme($candy-app-theme); 
+   @include mat-experimental.mdc-card-theme($candy-app-theme);
    ```
 
 ## API differences

src/material-experimental/mdc-checkbox/README.md

@@ -53,20 +53,20 @@ component by following these steps:
    the experimental `<mat-checkbox>`):
 
    ```scss
-   @import '~@angular/material/theming';
-   @import '~@angular/material-experimental/mdc-checkbox/checkbox-theme';
+   @use '~@angular/material' as mat;
+   @use '~@angular/material-experimental' as mat-experimental;
 
-   $my-primary: mat-palette($mat-indigo);
-   $my-accent:  mat-palette($mat-pink, A200, A100, A400);
-   $my-theme:   mat-light-theme((
+   $my-primary: mat.define-palette(mat.$indigo-palette);
+   $my-accent: mat.define-palette(mat.$pink-palette, A200, A100, A400);
+   $my-theme: mat.define-light-theme((
      color: (
-       primary: $my-primary, 
+       primary: $my-primary,
        accent: $my-accent
      )
    ));
 
-   @include mat-mdc-checkbox-theme($my-theme);
-   @include mat-mdc-checkbox-typography($my-theme);
+   @include mat-experimental.mdc-checkbox-theme($my-theme);
+   @include mat-experimental.mdc-checkbox-typography($my-theme);
    ```
 
 ## API differences

src/material-experimental/mdc-chips/README.md

@@ -50,20 +50,20 @@ Assuming your application is already up and running using Angular Material, you
 5. Add the theme mixins to your Sass:
 
    ```scss
-   @import '~@angular/material/theming';
-   @import '~@angular/material-experimental/mdc-chips/chips-theme';
+   @use '~@angular/material' as mat;
+   @use '~@angular/material-experimental' as mat-experimental;
 
-   $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: 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((
      color: (
        primary: $candy-app-primary,
        accent: $candy-app-accent,
-     ),
+     )
    ));
 
 
-   @include mat-mdc-chips-theme($candy-app-theme);
+   @include mat-experimental.mdc-chips-theme($candy-app-theme);
    ```
 
 ## API differences

src/material-experimental/mdc-dialog/README.md

@@ -43,7 +43,7 @@ component by following these steps:
 
 4. Use the `MatDialog` service in your components by injecting the service, just like you would
    use the normal dialog.
-   
+
 5. Ensure color and typography styles for `@angular/material-experimental` are set up. Either
    use a custom theme and use the `mat-mdc-dialog-theme` mixin, or use a prebuilt theme
    from `@angular/material-experimental/mdc-theming/prebuilt`.
@@ -57,7 +57,7 @@ longer has outer padding by default.
 If content elements such as `matDialogContent` or `matDialogTitle` are used though, the MDC dialog
 will display as with the current non-experimental dialog. The padding change will only surface if
 you have custom content within the dialog that is not wrapped with `matDialogContent`,
-`matDialogActions` or `matDialogTitle`. 
+`matDialogActions` or `matDialogTitle`.
 
 We provide a backwards compatibility mixin that re-adds the outer padding. The use of this mixin
 is generally not recommended as it results in inefficient CSS for the dialog because padding from
@@ -67,7 +67,7 @@ directly through CSS, or move them into one of the defined sections the Angular
 provides.
 
 ```scss
-@import '@angular/material-experimental/mdc-dialog/dialog-legacy-padding';
+@use '@angular/material-experimental/mdc-dialog/dialog-legacy-padding' as mat-mdc-dialog;
 
-@include mat-mdc-dialog-legacy-padding();
+@include mat-mdc-dialog.legacy-padding();
 ```

src/material-experimental/mdc-menu/README.md

@@ -57,20 +57,20 @@ component by following these steps:
    the experimental `<mat-menu>`):
 
    ```scss
-   @import '~@angular/material/theming';
-   @import '~@angular/material-experimental/mdc-menu/menu-theme';
+   @use '~@angular/material' as mat;
+   @use '~@angular/material-experimental' as mat-experimental;
 
-   $my-primary: mat-palette($mat-indigo);
-   $my-accent:  mat-palette($mat-pink, A200, A100, A400);
-   $my-theme:   mat-light-theme((
+   $my-primary: mat.define-palette(mat.$indigo-palette);
+   $my-accent: mat.define-palette(mat.$pink-palette, A200, A100, A400);
+   $my-theme: mat.define-light-theme((
      color: (
-       primary: $my-primary, 
+       primary: $my-primary,
        accent: $my-accent
      )
    ));
 
-   @include mat-mdc-menu-theme($my-theme);
-   @include mat-mdc-menu-typography($my-theme);
+   @include mat-experimental.mdc-menu-theme($my-theme);
+   @include mat-experimental.mdc-menu-typography($my-theme);
    ```
 
 ## API differences

src/material-experimental/mdc-paginator/README.md

@@ -53,20 +53,20 @@ component by following these steps:
    the experimental `<mat-paginator>`):
 
    ```scss
-   @import '~@angular/material/theming';
-   @import '~@angular/material-experimental/mdc-paginator/paginator-theme';
+   @use '~@angular/material' as mat;
+   @use '~@angular/material-experimental' as mat-experimental;
 
-   $my-primary: mat-palette($mat-indigo);
-   $my-accent:  mat-palette($mat-pink, A200, A100, A400);
-   $my-theme:   mat-light-theme((
+   $my-primary: mat.define-palette(mat.$indigo-palette);
+   $my-accent: mat.define-palette(mat.$pink-palette, A200, A100, A400);
+   $my-theme: mat.define-light-theme((
      color: (
        primary: $my-primary,
        accent: $my-accent
      )
    ));
 
-   @include mat-mdc-paginator-theme($my-theme);
-   @include mat-mdc-paginator-typography($my-theme);
+   @include mat-experimental.mdc-paginator-theme($my-theme);
+   @include mat-experimental.mdc-paginator-typography($my-theme);
    ```
 
 ## API differences

src/material-experimental/mdc-progress-bar/README.md

@@ -54,20 +54,20 @@ component by following these steps:
    the experimental `<mat-progress-bar>`):
 
    ```scss
-   @import '~@angular/material/theming';
-   @import '~@angular/material-experimental/mdc-progress-bar/progress-bar-theme';
+   @use '~@angular/material' as mat;
+   @use '~@angular/material-experimental' as mat-experimental;
 
-   $my-primary: mat-palette($mat-indigo);
-   $my-accent:  mat-palette($mat-pink, A200, A100, A400);
-   $my-theme:   mat-light-theme((
+   $my-primary: mat.define-palette(mat.$indigo-palette);
+   $my-accent: mat.define-palette(mat.$pink-palette, A200, A100, A400);
+   $my-theme: mat.define-light-theme((
      color: (
-       primary: $my-primary, 
+       primary: $my-primary,
        accent: $my-accent
      )
    ));
 
-   @include mat-mdc-progress-bar-theme($my-theme);
-   @include mat-mdc-progress-bar-typography($my-theme);
+   @include mat-experimental.mdc-progress-bar-theme($my-theme);
+   @include mat-experimental.mdc-progress-bar-typography($my-theme);
    ```
 
 ## Replacing the standard progress bar in an existing app

src/material-experimental/mdc-progress-spinner/README.md

@@ -54,20 +54,20 @@ component by following these steps:
    the experimental `<mat-progress-spinner>`):
 
    ```scss
-   @import '~@angular/material/theming';
-   @import '~@angular/material-experimental/mdc-progress-spinner/progress-spinner-theme';
+   @use '~@angular/material' as mat;
+   @use '~@angular/material-experimental' as mat-experimental;
 
-   $my-primary: mat-palette($mat-indigo);
-   $my-accent:  mat-palette($mat-pink, A200, A100, A400);
-   $my-theme:   mat-light-theme((
+   $my-primary: mat.define-palette(mat.$indigo-palette);
+   $my-accent: mat.define-palette(mat.$pink-palette, A200, A100, A400);
+   $my-theme: mat.define-light-theme((
      color: (
-       primary: $my-primary, 
+       primary: $my-primary,
        accent: $my-accent
      )
    ));
 
-   @include mat-mdc-progress-spinner-theme($my-theme);
-   @include mat-mdc-progress-spinner-typography($my-theme);
+   @include mat-experimental.mdc-progress-spinner-theme($my-theme);
+   @include mat-experimental.mdc-progress-spinner-typography($my-theme);
    ```
 
 ## Replacing the standard progress spinner in an existing app