@nypl/design-system-react-components 1.0.1 → 1.0.2

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

@@ -0,0 +1,237 @@
+import { HStack, VStack, Grid, Box } from "@chakra-ui/react";
+import {
+  Meta,
+  Story,
+  Canvas,
+  ArgsTable,
+  Description,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import Heading from "../Heading/Heading";
+import SimpleGrid from "../Grid/SimpleGrid";
+import Toggle from "./Toggle";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta
+  title={getCategory("Toggle")}
+  component={Toggle}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=31581%3A302",
+    },
+    jest: ["Toggle.test.tsx"],
+  }}
+  argTypes={{
+    defaultChecked: { control: false },
+    id: { control: false },
+    key: { table: { disable: true } },
+    name: { control: false },
+    onChange: { control: false },
+    ref: { table: { disable: true } },
+    size: {
+      control: {
+        table: { defaultValue: { summary: "default" } },
+      },
+    },
+  }}
+/>
+
+# Toggle
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.25.8`   |
+| Latest            | `1.0.2`    |
+
+## 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.
+
+### Best Practices
+
+`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.
+
+## Component Props
+
+<Canvas>
+  <Story
+    name="Toggle"
+    args={{
+      defaultChecked: false,
+      helperText: "This is the helper text!",
+      id: "toggle-1",
+      invalidText: "",
+      isChecked: undefined,
+      isDisabled: false,
+      isInvalid: false,
+      isRequired: false,
+      labelText: "Test Label",
+      name: "toggle-1",
+      onChange: undefined,
+      size: "ToogleSizes.Large",
+    }}
+  >
+    {(args) => <Toggle {...args} />}
+  </Story>
+</Canvas>
+
+<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}>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
+          defaultChecked={true}
+          id="small-checked"
+          size="small"
+          labelText="On"
+        />
+        <Toggle id="default-small" size="small" labelText="Off" />
+      </VStack>
+    </SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+## Controlled Toggle
+
+Note that the `isChecked` property in this example is set to `true`. Clicking
+on it won't change the toggle; The `isChecked` prop must now be controlled
+and removed manually by the parent component that controls this state. The
+`onChange` function will be called every time the `isChecked` prop changes.
+
+```jsx
+const isChecked = true;
+const onChange = (e) => {
+  // This will return the value through the event object.
+  console.log(e.target.value);
+};
+
+<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);
+      }}
+    />
+  </DSProvider>
+</Canvas>
+
+## Browser States
+
+<Canvas>
+  <DSProvider>
+    <SimpleGrid columns="3">
+      <VStack align="left" spacing="s">
+        <Heading level={3}>Default</Heading>
+        <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
+          defaultChecked={true}
+          id="disabled-checked"
+          isDisabled={true}
+          labelText="On"
+        />
+        <Toggle id="disabled2" isDisabled={true} labelText="Off" />
+      </VStack>
+      <VStack align="left" spacing="s">
+        <Heading level={3}>Error</Heading>
+        <Toggle
+          defaultChecked={true}
+          id="error-default"
+          isInvalid={true}
+          labelText="On"
+        />
+        <Toggle id="error2" isInvalid={true} labelText="Off" />
+      </VStack>
+    </SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+## Layouts
+
+<Canvas>
+  <DSProvider>
+    <SimpleGrid columns="2">
+      <VStack align="left" spacing="s">
+        <Heading level={3}>Grouped</Heading>
+        <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}
+          helperText="Component Helper Text"
+          id="helper-text"
+          labelText="On"
+        />
+      </VStack>
+    </SimpleGrid>
+  </DSProvider>
+</Canvas>

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

@@ -0,0 +1,170 @@
+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 Toggle from "./Toggle";
+
+describe("Toggle Accessibility", () => {
+  it("Passes axe accessibility test", async () => {
+    const { container } = render(
+      <Toggle id="inputID" onChange={jest.fn()} labelText="Test Label" />
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("Toggle", () => {
+  let changeHandler: jest.MockedFunction<() => void>;
+
+  beforeEach(() => {
+    changeHandler = jest.fn();
+  });
+
+  it("Renders with a Toggle input and label", () => {
+    render(<Toggle id="inputID" labelText="Test Label" />);
+    expect(screen.getByLabelText("Test Label")).toBeInTheDocument();
+    expect(screen.getByRole("checkbox")).toBeInTheDocument();
+  });
+
+  it("Renders visible helper or error text", () => {
+    const { rerender } = render(
+      <Toggle
+        id="inputID"
+        labelText="Test Label"
+        helperText="This is the helper text."
+        invalidText="This is the error text :("
+      />
+    );
+    expect(screen.getByText("This is the helper text.")).toBeVisible();
+    expect(
+      screen.queryByText("This is the error text :(")
+    ).not.toBeInTheDocument();
+
+    rerender(
+      <Toggle
+        id="inputID"
+        labelText="Test Label"
+        isInvalid
+        helperText="This is the helper text."
+        invalidText="This is the error text :("
+      />
+    );
+    expect(screen.getByText("This is the error text :(")).toBeVisible();
+    expect(
+      screen.queryByText("This is the helper text.")
+    ).not.toBeInTheDocument();
+  });
+
+  it("Sets the Toggle's ID", () => {
+    render(<Toggle id="inputID" labelText="Test Label" />);
+    expect(screen.getByRole("checkbox")).toHaveAttribute("id", "inputID");
+  });
+
+  it("Sets the 'checked' attribute", () => {
+    render(<Toggle id="inputID" labelText="Test Label" isChecked />);
+    expect(screen.getByRole("checkbox")).toHaveAttribute("checked");
+  });
+
+  it("Sets the 'disabled' attribute", () => {
+    render(<Toggle id="inputID" labelText="Test Label" isDisabled />);
+    expect(screen.getByRole("checkbox")).toHaveAttribute("disabled");
+  });
+
+  it("Sets the error state", () => {
+    render(
+      <Toggle
+        id="inputID-attributes"
+        labelText="onChange test"
+        invalidText="This is the error text!"
+        isInvalid
+      />
+    );
+    expect(screen.getByRole("checkbox")).toHaveAttribute("aria-invalid");
+    expect(screen.getByText("This is the error text!")).toBeInTheDocument();
+  });
+
+  it("does not render the error text when 'isInvalid' is true but 'invalidText' is not passed", () => {
+    render(
+      <Toggle id="inputID-attributes" labelText="onChange test" isInvalid />
+    );
+    expect(screen.getByRole("checkbox")).toHaveAttribute("aria-invalid");
+    expect(
+      screen.queryByText("This is the error text!")
+    ).not.toBeInTheDocument();
+  });
+
+  it("Changing the value calls the onChange handler", () => {
+    const utils = render(
+      <Toggle
+        id="onChangeTest"
+        onChange={changeHandler}
+        labelText="onChangeTest Lab"
+        isChecked
+      />
+    );
+
+    expect(changeHandler).toHaveBeenCalledTimes(0);
+    userEvent.click(utils.getByText("onChangeTest Lab"));
+    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" />)
+      .toJSON();
+    const isChecked = renderer
+      .create(<Toggle id="Toggle-checked" labelText="Test Label" isChecked />)
+      .toJSON();
+    const isInvalid = renderer
+      .create(<Toggle id="Toggle-invalid" labelText="Test Label" isInvalid />)
+      .toJSON();
+    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="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

@@ -0,0 +1,128 @@
+import {
+  Box,
+  chakra,
+  Switch,
+  useMultiStyleConfig,
+  useStyleConfig,
+} from "@chakra-ui/react";
+import * as React from "react";
+
+import ComponentWrapper from "../ComponentWrapper/ComponentWrapper";
+import { HelperErrorTextType } from "../HelperErrorText/HelperErrorText";
+import { getAriaAttrs } from "../../utils/utils";
+
+export type ToggleSizes = "default" | "small";
+export interface ToggleProps {
+  /** Used for uncontrolled scenarios.  Sets the state of the Toggle when the page first loads.
+   *   If true, the toggle will be initially set to the "on" position. */
+  defaultChecked?: boolean;
+  /** Optional string to populate the HelperErrorText for standard state */
+  helperText?: HelperErrorTextType;
+  /** ID that other components can cross reference for accessibility purposes */
+  id: string;
+  /** Optional string to populate the HelperErrorText for the error state
+   * when `isInvalid` is true. */
+  invalidText?: HelperErrorTextType;
+  /** When using the Toggle as a "controlled" form element, you can specify
+   * the Toggle's checked state using this prop.
+   * Learn more about controlled and uncontrolled form fields:
+   * https://goshakkk.name/controlled-vs-uncontrolled-inputs-react/ */
+  isChecked?: boolean;
+  /** 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. */
+  isInvalid?: boolean;
+  /** Adds the 'required' attribute to the input when true. */
+  isRequired?: boolean;
+  /** The toggle's label. This will serve as the text content for the `<label>` element */
+  labelText: string;
+  /** 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;
+  /** The size of the Toggle. Defaults to "large". */
+  size?: ToggleSizes;
+}
+
+export const onChangeDefault = () => {
+  return;
+};
+
+/**
+ * Component that renders Chakra's `Switch` component along with NYPL defaults.
+ */
+export const Toggle = chakra(
+  React.forwardRef<HTMLInputElement, ToggleProps>((props, ref?) => {
+    const {
+      defaultChecked = false,
+      helperText,
+      id,
+      invalidText,
+      isChecked,
+      isDisabled = false,
+      isInvalid = false,
+      isRequired = false,
+      labelText,
+      name,
+      onChange = onChangeDefault,
+      size = "default",
+      ...rest
+    } = props;
+    const styles = useMultiStyleConfig("Toggle", { isDisabled, size });
+    const switchStyles = useStyleConfig("Switch", { size });
+    const footnote = isInvalid ? invalidText : helperText;
+    const ariaAttributes = getAriaAttrs({
+      footnote,
+      id,
+      labelText,
+      name: "Toggle",
+      showLabel: true,
+    });
+
+    if (!id) {
+      console.warn(
+        "NYPL Reservoir Toggle: This component's required `id` prop was not passed."
+      );
+    }
+
+    return (
+      <ComponentWrapper
+        helperText={helperText}
+        helperTextStyles={styles.helperErrorText}
+        id={id}
+        invalidText={invalidText}
+        isInvalid={isInvalid}
+        {...rest}
+      >
+        <Box __css={styles}>
+          <Switch
+            id={id}
+            isDisabled={isDisabled}
+            isInvalid={isInvalid}
+            isRequired={isRequired}
+            name={name || "default"}
+            ref={ref}
+            size={size === "default" ? "lg" : "sm"}
+            lineHeight="1.5"
+            {...(isChecked !== undefined
+              ? {
+                  isChecked,
+                  onChange,
+                }
+              : {
+                  defaultChecked,
+                })}
+            {...ariaAttributes}
+            __css={switchStyles}
+          >
+            {labelText}
+          </Switch>
+        </Box>
+      </ComponentWrapper>
+    );
+  })
+);
+
+export default Toggle;