From c2e87d23904d2c5f0e24d7aeba668f9010da042f Mon Sep 17 00:00:00 2001 From: Dave Whitley Date: Mon, 3 Dec 2018 15:55:29 -0600 Subject: [PATCH 1/4] Update for RangeControl documentation This adds design documentation to RangeControl and also edits one sentence in the developer documentation to make it more generic. --- .../components/src/range-control/README.md | 115 +++++++++++++++--- 1 file changed, 101 insertions(+), 14 deletions(-) diff --git a/packages/components/src/range-control/README.md b/packages/components/src/range-control/README.md index 3966d604df865..bcd8e5e579c18 100644 --- a/packages/components/src/range-control/README.md +++ b/packages/components/src/range-control/README.md @@ -1,17 +1,101 @@ # RangeControl -RangeControl component is used to create range slider to input numerical values. +RangeControls are used to make selections from a range of incremental values. +![](https://make.wordpress.org/design/files/2018/12/rangecontrol.png) -## Usage +A RangeControl for volume + +## Table of contents + +1. [Design guidelines](http://#design-guidelines) +2. [Development guidelines](http://#development-guidelines) +3. [Related components](http://#related-components) + +## Design guidelines + +### Anatomy + +![](https://make.wordpress.org/design/files/2018/12/rangecontrol-anatomy.png) + +A RangeControls can contain the following elements: + +1. **Track**: The track shows the range available for user selection. For left-to-right (LTR) languages, the smallest value appears on the far left, and the largest value on the far right. For right-to-left (RTL) languages this orientation is reversed, with the smallest value on the far right and the largest value on the far left. +2. **Thumb**: The thumb slides along the track, displaying the selected value through its position. +3. **Value entry field** (optional): The value entry field displays the currently selected, specific numerical value. +4. **Icon** (optional): An icon can be displayed before or after the range slider. +5. **Tick mark** (optional): Tick marks represent predetermined values to which the user can move the slider. + +### Behavior + +- **Click and drag**: The range slider is controlled by clicking the thumb and dragging it. +- **Click jump**: The range slider is controlled by clicking the track. +- **Click and arrow**: The continuous slider is controlled by clicking the thumb, then using arrow keys to move it. +- **Tab and arrow**: The range slider is controlled by using the tab key to select the thumb of the desired slider, then using arrow keys to move it. +- **Tick marks** (Optional) Discrete sliders can use evenly spaced tick marks along the slider track, and the thumb will snap to them. Each tick mark should change the setting in increments that are discernible to the user. +- **Value entry field** (Optional): Discrete sliders have value entry fields. After a text entry is made, the slider position automatically updates to reflect the new value. + +### Usage + +RangeControls reflect a range of values along a track, from which users may select a single value. They are ideal for adjusting settings such as volume, opacity, or text size. + +RangeControls can have icons on both ends of the track that reflect a range of values. + +#### Immediate effects + +Changes made with RangeControls are immediate, allowing a user to make adjustments until finding their preference. They shouldn’t be paired with settings that have delays in providing feedback. + +![A range slider that requires a save action](https://make.wordpress.org/design/files/2018/12/rangecontrol-save-action.png) + +**Don’t** +Don’t use RangeControls if the effect isn’t immediate. + +#### Current state + +Range sliders reflect the current state of the settings they control. + +#### Values + +![](https://make.wordpress.org/design/files/2018/12/rangecontrol-field.png) + +A range slider with an editable numeric value + +**Editable numeric values**: Editable numeric values allow users to set the exact value of a range slider. After setting a value, the thumb position is immediately updated to match the new value. + +![A range slider with only two values](https://make.wordpress.org/design/files/2018/12/rangecontrol-2-values.png) + +**Don’t** +RangeControls should only be used for choosing selections from a range of values (e.g., don’t use a range slider if there are only 2 values). + +![](https://make.wordpress.org/design/files/2018/12/rangecontrol-disabled.png) + +**Don’t** +Sliders should provide the full range of choices available for the user to select from (e.g., don’t disable only part of a range slider). + +#### Types + +##### Continuous sliders + +Continuous sliders allow users to select a value along a subjective range. They do not display the selected numeric value. Use them when displaying/editing the numeric value is not important, like volume. + +##### Discrete sliders + +Discrete sliders can be adjusted to a specific value by referencing its value entry field. Use them when it’s important to display/edit the numeric value, like text size. + +Possible selections may be organized through the use of tick marks, which a slider thumb will snap to (or to which an input will round up or down). + +## Development guidelines + +### Usage + +Render a RangeControl to make a selection from a range of incremental values. -Render a user interface to select the number of columns between 2 and 10. ```jsx import { RangeControl } from '@wordpress/components'; import { withState } from '@wordpress/compose'; const MyRangeControl = withState( { - columns: 2, + columns: 2, } )( ( { columns, setState } ) => ( Date: Fri, 14 Dec 2018 15:45:06 -0600 Subject: [PATCH 2/4] Typos and small adjustments --- packages/components/src/range-control/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/components/src/range-control/README.md b/packages/components/src/range-control/README.md index bcd8e5e579c18..6d624dcf7f559 100644 --- a/packages/components/src/range-control/README.md +++ b/packages/components/src/range-control/README.md @@ -8,9 +8,9 @@ A RangeControl for volume ## Table of contents -1. [Design guidelines](http://#design-guidelines) -2. [Development guidelines](http://#development-guidelines) -3. [Related components](http://#related-components) +1. [Design guidelines](#design-guidelines) +2. [Development guidelines](#development-guidelines) +3. [Related components](#related-components) ## Design guidelines @@ -18,7 +18,7 @@ A RangeControl for volume ![](https://make.wordpress.org/design/files/2018/12/rangecontrol-anatomy.png) -A RangeControls can contain the following elements: +A RangeControl can contain the following elements: 1. **Track**: The track shows the range available for user selection. For left-to-right (LTR) languages, the smallest value appears on the far left, and the largest value on the far right. For right-to-left (RTL) languages this orientation is reversed, with the smallest value on the far right and the largest value on the far left. 2. **Thumb**: The thumb slides along the track, displaying the selected value through its position. From 57fa128bd4320bb2f3dcb79332d033bde0647799 Mon Sep 17 00:00:00 2001 From: Dave Whitley Date: Fri, 25 Jan 2019 15:27:54 -0600 Subject: [PATCH 3/4] Moving types higher in the doc --- .../components/src/range-control/README.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/packages/components/src/range-control/README.md b/packages/components/src/range-control/README.md index 6d624dcf7f559..c0c45214f499c 100644 --- a/packages/components/src/range-control/README.md +++ b/packages/components/src/range-control/README.md @@ -26,6 +26,18 @@ A RangeControl can contain the following elements: 4. **Icon** (optional): An icon can be displayed before or after the range slider. 5. **Tick mark** (optional): Tick marks represent predetermined values to which the user can move the slider. +### Types + +#### Continuous sliders + +Continuous sliders allow users to select a value along a subjective range. They do not display the selected numeric value. Use them when displaying/editing the numeric value is not important, like volume. + +#### Discrete sliders + +Discrete sliders can be adjusted to a specific value by referencing its value entry field. Use them when it’s important to display/edit the numeric value, like text size. + +Possible selections may be organized through the use of tick marks, which a slider thumb will snap to (or to which an input will round up or down). + ### Behavior - **Click and drag**: The range slider is controlled by clicking the thumb and dragging it. @@ -72,18 +84,6 @@ RangeControls should only be used for choosing selections from a range of values **Don’t** Sliders should provide the full range of choices available for the user to select from (e.g., don’t disable only part of a range slider). -#### Types - -##### Continuous sliders - -Continuous sliders allow users to select a value along a subjective range. They do not display the selected numeric value. Use them when displaying/editing the numeric value is not important, like volume. - -##### Discrete sliders - -Discrete sliders can be adjusted to a specific value by referencing its value entry field. Use them when it’s important to display/edit the numeric value, like text size. - -Possible selections may be organized through the use of tick marks, which a slider thumb will snap to (or to which an input will round up or down). - ## Development guidelines ### Usage From 4bd4fcc033f55403e53f8964463643f46444bcc4 Mon Sep 17 00:00:00 2001 From: Dave Whitley Date: Fri, 25 Jan 2019 15:37:13 -0600 Subject: [PATCH 4/4] Updates slider language I removed "range slider" language so that it's not confused with the types of sliders. I also inserted "RangeControl" when referring to the whole component. "Slider" is used when casually referring to the thumb+track portion of the component. --- .../components/src/range-control/README.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/packages/components/src/range-control/README.md b/packages/components/src/range-control/README.md index c0c45214f499c..87bdcd6e0af62 100644 --- a/packages/components/src/range-control/README.md +++ b/packages/components/src/range-control/README.md @@ -23,7 +23,7 @@ A RangeControl can contain the following elements: 1. **Track**: The track shows the range available for user selection. For left-to-right (LTR) languages, the smallest value appears on the far left, and the largest value on the far right. For right-to-left (RTL) languages this orientation is reversed, with the smallest value on the far right and the largest value on the far left. 2. **Thumb**: The thumb slides along the track, displaying the selected value through its position. 3. **Value entry field** (optional): The value entry field displays the currently selected, specific numerical value. -4. **Icon** (optional): An icon can be displayed before or after the range slider. +4. **Icon** (optional): An icon can be displayed before or after the slider. 5. **Tick mark** (optional): Tick marks represent predetermined values to which the user can move the slider. ### Types @@ -36,14 +36,14 @@ Continuous sliders allow users to select a value along a subjective range. They Discrete sliders can be adjusted to a specific value by referencing its value entry field. Use them when it’s important to display/edit the numeric value, like text size. -Possible selections may be organized through the use of tick marks, which a slider thumb will snap to (or to which an input will round up or down). +Possible selections may be organized through the use of tick marks, which a thumb will snap to (or to which an input will round up or down). ### Behavior -- **Click and drag**: The range slider is controlled by clicking the thumb and dragging it. -- **Click jump**: The range slider is controlled by clicking the track. -- **Click and arrow**: The continuous slider is controlled by clicking the thumb, then using arrow keys to move it. -- **Tab and arrow**: The range slider is controlled by using the tab key to select the thumb of the desired slider, then using arrow keys to move it. +- **Click and drag**: The slider is controlled by clicking the thumb and dragging it. +- **Click jump**: The slider is controlled by clicking the track. +- **Click and arrow**: The slider is controlled by clicking the thumb, then using arrow keys to move it. +- **Tab and arrow**: The slider is controlled by using the tab key to select the thumb of the desired slider, then using arrow keys to move it. - **Tick marks** (Optional) Discrete sliders can use evenly spaced tick marks along the slider track, and the thumb will snap to them. Each tick mark should change the setting in increments that are discernible to the user. - **Value entry field** (Optional): Discrete sliders have value entry fields. After a text entry is made, the slider position automatically updates to reflect the new value. @@ -57,32 +57,32 @@ RangeControls can have icons on both ends of the track that reflect a range of v Changes made with RangeControls are immediate, allowing a user to make adjustments until finding their preference. They shouldn’t be paired with settings that have delays in providing feedback. -![A range slider that requires a save action](https://make.wordpress.org/design/files/2018/12/rangecontrol-save-action.png) +![A RangeControl that requires a save action](https://make.wordpress.org/design/files/2018/12/rangecontrol-save-action.png) **Don’t** Don’t use RangeControls if the effect isn’t immediate. #### Current state -Range sliders reflect the current state of the settings they control. +RangeControls reflect the current state of the settings they control. #### Values ![](https://make.wordpress.org/design/files/2018/12/rangecontrol-field.png) -A range slider with an editable numeric value +A RangeControl with an editable numeric value -**Editable numeric values**: Editable numeric values allow users to set the exact value of a range slider. After setting a value, the thumb position is immediately updated to match the new value. +**Editable numeric values**: Editable numeric values allow users to set the exact value of a RangeControl. After setting a value, the thumb position is immediately updated to match the new value. -![A range slider with only two values](https://make.wordpress.org/design/files/2018/12/rangecontrol-2-values.png) +![A RangeControl with only two values](https://make.wordpress.org/design/files/2018/12/rangecontrol-2-values.png) **Don’t** -RangeControls should only be used for choosing selections from a range of values (e.g., don’t use a range slider if there are only 2 values). +RangeControls should only be used for choosing selections from a range of values (e.g., don’t use a RangeControl if there are only 2 values). ![](https://make.wordpress.org/design/files/2018/12/rangecontrol-disabled.png) **Don’t** -Sliders should provide the full range of choices available for the user to select from (e.g., don’t disable only part of a range slider). +RangeControls should provide the full range of choices available for the user to select from (e.g., don’t disable only part of a RangeControl). ## Development guidelines