feat(switch): Merge updated switch into master (#3214)

BREAKING CHANGE: MDC Switch DOM structure and Sass APIs have changed, and JavaScript APIs have been added. See the documentation for more information. Fixes #2825
material-components · Jul 27, 2018 · 19724f1 · 19724f1
1 parent b95d4e7
commit 19724f1
Show file tree

Hide file tree

Showing 25 changed files with 1,214 additions and 208 deletions.
diff --git a/demos/switch.html b/demos/switch.html
@@ -18,6 +18,7 @@
   <head>
     <meta charset="utf-8">
     <title>Switch - Material Components Catalog</title>
+    <script src="/ready.js"></script>
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <link rel="icon" type="image/png" href="/images/logo_components_color_2x_web_48dp.png">
     <link rel="stylesheet" href="/assets/switch.css">
@@ -63,9 +64,11 @@
       <div class="demo-wrapper">
         <section class="hero">
           <div class="mdc-switch">
-            <input type="checkbox" class="mdc-switch__native-control" role="switch">
-            <div class="mdc-switch__background">
-              <div class="mdc-switch__knob"></div>
+            <div class="mdc-switch__track"></div>
+            <div class="mdc-switch__thumb-underlay">
+              <div class="mdc-switch__thumb">
+                <input type="checkbox" class="mdc-switch__native-control" role="switch">
+              </div>
             </div>
           </div>
         </section>
@@ -74,21 +77,25 @@
           <h2>Enabled</h2>
           <div class="demo-switch-wrapper">
             <div class="mdc-switch">
-              <input type="checkbox" id="basic-switch" class="mdc-switch__native-control" role="switch">
-              <div class="mdc-switch__background">
-                <div class="mdc-switch__knob"></div>
+              <div class="mdc-switch__track"></div>
+              <div class="mdc-switch__thumb-underlay">
+                <div class="mdc-switch__thumb">
+                  <input type="checkbox" id="basic-switch" class="mdc-switch__native-control" role="switch">
+                </div>
               </div>
             </div>
             <label for="basic-switch" class="mdc-switch-label">off/on</label>
           </div>
           <div class="demo-switch-wrapper">
-            <div class="mdc-switch demo-switch--custom">
-              <input type="checkbox"
-                    id="basic-switch-custom"
-                    class="mdc-switch__native-control"
-                    role="switch" checked>
-              <div class="mdc-switch__background">
-                <div class="mdc-switch__knob"></div>
+            <div class="mdc-switch demo-switch--custom mdc-switch--checked">
+              <div class="mdc-switch__track"></div>
+              <div class="mdc-switch__thumb-underlay">
+                <div class="mdc-switch__thumb">
+                  <input type="checkbox"
+                  id="basic-switch-custom"
+                  class="mdc-switch__native-control"
+                  role="switch" checked>
+                </div>
               </div>
             </div>
             <label for="basic-switch-custom" class="mdc-switch-label">custom color</label>
@@ -97,14 +104,16 @@ <h2>Enabled</h2>
         <section class="example">
           <h2>Disabled</h2>
           <div class="demo-switch-wrapper">
-            <div class="mdc-switch">
-              <input type="checkbox"
-                    id="basic-switch--disabled"
-                    class="mdc-switch__native-control"
-                    role="switch"
-                    disabled>
-              <div class="mdc-switch__background">
-                <div class="mdc-switch__knob"></div>
+            <div class="mdc-switch mdc-switch--disabled">
+              <div class="mdc-switch__track"></div>
+              <div class="mdc-switch__thumb-underlay">
+                <div class="mdc-switch__thumb">
+                  <input type="checkbox"
+                  id="basic-switch--disabled"
+                  class="mdc-switch__native-control"
+                  role="switch"
+                  disabled>
+                </div>
               </div>
             </div>
             <label for="basic-switch--disabled" class="mdc-switch-label">off/on</label>
@@ -134,10 +143,16 @@ <h2>Disabled</h2>
 
     <script src="/assets/material-components-web.js" async></script>
     <script>
-      const demoWrapper = document.querySelector('.demo-wrapper');
+      var demoWrapper = document.querySelector('.demo-wrapper');
       document.getElementById('toggle-rtl').addEventListener('change', function() {
         this.checked ? demoWrapper.setAttribute('dir', 'rtl') : demoWrapper.removeAttribute('dir');
       });
+      demoReady(function() {
+        var switches = document.querySelectorAll('.mdc-switch');
+        for (var i = 0, switchEl; switchEl = switches[i]; i++) {
+          var switchInstance = new mdc.switchControl.MDCSwitch(switchEl);
+        }
+      });
     </script>
   </body>
 </html>
diff --git a/demos/switch.scss b/demos/switch.scss
@@ -28,9 +28,7 @@
 .demo-switch--custom {
   $color: $material-color-red-500;
 
-  @include mdc-switch-track-color($color);
-  @include mdc-switch-knob-color($color);
-  @include mdc-switch-focus-indicator-color($color);
+  @include mdc-switch-toggled-on-color($color);
 }
 
 .rtl-toggle {

diff --git a/demos/theme/index.html b/demos/theme/index.html
@@ -677,19 +677,23 @@ <h3 class="mdc-typography--headline5 demo-component-section__heading">
         </h3>
 
         <fieldset class="demo-switch-wrapper">
-          <div class="mdc-switch">
-            <input type="checkbox" id="basic-switch" class="mdc-switch__native-control" role="switch" checked>
-            <div class="mdc-switch__background">
-              <div class="mdc-switch__knob"></div>
+          <div class="mdc-switch mdc-switch--checked">
+            <div class="mdc-switch__track"></div>
+            <div class="mdc-switch__thumb-underlay">
+              <div class="mdc-switch__thumb">
+                <input type="checkbox" id="basic-switch" class="mdc-switch__native-control" role="switch" checked>
+              </div>
             </div>
           </div>
           <label for="basic-switch" class="mdc-switch-label">off/on</label>
         </fieldset>
         <fieldset class="demo-switch-wrapper" disabled>
-          <div class="mdc-switch">
-            <input type="checkbox" id="disabled-switch" class="mdc-switch__native-control" role="switch" checked>
-            <div class="mdc-switch__background">
-              <div class="mdc-switch__knob"></div>
+          <div class="mdc-switch mdc-switch--checked mdc-switch--disabled">
+            <div class="mdc-switch__track"></div>
+            <div class="mdc-switch__thumb-underlay">
+              <div class="mdc-switch__thumb">
+                <input type="checkbox" id="disabled-switch" class="mdc-switch__native-control" role="switch" checked>
+              </div>
             </div>
           </div>
           <label for="disabled-switch" class="mdc-switch-label">disabled</label>
@@ -933,6 +937,14 @@ <h3 class="mdc-typography--headline5 demo-component-section__heading">
           mdc.slider.MDCSlider.attachTo(slider);
         });
 
+        /*
+         * Switch
+         */
+
+        [].forEach.call(document.querySelectorAll('.mdc-switch'), function(switchEl) {
+            mdc.switchComponent.MDCSwitch.attachTo(switchEl);
+        });
+
         /*
          * Tab Bar
          */

diff --git a/package.json b/package.json
@@ -225,6 +225,7 @@
     "mdc-ripple",
     "mdc-selection-control",
     "mdc-slider",
+    "mdc-switch",
     "mdc-tab",
     "mdc-textfield",
     "mdc-top-app-bar"

diff --git a/packages/material-components-web/README.md b/packages/material-components-web/README.md
@@ -27,6 +27,8 @@ import { checkbox } from 'material-components-web';
 const checkbox = new checkbox.MDCCheckbox(document.querySelector('.mdc-checkbox'));
 ```
 
+> NOTE: Since switch is a reserved word in JS, switch is instead named `switchControl`. 
+
 > NOTE: Built CSS files as well as UMD JS bundles will be available as part of the package
 > post-alpha.
 

diff --git a/packages/material-components-web/index.js b/packages/material-components-web/index.js
@@ -36,6 +36,7 @@ import * as select from '@material/select/index';
 import * as selectionControl from '@material/selection-control/index';
 import * as slider from '@material/slider/index';
 import * as snackbar from '@material/snackbar/index';
+import * as switchControl from '@material/switch/index';
 import * as tabs from '@material/tabs/index';
 import * as textField from '@material/textfield/index';
 import * as toolbar from '@material/toolbar/index';
@@ -66,6 +67,7 @@ autoInit.register('MDCTextField', textField.MDCTextField);
 autoInit.register('MDCMenu', menu.MDCMenu);
 autoInit.register('MDCSelect', select.MDCSelect);
 autoInit.register('MDCSlider', slider.MDCSlider);
+autoInit.register('MDCSwitch', switchControl.MDCSwitch);
 autoInit.register('MDCToolbar', toolbar.MDCToolbar);
 autoInit.register('MDCTopAppBar', topAppBar.MDCTopAppBar);
 
@@ -92,6 +94,7 @@ export {
   select,
   selectionControl,
   slider,
+  switchControl,
   snackbar,
   tabs,
   textField,

diff --git a/packages/mdc-switch/README.md b/packages/mdc-switch/README.md
@@ -15,7 +15,7 @@ path: /catalog/input-controls/switches/
   </a>
 </div>-->
 
-Switches toggle the state of a single settings option on or off, and are mobile preferred.
+Switches toggle the state of a single setting on or off. They are the preferred way to adjust settings on mobile.
 
 ## Design & API Documentation
 
@@ -40,24 +40,47 @@ npm install @material/switch
 
 ```html
 <div class="mdc-switch">
-  <input type="checkbox" id="basic-switch" class="mdc-switch__native-control" role="switch">
-  <div class="mdc-switch__background">
-    <div class="mdc-switch__knob"></div>
+  <div class="mdc-switch__track"></div>
+  <div class="mdc-switch__thumb-underlay">
+    <div class="mdc-switch__thumb">
+        <input type="checkbox" id="basic-switch" class="mdc-switch__native-control" role="switch">
+    </div>
   </div>
 </div>
 <label for="basic-switch">off/on</label>
 ```
+
+### Styles
+
+```scss
+@import "@material/switch/mdc-switch";
+```
+
+### JavaScript Instantiation
+
+The Switch requires JavaScript to function, so it is necessary to instantiate MDCSwitch with the HTML.
+
+```js
+import {MDCSwitch} from '@material/switch';
+
+const switchControl = new MDCSwitch(document.querySelector('.mdc-switch'));
+```
+
+> See [Importing the JS component](../../docs/importing-js.md) for more information on how to import JavaScript.
+
 ## Variant
 
 ### Disabled Switch
 
-Users can add the `disabled` attribute directly to the `<input>` element or a parent `<fieldset>` element to disable a switch.
+Users can add the class 'mdc-switch--disabled' to the 'mdc-switch' element to disable the switch.
 
 ```html
-<div class="mdc-switch">
-  <input type="checkbox" id="another-basic-switch" class="mdc-switch__native-control" role="switch" disabled>
-  <div class="mdc-switch__background">
-    <div class="mdc-switch__knob"></div>
+<div class="mdc-switch mdc-switch--disabled">
+  <div class="mdc-switch__track"></div>
+  <div class="mdc-switch__thumb-underlay">
+    <div class="mdc-switch__thumb">
+        <input type="checkbox" id="another-basic-switch" class="mdc-switch__native-control" role="switch" disabled>
+    </div>
   </div>
 </div>
 <label for="another-basic-switch">off/on</label>
@@ -70,17 +93,63 @@ Users can add the `disabled` attribute directly to the `<input>` element or a pa
 CSS Class | Description
 --- | ---
 `mdc-switch` | Mandatory, for the parent element.
-`mdc-switch__native-control` | Mandatory, for the input checkbox.
-`mdc-switch__background` | Mandatory, for the background element.
-`mdc-switch__knob` | Mandatory, for the knob element.
+`mdc-switch__track` | Mandatory, for the track element.
+`mdc-switch__thumb-underlay` | Mandatory, for the ripple effect.
+`mdc-switch__thumb` | Mandatory, for the thumb element.
+`mdc-switch__native-control` | Mandatory, for the hidden input checkbox.
 
 ### Sass Mixins
 
-The following mixins apply only to _enabled_ switches in the _on_ (checked) state.
-It is not currently possible to customize the color of a _disabled_ or _off_ (unchecked) switch.
+MDC Switch uses [MDC Theme](../mdc-theme)'s `secondary` color by default for the checked (toggled on) state.
+Use the following mixins to customize _enabled_ switches. It is not currently possible to customize the color of a
+ _disabled_ switch. Disabled switches use the same colors as enabled switches, but with a different opacity value.
 
 Mixin | Description
 --- | ---
-`mdc-switch-track-color($color)` | Sets the track color.
-`mdc-switch-knob-color($color)` | Sets the knob color.
-`mdc-switch-focus-indicator-color($color)` | Sets the focus indicator color.
+`mdc-switch-toggled-on-color($color)` | Sets the base color of the track, thumb, and ripple when the switch is toggled on.
+`mdc-switch-toggled-off-color($color)` | Sets the base color of the track, thumb, and ripple when the switch is toggled off.
+`mdc-switch-toggled-on-track-color($color)` | Sets color of the track when the switch is toggled on.
+`mdc-switch-toggled-off-track-color($color)` | Sets color of the track when the switch is toggled off.
+`mdc-switch-toggled-on-thumb-color($color)` | Sets color of the thumb when the switch is toggled on.
+`mdc-switch-toggled-off-thumb-color($color)` | Sets color of the thumb when the switch is toggled off.
+`mdc-switch-toggled-on-ripple-color($color)` | Sets the color of the ripple surrounding the thumb when the switch is toggled on.
+`mdc-switch-toggled-off-ripple-color($color)` | Sets the color of the ripple surrounding the thumb when the switch is toggled off.
+
+## `MDCSwitch` Properties and Methods
+
+Property | Value Type | Description
+--- | --- | ---
+`checked` | Boolean | Setter/getter for the switch's checked state
+`disabled` | Boolean | Setter/getter for the switch's disabled state
+
+## Usage within Web Frameworks
+
+If you are using a JavaScript framework, such as React or Angular, you can create a Switch for your framework. Depending on your needs, you can use the _Simple Approach: Wrapping MDC Web Vanilla Components_, or the _Advanced Approach: Using Foundations and Adapters_. Please follow the instructions [here](../../docs/integrating-into-frameworks.md).
+
+### `MDCSwitchAdapter`
+
+| Method Signature | Description |
+| --- | --- |
+| `addClass(className: string) => void` | Adds a class to the root element. |
+| `removeClass(className: string) => void` | Removes a class from the root element. |
+| `setNativeControlChecked(checked: boolean)` | Sets the checked state of the native control. |
+| `isNativeControlChecked() => boolean` | Returns the checked state of the native control. | 
+| `setNativeControlDisabled(disabled: boolean)` | Sets the disabled state of the native control. |
+| `isNativeControlDisabled() => boolean` | Returns the disabled state of the native control. | 
+
+### `MDCSwitchFoundation`
+
+| Method Signature | Description |
+| --- | --- |
+| `isChecked() => boolean` | Returns whether the native control is checked. |
+| `setChecked(checked: boolean) => void` | Sets the checked value of the native control and updates styling to reflect the checked state. |
+| `isDisabled() => boolean` | Returns whether the native control is disabled. |
+| `setDisabled(disabled: boolean) => void` | Sets the disabled value of the native control and updates styling to reflect the disabled state. |
+| `handleChange() => void` | Handles a change event from the native control. |
+
+### `MDCSwitchFoundation` Event Handlers
+If wrapping the switch component it is necessary to add an event handler for native control change events that calls the `handleChange` foundation method. For an example of this, see the [MDCSwitch](index.js) component `initialSyncWithDOM` method.
+
+| Event | Element Selector | Foundation Handler |
+| --- | --- | --- |
+| `change` | `.mdc-switch__native-control` | `handleChange()` |
diff --git a/packages/mdc-switch/_functions.scss b/packages/mdc-switch/_functions.scss
@@ -1,5 +1,5 @@
 //
-// Copyright 2016 Google Inc. All Rights Reserved.
+// Copyright 2018 Google Inc. All Rights Reserved.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.