feat(slider): Add M2 version of slider.

BREAKING CHANGE: This upgrades the old slider to a new version of slider that adheres to the M2 design spec. Changes include: - M2 design (primary instead of secondary color used, larger active track and thumb, improved tick marks UI) - Range (two-thumb slider) slider - Pointer events support (for browsers that support pointer events) - High contrast mode support - Improved accessibility (follows WAI-ARIA spec for slider) - Bug fixes PiperOrigin-RevId: 322199406
material-components · Jul 20, 2020 · 8158544 · 8158544
1 parent fb5a4cd
commit 8158544
Show file tree

Hide file tree

Showing 29 changed files with 4,037 additions and 3,889 deletions.
diff --git a/packages/mdc-slider/README.md b/packages/mdc-slider/README.md
@@ -0,0 +1,289 @@
+<!--docs:
+title: "Sliders"
+layout: detail
+section: components
+excerpt: "Sliders allow users to make selections from a range of values."
+iconId: slider
+path: /catalog/input-controls/sliders/
+-->
+
+# Slider
+
+[Sliders](https://material.io/components/sliders/) allow users to make
+selections from a range of values.
+
+The MDC Slider implementation supports both single point sliders (one thumb)
+and range sliders (two thumbs). It is modeled after the browser's
+`<input type="range">` element.
+
+Sliders follow accessibility best practices per the [WAI-ARIA spec](https://www.w3.org/TR/wai-aria-practices/#slider)
+and are fully RTL-aware.
+
+## Contents
+
+*   [Using sliders](#using-sliders)
+*   [Sliders](#sliders)
+*   [Other variants](#other-variants)
+*   [Additional information](#additional-information)
+*   [API](#api)
+
+## Using sliders
+
+### Installing sliders
+
+```
+npm install @material/slider
+```
+
+### Styles
+
+```scss
+@use "@material/slider";
+
+@include slider.core-styles;
+```
+
+### JavaScript instantiation
+
+```js
+import {MDCSlider} from '@material/slider';
+
+const slider = new MDCSlider(document.querySelector('.mdc-slider'));
+```
+
+**Note**: See [Importing the JS component](../../docs/importing-js.md) for more
+information on how to import JavaScript.
+
+## Sliders
+
+There are two types of sliders:
+
+1.  [Continuous slider](#continuous-slider)
+1.  [Discrete slider](#discrete-slider)
+
+### Continuous slider
+
+Continuous sliders allow users to make meaningful selections that don’t require
+a specific value.
+
+<img src="images/continuous-slider.png" alt="Continuous slider with a value of 50">
+
+```html
+<div class="mdc-slider">
+  <div class="mdc-slider__track">
+    <div class="mdc-slider__track--active">
+      <div class="mdc-slider__track--active_fill"></div>
+    </div>
+    <div class="mdc-slider__track--inactive"></div>
+  </div>
+  <div class="mdc-slider__thumb" role="slider" tabindex="0" aria-valuemin="0"
+       aria-valuemax="100" aria-valuenow="50">
+    <div class="mdc-slider__thumb-knob"></div>
+  </div>
+</div>
+```
+
+#### Continuous range slider
+
+<img src="images/continuous-range-slider.png" alt="Continuous range slider with values of 30 and 70">
+
+```html
+<div class="mdc-slider mdc-slider--range">
+  <div class="mdc-slider__track">
+    <div class="mdc-slider__track--active">
+      <div class="mdc-slider__track--active_fill"></div>
+    </div>
+    <div class="mdc-slider__track--inactive"></div>
+  </div>
+  <div class="mdc-slider__thumb" role="slider" tabindex="0" aria-valuemin="0" aria-valuemax="100" aria-valuenow="30">
+    <div class="mdc-slider__thumb-knob"></div>
+  </div>
+  <div class="mdc-slider__thumb" role="slider" tabindex="0" aria-valuemin="0" aria-valuemax="100" aria-valuenow="70">
+    <div class="mdc-slider__thumb-knob"></div>
+  </div>
+</div>
+```
+
+### Discrete slider
+
+Discrete sliders display a numeric value label upon pressing the thumb, which
+allows a user to select an exact value.
+
+<img src="images/discrete-slider.png" alt="Discrete slider with a value of 50">
+
+To create a discrete slider, add the following:
+
+*   `mdc-slider--discrete` class on the root element.
+*   `data-step` attribute on the root element. This will be the step size for
+    value quantization. If not set, the default is 1.
+*   Value indicator element (`mdc-slider__value-indicator-container`), as shown
+    below.
+
+```html
+<div class="mdc-slider mdc-slider--discrete" data-step="10">
+  <div class="mdc-slider__track">
+    <div class="mdc-slider__track--active">
+      <div class="mdc-slider__track--active_fill"></div>
+    </div>
+    <div class="mdc-slider__track--inactive"></div>
+  </div>
+  <div class="mdc-slider__thumb" role="slider" tabindex="0" aria-valuemin="0" aria-valuemax="100" aria-valuenow="50">
+    <div class="mdc-slider__value-indicator-container">
+      <div class="mdc-slider__value-indicator">
+        <span class="mdc-slider__value-indicator-text">
+          50
+        </span>
+      </div>
+    </div>
+    <div class="mdc-slider__thumb-knob"></div>
+  </div>
+</div>
+```
+
+#### Discrete slider with tick marks
+
+Discrete sliders can optionally display tick marks. Tick marks represent
+predetermined values to which the user can move the slider.
+
+<img src="images/discrete-slider-tick-marks.png" alt="Discrete slider (with tick marks), with a value of 50">
+
+To add tick marks to a discrete slider, add the following:
+
+*   `mdc-slider--tick-marks` class on the root element
+
+```html
+<div class="mdc-slider mdc-slider--discrete mdc-slider--tick-marks" data-step="10">
+  <div class="mdc-slider__track">
+    <div class="mdc-slider__track--active">
+      <div class="mdc-slider__track--active_fill"></div>
+    </div>
+    <div class="mdc-slider__track--inactive"></div>
+  </div>
+  <div class="mdc-slider__thumb" role="slider" tabindex="0" aria-valuemin="0" aria-valuemax="100" aria-valuenow="50">
+    <div class="mdc-slider__value-indicator-container">
+      <div class="mdc-slider__value-indicator">
+        <span class="mdc-slider__value-indicator-text">
+          50
+        </span>
+      </div>
+    </div>
+    <div class="mdc-slider__thumb-knob"></div>
+  </div>
+</div>
+```
+
+#### Discrete range slider
+
+```html
+<div class="mdc-slider mdc-slider--range mdc-slider--discrete" data-step="10">
+  <div class="mdc-slider__track">
+    <div class="mdc-slider__track--active">
+      <div class="mdc-slider__track--active_fill"></div>
+    </div>
+    <div class="mdc-slider__track--inactive"></div>
+  </div>
+  <div class="mdc-slider__thumb" role="slider" tabindex="0" aria-valuemin="0" aria-valuemax="100" aria-valuenow="20">
+    <div class="mdc-slider__value-indicator-container">
+      <div class="mdc-slider__value-indicator">
+        <span class="mdc-slider__value-indicator-text">
+          20
+        </span>
+      </div>
+    </div>
+    <div class="mdc-slider__thumb-knob"></div>
+  </div>
+  <div class="mdc-slider__thumb" role="slider" tabindex="0" aria-valuemin="0" aria-valuemax="100" aria-valuenow="50">
+    <div class="mdc-slider__value-indicator-container">
+      <div class="mdc-slider__value-indicator">
+        <span class="mdc-slider__value-indicator-text">
+          50
+        </span>
+      </div>
+    </div>
+    <div class="mdc-slider__thumb-knob"></div>
+  </div>
+</div>
+```
+
+## Other variants
+
+### Disabled slider
+
+To disable a slider, add the following:
+
+*   `mdc-slider--disabled` class on the root element
+*   `tabindex="-1"` attribute on the thumb(s)
+*   `aria-disabled="true"` on the thumb(s)
+
+```html
+<div class="mdc-slider mdc-slider--disabled">
+  <div class="mdc-slider__track">
+    <div class="mdc-slider__track--active">
+      <div class="mdc-slider__track--active_fill"></div>
+    </div>
+    <div class="mdc-slider__track--inactive"></div>
+  </div>
+  <div class="mdc-slider__thumb" role="slider" tabindex="-1" aria-valuemin="0" aria-valuemax="100" aria-valuenow="50" aria-disabled="true">
+    <div class="mdc-slider__thumb-knob"></div>
+  </div>
+</div>
+```
+
+## Additional information
+
+### Initialization with custom ranges and values
+
+When `MDCSlider` is initialized, it reads the thumb element's `aria-valuemin`,
+`aria-valuemax`, and `aria-valuenow` attributes if present, using them to set
+the component's internal `min`, `max`, and `value` properties.
+
+Use these attributes to initialize the slider with a custom range and values,
+as shown below:
+
+```html
+<div class="mdc-slider">
+  <!-- ... -->
+  <div class="mdc-slider__thumb" role="slider" tabindex="0" aria-valuemin="0" aria-valuemax="100" aria-valuenow="75">
+    <div class="mdc-slider__thumb-knob"></div>
+  </div>
+</div>
+```
+
+## API
+
+### Sass mixins
+
+Mixin | Description
+--- | ---
+`track-active-color($color)` | Sets the color of the active track.
+`track-inactive-color($color, $opacity)` | Sets the color and opacity of the inactive track.
+`thumb-color($color)` | Sets the color of the thumb.
+`thumb-ripple-color($color)` | Sets the color of the thumb ripple.
+`tick-mark-active-color($color)` | Sets the color of tick marks on the active track.
+`tick-mark-inactive-color($color)` | Sets the color of tick marks on the inactive track.
+`value-indicator-color($color, $opaicty)` | Sets the color and opacity of the value indicator.
+`value-indicator-text-color($color, $opaicty)` | Sets the color of the value indicator text.
+
+### `MDCSlider` events
+
+Event name | `event.detail` | Description
+--- | --- | ---
+`MDCSlider:change` | `MDCSliderChangeEventDetail` | Emitted when a value has been changed and committed from a user event. Mirrors the native `change` event: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event
+`MDCSlider:input` | `MDCSliderChangeEventDetail` | Emitted when a value has been changed from a user event. Mirrors the native `input` event: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event
+
+### `MDCSlider` methods
+
+Method Signature | Description
+--- | ---
+`getValueStart() => number` | Gets the value of the start thumb (only applicable for range sliders).
+`setValueStart(valueStart: number) => void` | Sets the value of the start thumb (only applicable for range sliders).
+`getValue() => number` | Gets the value of the thumb (for single point sliders), or the end thumb (for range sliders).
+`setValue(value: number) => void` | Sets the value of the thumb (for single point sliders), or the end thumb (for range sliders).
+`getDisabled() => boolean` | Gets the disabled state of the slider.
+`setDisabled(disabled: boolean) => void` | Sets the disabled state of the slider.
+
+### Usage within frameworks
+
+If you are using a JavaScript framework such as React or Angular, you can create a slider 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).
+
+See [MDCSliderAdapter](./adapter.ts) and [MDCSliderFoundation](./foundation.ts) for up-to-date code documentation of slider foundation API's.
diff --git a/packages/mdc-slider/_index.scss b/packages/mdc-slider/_index.scss
@@ -1,3 +1 @@
-@forward "./variables";
-@forward "./mixins";
-@forward "./keyframes";
+@forward './slider-theme';
diff --git a/packages/mdc-slider/_keyframes.import.scss b/packages/mdc-slider/_keyframes.import.scss
diff --git a/packages/mdc-slider/_keyframes.scss b/packages/mdc-slider/_keyframes.scss
diff --git a/packages/mdc-slider/_mixins.import.scss b/packages/mdc-slider/_mixins.import.scss