@nypl/design-system-react-components 0.25.11 → 0.26.0

package/src/components/Slider/Slider.stories.mdx

@@ -50,9 +50,6 @@ import DSProvider from "../../theme/provider";
     },
     name: { control: false },
     onChange: { control: false },
-    optReqFlag: {
-      table: { defaultValue: { summary: true } },
-    },
     showBoxes: {
       table: { defaultValue: { summary: true } },
     },
@@ -62,6 +59,9 @@ import DSProvider from "../../theme/provider";
     showLabel: {
       table: { defaultValue: { summary: true } },
     },
+    showRequiredLabel: {
+      table: { defaultValue: { summary: true } },
+    },
     showValues: {
       table: { defaultValue: { summary: true } },
     },
@@ -76,13 +76,26 @@ import DSProvider from "../../theme/provider";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.25.4`   |
-| Latest            | `0.25.10`  |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [RangeSlider](#rangeslider)
+- [Examples](#examples)
+- [Get Input Values](#get-input-values)
+
+## Overview
 
 <Description of={Slider} />
 
 The text input component doubles as a display for the slider's current value.
 For this type of component, the `value` prop must be a single number.
 
+## Component Props
+
 <Canvas withToolbar>
   <Story
     name="Slider with Controls"
@@ -101,10 +114,10 @@ For this type of component, the `value` prop must be a single number.
       min: 0,
       name: undefined,
       onChange: undefined,
-      optReqFlag: true,
       showBoxes: true,
       showHelperInvalidText: true,
       showLabel: true,
+      showRequiredLabel: true,
       showValues: true,
       step: 1,
     }}
@@ -123,18 +136,40 @@ For this type of component, the `value` prop must be a single number.
 
 <ArgsTable story="Slider with Controls" />
 
-### Accessibility
+## Accessibility
+
+The `Slider` component is accessible via keyboard. In addition to the text fields,
+a keyboard user can tab to the blue slider thumb and then with left and right
+arrows increase or decrease the value. The color contrast between foreground
+color and background color is 4.5:1. If text size is 200%, the button scales
+with text so there is no overlap. Internally, a `Label` is associated with the
+`<input>` element.
+
+When `showLabel` is set to false, the `labelText` value will be set to the
+main `<div>`'s `aria-label` attribute. This is the same `<div>` that contains the
+`aria-valuemin`, `aria-valuemax`, `aria-orientation`, and `aria-valuenow`
+attributes.
+
+Resources:
+
+- [W3C WAI-Aria Practices - Slider](https://www.w3.org/TR/wai-aria-practices-1.1/#slider)
+- [W3C WAI-Aria Practices - Slider (Multi-Thumb)](https://www.w3.org/TR/wai-aria-practices-1.1/#slidertwothumb)
+- [Chakra Slider](https://chakra-ui.com/docs/components/form/slider)
+- [Chakra RangeSlider](https://chakra-ui.com/docs/components/form/range-slider)
+
+### Slider Accessibility Implementation
 
 Chakra's `Slider` component is accessible and, as recommended, we pass in an
-`aria-label` to their `Slider` component. On top of that, the DS `Slider`
-component's `<label>` points to the `<input>` element which shows the current
-value. This `input` element also has its own `aria-label`. When the input box
-is hidden, the `for` attribute in the `label` element is removed.
+`aria-label` to their `Slider` component. On top of that, the Reservoir Design 
+System (DS) `Slider` component's `<label>` points to the `<input>` element 
+which shows the current value. This `input` element also has its own 
+`aria-label`. When the input box is hidden, the `for` attribute in the `label` 
+element is removed.
 
 Note that Chakra handles its single slider thumb aria attributes: `aria-valuemin`,
 `aria-valuemax`, `aria-valuenow`, and `aria-orientation`.
 
-## Range Slider
+## RangeSlider
 
 Set `isRangeSlider` to `true` to create a range slider. The text input
 components double as displays for the slider's current minimum and maximum
@@ -143,7 +178,7 @@ numbers. This signifies the starting and ending values of the range slider.
 
 <Canvas withToolbar>
   <Story
-    name="Range Slider with Props"
+    name="RangeSlider with Controls"
     args={{
       className: undefined,
       defaultValue: [25, 75],
@@ -159,10 +194,10 @@ numbers. This signifies the starting and ending values of the range slider.
       min: 0,
       name: undefined,
       onChange: undefined,
-      optReqFlag: true,
       showBoxes: true,
       showHelperInvalidText: true,
       showLabel: true,
+      showRequiredLabel: true,
       showValues: true,
       step: 1,
     }}
@@ -179,7 +214,7 @@ numbers. This signifies the starting and ending values of the range slider.
   </Story>
 </Canvas>
 
-### Accessibility
+### RangeSlider Accessibility Implementation
 
 Chakra's `RangeSlider` component is accessible and, as recommended, we pass in
 two `aria-label`s to their `RangeSlider` component. The syntax is different than
@@ -192,10 +227,9 @@ When the input boxes are hidden, the `for` attribute in the `label` element is r
 Note that Chakra handles its two slider thumbs aria attributes: `aria-valuemin`,
 `aria-valuemax`, `aria-valuenow`, and `aria-orientation`.
 
-### Single Slider States
+## Examples
 
-Note: In the following examples, the "Required"/"Optional" text in the label is
-hidden by setting the `optReqFlag` prop to false.
+### Single Slider States
 
 <Canvas>
   <DSProvider>
@@ -206,8 +240,8 @@ hidden by setting the `optReqFlag` prop to false.
     />
     <Slider
       defaultValue={50}
-      optReqFlag={false}
       helperText="Component helper text."
+      id="single-slider"
       invalidText="Component error text :("
       labelText="Label"
     />
@@ -223,8 +257,8 @@ hidden by setting the `optReqFlag` prop to false.
     />
     <Slider
       defaultValue={50}
-      optReqFlag={false}
       helperText="Component helper text."
+      id="errored-slider"
       invalidText="Component error text :("
       labelText="Label"
       isInvalid
@@ -232,6 +266,24 @@ hidden by setting the `optReqFlag` prop to false.
   </DSProvider>
 </Canvas>
 
+<Canvas>
+  <DSProvider>
+    <Heading
+      id="heading-single-required"
+      level={HeadingLevels.Four}
+      text="Required State"
+    />
+    <Slider
+      defaultValue={50}
+      helperText="Component helper text."
+      id="required-slider"
+      invalidText="Component error text :("
+      labelText="Label"
+      isRequired
+    />
+  </DSProvider>
+</Canvas>
+
 <Canvas>
   <DSProvider>
     <Heading
@@ -241,8 +293,8 @@ hidden by setting the `optReqFlag` prop to false.
     />
     <Slider
       defaultValue={50}
-      optReqFlag={false}
       helperText="Component helper text."
+      id="disabled-slider"
       invalidText="Component error text :("
       labelText="Label"
       isDisabled
@@ -254,9 +306,6 @@ hidden by setting the `optReqFlag` prop to false.
 
 To enable the Range Slider, set the `isRangeSlider` prop to true.
 
-Note: In the following examples, the "Required"/"Optional" text in the label is
-hidden by setting the `optReqFlag` prop to false.
-
 <Canvas>
   <DSProvider>
     <Heading
@@ -266,8 +315,8 @@ hidden by setting the `optReqFlag` prop to false.
     />
     <Slider
       defaultValue={[25, 75]}
-      optReqFlag={false}
       helperText="Component helper text."
+      id="range-slider"
       invalidText="Component error text :("
       labelText="Label"
       isRangeSlider
@@ -285,8 +334,8 @@ hidden by setting the `optReqFlag` prop to false.
     <SimpleGrid columns={1} gap={GridGaps.Large}>
       <Slider
         defaultValue={[25, 75]}
-        optReqFlag={false}
         helperText="Component helper text."
+        id="range-error-slider"
         invalidText="Component error text :("
         labelText="Label"
         isRangeSlider
@@ -303,8 +352,8 @@ hidden by setting the `optReqFlag` prop to false.
       </p>
       <Slider
         defaultValue={[80, 20]}
-        optReqFlag={false}
         helperText="Component helper text."
+        id="range-error-slider2"
         invalidText="Component error text :("
         labelText="Label"
         isRangeSlider
@@ -313,6 +362,25 @@ hidden by setting the `optReqFlag` prop to false.
   </DSProvider>
 </Canvas>
 
+<Canvas>
+  <DSProvider>
+    <Heading
+      id="heading-range-required"
+      level={HeadingLevels.Four}
+      text="Required State"
+    />
+    <Slider
+      defaultValue={[25, 75]}
+      helperText="Component helper text."
+      id="range-required-slider"
+      invalidText="Component error text :("
+      labelText="Label"
+      isRangeSlider
+      isRequired
+    />
+  </DSProvider>
+</Canvas>
+
 <Canvas>
   <DSProvider>
     <Heading
@@ -322,8 +390,8 @@ hidden by setting the `optReqFlag` prop to false.
     />
     <Slider
       defaultValue={[25, 75]}
-      optReqFlag={false}
       helperText="Component helper text."
+      id="single-disabled-slider"
       invalidText="Component error text :("
       labelText="Label"
       isRangeSlider
@@ -348,6 +416,7 @@ input are hidden.
       <Slider
         defaultValue={50}
         helperText="Component helper text."
+        id="single-slider-variant-1"
         labelText="Label"
         showValues={false}
         showBoxes={false}
@@ -355,6 +424,7 @@ input are hidden.
       <Slider
         defaultValue={50}
         helperText="Component helper text."
+        id="single-slider-variant-2"
         labelText="Label"
         showValues={false}
         showBoxes={false}
@@ -363,16 +433,16 @@ input are hidden.
       <Slider
         defaultValue={50}
         helperText="Component helper text."
+        id="single-slider-variant-3"
         labelText="Label"
-        optReqFlag={false}
         showValues={false}
         showBoxes={false}
       />
       <Slider
         defaultValue={50}
         helperText="Component helper text."
+        id="single-slider-variant-4"
         labelText="Label"
-        optReqFlag={false}
         showHelperInvalidText={false}
         showValues={false}
         showBoxes={false}
@@ -380,8 +450,8 @@ input are hidden.
       <Slider
         defaultValue={50}
         helperText="Component helper text."
+        id="single-slider-variant-5"
         labelText="Label"
-        optReqFlag={false}
         showValues={false}
         showBoxes={false}
         showLabel={false}
@@ -403,6 +473,7 @@ For the following examples, all labels are hidden.
       <Slider
         defaultValue={50}
         helperText="Component helper text."
+        id="hidden-labels-1"
         labelText="Label"
         showHelperInvalidText={false}
         showLabel={false}
@@ -410,6 +481,7 @@ For the following examples, all labels are hidden.
       <Slider
         defaultValue={50}
         helperText="Component helper text."
+        id="hidden-labels-2"
         labelText="Label"
         showHelperInvalidText={false}
         showLabel={false}
@@ -418,6 +490,7 @@ For the following examples, all labels are hidden.
       <Slider
         defaultValue={50}
         helperText="Component helper text."
+        id="hidden-labels-3"
         labelText="Label"
         showHelperInvalidText={false}
         showLabel={false}
@@ -426,6 +499,7 @@ For the following examples, all labels are hidden.
       <Slider
         defaultValue={50}
         helperText="Component helper text."
+        id="hidden-labels-4"
         labelText="Label"
         showHelperInvalidText={false}
         showLabel={false}
@@ -446,44 +520,48 @@ In the following examples, all the labels are hidden.
       <Slider
         defaultValue={[15, 75]}
         helperText="Component helper text."
+        id="range-slider-1"
+        isRangeSlider
         labelText="Label"
         showHelperInvalidText={false}
         showLabel={false}
-        isRangeSlider
       />
       <Slider
         defaultValue={[15, 75]}
         helperText="Component helper text."
+        id="range-slider-1"
+        isRangeSlider
         labelText="Label"
+        showBoxes={false}
         showHelperInvalidText={false}
         showLabel={false}
-        showBoxes={false}
-        isRangeSlider
       />
       <Slider
         defaultValue={[15, 75]}
         helperText="Component helper text."
+        id="range-slider-3"
+        isRangeSlider
         labelText="Label"
         showHelperInvalidText={false}
         showLabel={false}
         showValues={false}
-        isRangeSlider
       />
       <Slider
         defaultValue={[15, 75]}
         helperText="Component helper text."
+        id="range-slider-4"
+        isRangeSlider
         labelText="Label"
+        showBoxes={false}
         showHelperInvalidText={false}
         showLabel={false}
         showValues={false}
-        showBoxes={false}
-        isRangeSlider
       />
     </SimpleGrid>
   </DSProvider>
 </Canvas>
 
-### Get Data Values
+## Get Input Values
 
 Pass a callback function to the `onChange` prop to get the current number value
 of the `Slider` component or an array of two numbers when it is a range slider.
@@ -492,7 +570,7 @@ value or values. Once the value(s) is updated, the `onChange` callback will be
 called and the values will be passed. If no `onChange` callback is provided,
 you won't be able to get the updated value(s) of the `Slider` component.
 
-#### Single Slider Value
+### Single Slider Value
 
 Open up the browser's developer console to see the value of the `Slider`
 after updating it.
@@ -506,6 +584,7 @@ function SliderExample() {
   return (
     <Slider
       helperText="Component helper text."
+      id="slider"
       labelText="Label"
       onChange={onChange}
     />
@@ -520,6 +599,7 @@ export function SliderExample() {
   return (
     <Slider
       helperText="Component helper text."
+      id="slider"
       labelText="Label"
       onChange={onChange}
     />
@@ -532,7 +612,7 @@ export function SliderExample() {
   </DSProvider>
 </Canvas>
 
-#### Range Slider Values
+### Range Slider Values
 
 Open up the browser's developer console to see the values of the `Slider`
 after updating it in the `isRangeSlider` state.
@@ -548,9 +628,10 @@ function RangeSliderExample() {
   return (
     <Slider
       helperText="Component helper text."
+      id="range-slider"
+      isRangeSlider
       labelText="Label"
       onChange={onChange}
-      isRangeSlider
     />
   );
 }
@@ -566,9 +647,10 @@ export function RangeSliderExample() {
     <Slider
       defaultValue={[15, 75]}
       helperText="Component helper text."
+      id="range-slider"
+      isRangeSlider
       labelText="Label"
       onChange={onChange}
-      isRangeSlider
     />
   );
 }