Update for RangeControl documentation #12564

davewhitley · 2018-12-03T22:00:53Z

Initial commit to update the RangeControl readme. These changes add design documentation.

Description

This PR adds design guideline documentation in addition to the development documentation that existed previously. These guidelines are 'best practices' for the usage of the component, as well as describing the component in more detail.

Screenshots

A preview can be seen here, although it doesn't represent what it will look like in the handbook:

preview

Feedback

I'd appreciate feedback on:

Whether my markdown syntax is correct
Design guidelines
Double-checking a11y of the document
Seeing if the design guidelines align with the development documentation

Thank you!

This adds design documentation to RangeControl and also edits one sentence in the developer documentation to make it more generic.

packages/components/src/range-control/README.md

chrisvanpatten

A few questions but overall nice. I also noticed some of the docs here are pulled from Material Design's documentation — do we need to credit that somewhere?

packages/components/src/range-control/README.md

chrisvanpatten · 2018-12-14T15:04:04Z

packages/components/src/range-control/README.md

+
+### 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.


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.

chrisvanpatten · 2018-12-14T15:04:25Z

packages/components/src/range-control/README.md

+
+##### 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.


Does the range component even allow this?

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.

davewhitley · 2018-12-14T22:57:28Z

@chrisvanpatten

A few questions but overall nice. I also noticed some of the docs here are pulled from Material Design's documentation — do we need to credit that somewhere?

You're right, most of the docs are pulled from Material, even though they are mostly edited to fit WordPress. What would be the best way to credit Material? I think it would be easier if we had a separate documentation site. In terms of the component package, maybe a top level readme file in the component folder?

ajitbohra · 2018-12-17T21:01:50Z

@chrisvanpatten

Should we convert props info to the table like we have one here https://github.com/WordPress/gutenberg/tree/master/packages/components/src/button#props

The table looks neat and easy to refer compared to vertical flowing text, though formatting on the handbook for table needs CSS tweaks.

chrisvanpatten · 2018-12-17T23:35:38Z

@ajitbohra I like the more verbose version we have here as it makes it easier to deep-link to a specific prop in GitHub. Also the table makes it harder to provide in-context examples for specific props.

kjellr · 2019-01-15T14:20:28Z

You're right, most of the docs are pulled from Material, even though they are mostly edited to fit WordPress. What would be the best way to credit Material? I think it would be easier if we had a separate documentation site. In terms of the component package, maybe a top level readme file in the component folder?

I do think something like that would make sense — but maybe it could just be a note on one of these more global docs pages?

https://github.com/WordPress/gutenberg/blob/master/docs/readme.md
https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/readme.md

In any case, I don't think it should hold up this PR. It looks to me like the other issues raised here are addressed — can someone else confirm?

davewhitley · 2019-01-15T18:06:51Z

I addressed all the raised issues to the best of my knowledge. Thanks!

gziolo · 2019-01-25T12:43:54Z

@kjellr or @mapk can you give 👍 for the changes proposed, they mostly related to design-related considerations :)

mapk

The usage of "range sliders" and "continuous sliders" appears in the Behavior section of the doc before I even understand the difference. When we get to the Type section, I only see "continuous slider" and "discrete slider" mentioned which leaves me a bit lost.

I imagine that "range slider" is a term that includes both "continuous" and "discrete" but am unsure. Can this be made more explicit?

kjellr · 2019-01-25T18:51:30Z

I agree with @mapk on that one. For the simplest fix, I think it'd be fine to move types out of "Usage" and into "Anatomy" (Or even into its own H3 maybe). Bonus points if we can include a screenshot of each, but we can also add that later on.

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.

davewhitley · 2019-01-25T21:38:56Z

@mapk @kjellr ready for another review

Moved Types section here 57fa128

Updated slider language here 4bd4fcc

"Slider" refers to the thumb+track part of the component even though it's not in the official anatomy.

mapk

Reads much better for me now. Thanks!

gziolo · 2019-01-26T07:20:14Z

It’s only docs changes, we can ignore bad the fact that Travis CI is red expressing its bad mood 😃 Nice work on providing lots of useful details about this component.

…rnmobile/372-enter-key-detection-to-title * 'master' of https://github.com/WordPress/gutenberg: (29 commits) Update for RangeControl documentation (#12564) Plugin: Deprecate gutenberg_load_list_reusable_blocks (#13456) Update the columns attribute in onSelectImages so that if images are removed via the media modal, the columns can't be higher than the new number of images (#13488) Replace the fullscreen "exit" icon with a back arrow (#13403) Include :visited links in button color (#12183) Amazon Kindle block (#13510) Plugin: Deprecate gutenberg_prepare_blocks_for_js (#13457) Add watcher on Linux: change fs to node-watch (#13448) Plugin: Deprecate `gutenberg` theme support (#13458) Datepicker: Add inValidDay support (#12962) Block Switcher: Render disabled button even if multi-selection (#13431) Plugin: Deprecate gutenberg_register_post_types (#13468) Plugin: Deprecate register_tinymce_scripts (#13466) Set minimum of words for RSS excerpt (#13502) Plugin: Deprecate gutenberg_get_block_categories (#13454) Plugin: Deprecate gutenberg_content_block_version (#13469) API Fetch: Expose nonce on created middleware function (#13451) Plugin: Remove list screens integrations (#13459) Plugin: Remove core-defined block detection functions (#13467) Spec Parser: Move generated spec parser to package (#13493) ...

* Update for RangeControl documentation This adds design documentation to RangeControl and also edits one sentence in the developer documentation to make it more generic. * Typos and small adjustments * Moving types higher in the doc * 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.

Update for RangeControl documentation

c2e87d2

This adds design documentation to RangeControl and also edits one sentence in the developer documentation to make it more generic.

davewhitley added [Type] Developer Documentation Documentation for developers [Feature] UI Components Impacts or related to the UI component system labels Dec 3, 2018

swissspidy reviewed Dec 3, 2018

View reviewed changes

packages/components/src/range-control/README.md Outdated Show resolved Hide resolved

gziolo added this to the Documentation & Handbook milestone Dec 14, 2018

gziolo requested review from ajitbohra and chrisvanpatten December 14, 2018 15:01

chrisvanpatten suggested changes Dec 14, 2018

View reviewed changes

Typos and small adjustments

7b4f163

chrisvanpatten mentioned this pull request Dec 18, 2018

Small typo in the Range Control's readme #12989

Merged

gziolo requested review from mapk and kjellr January 25, 2019 12:44

mapk requested changes Jan 25, 2019

View reviewed changes

davewhitley added 2 commits January 25, 2019 15:27

Moving types higher in the doc

57fa128

Updates slider language

4bd4fcc

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.

mapk approved these changes Jan 26, 2019

View reviewed changes

gziolo merged commit 096c12c into master Jan 26, 2019

gziolo deleted the update/rangecontrol-readme branch January 26, 2019 07:22

swissspidy mentioned this pull request May 31, 2019

RangeControl > Value entry field (optional): #15931

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update for RangeControl documentation #12564

Update for RangeControl documentation #12564

davewhitley commented Dec 3, 2018 •

edited

Loading

chrisvanpatten left a comment

chrisvanpatten Dec 14, 2018

chrisvanpatten Dec 14, 2018

davewhitley Dec 17, 2018

davewhitley commented Dec 14, 2018

ajitbohra commented Dec 17, 2018

chrisvanpatten commented Dec 17, 2018

kjellr commented Jan 15, 2019

davewhitley commented Jan 15, 2019

gziolo commented Jan 25, 2019

mapk left a comment

kjellr commented Jan 25, 2019

davewhitley commented Jan 25, 2019

mapk left a comment

gziolo commented Jan 26, 2019


		### 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.


		##### 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.

Update for RangeControl documentation #12564

Update for RangeControl documentation #12564

Conversation

davewhitley commented Dec 3, 2018 • edited Loading

Description

Screenshots

Feedback

chrisvanpatten left a comment

Choose a reason for hiding this comment

chrisvanpatten Dec 14, 2018

Choose a reason for hiding this comment

chrisvanpatten Dec 14, 2018

Choose a reason for hiding this comment

davewhitley Dec 17, 2018

Choose a reason for hiding this comment

davewhitley commented Dec 14, 2018

ajitbohra commented Dec 17, 2018

chrisvanpatten commented Dec 17, 2018

kjellr commented Jan 15, 2019

davewhitley commented Jan 15, 2019

gziolo commented Jan 25, 2019

mapk left a comment

Choose a reason for hiding this comment

kjellr commented Jan 25, 2019

davewhitley commented Jan 25, 2019

mapk left a comment

Choose a reason for hiding this comment

gziolo commented Jan 26, 2019

davewhitley commented Dec 3, 2018 •

edited

Loading