@nypl/design-system-react-components 1.0.1 → 1.0.2

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

@@ -0,0 +1,628 @@
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import Heading from "../Heading/Heading";
+import SimpleGrid from "../Grid/SimpleGrid";
+import Slider from "./Slider";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta
+  title={getCategory("Slider")}
+  component={Slider}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=36889%3A25871",
+    },
+    jest: ["Slider.test.tsx"],
+  }}
+  argTypes={{
+    className: { control: false },
+    defaultValue: {
+      control: false,
+      table: { defaultValue: { summary: 0 } },
+    },
+    id: { control: false },
+    isDisabled: {
+      table: { defaultValue: { summary: false } },
+    },
+    isInvalid: {
+      table: { defaultValue: { summary: false } },
+    },
+    isRequired: {
+      table: { defaultValue: { summary: false } },
+    },
+    max: {
+      table: { defaultValue: { summary: 100 } },
+    },
+    min: {
+      table: { defaultValue: { summary: 0 } },
+    },
+    name: { control: false },
+    onChange: { control: false },
+    showBoxes: {
+      table: { defaultValue: { summary: true } },
+    },
+    showHelperInvalidText: {
+      table: { defaultValue: { summary: true } },
+    },
+    showLabel: {
+      table: { defaultValue: { summary: true } },
+    },
+    showRequiredLabel: {
+      table: { defaultValue: { summary: true } },
+    },
+    showValues: {
+      table: { defaultValue: { summary: true } },
+    },
+    step: {
+      table: { defaultValue: { summary: 1 } },
+    },
+  }}
+/>
+
+# Slider
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.25.4`   |
+| Latest            | `1.0.2`    |
+
+## 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"
+    args={{
+      className: undefined,
+      defaultValue: 50,
+      helperText: "Pass in a value from the min 0 to the max 100 values.",
+      id: "slider-id",
+      invalidText: "Oh no this is an error :(",
+      isDisabled: false,
+      isInvalid: false,
+      isRangeSlider: false,
+      isRequired: false,
+      labelText: "Slider label",
+      max: 100,
+      min: 0,
+      name: undefined,
+      onChange: undefined,
+      showBoxes: true,
+      showHelperInvalidText: true,
+      showLabel: true,
+      showRequiredLabel: true,
+      showValues: true,
+      step: 1,
+    }}
+    argTypes={{
+      isRangeSlider: {
+        control: false,
+        table: {
+          defaultValue: { summary: false },
+        },
+      },
+    }}
+  >
+    {(args) => <Slider {...args} />}
+  </Story>
+</Canvas>
+
+<ArgsTable story="Slider with Controls" />
+
+## 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 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`.
+
+## 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
+value. For this type of component, the `value` prop must be an array of two
+numbers. This signifies the starting and ending values of the range slider.
+
+<Canvas withToolbar>
+  <Story
+    name="RangeSlider with Controls"
+    args={{
+      className: undefined,
+      defaultValue: [25, 75],
+      helperText: "Pass in a value from the min 0 to the max 100 values.",
+      id: "slider-range-id",
+      invalidText: "Oh no this is an error :(",
+      isDisabled: false,
+      isInvalid: false,
+      isRangeSlider: true,
+      isRequired: false,
+      labelText: "Range Slider label",
+      max: 100,
+      min: 0,
+      name: undefined,
+      onChange: undefined,
+      showBoxes: true,
+      showHelperInvalidText: true,
+      showLabel: true,
+      showRequiredLabel: true,
+      showValues: true,
+      step: 1,
+    }}
+    argTypes={{
+      isRangeSlider: {
+        control: false,
+        table: {
+          defaultValue: { summary: false },
+        },
+      },
+    }}
+  >
+    {(args) => <Slider {...args} />}
+  </Story>
+</Canvas>
+
+### 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
+the expected standard string; the `RangeSlider` expect `aria-label` to be an array
+of two strings. On top of this, the DS `Slider`'s `<label>` element, when in the
+`isRangeSlider` state, points to the _first_ `<input>` element which shows the
+current _start_ value. These two `input` elements also have their own `aria-label`s.
+When the input boxes are hidden, the `for` attribute in the `label` element is removed.
+
+Note that Chakra handles its two slider thumbs aria attributes: `aria-valuemin`,
+`aria-valuemax`, `aria-valuenow`, and `aria-orientation`.
+
+## Examples
+
+### Single Slider States
+
+<Canvas>
+  <DSProvider>
+    <Heading id="heading-single-default" level="four" text="Default State" />
+    <Slider
+      defaultValue={50}
+      helperText="Component helper text."
+      id="single-slider"
+      invalidText="Component error text :("
+      labelText="Label"
+    />
+  </DSProvider>
+</Canvas>
+
+<Canvas>
+  <DSProvider>
+    <Heading id="heading-single-errored" level="four" text="Errored State" />
+    <Slider
+      defaultValue={50}
+      helperText="Component helper text."
+      id="errored-slider"
+      invalidText="Component error text :("
+      labelText="Label"
+      isInvalid
+    />
+  </DSProvider>
+</Canvas>
+
+<Canvas>
+  <DSProvider>
+    <Heading id="heading-single-required" level="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 id="heading-single-disabled" level="four" text="Disabled State" />
+    <Slider
+      defaultValue={50}
+      helperText="Component helper text."
+      id="disabled-slider"
+      invalidText="Component error text :("
+      labelText="Label"
+      isDisabled
+    />
+  </DSProvider>
+</Canvas>
+
+### Range Slider States
+
+To enable the Range Slider, set the `isRangeSlider` prop to true.
+
+<Canvas>
+  <DSProvider>
+    <Heading id="heading-range-default" level="four" text="Default State" />
+    <Slider
+      defaultValue={[25, 75]}
+      helperText="Component helper text."
+      id="range-slider"
+      invalidText="Component error text :("
+      labelText="Label"
+      isRangeSlider
+    />
+  </DSProvider>
+</Canvas>
+
+<Canvas>
+  <DSProvider>
+    <Heading id="heading-range-errored" level="four" text="Errored State" />
+    <SimpleGrid columns={1} gap="grid.l">
+      <Slider
+        defaultValue={[25, 75]}
+        helperText="Component helper text."
+        id="range-error-slider"
+        invalidText="Component error text :("
+        labelText="Label"
+        isRangeSlider
+        isInvalid
+      />
+      <p>
+        Note: The slider does not allow the starting thumb to go past the ending
+        thumb. Likewise, it also does not allow the ending thumb to go below the
+        starting thumb. However, it's possible to set incorrect values directly
+        into both of the text inputs. For example, if you enter 80 in the first
+        text input box and 20 in the second input box, it will automatically go
+        into the invalid state. In the following example, the default values are
+        already set to 80 and 20 *just* to showcase this error.
+      </p>
+      <Slider
+        defaultValue={[80, 20]}
+        helperText="Component helper text."
+        id="range-error-slider2"
+        invalidText="Component error text :("
+        labelText="Label"
+        isRangeSlider
+      />
+    </SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+<Canvas>
+  <DSProvider>
+    <Heading id="heading-range-required" level="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 id="heading-range-disabled" level="four" text="Disabled State" />
+    <Slider
+      defaultValue={[25, 75]}
+      helperText="Component helper text."
+      id="single-disabled-slider"
+      invalidText="Component error text :("
+      labelText="Label"
+      isRangeSlider
+      isDisabled
+    />
+  </DSProvider>
+</Canvas>
+
+### Single Slider Variants
+
+In the following example, the min/max values and the current value text
+input are hidden.
+
+<Canvas>
+  <DSProvider>
+    <Heading
+      id="heading-single-labels"
+      level="four"
+      text="With and Without Component Labels"
+    />
+    <SimpleGrid columns={1} gap="grid.xl">
+      <Slider
+        defaultValue={50}
+        helperText="Component helper text."
+        id="single-slider-variant-1"
+        labelText="Label"
+        showValues={false}
+        showBoxes={false}
+      />
+      <Slider
+        defaultValue={50}
+        helperText="Component helper text."
+        id="single-slider-variant-2"
+        labelText="Label"
+        showValues={false}
+        showBoxes={false}
+        isRequired
+      />
+      <Slider
+        defaultValue={50}
+        helperText="Component helper text."
+        id="single-slider-variant-3"
+        labelText="Label"
+        showValues={false}
+        showBoxes={false}
+      />
+      <Slider
+        defaultValue={50}
+        helperText="Component helper text."
+        id="single-slider-variant-4"
+        labelText="Label"
+        showHelperInvalidText={false}
+        showValues={false}
+        showBoxes={false}
+      />
+      <Slider
+        defaultValue={50}
+        helperText="Component helper text."
+        id="single-slider-variant-5"
+        labelText="Label"
+        showValues={false}
+        showBoxes={false}
+        showLabel={false}
+      />
+    </SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+For the following examples, all labels are hidden.
+
+<Canvas>
+  <DSProvider>
+    <Heading
+      id="heading-single-labels-inputs"
+      level="four"
+      text="With and Without Internal Inputs and Labels"
+    />
+    <SimpleGrid columns={1} gap="grid.xl">
+      <Slider
+        defaultValue={50}
+        helperText="Component helper text."
+        id="hidden-labels-1"
+        labelText="Label"
+        showHelperInvalidText={false}
+        showLabel={false}
+      />
+      <Slider
+        defaultValue={50}
+        helperText="Component helper text."
+        id="hidden-labels-2"
+        labelText="Label"
+        showHelperInvalidText={false}
+        showLabel={false}
+        showBoxes={false}
+      />
+      <Slider
+        defaultValue={50}
+        helperText="Component helper text."
+        id="hidden-labels-3"
+        labelText="Label"
+        showHelperInvalidText={false}
+        showLabel={false}
+        showValues={false}
+      />
+      <Slider
+        defaultValue={50}
+        helperText="Component helper text."
+        id="hidden-labels-4"
+        labelText="Label"
+        showHelperInvalidText={false}
+        showLabel={false}
+        showValues={false}
+        showBoxes={false}
+      />
+    </SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+### Range Slider with Adjusted Handles
+
+In the following examples, all the labels are hidden.
+
+<Canvas>
+  <DSProvider>
+    <SimpleGrid columns={1} gap="grid.xl">
+      <Slider
+        defaultValue={[15, 75]}
+        helperText="Component helper text."
+        id="range-slider-1"
+        isRangeSlider
+        labelText="Label"
+        showHelperInvalidText={false}
+        showLabel={false}
+      />
+      <Slider
+        defaultValue={[15, 75]}
+        helperText="Component helper text."
+        id="range-slider-1"
+        isRangeSlider
+        labelText="Label"
+        showBoxes={false}
+        showHelperInvalidText={false}
+        showLabel={false}
+      />
+      <Slider
+        defaultValue={[15, 75]}
+        helperText="Component helper text."
+        id="range-slider-3"
+        isRangeSlider
+        labelText="Label"
+        showHelperInvalidText={false}
+        showLabel={false}
+        showValues={false}
+      />
+      <Slider
+        defaultValue={[15, 75]}
+        helperText="Component helper text."
+        id="range-slider-4"
+        isRangeSlider
+        labelText="Label"
+        showBoxes={false}
+        showHelperInvalidText={false}
+        showLabel={false}
+        showValues={false}
+      />
+    </SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+## 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.
+Internally, the `Slider` component handles the state of the current selected
+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
+
+Open up the browser's developer console to see the value of the `Slider`
+after updating it.
+
+```tsx
+// Typescript example:
+function SliderExample() {
+  const onChange = (newValue: number) => {
+    console.log(`The single Slider updated value is: ${newValue}`);
+  };
+  return (
+    <Slider
+      helperText="Component helper text."
+      id="slider"
+      labelText="Label"
+      onChange={onChange}
+    />
+  );
+}
+```
+
+export function SliderExample() {
+  const onChange = (newValue) => {
+    console.log(`The single Slider updated value is: ${newValue}`);
+  };
+  return (
+    <Slider
+      helperText="Component helper text."
+      id="slider"
+      labelText="Label"
+      onChange={onChange}
+    />
+  );
+}
+
+<Canvas>
+  <DSProvider>
+    <SliderExample />
+  </DSProvider>
+</Canvas>
+
+### Range Slider Values
+
+Open up the browser's developer console to see the values of the `Slider`
+after updating it in the `isRangeSlider` state.
+
+```tsx
+// Typescript example:
+function RangeSliderExample() {
+  const onChange = (newValue: number[]) => {
+    const [start, end] = newValue;
+    console.log(`The Range Slider updated start value is: ${start}`);
+    console.log(`The Range Slider updated end value is: ${end}`);
+  };
+  return (
+    <Slider
+      helperText="Component helper text."
+      id="range-slider"
+      isRangeSlider
+      labelText="Label"
+      onChange={onChange}
+    />
+  );
+}
+```
+
+export function RangeSliderExample() {
+  const onChange = (newValue) => {
+    const [start, end] = newValue;
+    console.log(`The Range Slider updated start value is: ${start}`);
+    console.log(`The Range Slider updated end value is: ${end}`);
+  };
+  return (
+    <Slider
+      defaultValue={[15, 75]}
+      helperText="Component helper text."
+      id="range-slider"
+      isRangeSlider
+      labelText="Label"
+      onChange={onChange}
+    />
+  );
+}
+
+<Canvas>
+  <DSProvider>
+    <RangeSliderExample />
+  </DSProvider>
+</Canvas>