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

package/src/components/Checkbox/Checkbox.stories.mdx

@@ -57,12 +57,31 @@ import DSProvider from "../../theme/provider";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.1.0`    |
-| Latest            | `0.25.12`  |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Checked](#checked)
+- [Indeterminate](#indeterminate)
+- [Focused](#focused)
+- [Errored](#errored)
+- [Disabled](#disabled)
+- [Helper Text](#helper-text)
+- [Error Text](#error-text)
+- [With JSX Element Label](#with-jsx-element-label)
+
+## Overview
 
 <Description of={Checkbox} />
 
-This component renders a Checkbox button form element. See below for configuration information. Note that the `id` property, while optional, will
-cause an accessibility violation if none is present.
+This component renders a Checkbox button form element. See below for configuration
+information. Note that the `id` property, while optional, will cause an
+accessibility violation if none is present.
+
+## Component Props
 
 <Canvas withToolbar>
   <Story
@@ -91,6 +110,24 @@ cause an accessibility violation if none is present.
 
 <ArgsTable story="Checkbox" />
 
+## Accessibility
+
+The `Checkbox` component renders `<label>` and `<input type="checkbox" />`
+elements that are associated with each other; the label has a `for` attribute
+with the value of the `input`'s `id` element. If there is helper or invalid text,
+the `<input>` element will have a `aria-describedby` attribute with the value of
+the helper or invalid text.
+
+When `showLabel` is set to false, the `labelText` value will be set to the
+`<input>`'s `aria-label` attribute.
+
+Resources:
+
+- [W3C WAI ARIA Checkbox Example](https://www.w3.org/TR/wai-aria-practices-1.1/examples/checkbox/checkbox-1/checkbox-1.html)
+- [a11ymatters Accessible Checkbox](https://www.a11ymatters.com/pattern/checkbox/)
+- [MDN ARIA: checkbox role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role)
+- [Chakra UI Checkbox](https://chakra-ui.com/docs/components/form/checkbox)
+
 ## Checked
 
 Note that the `isChecked` property in this example is set to `true` and clicking
@@ -123,7 +160,10 @@ now be controlled and removed by the parent component in order to remove this st
 
 <Canvas>
   <DSProvider>
-    <Checkbox labelText="Click or tab to the Checkbox to see its focus state" />
+    <Checkbox
+      id="focused"
+      labelText="Click or tab to the Checkbox to see its focus state"
+    />
   </DSProvider>
 </Canvas>
 
@@ -132,8 +172,9 @@ now be controlled and removed by the parent component in order to remove this st
 <Canvas>
   <DSProvider>
     <HStack>
-      <Checkbox isInvalid labelText="I am in an error state" />
+      <Checkbox id="invalid" isInvalid labelText="I am in an error state" />
       <Checkbox
+        id="invalid-checked"
         isInvalid
         isChecked
         labelText="I am checked in an error state"
@@ -147,8 +188,13 @@ now be controlled and removed by the parent component in order to remove this st
 <Canvas>
   <DSProvider>
     <HStack>
-      <Checkbox isDisabled labelText="I am disabled" />
-      <Checkbox isDisabled isChecked labelText="I am checked and disabled" />
+      <Checkbox id="disabled" isDisabled labelText="I am disabled" />
+      <Checkbox
+        id="disabled-checked"
+        isDisabled
+        isChecked
+        labelText="I am checked and disabled"
+      />
     </HStack>
   </DSProvider>
 </Canvas>
@@ -158,6 +204,7 @@ now be controlled and removed by the parent component in order to remove this st
 <Canvas>
   <DSProvider>
     <Checkbox
+      id="helpertext"
       name="testHelperText"
       labelText="I have helper text"
       helperText="I am the helper text for this Checkbox"
@@ -170,10 +217,27 @@ now be controlled and removed by the parent component in order to remove this st
 <Canvas>
   <DSProvider>
     <Checkbox
-      name="testinvalidText"
-      labelText="I have error text"
+      id="invalid-text"
       invalidText="I am the error text for this Checkbox"
       isInvalid
+      name="testinvalidText"
+      labelText="I have error text"
+    />
+  </DSProvider>
+</Canvas>
+
+## With JSX Element Label
+
+This is useful when you want to add dynamic content to the label or add
+a layout to the label. View the `CheckboxGroup` documentation for this
+usage.
+
+<Canvas>
+  <DSProvider>
+    <Checkbox
+      id="jsx-label"
+      labelText={<span>Arts</span>}
+      name="jsxElementLabel"
     />
   </DSProvider>
 </Canvas>

package/src/components/Checkbox/Checkbox.test.tsx

@@ -1,13 +1,14 @@
+import { Flex, Spacer } from "@chakra-ui/react";
 import * as React from "react";
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { axe } from "jest-axe";
 import renderer from "react-test-renderer";
-import * as generateUUID from "../../helpers/generateUUID";
+
 import Checkbox from "./Checkbox";
 
 describe("Checkbox Accessibility", () => {
-  it("Passes axe accessibility test", async () => {
+  it("passes axe accessibility test with string label", async () => {
     const { container } = render(
       <Checkbox
         id="inputID"
@@ -18,15 +19,30 @@ describe("Checkbox Accessibility", () => {
     );
     expect(await axe(container)).toHaveNoViolations();
   });
+
+  it("passes axe accessibility test with jsx label", async () => {
+    const { container } = render(
+      <Checkbox
+        id="jsxLabel"
+        labelText={
+          <Flex>
+            <span>Arts</span>
+            <Spacer />
+            <span>4</span>
+          </Flex>
+        }
+        value="arts"
+      />
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
 });
 
 describe("Checkbox", () => {
   let changeHandler;
-  let generateUUIDSpy;
 
   beforeEach(() => {
     changeHandler = jest.fn();
-    generateUUIDSpy = jest.spyOn(generateUUID, "default");
   });
 
   it("Renders with a checkbox input and label", () => {
@@ -91,12 +107,6 @@ describe("Checkbox", () => {
     expect(screen.getByRole("checkbox")).toHaveAttribute("id", "inputID");
   });
 
-  it("Calls the UUID generation function if no id prop value is passed", () => {
-    expect(generateUUIDSpy).toHaveBeenCalledTimes(0);
-    render(<Checkbox labelText="Test Label" />);
-    expect(generateUUIDSpy).toHaveBeenCalledTimes(1);
-  });
-
   it("Sets the 'checked' attribute", () => {
     render(
       <Checkbox
@@ -195,6 +205,38 @@ describe("Checkbox", () => {
     expect(changeHandler).toHaveBeenCalledTimes(1);
   });
 
+  it("logs a warning if `labelText` is not a string and `showLabel` is false", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(
+      <Checkbox
+        id="checkbox"
+        value="arts"
+        labelText={
+          <Flex>
+            <span>Arts</span>
+            <Spacer />
+            <span>4</span>
+          </Flex>
+        }
+        showLabel={false}
+      />
+    );
+
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir Checkbox: `labelText` must be a string when `showLabel` is false."
+    );
+  });
+
+  it("Logs a warning when there is no `id` passed", () => {
+    const warn = jest.spyOn(console, "warn");
+    // @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.
+    render(<Checkbox labelText="checkbox" />);
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir Checkbox: This component's required `id` prop was not passed."
+    );
+  });
+
   it("Renders the UI snapshot correctly", () => {
     const primary = renderer
       .create(<Checkbox id="inputID" labelText="Test Label" />)
@@ -229,6 +271,40 @@ describe("Checkbox", () => {
         <Checkbox id="checkbox-disabled" labelText="Test Label" isDisabled />
       )
       .toJSON();
+    const withJSXLabel = renderer
+      .create(
+        <Checkbox
+          id="jsxLabel"
+          labelText={
+            <Flex>
+              <span>Arts</span>
+              <Spacer />
+              <span>4</span>
+            </Flex>
+          }
+          value="arts"
+        />
+      )
+      .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <Checkbox
+          id="checkbox-chakra"
+          labelText="Test Label"
+          p="s"
+          color="ui.error.primary"
+        />
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(
+        <Checkbox
+          id="checkbox-props"
+          labelText="Test Label"
+          data-testid="testid"
+        />
+      )
+      .toJSON();
 
     expect(primary).toMatchSnapshot();
     expect(isChecked).toMatchSnapshot();
@@ -236,5 +312,8 @@ describe("Checkbox", () => {
     expect(isRequired).toMatchSnapshot();
     expect(isInvalid).toMatchSnapshot();
     expect(isDisabled).toMatchSnapshot();
+    expect(withJSXLabel).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
   });
 });

package/src/components/Checkbox/Checkbox.tsx

@@ -1,5 +1,5 @@
 import {
-  Box,
+  chakra,
   Checkbox as ChakraCheckbox,
   Icon,
   useMultiStyleConfig,
@@ -9,15 +9,13 @@ import * as React from "react";
 import HelperErrorText, {
   HelperErrorTextType,
 } from "../HelperErrorText/HelperErrorText";
-import generateUUID from "../../helpers/generateUUID";
-
 export interface CheckboxProps {
   /** className you can add in addition to 'input' */
   className?: string;
   /** Optional string to populate the HelperErrorText for standard state */
   helperText?: HelperErrorTextType;
   /** ID that other components can cross reference for accessibility purposes */
-  id?: string;
+  id: string;
   /** Optional string to populate the HelperErrorText for the error state
    * when `isInvalid` is true. */
   invalidText?: HelperErrorTextType;
@@ -38,7 +36,7 @@ export interface CheckboxProps {
   isRequired?: boolean;
   /** The checkbox's label. This will serve as the text content for a `<label>`
    * element if `showlabel` is true, or an "aria-label" if `showLabel` is false. */
-  labelText: string;
+  labelText: string | JSX.Element;
   /** The name prop indicates into which group of checkboxes this checkbox
    * belongs. If none is specified, 'default' will be used */
   name?: string;
@@ -73,13 +71,13 @@ function CheckboxIcon(props) {
   );
 }
 
-const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
-  (props, ref?) => {
+export const Checkbox = chakra(
+  React.forwardRef<HTMLInputElement, CheckboxProps>((props, ref?) => {
     const {
       className,
       invalidText,
       helperText,
-      id = generateUUID(),
+      id,
       isChecked,
       isDisabled = false,
       isIndeterminate = false,
@@ -90,6 +88,7 @@ const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
       showHelperInvalidText = true,
       showLabel = true,
       value,
+      ...rest
     } = props;
     const styles = useMultiStyleConfig("Checkbox", {});
     const footnote: HelperErrorTextType = isInvalid ? invalidText : helperText;
@@ -98,7 +97,18 @@ const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
     // Use Chakra's default indeterminate icon.
     const icon = !isIndeterminate ? <CheckboxIcon /> : undefined;
 
+    if (!id) {
+      console.warn(
+        "NYPL Reservoir Checkbox: This component's required `id` prop was not passed."
+      );
+    }
+
     if (!showLabel) {
+      if (typeof labelText !== "string") {
+        console.warn(
+          "NYPL Reservoir Checkbox: `labelText` must be a string when `showLabel` is false."
+        );
+      }
       ariaAttributes["aria-label"] =
         labelText && footnote ? `${labelText} - ${footnote}` : labelText;
     } else {
@@ -129,21 +139,21 @@ const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
           alignItems="flex-start"
           __css={styles}
           {...ariaAttributes}
+          {...rest}
         >
           {showLabel && labelText}
         </ChakraCheckbox>
         {footnote && showHelperInvalidText && (
-          <Box __css={styles.helper}>
-            <HelperErrorText
-              id={`${id}-helperText`}
-              isInvalid={isInvalid}
-              text={footnote}
-            />
-          </Box>
+          <HelperErrorText
+            additionalStyles={styles.helperErrorText}
+            id={`${id}-helperText`}
+            isInvalid={isInvalid}
+            text={footnote}
+          />
         )}
       </>
     );
-  }
+  })
 );
 
 export default Checkbox;

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

@@ -2,7 +2,7 @@
 
 exports[`Checkbox Renders the UI snapshot correctly 1`] = `
 <label
-  className="chakra-checkbox css-g8du1g"
+  className="chakra-checkbox css-scawxr"
   onClick={[Function]}
 >
   <input
@@ -65,7 +65,7 @@ exports[`Checkbox Renders the UI snapshot correctly 1`] = `
 
 exports[`Checkbox Renders the UI snapshot correctly 2`] = `
 <label
-  className="chakra-checkbox css-g8du1g"
+  className="chakra-checkbox css-scawxr"
   data-checked=""
   onClick={[Function]}
 >
@@ -131,7 +131,7 @@ exports[`Checkbox Renders the UI snapshot correctly 2`] = `
 
 exports[`Checkbox Renders the UI snapshot correctly 3`] = `
 <label
-  className="chakra-checkbox css-g8du1g"
+  className="chakra-checkbox css-scawxr"
   data-checked=""
   onClick={[Function]}
 >
@@ -219,7 +219,7 @@ exports[`Checkbox Renders the UI snapshot correctly 3`] = `
 
 exports[`Checkbox Renders the UI snapshot correctly 4`] = `
 <label
-  className="chakra-checkbox css-g8du1g"
+  className="chakra-checkbox css-scawxr"
   onClick={[Function]}
 >
   <input
@@ -282,7 +282,7 @@ exports[`Checkbox Renders the UI snapshot correctly 4`] = `
 
 exports[`Checkbox Renders the UI snapshot correctly 5`] = `
 <label
-  className="chakra-checkbox css-g8du1g"
+  className="chakra-checkbox css-scawxr"
   data-invalid=""
   onClick={[Function]}
 >
@@ -348,7 +348,7 @@ exports[`Checkbox Renders the UI snapshot correctly 5`] = `
 
 exports[`Checkbox Renders the UI snapshot correctly 6`] = `
 <label
-  className="chakra-checkbox css-g8du1g"
+  className="chakra-checkbox css-scawxr"
   data-disabled=""
   onClick={[Function]}
 >
@@ -411,3 +411,206 @@ exports[`Checkbox Renders the UI snapshot correctly 6`] = `
   </span>
 </label>
 `;
+
+exports[`Checkbox Renders the UI snapshot correctly 7`] = `
+<label
+  className="chakra-checkbox css-scawxr"
+  onClick={[Function]}
+>
+  <input
+    aria-disabled={false}
+    aria-invalid={false}
+    checked={false}
+    className="chakra-checkbox__input"
+    disabled={false}
+    id="jsxLabel"
+    name="default"
+    onBlur={[Function]}
+    onChange={[Function]}
+    onFocus={[Function]}
+    onKeyDown={[Function]}
+    onKeyUp={[Function]}
+    required={false}
+    style={
+      Object {
+        "border": "0px",
+        "clip": "rect(0px, 0px, 0px, 0px)",
+        "height": "1px",
+        "margin": "-1px",
+        "overflow": "hidden",
+        "padding": "0px",
+        "position": "absolute",
+        "whiteSpace": "nowrap",
+        "width": "1px",
+      }
+    }
+    type="checkbox"
+    value="arts"
+  />
+  <span
+    aria-hidden={true}
+    className="chakra-checkbox__control css-dnty2r"
+    onMouseDown={[Function]}
+    onMouseEnter={[Function]}
+    onMouseLeave={[Function]}
+    onMouseUp={[Function]}
+  >
+    <svg
+      className="chakra-icon css-1vfv7ic"
+      focusable={false}
+      viewBox="0 0 24 24"
+    >
+      <path
+        d="M8.795 15.875l-4.17-4.17-1.42 1.41 5.59 5.59 12-12-1.41-1.41-10.59 10.58z"
+        fill="currentColor"
+      />
+    </svg>
+  </span>
+  <span
+    className="chakra-checkbox__label css-1oeb2oe"
+    onMouseDown={[Function]}
+    onTouchStart={[Function]}
+  >
+    <div
+      className="css-k008qs"
+    >
+      <span>
+        Arts
+      </span>
+      <div
+        className="css-17xejub"
+      />
+      <span>
+        4
+      </span>
+    </div>
+  </span>
+</label>
+`;
+
+exports[`Checkbox Renders the UI snapshot correctly 8`] = `
+<label
+  className="chakra-checkbox css-wkfjn4"
+  onClick={[Function]}
+>
+  <input
+    aria-disabled={false}
+    aria-invalid={false}
+    checked={false}
+    className="chakra-checkbox__input"
+    disabled={false}
+    id="checkbox-chakra"
+    name="default"
+    onBlur={[Function]}
+    onChange={[Function]}
+    onFocus={[Function]}
+    onKeyDown={[Function]}
+    onKeyUp={[Function]}
+    required={false}
+    style={
+      Object {
+        "border": "0px",
+        "clip": "rect(0px, 0px, 0px, 0px)",
+        "height": "1px",
+        "margin": "-1px",
+        "overflow": "hidden",
+        "padding": "0px",
+        "position": "absolute",
+        "whiteSpace": "nowrap",
+        "width": "1px",
+      }
+    }
+    type="checkbox"
+  />
+  <span
+    aria-hidden={true}
+    className="chakra-checkbox__control css-dnty2r"
+    onMouseDown={[Function]}
+    onMouseEnter={[Function]}
+    onMouseLeave={[Function]}
+    onMouseUp={[Function]}
+  >
+    <svg
+      className="chakra-icon css-1vfv7ic"
+      focusable={false}
+      viewBox="0 0 24 24"
+    >
+      <path
+        d="M8.795 15.875l-4.17-4.17-1.42 1.41 5.59 5.59 12-12-1.41-1.41-10.59 10.58z"
+        fill="currentColor"
+      />
+    </svg>
+  </span>
+  <span
+    className="chakra-checkbox__label css-1oeb2oe"
+    onMouseDown={[Function]}
+    onTouchStart={[Function]}
+  >
+    Test Label
+  </span>
+</label>
+`;
+
+exports[`Checkbox Renders the UI snapshot correctly 9`] = `
+<label
+  className="chakra-checkbox css-scawxr"
+  data-testid="testid"
+  onClick={[Function]}
+>
+  <input
+    aria-disabled={false}
+    aria-invalid={false}
+    checked={false}
+    className="chakra-checkbox__input"
+    disabled={false}
+    id="checkbox-props"
+    name="default"
+    onBlur={[Function]}
+    onChange={[Function]}
+    onFocus={[Function]}
+    onKeyDown={[Function]}
+    onKeyUp={[Function]}
+    required={false}
+    style={
+      Object {
+        "border": "0px",
+        "clip": "rect(0px, 0px, 0px, 0px)",
+        "height": "1px",
+        "margin": "-1px",
+        "overflow": "hidden",
+        "padding": "0px",
+        "position": "absolute",
+        "whiteSpace": "nowrap",
+        "width": "1px",
+      }
+    }
+    type="checkbox"
+  />
+  <span
+    aria-hidden={true}
+    className="chakra-checkbox__control css-dnty2r"
+    onMouseDown={[Function]}
+    onMouseEnter={[Function]}
+    onMouseLeave={[Function]}
+    onMouseUp={[Function]}
+  >
+    <svg
+      className="chakra-icon css-1vfv7ic"
+      focusable={false}
+      viewBox="0 0 24 24"
+    >
+      <path
+        d="M8.795 15.875l-4.17-4.17-1.42 1.41 5.59 5.59 12-12-1.41-1.41-10.59 10.58z"
+        fill="currentColor"
+      />
+    </svg>
+  </span>
+  <span
+    className="chakra-checkbox__label css-1oeb2oe"
+    onMouseDown={[Function]}
+    onTouchStart={[Function]}
+  >
+    Test Label
+  </span>
+</label>
+`;