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

package/src/components/Toggle/Toggle.stories.mdx

@@ -11,7 +11,7 @@ import { withDesign } from "storybook-addon-designs";
 import Heading from "../Heading/Heading";
 import SimpleGrid from "../Grid/SimpleGrid";
 import Toggle from "./Toggle";
-import { ToggleSizes } from "./ToggleSizes";
+import { ToggleSizes } from "./ToggleTypes";
 import { getCategory } from "../../utils/componentCategories";
 import DSProvider from "../../theme/provider";
 import { getStorybookEnumValues } from "../../utils/utils";
@@ -43,7 +43,7 @@ export const sizeEnumValues = getStorybookEnumValues(
     size: {
       control: {
         type: "select",
-        table: { defaultValue: { summary: "ToggleSizes.Large" } },
+        table: { defaultValue: { summary: "ToggleSizes.Default" } },
         options: sizeEnumValues.options,
       },
     },
@@ -55,17 +55,35 @@ export const sizeEnumValues = getStorybookEnumValues(
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.25.8`   |
-| Latest            | `0.25.12`  |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Sizes](#sizes)
+- [Controlled Toggle](#controlled-toggle)
+- [Browser States](#browser-states)
+- [Layouts](#layouts)
+
+## Overview
 
 <Description of={Toggle} />
 
-The Toggle component is used as an alternative for the Checkbox component and returns a boolean response. Like the Checkbox component, the Toggle component can display a label to the right of the toggle and helper/error text below the toggle.
+The `Toggle` component is used as an alternative for the Checkbox component and
+returns a boolean response. Like the Checkbox component, the `Toggle` component
+can display a label to the right of the toggle and helper/error text below the toggle.
 
 ### Best Practices
 
-Toggle components are commonly used for “on/off” switches to perform binary actions that occur immediately after a user “flips the switch.”
+`Toggle` components are commonly used for “on/off” switches to perform binary
+actions that occur immediately after a user “flips the switch.”
 
-The Toggle component label should clarify the action being performed. Labels should be short and to the point, often three words or less.
+The Toggle component label should clarify the action being performed. Labels
+should be short and to the point, often three words or less.
+
+## Component Props
 
 <Canvas>
   <Story
@@ -92,20 +110,43 @@ The Toggle component label should clarify the action being performed. Labels sho
 
 <ArgsTable story="Toggle" />
 
+## Accessibility
+
+The `Toggle` component is implemented using Chakra's `Switch` component. While
+some accessibility resources state that using a `<button>` element is better for
+a toggle or switch component, Chakra UI internally uses a `checkbox` element.
+Because Chakra's `Switch` component handles the internal state so well and its
+styles, we chose this over implementing this component with a `<button>` element.
+
+For comparison and reference, resources that build toggle components with the
+`<button>` element are linked below.
+
+Resources:
+
+- [Chakra UI Switch](https://chakra-ui.com/docs/components/form/switch)
+- [W3C Switch Example Using HTML Button](https://w3c.github.io/aria-practices/examples/switch/switch-button.html)
+- [Inclusive Components Toggle Buttons](https://inclusive-components.design/toggle-button/)
+- [Accessible HTML Toggle Button (Switch)](https://www.erikkroes.nl/blog/accessible-html-toggle-button-switch/)
+
 ## Sizes
 
 <Canvas>
   <DSProvider>
     <SimpleGrid columns="2">
       <VStack align="left" spacing="s">
-        <Heading level={3}>Large</Heading>
-        <Toggle size={ToggleSizes.Large} defaultChecked={true} labelText="On" />
-        <Toggle size={ToggleSizes.Large} labelText="Off" />
+        <Heading level={3}>Default</Heading>
+        <Toggle defaultChecked={true} id="default-checked" labelText="On" />
+        <Toggle id="default" labelText="Off" />
       </VStack>
       <VStack align="left" spacing="s">
         <Heading level={3}>Small</Heading>
-        <Toggle size={ToggleSizes.Small} defaultChecked={true} labelText="On" />
-        <Toggle size={ToggleSizes.Small} labelText="Off" />
+        <Toggle
+          defaultChecked={true}
+          id="small-checked"
+          size={ToggleSizes.Small}
+          labelText="On"
+        />
+        <Toggle id="default-small" size={ToggleSizes.Small} labelText="Off" />
       </VStack>
     </SimpleGrid>
   </DSProvider>
@@ -125,17 +166,23 @@ const onChange = (e) => {
   console.log(e.target.value);
 };
 
-<Toggle isChecked={true} onChange={onChange} labelText="Controlled Toggle" />;
+<Toggle
+  id="toggle"
+  isChecked={true}
+  labelText="Controlled Toggle"
+  onChange={onChange}
+/>;
 ```
 
 <Canvas>
   <DSProvider>
     <Toggle
+      id="toggle"
       isChecked={true}
+      labelText="Controlled Toggle"
       onChange={(e) => {
         console.log(e.target.value);
       }}
-      labelText="Controlled Toggle"
     />
   </DSProvider>
 </Canvas>
@@ -147,28 +194,28 @@ const onChange = (e) => {
     <SimpleGrid columns="3">
       <VStack align="left" spacing="s">
         <Heading level={3}>Default</Heading>
-        <Toggle size={ToggleSizes.Large} defaultChecked={true} labelText="On" />
-        <Toggle size={ToggleSizes.Large} labelText="Off" />
+        <Toggle defaultChecked={true} id="checked-default2" labelText="On" />
+        <Toggle id="default2" labelText="Off" />
       </VStack>
       <VStack align="left" spacing="s">
         <Heading level={3}>Disabled</Heading>
         <Toggle
-          size={ToggleSizes.Large}
           defaultChecked={true}
+          id="disabled-checked"
           isDisabled={true}
           labelText="On"
         />
-        <Toggle size={ToggleSizes.Large} labelText="Off" isDisabled={true} />
+        <Toggle id="disabled2" isDisabled={true} labelText="Off" />
       </VStack>
       <VStack align="left" spacing="s">
         <Heading level={3}>Error</Heading>
         <Toggle
-          size={ToggleSizes.Large}
           defaultChecked={true}
-          labelText="On"
+          id="error-default"
           isInvalid={true}
+          labelText="On"
         />
-        <Toggle size={ToggleSizes.Large} labelText="Off" isInvalid={true} />
+        <Toggle id="error2" isInvalid={true} labelText="Off" />
       </VStack>
     </SimpleGrid>
   </DSProvider>
@@ -181,18 +228,19 @@ const onChange = (e) => {
     <SimpleGrid columns="2">
       <VStack align="left" spacing="s">
         <Heading level={3}>Grouped</Heading>
-        <Toggle defaultChecked={true} labelText="On" />
-        <Toggle defaultChecked={true} labelText="On" />
-        <Toggle defaultChecked={true} labelText="On" />
-        <Toggle defaultChecked={true} labelText="On" />
-        <Toggle defaultChecked={true} labelText="On" />
+        <Toggle defaultChecked={true} id="layout1" labelText="On" />
+        <Toggle defaultChecked={true} id="layout2" labelText="On" />
+        <Toggle defaultChecked={true} id="layout3" labelText="On" />
+        <Toggle defaultChecked={true} id="layout4" labelText="On" />
+        <Toggle defaultChecked={true} id="layout5" labelText="On" />
       </VStack>
       <VStack align="left" spacing="s">
         <Heading level={3}>With Helper Text</Heading>
         <Toggle
           defaultChecked={true}
-          labelText="On"
           helperText="Component Helper Text"
+          id="helper-text"
+          labelText="On"
         />
       </VStack>
     </SimpleGrid>

package/src/components/Toggle/Toggle.test.tsx

@@ -1,10 +1,11 @@
-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 * as React from "react";
 import renderer from "react-test-renderer";
-import * as generateUUID from "../../helpers/generateUUID";
+
 import Toggle from "./Toggle";
+import { ToggleSizes } from "./ToggleTypes";
 
 describe("Toggle Accessibility", () => {
   it("Passes axe accessibility test", async () => {
@@ -17,7 +18,6 @@ describe("Toggle Accessibility", () => {
 
 describe("Toggle", () => {
   let changeHandler;
-  let generateUUIDSpy;
 
   beforeEach(() => {
     changeHandler = jest.fn();
@@ -63,13 +63,6 @@ describe("Toggle", () => {
     expect(screen.getByRole("checkbox")).toHaveAttribute("id", "inputID");
   });
 
-  it("Calls the UUID generation function if no id prop value is passed", () => {
-    generateUUIDSpy = jest.spyOn(generateUUID, "default");
-    expect(generateUUIDSpy).toHaveBeenCalledTimes(0);
-    render(<Toggle labelText="Test Label" />);
-    expect(generateUUIDSpy).toHaveBeenCalledTimes(1);
-  });
-
   it("Sets the 'checked' attribute", () => {
     render(<Toggle id="inputID" labelText="Test Label" isChecked />);
     expect(screen.getByRole("checkbox")).toHaveAttribute("checked");
@@ -118,6 +111,18 @@ describe("Toggle", () => {
     expect(changeHandler).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.
+      <Toggle labelText="test" />
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir Toggle: This component's required `id` prop was not passed."
+    );
+  });
+
   it("Renders the UI snapshot correctly", () => {
     const primary = renderer
       .create(<Toggle id="inputID" labelText="Test Label" />)
@@ -131,10 +136,36 @@ describe("Toggle", () => {
     const isDisabled = renderer
       .create(<Toggle id="Toggle-disabled" labelText="Test Label" isDisabled />)
       .toJSON();
+    const small = renderer
+      .create(
+        <Toggle
+          id="Toggle-disabled"
+          labelText="Test Label"
+          isDisabled
+          size={ToggleSizes.Small}
+        />
+      )
+      .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <Toggle
+          id="chakra"
+          labelText="Test Label"
+          p="20px"
+          color="ui.error.primray"
+        />
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(<Toggle id="props" labelText="Test Label" data-testid="props" />)
+      .toJSON();
 
     expect(primary).toMatchSnapshot();
     expect(isChecked).toMatchSnapshot();
     expect(isInvalid).toMatchSnapshot();
     expect(isDisabled).toMatchSnapshot();
+    expect(small).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
   });
 });

package/src/components/Toggle/Toggle.tsx

@@ -1,5 +1,6 @@
 import {
   Box,
+  chakra,
   Switch,
   useMultiStyleConfig,
   useStyleConfig,
@@ -9,9 +10,7 @@ import * as React from "react";
 import HelperErrorText, {
   HelperErrorTextType,
 } from "../HelperErrorText/HelperErrorText";
-import { ToggleSizes } from "./ToggleSizes";
-import generateUUID from "../../helpers/generateUUID";
-
+import { ToggleSizes } from "./ToggleTypes";
 export interface ToggleProps {
   /** Optionally pass in additional Chakra-based styles. */
   additionalStyles?: { [key: string]: any };
@@ -21,7 +20,7 @@ export interface ToggleProps {
   /** 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;
@@ -33,20 +32,18 @@ export interface ToggleProps {
   /** Adds the 'disabled' and `aria-disabled` attributes to the input when true.
    * This also makes the text italic and color scheme gray. */
   isDisabled?: boolean;
-  /** Adds the 'aria-invalid' attribute to the input when true. This also makes
-   * the color theme "NYPL error" red for the button and text. */
+  /** Adds the 'aria-invalid' attribute to the input when true. */
   isInvalid?: boolean;
   /** Adds the 'required' attribute to the input when true. */
   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. */
+  /** The toggle's label. This will serve as the text content for the `<label>` element */
   labelText: string;
-  /** The name prop indicates into which group of checkboxes this checkbox
-   * belongs. If none is specified, 'default' will be used */
+  /** The name prop indicates the `Toggle`'s form element name. If none is
+   * specified, 'default' will be used. */
   name?: string;
   /** The action to perform on the `<input>`'s onChange function  */
   onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
-  /** Offers the ability to hide the helper/invalid text. */
+  /** The size of the Toggle. Defaults to "large". */
   size?: ToggleSizes;
 }
 
@@ -57,13 +54,13 @@ export const onChangeDefault = () => {
 /**
  * Component that renders Chakra's `Switch` component along with NYPL defaults.
  */
-const Toggle = React.forwardRef<HTMLInputElement, ToggleProps>(
-  (props, ref?) => {
+export const Toggle = chakra(
+  React.forwardRef<HTMLInputElement, ToggleProps>((props, ref?) => {
     const {
       additionalStyles = {},
       defaultChecked = false,
       helperText,
-      id = generateUUID(),
+      id,
       invalidText,
       isChecked,
       isDisabled = false,
@@ -72,18 +69,25 @@ const Toggle = React.forwardRef<HTMLInputElement, ToggleProps>(
       labelText,
       name,
       onChange = onChangeDefault,
-      size = ToggleSizes.Large,
+      size = ToggleSizes.Default,
+      ...rest
     } = props;
     const footnote: HelperErrorTextType = isInvalid ? invalidText : helperText;
     const ariaAttributes = {};
-    const styles = useMultiStyleConfig("Toggle", {});
+    const styles = useMultiStyleConfig("Toggle", { isDisabled, size });
     const switchStyles = useStyleConfig("Switch", { size });
     ariaAttributes["aria-label"] =
       labelText && footnote ? `${labelText} - ${footnote}` : labelText;
 
+    if (!id) {
+      console.warn(
+        "NYPL Reservoir Toggle: This component's required `id` prop was not passed."
+      );
+    }
+
     return (
       <>
-        <Box __css={{ ...styles, ...additionalStyles }}>
+        <Box __css={{ ...styles, ...additionalStyles }} {...rest}>
           <Switch
             id={id}
             name={name || "default"}
@@ -91,7 +95,7 @@ const Toggle = React.forwardRef<HTMLInputElement, ToggleProps>(
             isInvalid={isInvalid}
             isRequired={isRequired}
             ref={ref}
-            size={size === ToggleSizes.Large ? "lg" : "sm"}
+            size={size === ToggleSizes.Default ? "lg" : "sm"}
             lineHeight="1.5"
             {...(isChecked !== undefined
               ? {
@@ -108,17 +112,16 @@ const Toggle = React.forwardRef<HTMLInputElement, ToggleProps>(
           </Switch>
         </Box>
         {footnote && (
-          <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 Toggle;

package/src/components/Toggle/{ToggleSizes.tsx → ToggleTypes.tsx}

@@ -1,4 +1,4 @@
 export enum ToggleSizes {
-  Large = "large",
+  Default = "default",
   Small = "small",
 }

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

@@ -2,7 +2,7 @@
 
 exports[`Toggle Renders the UI snapshot correctly 1`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
 >
   <label
     className="chakra-switch css-18x0has"
@@ -63,7 +63,7 @@ exports[`Toggle Renders the UI snapshot correctly 1`] = `
 
 exports[`Toggle Renders the UI snapshot correctly 2`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
 >
   <label
     className="chakra-switch css-18x0has"
@@ -128,7 +128,7 @@ exports[`Toggle Renders the UI snapshot correctly 2`] = `
 
 exports[`Toggle Renders the UI snapshot correctly 3`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
 >
   <label
     className="chakra-switch css-18x0has"
@@ -192,7 +192,7 @@ exports[`Toggle Renders the UI snapshot correctly 3`] = `
 
 exports[`Toggle Renders the UI snapshot correctly 4`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
 >
   <label
     className="chakra-switch css-18x0has"
@@ -253,3 +253,190 @@ exports[`Toggle Renders the UI snapshot correctly 4`] = `
   </label>
 </div>
 `;
+
+exports[`Toggle Renders the UI snapshot correctly 5`] = `
+<div
+  className="css-1xdhyk6"
+>
+  <label
+    className="chakra-switch css-18x0has"
+    data-disabled=""
+    onClick={[Function]}
+  >
+    <input
+      aria-disabled={true}
+      aria-invalid={false}
+      aria-label="Test Label"
+      checked={false}
+      className="chakra-switch__input"
+      disabled={true}
+      id="Toggle-disabled"
+      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-switch__track css-14qxnv8"
+      data-disabled=""
+      onMouseDown={[Function]}
+      onMouseEnter={[Function]}
+      onMouseLeave={[Function]}
+      onMouseUp={[Function]}
+    >
+      <span
+        className="chakra-switch__thumb css-0"
+      />
+    </span>
+    <span
+      className="chakra-switch__label css-1y8kf23"
+      data-disabled=""
+      onMouseDown={[Function]}
+      onTouchStart={[Function]}
+    >
+      Test Label
+    </span>
+  </label>
+</div>
+`;
+
+exports[`Toggle Renders the UI snapshot correctly 6`] = `
+<div
+  className="css-13xjm0o"
+>
+  <label
+    className="chakra-switch css-18x0has"
+    onClick={[Function]}
+  >
+    <input
+      aria-disabled={false}
+      aria-invalid={false}
+      aria-label="Test Label"
+      checked={false}
+      className="chakra-switch__input"
+      disabled={false}
+      id="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-switch__track css-14qxnv8"
+      onMouseDown={[Function]}
+      onMouseEnter={[Function]}
+      onMouseLeave={[Function]}
+      onMouseUp={[Function]}
+    >
+      <span
+        className="chakra-switch__thumb css-0"
+      />
+    </span>
+    <span
+      className="chakra-switch__label css-1y8kf23"
+      onMouseDown={[Function]}
+      onTouchStart={[Function]}
+    >
+      Test Label
+    </span>
+  </label>
+</div>
+`;
+
+exports[`Toggle Renders the UI snapshot correctly 7`] = `
+<div
+  className="css-1xdhyk6"
+  data-testid="props"
+>
+  <label
+    className="chakra-switch css-18x0has"
+    onClick={[Function]}
+  >
+    <input
+      aria-disabled={false}
+      aria-invalid={false}
+      aria-label="Test Label"
+      checked={false}
+      className="chakra-switch__input"
+      disabled={false}
+      id="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-switch__track css-14qxnv8"
+      onMouseDown={[Function]}
+      onMouseEnter={[Function]}
+      onMouseLeave={[Function]}
+      onMouseUp={[Function]}
+    >
+      <span
+        className="chakra-switch__thumb css-0"
+      />
+    </span>
+    <span
+      className="chakra-switch__label css-1y8kf23"
+      onMouseDown={[Function]}
+      onTouchStart={[Function]}
+    >
+      Test Label
+    </span>
+  </label>
+</div>
+`;