@nypl/design-system-react-components 0.23.4 → 0.25.1

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

@@ -10,15 +10,22 @@ import { withDesign } from "storybook-addon-designs";
 import { getCategory } from "../../utils/componentCategories";
 
 import Form, { FormRow, FormField } from "./Form";
+import { FormSpacing } from "./FormTypes";
 import TextInput from "../TextInput/TextInput";
 import Radio from "../Radio/Radio";
+import RadioGroup from "../RadioGroup/RadioGroup";
 import Checkbox from "../Checkbox/Checkbox";
+import CheckboxGroup from "../CheckboxGroup/CheckboxGroup";
 import Label from "../Label/Label";
 import Button from "../Button/Button";
 import Select from "../Select/Select";
-import HelperErrorText from "../HelperErrorText/HelperErrorText";
+import Heading from "../Heading/Heading";
+import { HeadingLevels } from "../Heading/HeadingTypes";
+import HorizontalRule from "../HorizontalRule/HorizontalRule";
 import { action } from "@storybook/addon-actions";
 
+import SimpleGrid from "../Grid/SimpleGrid";
+
 <Meta
   title={getCategory("Form")}
   component={Form}
@@ -35,6 +42,11 @@ import { action } from "@storybook/addon-actions";
 
 # Form
 
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.23.2`   |
+| Latest            | `0.25.1`   |
+
 <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>` struture and to arrange input fields as needed.
@@ -62,18 +74,34 @@ The `Form` component renders a standard `<form>` element and should be used to h
   >
     {(args) => (
       <Form {...args}>
+        <FormRow>
+          <FormField>
+            <TextInput
+              labelText="First Name"
+              helperText="Make sure to complete this field."
+              isRequired
+            />
+          </FormField>
+          <FormField>
+            <TextInput
+              labelText="Last Name"
+              helperText="Make sure to complete this field."
+              isRequired
+            />
+          </FormField>
+        </FormRow>
         <FormField>
           <TextInput
             labelText="Username"
             helperText="Make sure to complete this field."
-            required
+            isRequired
           />
         </FormField>
         <FormField>
           <TextInput
             labelText="Password"
             helperText="Make sure to complete this field."
-            required
+            isRequired
           />
         </FormField>
         <FormRow>
@@ -101,24 +129,24 @@ The `Form` component renders a standard `<form>` element and should be used to h
         </FormRow>
         <FormRow>
           <FormField>
-            <Label>Checkbox Group</Label>
-            <Checkbox labelText="Checkbox 1" showLabel />
-            <br />
-            <Checkbox labelText="Checkbox 1" showLabel />
-            <br />
-            <Checkbox labelText="Checkbox 1" showLabel />
-            <br />
-            <Checkbox labelText="Checkbox 1" showLabel />
+            <CheckboxGroup
+              labelText="Checkbox Group"
+              name="cbg1"
+              optReqFlag={false}
+            >
+              <Checkbox labelText="Checkbox 1" showLabel />
+              <Checkbox labelText="Checkbox 2" showLabel />
+              <Checkbox labelText="Checkbox 3" showLabel />
+              <Checkbox labelText="Checkbox 4" showLabel />
+            </CheckboxGroup>
           </FormField>
           <FormField>
-            <Label>Radio Group</Label>
-            <Radio labelText="Radio 1" showLabel />
-            <br />
-            <Radio labelText="Radio 2" showLabel />
-            <br />
-            <Radio labelText="Radio 3" showLabel />
-            <br />
-            <Radio labelText="Radio 4" showLabel />
+            <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>
           </FormField>
           <FormField>
             <Select
@@ -129,6 +157,8 @@ The `Form` component renders a standard `<form>` element and should be used to h
               <option>Option 1</option>
               <option>Option 2</option>
               <option>Option 3</option>
+              <option>Option 4</option>
+              <option>Option 5</option>
             </Select>
           </FormField>
         </FormRow>
@@ -142,25 +172,98 @@ The `Form` component renders a standard `<form>` element and should be used to h
 
 <ArgsTable story="Form" />
 
-### Example Code
+## Spacing Variants
 
-```
-<Form
-  action="/end/point"
-  method="get"
->
+export const formRow = (size) => {
+  const labelText = `Size: ${size}`;
+  return (
+    <li>
+      <Heading level={HeadingLevels.Three}>{labelText}</Heading>
+      <Form spacing={size}>
+        <FormRow>
+          <FormField>
+            <Select
+              labelText="Select Field"
+              showLabel={true}
+              helperText="The select field helper text."
+            >
+              <option>Option 1</option>
+              <option>Option 2</option>
+              <option>Option 3</option>
+              <option>Option 4</option>
+            </Select>
+          </FormField>
+          <FormField>
+            <Select
+              labelText="Select Field"
+              showLabel={true}
+              helperText="The select field helper text."
+            >
+              <option>Option 1</option>
+              <option>Option 2</option>
+              <option>Option 3</option>
+              <option>Option 4</option>
+            </Select>
+          </FormField>
+          <FormField>
+            <Select
+              labelText="Select Field"
+              showLabel={true}
+              helperText="The select field helper text."
+            >
+              <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 = [];
+for (const formSpacing in FormSpacing) {
+  sizes.push(formRow(FormSpacing[formSpacing]));
+}
+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`, which corresponds to the CSS variable `--space-l` (2rem / 32px).
+
+**IMPORTANT:** The default spacing should not be overwritten without a very good reason.
+
+Below are the spacing variants available with the `FormSpacing` enum.
+
+<Preview>
+  <Story
+    name="Spacing Variants"
+    args={{
+      id: "spacing-form-id",
+    }}
+  >
+    {getForms(sizes)}
+  </Story>
+</Preview>
+
+## Example Code
+
+<Story name="Example Code" />
+
+```jsx
+<Form action="/end/point" method="get">
   <FormField>
     <TextInput
       labelText="Username"
       helperText="Make sure to complete this field."
-      required
+      isRequired
     />
   </FormField>
   <FormField>
     <TextInput
       labelText="Password"
       helperText="Make sure to complete this field."
-      required
+      isRequired
     />
   </FormField>
   <FormRow>

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

@@ -1,8 +1,10 @@
 import * as React from "react";
-import { render } from "@testing-library/react";
+import { render, screen } from "@testing-library/react";
 import { axe } from "jest-axe";
+import renderer from "react-test-renderer";
 
 import Form, { FormRow, FormField } from "./Form";
+// import { FormSpacing } from "./FormTypes";
 import TextInput from "../TextInput/TextInput";
 
 describe("Form Accessibility", () => {
@@ -12,41 +14,61 @@ describe("Form Accessibility", () => {
   });
 });
 
+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();
+    expect(tree).toMatchSnapshot();
+  });
+});
+
 describe("Form", () => {
-  let container;
   it("Renders a <form> element", () => {
-    const utils = render(<Form />);
-    container = utils.container;
-
-    expect(container.querySelector(".form")).toBeInTheDocument();
+    render(<Form />);
+    expect(screen.getByRole("form")).toBeInTheDocument();
   });
 
-  it("Renders a <form> element with child .form-row element", () => {
-    const utils = render(
+  it("Renders a <form> element with child FormRow element", () => {
+    render(
       <Form>
         <FormRow />
       </Form>
     );
-    container = utils.container;
-
-    expect(container.querySelector(".form")).toBeInTheDocument();
-    expect(container.querySelector(".form-row")).toBeInTheDocument();
+    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 .form-field element", () => {
-    const utils = render(
+  it("Renders a <form> element with child FormField element", () => {
+    render(
       <Form>
         <FormField />
       </Form>
     );
-    container = utils.container;
-
-    expect(container.querySelector(".form")).toBeInTheDocument();
-    expect(container.querySelector(".form-field")).toBeInTheDocument();
+    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 .form-row, .form-field and input elements properly nested", () => {
-    const utils = render(
+  it("Renders a <form> element with FormRow, FormField and input elements properly nested", () => {
+    render(
       <Form>
         <FormRow>
           <FormField>
@@ -55,23 +77,43 @@ describe("Form", () => {
         </FormRow>
       </Form>
     );
-    container = utils.container;
-
-    expect(container.querySelector(".form")).toBeInTheDocument();
-    expect(container.querySelector(".form-row")).toBeInTheDocument();
-    expect(container.querySelector(".form-field")).toBeInTheDocument();
-    expect(container.querySelector(".textinput")).toBeInTheDocument();
+    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 .form-row and .form-field elements properly nested", () => {
-    const utils = render(<Form action="/end/point" method="get" />);
-    container = utils.container;
-
-    expect(container.querySelector(".form")).toBeInTheDocument();
-    expect(container.querySelector(".form")).toHaveAttribute(
-      "action",
-      "/end/point"
-    );
-    expect(container.querySelector(".form")).toHaveAttribute("method", "get");
+  it("Renders a <form> element with custom `action` and `method` attributes", () => {
+    render(<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");
   });
+
+  // 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", () => {
+  //   render(
+  //     <Form spacing={FormSpacing.ExtraSmall}>
+  //       <FormRow />
+  //     </Form>
+  //   );
+  //   const form = screen.getByRole("form");
+  //   const formRow = form.firstChild;
+  //   expect(form).toBeInTheDocument();
+  //   expect(formRow).toHaveStyle({
+  //     "grid-gap": "var(--chakra-space-xs)",
+  //   });
+  // });
 });

package/src/components/Form/Form.tsx

@@ -1,60 +1,94 @@
 import * as React from "react";
-import bem from "../../utils/bem";
+import { FormSpacing } from "./FormTypes";
+import SimpleGrid from "../Grid/SimpleGrid";
+import { Box } from "@chakra-ui/react";
 import generateUUID from "../../helpers/generateUUID";
 
+export interface FormChildProps {
+  /** className to be applied to FormRow */
+  className?: string;
+  /** Spacing size (internal use) */
+  gap?: FormSpacing;
+  /** ID that other components can cross reference (internal use) */
+  id?: string;
+}
+
 export interface FormProps {
   /** Optional form `action` attribute */
   action?: string;
-  /** Optional additional attributes passed to the `<form>` element */
-  attributes?: { [key: string]: any };
   /** Optional className you can add in addition to `form` */
   className?: string;
   /** Optional ID that other components can cross reference */
   id?: string;
   /** Optional form `method` attribute */
   method?: "get" | "post";
-  /** Optional modifiers array for use with BEM. See how to work with modifiers and BEM here: http://getbem.com/introduction/ */
-  modifiers?: string[];
+  /** Optional spacing size; if omitted, the default `large` (2rem / 32px) spacing will be used; ```IMPORTANT: for general form layout, this prop should not be used``` */
+  spacing?: FormSpacing;
 }
 
-// FormRow child-component
-export function FormRow(props) {
-  const { children, className } = props;
-  return <div className={bem("form-row", [], "", [className])}>{children}</div>;
+/** 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) => {
+      return React.cloneElement(child, { id: `${id}-grandchild${i}` });
+    }
+  );
+  return (
+    <SimpleGrid columns={count} className={className} gap={gap} id={id}>
+      {alteredChildren}
+    </SimpleGrid>
+  );
 }
 
-// FormField child-component
-export function FormField(props) {
-  const { children, className } = props;
+/** FormField child-component */
+export function FormField(props: React.PropsWithChildren<FormChildProps>) {
+  const { children, className, gap, id } = props;
   return (
-    <div className={bem("form-field", [], "", [className])}>{children}</div>
+    <SimpleGrid columns={1} className={className} gap={gap} id={id}>
+      {children}
+    </SimpleGrid>
   );
 }
 
+/** main Form component */
 export default function Form(props: React.ComponentProps<"form"> & FormProps) {
   const {
     action,
-    attributes = {},
     children,
     className,
     id = generateUUID(),
     method,
-    modifiers = [],
+    spacing,
   } = props;
 
+  let attributes = {};
   action && (attributes["action"] = action);
 
   method &&
     (method === "get" || method === "post") &&
     (attributes["method"] = method);
 
+  const alteredChildren = React.Children.map(
+    children,
+    (child: React.ReactElement, i) => {
+      return React.cloneElement(child, { gap: spacing, id: `${id}-child${i}` });
+    }
+  );
+
   return (
-    <form
-      className={bem("form", modifiers, "", [className])}
+    <Box
+      as="form"
+      aria-label="form"
       id={id}
       {...attributes}
+      className={className}
     >
-      {children}
-    </form>
+      <SimpleGrid columns={1} gap={spacing} id={id + "-parent"}>
+        {alteredChildren}
+      </SimpleGrid>
+    </Box>
   );
 }

package/src/components/Form/FormTypes.tsx

@@ -0,0 +1,3 @@
+import { GridGaps as FormSpacing } from "../Grid/GridTypes";
+
+export { FormSpacing };

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

@@ -0,0 +1,38 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Form Snapshot Renders the UI snapshot correctly 1`] = `
+<form
+  aria-label="form"
+  className="css-0"
+  id="snapshot-form"
+>
+  <div
+    className="css-aq1pyb"
+    id="snapshot-form-parent"
+  >
+    <div
+      className="css-1ao258g"
+      id="snapshot-form-child0"
+    >
+      <div
+        className="css-aq1pyb"
+        id="snapshot-form-child0-grandchild0"
+      >
+        Form Field 1
+      </div>
+      <div
+        className="css-aq1pyb"
+        id="snapshot-form-child0-grandchild1"
+      >
+        Form Field 2
+      </div>
+      <div
+        className="css-aq1pyb"
+        id="snapshot-form-child0-grandchild2"
+      >
+        Form Field 3
+      </div>
+    </div>
+  </div>
+</form>
+`;

package/src/components/Grid/GridTypes.tsx

@@ -0,0 +1,9 @@
+export enum GridGaps {
+  ExtraExtraSmall = "xxs",
+  ExtraSmall = "xs",
+  Small = "s",
+  Medium = "m",
+  Large = "l",
+  ExtraLarge = "xl",
+  ExtraExtraLarge = "xxl",
+}