@nypl/design-system-react-components 0.25.0 → 0.25.4

package/src/components/CheckboxGroup/CheckboxGroup.stories.mdx

@@ -0,0 +1,329 @@
+import {
+  Meta,
+  Story,
+  Canvas,
+  ArgsTable,
+  Description,
+} from "@storybook/addon-docs/blocks";
+import { withDesign } from "storybook-addon-designs";
+
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+import CheckboxGroup from "./CheckboxGroup";
+import { CheckboxGroupLayoutTypes } from "./CheckboxGroupLayoutTypes";
+import Checkbox from "../Checkbox/Checkbox";
+
+<Meta
+  title={getCategory("CheckboxGroup")}
+  component={CheckboxGroup}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url:
+        "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=11895%3A658",
+    },
+    jest: ["CheckboxGroup.test.tsx"],
+  }}
+  argTypes={{
+    children: { table: { disable: true } },
+    defaultValue: { table: { disable: true } },
+    id: { table: { disable: true } },
+    name: { table: { disable: true } },
+    onChange: { table: { disable: true } },
+  }}
+/>
+
+# CheckboxGroup
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.25.1`   |
+| Latest            | `0.25.3`   |
+
+<Description of={CheckboxGroup} />
+
+<Canvas withToolbar>
+  <Story
+    name="CheckboxGroup"
+    args={{
+      defaultValue: ["4"],
+      helperText: "This is the helper text for the full group.",
+      invalidText: "This is the error text :(",
+      isDisabled: false,
+      isInvalid: false,
+      isRequired: false,
+      labelText: "Standard Checkbox Group",
+      layout: CheckboxGroupLayoutTypes.Column,
+      name: "checkbox-story",
+      optReqFlag: true,
+      showHelperInvalidText: true,
+      showLabel: true,
+    }}
+  >
+    {(args) => (
+      <CheckboxGroup {...args}>
+        <Checkbox value="2" labelText="Checkbox 2" />
+        <Checkbox value="3" labelText="Checkbox 3" />
+        <Checkbox value="4" labelText="Checkbox 4" />
+        <Checkbox value="5" labelText="Checkbox 5" />
+      </CheckboxGroup>
+    )}
+  </Story>
+</Canvas>
+
+<ArgsTable story="CheckboxGroup" />
+
+## Layout Patterns
+
+Use the `layout` prop to set the `Checkbox` buttons to display in a column or in
+a row.
+
+<Canvas>
+  <DSProvider>
+    <CheckboxGroup
+      labelText="Column (default)"
+      name="column-example"
+      optReqFlag={false}
+    >
+      <Checkbox value="2" labelText="Checkbox 2" />
+      <Checkbox value="3" labelText="Checkbox 3" />
+      <Checkbox value="4" labelText="Checkbox 4" />
+      <Checkbox value="5" labelText="Checkbox 5" />
+    </CheckboxGroup>
+    <br />
+    <CheckboxGroup
+      labelText="Row"
+      name="row-example"
+      layout={CheckboxGroupLayoutTypes.Row}
+      optReqFlag={false}
+    >
+      <Checkbox value="2" labelText="Checkbox 2" />
+      <Checkbox value="3" labelText="Checkbox 3" />
+      <Checkbox value="4" labelText="Checkbox 4" />
+      <Checkbox value="5" labelText="Checkbox 5" />
+    </CheckboxGroup>
+  </DSProvider>
+</Canvas>
+
+## Errored
+
+<Canvas>
+  <DSProvider>
+    <CheckboxGroup
+      labelText="Errored Checkbox Group"
+      name="errored-example"
+      optReqFlag={false}
+      invalidText="Error message for the full group."
+      isInvalid
+    >
+      <Checkbox value="2" labelText="Checkbox 2" />
+      <Checkbox value="3" labelText="Checkbox 3" />
+      <Checkbox value="4" labelText="Checkbox 4" />
+      <Checkbox value="5" labelText="Checkbox 5" />
+    </CheckboxGroup>
+  </DSProvider>
+</Canvas>
+
+## Disabled
+
+<Canvas>
+  <DSProvider>
+    <CheckboxGroup
+      labelText="Disabled Checkbox Group"
+      name="disabled-example"
+      optReqFlag={false}
+      helperText="The reason for being disabled."
+      isDisabled
+    >
+      <Checkbox value="2" labelText="Checkbox 2" />
+      <Checkbox value="3" labelText="Checkbox 3" />
+      <Checkbox value="4" labelText="Checkbox 4" />
+      <Checkbox value="5" labelText="Checkbox 5" />
+    </CheckboxGroup>
+  </DSProvider>
+</Canvas>
+
+## Indeterminate Example
+
+The "indeterminate" state can be used when a group of checkboxes are not all
+checked or unchecked. In the following example, if only one child checkebox is
+checked, the parent checkbox will be in the "indeterminate" state. Once both
+children are checked, the parent will be in the "checked" state.
+
+The following working example can be used in your application to keep track of
+the checked and indeterminate states - taken and modified from Chakra's
+[Checkbox](https://chakra-ui.com/docs/form/checkbox#indeterminate) documentation.
+Note that this example is specifically using NYPL DS `Checkbox` and
+`CheckboxGroup` components.
+
+```tsx
+export function IndeterminateExample() {
+  const [checkedItems, setCheckedItems] = React.useState([false, false]);
+  const allChecked = checkedItems.every(Boolean);
+  const isIndeterminate = checkedItems.some(Boolean) && !allChecked;
+  return (
+    <CheckboxGroup
+      labelText="Indeterminate Example"
+      name="indeterminate-example"
+    >
+      <Checkbox
+        isChecked={allChecked}
+        isIndeterminate={isIndeterminate}
+        onChange={(e) => setCheckedItems([e.target.checked, e.target.checked])}
+        labelText="Parent Checkbox"
+      />
+      <Checkbox
+        isChecked={checkedItems[0]}
+        onChange={(e) => setCheckedItems([e.target.checked, checkedItems[1]])}
+        labelText="Child Checkbox 1"
+      />
+      <Checkbox
+        isChecked={checkedItems[1]}
+        onChange={(e) => setCheckedItems([checkedItems[0], e.target.checked])}
+        labelText="Child Checkbox 2"
+      />
+    </CheckboxGroup>
+  );
+}
+```
+
+export function IndeterminateExample() {
+  const [checkedItems, setCheckedItems] = React.useState([false, false]);
+  const allChecked = checkedItems.every(Boolean);
+  const isIndeterminate = checkedItems.some(Boolean) && !allChecked;
+  return (
+    <CheckboxGroup
+      labelText="Indeterminate Example"
+      name="indeterminate-example"
+    >
+      <Checkbox
+        isChecked={allChecked}
+        isIndeterminate={isIndeterminate}
+        onChange={(e) => setCheckedItems([e.target.checked, e.target.checked])}
+        labelText="Parent Checkbox"
+      />
+      <Checkbox
+        isChecked={checkedItems[0]}
+        onChange={(e) => setCheckedItems([e.target.checked, checkedItems[1]])}
+        labelText="Child Checkbox 1"
+      />
+      <Checkbox
+        isChecked={checkedItems[1]}
+        onChange={(e) => setCheckedItems([checkedItems[0], e.target.checked])}
+        labelText="Child Checkbox 2"
+      />
+    </CheckboxGroup>
+  );
+}
+
+<Canvas>
+  <DSProvider>
+    <IndeterminateExample />
+  </DSProvider>
+</Canvas>
+
+## Getting Checkbox Data Values
+
+### Controlled Component using `name`, `defaultValue`, and `onChange` props
+
+If your application uses controlled React components and the DS CheckboxGroup
+must be controlled, you can extract the data through the `name`, `defaultValue`,
+and `onChange` props. The `onChange` function will be called every time a new
+`Checkbox` value is checked or unchecked.
+
+```jsx
+const onChange = (data: string[]) => {
+  // This will return the values selected as an array of strings.
+  // Ex: ["2", "4"]
+  console.log(data);
+};
+// ...
+
+// Example of the DS CheckboxGroup instance with the function above:
+<CheckboxGroup
+  id="controlled-example"
+  labelText="Checkbox Group"
+  name="CheckboxExample"
+  defaultValue={["2"]}
+  onChange={onChange}
+>
+  <Checkbox value="2" labelText="Checkbox 2" />
+  <Checkbox value="3" labelText="Checkbox 3" />
+  <Checkbox value="4" labelText="Checkbox 4" />
+</CheckboxGroup>;
+```
+
+### Uncontrolled Component using `ref`s
+
+If your application uses uncontrolled components, you can pass React `ref` props
+to the DS CheckboxGroup component to get the selected value from the DOM.
+
+The following example is using the `register` React `ref` from the
+`react-hook-form` package.
+
+```jsx
+import { useFormContext, Controller } from "react-hook-form";
+// ...
+const { register, handleSubmit, control } = useFormContext();
+// ...
+const submitForm = (formData) => {
+  // This will return an object with all the DOM element values that were
+  // registered with a `name` attribute.
+  // {
+  //   checkboxExample: ["3"]
+  // }
+  console.log(formData);
+  // ...
+};
+
+<form
+  onSubmit={handleSubmit(submitForm)}
+  method="post"
+  action="/some/api/endpoint"
+>
+  <Controller
+    as={
+      <CheckboxGroup
+        id="uncontrolled-example"
+        labelText="Checkbox Group"
+        name="checkboxExample"
+        defaultValue={["3"]}
+        ref={register()}
+      >
+        <Checkbox value="2" labelText="Checkbox 2" />
+        <Checkbox value="3" labelText="Checkbox 3" />
+        <Checkbox value="4" labelText="Checkbox 4" />
+      </CheckboxGroup>
+    }
+    name="checkboxExample"
+    control={control}
+  />
+</form>;
+```
+
+The above is specific to `react-hook-form` but a similar pattern can be used
+with normal React `ref` values.
+
+```jsx
+const CheckboxGroupRef = React.createRef<HTMLInputElement>();
+// ...
+<CheckboxGroup
+  id="uncontrolled-example"
+  labelText="Checkbox Group"
+  name="checkboxExample"
+  defaultValue={["3"]}
+  ref={CheckboxGroupRef}
+>
+  <Checkbox value="2" labelText="Checkbox 2" />
+  <Checkbox value="3" labelText="Checkbox 3" />
+  <Checkbox value="4" labelText="Checkbox 4" />
+</CheckboxGroup>
+
+// ...
+// Get the value through:
+const onSubmit = () => {
+  // ...
+  const CheckboxGroupValue = CheckboxGroupRef.current.value;
+};
+```

package/src/components/CheckboxGroup/CheckboxGroup.test.tsx

@@ -0,0 +1,372 @@
+import * as React from "react";
+import { render, screen } from "@testing-library/react";
+import { axe } from "jest-axe";
+import renderer from "react-test-renderer";
+
+import * as generateUUID from "../../helpers/generateUUID";
+import CheckboxGroup from "./CheckboxGroup";
+import Checkbox from "../Checkbox/Checkbox";
+import { CheckboxGroupLayoutTypes } from "./CheckboxGroupLayoutTypes";
+import userEvent from "@testing-library/user-event";
+
+describe("Checkbox Accessibility", () => {
+  it("passes axe accessibility", async () => {
+    const { container } = render(
+      <CheckboxGroup labelText="CheckboxGroup example" name="a11y-test">
+        <Checkbox value="2" labelText="Checkbox 2" />
+        <Checkbox value="3" labelText="Checkbox 3" />
+        <Checkbox value="4" labelText="Checkbox 4" />
+        <Checkbox value="5" labelText="Checkbox 5" />
+      </CheckboxGroup>
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("Checkbox", () => {
+  it("renders with Checkbox inputs and a label", () => {
+    render(
+      <CheckboxGroup labelText="Test Label" name="test1">
+        <Checkbox value="2" labelText="Checkbox 2" />
+        <Checkbox value="3" labelText="Checkbox 3" />
+        <Checkbox value="4" labelText="Checkbox 4" />
+      </CheckboxGroup>
+    );
+    expect(screen.getByText(/Test Label/i)).toBeInTheDocument();
+    expect(screen.getAllByRole("checkbox")).toHaveLength(3);
+    expect(screen.getByLabelText("Checkbox 2")).toBeInTheDocument();
+    expect(screen.getByLabelText("Checkbox 3")).toBeInTheDocument();
+    expect(screen.getByLabelText("Checkbox 4")).toBeInTheDocument();
+  });
+
+  it("renders with appropriate 'aria-label' attribute and value when 'showLabel' prop is set to false", () => {
+    const { rerender } = render(
+      <CheckboxGroup labelText="Test Label" name="test2">
+        <Checkbox value="2" labelText="Checkbox 2" />
+        <Checkbox value="3" labelText="Checkbox 3" />
+        <Checkbox value="4" labelText="Checkbox 4" />
+      </CheckboxGroup>
+    );
+    expect(screen.getByTestId("checkbox-group")).not.toHaveAttribute(
+      "aria-label",
+      "Test Label"
+    );
+
+    rerender(
+      <CheckboxGroup labelText="Test Label" name="test2" showLabel={false}>
+        <Checkbox value="2" labelText="Checkbox 2" />
+        <Checkbox value="3" labelText="Checkbox 3" />
+        <Checkbox value="4" labelText="Checkbox 4" />
+      </CheckboxGroup>
+    );
+    expect(screen.getByTestId("checkbox-group")).toHaveAttribute(
+      "aria-label",
+      "Test Label"
+    );
+  });
+
+  it("renders visible helper or error text", () => {
+    const { rerender } = render(
+      <CheckboxGroup
+        labelText="Test Label"
+        name="test3"
+        helperText="This is the helper text for the full group."
+        invalidText="This is the error text :("
+      >
+        <Checkbox value="2" labelText="Checkbox 2" />
+        <Checkbox value="3" labelText="Checkbox 3" />
+        <Checkbox value="4" labelText="Checkbox 4" />
+      </CheckboxGroup>
+    );
+    expect(
+      screen.getByText("This is the helper text for the full group.")
+    ).toBeVisible();
+    expect(
+      screen.queryByText("This is the error text :(")
+    ).not.toBeInTheDocument();
+
+    rerender(
+      <CheckboxGroup
+        labelText="Test Label"
+        name="test3"
+        helperText="This is the helper text for the full group."
+        invalidText="This is the error text :("
+        isInvalid
+      >
+        <Checkbox value="2" labelText="Checkbox 2" />
+        <Checkbox value="3" labelText="Checkbox 3" />
+        <Checkbox value="4" labelText="Checkbox 4" />
+      </CheckboxGroup>
+    );
+    expect(screen.getByText("This is the error text :(")).toBeVisible();
+    expect(
+      screen.queryByText("This is the helper text for the full group.")
+    ).not.toBeInTheDocument();
+  });
+
+  it("sets the CheckboxGroup's ID", () => {
+    render(
+      <CheckboxGroup labelText="Test Label" name="test5" id="some-id">
+        <Checkbox value="2" labelText="Checkbox 2" />
+      </CheckboxGroup>
+    );
+
+    // The "group" role here is for the `fieldset` element.
+    expect(screen.getByRole("group")).toHaveAttribute(
+      "id",
+      "some-id-checkbox-group"
+    );
+  });
+
+  it("sets the next value through the onChange function", () => {
+    let newValue = [];
+    const onChange = (value) => {
+      newValue = value;
+    };
+    render(
+      <CheckboxGroup
+        labelText="Test Label"
+        name="getValue"
+        defaultValue={["4"]}
+        onChange={onChange}
+      >
+        <Checkbox value="2" labelText="Checkbox 2" />
+        <Checkbox value="3" labelText="Checkbox 3" />
+        <Checkbox value="4" labelText="Checkbox 4" />
+      </CheckboxGroup>
+    );
+
+    expect(newValue).toEqual([]);
+
+    userEvent.click(screen.getByText("Checkbox 3"));
+    // "4" was the initial selected value
+    expect(newValue).toEqual(["4", "3"]);
+    userEvent.click(screen.getByText("Checkbox 2"));
+    expect(newValue).toEqual(["4", "3", "2"]);
+    userEvent.click(screen.getByText("Checkbox 3"));
+    expect(newValue).toEqual(["4", "2"]);
+  });
+
+  it("calls the UUID generation function if no id prop value is passed", () => {
+    const generateUUIDSpy = jest.spyOn(generateUUID, "default");
+    expect(generateUUIDSpy).toHaveBeenCalledTimes(0);
+    render(
+      <CheckboxGroup labelText="Test Label" name="test6">
+        <Checkbox value="2" labelText="Checkbox 2" />
+      </CheckboxGroup>
+    );
+    expect(generateUUIDSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("sets the 'disabled' attribute for all its Checkbox children", () => {
+    render(
+      <CheckboxGroup labelText="Test Label" name="test7" isDisabled>
+        <Checkbox value="2" labelText="Checkbox 2" />
+        <Checkbox value="3" labelText="Checkbox 3" />
+        <Checkbox value="4" labelText="Checkbox 4" />
+      </CheckboxGroup>
+    );
+    const Checkboxes = screen.getAllByRole("checkbox");
+
+    expect(Checkboxes).toHaveLength(3);
+    expect(Checkboxes[0]).toHaveAttribute("disabled");
+    expect(Checkboxes[1]).toHaveAttribute("disabled");
+    expect(Checkboxes[2]).toHaveAttribute("disabled");
+  });
+
+  it("sets the 'required' attribute for all its Checkbox children", () => {
+    render(
+      <CheckboxGroup labelText="Test Label" name="test8" isRequired>
+        <Checkbox value="2" labelText="Checkbox 2" />
+        <Checkbox value="3" labelText="Checkbox 3" />
+        <Checkbox value="4" labelText="Checkbox 4" />
+      </CheckboxGroup>
+    );
+    const Checkboxes = screen.getAllByRole("checkbox");
+
+    expect(Checkboxes).toHaveLength(3);
+    expect(Checkboxes[0]).toHaveAttribute("required");
+    expect(Checkboxes[1]).toHaveAttribute("required");
+    expect(Checkboxes[2]).toHaveAttribute("required");
+  });
+
+  it("sets the error state for all its Checkbox children", () => {
+    render(
+      <CheckboxGroup
+        labelText="Test Label"
+        name="test9"
+        isInvalid
+        invalidText="There's an error!"
+      >
+        <Checkbox value="2" labelText="Checkbox 2" />
+        <Checkbox value="3" labelText="Checkbox 3" />
+        <Checkbox value="4" labelText="Checkbox 4" />
+      </CheckboxGroup>
+    );
+    const Checkboxes = screen.getAllByRole("checkbox");
+
+    expect(Checkboxes).toHaveLength(3);
+    expect(Checkboxes[0]).toHaveAttribute("aria-invalid");
+    expect(Checkboxes[1]).toHaveAttribute("aria-invalid");
+    expect(Checkboxes[2]).toHaveAttribute("aria-invalid");
+  });
+
+  it("does not render the invalid text when 'isInvalid' is true but 'showHelperInvalidText' is false", () => {
+    render(
+      <CheckboxGroup
+        labelText="Test Label"
+        name="test9"
+        isInvalid
+        invalidText="There's an error!"
+        showHelperInvalidText={false}
+      >
+        <Checkbox value="2" labelText="Checkbox 2" />
+        <Checkbox value="3" labelText="Checkbox 3" />
+        <Checkbox value="4" labelText="Checkbox 4" />
+      </CheckboxGroup>
+    );
+    const Checkboxes = screen.getAllByRole("checkbox");
+
+    expect(Checkboxes).toHaveLength(3);
+    expect(Checkboxes[0]).toHaveAttribute("aria-invalid");
+    expect(Checkboxes[1]).toHaveAttribute("aria-invalid");
+    expect(Checkboxes[2]).toHaveAttribute("aria-invalid");
+  });
+
+  it("renders the UI snapshot correctly", () => {
+    const column = renderer
+      .create(
+        <CheckboxGroup labelText="column" name="column" id="column">
+          <Checkbox value="2" labelText="Checkbox 2" />
+          <Checkbox value="3" labelText="Checkbox 3" />
+        </CheckboxGroup>
+      )
+      .toJSON();
+    const row = renderer
+      .create(
+        <CheckboxGroup
+          labelText="row"
+          name="row"
+          id="row"
+          layout={CheckboxGroupLayoutTypes.Row}
+        >
+          <Checkbox value="2" labelText="Checkbox 2" />
+          <Checkbox value="3" labelText="Checkbox 3" />
+        </CheckboxGroup>
+      )
+      .toJSON();
+    const noLabel = renderer
+      .create(
+        <CheckboxGroup
+          labelText="no label"
+          name="noLabel"
+          id="noLabel"
+          showLabel={false}
+        >
+          <Checkbox value="2" labelText="Checkbox 2" />
+          <Checkbox value="3" labelText="Checkbox 3" />
+        </CheckboxGroup>
+      )
+      .toJSON();
+    const helperText = renderer
+      .create(
+        <CheckboxGroup
+          labelText="helperText"
+          name="helperText"
+          id="helperText"
+          helperText="helper text"
+        >
+          <Checkbox value="2" labelText="Checkbox 2" />
+          <Checkbox value="3" labelText="Checkbox 3" />
+        </CheckboxGroup>
+      )
+      .toJSON();
+    const invalidText = renderer
+      .create(
+        <CheckboxGroup
+          labelText="invalidText"
+          name="invalidText"
+          id="invalidText"
+          invalidText="error text"
+        >
+          <Checkbox value="2" labelText="Checkbox 2" />
+          <Checkbox value="3" labelText="Checkbox 3" />
+        </CheckboxGroup>
+      )
+      .toJSON();
+    const noOptReqLabel = renderer
+      .create(
+        <CheckboxGroup
+          labelText="no optional or required label"
+          name="optReq"
+          id="optReq"
+          optReqFlag={false}
+        >
+          <Checkbox value="2" labelText="Checkbox 2" />
+          <Checkbox value="3" labelText="Checkbox 3" />
+        </CheckboxGroup>
+      )
+      .toJSON();
+    const isRequired = renderer
+      .create(
+        <CheckboxGroup
+          labelText="required"
+          name="required"
+          id="required"
+          isRequired
+        >
+          <Checkbox value="2" labelText="Checkbox 2" />
+          <Checkbox value="3" labelText="Checkbox 3" />
+        </CheckboxGroup>
+      )
+      .toJSON();
+    const isInvalid = renderer
+      .create(
+        <CheckboxGroup
+          labelText="invalid"
+          name="invalid"
+          id="invalid"
+          isInvalid
+        >
+          <Checkbox value="2" labelText="Checkbox 2" />
+          <Checkbox value="3" labelText="Checkbox 3" />
+        </CheckboxGroup>
+      )
+      .toJSON();
+    const isDisabled = renderer
+      .create(
+        <CheckboxGroup
+          labelText="disabled"
+          name="disabled"
+          id="disabled"
+          isDisabled
+        >
+          <Checkbox value="2" labelText="Checkbox 2" />
+          <Checkbox value="3" labelText="Checkbox 3" />
+        </CheckboxGroup>
+      )
+      .toJSON();
+
+    expect(column).toMatchSnapshot();
+    expect(row).toMatchSnapshot();
+    expect(noLabel).toMatchSnapshot();
+    expect(helperText).toMatchSnapshot();
+    expect(invalidText).toMatchSnapshot();
+    expect(noOptReqLabel).toMatchSnapshot();
+    expect(isRequired).toMatchSnapshot();
+    expect(isInvalid).toMatchSnapshot();
+    expect(isDisabled).toMatchSnapshot();
+  });
+
+  it("should throw warning when a non-Checkbox component is used as a child", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(
+      <CheckboxGroup labelText="wrong child!" name="wrong" id="wrong-child">
+        <p>This is wrong!</p>
+      </CheckboxGroup>
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "Only `Checkbox` components are allowed inside the `CheckboxGroup` component."
+    );
+  });
+});