Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update for RangeControl documentation #12564

Merged
merged 4 commits into from
Jan 26, 2019
Merged

Update for RangeControl documentation #12564

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c2e87d2
Update for RangeControl documentation
davewhitley Dec 3, 2018
7b4f163
Typos and small adjustments
davewhitley Dec 14, 2018
57fa128
Moving types higher in the doc
davewhitley Jan 25, 2019
4bd4fcc
Updates slider language
davewhitley Jan 25, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 101 additions & 14 deletions packages/components/src/range-control/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
davewhitley marked this conversation as resolved.
Show resolved Hide resolved
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:
davewhitley marked this conversation as resolved.
Show resolved Hide resolved

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a broader question but I wonder whether it makes more sense to refer to RangeControls reflect or the singular A RangeControl reflects. Might be worth a copy review on this.


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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does the range component even allow this?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not explicitly, although you can set a large max number and simulate a continuous slider. I feel like it will be a needed feature in the near future, given that it's an option in a regular html slider. Even though the component doesn't support it fully, I think the design guidelines can be somewhat aspirational in this case.


##### 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 } ) => (
<RangeControl
label="Columns"
Expand All @@ -23,65 +107,68 @@ const MyRangeControl = withState( {
) );
```

## Props
### Props

The set of props accepted by the component will be specified below.
Props not included in this set will be applied to the input elements.

### label
#### label

If this property is added, a label will be generated using label property as the content.

- Type: `String`
- Required: No

### help
#### help

If this property is added, a help text will be generated using help property as the content.

- Type: `String`
- Required: No


### beforeIcon
#### beforeIcon

If this property is added, a DashIcon component will be rendered before the slider with the icon equal to beforeIcon

- Type: `String`
- Required: No

### afterIcon
#### afterIcon

If this property is added, a DashIcon component will be rendered after the slider with the icon equal to afterIcon

- Type: `String`
- Required: No

### allowReset
#### allowReset

If this property is true, a button to reset the the slider is rendered.

- Type: `Boolean`
- Required: No

### initialPosition
#### initialPosition

In no value exists this prop contains the slider starting position.

- Type: `Number`
- Required: No

### value
#### value

The current value of the range slider.

- Type: `Number`
- Required: Yes

### onChange
#### onChange

A function that receives the new value.
If allowReset is true, when onChange is called without any parameter passed it should reset the value.

- Type: `function`
- Required: Yes

## Related components

- To collect a numerical input in a text field, use the `TextControl` component.