Skip to content

Commit

Permalink
chore(docs): slider and range slider docs update (VIV-2105) (#2055)
Browse files Browse the repository at this point in the history
  • Loading branch information
rachelbt authored Dec 15, 2024
1 parent 146f7ad commit f316924
Show file tree
Hide file tree
Showing 11 changed files with 335 additions and 243 deletions.
23 changes: 16 additions & 7 deletions apps/docs/content/_data/components.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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",
Expand Down
10 changes: 10 additions & 0 deletions libs/components/src/lib/range-slider/ACCESSIBILITY.md
Original file line number Diff line number Diff line change
@@ -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)
Empty file.
219 changes: 75 additions & 144 deletions libs/components/src/lib/range-slider/README.md
Original file line number Diff line number Diff line change
@@ -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.
<vwc-tabs>
<vwc-tab label="Web component"></vwc-tab>
<vwc-tab-panel>

```js
<script type="module">import '@vonage/vivid/range-slider';</script>
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
<vwc-range-slider></vwc-range-slider>
<script type="module">
import { registerRangeSlider } from '@vonage/vivid';
registerRangeSlider('your-prefix');
</script>

<your-prefix-range-slider></your-prefix-range-slider>
```

## Members
</vwc-tab-panel>
<vwc-tab label="Vue"></vwc-tab>
<vwc-tab-panel>

```html
<script setup lang="ts">
import { VRangeSlider } from '@vonage/vivid-vue';
</script>
<template>
<VRangeSlider />
</template>
```

### Min
</vwc-tab-panel>
</vwc-tabs>

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
<div>
<vwc-range-slider id="slider" min="-10"></vwc-range-slider>
<vwc-range-slider min="-10" id="slider"></vwc-range-slider>
</div>
<div>
Current range:
Expand All @@ -45,16 +72,14 @@ The lowest value allowed for the range.
</script>
```

### 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
<div>
<vwc-range-slider id="slider" max="20"></vwc-range-slider>
<vwc-range-slider max="20" id="slider"></vwc-range-slider>
</div>
<div>
Current range:
Expand All @@ -78,16 +103,14 @@ The highest value allowed for the range.
</script>
```

### 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
<div>
<vwc-range-slider id="slider" step="0.5"></vwc-range-slider>
<vwc-range-slider step="0.5" id="slider" markers></vwc-range-slider>
</div>
<div>
Current range:
Expand All @@ -111,92 +134,53 @@ Sets the granularity with which values can be incremented/decremented.
</script>
```

### Orientation

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

- Type: `'horizontal'` | `'vertical'`
- Default: `'horizontal'`

```html preview center 300px
<vwc-range-slider orientation="vertical"></vwc-range-slider>
```

### 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
<vwc-range-slider markers></vwc-range-slider>
<vwc-range-slider start="5" markers></vwc-range-slider>
```

### 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
<vwc-range-slider connotation="cta"></vwc-range-slider>
```

### 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
<vwc-range-slider pin></vwc-range-slider>
<vwc-range-slider
orientation="vertical"
style="height: 200px"
pin
></vwc-range-slider>
<script>
for (const slider of document.querySelectorAll('vwc-range-slider')) {
slider.valueTextFormatter = (value) => `${value} units`;
}
</script>
<vwc-range-slider end="5" markers></vwc-range-slider>
```

### Disabled

Toggle the `disabled` member to disable/enable the slider.

- Type: `boolean`
- Default: `false`
## Value Text Formatter

```html preview blocks
<vwc-range-slider disabled></vwc-range-slider>
```
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
<vwc-range-slider start="5"></vwc-range-slider>
```

### End

The upper value of the range.
<div class="table-wrapper">

- 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_:<br/>`accent`<br/>`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_:<br/>`horizontal`<br/>`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
<vwc-range-slider end="5"></vwc-range-slider>
```
</div>

## Events
### Events

<div class="table-wrapper">

Expand All @@ -208,56 +192,3 @@ The upper value of the range.
| `change` | `CustomEvent<undefined>` | Yes | Yes | Event emitted when either the start or end value changes. |

</div>

## 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
<div>
<vwc-range-slider
id="slider"
min="0"
max="7200"
end="7200"
step="15"
></vwc-range-slider>
</div>
<div>
Duration from
<strong>
<span id="start"></span>
to
<span id="end"></span>
</strong>
</div>
<script>
const slider = document.querySelector('#slider');
const start = document.querySelector('#start');
const end = document.querySelector('#end');
const formatValue = (value) => {
const totalSeconds = Number.parseFloat(value);
const hours = Math.floor(totalSeconds / 3600);
const minutes = Math.floor((totalSeconds % 3600) / 60);
const seconds = Math.floor(totalSeconds % 60);
return `${hours.toString().padStart(2, '0')}:${minutes
.toString()
.padStart(2, '0')}:${seconds.toString().padStart(2, '0')}`;
};
const updateDescription = () => {
start.innerText = formatValue(slider.start);
end.innerText = formatValue(slider.end);
};
customElements.whenDefined('vwc-range-slider').then(updateDescription);
slider.valueTextFormatter = formatValue;
slider.addEventListener('change', updateDescription);
</script>
```
43 changes: 43 additions & 0 deletions libs/components/src/lib/range-slider/USE-CASES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
```html preview
<div>
<vwc-range-slider
id="slider"
min="0"
max="7200"
end="7200"
step="15"
></vwc-range-slider>
</div>
<div>
Duration from
<strong>
<span id="start"></span>
to
<span id="end"></span>
</strong>
</div>
<script>
const slider = document.querySelector('#slider');
const start = document.querySelector('#start');
const end = document.querySelector('#end');
const formatValue = (value) => {
const totalSeconds = Number.parseFloat(value);
const hours = Math.floor(totalSeconds / 3600);
const minutes = Math.floor((totalSeconds % 3600) / 60);
const seconds = Math.floor(totalSeconds % 60);
return `${hours.toString().padStart(2, '0')}:${minutes
.toString()
.padStart(2, '0')}:${seconds.toString().padStart(2, '0')}`;
};
const updateDescription = () => {
start.innerText = formatValue(slider.start);
end.innerText = formatValue(slider.end);
};
customElements.whenDefined('vwc-range-slider').then(updateDescription);
slider.valueTextFormatter = formatValue;
slider.addEventListener('change', updateDescription);
</script>
```
Loading

0 comments on commit f316924

Please sign in to comment.