@nypl/design-system-react-components 0.25.5 → 0.25.9

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

@@ -0,0 +1,200 @@
+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 { ToggleSizes } from "./ToggleSizes";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+import { getStorybookEnumValues } from "../../utils/utils";
+
+export const sizeEnumValues = getStorybookEnumValues(
+  ToggleSizes,
+  "ToggleSizes"
+);
+
+<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={{
+    additionalStyles: { control: false },
+    defaultChecked: { control: false },
+    id: { control: false },
+    key: { table: { disable: true } },
+    name: { control: false },
+    onChange: { control: false },
+    ref: { table: { disable: true } },
+    size: {
+      control: {
+        type: "select",
+        table: { defaultValue: { summary: "ToggleSizes.Large" } },
+        options: sizeEnumValues.options,
+      },
+    },
+  }}
+/>
+
+# Toggle
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.25.8`   |
+| Latest            | `0.25.9`   |
+
+<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.
+
+<Canvas>
+  <Story
+    name="Toggle"
+    args={{
+      additionalStyles: undefined,
+      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} size={sizeEnumValues.getValue(args.size)} />}
+  </Story>
+</Canvas>
+
+<ArgsTable story="Toggle" />
+
+## 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" />
+      </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" />
+      </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 isChecked={true} onChange={onChange} labelText="Controlled Toggle" />;
+```
+
+<Canvas>
+  <DSProvider>
+    <Toggle
+      isChecked={true}
+      onChange={(e) => {
+        console.log(e.target.value);
+      }}
+      labelText="Controlled Toggle"
+    />
+  </DSProvider>
+</Canvas>
+
+## Browser States
+
+<Canvas>
+  <DSProvider>
+    <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" />
+      </VStack>
+      <VStack align="left" spacing="s">
+        <Heading level={3}>Disabled</Heading>
+        <Toggle
+          size={ToggleSizes.Large}
+          defaultChecked={true}
+          isDisabled={true}
+          labelText="On"
+        />
+        <Toggle size={ToggleSizes.Large} labelText="Off" isDisabled={true} />
+      </VStack>
+      <VStack align="left" spacing="s">
+        <Heading level={3}>Error</Heading>
+        <Toggle
+          size={ToggleSizes.Large}
+          defaultChecked={true}
+          labelText="On"
+          isInvalid={true}
+        />
+        <Toggle size={ToggleSizes.Large} labelText="Off" isInvalid={true} />
+      </VStack>
+    </SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+## Layouts
+
+<Canvas>
+  <DSProvider>
+    <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" />
+      </VStack>
+      <VStack align="left" spacing="s">
+        <Heading level={3}>With Helper Text</Heading>
+        <Toggle
+          defaultChecked={true}
+          labelText="On"
+          helperText="Component Helper Text"
+        />
+      </VStack>
+    </SimpleGrid>
+  </DSProvider>
+</Canvas>

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

@@ -0,0 +1,140 @@
+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 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;
+  let generateUUIDSpy;
+
+  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("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");
+  });
+
+  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("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();
+
+    expect(primary).toMatchSnapshot();
+    expect(isChecked).toMatchSnapshot();
+    expect(isInvalid).toMatchSnapshot();
+    expect(isDisabled).toMatchSnapshot();
+  });
+});

package/src/components/Toggle/Toggle.tsx

@@ -0,0 +1,123 @@
+import {
+  Box,
+  Switch,
+  useMultiStyleConfig,
+  useStyleConfig,
+} from "@chakra-ui/react";
+import * as React from "react";
+
+import HelperErrorText, {
+  HelperErrorTextType,
+} from "../HelperErrorText/HelperErrorText";
+import { ToggleSizes } from "./ToggleSizes";
+import generateUUID from "../../helpers/generateUUID";
+
+export interface ToggleProps {
+  /** Optionally pass in additional Chakra-based styles. */
+  additionalStyles?: { [key: string]: any };
+  /** 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. This also makes
+   * the color theme "NYPL error" red for the button and text. */
+  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. */
+  labelText: string;
+  /** The name prop indicates into which group of checkboxes this checkbox
+   * belongs. 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. */
+  size?: ToggleSizes;
+}
+
+export const onChangeDefault = () => {
+  return;
+};
+
+/**
+ * Component that renders Chakra's `Switch` component along with NYPL defaults.
+ */
+const Toggle = React.forwardRef<HTMLInputElement, ToggleProps>(
+  (props, ref?) => {
+    const {
+      additionalStyles = {},
+      defaultChecked = false,
+      helperText,
+      id = generateUUID(),
+      invalidText,
+      isChecked,
+      isDisabled = false,
+      isInvalid = false,
+      isRequired = false,
+      labelText,
+      name,
+      onChange = onChangeDefault,
+      size = ToggleSizes.Large,
+    } = props;
+    const footnote: HelperErrorTextType = isInvalid ? invalidText : helperText;
+    const ariaAttributes = {};
+    const styles = useMultiStyleConfig("Toggle", {});
+    const switchStyles = useStyleConfig("Switch");
+    ariaAttributes["aria-label"] =
+      labelText && footnote ? `${labelText} - ${footnote}` : labelText;
+
+    return (
+      <>
+        <Box __css={{ ...styles, ...additionalStyles }}>
+          <Switch
+            id={id}
+            name={name || "default"}
+            isDisabled={isDisabled}
+            isInvalid={isInvalid}
+            isRequired={isRequired}
+            ref={ref}
+            size={size === ToggleSizes.Large ? "lg" : "sm"}
+            {...(isChecked !== undefined
+              ? {
+                  isChecked,
+                  onChange,
+                }
+              : {
+                  defaultChecked,
+                })}
+            {...ariaAttributes}
+            __css={switchStyles}
+          >
+            {labelText}
+          </Switch>
+        </Box>
+        {footnote && (
+          <Box __css={styles.helper}>
+            <HelperErrorText
+              id={`${id}-helperText`}
+              isInvalid={isInvalid}
+              text={footnote}
+            />
+          </Box>
+        )}
+      </>
+    );
+  }
+);
+
+export default Toggle;

package/src/components/Toggle/ToggleSizes.tsx

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