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

package/src/components/Form/Form.stories.mdx

@@ -0,0 +1,426 @@
+import { Flex, Spacer } from "@chakra-ui/react";
+import { action } from "@storybook/addon-actions";
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import Button from "../Button/Button";
+import ButtonGroup from "../ButtonGroup/ButtonGroup";
+import Checkbox from "../Checkbox/Checkbox";
+import CheckboxGroup from "../CheckboxGroup/CheckboxGroup";
+import DatePicker from "../DatePicker/DatePicker";
+import Form, { FormRow, FormField } from "./Form";
+import Heading from "../Heading/Heading";
+import HorizontalRule from "../HorizontalRule/HorizontalRule";
+import Label from "../Label/Label";
+import Radio from "../Radio/Radio";
+import RadioGroup from "../RadioGroup/RadioGroup";
+import Select from "../Select/Select";
+import SimpleGrid from "../Grid/SimpleGrid";
+import TextInput from "../TextInput/TextInput";
+import { getCategory } from "../../utils/componentCategories";
+
+<Meta
+  title={getCategory("Form")}
+  component={Form}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=11895%3A547",
+    },
+    jest: ["Form.test.tsx"],
+  }}
+  argTypes={{
+    action: { control: false },
+    id: { control: false },
+    method: {
+      control: { type: "radio" },
+      options: ["get", "post"],
+    },
+    gap: {
+      control: { type: "select" },
+      table: { defaultValue: { summary: "grid.l" } },
+      options: [
+        "grid.xxs",
+        "grid.xs",
+        "grid.s",
+        "grid.m",
+        "grid.l",
+        "grid.xl",
+        "grid.xxl",
+      ],
+    },
+  }}
+/>
+
+# Form
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.23.2`   |
+| Latest            | `0.28.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Spacing Variants](#spacing-variants)
+- [Example Code](#example-code)
+
+## Overview
+
+<Description of={Form} />
+
+The `Form` component renders a standard `<form>` element and should be used to
+handle layout and spacing for child input fields. `FormRow` and `FormField`
+components should be used to build the `<form>` structure and to arrange input
+fields as needed.
+
+```jsx
+<Form id="form-id">
+  <FormRow>
+    <FormField>{/* ... */}</FormField>
+  </FormRow>
+  <FormRow>
+    <FormField>{/* ... */}</FormField>
+  </FormRow>
+</Form>
+```
+
+`FormField` should be used as a parent for all input components from the
+Reservoir Design System (DS) (`Button`, `Select`, `TextInput`, etc.).
+
+`FormRow` should be used as a parent of multiple `FormField` components when
+you need to render multiple input components in a horizontal row.
+
+## Component Props
+
+<Canvas withToolbar>
+  <Story
+    name="Form with Controls"
+    args={{
+      action: "/end/point",
+      className: undefined,
+      id: "form-id",
+      method: "get",
+      gap: "grid.l",
+    }}
+  >
+    {(args) => (
+      <Form {...args} id="form-id">
+        <FormRow>
+          <FormField>
+            <TextInput
+              helperText="Make sure to complete this field."
+              id="first-name"
+              isRequired
+              labelText="First Name"
+            />
+          </FormField>
+          <FormField>
+            <TextInput
+              helperText="Make sure to complete this field."
+              id="last-name"
+              isRequired
+              labelText="Last Name"
+            />
+          </FormField>
+          <FormField>
+            <DatePicker
+              dateType="full"
+              dateFormat="yyyy-MM-dd"
+              helperTextFrom="From this date."
+              helperTextTo="To this date."
+              helperText="Select a valid date range."
+              id="date-range"
+              invalidText="Please select a valid date range."
+              isDateRange
+              labelText="Select the date range you want to visit NYPL"
+              minDate="1/1/2021"
+              maxDate="1/1/2022"
+              nameFrom="visit-dates"
+              showLabel={false}
+            />
+          </FormField>
+        </FormRow>
+        <FormField>
+          <TextInput
+            helperText="Make sure to complete this field."
+            id="username"
+            isRequired
+            labelText="Username"
+          />
+        </FormField>
+        <FormField>
+          <TextInput
+            helperText="Make sure to complete this field."
+            id="password"
+            isRequired
+            labelText="Password"
+          />
+        </FormField>
+        <FormRow>
+          <FormField>
+            <TextInput
+              helperText="This one is up to you."
+              id="phone"
+              labelText="Phone Field"
+              type="tel"
+            />
+          </FormField>
+          <FormField>
+            <TextInput
+              helperText="This one is up to you."
+              id="url"
+              labelText="URL Field"
+              type="url"
+            />
+          </FormField>
+          <FormField>
+            <TextInput
+              helperText="This one is up to you."
+              id="age"
+              labelText="Age"
+              type="number"
+            />
+          </FormField>
+        </FormRow>
+        <FormRow>
+          <FormField>
+            <CheckboxGroup
+              id="checkbox-group"
+              isFullWidth
+              labelText="Checkbox Group"
+              name="checkbox-example"
+            >
+              <Checkbox
+                id="arts"
+                labelText={
+                  <Flex>
+                    <span>Arts</span>
+                    <Spacer />
+                    <span>4</span>
+                  </Flex>
+                }
+                value="arts"
+              />
+              <Checkbox
+                id="english"
+                labelText={
+                  <Flex>
+                    <span>English</span>
+                    <Spacer />
+                    <span>23</span>
+                  </Flex>
+                }
+                value="English"
+              />
+              <Checkbox
+                id="science"
+                labelText={
+                  <Flex>
+                    <span>Science</span>
+                    <Spacer />
+                    <span>10</span>
+                  </Flex>
+                }
+                value="Science"
+              />
+              <Checkbox
+                id="math"
+                labelText={
+                  <Flex>
+                    <span>Math</span>
+                    <Spacer />
+                    <span>3</span>
+                  </Flex>
+                }
+                value="Math"
+              />
+            </CheckboxGroup>
+          </FormField>
+          <FormField>
+            <RadioGroup id="radio-group" labelText="Radio Group" name="rg1">
+              <Radio id="radio1" labelText="Radio 1" value="radio1" />
+              <Radio id="radio2" labelText="Radio 2" value="radio2" />
+              <Radio id="radio3" labelText="Radio 3" value="radio3" />
+              <Radio id="radio4" labelText="Radio 4" value="radio4" />
+            </RadioGroup>
+          </FormField>
+          <FormField>
+            <Select
+              helperText="The select field helper text."
+              id="select"
+              labelText="Select Field"
+              showLabel={true}
+            >
+              <option>Option 1</option>
+              <option>Option 2</option>
+              <option>Option 3</option>
+              <option>Option 4</option>
+              <option>Option 5</option>
+            </Select>
+          </FormField>
+        </FormRow>
+        <FormRow>
+          <FormField>
+            <ButtonGroup>
+              <Button id="submit">Submit</Button>
+            </ButtonGroup>
+          </FormField>
+        </FormRow>
+      </Form>
+    )}
+  </Story>
+</Canvas>
+
+<ArgsTable story="Form with Controls" />
+
+## Accessibility
+
+The `Form` component renders a standard `<form>` element and should be used to
+wrap all form elements. A `Form` should have a `Button` component with a `type`
+of `submit` to submit the form to a server through the `Form`'s `action` prop.
+
+Resources:
+
+- [WebAIM Creating Accessible Forms](https://webaim.org/techniques/forms/)
+- [Deque The Anatomy of Accessible Forms: Best Practices](https://www.deque.com/blog/anatomy-of-accessible-forms-best-practices/)
+
+## Spacing Variants
+
+export const formRow = (gapValue) => {
+  const labelText = `Size: ${gapValue}`;
+  return (
+    <li key={gapValue}>
+      <Heading level="three">{labelText}</Heading>
+      <Form gap={gapValue} id={`form-spacing-${gapValue}`}>
+        <FormRow>
+          <FormField>
+            <Select
+              helperText="The select field helper text."
+              id={`select-spacing-${gapValue}-1`}
+              labelText="Select Field"
+              showLabel={true}
+            >
+              <option>Option 1</option>
+              <option>Option 2</option>
+              <option>Option 3</option>
+              <option>Option 4</option>
+            </Select>
+          </FormField>
+          <FormField>
+            <Select
+              helperText="The select field helper text."
+              id={`select-spacing-${gapValue}-2`}
+              labelText="Select Field"
+              showLabel={true}
+            >
+              <option>Option 1</option>
+              <option>Option 2</option>
+              <option>Option 3</option>
+              <option>Option 4</option>
+            </Select>
+          </FormField>
+          <FormField>
+            <Select
+              helperText="The select field helper text."
+              id={`select-spacing-${gapValue}-3`}
+              labelText="Select Field"
+              showLabel={true}
+            >
+              <option>Option 1</option>
+              <option>Option 2</option>
+              <option>Option 3</option>
+              <option>Option 4</option>
+            </Select>
+          </FormField>
+        </FormRow>
+      </Form>
+      <HorizontalRule />
+    </li>
+  );
+};
+export const sizes = [];
+export const gapValues = [
+  "grid.xxs",
+  "grid.xs",
+  "grid.s",
+  "grid.m",
+  "grid.l",
+  "grid.xl",
+  "grid.xxl",
+];
+for (const gap in gapValues) {
+  sizes.push(formRow(gapValues[gap]));
+}
+export const getForms = (list) => <ul style={{ listStyle: "none" }}>{list}</ul>;
+
+By default, the `Form` component will handle the NYPL spacing around form input
+elements. The default spacing value is large `grid.l`, which corresponds to the
+CSS variable `--nypl-space-l` (2rem / 32px).
+
+**IMPORTANT:** The default spacing should not be overwritten without a very
+good reason.
+
+Below are examples of the spacing values available to use in the `gap` prop of
+the `Form` component: `"grid.xxs"`, `"grid.xs"`, `"grid.s"`, `"grid.m"`,
+`"grid.l"`, `"grid.xl"`, `"grid.xxl"`.
+
+<Canvas>
+  <Story name="Spacing Variants">{getForms(sizes)}</Story>
+</Canvas>
+
+## Example Code
+
+```jsx
+<Form action="/end/point" method="get" gap="grid.l" id="example-form">
+  <FormField>
+    <TextInput
+      labelText="Username"
+      helperText="Make sure to complete this field."
+      isRequired
+    />
+  </FormField>
+  <FormField>
+    <TextInput
+      labelText="Password"
+      helperText="Make sure to complete this field."
+      isRequired
+    />
+  </FormField>
+  <FormRow>
+    <FormField>
+      <TextInput
+        labelText="Phone Field"
+        helperText="This one is up to you."
+        type="tel"
+      />
+    </FormField>
+    <FormField>
+      <TextInput
+        labelText="URL Field"
+        helperText="This one is up to you."
+        type="url"
+      />
+    </FormField>
+    <FormField>
+      <TextInput
+        labelText="Age"
+        helperText="This one is up to you."
+        type="number"
+      />
+    </FormField>
+  </FormRow>
+  <FormField>
+    <Button>Submit</Button>
+  </FormField>
+</Form>
+```

package/src/components/Form/Form.test.tsx

@@ -0,0 +1,234 @@
+import * as React from "react";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { axe } from "jest-axe";
+import renderer from "react-test-renderer";
+
+import Form, { FormRow, FormField } from "./Form";
+import TextInput from "../TextInput/TextInput";
+
+describe("Form Accessibility", () => {
+  it("passes axe accessibility test", async () => {
+    const { container } = render(<Form id="form" />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+
+  it("passes axe accessibility test for the full hierachy", async () => {
+    const { container } = render(
+      <Form id="form">
+        <FormRow>
+          <FormField>Form Field 1</FormField>
+          <FormField>Form Field 2</FormField>
+          <FormField>Form Field 3</FormField>
+        </FormRow>
+      </Form>
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("Form Snapshot", () => {
+  it("Renders the UI snapshot correctly", () => {
+    const tree = renderer
+      .create(
+        <Form id="snapshot-form">
+          <FormRow>
+            <FormField>Form Field 1</FormField>
+            <FormField>Form Field 2</FormField>
+            <FormField>Form Field 3</FormField>
+          </FormRow>
+        </Form>
+      )
+      .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <Form id="chakra" p="20px" color="ui.error.primary">
+          <FormRow>
+            <FormField>Form Field 1</FormField>
+            <FormField>Form Field 2</FormField>
+            <FormField>Form Field 3</FormField>
+          </FormRow>
+        </Form>
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(
+        <Form id="props" data-testid="props">
+          <FormRow>
+            <FormField>Form Field 1</FormField>
+            <FormField>Form Field 2</FormField>
+            <FormField>Form Field 3</FormField>
+          </FormRow>
+        </Form>
+      )
+      .toJSON();
+
+    expect(tree).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
+  });
+});
+
+describe("Form", () => {
+  it("Renders a <form> element", () => {
+    render(<Form id="form" />);
+    expect(screen.getByRole("form")).toBeInTheDocument();
+  });
+
+  it("Renders a <form> element with child FormRow element", () => {
+    render(
+      <Form id="form">
+        <FormRow />
+      </Form>
+    );
+    const form = screen.getByRole("form");
+    const formRow = form.firstChild;
+    expect(form).toBeInTheDocument();
+    expect(formRow).toBeInTheDocument();
+    expect(formRow).toHaveStyle({
+      display: "grid",
+    });
+  });
+
+  it("Renders a <form> element with child FormField element", () => {
+    render(
+      <Form id="form">
+        <FormField />
+      </Form>
+    );
+    const form = screen.getByRole("form");
+    const formField = form.firstChild;
+    expect(form).toBeInTheDocument();
+    expect(formField).toBeInTheDocument();
+    expect(formField).toHaveStyle({
+      display: "grid",
+    });
+  });
+
+  it("Renders a <form> element with FormRow, FormField and input elements properly nested", () => {
+    render(
+      <Form id="form">
+        <FormRow>
+          <FormField>
+            <TextInput id="textInput" labelText="Input Field" />
+          </FormField>
+        </FormRow>
+      </Form>
+    );
+    const form = screen.getByRole("form");
+    const formRow = form.firstChild;
+    const formField = formRow?.firstChild;
+    const textInput = screen.getByRole("textbox");
+    expect(form).toBeInTheDocument();
+    expect(formRow).toBeInTheDocument();
+    expect(formRow).toHaveStyle({
+      display: "grid",
+    });
+    expect(formField).toBeInTheDocument();
+    expect(formField).toHaveStyle({
+      display: "grid",
+    });
+    expect(textInput).toBeInTheDocument();
+  });
+
+  it("Renders a <form> element with custom `action` and `method` attributes", () => {
+    render(<Form id="form" action="/end/point" method="get" />);
+    const form = screen.getByRole("form");
+    expect(form).toBeInTheDocument();
+    expect(form).toHaveAttribute("action", "/end/point");
+    expect(form).toHaveAttribute("method", "get");
+  });
+
+  it("passes down the `Form`'s id down to its children", () => {
+    const { container } = render(
+      <Form id="formId">
+        <FormRow>
+          <FormField>
+            <TextInput id="textInput" labelText="Input Field" />
+          </FormField>
+          <FormField>
+            <TextInput id="textInput" labelText="Input Field" />
+          </FormField>
+        </FormRow>
+        <FormRow>
+          <FormField>
+            <TextInput id="textInput" labelText="Input Field" />
+          </FormField>
+          <FormField>
+            <TextInput id="textInput" labelText="Input Field" />
+          </FormField>
+        </FormRow>
+      </Form>
+    );
+
+    expect(container.querySelector("#formId")).toBeInTheDocument();
+    // The first `FormRow` adds "child0" to its id
+    expect(container.querySelector("#formId-child0")).toBeInTheDocument();
+    // The first `FormRow`'s first `FormField` adds "grandchild0" to its id
+    expect(
+      container.querySelector("#formId-child0-grandchild0")
+    ).toBeInTheDocument();
+    // The first `FormRow`'s second `FormField` adds "grandchild1" to its id
+    expect(
+      container.querySelector("#formId-child0-grandchild1")
+    ).toBeInTheDocument();
+    // The second `FormRow` adds "child1" to its id
+    expect(container.querySelector("#formId-child1")).toBeInTheDocument();
+    // The second `FormRow`'s first `FormField` adds "grandchild0" to its id
+    expect(
+      container.querySelector("#formId-child1-grandchild0")
+    ).toBeInTheDocument();
+    // The second `FormRow`'s second `FormField` adds "grandchild1" to its id
+    expect(
+      container.querySelector("#formId-child1-grandchild1")
+    ).toBeInTheDocument();
+  });
+
+  it("logs a warning if a child of `FormRow` is not a `FormField`", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(
+      <Form id="form">
+        <FormRow>
+          <div>Not a FormField</div>
+        </FormRow>
+      </Form>
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir FormRow: Children must be `FormField` components."
+    );
+  });
+
+  it("calls the onSubmit function", () => {
+    const onSubmit = jest.fn();
+    render(
+      <Form id="form" onSubmit={onSubmit}>
+        <FormRow>
+          <FormField>
+            <TextInput id="textInput" labelText="Input Field" />
+          </FormField>
+        </FormRow>
+      </Form>
+    );
+    const form = screen.getByRole("form");
+    expect(onSubmit).toHaveBeenCalledTimes(0);
+    fireEvent.submit(form);
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+  });
+
+  it("Logs a warning when there is no `id` passed", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(
+      // @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.
+      <Form>
+        <FormRow>
+          <FormField>
+            <TextInput id="textInput" labelText="Input Field" />
+          </FormField>
+        </FormRow>
+      </Form>
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir Form: This component's required `id` prop was not passed."
+    );
+  });
+});