From f3169242d0cccb1589f9855390ef82bdccdec8cb Mon Sep 17 00:00:00 2001 From: Rachel Bratt Tannenbaum Date: Sun, 15 Dec 2024 11:40:05 +0200 Subject: [PATCH] chore(docs): slider and range slider docs update (VIV-2105) (#2055) --- apps/docs/content/_data/components.json | 23 +- .../src/lib/range-slider/ACCESSIBILITY.md | 10 + .../src/lib/range-slider/GUIDELINES.md | 0 .../components/src/lib/range-slider/README.md | 219 ++++++------------ .../src/lib/range-slider/USE-CASES.md | 43 ++++ .../src/lib/range-slider/VARIATIONS.md | 57 +++++ .../src/lib/slider/ACCESSIBILITY.md | 9 + libs/components/src/lib/slider/GUIDELINES.md | 0 libs/components/src/lib/slider/README.md | 163 ++++++------- libs/components/src/lib/slider/USE-CASES.md | 0 libs/components/src/lib/slider/VARIATIONS.md | 54 +++++ 11 files changed, 335 insertions(+), 243 deletions(-) create mode 100644 libs/components/src/lib/range-slider/ACCESSIBILITY.md create mode 100644 libs/components/src/lib/range-slider/GUIDELINES.md create mode 100644 libs/components/src/lib/range-slider/USE-CASES.md create mode 100644 libs/components/src/lib/range-slider/VARIATIONS.md create mode 100644 libs/components/src/lib/slider/ACCESSIBILITY.md create mode 100644 libs/components/src/lib/slider/GUIDELINES.md create mode 100644 libs/components/src/lib/slider/USE-CASES.md create mode 100644 libs/components/src/lib/slider/VARIATIONS.md diff --git a/apps/docs/content/_data/components.json b/apps/docs/content/_data/components.json index 1e492a2f6e..44db8c4b58 100644 --- a/apps/docs/content/_data/components.json +++ b/apps/docs/content/_data/components.json @@ -274,9 +274,14 @@ }, { "title": "Slider", - "page": "legacy", - "markdown": "./libs/components/src/lib/slider/README.md", - "children": ["Range Slider"] + "description": "Allows users to choose from a range of values along a horizontal or vertical line", + "variations": "./libs/components/src/lib/slider/VARIATIONS.md", + "guidelines": "./libs/components/src/lib/slider/GUIDELINES.md", + "hideGuidelines": "true", + "code": "./libs/components/src/lib/slider/README.md", + "accessibility": "./libs/components/src/lib/slider/ACCESSIBILITY.md", + "useCases": "./libs/components/src/lib/slider/USE-CASES.md", + "hideUseCases": "true" }, { "title": "Tabs", @@ -382,10 +387,14 @@ }, { "title": "Range Slider", - "page": "legacy", - "status": "alpha", - "markdown": "./libs/components/src/lib/range-slider/README.md", - "parent": "Slider" + "description": "Allows users to select a range. It includes two thumb controls that can be dragged to set the start and end values.", + "variations": "./libs/components/src/lib/range-slider/VARIATIONS.md", + "guidelines": "./libs/components/src/lib/range-slider/GUIDELINES.md", + "hideGuidelines": "true", + "code": "./libs/components/src/lib/range-slider/README.md", + "accessibility": "./libs/components/src/lib/range-slider/ACCESSIBILITY.md", + "useCases": "./libs/components/src/lib/range-slider/USE-CASES.md", + "status": "alpha" }, { "title": "Split Button", diff --git a/libs/components/src/lib/range-slider/ACCESSIBILITY.md b/libs/components/src/lib/range-slider/ACCESSIBILITY.md new file mode 100644 index 0000000000..d20d873b77 --- /dev/null +++ b/libs/components/src/lib/range-slider/ACCESSIBILITY.md @@ -0,0 +1,10 @@ +## Implementation + +Both thumbs have a `role` of `slider`, which needs an accessible label. By default, they use a localized version of "min" and "max". +You can change the labels by setting the `aria-start-label` and `aria-end-label` attributes. + +Vivid automatically sets the `aria-valuetext` attribute on the thumbs. The attribute is read by assistive technology. You can control its format using the `valueTextFormatter` property for a more human-readable value. + +## Resources + +- [Vivid Tabs: Manual accessibility test](https://docs.google.com/spreadsheets/d/15J0sHxVUlmjv7HwT2b0gGNJFP_vsjAByzgRP_4oWYKk/edit?gid=1175911860#gid=1175911860) diff --git a/libs/components/src/lib/range-slider/GUIDELINES.md b/libs/components/src/lib/range-slider/GUIDELINES.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/libs/components/src/lib/range-slider/README.md b/libs/components/src/lib/range-slider/README.md index ee44275fdd..8852e3b31e 100644 --- a/libs/components/src/lib/range-slider/README.md +++ b/libs/components/src/lib/range-slider/README.md @@ -1,27 +1,54 @@ -# Range Slider +## Usage -The range slider component allows users to select a range. It includes two thumb controls that can be dragged to set the start and end values. + + + ```js - +import '@vonage/vivid/range-slider'; +``` + +or, if you need to use a unique prefix: + +```js +import { registerRangeSlider } from '@vonage/vivid'; + +registerRangeSlider('your-prefix'); ``` ```html preview - + + + ``` -## Members + + + + +```html + + +``` -### Min + + -The lowest value allowed for the range. +## Min -- Type: `number` -- Default: `0` +Use the `min` attribute to set the lowest value allowed for the Range Slider. +The default value of `min` is `0`. ```html preview blocks
- +
Current range: @@ -45,16 +72,14 @@ The lowest value allowed for the range. ``` -### Max +## Max -The highest value allowed for the range. - -- Type: `number` -- Default: `0` +Use the `max` attribute to set the highest value allowed for the Range Slider. +The default value `max` of is `10`. ```html preview blocks
- +
Current range: @@ -78,16 +103,14 @@ The highest value allowed for the range. ``` -### Step - -Sets the granularity with which values can be incremented/decremented. +## Step -- Type: `number` -- Default: `1` +Use the `step` attribute sets the granularity with which values can be incremented/decremented. +The default value `step` of is `1`. ```html preview blocks
- +
Current range: @@ -111,92 +134,53 @@ Sets the granularity with which values can be incremented/decremented. ``` -### Orientation - -When used vertically, the range slider fills the height of its container. - -- Type: `'horizontal'` | `'vertical'` -- Default: `'horizontal'` - -```html preview center 300px - -``` - -### Markers - -Toggles markers display. +## Start -- Type: `boolean` -- Default: `false` +Use the `start` attribute to set the lower position of the range indicator. +The default value of `start` is [`min`](/components/range-slider/code/#min). ```html preview blocks - + ``` -### Connotation +## End -- Type: `'accent'` | `'cta'` -- Default: `'accent'` +Use the `end` attribute to set the upper position of the range indicator. +The default value of `end` is [`max`](/components/range-slider/code/#max). ```html preview blocks - -``` - -### Pin - -Toggles display of the start and end values with a tooltip. Use the `valueTextFormatter` member to customize the format of the values. - -- Type: `boolean` -- Default: `false` - -```html preview - - - + ``` -### Disabled - -Toggle the `disabled` member to disable/enable the slider. - -- Type: `boolean` -- Default: `false` +## Value Text Formatter -```html preview blocks - -``` +Use the `valueTextFormatter` to generates a string for the Range Slider's "aria-valuetext" attribute based on the current value. +Use this to configure the [`pin`](/components/range-slider/#pin) string. -### Start +## API Reference -The lower value of the range. +### Properties -- Type: `string` -- Default: `min` - -```html preview blocks - -``` - -### End - -The upper value of the range. +
-- Type: `string` -- Default: `max` +| Name | Type | Description | +| -------------------- | --------------------------------------- | -------------------------------------------------------------------- | +| **aria-start-label** | `string` | Aria label for the start thumb | +| **aria-end-label** | `string` | Aria label for the end thumb | +| **connotation** | _Enum_:
`accent`
`cta` | The connotation of the component | +| **disabled** | `boolean` | Sets the element's disabled state | +| **end** | `string` | The current end value of the element. | +| **markers** | `boolean` | Display markers on/off | +| **max** | `number` | The maximum value of the range. | +| **min** | `number` | The minimum value of the range. | +| **orientation** | _Enum_:
`horizontal`
`vertical` | The orientation of the slider. | +| **pin** | `boolean` | Show current values on the thumbs. | +| **start** | `string` | The current start value of the element. | +| **step** | `number` | Value to increment or decrement via arrow keys, mouse click or drag. | -```html preview blocks - -``` +
-## Events +### Events
@@ -208,56 +192,3 @@ The upper value of the range. | `change` | `CustomEvent` | Yes | Yes | Event emitted when either the start or end value changes. |
- -## Accessibility - -Both thumbs have a `role` of `slider`, which needs an accessible label. By default, they use a localized version of "min" and "max". -You can change the labels by setting the `aria-start-label` and `aria-end-label` attributes. - -Vivid automatically sets the `aria-valuetext` attribute on the thumbs. The attribute is read by assistive technology. You can control its format using the `valueTextFormatter` property for a more human-readable value. - -## Use Cases - -```html preview -
- -
-
- Duration from - - - to - - -
- -``` diff --git a/libs/components/src/lib/range-slider/USE-CASES.md b/libs/components/src/lib/range-slider/USE-CASES.md new file mode 100644 index 0000000000..eafcc0268f --- /dev/null +++ b/libs/components/src/lib/range-slider/USE-CASES.md @@ -0,0 +1,43 @@ +```html preview +
+ +
+
+ Duration from + + + to + + +
+ +``` diff --git a/libs/components/src/lib/range-slider/VARIATIONS.md b/libs/components/src/lib/range-slider/VARIATIONS.md new file mode 100644 index 0000000000..7c33ee7390 --- /dev/null +++ b/libs/components/src/lib/range-slider/VARIATIONS.md @@ -0,0 +1,57 @@ +## Connotation + +Use the `connotation` attribute on Range Slider to control the color of the selected range. + +```html preview blocks> + + +``` + +## Markers + +Use the `markers` attribute to add tick marks on the slider. +The markers are set by the value of [`step`](/components/range-slider/code/#step). + +```html preview blocks + +``` + +## Orientation + +The `orientation` attribute controls which axis the Range Slider is aligned. +Below is an example of vertical alignment. + + +

When used vertically, the range slider fits the height of its container.

+ + +```html preview center 300px + +``` + +## Pin + +Use `pin` attribute to display a tooltip at the start and end values. +Use the [`valueTextFormatter`](/components/range-slider/code/#value-text-formatter) member to customize the format of the values. + +```html preview + + + +``` + +## Disabled + +The `disabled` attribute disables the Range Slider. + +```html preview blocks + +``` diff --git a/libs/components/src/lib/slider/ACCESSIBILITY.md b/libs/components/src/lib/slider/ACCESSIBILITY.md new file mode 100644 index 0000000000..a245ab6ecc --- /dev/null +++ b/libs/components/src/lib/slider/ACCESSIBILITY.md @@ -0,0 +1,9 @@ +## Implementation + +The slider has a `role` of `slider`, which needs an accessible label. You must provide it using `aria-label`. + +Vivid automatically sets the `aria-valuetext` attribute on the slider. The attribute is read by assistive technology. You can control its format using the `valueTextFormatter` property for a more human-readable value. + +## Resources + +- [Vivid Tabs: Manual accessibility test](https://docs.google.com/spreadsheets/d/15J0sHxVUlmjv7HwT2b0gGNJFP_vsjAByzgRP_4oWYKk/edit?gid=1175911860#gid=1175911860) diff --git a/libs/components/src/lib/slider/GUIDELINES.md b/libs/components/src/lib/slider/GUIDELINES.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/libs/components/src/lib/slider/README.md b/libs/components/src/lib/slider/README.md index b9c76f7b08..53e212d3cd 100644 --- a/libs/components/src/lib/slider/README.md +++ b/libs/components/src/lib/slider/README.md @@ -1,23 +1,63 @@ -# Slider +## Usage -Represents a slider custom element. + + + ```js - +import '@vonage/vivid/slider'; +``` + +or, if you need to use a unique prefix: + +```js +import { registerSlider } from '@vonage/vivid'; + +registerSlider('your-prefix'); ``` ```html preview - + + + ``` -## Members + + + -### Min +```html + + +``` + + + -Use `min` to set the lowest value allowed for the slider. +## Value -- Type: `number` -- Default: `0` +Set the `value` attribute to set the value of the Slider. + +```html preview blocks + +``` + +### Value Text Formatter + +Use the `valueTextFormatter` to generates a string for the Slider's "aria-valuetext" attribute based on the current value. +Use this to configure the [`pin`](/components/slider/#pin) string. + +## Min + +Use the `min` attribute to set the lowest value allowed for the Slider. +The default value of `min` is `0`. ```html preview blocks
@@ -36,12 +76,10 @@ Use `min` to set the lowest value allowed for the slider. ``` -### Max - -Use `max` to set the greatest value allowed for the slider. +## Max -- Type: `number` -- Default: `10` +Use the `max` attribute to set the highest value allowed for the Slider. +The default value `max` of is `10`. ```html preview blocks
@@ -60,12 +98,10 @@ Use `max` to set the greatest value allowed for the slider. ``` -### Step +## Step -Use `step` to set determine the granularity with which values can be incremented/decremented. - -- Type: `number` -- Default: `1` +Use the `step` attribute sets the granularity with which values can be incremented/decremented. +The default value of `step` is `1`. ```html preview blocks
@@ -84,78 +120,27 @@ Use `step` to set determine the granularity with which values can be incremented ``` -### Orientation - -When used vertically, the slider fills the height of its container. - -- Type: `'horizontal'` | `'vertical'` -- Default: `'horizontal'` - -```html preview center 300px - -``` - -### Markers - -Toggles markers display. -Markers are set according to the value of step (1 by default). +## API Reference -- Type: `boolean` -- Default: `false` - -```html preview blocks - -``` +### Properties -### Connotation - -- Type: `'accent'` | `'cta'` -- Default: `'accent'` - -```html preview blocks - -``` - -### Pin - -Toggles display the value through a tooltip. Use the `valueTextFormatter` member to customize the format of the value. - -- Type: `boolean` -- Default: `false` - -```html preview - - - -``` - -### Disabled - -Toggle the `disabled` member to disable/enable the slider. - -- Type: `boolean` -- Default: `false` - -```html preview blocks - -``` - -### Value - -Use `value` to set the value of the slider. +
-- Type: `string` -- Default: `5` +| Name | Type | Description | +| --------------- | --------------------------------------- | -------------------------------------------------------------------- | +| **connotation** | _Enum_:
`accent`
`cta` | The connotation of the component | +| **disabled** | `boolean` | Sets the element's disabled state | +| **markers** | `boolean` | Display markers on/off | +| **max** | `number` | The maximum value of the range. | +| **min** | `number` | The minimum value of the range. | +| **orientation** | _Enum_:
`horizontal`
`vertical` | The orientation of the slider. | +| **pin** | `boolean` | Show current values on the thumbs. | +| **step** | `number` | Value to increment or decrement via arrow keys, mouse click or drag. | +| **value** | `number` | Set the value attribute to set the value of the slider. | -```html preview blocks - -``` +
-## Events +### Events
@@ -164,9 +149,3 @@ Use `value` to set the value of the slider. | `change` | `CustomEvent` | Yes | Yes | Fires a custom 'change' event when the slider value changes |
- -## Accessibility - -The slider has a `role` of `slider`, which needs an accessible label. You must provide it using `aria-label`. - -Vivid automatically sets the `aria-valuetext` attribute on the slider. The attribute is read by assistive technology. You can control its format using the `valueTextFormatter` property for a more human-readable value. diff --git a/libs/components/src/lib/slider/USE-CASES.md b/libs/components/src/lib/slider/USE-CASES.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/libs/components/src/lib/slider/VARIATIONS.md b/libs/components/src/lib/slider/VARIATIONS.md new file mode 100644 index 0000000000..0f224a8555 --- /dev/null +++ b/libs/components/src/lib/slider/VARIATIONS.md @@ -0,0 +1,54 @@ +## Connotation + +Use the `connotation` attribute on Slider to control the Slider track. + +```html preview blocks> + + +``` + +## Markers + +Use the `markers` attribute to add tick marks on the slider. +The markers are set by the value of [`step`](/components/slider/code/#step). + +```html preview blocks + +``` + +## Orientation + +The `orientation` attribute controls which axis the Slider is aligned. +Below is an example of vertical alignment. + + +

When used vertically, the Slider fits the height of its container.

+ + +```html preview center 300px + +``` + +## Pin + +Use `pin` attribute to display a tooltip on the Slider knob. +Use the [`valueTextFormatter`](/components/slider/code/#value-text-formatter) member to customize the format of the value. + +```html preview + + + + +``` + +## Disabled + +The `disabled` attribute disables the Slider. + +```html preview blocks + +```