prototype(slide-toggle): create prototype menu based on MDC Web (#15893)

Creates a prototype of `mat-slide-toggle` that uses MDC web.

Author: crisbeto

e2e/components/mdc-slide-toggle-e2e.spec.ts

@@ -1 +1,75 @@
-// TODO: copy tests from existing mat-slide-toggle, update as necessary to fix.
+import {browser, element, by, Key} from 'protractor';
+import {expectToExist} from '../util/index';
+
+
+describe('slide-toggle', () => {
+  const getInput = () => element(by.css('#normal-slide-toggle input'));
+  const getNormalToggle = () => element(by.css('#normal-slide-toggle'));
+
+  beforeEach(async () => await browser.get('mdc-slide-toggle'));
+
+  it('should render a slide-toggle', async () => {
+    await expectToExist('mat-slide-toggle');
+  });
+
+  it('should change the checked state on click', async () => {
+    const inputEl = getInput();
+
+    expect(await inputEl.getAttribute('checked'))
+      .toBeFalsy('Expect slide-toggle to be unchecked');
+
+    await getNormalToggle().click();
+
+    expect(await inputEl.getAttribute('checked'))
+      .toBeTruthy('Expect slide-toggle to be checked');
+  });
+
+  it('should change the checked state on click', async () => {
+    const inputEl = getInput();
+
+    expect(await inputEl.getAttribute('checked'))
+      .toBeFalsy('Expect slide-toggle to be unchecked');
+
+    await getNormalToggle().click();
+
+    expect(await inputEl.getAttribute('checked'))
+      .toBeTruthy('Expect slide-toggle to be checked');
+  });
+
+  it('should not change the checked state on click when disabled', async () => {
+    const inputEl = getInput();
+
+    expect(await inputEl.getAttribute('checked'))
+      .toBeFalsy('Expect slide-toggle to be unchecked');
+
+    await element(by.css('#disabled-slide-toggle')).click();
+
+    expect(await inputEl.getAttribute('checked'))
+      .toBeFalsy('Expect slide-toggle to be unchecked');
+  });
+
+  it('should move the thumb on state change', async () => {
+    const slideToggleEl = getNormalToggle();
+    const thumbEl = element(by.css('#normal-slide-toggle .mdc-switch__thumb-underlay'));
+    const previousPosition = await thumbEl.getLocation();
+
+    await slideToggleEl.click();
+
+    const position = await thumbEl.getLocation();
+
+    expect(position.x).not.toBe(previousPosition.x);
+  });
+
+  it('should toggle the slide-toggle on space key', async () => {
+    const inputEl = getInput();
+
+    expect(await inputEl.getAttribute('checked'))
+      .toBeFalsy('Expect slide-toggle to be unchecked');
+
+    await inputEl.sendKeys(Key.SPACE);
+
+    expect(await inputEl.getAttribute('checked'))
+      .toBeTruthy('Expect slide-toggle to be checked');
+  });
+
+});

src/dev-app/mdc-slide-toggle/mdc-slide-toggle-demo-module.ts

@@ -9,12 +9,14 @@
 import {NgModule} from '@angular/core';
 import {MatSlideToggleModule} from '@angular/material-experimental/mdc-slide-toggle';
 import {RouterModule} from '@angular/router';
+import {FormsModule} from '@angular/forms';
 import {MdcSlideToggleDemo} from './mdc-slide-toggle-demo';
 
 @NgModule({
   imports: [
     MatSlideToggleModule,
     RouterModule.forChild([{path: '', component: MdcSlideToggleDemo}]),
+    FormsModule,
   ],
   declarations: [MdcSlideToggleDemo],
 })

src/dev-app/mdc-slide-toggle/mdc-slide-toggle-demo.html

@@ -1,2 +1,29 @@
-<!-- TODO: copy in demo template from existing mat-slide-toggle demo. -->
-Not yet implemented.
+<div class="demo-slide-toggle">
+
+  <mat-slide-toggle color="primary" [(ngModel)]="firstToggle">
+    Default Slide Toggle
+  </mat-slide-toggle>
+
+  <mat-slide-toggle [(ngModel)]="firstToggle" disabled>
+    Disabled Slide Toggle
+  </mat-slide-toggle>
+
+  <mat-slide-toggle [disabled]="firstToggle">
+    Disable Bound
+  </mat-slide-toggle>
+
+  <p>Example where the slide toggle is required inside of a form.</p>
+
+  <form #form="ngForm" (ngSubmit)="onFormSubmit()" ngNativeValidate>
+
+    <mat-slide-toggle name="slideToggle" required ngModel>
+      Slide Toggle
+    </mat-slide-toggle>
+
+    <p>
+      <button mat-raised-button type="submit">Submit Form</button>
+    </p>
+
+  </form>
+
+</div>

src/dev-app/mdc-slide-toggle/mdc-slide-toggle-demo.scss

@@ -1 +1,9 @@
-// TODO: copy in demo styles from existing mat-slide-toggle demo.
+.demo-slide-toggle {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+
+  mat-slide-toggle {
+    margin: 6px 0;
+  }
+}

src/dev-app/mdc-slide-toggle/mdc-slide-toggle-demo.ts

@@ -15,4 +15,9 @@ import {Component} from '@angular/core';
   styleUrls: ['mdc-slide-toggle-demo.css'],
 })
 export class MdcSlideToggleDemo {
+  firstToggle: boolean;
+
+  onFormSubmit() {
+    alert(`You submitted the form.`);
+  }
 }

src/e2e-app/mdc-slide-toggle/mdc-slide-toggle-e2e.html

@@ -1 +1,2 @@
-<!-- TODO: copy implementation from existing mat-slide-toggle e2e page. -->
+<mat-slide-toggle id="normal-slide-toggle">Slide Toggle</mat-slide-toggle>
+<mat-slide-toggle id="disabled-slide-toggle" disabled>Disabled Slide Toggle</mat-slide-toggle>

src/e2e-app/mdc-slide-toggle/mdc-slide-toggle-e2e.ts

@@ -13,6 +13,4 @@ import {Component} from '@angular/core';
   selector: 'mdc-slide-toggle-e2e',
   templateUrl: 'mdc-slide-toggle-e2e.html',
 })
-export class MdcSlideToggleE2e {
-  // TODO: copy implementation from existing mat-slide-toggle e2e page.
-}
+export class MdcSlideToggleE2e {}

src/material-experimental/mdc-slide-toggle/BUILD.bazel

@@ -10,6 +10,10 @@ ng_module(
   module_name = "@angular/material-experimental/mdc-slide-toggle",
   assets = [":slide_toggle_scss"] + glob(["**/*.html"]),
   deps = [
+    "@npm//@angular/common",
+    "@npm//@angular/core",
+    "@npm//@angular/forms",
+    "@npm//@angular/animations",
     "@npm//material-components-web",
   ] + CDK_TARGETS + MATERIAL_TARGETS,
 )
@@ -20,10 +24,18 @@ sass_library(
   deps = [
     "//src/material/core:core_scss_lib",
     "//src/material-experimental/mdc-helpers:mdc_helpers_scss_lib",
+    "//src/material-experimental/mdc-helpers:mdc_scss_deps_lib",
   ],
 )
 
 sass_binary(
   name = "slide_toggle_scss",
   src = "slide-toggle.scss",
+  include_paths = [
+    "external/npm/node_modules",
+  ],
+  deps = [
+    ":slide_toggle_scss_lib",
+    "//src/material-experimental/mdc-helpers:mdc_scss_deps_lib",
+  ]
 )

src/material-experimental/mdc-slide-toggle/README.md

@@ -1 +1,93 @@
-This is a placeholder for the MDC-based implementation of slide toggle.
+This is prototype of an alternate version of `<mat-slide-toggle>` built on top of
+[MDC Web](https://github.com/material-components/material-components-web). It demonstrates how
+Angular Material could use MDC Web under the hood while still exposing the same API Angular users as
+the existing `<mat-slide-toggle>`. This component is 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
+component by following these steps:
+
+1. Install Angular Material Experimental & MDC WEB:
+
+   ```bash
+   npm i material-components-web @angular/material-experimental
+   ```
+
+2. In your `angular.json`, make sure `node_modules/` is listed as a Sass include path. This is
+   needed for the Sass compiler to be able to find the MDC Web Sass files.
+
+   ```json
+   ...
+   "styles": [
+     "src/styles.scss"
+   ],
+   "stylePreprocessorOptions": {
+     "includePaths": [
+       "node_modules/"
+     ]
+   },
+   ...
+   ```
+
+3. Import the experimental `MatSlideToggleModule` and add it to the module that declares your
+   component:
+
+   ```ts
+   import {MatSlideToggleModule} from '@angular/material-experimental/mdc-slide-toggle';
+
+   @NgModule({
+     declarations: [MyComponent],
+     imports: [MatSlideToggleModule],
+   })
+   export class MyModule {}
+   ```
+
+4. Add use `<mat-slide-toggle>` in your component's template, just like you would the normal
+   `<mat-slide-toggle>`:
+
+   ```html
+   <mat-slide-toggle [checked]="isChecked">Toggle me</mat-slide-toggle>
+   ```
+
+5. Add the theme and typography mixins to your Sass. (There is currently no pre-built CSS option for
+   the experimental `<mat-slide-toggle>`):
+
+   ```scss
+   @import '~@angular/material/theming';
+   @import '~@angular/material-experimental/mdc-slide-toggle';
+
+   $my-primary: mat-palette($mat-indigo);
+   $my-accent:  mat-palette($mat-pink, A200, A100, A400);
+   $my-theme:   mat-light-theme($my-primary, $my-accent);
+
+   @include mat-slide-toggle-theme-mdc($my-theme);
+   @include mat-slide-toggle-typography-mdc();
+   ```
+
+## API differences
+The experimental slide toggle API closely matches the
+[API of the standard slide toggle](https://material.angular.io/components/slide-toggle/api).
+`@angular/material-experimental/mdc-slide-toggle` exports symbols with the same name and public
+interface as all of the symbols found under `@angular/material/slide-toggle`, except for the
+following differences:
+
+* The MDC-based `mat-slide-toggle` drops the dependency on Hammer.js and as a result doesn't support
+dragging gestures.
+* As a result of dragging gestures not being supported, the `dragChange` event won't emit.
+
+## Replacing the standard slide toggle in an existing app
+Because the experimental API mirrors the API for the standard slide toggle, it can easily be swapped
+in by just changing the import paths. There is currently no schematic for this, but you can run the
+following string replace across your TypeScript files:
+
+```bash
+grep -lr --include="*.ts" --exclude-dir="node_modules" \
+  --exclude="*.d.ts" "['\"]@angular/material/slide-toggle['\"]" | xargs sed -i \
+  "s/['\"]@angular\/material\/slide-toggle['\"]/'@angular\/material-experimental\/mdc-slide-toggle'/g"
+```
+
+CSS styles and tests that depend on implementation details of mat-slide-toggle (such as getting
+elements from the template by class name) will need to be manually updated.
+
+There are some small visual differences between this slide and the standard mat-slide. This
+slide has a slightly larger ripple and different spacing between the label and the toggle.

src/material-experimental/mdc-slide-toggle/_mdc-slide-toggle.scss

@@ -1,13 +1,70 @@
+@import '@material/switch/mixins';
+@import '@material/switch/variables';
+@import '@material/form-field/mixins';
+@import '@material/ripple/variables';
+@import '@material/theme/functions';
 @import '../mdc-helpers/mdc-helpers';
 
 @mixin mat-slide-toggle-theme-mdc($theme) {
+  $primary: mat-color(map-get($theme, primary));
+  $accent: mat-color(map-get($theme, accent));
+  $warn: mat-color(map-get($theme, warn));
+
+  // Save original values of MDC global variables. We need to save these so we can restore the
+  // variables to their original values and prevent unintended side effects from using this mixin.
+  $orig-mdc-switch-baseline-theme-color: $mdc-switch-baseline-theme-color;
+
   @include mat-using-mdc-theme($theme) {
-    // TODO: MDC theme styles here.
+    $mdc-switch-baseline-theme-color: primary !global;
+
+    @include mdc-switch-without-ripple($query: $mat-theme-styles-query);
+    @include mdc-form-field-core-styles($query: $mat-theme-styles-query);
+
+    // MDC's switch doesn't support a `color` property. We add support
+    // for it by adding a CSS class for accent and warn style.
+    .mat-mdc-slide-toggle {
+      .mdc-switch__thumb-underlay::before, .mat-ripple-element {
+        background: $mdc-switch-toggled-off-ripple-color;
+      }
+
+      &.mat-accent {
+        $mdc-switch-baseline-theme-color: secondary !global;
+        @include mdc-switch-without-ripple($query: $mat-theme-styles-query);
+      }
+
+      &.mat-warn {
+        $mdc-switch-baseline-theme-color: error !global;
+        @include mdc-switch-without-ripple($query: $mat-theme-styles-query);
+      }
+    }
+
+    // The ripple color matches the palette only when it's checked.
+    .mat-mdc-slide-toggle-checked {
+      .mdc-switch__thumb-underlay::before, .mat-ripple-element {
+        background: $primary;
+      }
+
+      &.mat-accent {
+        .mdc-switch__thumb-underlay::before, .mat-ripple-element {
+          background: $accent;
+        }
+      }
+
+      &.mat-warn {
+        .mdc-switch__thumb-underlay::before, .mat-ripple-element {
+          background: $warn;
+        }
+      }
+    }
   }
+
+  // Restore original values of MDC global variables.
+  $mdc-switch-baseline-theme-color: $orig-mdc-switch-baseline-theme-color !global;
 }
 
 @mixin mat-slide-toggle-typography-mdc($config) {
   @include mat-using-mdc-typography($config) {
-    // TODO: MDC typography styles here.
+    @include mdc-switch-without-ripple($query: $mat-typography-styles-query);
+    @include mdc-form-field-core-styles($query: $mat-typography-styles-query);
   }
 }