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

package/src/components/Tabs/Tabs.stories.mdx

@@ -0,0 +1,338 @@
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import Tabs, { TabList, Tab, TabPanels, TabPanel } from "./Tabs";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta
+  title={getCategory("Tabs")}
+  component={Tabs}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=36835%3A26464",
+    },
+    jest: ["Tabs.test.tsx"],
+  }}
+  argTypes={{
+    children: { table: { disable: true } },
+    defaultIndex: {
+      table: { defaultValue: { summary: 0 } },
+    },
+    id: { control: false },
+    onChange: { control: false },
+    tabsData: { control: false },
+    useHash: {
+      table: { defaultValue: { summary: false } },
+    },
+  }}
+/>
+
+# Tabs
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.24.0`   |
+| Latest            | `0.28.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Composing with a Data Object](#composing-with-a-data-object)
+- [Responsive Mobile Carousel](#responsive-mobile-carousel)
+- [With Callback Event Function](#with-callback-event-function)
+- [With URL Hash Option](#with-url-hash-option)
+- [With Children Components](#with-children-components)
+
+## Overview
+
+<Description of={Tabs} />
+
+export const animalCrossing = [
+  {
+    label: "Tom Nook",
+    content: (
+      <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",
+    content:
+      "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",
+    content:
+      "<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>",
+  },
+  {
+    label: "Mr. Resetti",
+    content:
+      "<strong>Mr. Resetti</strong>, full name Sonny Resetti, is a fictional " +
+      "character from the Animal Crossing series of video games by Nintendo. " +
+      "His first appearance was in the Nintendo 64 game Dōbutsu no Mori, " +
+      "released in Europe and North America on the GameCube as Animal Crossing.",
+  },
+  {
+    label: "Zucker",
+    content:
+      "<strong>Zucker</strong> is a lazy octopus villager who first appeared " +
+      "in New Leaf. His Japanese name and general appearance refers to the " +
+      "Japanese snack takoyaki, which is a fried ball of dough commonly " +
+      "filled with minced octopus. His catchphrase is a reference to how he " +
+      "is an underwater animal. He has the same initial phrase as Bertha. He " +
+      "has the nature hobby.",
+  },
+];
+
+## Component Props
+
+<Canvas withToolbar>
+  <Story
+    name="Tabs with Controls"
+    args={{
+      tabsData: animalCrossing,
+      defaultIndex: 0,
+      id: "tabs-id",
+      onChange: undefined,
+      useHash: false,
+    }}
+  >
+    {(args) => <Tabs {...args} />}
+  </Story>
+</Canvas>
+
+<ArgsTable story="Tabs with Controls" />
+
+## Accessibility
+
+Using the DS `Tabs` component renders HTML for button tabs and panels that are
+associated with each other. In order to simplify the content and reduce cognitive
+load for a user, we recommend to not use more than a six (6) button tabs and
+panels. Likewise, button tab labels should be clear and concise. Do not use
+icons for tab labels.
+
+The `Tabs` component is fully accessible through keyboard usage. The initial focus
+on the UI is set on the first tab. To move between tabs, use the left and right
+key arrows. The `home` key can be used to navigate to the first tab and the `end`
+key can be used to navigate to the last tab. To move from a tab to its panel,
+use the `tab` key. Likewise, use the `tab + shift` key combination to move from
+the panel to its tab. A user cannot navigate between panels; they must navigate
+through the tabs.
+
+This `Tabs` component is implemented with Chakra UI and this library handles the
+appropriate `aria-selected` and `aria-controls` attributes for the tabs, the
+related `aria-labelledby` and `id` attributes for the panels, and the `tablist`,
+`tab`, and `tabpanel` roles for the relevant HTML elements.
+
+### Mobile Carousel
+
+When viewing the `Tabs` component on a narrow screen, an additional carousel
+interface is wrapped around the button tabs. "Next" and "Previous" arrow buttons
+slide the view of the tabs to the left and right, but all initial functionality
+for the `Tabs` component doesn't change.
+
+Resources:
+
+- [Inclusive Design Tabbed Interfaces](https://inclusive-components.design/tabbed-interfaces/)
+- [W3C WAI Example of Tabs with Automatic Activation](https://www.w3.org/TR/wai-aria-practices/examples/tabs/tabs-1/tabs.html)
+- [Chakra UI Tabs](https://chakra-ui.com/docs/components/disclosure/tabs)
+
+## Composing with a Data Object
+
+_Note: this is the recommended approach._
+
+We recommended passing in the data for the `Tabs` component through the `data`
+prop. This allows the consumer to pass in well-formed data and always generate
+the correct DOM.
+
+Internally in the Reservoir Design System (DS) `Tabs` component:
+
+- we map through the data array and generate the appropriate components needed
+  for the layout.
+- adds the carousel feature for the mobile view.
+
+Note that HTML is allowed in the `content` property in each object as part of the
+string or as straight HTML.
+
+```jsx
+import { Tabs } from "@nypl/design-system-react-components";
+
+const animalCrossing = [
+  {
+    label: "Tom Nook",
+    content: <p>Tom Nook, <b>known in Japan as Tanukichi</b>, is a ...,
+  {
+    label: "Isabelle",
+    content: "Isabelle, known as Shizue in Japan, is a fictional ...",
+  },
+  {
+    label: "K.K. Slider",
+    content:
+      "<p>Totakeke, more commonly known as <b>K.K. Slider or K.K.</b>, is ...",
+  },
+  {
+    label: "Mr. Resetti",
+    content:
+      "<strong>Mr. Resetti</strong>, full name Sonny Resetti, is a ...",
+  },
+  {
+    label: "Zucker",
+    content:
+      "<strong>Zucker</strong> is a lazy octopus villager who first ...",
+  },
+];
+
+// ...
+<Tabs tabsData={animalCrossing} />;
+```
+
+## Responsive Mobile Carousel
+
+For both, the `tabsData` prop approach and the children component approach
+(described below in this document), the mobile carousel feature is built. This
+adds "previous" and "next" arrows in the tab list for users to scroll through
+all the tabs while the panel stays static.
+
+Note that for the children component approach, we expect a `TabList` component
+to be passed or else the mobile carousel will _not_ be built. More on this in
+the [With Children Components](#with-children-components) section.
+
+To view and test this in Storybook, go to the "Canvas" tab and change the
+viewport in the Storybook toolbar at the top of the page.
+
+## With Callback Event Function
+
+If you need to keep track of the index of current tab that was selected, pass
+an `onChange` event handler to the `onChange` prop. This will return the index
+(0-based) of the tab selected.
+
+```jsx
+export const onChange = (value) => {
+  window.alert(`Tab index selected was ${value}`);
+};
+
+// ...
+<Tabs tabsData={animalCrossing} onChange={onChange} />;
+```
+
+export const onChange = (value) => {
+  window.alert(`Tab index selected was ${value}`);
+};
+
+<Canvas>
+  <Story name="With Callback Event Function">
+    <Tabs tabsData={animalCrossing} onChange={onChange} />
+  </Story>
+</Canvas>
+
+## With URL Hash Option
+
+In some situations, each selected tab should update the URL with a hash value.
+To enable this, set the `useHash` prop to true.
+
+<Canvas>
+  <Story name="With URL Hash Option">
+    <Tabs tabsData={animalCrossing} useHash={true} />
+  </Story>
+</Canvas>
+
+## With Children Components
+
+_Note: not recommended but available._
+
+There are five components that make up the Design System `Tabs` component:
+`Tabs`, `TabList`, `Tab`, `TabPanels`, `TabPanel`. The general layout is always
+the same such that the `Tabs` component has `TabList` and `TabPanels` as children.
+
+`TabList` only takes `Tab` components as children and `TabPanels` only take
+`TabPanel` as children. While you can compose the DS `Tabs` components with these
+available components, you will probably have to iterate or map through an array
+to get the desired outcome. The DS `Tabs` component does this internally for
+you so this should be a last resort option.
+
+Make sure that:
+
+- all five components are imported to use this approach.
+- the structure follows the example below for the mobile carousel to render properly.
+
+```jsx
+import {
+  Tabs,
+  TabList,
+  Tab,
+  TabPanels,
+  TabPanel,
+} from "@nypl/design-system-react-components";
+```
+
+<Canvas>
+  <Story name="With Children Components">
+    <Tabs>
+      <TabList>
+        <Tab>Tom Nook</Tab>
+        <Tab>Isabelle</Tab>
+        <Tab>K.K. Slider</Tab>
+        <Tab>Mr. Resetti</Tab>
+        <Tab>Zucker</Tab>
+      </TabList>
+      <TabPanels>
+        <TabPanel>
+          <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>
+        </TabPanel>
+        <TabPanel>
+          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.
+        </TabPanel>
+        <TabPanel>
+          <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>
+        </TabPanel>
+        <TabPanel>
+          <strong>Mr. Resetti</strong>, full name Sonny Resetti, is a fictional
+          character from the Animal Crossing series of video games by Nintendo.
+          His first appearance was in the Nintendo 64 game Dōbutsu no Mori,
+          released in Europe and North America on the GameCube as Animal
+          Crossing.
+        </TabPanel>
+        <TabPanel>
+          <strong>Zucker</strong> is a lazy octopus villager who first appeared
+          in New Leaf. His Japanese name and general appearance refers to the
+          Japanese snack takoyaki, which is a fried ball of dough commonly
+          filled with minced octopus. His catchphrase is a reference to how he
+          is an underwater animal. He has the same initial phrase as Bertha. He
+          has the nature hobby.
+        </TabPanel>
+      </TabPanels>
+    </Tabs>
+  </Story>
+</Canvas>

package/src/components/Tabs/Tabs.test.tsx

@@ -0,0 +1,298 @@
+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 { Tabs, TabList, Tab, TabPanels, TabPanel } from "./Tabs";
+
+export const animalCrossing = [
+  {
+    label: "Tom Nook",
+    content: (
+      <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",
+    content:
+      "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",
+    content:
+      "<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("Tabs Accessibility", () => {
+  it("passes axe accessibility test with the data prop", async () => {
+    const { container } = render(<Tabs tabsData={animalCrossing} />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+
+  it("passes axe accessibility test with children components", async () => {
+    const { container } = render(
+      <Tabs>
+        <TabList>
+          <Tab>Tom Nook</Tab>
+          <Tab>Isabelle</Tab>
+          <Tab>K.K. Slider</Tab>
+        </TabList>
+        <TabPanels>
+          <TabPanel>
+            Tom Nook, known in Japan as Tanukichi, is a fictional character in
+            the Animal Crossing series who operates the village store.
+          </TabPanel>
+          <TabPanel>
+            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.
+          </TabPanel>
+          <TabPanel>
+            Totakeke, more commonly known as K.K. Slider or K.K., 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.
+          </TabPanel>
+        </TabPanels>
+      </Tabs>
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("Tabs", () => {
+  const getTabByName = (name: string) => screen.getByRole("tab", { name });
+
+  it("renders all tabs but only one panel at a time with children", () => {
+    render(
+      <Tabs>
+        <TabList>
+          <Tab>Tom Nook</Tab>
+          <Tab>Isabelle</Tab>
+          <Tab>K.K. Slider</Tab>
+        </TabList>
+        <TabPanels>
+          <TabPanel>
+            Tom Nook, known in Japan as Tanukichi, is a fictional character in
+            the Animal Crossing series who operates the village store.
+          </TabPanel>
+          <TabPanel>
+            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.
+          </TabPanel>
+          <TabPanel>
+            Totakeke, more commonly known as K.K. Slider or K.K., 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.
+          </TabPanel>
+        </TabPanels>
+      </Tabs>
+    );
+
+    expect(getTabByName("Tom Nook")).toBeInTheDocument();
+    expect(getTabByName("Isabelle")).toBeInTheDocument();
+    expect(getTabByName("K.K. Slider")).toBeInTheDocument();
+    expect(
+      screen.getByText(/Tom Nook, known in Japan as Tanukichi/i)
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByText(/Isabelle, known as Shizue in Japan,/i)
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByText(
+        /Totakeke, more commonly known as K.K. Slider or K.K./i
+      )
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders all tabs but only one visible panel at a time with data prop", () => {
+    render(<Tabs tabsData={animalCrossing} />);
+    expect(getTabByName("Tom Nook")).toBeInTheDocument();
+    expect(getTabByName("Isabelle")).toBeInTheDocument();
+    expect(getTabByName("K.K. Slider")).toBeInTheDocument();
+    expect(
+      screen.getByText(/known in Japan as Tanukichi/i)
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByText(/Isabelle, known as Shizue in Japan,/i)
+    ).not.toBeVisible();
+    expect(
+      screen.queryByText(/Totakeke, more commonly known as/i)
+    ).not.toBeVisible();
+  });
+
+  it("switches between tabs", () => {
+    render(<Tabs tabsData={animalCrossing} />);
+    const isabelleTab = getTabByName("Isabelle");
+    const kkSliderTab = getTabByName("K.K. Slider");
+
+    expect(
+      screen.getByText(/known in Japan as Tanukichi/i)
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByText(/Isabelle, known as Shizue in Japan,/i)
+    ).not.toBeVisible();
+    expect(
+      screen.queryByText(/Totakeke, more commonly known as/i)
+    ).not.toBeVisible();
+
+    userEvent.click(isabelleTab);
+    expect(isabelleTab).toHaveAttribute("aria-selected", "true");
+
+    expect(
+      screen.queryByText(/known in Japan as Tanukichi/i)
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByText(/Isabelle, known as Shizue in Japan,/i)
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByText(/Totakeke, more commonly known/i)
+    ).not.toBeVisible();
+
+    userEvent.click(kkSliderTab);
+    expect(kkSliderTab).toHaveAttribute("aria-selected", "true");
+
+    expect(
+      screen.queryByText(/known in Japan as Tanukichi/i)
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByText(/Isabelle, known as Shizue in Japan,/i)
+    ).not.toBeVisible();
+    expect(
+      screen.queryByText(/Totakeke, more commonly known/i)
+    ).toBeInTheDocument();
+  });
+
+  it("renders the specified initial index value", () => {
+    render(<Tabs tabsData={animalCrossing} defaultIndex={2} />);
+    let tomTab = getTabByName("Tom Nook");
+    let isabelleTab = getTabByName("Isabelle");
+    let kkSliderTab = getTabByName("K.K. Slider");
+
+    expect(tomTab).toHaveAttribute("aria-selected", "false");
+    expect(isabelleTab).toHaveAttribute("aria-selected", "false");
+    expect(kkSliderTab).toHaveAttribute("aria-selected", "true");
+  });
+
+  it("invokes the callback function", () => {
+    let selectedIndex = 0;
+    const onChange = (index: number) => (selectedIndex = index);
+
+    render(<Tabs tabsData={animalCrossing} onChange={onChange} />);
+
+    const tomTab = getTabByName("Tom Nook");
+    const isabelleTab = getTabByName("Isabelle");
+    const kkSliderTab = getTabByName("K.K. Slider");
+
+    userEvent.click(kkSliderTab);
+    expect(selectedIndex).toEqual(2);
+
+    userEvent.click(tomTab);
+    expect(selectedIndex).toEqual(0);
+
+    userEvent.click(isabelleTab);
+    expect(selectedIndex).toEqual(1);
+  });
+
+  it("should throw a warning when no data is passed", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(<Tabs />);
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir Tabs: Pass data in the `contentData` props or as children."
+    );
+  });
+
+  it("should throw a warning when both the 'data' prop and children are passed", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(
+      <Tabs tabsData={animalCrossing}>
+        <TabList>
+          <Tab>Tom Nook</Tab>
+          <Tab>Isabelle</Tab>
+          <Tab>K.K. Slider</Tab>
+        </TabList>
+        <TabPanels>
+          <TabPanel>
+            Tom Nook, known in Japan as Tanukichi, is a fictional character in
+            the Animal Crossing series who operates the village store.
+          </TabPanel>
+          <TabPanel>
+            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.
+          </TabPanel>
+          <TabPanel>
+            Totakeke, more commonly known as K.K. Slider or K.K., 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.
+          </TabPanel>
+        </TabPanels>
+      </Tabs>
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir Tabs: Only pass children or data in the `contentData` " +
+        "prop. Do not pass both."
+    );
+  });
+
+  it("should throw a warning when more than six object tabs are passed", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(
+      <Tabs
+        tabsData={[
+          ...animalCrossing,
+          ...[
+            { label: "Another character 1", content: "Text" },
+            { label: "Another character 2", content: "Text" },
+            { label: "Another character 3", content: "Text" },
+            { label: "Another character 4", content: "Text" },
+          ],
+        ]}
+      />
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir Tabs: it is recommended to use no more than six tabs. If " +
+        "more than six tabs are needed, consider other navigational patterns."
+    );
+  });
+
+  it("renders the UI snapshot correctly", () => {
+    const basic = renderer
+      .create(<Tabs tabsData={animalCrossing} id="basic" />)
+      .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <Tabs
+          tabsData={animalCrossing}
+          id="chakra"
+          p="20px"
+          color="ui.error.primary"
+        />
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(<Tabs tabsData={animalCrossing} id="props" data-testid="props" />)
+      .toJSON();
+
+    expect(basic).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
+  });
+});