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

package/src/components/Accordion/Accordion.stories.mdx

@@ -0,0 +1,333 @@
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import ReactDOMServer from "react-dom/server";
+import { withDesign } from "storybook-addon-designs";
+
+import Accordion from "./Accordion";
+import Card, { CardHeading, CardContent } from "../Card/Card";
+import { getCategory } from "../../utils/componentCategories";
+
+<Meta
+  title={getCategory("Accordion")}
+  component={Accordion}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=10734%3A2520",
+    },
+    jest: ["Accordion.test.tsx"],
+  }}
+  argTypes={{
+    accordionData: { control: false },
+    id: { control: false },
+    isDefaultOpen: { table: { defaultValue: { summary: false } } },
+  }}
+/>
+
+# Accordion
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.1.0`    |
+| Latest            | `1.0.2`    |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [FAQ Example](#faq-example)
+
+## Overview
+
+<Description of={Accordion} />
+
+The `Accordion` component displays a list of high-level options that can
+expand and collapse to reveal associated sections of content. This component
+pushes existing content on the page down. Each accordion item is self contained,
+but when the data for multiple accordions is passed in through the `accordionData`
+prop, the `Accordion` components are grouped together and rendered under a single
+element. When grouped like this, each `Accordion` component still opens and
+closes independent from the others in the group.
+
+The only way to render an `Accordion` component is to pass in an array of objects
+with `label`, `panel`, and optional `accordionType` properties for each accordion item.
+Note that you can pass in a string or DOM elements into the `panel` property in each
+object. This approach is needed because, internally, we deal with the logic to render
+the necessary icon, Chakra components, and styles. Additionally, the `accordionType`
+prop can be used to change the accordion button's background color. It takes a value
+of `"default"` for `"ui.white"`, `"warning"` for `"ui.status.primary"`, and
+`"error"` for `"ui.status.secondary"`.
+
+```jsx
+const accordionData = [
+  {
+    accordionType: "default",
+    label: "Tom Nook",
+    panel: (
+      <Card
+        imageProps={{
+          alt: "Alt text",
+          aspectRatio: "twoByOne",
+          src: "https://play.nintendo.com/images/AC_Tom_FRYtwIN.17345b1513ac044897cfc243542899dce541e8dc.9afde10b.png",
+        }}
+        isCentered
+        layout="row"
+      >
+        <CardHeading level="four" id="heading1">
+          Tom Nook
+        </CardHeading>
+        <CardContent>
+          Tom Nook, <b>known in Japan as Tanukichi</b>, is a fictional
+          character in the Animal Crossing series who operates the
+          village store.
+        </CardContent>
+      </Card>
+    ),
+  },
+];
+
+...
+
+<Accordion accordionData={accordionData} />
+```
+
+## Component Props
+
+export const accordionData = [
+  {
+    accordionType: "default",
+    label: "Tom Nook",
+    panel: (
+      <Card
+        imageProps={{
+          alt: "Alt text",
+          aspectRatio: "twoByOne",
+          src: "https://play.nintendo.com/images/AC_Tom_FRYtwIN.17345b1513ac044897cfc243542899dce541e8dc.9afde10b.png",
+        }}
+        isCentered
+        layout="row"
+      >
+        <CardHeading level="four" id="heading1">
+          Tom Nook
+        </CardHeading>
+        <CardContent>
+          Tom Nook, <b>known in Japan as Tanukichi</b>, is a fictional character
+          in the Animal Crossing series who operates the village store.
+        </CardContent>
+      </Card>
+    ),
+  },
+];
+
+<Canvas withToolbar>
+  <Story
+    name="Accordion with Controls"
+    args={{
+      id: "accordion-id",
+      isDefaultOpen: false,
+    }}
+  >
+    {(args) => <Accordion accordionData={accordionData} {...args} />}
+  </Story>
+</Canvas>
+
+<ArgsTable story="Accordion with Controls" />
+
+## Accessibility
+
+- Follows [U.S. Web Design System (USWDS)](https://designsystem.digital.gov/components/accordion/)
+  guidelines:
+  - Use the `button` HTML element for screenreaders and keyboards.
+  - Use the `aria-expanded` attribute to indicate whether the `Accordion` is
+    expanded (`true`) or collapsed (`false`).
+  - Use the `aria-controls` attribute to associate the control with the panel.
+- Deviates from USWDS in that the user can open multiple panels. Opening one,
+  does not collapse already expanded panel.
+- The open and close icons are decorative (`aria-hidden` is `true`).
+- Visible focus goes around full button and full button is clickable
+
+Resources:
+
+- [W3C WAI-Aria Practices - Accordion](https://www.w3.org/TR/wai-aria-practices-1.1/#accordion)
+- [USWDS Accordion](https://designsystem.digital.gov/components/accordion/)
+- [Chakra Accordion](https://chakra-ui.com/docs/components/disclosure/accordion)
+
+## FAQ Example
+
+export const faqContent = [
+  {
+    accordionType: "default",
+    label: "Tom Nook",
+    panel: (
+      <Card
+        imageProps={{
+          alt: "Alt text",
+          aspectRatio: "twoByOne",
+          src: "https://play.nintendo.com/images/AC_Tom_FRYtwIN.17345b1513ac044897cfc243542899dce541e8dc.9afde10b.png",
+        }}
+        isCentered
+        layout="row"
+      >
+        <CardHeading level="four" id="heading1-tom">
+          Tom Nook
+        </CardHeading>
+        <CardContent>
+          Tom Nook, <b>known in Japan as Tanukichi</b>, is a fictional character
+          in the Animal Crossing series who operates the village store.
+        </CardContent>
+      </Card>
+    ),
+  },
+  {
+    accordionType: "warning",
+    label: "Isabelle",
+    panel: (
+      <Card
+        imageProps={{
+          alt: "Alt text",
+          aspectRatio: "twoByOne",
+          src: "https://play.nintendo.com/images/AC_Isabelle_7XU6aGu.17345b1513ac044897cfc243542899dce541e8dc.9afde10b.png",
+        }}
+        isCentered
+        layout="row"
+      >
+        <CardHeading level="four" id="heading1-isabelle">
+          Isabelle
+        </CardHeading>
+        <CardContent>
+          Isabelle, known as Shizue in Japan, is a fictional character from the
+          Animal Crossing series of video games. She is a kindly Shih Tzu that
+          debuted in the 2012 release Animal Crossing: New Leaf, where she
+          serves as the secretary to the player character.
+        </CardContent>
+      </Card>
+    ),
+  },
+  {
+    accordionType: "error",
+    label: "K.K. Slider",
+    panel: (
+      <Card
+        imageProps={{
+          alt: "Alt text",
+          aspectRatio: "twoByOne",
+          src: "https://play.nintendo.com/images/AC_KK_jh4yj5t.17345b1513ac044897cfc243542899dce541e8dc.9afde10b.png",
+        }}
+        isCentered
+        layout="row"
+      >
+        <CardHeading level="four" id="heading1-kkslider">
+          K.K. Slider
+        </CardHeading>
+        <CardContent>
+          <p>
+            Totakeke, more commonly known as <b>K.K. Slider or K.K.</b>, is a
+            fictional character within the Animal Crossing franchise. One of the
+            franchise's most popular characters, he debuted in the title Animal
+            Crossing, and has appeared in every installment since.
+          </p>
+        </CardContent>
+      </Card>
+    ),
+  },
+];
+
+Building out FAQ-like accordions happens automatically when there are more than
+one object in the array passed into the `accordionData` prop.
+
+<Canvas withToolbar>
+  <Story name="FAQ Example">
+    <Accordion accordionData={faqContent} />
+  </Story>
+</Canvas>
+
+```jsx
+export const faqContent = [
+  {
+    accordionType: "default",
+    label: "Tom Nook",
+    panel: (
+      <Card
+        imageProps={{
+          alt: "Alt text",
+          aspectRatio: "twoByOne",
+          src: "https://play.nintendo.com/images/AC_Tom_FRYtwIN.17345b1513ac044897cfc243542899dce541e8dc.9afde10b.png",
+        }}
+        isCentered
+        layout="row"
+      >
+        <CardHeading level="four" id="heading1-tom">
+          Tom Nook
+        </CardHeading>
+        <CardContent>
+          Tom Nook, <b>known in Japan as Tanukichi</b>, is a fictional character
+          in the Animal Crossing series who operates the village store.
+        </CardContent>
+      </Card>
+    ),
+  },
+  {
+    accordionType: "warning",
+    label: "Isabelle",
+    panel: (
+      <Card
+        imageProps={{
+          alt: "Alt text",
+          aspectRatio: "twoByOne",
+          src: "https://play.nintendo.com/images/AC_Isabelle_7XU6aGu.17345b1513ac044897cfc243542899dce541e8dc.9afde10b.png",
+        }}
+        isCentered
+        layout="row"
+      >
+        <CardHeading level="four" id="heading1-isabelle">
+          Isabelle
+        </CardHeading>
+        <CardContent>
+          Isabelle, known as Shizue in Japan, is a fictional character from the
+          Animal Crossing series of video games. She is a kindly Shih Tzu that
+          debuted in the 2012 release Animal Crossing: New Leaf, where she
+          serves as the secretary to the player character.
+        </CardContent>
+      </Card>
+    ),
+  },
+  {
+    accordionType: "error",
+    label: "K.K. Slider",
+    panel: (
+      <Card
+        imageProps={{
+          alt: "Alt text",
+          aspectRatio: "twoByOne",
+          src: "https://play.nintendo.com/images/AC_KK_jh4yj5t.17345b1513ac044897cfc243542899dce541e8dc.9afde10b.png",
+        }}
+        isCentered
+        layout="row"
+      >
+        <CardHeading level="four" id="heading1-kkslider">
+          K.K. Slider
+        </CardHeading>
+        <CardContent>
+          <p>
+            Totakeke, more commonly known as <b>K.K. Slider or K.K.</b>, is a
+            fictional character within the Animal Crossing franchise. One of the
+            franchise's most popular characters, he debuted in the title Animal
+            Crossing, and has appeared in every installment since.
+          </p>
+        </CardContent>
+      </Card>
+    ),
+  },
+];
+
+...
+
+<Accordion accordionData={faqContent} />
+```

package/src/components/Accordion/Accordion.test.tsx

@@ -0,0 +1,237 @@
+import * as React from "react";
+import { axe } from "jest-axe";
+import { render, screen } from "@testing-library/react";
+import renderer from "react-test-renderer";
+import userEvent from "@testing-library/user-event";
+
+import Accordion from "./Accordion";
+import Card, { CardContent, CardHeading } from "../Card/Card";
+
+describe("Accordion Accessibility", () => {
+  it("passes axe accessibility test for one item", async () => {
+    const { container } = render(
+      <Accordion
+        accordionData={[
+          {
+            label: "Tom Nook",
+            panel: (
+              <p>
+                Tom Nook, <b>known in Japan as Tanukichi</b>, is a fictional
+                character in the Animal Crossing series who operates the village
+                store.
+              </p>
+            ),
+          },
+        ]}
+      />
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+
+  it("passes axe accessibility test for multiple items", async () => {
+    const { container } = render(
+      <Accordion
+        accordionData={[
+          {
+            label: "Tom Nook",
+            panel: (
+              <p>
+                Tom Nook, <b>known in Japan as Tanukichi</b>, is a fictional
+                character in the Animal Crossing series who operates the village
+                store.
+              </p>
+            ),
+          },
+          {
+            label: "Isabelle",
+            panel:
+              "Isabelle, known as Shizue in Japan, is a fictional character " +
+              "from the Animal Crossing series of video games. She is a kindly Shih " +
+              "Tzu that debuted in the 2012 release Animal Crossing: New Leaf, where " +
+              "she serves as the secretary to the player character.",
+          },
+        ]}
+      />
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+export const accordionData = [
+  {
+    label: "Tom Nook",
+    panel: (
+      <p>
+        Tom Nook, <b>known in Japan as Tanukichi</b>, is a fictional character
+        in the Animal Crossing series who operates the village store.
+      </p>
+    ),
+  },
+  {
+    label: "Isabelle",
+    panel:
+      "Isabelle, known as Shizue in Japan, is a fictional character " +
+      "from the Animal Crossing series of video games. She is a kindly Shih " +
+      "Tzu that debuted in the 2012 release Animal Crossing: New Leaf, where " +
+      "she serves as the secretary to the player character.",
+  },
+  {
+    label: "K.K. Slider",
+    panel:
+      "<p>Totakeke, more commonly known as <b>K.K. Slider or K.K.</b>, is a " +
+      "fictional character within the Animal Crossing franchise. One of the " +
+      "franchise's most popular characters, he debuted in the title Animal " +
+      "Crossing, and has appeared in every installment since.</p>",
+  },
+];
+
+describe("Accordion", () => {
+  it("renders a visible button with a label to click on", () => {
+    render(<Accordion accordionData={[accordionData[0]]} />);
+    const accordionLabel = screen.getByRole("button", { name: "Tom Nook" });
+
+    expect(accordionLabel).toBeInTheDocument();
+    // Closed by default.
+    expect(accordionLabel).toHaveAttribute("aria-expanded", "false");
+    expect(screen.getByText(/known in Japan as Tanukichi/i)).not.toBeVisible();
+  });
+
+  it("opens the panel by default with isDefaultOpen passed", () => {
+    render(<Accordion isDefaultOpen accordionData={[accordionData[0]]} />);
+    const accordionLabel = screen.getByRole("button", { name: "Tom Nook" });
+
+    expect(accordionLabel).toBeInTheDocument();
+    expect(accordionLabel).toHaveAttribute("aria-expanded", "true");
+  });
+
+  it("opens the accordion when the label is clicked", () => {
+    render(<Accordion accordionData={[accordionData[0]]} />);
+
+    const accordionLabel = screen.getByRole("button", { name: "Tom Nook" });
+    expect(accordionLabel).toHaveAttribute("aria-expanded", "false");
+    userEvent.click(accordionLabel);
+    expect(accordionLabel).toHaveAttribute("aria-expanded", "true");
+  });
+
+  it("renders multiple accordion items grouped together", () => {
+    render(<Accordion accordionData={accordionData} />);
+
+    const accordion1 = screen.getByRole("button", { name: "Tom Nook" });
+    const accordion2 = screen.getByRole("button", { name: "Isabelle" });
+    const accordion3 = screen.getByRole("button", { name: "K.K. Slider" });
+
+    expect(accordion1).toHaveAttribute("aria-expanded", "false");
+    expect(accordion2).toHaveAttribute("aria-expanded", "false");
+    expect(accordion3).toHaveAttribute("aria-expanded", "false");
+  });
+
+  it("opens each accordion item independently of each other", () => {
+    render(<Accordion accordionData={accordionData} />);
+
+    const accordion1 = screen.getByRole("button", { name: "Tom Nook" });
+    const accordion2 = screen.getByRole("button", { name: "Isabelle" });
+    const accordion3 = screen.getByRole("button", { name: "K.K. Slider" });
+
+    expect(accordion1).toHaveAttribute("aria-expanded", "false");
+    expect(accordion2).toHaveAttribute("aria-expanded", "false");
+    expect(accordion3).toHaveAttribute("aria-expanded", "false");
+
+    userEvent.click(accordion1);
+    expect(accordion1).toHaveAttribute("aria-expanded", "true");
+    expect(accordion2).toHaveAttribute("aria-expanded", "false");
+    expect(accordion3).toHaveAttribute("aria-expanded", "false");
+
+    userEvent.click(accordion2);
+    expect(accordion1).toHaveAttribute("aria-expanded", "true");
+    expect(accordion2).toHaveAttribute("aria-expanded", "true");
+    expect(accordion3).toHaveAttribute("aria-expanded", "false");
+
+    userEvent.click(accordion3);
+    userEvent.click(accordion1);
+    expect(accordion1).toHaveAttribute("aria-expanded", "false");
+    expect(accordion2).toHaveAttribute("aria-expanded", "true");
+    expect(accordion3).toHaveAttribute("aria-expanded", "true");
+  });
+
+  it("Renders the UI snapshot correctly", () => {
+    const accordionData = [
+      {
+        label: "Gerry Kellman",
+        panel: (
+          <Card
+            id="card"
+            imageProps={{
+              alt: "Alt text",
+              aspectRatio: "twoByOne",
+              src: "https://cdn.onebauer.media/one/media/6176/76fd/405b/ab5f/f20f/2d52/gerri-1500-1.jpg?format=jpg&quality=80&width=850&ratio=1-1&resize=aspectfit",
+            }}
+            isCentered
+            layout="row"
+          >
+            <CardHeading id="heading1" level="four">
+              Gerry Kellman
+            </CardHeading>
+            <CardContent>
+              Gerri is <b>one of Logan's most trusted confidantes</b>, one who
+              serves many roles within the company. She's one of the most
+              powerful people at Waystar Royco outside of the family itself.
+            </CardContent>
+          </Card>
+        ),
+      },
+    ];
+
+    const primary = renderer
+      .create(<Accordion accordionData={accordionData} id="accordian" />)
+      .toJSON();
+    const defaultOpen = renderer
+      .create(
+        <Accordion accordionData={accordionData} id="accordian" isDefaultOpen />
+      )
+      .toJSON();
+    const withError = renderer
+      .create(
+        <Accordion
+          accordionData={[{ ...accordionData[0], accordionType: "error" }]}
+          id="accordian"
+          isDefaultOpen
+        />
+      )
+      .toJSON();
+    const withWarning = renderer
+      .create(
+        <Accordion
+          accordionData={[{ ...accordionData[0], accordionType: "warning" }]}
+          id="accordian"
+          isDefaultOpen
+        />
+      )
+      .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <Accordion
+          accordionData={accordionData}
+          id="accordian"
+          p="s"
+          color="ui.error.primary"
+        />
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(
+        <Accordion
+          accordionData={accordionData}
+          id="accordian"
+          data-testid="testid"
+        />
+      )
+      .toJSON();
+
+    expect(primary).toMatchSnapshot();
+    expect(defaultOpen).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
+    expect(withError).toMatchSnapshot();
+    expect(withWarning).toMatchSnapshot();
+  });
+});

package/src/components/Accordion/Accordion.tsx

@@ -0,0 +1,137 @@
+import {
+  Accordion as ChakraAccordion,
+  AccordionButton,
+  AccordionItem,
+  AccordionPanel,
+  Box,
+  chakra,
+} from "@chakra-ui/react";
+import * as React from "react";
+
+import Icon from "../Icons/Icon";
+
+export type AccordionTypes = "default" | "warning" | "error";
+export interface AccordionDataProps {
+  accordionType?: AccordionTypes;
+  label: string;
+  panel: string | React.ReactNode;
+}
+export interface AccordionProps {
+  /** Array of data to display, and an optional accordionType */
+  accordionData: AccordionDataProps[];
+  /** ID that other components can cross reference for accessibility purposes */
+  id?: string;
+  /** Whether the accordion is open by default only on its initial rendering */
+  isDefaultOpen?: boolean;
+}
+
+/**
+ * Get the minus or plus icon depending on whether the accordion
+ * is open or closed.
+ */
+const getIcon = (isExpanded = false, index: number, id: string) => {
+  const iconName = isExpanded ? "minus" : "plus";
+  return (
+    <Icon id={`accordion-${id}-icon-${index}`} name={iconName} size="small" />
+  );
+};
+
+/**
+ * Returns `AccordionItems` for every accordion object in the data
+ * array. This automatically creates the `AccordionButton` and `AccordionPanel`
+ * combination that is required for the Chakra `Accordion` component.
+ */
+const getElementsFromData = (data: AccordionDataProps[] = [], id: string) => {
+  const colorMap = {
+    default: "ui.white",
+    warning: "ui.status.primary",
+    error: "ui.status.secondary",
+  };
+  // For FAQ-style multiple accordions, the button should be bigger.
+  // Otherwise, use the default.
+  const multipleFontSize = data?.length > 1 ? "text.default" : "text.caption";
+  const multiplePadding = data?.length > 1 ? "s" : "xs s";
+
+  return data.map((content, index) => {
+    // This is done to support both string and DOM element input.
+    const panel =
+      typeof content.panel === "string" ? (
+        <AccordionPanel
+          id={`${id}-panel-${index}`}
+          key={index}
+          dangerouslySetInnerHTML={{ __html: content.panel }}
+        />
+      ) : (
+        <AccordionPanel id={`${id}-panel-${index}`} key={index}>
+          {content.panel}
+        </AccordionPanel>
+      );
+
+    return (
+      <AccordionItem id={`${id}-item-${index}`} key={index}>
+        {/* Get the current state to render the correct icon. */}
+        {({ isExpanded }) => {
+          const bgColorByAccordionType = colorMap[content.accordionType];
+          return (
+            <>
+              <AccordionButton
+                id={`${id}-button-${index}`}
+                padding={multiplePadding}
+                bg={
+                  !content.accordionType
+                    ? colorMap.default
+                    : bgColorByAccordionType
+                }
+                _expanded={{
+                  bg:
+                    !content.accordionType ||
+                    content.accordionType === "default"
+                      ? "ui.gray.light-cool"
+                      : bgColorByAccordionType,
+                }}
+                _hover={{
+                  bg:
+                    !content.accordionType ||
+                    content.accordionType === "default"
+                      ? "transparent"
+                      : bgColorByAccordionType,
+                  borderColor: "ui.gray.dark",
+                }}
+              >
+                <Box flex="1" fontSize={multipleFontSize} textAlign="left">
+                  {content.label}
+                </Box>
+                {getIcon(isExpanded, index, id)}
+              </AccordionButton>
+              {panel}
+            </>
+          );
+        }}
+      </AccordionItem>
+    );
+  });
+};
+
+/**
+ * Accordion component that shows content on toggle. Can be used to display
+ * multiple accordion items together.
+ */
+export const Accordion = chakra((props: AccordionProps) => {
+  const { accordionData, id, isDefaultOpen = false, ...rest } = props;
+
+  // Pass `0` to open the first accordion in the 0-index based array.
+  const openFirstAccordion = isDefaultOpen ? [0] : undefined;
+
+  return (
+    <ChakraAccordion
+      id={id}
+      defaultIndex={openFirstAccordion}
+      allowMultiple
+      {...rest}
+    >
+      {getElementsFromData(accordionData, id)}
+    </ChakraAccordion>
+  );
+});
+
+export default Accordion;