@nypl/design-system-react-components 0.25.12 → 0.26.1

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

@@ -9,14 +9,21 @@ import {
 import { withDesign } from "storybook-addon-designs";
 
 import Button from "../Button/Button";
-import Form from "../Form/Form";
+import Form, { FormField } from "../Form/Form";
 import Select from "./Select";
-import { SelectTypes } from "./SelectTypes";
+import { SelectTypes, LabelPositions } from "./SelectTypes";
 import { getCategory } from "../../utils/componentCategories";
 import DSProvider from "../../theme/provider";
 import { getStorybookEnumValues } from "../../utils/utils";
 
-export const enumValues = getStorybookEnumValues(SelectTypes, "SelectTypes");
+export const selectTypesEnumValues = getStorybookEnumValues(
+  SelectTypes,
+  "SelectTypes"
+);
+export const labelPositionsEnumValues = getStorybookEnumValues(
+  LabelPositions,
+  "LabelPositions"
+);
 
 <Meta
   title={getCategory("Select")}
@@ -41,6 +48,11 @@ export const enumValues = getStorybookEnumValues(SelectTypes, "SelectTypes");
     isRequired: {
       table: { defaultValue: { summary: false } },
     },
+    labelPosition: {
+      control: { type: "select" },
+      table: { defaultValue: { summary: "LabelPositions.Default" } },
+      options: labelPositionsEnumValues.options,
+    },
     name: { control: false },
     key: { table: { disable: true } },
     onChange: { control: false },
@@ -51,10 +63,10 @@ export const enumValues = getStorybookEnumValues(SelectTypes, "SelectTypes");
     showLabel: {
       table: { defaultValue: { summary: true } },
     },
-    showOptReqLabel: {
+    showRequiredLabel: {
       table: { defaultValue: { summary: true } },
     },
-    type: {
+    selectType: {
       control: false,
       table: { defaultValue: { summary: "SelectTypes.Default" } },
     },
@@ -67,7 +79,20 @@ export const enumValues = getStorybookEnumValues(SelectTypes, "SelectTypes");
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.7.0`    |
-| Latest            | `0.25.12`  |
+| Latest            | `0.26.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} />
 
@@ -77,18 +102,7 @@ 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.
 
-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 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>
-```
+## Component Props
 
 <Canvas withToolbar>
   <Story
@@ -101,18 +115,22 @@ elements, but the select options _need_ to be child `<option>` HTML elements.
       isDisabled: false,
       isInvalid: false,
       isRequired: false,
+      labelPosition: "LabelPositions.Default",
       labelText: "What is your favorite color?",
       name: "color",
       onChange: undefined,
       showHelperInvalidText: undefined,
       showLabel: true,
-      showOptReqLabel: true,
-      type: SelectTypes.Default,
+      showRequiredLabel: true,
+      selectType: SelectTypes.Default,
       value: undefined,
     }}
   >
     {(args) => (
-      <Select {...args}>
+      <Select
+        {...args}
+        labelPosition={labelPositionsEnumValues.getValue(args.labelPosition)}
+      >
         <option value="red">Red</option>
         <option value="green">Green</option>
         <option value="blue">Blue</option>
@@ -125,19 +143,60 @@ elements, but the select options _need_ to be child `<option>` HTML elements.
 
 <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. 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
-`showOptReqLabel` prop can be used to show or hide the "Required"/"Optional"
-text within the `label` element.
+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"
       >
@@ -149,6 +208,7 @@ text within the `label` element.
       </Select>
       <Select
         helperText="Do not display the label"
+        id="label-example2"
         labelText="What is your favorite color?"
         name="color"
         showLabel={false}
@@ -160,7 +220,8 @@ text within the `label` element.
         <option value="white">White</option>
       </Select>
       <Select
-        helperText="Display the Required/Optional text"
+        helperText="Display the Required text"
+        id="label-example3"
         isRequired
         labelText="What is your favorite color?"
         name="color"
@@ -172,11 +233,25 @@ text within the `label` element.
         <option value="white">White</option>
       </Select>
       <Select
-        helperText="Do not display the Required/Optional text"
+        helperText="Do not display the Required text"
+        id="label-example4"
         isRequired
         labelText="What is your favorite color?"
         name="color"
-        showOptReqLabel={false}
+        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"
+        isRequired
+        labelText="What is your favorite color?"
+        name="color"
+        labelPosition={LabelPositions.Inline}
       >
         <option value="red">Red</option>
         <option value="green">Green</option>
@@ -194,6 +269,7 @@ text within the `label` element.
   <DSProvider>
     <Select
       helperText="This is the helper text."
+      id="errored"
       invalidText="This is the error text :("
       isInvalid
       labelText="What is your favorite color?"
@@ -214,6 +290,7 @@ text within the `label` element.
   <DSProvider>
     <Select
       helperText="This is the helper text."
+      id="disabled"
       invalidText="This is the error text :("
       isDisabled
       labelText="What is your favorite color?"
@@ -228,14 +305,14 @@ text within the `label` element.
   </DSProvider>
 </Canvas>
 
-## Getting Select Data Value
+## Getting Select Input Value
 
 ### Controlled Component using `value` and `onChange` props
 
-If your application uses controlled React components and the 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.
+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.
@@ -251,6 +328,7 @@ export function SelectControlledExample() {
   return (
     <Select
       helperText="This is the helper text."
+      id="example-1"
       labelText="What is your favorite color?"
       name="color"
       onChange={onChange}
@@ -276,6 +354,7 @@ export function SelectControlledExample() {
   return (
     <Select
       helperText="This is the helper text."
+      id="example-1"
       labelText="What is your favorite color?"
       name="color"
       onChange={onChange}
@@ -314,20 +393,25 @@ export function SelectUncontrolledExample() {
     console.log("Using uncontrolled ref:", selectValue);
   };
   return (
-    <Form>
-      <Select
-        helperText="This is the helper text."
-        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 onClick={onSubmit}>Submit</Button>
+    <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>
   );
 }
@@ -340,20 +424,25 @@ export function SelectUncontrolledExample() {
     console.log("Using uncontrolled ref:", selectValue);
   };
   return (
-    <Form>
-      <Select
-        helperText="This is the helper text."
-        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 onClick={onSubmit}>Submit</Button>
+    <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>
   );
 }

package/src/components/Select/Select.test.tsx

@@ -4,10 +4,12 @@ import { axe } from "jest-axe";
 import renderer from "react-test-renderer";
 
 import Select from "./Select";
+import { LabelPositions } from "./SelectTypes";
 
 const baseProps = {
-  labelText: "What is your favorite color?",
   helperText: "This is the helper text.",
+  id: "select",
+  labelText: "What is your favorite color?",
   name: "color",
 };
 const baseOptions = (
@@ -79,26 +81,17 @@ describe("Select", () => {
     ).toHaveAttribute("aria-describedby", `${id}-helperText`);
   });
 
-  it("renders required or optional text in the label", () => {
-    const { rerender } = render(<Select {...baseProps}>{baseOptions}</Select>);
-    expect(screen.getByText(/Optional/i)).toBeInTheDocument();
-
-    rerender(
+  it("renders '(Required)' text in the label", () => {
+    const { rerender } = render(
       <Select {...baseProps} isRequired>
         {baseOptions}
       </Select>
     );
-    expect(screen.getByText(/Required/i)).toBeInTheDocument();
 
-    rerender(
-      <Select {...baseProps} showOptReqLabel={false}>
-        {baseOptions}
-      </Select>
-    );
-    expect(screen.queryByText(/Optional/i)).not.toBeInTheDocument();
+    expect(screen.getByText(/Required/i)).toBeInTheDocument();
 
     rerender(
-      <Select {...baseProps} isRequired showOptReqLabel={false}>
+      <Select {...baseProps} isRequired showRequiredLabel={false}>
         {baseOptions}
       </Select>
     );
@@ -120,9 +113,9 @@ describe("Select", () => {
     ).toHaveAttribute("required");
   });
 
-  it("should not render a required label if 'showOptReqLabel' flag is false, but still render the label", () => {
+  it("should not render a required label if 'showRequiredLabel' flag is false, but still render the label", () => {
     render(
-      <Select {...baseProps} isRequired showOptReqLabel={false}>
+      <Select {...baseProps} isRequired showRequiredLabel={false}>
         {baseOptions}
       </Select>
     );
@@ -222,44 +215,22 @@ describe("Select", () => {
     expect(value).toEqual("white");
   });
 
-  it("should throw warning when fewer than 4 options", () => {
-    const warn = jest.spyOn(console, "warn");
-    render(
-      <Select {...baseProps}>
-        <option value="red">Red</option>
-      </Select>
-    );
-    expect(warn).toHaveBeenCalledWith(
-      "NYPL DS recommends that <select> fields have at least 4 options; a radio button group is a good alternative for 3 or fewer options."
-    );
-  });
-
-  it("should throw warning when there are more than 10 options", () => {
+  it("logs a warning when there is no `id` passed", () => {
     const warn = jest.spyOn(console, "warn");
     render(
-      <Select {...baseProps}>
-        <option aria-selected={false}>test1</option>
-        <option aria-selected={false}>test2</option>
-        <option aria-selected={false}>test3</option>
-        <option aria-selected={false}>test4</option>
-        <option aria-selected={false}>test5</option>
-        <option aria-selected={false}>test6</option>
-        <option aria-selected={false}>test7</option>
-        <option aria-selected={false}>test8</option>
-        <option aria-selected={false}>test9</option>
-        <option aria-selected={false}>test10</option>
-        <option aria-selected={false}>test11</option>
+      // @ts-ignore: Typescript complains when a required prop is not passed, but
+      // here we don't want to pass the required prop to make sure the warning appears.
+      <Select labelText="What is your favorite color?" name="color">
+        {baseOptions}
       </Select>
     );
-
     expect(warn).toHaveBeenCalledWith(
-      "NYPL DS recommends that <select> fields have no more than 10 options; an auto-complete text input is a good alternative for 11 or more options."
+      "NYPL Reservoir Select: This component's required `id` prop was not passed."
     );
   });
 
   it("Renders the UI snapshot correctly", () => {
     const siblings = ["Kendall", "Shiv", "Connor", "Roman", "Tom"];
-
     const options = siblings.map((sibling) => (
       <option key={sibling}>{sibling}</option>
     ));
@@ -324,6 +295,19 @@ describe("Select", () => {
         </Select>
       )
       .toJSON();
+    const withLabelInline = renderer
+      .create(
+        <Select
+          id="select"
+          isRequired
+          labelPosition={LabelPositions.Inline}
+          labelText="Which Succession sibling are you?"
+          name="succession-sibling"
+        >
+          {options}
+        </Select>
+      )
+      .toJSON();
     const hasOnChange = renderer
       .create(
         <Select
@@ -336,12 +320,40 @@ describe("Select", () => {
         </Select>
       )
       .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <Select
+          id="chakra"
+          labelText="Which Succession sibling are you?"
+          name="succession-sibling"
+          p="20px"
+          color="ui.error.primary"
+        >
+          {options}
+        </Select>
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(
+        <Select
+          id="props"
+          labelText="Which Succession sibling are you?"
+          name="succession-sibling"
+          data-testid="props"
+        >
+          {options}
+        </Select>
+      )
+      .toJSON();
 
     expect(primary).toMatchSnapshot();
     expect(disabled).toMatchSnapshot();
     expect(withInvalidText).toMatchSnapshot();
     expect(withHelperText).toMatchSnapshot();
     expect(required).toMatchSnapshot();
+    expect(withLabelInline).toMatchSnapshot();
     expect(hasOnChange).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
   });
 });