refactor: remove tilde import usages (#23702)

Removes the tilde imports from all docs and schematics since they're deprecated and they may cause build issues in the future.

Also reworks the theming API migration to handle tilde imports.

Author: crisbeto

guides/duplicate-theming-styles.md

@@ -9,7 +9,7 @@ Below are examples of patterns that generate duplicative theme styles:
 **Example #1**
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 $light-theme: mat.define-light-theme((color: ...));
 $dark-theme: mat.define-dark-theme((color: ...));
@@ -31,7 +31,7 @@ selector. Replace the `all-component-themes` mixin and include the dark theme us
 `all-component-colors` mixin. For example:
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 ...
 @include mat.all-component-themes($light-theme);
@@ -49,7 +49,7 @@ Typography can also be configured via Sass mixin; see `all-component-typographie
 Theme styles could also be duplicated if individual theme mixins are used. For example:
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 @include mat.all-component-themes($my-theme);
 
@@ -63,7 +63,7 @@ To avoid this duplication of styles, use the dedicated mixin for the color syste
 extract the configuration for the color system from the theme.
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 .my-custom-dark-button {
   // This will only generate the color styles for `mat-button`.
@@ -77,7 +77,7 @@ If your application intentionally duplicates styles, a global Sass variable can
 set to disable duplication warnings from Angular Material. For example:
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 mat.$theme-ignore-duplication-warnings: true;
 

guides/elevation.md

@@ -31,7 +31,7 @@ Sass mixin. This mixin accepts a `$zValue` and an optional `$color`. The `$zValu
 box-shadow. You can use the `$color` parameter to further customize the shadow appearance.
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 .my-class-with-default-shadow {
   // Adds a shadow for elevation level 2 with default color and full opacity:
@@ -57,7 +57,7 @@ have a CSS class matching the pattern `mat-elevation-z#`, as described in
 You can use the `elevation-transition` mixin to add a transition when elevation changes.
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 .my-class {
   @include mat.elevation-transition();

guides/theming-your-components.md

@@ -17,7 +17,7 @@ indicating whether dark mode is set.
 
 ```scss
 @use 'sass:map';
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 $color-config:    mat.get-color-config($theme);
 $primary-palette: map.get($color-config, 'primary');
@@ -39,7 +39,7 @@ structure and for APIs for reading values from this config.
 [typography-config]: https://material.angular.io/guide/typography#typography-config
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 $typography-config: mat.get-typography-config($theme);
 $my-font-family: mat.font-family($typography-config);
@@ -123,7 +123,7 @@ theme passed into the mixins.
 // _carousel-theme.scss
 
 @use 'sass:map';
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 @mixin color($theme) {
   // Get the color config from the theme.
@@ -158,7 +158,7 @@ have a config specified.
 // _carousel-theme.scss
 
 @use 'sass:map';
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 @mixin color($theme) {
   // Get the color config from the theme.
@@ -201,7 +201,7 @@ Now that you've defined the carousel component's theme mixin, you can include th
 the other theme mixins in your application.
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 @use './path/to/carousel-theme' as carousel;
 
 @include mat.core();

guides/theming.md

@@ -77,7 +77,7 @@ require these hues, but you can use these hues when defining a theme as describe
 [Defining a theme](#defining-a-theme) below.
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 $my-palette: mat.$indigo-palette;
 ```
@@ -109,7 +109,7 @@ once for your application, even if you define multiple themes. Including the `co
 times will result in duplicate CSS in your application.
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 @include mat.core();
 ```
@@ -127,7 +127,7 @@ Components use these hues to choose the most appropriate color for different par
 themselves.
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 $my-primary: mat.define-palette(mat.$indigo-palette, 500);
 $my-accent: mat.define-palette(mat.$pink-palette, A200, A100, A400);
@@ -141,7 +141,7 @@ the result from `define-palette`. The choice of a light versus a dark theme dete
 background and foreground colors used throughout the components.
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 $my-primary: mat.define-palette(mat.$indigo-palette, 500);
 $my-accent: mat.define-palette(mat.$pink-palette, A200, A100, A400);
@@ -174,7 +174,7 @@ Apply the styles for each of the components used in your application by includin
 theme Sass mixins.
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 @include mat.core();
 
@@ -206,7 +206,7 @@ component mixins, except they emit styles for `core-theme` and _all_ 35+ compone
 Material. Unless your application uses every single component, this will produce unnecessary CSS.
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 @include mat.core();
 
@@ -270,7 +270,7 @@ CSS rule declaration. See the [documentation for Sass mixins][sass-mixins] for f
 [sass-mixins]: https://sass-lang.com/documentation/at-rules/mixin
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 @include mat.core();
 
@@ -323,7 +323,7 @@ The example below shows how to customize the color of all buttons inside element
 `.my-special-section` CSS class.
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 .my-special-section {
  $special-primary: mat.define-palette(mat.$orange-palette);
@@ -343,7 +343,7 @@ number identifier. You can also access the contrast color for a particular hue b
 hue's number idenfier with `-contrast`.
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 $my-palette: mat.define-palette(mat.$indigo-palette);
 
@@ -357,7 +357,7 @@ You can also reference colors using the `"default"`, `"lighter"`, `"darker"`, an
 passed to `define-palette`.
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 $my-palette: mat.define-palette(mat.$indigo-palette);
 
@@ -389,7 +389,7 @@ The following example includes strong focus indicator styles in an application a
 the custom theme API.
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 @include mat.core();
 @include mat.strong-focus-indicators();
@@ -421,7 +421,7 @@ The following example includes strong focus indicator styles with custom setting
 of the custom theme API.
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 @include mat.core();
 @include mat.strong-focus-indicators((

guides/typography.md

@@ -66,7 +66,7 @@ accepts, in order, CSS values for `font-size`, `line-height`, `font-weight`, `fo
 `letter-spacing`. You can also specify the parameters by name, as demonstrated in the example below.
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 $my-custom-level: mat.define-typography-level(
   $font-family: Roboto,
@@ -86,7 +86,7 @@ a typography config with the `define-typography-config` Sass function. Every par
 baseline if unspecified.
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 $my-custom-typography-config: mat.define-typography-config(
   $display-4: mat.define-typography-level(112px, 112px, 300, $letter-spacing: -0.05em),
@@ -102,7 +102,7 @@ To customize component typography for your entire application, you can pass your
 config to the `core` mixin described in the [theming guide][theming-system].
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 $my-custom-typography: mat.define-typography-config(
   $headline:  mat.define-typography-level(3rem, 1, 700),
@@ -128,7 +128,7 @@ the `".kids-theme"` CSS class is present. You can [see the theming guide for mor
 defining multiple themes](https://material.angular.io/guide/theming#defining-multiple-themes).
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 @include mat.core();
 
@@ -169,7 +169,7 @@ component, based on a provided typography config. The following example demonstr
 typography styles only for the button component.
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 $kids-typography: mat.define-typography-config(
   // Specify "Comic Sans" as the default font family for all levels.
@@ -249,7 +249,7 @@ Additionally, you can use the `typography-level` Sass mixin to directly emit the
 given typography level.
 
 ```scss
-@use '~@angular/material' as mat;
+@use '@angular/material' as mat;
 
 // Use the default configuration.
 $my-typography: mat.define-typography-config();

src/cdk/a11y/a11y.md

@@ -179,7 +179,7 @@ the host element with `checkChildren` set to `true`. Each of these directives ha
 ### Styling utilities
 
 The `cdk/a11y` package comes with Sass mixins that produce styles useful for building
-accessible experiences. 
+accessible experiences.
 
 #### Hiding elements in an accessible way
 
@@ -192,7 +192,7 @@ If you're using Angular Material, this class is included automatically by Angula
 system. Otherwise, you can include this mixin in a global stylesheet.
 
 ```scss
-@use '~@angular/cdk';
+@use '@angular/cdk';
 
 @include cdk.a11y-visually-hidden();
 ```
@@ -213,7 +213,7 @@ The mixin works by targeting a CSS class which is added to the `body` by the CDK
 mode is detected at runtime, via the `HighContrastModeDetector` service.
 
 ```scss
-@use '~@angular/cdk';
+@use '@angular/cdk';
 
 button {
   @include cdk.high-contrast() {

src/cdk/overlay/overlay.md

@@ -7,7 +7,7 @@ using the CDK on its own, you'll have to include the styles yourself. You can do
 the prebuilt styles in your global stylesheet:
 
 ```scss
-@import '~@angular/cdk/overlay-prebuilt.css';
+@import '@angular/cdk/overlay-prebuilt.css';
 ```
 
 ### Creating overlays

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

@@ -35,7 +35,7 @@ you are using Angular Material, this CSS is included as part of the `mat-core` m
 using Angular Material, you should include this CSS with the `text-field-autofill` mixin.
 
 ```scss
-@use '~@angular/cdk';
+@use '@angular/cdk';
 
 @include cdk.text-field-autofill();
 ```
@@ -48,7 +48,7 @@ which can be used to set these properties. It takes a `background` value as the
 an optional `color` value as the second parameter.
 
 ```scss
-@use '~@angular/cdk';
+@use '@angular/cdk';
 
 // Set custom autofill inputs to have no background and red text.
 input.custom-autofill {

src/material-experimental/README.md

@@ -52,8 +52,8 @@ 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
-  @use '~@angular/material' as mat;
-  @use '~@angular/material-experimental' as mat-experimental;
+  @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);

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

@@ -57,8 +57,8 @@ component by following these steps:
    the experimental `<mat-autocomplete>`):
 
    ```scss
-   @use '~@angular/material' as mat;
-   @use '~@angular/material-experimental' as mat-experimental;
+   @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);