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

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

@@ -1,3 +1,4 @@
+import { ButtonGroup, Flex, Spacer } from "@chakra-ui/react";
 import { action } from "@storybook/addon-actions";
 import {
   ArgsTable,
@@ -60,7 +61,17 @@ export const enumValues = getStorybookEnumValues(FormGaps, "FormGaps");
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.23.2`   |
-| Latest            | `0.25.10`  |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Spacing Variants](#spacing-variants)
+- [Example Code](#example-code)
+
+## Overview
 
 <Description of={Form} />
 
@@ -70,7 +81,7 @@ components should be used to build the `<form>` structure and to arrange input
 fields as needed.
 
 ```jsx
-<Form>
+<Form id="form-id">
   <FormRow>
     <FormField>{/* ... */}</FormField>
   </FormRow>
@@ -80,11 +91,13 @@ fields as needed.
 </Form>
 ```
 
-`FormField` should be used as a parent for all input components from the DS
-(`Button`, `Select`, `TextInput`, etc.).
+`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.
+`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
@@ -98,30 +111,32 @@ need to render multiple input components in a horizontal row.
     }}
   >
     {(args) => (
-      <Form {...args} gap={enumValues.getValue(args.gap)}>
+      <Form {...args} gap={enumValues.getValue(args.gap)} id="form-id">
         <FormRow>
           <FormField>
             <TextInput
-              labelText="First Name"
               helperText="Make sure to complete this field."
+              id="first-name"
               isRequired
+              labelText="First Name"
             />
           </FormField>
           <FormField>
             <TextInput
-              labelText="Last Name"
               helperText="Make sure to complete this field."
+              id="last-name"
               isRequired
+              labelText="Last Name"
             />
           </FormField>
           <FormField>
             <DatePicker
-              id="date-range"
               dateType={DatePickerTypes.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"
@@ -134,37 +149,42 @@ need to render multiple input components in a horizontal row.
         </FormRow>
         <FormField>
           <TextInput
-            labelText="Username"
             helperText="Make sure to complete this field."
+            id="username"
             isRequired
+            labelText="Username"
           />
         </FormField>
         <FormField>
           <TextInput
-            labelText="Password"
             helperText="Make sure to complete this field."
+            id="password"
             isRequired
+            labelText="Password"
           />
         </FormField>
         <FormRow>
           <FormField>
             <TextInput
-              labelText="Phone Field"
               helperText="This one is up to you."
+              id="phone"
+              labelText="Phone Field"
               type="tel"
             />
           </FormField>
           <FormField>
             <TextInput
-              labelText="URL Field"
               helperText="This one is up to you."
+              id="url"
+              labelText="URL Field"
               type="url"
             />
           </FormField>
           <FormField>
             <TextInput
-              labelText="Age"
               helperText="This one is up to you."
+              id="age"
+              labelText="Age"
               type="number"
             />
           </FormField>
@@ -172,29 +192,71 @@ need to render multiple input components in a horizontal row.
         <FormRow>
           <FormField>
             <CheckboxGroup
+              id="checkbox-group"
+              isFullWidth
               labelText="Checkbox Group"
-              name="cbg1"
-              optReqFlag={false}
+              name="checkbox-example"
             >
-              <Checkbox labelText="Checkbox 1" showLabel />
-              <Checkbox labelText="Checkbox 2" showLabel />
-              <Checkbox labelText="Checkbox 3" showLabel />
-              <Checkbox labelText="Checkbox 4" showLabel />
+              <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 labelText="Radio Group" name="rg1" optReqFlag={false}>
-              <Radio labelText="Radio 1" showLabel />
-              <Radio labelText="Radio 2" showLabel />
-              <Radio labelText="Radio 3" showLabel />
-              <Radio labelText="Radio 4" showLabel />
+            <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}
-              helperText="The select field helper text."
             >
               <option>Option 1</option>
               <option>Option 2</option>
@@ -204,9 +266,13 @@ need to render multiple input components in a horizontal row.
             </Select>
           </FormField>
         </FormRow>
-        <FormField>
-          <Button>Submit</Button>
-        </FormField>
+        <FormRow>
+          <FormField>
+            <ButtonGroup>
+              <Button id="submit">Submit</Button>
+            </ButtonGroup>
+          </FormField>
+        </FormRow>
       </Form>
     )}
   </Story>
@@ -214,6 +280,17 @@ need to render multiple input components in a horizontal row.
 
 <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 = (nameString, size) => {
@@ -221,13 +298,14 @@ export const formRow = (nameString, size) => {
   return (
     <li key={size}>
       <Heading level={HeadingLevels.Three}>{labelText}</Heading>
-      <Form gap={size}>
+      <Form gap={size} id={`form-spacing-${size}`}>
         <FormRow>
           <FormField>
             <Select
+              helperText="The select field helper text."
+              id={`select-spacing-${size}-1`}
               labelText="Select Field"
               showLabel={true}
-              helperText="The select field helper text."
             >
               <option>Option 1</option>
               <option>Option 2</option>
@@ -237,9 +315,10 @@ export const formRow = (nameString, size) => {
           </FormField>
           <FormField>
             <Select
+              helperText="The select field helper text."
+              id={`select-spacing-${size}-2`}
               labelText="Select Field"
               showLabel={true}
-              helperText="The select field helper text."
             >
               <option>Option 1</option>
               <option>Option 2</option>
@@ -249,9 +328,10 @@ export const formRow = (nameString, size) => {
           </FormField>
           <FormField>
             <Select
+              helperText="The select field helper text."
+              id={`select-spacing-${size}-3`}
               labelText="Select Field"
               showLabel={true}
-              helperText="The select field helper text."
             >
               <option>Option 1</option>
               <option>Option 2</option>
@@ -266,8 +346,8 @@ export const formRow = (nameString, size) => {
   );
 };
 export const sizes = [];
-for (const FormGaps in FormGaps) {
-  sizes.push(formRow(`FormGaps.${FormGaps}`, FormGaps[FormGaps]));
+for (const formGap in FormGaps) {
+  sizes.push(formRow(`FormGaps.${formGap}`, FormGaps[formGap]));
 }
 export const getForms = (list) => <ul style={{ listStyle: "none" }}>{list}</ul>;
 
@@ -280,22 +360,13 @@ variable `--nypl-space-l` (2rem / 32px).
 Below are the spacing variants available with the `FormGaps` enum.
 
 <Canvas>
-  <Story
-    name="Spacing Variants"
-    args={{
-      id: "spacing-form-id",
-    }}
-  >
-    {getForms(sizes)}
-  </Story>
+  <Story name="Spacing Variants">{getForms(sizes)}</Story>
 </Canvas>
 
 ## Example Code
 
-<Story name="Example Code" />
-
 ```jsx
-<Form action="/end/point" method="get" gap={FormGaps.Large}>
+<Form action="/end/point" method="get" gap={FormGaps.Large} id="example-form">
   <FormField>
     <TextInput
       labelText="Username"

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

@@ -9,13 +9,13 @@ import TextInput from "../TextInput/TextInput";
 
 describe("Form Accessibility", () => {
   it("passes axe accessibility test", async () => {
-    const { container } = render(<Form />);
+    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>
+      <Form id="form">
         <FormRow>
           <FormField>Form Field 1</FormField>
           <FormField>Form Field 2</FormField>
@@ -40,19 +40,44 @@ describe("Form Snapshot", () => {
         </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 />);
+    render(<Form id="form" />);
     expect(screen.getByRole("form")).toBeInTheDocument();
   });
 
   it("Renders a <form> element with child FormRow element", () => {
     render(
-      <Form>
+      <Form id="form">
         <FormRow />
       </Form>
     );
@@ -67,7 +92,7 @@ describe("Form", () => {
 
   it("Renders a <form> element with child FormField element", () => {
     render(
-      <Form>
+      <Form id="form">
         <FormField />
       </Form>
     );
@@ -82,10 +107,10 @@ describe("Form", () => {
 
   it("Renders a <form> element with FormRow, FormField and input elements properly nested", () => {
     render(
-      <Form>
+      <Form id="form">
         <FormRow>
           <FormField>
-            <TextInput labelText="Input Field" />
+            <TextInput id="textInput" labelText="Input Field" />
           </FormField>
         </FormRow>
       </Form>
@@ -107,7 +132,7 @@ describe("Form", () => {
   });
 
   it("Renders a <form> element with custom `action` and `method` attributes", () => {
-    render(<Form action="/end/point" method="get" />);
+    render(<Form id="form" action="/end/point" method="get" />);
     const form = screen.getByRole("form");
     expect(form).toBeInTheDocument();
     expect(form).toHaveAttribute("action", "/end/point");
@@ -119,18 +144,18 @@ describe("Form", () => {
       <Form id="formId">
         <FormRow>
           <FormField>
-            <TextInput labelText="Input Field" />
+            <TextInput id="textInput" labelText="Input Field" />
           </FormField>
           <FormField>
-            <TextInput labelText="Input Field" />
+            <TextInput id="textInput" labelText="Input Field" />
           </FormField>
         </FormRow>
         <FormRow>
           <FormField>
-            <TextInput labelText="Input Field" />
+            <TextInput id="textInput" labelText="Input Field" />
           </FormField>
           <FormField>
-            <TextInput labelText="Input Field" />
+            <TextInput id="textInput" labelText="Input Field" />
           </FormField>
         </FormRow>
       </Form>
@@ -162,24 +187,24 @@ describe("Form", () => {
   it("logs a warning if a child of `FormRow` is not a `FormField`", () => {
     const warn = jest.spyOn(console, "warn");
     render(
-      <Form>
+      <Form id="form">
         <FormRow>
           <div>Not a FormField</div>
         </FormRow>
       </Form>
     );
     expect(warn).toHaveBeenCalledWith(
-      "FormRow children must be `FormField` components."
+      "NYPL Reservoir FormRow: Children must be `FormField` components."
     );
   });
 
   it("calls the onSubmit function", () => {
     const onSubmit = jest.fn();
     render(
-      <Form onSubmit={onSubmit}>
+      <Form id="form" onSubmit={onSubmit}>
         <FormRow>
           <FormField>
-            <TextInput labelText="Input Field" />
+            <TextInput id="textInput" labelText="Input Field" />
           </FormField>
         </FormRow>
       </Form>
@@ -190,6 +215,24 @@ describe("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."
+    );
+  });
+
   // TO DO: There's somethign weird about checking for the "grid-gap" style.
   // Other styles can be validated, but "grid-gap" is being ellusive.
   // it("Renders a <form> element with spacing variant applied", () => {

package/src/components/Form/Form.tsx

@@ -1,8 +1,8 @@
+import { chakra } from "@chakra-ui/react";
 import * as React from "react";
 
 import { FormGaps } from "./FormTypes";
 import SimpleGrid from "../Grid/SimpleGrid";
-import generateUUID from "../../helpers/generateUUID";
 
 interface FormBaseProps {
   /** className to be applied to FormRow, FormField, and Form */
@@ -12,10 +12,10 @@ interface FormBaseProps {
    * should not be used``` */
   gap?: FormGaps;
   /** ID that other components can cross reference (internal use) */
-  id?: string;
+  id: string;
 }
 
-export interface FormChildProps extends FormBaseProps {}
+export interface FormChildProps extends Partial<FormBaseProps> {}
 
 export interface FormProps extends FormBaseProps {
   /** Optional form `action` attribute */
@@ -27,74 +27,98 @@ export interface FormProps extends FormBaseProps {
 }
 
 /** FormRow child-component */
-export function FormRow(props: React.PropsWithChildren<FormChildProps>) {
-  const { children, className, gap, id } = props;
-  const count = React.Children.count(children);
-  const alteredChildren = React.Children.map(
-    children,
-    (child: React.ReactElement, i) => {
-      if (!child) return null;
-      if (child.type === FormField || child.props.mdxType === "FormField") {
-        return React.cloneElement(child, { id: `${id}-grandchild${i}` });
+export const FormRow = chakra(
+  (props: React.PropsWithChildren<FormChildProps>) => {
+    const { children, className, gap, id, ...rest } = props;
+    const count = React.Children.count(children);
+    const alteredChildren = React.Children.map(
+      children,
+      (child: React.ReactElement, i) => {
+        if (!child) return null;
+        if (child.type === FormField || child.props.mdxType === "FormField") {
+          return React.cloneElement(child, { id: `${id}-grandchild${i}` });
+        }
+        console.warn(
+          "NYPL Reservoir FormRow: Children must be `FormField` components."
+        );
+        return null;
       }
-      console.warn("FormRow children must be `FormField` components.");
-      return null;
-    }
-  );
-  return (
-    <SimpleGrid columns={count} className={className} gap={gap} id={id}>
-      {alteredChildren}
-    </SimpleGrid>
-  );
-}
+    );
+    return (
+      <SimpleGrid
+        columns={count}
+        className={className}
+        gap={gap}
+        id={id}
+        {...rest}
+      >
+        {alteredChildren}
+      </SimpleGrid>
+    );
+  }
+);
 
 /** FormField child-component */
-export function FormField(props: React.PropsWithChildren<FormChildProps>) {
-  const { children, className, gap, id } = props;
-  return (
-    <SimpleGrid columns={1} className={className} gap={gap} id={id}>
-      {children}
-    </SimpleGrid>
-  );
-}
+export const FormField = chakra(
+  (props: React.PropsWithChildren<FormChildProps>) => {
+    const { children, className, gap, id, ...rest } = props;
+    return (
+      <SimpleGrid columns={1} className={className} gap={gap} id={id} {...rest}>
+        {children}
+      </SimpleGrid>
+    );
+  }
+);
 
 /** Main Form component */
-export default function Form(props: React.PropsWithChildren<FormProps>) {
-  const {
-    action,
-    children,
-    className,
-    gap = FormGaps.Large,
-    id = generateUUID(),
-    method,
-    onSubmit,
-  } = props;
+export const Form = chakra(
+  (props: React.PropsWithChildren<FormProps>) => {
+    const {
+      action,
+      children,
+      className,
+      gap = FormGaps.Large,
+      id,
+      method,
+      onSubmit,
+      ...rest
+    } = props;
 
-  let attributes = {};
-  action && (attributes["action"] = action);
+    if (!id) {
+      console.warn(
+        "NYPL Reservoir Form: This component's required `id` prop was not passed."
+      );
+    }
+    let attributes = {};
+    action && (attributes["action"] = action);
 
-  method &&
-    (method === "get" || method === "post") &&
-    (attributes["method"] = method);
+    method &&
+      (method === "get" || method === "post") &&
+      (attributes["method"] = method);
 
-  const alteredChildren = React.Children.map(
-    children,
-    (child: React.ReactElement, i) => {
-      return React.cloneElement(child, { gap, id: `${id}-child${i}` });
-    }
-  );
+    const alteredChildren = React.Children.map(
+      children,
+      (child: React.ReactElement, i) => {
+        return React.cloneElement(child, { gap, id: `${id}-child${i}` });
+      }
+    );
 
-  return (
-    <form
-      aria-label="form"
-      className={className}
-      id={id}
-      onSubmit={onSubmit}
-      {...attributes}
-    >
-      <SimpleGrid columns={1} gap={gap} id={`${id}-parent`}>
-        {alteredChildren}
-      </SimpleGrid>
-    </form>
-  );
-}
+    return (
+      <form
+        aria-label="form"
+        className={className}
+        id={id}
+        onSubmit={onSubmit}
+        {...attributes}
+        {...rest}
+      >
+        <SimpleGrid columns={1} gap={gap} id={`${id}-parent`}>
+          {alteredChildren}
+        </SimpleGrid>
+      </form>
+    );
+  },
+  { shouldForwardProp: () => true }
+);
+
+export default Form;