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

package/src/components/Select/Select.stories.mdx

@@ -0,0 +1,439 @@
+import { VStack } from "@chakra-ui/react";
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import Button from "../Button/Button";
+import Form, { FormField } from "../Form/Form";
+import Select from "./Select";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta
+  title={getCategory("Select")}
+  component={Select}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=11895%3A549",
+    },
+    jest: ["Select.test.tsx"],
+  }}
+  argTypes={{
+    children: { table: { disable: true } },
+    id: { control: false },
+    isDisabled: {
+      table: { defaultValue: { summary: false } },
+    },
+    isInvalid: {
+      table: { defaultValue: { summary: false } },
+    },
+    isRequired: {
+      table: { defaultValue: { summary: false } },
+    },
+    labelPosition: {
+      table: { defaultValue: { summary: "default" } },
+    },
+    name: { control: false },
+    key: { table: { disable: true } },
+    onChange: { control: false },
+    ref: { table: { disable: true } },
+    showHelperInvalidText: {
+      table: { defaultValue: { summary: true } },
+    },
+    showLabel: {
+      table: { defaultValue: { summary: true } },
+    },
+    showRequiredLabel: {
+      table: { defaultValue: { summary: true } },
+    },
+    selectType: {
+      control: false,
+      table: { defaultValue: { summary: "default" } },
+    },
+    value: { control: false },
+  }}
+/>
+
+# Select
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.7.0`    |
+| Latest            | `1.0.2`    |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Option Elements](#option-elements)
+- [Labelling Variations](#labelling-variations)
+- [Errored](#errored)
+- [Disabled](#disabled)
+- [Getting Select Input Value](#getting-select-input-value)
+
+## Overview
+
+<Description of={Select} />
+
+The `Select` component renders a `select` element along with its `option`
+children. For optimal accessibility, the `labelText` property is a required
+prop, regardless of the label visibility. Additionally, while the `id` prop is
+optional, a unique `id` attribute is necessary for accessibility. If the prop
+is left blank, a value will be generated for you.
+
+## Component Props
+
+<Canvas withToolbar>
+  <Story
+    name="Select with Controls"
+    args={{
+      className: undefined,
+      helperText: "This is the helper text.",
+      id: "select-id",
+      invalidText: "This is the error text :(",
+      isDisabled: false,
+      isInvalid: false,
+      isRequired: false,
+      labelPosition: "default",
+      labelText: "What is your favorite color?",
+      name: "color",
+      onChange: undefined,
+      showHelperInvalidText: undefined,
+      showLabel: true,
+      showRequiredLabel: true,
+      selectType: "default",
+      value: undefined,
+    }}
+  >
+    {(args) => (
+      <Select {...args}>
+        <option value="red">Red</option>
+        <option value="green">Green</option>
+        <option value="blue">Blue</option>
+        <option value="black">Black</option>
+        <option value="white">White</option>
+      </Select>
+    )}
+  </Story>
+</Canvas>
+
+<ArgsTable story="Select with Controls" />
+
+## Accessibility
+
+The `Select` component renders an HTML `<select>` element which is accessible.
+It's the developer's responsibility to ensure that the appropriate `<option>`
+elements are provided as children. Internally, a `Label` is associated with the
+`<select>` element.
+
+When `showLabel` is set to false, the `labelText` value will be set to the
+`<select>`'s `aria-label` attribute.
+
+Resources:
+
+- [MDN select: The HTML Select element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select)
+- [Chakra UI Select](https://chakra-ui.com/docs/components/form/select)
+
+## Option Elements
+
+The `Select` component renders all the necessary wrapping and associated text
+elements, but the select options _need_ to be child `<option>` HTML elements.
+
+```jsx
+<Select id="select" labelText="What is your favorite color?" name="color">
+  <option value="red">Red</option>
+  <option value="green">Green</option>
+  <option value="blue">Blue</option>
+  <option value="black">Black</option>
+  <option value="white">White</option>
+</Select>
+```
+
+There are two NYPL best practices to consider when using the `Select` component
+and `option` HTML elements:
+
+- Use no more than 10 options. If more than 10 options are needed, an
+  auto-complete text input is a good alternative.
+- Use at least four options. If fewer than three options are needed, a radio
+  button group is a good alternative.
+
+## Labelling Variations
+
+A Select can be rendered with or without a visible label. If the label is visible,
+it can be displayed above (the default) or inline with the select input using the
+`labelPosition` prop. Note that the label will only display inline when the device
+width exceeds the `--nypl-breakpoint-medium` breakpoint, or 600px. When `showLabel`
+is set to `false`, an `aria-label` attribute is added to the select input to maintain
+accessibility. If the component needs to be required, the `showRequiredLabel` prop
+can be used to show or hide the "Required" text within the `label` element.
+
+<Canvas>
+  <Story name="Labelling Variations">
+    <VStack align="stretch" spacing={8}>
+      <Select
+        helperText="Display the label"
+        id="label-example1"
+        labelText="What is your favorite color?"
+        name="color"
+      >
+        <option value="red">Red</option>
+        <option value="green">Green</option>
+        <option value="blue">Blue</option>
+        <option value="black">Black</option>
+        <option value="white">White</option>
+      </Select>
+      <Select
+        helperText="Do not display the label"
+        id="label-example2"
+        labelText="What is your favorite color?"
+        name="color"
+        showLabel={false}
+      >
+        <option value="red">Red</option>
+        <option value="green">Green</option>
+        <option value="blue">Blue</option>
+        <option value="black">Black</option>
+        <option value="white">White</option>
+      </Select>
+      <Select
+        helperText="Display the Required text"
+        id="label-example3"
+        isRequired
+        labelText="What is your favorite color?"
+        name="color"
+      >
+        <option value="red">Red</option>
+        <option value="green">Green</option>
+        <option value="blue">Blue</option>
+        <option value="black">Black</option>
+        <option value="white">White</option>
+      </Select>
+      <Select
+        helperText="Do not display the Required text"
+        id="label-example4"
+        isRequired
+        labelText="What is your favorite color?"
+        name="color"
+        showRequiredLabel={false}
+      >
+        <option value="red">Red</option>
+        <option value="green">Green</option>
+        <option value="blue">Blue</option>
+        <option value="black">Black</option>
+        <option value="white">White</option>
+      </Select>
+      <Select
+        helperText="Display the label inline"
+        id="label-example5"
+        isRequired
+        labelText="What is your favorite color?"
+        name="color"
+        labelPosition="inline"
+      >
+        <option value="red">Red</option>
+        <option value="green">Green</option>
+        <option value="blue">Blue</option>
+        <option value="black">Black</option>
+        <option value="white">White</option>
+      </Select>
+    </VStack>
+  </Story>
+</Canvas>
+
+## Errored
+
+<Canvas>
+  <DSProvider>
+    <Select
+      helperText="This is the helper text."
+      id="errored"
+      invalidText="This is the error text :("
+      isInvalid
+      labelText="What is your favorite color?"
+      name="color"
+    >
+      <option value="red">Red</option>
+      <option value="green">Green</option>
+      <option value="blue">Blue</option>
+      <option value="black">Black</option>
+      <option value="white">White</option>
+    </Select>
+  </DSProvider>
+</Canvas>
+
+## Disabled
+
+<Canvas>
+  <DSProvider>
+    <Select
+      helperText="This is the helper text."
+      id="disabled"
+      invalidText="This is the error text :("
+      isDisabled
+      labelText="What is your favorite color?"
+      name="color"
+    >
+      <option value="red">Red</option>
+      <option value="green">Green</option>
+      <option value="blue">Blue</option>
+      <option value="black">Black</option>
+      <option value="white">White</option>
+    </Select>
+  </DSProvider>
+</Canvas>
+
+## Getting Select Input Value
+
+### Controlled Component using `value` and `onChange` props
+
+If your application uses controlled React components and the Reservoir Design
+System (DS) `Select` component must be controlled, you can pass and extract the
+value through the `value` and `onChange` props. This will be called every time
+a new `option` value is selected.
+
+Try it out: open up the browser's console to see new values being logged on
+each change.
+
+```jsx
+export function SelectControlledExample() {
+  const [value, setValue] = React.useState();
+  const onChange = (e) => {
+    // This will return the value selected through the event object.
+    console.log(e.target.value);
+    setValue(e.target.value);
+  };
+  return (
+    <Select
+      helperText="This is the helper text."
+      id="example-1"
+      labelText="What is your favorite color?"
+      name="color"
+      onChange={onChange}
+      value={value}
+    >
+      <option value="red">Red</option>
+      <option value="green">Green</option>
+      <option value="blue">Blue</option>
+      <option value="black">Black</option>
+      <option value="white">White</option>
+    </Select>
+  );
+}
+```
+
+export function SelectControlledExample() {
+  const [value, setValue] = React.useState();
+  const onChange = (e) => {
+    // This will return the value selected through the event object.
+    console.log("Controlled value:", e.target.value);
+    setValue(e.target.value);
+  };
+  return (
+    <Select
+      helperText="This is the helper text."
+      id="example-1"
+      labelText="What is your favorite color?"
+      name="color"
+      onChange={onChange}
+      value={value}
+    >
+      <option value="red">Red</option>
+      <option value="green">Green</option>
+      <option value="blue">Blue</option>
+      <option value="black">Black</option>
+      <option value="white">White</option>
+    </Select>
+  );
+}
+
+<Canvas>
+  <DSProvider>
+    <SelectControlledExample />
+  </DSProvider>
+</Canvas>
+
+### Uncontrolled Component using `ref`s
+
+If your application uses uncontrolled components, you can pass a React `ref`
+prop to the DS Select component to get the selected value from the DOM. Note
+that this example uses a `Form` and a `Button` to submit the form, only then
+will the value be available.
+
+Try it out: open up the browser's console to see new values being logged on
+each change.
+
+```jsx
+export function SelectUncontrolledExample() {
+  const selectRef = React.createRef();
+  const onSubmit = () => {
+    const selectValue = selectRef.current.value;
+    console.log("Using uncontrolled ref:", selectValue);
+  };
+  return (
+    <Form id="form">
+      <FormField>
+        <Select
+          helperText="This is the helper text."
+          id="example-2"
+          labelText="What is your favorite color?"
+          name="color"
+          ref={selectRef}
+        >
+          <option value="red">Red</option>
+          <option value="green">Green</option>
+          <option value="blue">Blue</option>
+          <option value="black">Black</option>
+          <option value="white">White</option>
+        </Select>
+        <Button id="submit" onClick={onSubmit}>
+          Submit
+        </Button>
+      </FormField>
+    </Form>
+  );
+}
+```
+
+export function SelectUncontrolledExample() {
+  const selectRef = React.createRef();
+  const onSubmit = () => {
+    const selectValue = selectRef.current.value;
+    console.log("Using uncontrolled ref:", selectValue);
+  };
+  return (
+    <Form id="form">
+      <FormField>
+        <Select
+          helperText="This is the helper text."
+          id="example-2"
+          labelText="What is your favorite color?"
+          name="color"
+          ref={selectRef}
+        >
+          <option value="red">Red</option>
+          <option value="green">Green</option>
+          <option value="blue">Blue</option>
+          <option value="black">Black</option>
+          <option value="white">White</option>
+        </Select>
+        <Button id="submit" onClick={onSubmit}>
+          Submit
+        </Button>
+      </FormField>
+    </Form>
+  );
+}
+
+<Canvas>
+  <DSProvider>
+    <SelectUncontrolledExample />
+  </DSProvider>
+</Canvas>