@nypl/design-system-react-components 1.0.0 → 1.0.3-beta

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

@@ -1,439 +0,0 @@
-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            | `0.28.0`   |
-
-## 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>