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

package/src/components/List/List.test.tsx

@@ -0,0 +1,265 @@
+import * as React from "react";
+import { render, screen } from "@testing-library/react";
+import { axe } from "jest-axe";
+import renderer from "react-test-renderer";
+
+import List from "./List";
+
+const fishArray = ["Mahi-mahi", "Golden trout", "Rainbowfish", "Suckerfish"];
+const fishDescriptions = [
+  {
+    term: "Mahi-mahi",
+    description: <p>The mahi-mahi is an ocean fish known...</p>,
+  },
+  {
+    term: "Golden trout",
+    description: "The golden trout is a beautifully colored fish...",
+  },
+];
+
+describe("List Accessibility", () => {
+  it("passes axe accessibility test for unordered list", async () => {
+    const { container, rerender } = render(
+      <List type="ul">
+        <li>Mahi-mahi</li>
+        <li>Golden trout</li>
+      </List>
+    );
+    expect(await axe(container)).toHaveNoViolations();
+
+    rerender(<List type="ul" listItems={fishArray} />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+  it("passes axe accessibility test for ordered list", async () => {
+    const { container, rerender } = render(
+      <List type="ol">
+        <li>Mahi-mahi</li>
+        <li>Golden trout</li>
+      </List>
+    );
+    expect(await axe(container)).toHaveNoViolations();
+
+    rerender(<List type="ol" listItems={fishArray} />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+  it("passes axe accessibility test for description list", async () => {
+    const { container } = render(
+      <List
+        type="dl"
+        title="Animal Crossing Fish"
+        listItems={fishDescriptions}
+      />
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("List", () => {
+  it("renders unordered list", () => {
+    render(
+      <List type="ul">
+        <li>Mahi-mahi</li>
+        <li>Golden trout</li>
+      </List>
+    );
+
+    expect(screen.getAllByRole("listitem")).toHaveLength(2);
+    expect(screen.getByText("Mahi-mahi")).toBeInTheDocument();
+    expect(screen.getByText("Golden trout")).toBeInTheDocument();
+  });
+
+  it("renders unordered list with the `listItems` prop", () => {
+    render(<List type="ul" listItems={fishArray} />);
+
+    expect(screen.getAllByRole("listitem")).toHaveLength(4);
+    expect(screen.getByText("Mahi-mahi")).toBeInTheDocument();
+    expect(screen.getByText("Golden trout")).toBeInTheDocument();
+    expect(screen.getByText("Rainbowfish")).toBeInTheDocument();
+    expect(screen.getByText("Suckerfish")).toBeInTheDocument();
+  });
+
+  it("renders ordered list", () => {
+    render(
+      <List type="ol">
+        <li>Mahi-mahi</li>
+        <li>Golden trout</li>
+      </List>
+    );
+
+    expect(screen.getAllByRole("listitem")).toHaveLength(2);
+    expect(screen.getByText("Mahi-mahi")).toBeInTheDocument();
+    expect(screen.getByText("Golden trout")).toBeInTheDocument();
+  });
+
+  it("renders ordered list with the `listItems` prop", () => {
+    render(<List type="ol" listItems={fishArray} />);
+
+    expect(screen.getAllByRole("listitem")).toHaveLength(4);
+    expect(screen.getByText("Mahi-mahi")).toBeInTheDocument();
+    expect(screen.getByText("Golden trout")).toBeInTheDocument();
+    expect(screen.getByText("Rainbowfish")).toBeInTheDocument();
+    expect(screen.getByText("Suckerfish")).toBeInTheDocument();
+  });
+
+  it("returns description list", () => {
+    render(
+      <List type="dl">
+        <dt>Mahi-mahi</dt>
+        <dd>The mahi-mahi is an ocean fish known...</dd>
+      </List>
+    );
+    expect(screen.getByRole("definition")).toBeInTheDocument();
+    expect(screen.getByText("Mahi-mahi")).toBeInTheDocument();
+    expect(
+      screen.getByText("The mahi-mahi is an ocean fish known...")
+    ).toBeInTheDocument();
+  });
+
+  it("returns description list with the `listItems` prop", () => {
+    render(
+      <List
+        type="dl"
+        title="Animal Crossing Fish"
+        listItems={fishDescriptions}
+      />
+    );
+    expect(screen.getAllByRole("definition")).toHaveLength(2);
+  });
+
+  it("consoles a warning when children and the `listItems` prop are both passed", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(
+      <List type="ol" listItems={fishArray}>
+        <li>Mahi-mahi</li>
+        <li>Golden trout</li>
+        <li>Rainbowfish</li>
+        <li>Suckerfish</li>
+      </List>
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir List: Pass in either `<li>`, `<dt>`, or `<dd>` children " +
+        "or use the `listItems` data prop. Do not use both."
+    );
+  });
+
+  it("consoles a warning when no children are passed or the `listItems` prop is not passed", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(<List type="ol"></List>);
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir List: Pass in either `<li>` children or pass data in " +
+        "the `listItems` prop, not both."
+    );
+  });
+
+  it("consoles a warning when you pass an ordered or unordered list children that aren't <li>s", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(
+      <List type="ol">
+        <span>Mahi-mahi</span>
+        <span>Golden trout</span>
+        <span>Rainbowfish</span>
+      </List>
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir List: Direct children of `List` (ol) must be `<li>`s."
+    );
+  });
+
+  it("consoles a warning when you pass a description list children that aren't `<dt>`s or `<dd>`s", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(
+      <List type="dl">
+        <span>Mahi-mahi</span>
+        <span>Golden trout</span>
+        <span>Rainbowfish</span>
+      </List>
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir List: Direct children of `List` (description) must be " +
+        "`<dt>`s and `<dd>`s."
+    );
+  });
+
+  it("Renders the UI snapshot correctly", () => {
+    const unordered = renderer
+      .create(<List id="unordered" type="ul" listItems={fishArray} />)
+      .toJSON();
+    const unorderedNoStyling = renderer
+      .create(<List id="ordered" type="ul" listItems={fishArray} noStyling />)
+      .toJSON();
+    const ordered = renderer
+      .create(
+        <List id="unordered-no-styling" type="ol" listItems={fishArray} />
+      )
+      .toJSON();
+    const orderedNoStyling = renderer
+      .create(
+        <List
+          id="ordered-no-styling"
+          type="ol"
+          listItems={fishArray}
+          noStyling
+        />
+      )
+      .toJSON();
+    const description = renderer
+      .create(
+        <List
+          id="description"
+          type="dl"
+          title="Animal Crossing Fish"
+          listItems={fishDescriptions}
+        />
+      )
+      .toJSON();
+    const withChakraPropsUnordered = renderer
+      .create(
+        <List
+          id="chakra"
+          type="ul"
+          listItems={fishArray}
+          p="20px"
+          color="ui.error.primary"
+        />
+      )
+      .toJSON();
+    const withOtherPropsUnordered = renderer
+      .create(
+        <List id="other" type="ul" listItems={fishArray} data-testid="other" />
+      )
+      .toJSON();
+    const withChakraPropsDescription = renderer
+      .create(
+        <List
+          id="chakra"
+          type="dl"
+          title="Animal Crossing Fish"
+          listItems={fishDescriptions}
+          p="20px"
+          color="ui.error.primary"
+        />
+      )
+      .toJSON();
+    const withOtherPropsDescription = renderer
+      .create(
+        <List
+          id="other"
+          type="dl"
+          title="Animal Crossing Fish"
+          listItems={fishDescriptions}
+          data-testid="other"
+        />
+      )
+      .toJSON();
+
+    expect(unordered).toMatchSnapshot();
+    expect(unorderedNoStyling).toMatchSnapshot();
+    expect(ordered).toMatchSnapshot();
+    expect(orderedNoStyling).toMatchSnapshot();
+    expect(description).toMatchSnapshot();
+    expect(withChakraPropsUnordered).toMatchSnapshot();
+    expect(withOtherPropsUnordered).toMatchSnapshot();
+    expect(withChakraPropsDescription).toMatchSnapshot();
+    expect(withOtherPropsDescription).toMatchSnapshot();
+  });
+});

package/src/components/List/List.tsx

@@ -0,0 +1,156 @@
+import { As, Box, chakra, useStyleConfig } from "@chakra-ui/react";
+import * as React from "react";
+
+import Heading from "../Heading/Heading";
+
+export type ListTypes = "ol" | "ul" | "dl";
+interface DescriptionProps {
+  term: string;
+  description: string | JSX.Element;
+}
+export interface ListProps {
+  /** ClassName you can add in addition to 'list' */
+  className?: string;
+  /** ID that other components can cross reference for accessibility purposes */
+  id?: string;
+  /** Display the list in a row. */
+  inline?: boolean;
+  /** Data to render if children are not passed. For `listTypes` orderd `"ol"`
+   * and unordered `"ul"` `List` types, the data structure is an array of strings
+   * to renders as `li` items. For descroption `"dl"` `List` types, the data
+   * structure is an array of objects with `term` and `description` properties
+   * to render `dt` and `dd` elements, respectively.
+   */
+  listItems?: (string | JSX.Element | DescriptionProps)[];
+  /** Remove list styling. */
+  noStyling?: boolean;
+  /** An optional title that will appear over the list. This prop only applies
+   * to Description Lists. */
+  title?: string;
+  /** The type of list: "ol", "ul", or "dl". "ul" by default. */
+  type: ListTypes;
+}
+
+/**
+ * A component that renders list item `li` elements or description item `dt`
+ * and `dd` elements based on the `type` prop. Note that the `title` prop will
+ * only display for the `Description` list type.
+ */
+export const List = chakra((props: React.PropsWithChildren<ListProps>) => {
+  const {
+    children,
+    className,
+    id,
+    inline = false,
+    listItems,
+    noStyling = false,
+    title,
+    type = "ul",
+    ...rest
+  } = props;
+  const styles = useStyleConfig("List", { inline, noStyling, variant: type });
+  let listElement = null;
+
+  // Either li/dt/dd children elements must be passed or the `listItems`
+  // prop must be used.
+  if (children && listItems && listItems?.length > 0) {
+    console.warn(
+      "NYPL Reservoir List: Pass in either `<li>`, `<dt>`, or `<dd>` " +
+        "children or use the `listItems` data prop. Do not use both."
+    );
+    return null;
+  }
+  if (!children && !listItems) {
+    console.warn(
+      "NYPL Reservoir List: Pass in either `<li>` children or pass data in " +
+        "the `listItems` prop, not both."
+    );
+    return null;
+  }
+
+  /**
+   * This returns either the `children` elements passed to the `List` component
+   * first, otherwise it will check and render the data passed into the
+   * `listItems` props based on the `ListType` type. If it is of type unordered
+   * or ordered, it will return `li` elements. Otherwise, it will return a
+   * combination of `dt` and `dd` elements for the description type.
+   */
+  const listChildrenElms = (listType: ListTypes) => {
+    if (children) {
+      return children;
+    }
+    if (!listItems) {
+      return null;
+    }
+    if (listType === "ol" || listType === "ul") {
+      return listItems.map((item, i) => <li key={i}>{item}</li>);
+    } else if (listType === "dl") {
+      return (listItems as DescriptionProps[]).map((item, i) => [
+        <dt key={`${i}-term`}>{item.term}</dt>,
+        <dd key={`${i}-des`}>{item.description}</dd>,
+      ]);
+    }
+    return null;
+  };
+  /**
+   * Checks for `li` elements and consoles a warning if the
+   * children are different HTML elements.
+   */
+  const checkListChildrenError = (listType: ListTypes) => {
+    React.Children.map(children as JSX.Element, (child: React.ReactElement) => {
+      if (child && child?.type !== "li" && child?.props?.mdxType !== "li") {
+        console.warn(
+          `NYPL Reservoir List: Direct children of \`List\` (${listType}) must be \`<li>\`s.`
+        );
+      }
+    });
+  };
+  /**
+   * Checks for `dt` and `dd` elements and consoles a warning if the
+   * children are different HTML elements.
+   */
+  const checkDescriptionChildrenError = () => {
+    React.Children.map(children as JSX.Element, (child: React.ReactElement) => {
+      if (
+        child.type !== "dt" &&
+        child.type !== "dd" &&
+        child.type !== React.Fragment &&
+        child.props.mdxType !== "dt" &&
+        child.props.mdxType !== "dd" &&
+        child.props.mdxType !== React.Fragment
+      ) {
+        console.warn(
+          "NYPL Reservoir List: Direct children of `List` (description) must " +
+            "be `<dt>`s and `<dd>`s."
+        );
+      }
+    });
+  };
+
+  if (type === "ol" || type === "ul") {
+    checkListChildrenError(type);
+    listElement = (
+      <Box
+        as={type as As}
+        id={id}
+        className={className}
+        __css={styles}
+        {...rest}
+      >
+        {listChildrenElms(type)}
+      </Box>
+    );
+  } else if (type === "dl") {
+    checkDescriptionChildrenError();
+    listElement = (
+      <Box as="section" id={id} className={className} __css={styles} {...rest}>
+        {title && <Heading id={`${id}-heading`}>{title}</Heading>}
+        <dl>{listChildrenElms(type)}</dl>
+      </Box>
+    );
+  }
+
+  return listElement;
+});
+
+export default List;

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

@@ -0,0 +1,213 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`List Renders the UI snapshot correctly 1`] = `
+<ul
+  className="css-1xdhyk6"
+  id="unordered"
+>
+  <li>
+    Mahi-mahi
+  </li>
+  <li>
+    Golden trout
+  </li>
+  <li>
+    Rainbowfish
+  </li>
+  <li>
+    Suckerfish
+  </li>
+</ul>
+`;
+
+exports[`List Renders the UI snapshot correctly 2`] = `
+<ul
+  className="css-1xdhyk6"
+  id="ordered"
+>
+  <li>
+    Mahi-mahi
+  </li>
+  <li>
+    Golden trout
+  </li>
+  <li>
+    Rainbowfish
+  </li>
+  <li>
+    Suckerfish
+  </li>
+</ul>
+`;
+
+exports[`List Renders the UI snapshot correctly 3`] = `
+<ol
+  className="css-1xdhyk6"
+  id="unordered-no-styling"
+>
+  <li>
+    Mahi-mahi
+  </li>
+  <li>
+    Golden trout
+  </li>
+  <li>
+    Rainbowfish
+  </li>
+  <li>
+    Suckerfish
+  </li>
+</ol>
+`;
+
+exports[`List Renders the UI snapshot correctly 4`] = `
+<ol
+  className="css-1xdhyk6"
+  id="ordered-no-styling"
+>
+  <li>
+    Mahi-mahi
+  </li>
+  <li>
+    Golden trout
+  </li>
+  <li>
+    Rainbowfish
+  </li>
+  <li>
+    Suckerfish
+  </li>
+</ol>
+`;
+
+exports[`List Renders the UI snapshot correctly 5`] = `
+<section
+  className="css-1xdhyk6"
+  id="description"
+>
+  <h2
+    className="chakra-heading css-1xdhyk6"
+    id="description-heading"
+  >
+    Animal Crossing Fish
+  </h2>
+  <dl>
+    <dt>
+      Mahi-mahi
+    </dt>
+    <dd>
+      <p>
+        The mahi-mahi is an ocean fish known...
+      </p>
+    </dd>
+    <dt>
+      Golden trout
+    </dt>
+    <dd>
+      The golden trout is a beautifully colored fish...
+    </dd>
+  </dl>
+</section>
+`;
+
+exports[`List Renders the UI snapshot correctly 6`] = `
+<ul
+  className="css-kle7zy"
+  id="chakra"
+>
+  <li>
+    Mahi-mahi
+  </li>
+  <li>
+    Golden trout
+  </li>
+  <li>
+    Rainbowfish
+  </li>
+  <li>
+    Suckerfish
+  </li>
+</ul>
+`;
+
+exports[`List Renders the UI snapshot correctly 7`] = `
+<ul
+  className="css-1xdhyk6"
+  data-testid="other"
+  id="other"
+>
+  <li>
+    Mahi-mahi
+  </li>
+  <li>
+    Golden trout
+  </li>
+  <li>
+    Rainbowfish
+  </li>
+  <li>
+    Suckerfish
+  </li>
+</ul>
+`;
+
+exports[`List Renders the UI snapshot correctly 8`] = `
+<section
+  className="css-kle7zy"
+  id="chakra"
+>
+  <h2
+    className="chakra-heading css-1xdhyk6"
+    id="chakra-heading"
+  >
+    Animal Crossing Fish
+  </h2>
+  <dl>
+    <dt>
+      Mahi-mahi
+    </dt>
+    <dd>
+      <p>
+        The mahi-mahi is an ocean fish known...
+      </p>
+    </dd>
+    <dt>
+      Golden trout
+    </dt>
+    <dd>
+      The golden trout is a beautifully colored fish...
+    </dd>
+  </dl>
+</section>
+`;
+
+exports[`List Renders the UI snapshot correctly 9`] = `
+<section
+  className="css-1xdhyk6"
+  data-testid="other"
+  id="other"
+>
+  <h2
+    className="chakra-heading css-1xdhyk6"
+    id="other-heading"
+  >
+    Animal Crossing Fish
+  </h2>
+  <dl>
+    <dt>
+      Mahi-mahi
+    </dt>
+    <dd>
+      <p>
+        The mahi-mahi is an ocean fish known...
+      </p>
+    </dd>
+    <dt>
+      Golden trout
+    </dt>
+    <dd>
+      The golden trout is a beautifully colored fish...
+    </dd>
+  </dl>
+</section>
+`;