@nypl/design-system-react-components 0.25.0 → 0.25.4

package/src/components/List/List.stories.mdx

@@ -3,24 +3,17 @@ import {
   Story,
   Canvas,
   ArgsTable,
-  Preview,
   Description,
 } from "@storybook/addon-docs/blocks";
 import { withDesign } from "storybook-addon-designs";
-import Card from "../Card/Card";
+
 import Heading from "../Heading/Heading";
-import Icon from "../Icons/Icon";
-import { IconNames, IconRotationTypes } from "../Icons/IconTypes";
+import { HeadingLevels } from "../Heading/HeadingTypes";
 import Image from "../Image/Image";
 import Link from "../Link/Link";
 import { LinkTypes } from "../Link/LinkTypes";
 import List from "./List";
 import { ListTypes } from "./ListTypes";
-import {
-  animalCrossingDefinitions,
-  cardsList,
-  listRenderer,
-} from "./List.stories.tsx";
 import { getCategory } from "../../utils/componentCategories";
 
 <Meta
@@ -36,16 +29,15 @@ import { getCategory } from "../../utils/componentCategories";
     jest: ["List.test.tsx"],
   }}
   argTypes={{
-    blockName: { table: { disable: true } },
-    modifiers: { table: { disable: true } },
     children: { table: { disable: true } },
-    definitions: { table: { disable: true } },
-    itemGroups: { table: { disable: true } },
+    className: { table: { disable: true } },
+    id: { table: { disable: true } },
     listItems: { table: { disable: true } },
     type: {
       control: {
         type: "radio",
       },
+      options: Object.keys(ListTypes),
     },
   }}
 />
@@ -55,33 +47,119 @@ import { getCategory } from "../../utils/componentCategories";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.7.0`    |
-| Latest            | `0.23.2`   |
+| Latest            | `0.25.2`   |
 
 <Description of={List} />
 
-<Preview withToolbar>
+export const animalCrossingDefinitions = [
+  {
+    term: "Mahi-mahi",
+    definition:
+      'The mahi-mahi is an ocean fish known for its wide, somewhat-cute face. It can reach over six feet long. It is known by different names including "dolphinfish," even though it has no relation to dolphins. They live in only in warm, tropical waters...which perhaps explains the relaxed, happy look on their faces.',
+  },
+  {
+    term: "Golden trout",
+    definition:
+      "The golden trout is a beautifully colored fish that can only live in very clean waters. They are difficult to come across since they are found only in high mountain streams. As a side note, I find it much easier to appreciate fish that aren't such prima donnas about everything.",
+  },
+  {
+    term: "Rainbowfish",
+    definition:
+      'The rainbowfish is a tropical fish known for its metallic colors and beautiful fins. There are over 50 different species, each unique and pleasing color. I must say, it does make me wish for feathers of a more exciting hue than "underbaked brownie."',
+  },
+  {
+    term: "Suckerfish",
+    definition:
+      "The suckerfish is a curious fish that likes to attach itself with its sucker mouth to larger marine animals. The benefit to the suckerfish is that it gets to eat smaller parasites and dead skin off the host's body. Amusingly, some people have used suckerfish on cords to catch large turtles with the fish's own suction! I imagine this practice is the cause of some awkward conversations between fish and turtle, eh wot?",
+  },
+];
+export const itemGroups = [
+  "Art",
+  "Bushes",
+  "Clothing",
+  "DIY Recipes",
+  "Flowers",
+  "Fossils",
+  "Fruits",
+  "Furniture",
+  "Materials",
+  "NPC",
+  "Songs",
+  "Tools",
+  "Villagers",
+];
+export const definitions = [
+  {
+    term: "Balrogs",
+    definition:
+      'Demonic creatures of fire and shadow, Balrogs were fallen Maiar, loyal to the first Dark Lord, Morgoth. They participated in the wars of the First Age of Middle-earth but were mostly destroyed during the War of Wrath which ended the Age. By the Third Age, the only remaining Balrog was "Durin\'s Bane," the Balrog of Moria, killed by Gandalf.',
+  },
+  {
+    term: "Dwarves",
+    definition:
+      "The race of Dwarves preferred to live in mountains and caves, settling in places such as Erebor (the Lonely Mountain), the Iron Hills, the Blue Mountains, and Moria (Khazad-dûm) in the Misty Mountains. Aulë the Smith created Dwarves; he also invented the Dwarven language, known as Khuzdul. Dwarves mined and worked precious metals throughout the mountains of Middle-earth. The seven different groups of Dwarf-folk originated in the locations where the Seven Fathers of the Dwarves first awoke before the First Age.",
+  },
+  {
+    term: "Elves",
+    definition:
+      'The Elves, or Firstborn, were the first of Eru\'s Children to awaken. Born under the stars before the ascension of the Moon and the Sun, they retain a special love for light and an inner spirit endowed with unique gifts. They call themselves the Quendi, or "Speakers", for they were the first to utter words; and, even now, no race understands language and song like the Firstborn. Fair and fine featured, brilliant and proud, immortal and strong, tall and agile, they are the most blessed of the Free Peoples. They can see as well under moon or starlight as a man at the height of day. They cannot become sick or scarred, but if an Elf should die, from violence or losing the will to live from grief, their spirit goes to the halls of Mandos, and as they are bound to Arda and cannot leave until the world is broken and remade. Elven skill and agility is legendary: for instance, walking atop freshly fallen snow without leaving a trace of their passing. On a clear day they can see ten miles with perfect clarity and detail up to 100 miles. These gifts come at great cost, though: they are strongly bound to Fate (see Mandos) and hated by Morgoth. No other race has been blessed and cursed more than the Quendi.',
+  },
+  {
+    term: "Ents",
+    definition:
+      "Ents were an ancient race of tree-like creatures, having become like the trees that they shepherd. They were created by Yavanna and given life by Ilúvatar. By the Third Age, they were a dwindling race, having long ago lost their mates, the Entwives.",
+  },
+  {
+    term: "Hobbits",
+    definition:
+      'Hobbits are a race of Middle-earth, also known as "halflings" on account of their short stature, roughly half the size of men. They are characterized by curly hair on their heads and leathery feet that have furry insteps, for which they did not wear shoes. Many hobbits live in the Shire as well as Bree, and they once lived in the vales of the Anduin. They are fond of an unadventurous life of farming, eating, and socializing. There were three types of Hobbits: The Harfoots were the most numerous. The Stoors had an affinity for water, boats and swimming; the Fallohides were an adventurous people. The origin of hobbits is unclear, but of all the races they have the closest affinity to men, and in the Prologue to The Lord of the Rings Tolkien calls them relatives of men.',
+  },
+];
+
+<Canvas withToolbar>
   <Story
     name="List"
     args={{
       id: "nypl-list",
+      noStyling: false,
+      title: "Middle-Earth Peoples",
       type: ListTypes.Unordered,
-      title: "",
     }}
   >
-    {(args) => listRenderer(args)}}
+    {(args) => (
+      <List {...args} type={ListTypes[args.type]}>
+        {ListTypes[args.type] !== ListTypes.Definition
+          ? itemGroups.map((item, i) => <li key={i}>{item}</li>)
+          : definitions.map((item, i) => [
+              <dt key={`dt_${i}`}>{item.term}</dt>,
+              <dd key={`dd_${i}`}>{item.definition}</dd>,
+            ])}
+      </List>
+    )}
   </Story>
-</Preview>
+</Canvas>
 
 <ArgsTable story="List" />
 
 ## Definition List
 
-<Preview withToolbar>
+To render a definition list, pass in `ListTypes.Definition` to the `type` prop.
+The optional `title` prop will now render above the definition list element.
+This type of list renders `dt` and `dd` elements.
+
+```jsx
+<List type={ListTypes.Definition}>
+  <dt>Term</dt>
+  <dd>Definition</dd>
+</List>
+```
+
+<Canvas>
   <Story
     name="Definition List"
     args={{
       id: "nypl-list2",
-      type: ListTypes.Definition,
+      noStyling: false,
       title: "Middle-Earth Peoples",
     }}
     argTypes={{
@@ -95,39 +173,30 @@ import { getCategory } from "../../utils/componentCategories";
       },
     }}
   >
-    {(args) => listRenderer(args)}}
-  </Story>
-</Preview>
-
-## Ordered Card List
-
-<Preview withToolbar>
-  <Story
-    name="Ordered Card List"
-    args={{
-      id: "nypl-list3",
-    }}
-    argTypes={{
-      type: { table: { disable: true } },
-      title: { table: { disable: true } },
-    }}
-  >
-    {(args) => <List type={ListTypes.Ordered}>{cardsList}</List>}
+    {(args) => (
+      <List {...args} type={ListTypes.Definition}>
+        {definitions.map((item, i) => [
+          <dt key={`dt_${i}`}>{item.term}</dt>,
+          <dd key={`dd_${i}`}>{item.definition}</dd>,
+        ])}
+      </List>
+    )}
   </Story>
-</Preview>
+</Canvas>
 
 ## Definition List of Links
 
-<Preview withToolbar>
+An example with HTML elements inside of the `dd` elements.
+
+<Canvas>
   <Story
     name="Definition List of Links"
     args={{
-      type: ListTypes.Definition,
+      noStyling: false,
       title: "Details",
     }}
     argTypes={{
       type: { table: { disable: true } },
-      title: { table: { disable: true } },
     }}
     parameters={{
       design: {
@@ -138,7 +207,7 @@ import { getCategory } from "../../utils/componentCategories";
     }}
   >
     {(args) => (
-      <List title="Details" type={ListTypes.Definition}>
+      <List {...args} type={ListTypes.Definition}>
         <dt>Authors</dt>
         <dd>
           <a href="#">Chirwa, Ephraim Wadonda, author</a>
@@ -177,7 +246,7 @@ import { getCategory } from "../../utils/componentCategories";
       </List>
     )}
   </Story>
-</Preview>
+</Canvas>
 
 ## Lists with Data Props
 
@@ -185,6 +254,8 @@ If `li` or `dt`/`dd` elements cannot be passed as children to the `List` element
 an array with data can be passed into the `listItems` prop. Note: either
 children elements or the `listItems` prop should be passed but not both.
 
+### Unordered and Ordered
+
 For lists of type `ListTypes.Unordered` (ul) or `ListTypes.Ordered` (ol), `li`
 list item elements can be passed as children. If that's not possible but the
 data to render is stored as an array of strings, then that data array can be
@@ -204,6 +275,8 @@ const fishArray = ["Mahi-mahi", "Golden trout", "Rainbowfish", "Suckerfish"];
 <List type={ListTypes.Unordered} listItems={fishArray} />
 ```
 
+### Definition
+
 For lists of type `ListTypes.Definition` (dl), `dt` and `dd` elements can be
 passed as children. If that's not possible but the data to render is stored as
 an array of objects, then that data array can be passed into `listItems`. The
@@ -242,24 +315,24 @@ const fishDefinitions = [
   }
 ];
 <List
-  type={ListTypes.Definition}
-  title="Animal Crossing Fish"
   listItems={fishDefinitions}
+  title="Animal Crossing Fish"
+  type={ListTypes.Definition}
 />
 ```
 
-<Preview>
+<Canvas>
   <Story
     name="List with Data Props"
     args={{
-      type: ListTypes.Definition,
-      title: "Animal Crossing Fish",
       listItems: animalCrossingDefinitions,
+      noStyling: false,
+      title: "Animal Crossing Fish",
     }}
     argTypes={{
       type: { table: { disable: true } },
     }}
   >
-    {(args) => <List {...args} />}
+    {(args) => <List {...args} type={ListTypes.Definition} />}
   </Story>
-</Preview>
+</Canvas>

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

@@ -1,53 +1,77 @@
 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";
 import { ListTypes } from "./ListTypes";
 
-describe("Link Accessibility", () => {
-  it("passes axe accessibility test", async () => {
-    const { container } = render(
+const fishArray = ["Mahi-mahi", "Golden trout", "Rainbowfish", "Suckerfish"];
+const fishDefinitions = [
+  {
+    term: "Mahi-mahi",
+    definition: "The mahi-mahi is an ocean fish known...",
+  },
+  {
+    term: "Golden trout",
+    definition: "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={ListTypes.Unordered}>
         <li>Mahi-mahi</li>
         <li>Golden trout</li>
       </List>
     );
     expect(await axe(container)).toHaveNoViolations();
+
+    rerender(<List type={ListTypes.Unordered} listItems={fishArray} />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+  it("passes axe accessibility test for ordered list", async () => {
+    const { container, rerender } = render(
+      <List type={ListTypes.Ordered}>
+        <li>Mahi-mahi</li>
+        <li>Golden trout</li>
+      </List>
+    );
+    expect(await axe(container)).toHaveNoViolations();
+
+    rerender(<List type={ListTypes.Ordered} listItems={fishArray} />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+  it("passes axe accessibility test for definition list", async () => {
+    const { container } = render(
+      <List
+        type={ListTypes.Definition}
+        title="Animal Crossing Fish"
+        listItems={fishDefinitions}
+      />
+    );
+    expect(await axe(container)).toHaveNoViolations();
   });
 });
 
 describe("List", () => {
-  const fishArray = ["Mahi-mahi", "Golden trout", "Rainbowfish", "Suckerfish"];
-  const fishDefinitions = [
-    {
-      term: "Mahi-mahi",
-      definition: "The mahi-mahi is an ocean fish known...",
-    },
-    {
-      term: "Golden trout",
-      definition: "The golden trout is a beautifully colored fish...",
-    },
-  ];
-
   it("renders unordered list", () => {
-    const utils = render(
+    render(
       <List type={ListTypes.Unordered}>
         <li>Mahi-mahi</li>
         <li>Golden trout</li>
       </List>
     );
-    expect(utils.container.querySelector(".list")).toBeInTheDocument();
+
     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", () => {
-    const utils = render(
-      <List type={ListTypes.Unordered} listItems={fishArray} />
-    );
-    expect(utils.container.querySelector(".list")).toBeInTheDocument();
+    render(<List type={ListTypes.Unordered} listItems={fishArray} />);
+
     expect(screen.getAllByRole("listitem")).toHaveLength(4);
     expect(screen.getByText("Mahi-mahi")).toBeInTheDocument();
     expect(screen.getByText("Golden trout")).toBeInTheDocument();
@@ -56,23 +80,21 @@ describe("List", () => {
   });
 
   it("renders ordered list", () => {
-    const utils = render(
+    render(
       <List type={ListTypes.Ordered}>
         <li>Mahi-mahi</li>
         <li>Golden trout</li>
       </List>
     );
-    expect(utils.container.querySelector(".list")).toBeInTheDocument();
+
     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", () => {
-    const utils = render(
-      <List type={ListTypes.Ordered} listItems={fishArray} />
-    );
-    expect(utils.container.querySelector(".list")).toBeInTheDocument();
+    render(<List type={ListTypes.Ordered} listItems={fishArray} />);
+
     expect(screen.getAllByRole("listitem")).toHaveLength(4);
     expect(screen.getByText("Mahi-mahi")).toBeInTheDocument();
     expect(screen.getByText("Golden trout")).toBeInTheDocument();
@@ -105,50 +127,107 @@ describe("List", () => {
     expect(screen.getAllByRole("definition")).toHaveLength(2);
   });
 
-  it("throws an error when you pass an ordered or unordered list children that aren't <li>s", () => {
-    expect(() =>
-      render(
-        <List type={ListTypes.Ordered}>
-          <span>Mahi-mahi</span>
-          <span>Golden trout</span>
-          <span>Rainbowfish</span>
-        </List>
-      )
-    ).toThrowError("Direct children of `List` (ordered) should be `<li>`s");
+  it("consoles a warning when children and the `listItems` prop are both passed", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(
+      <List type={ListTypes.Ordered} listItems={fishArray}>
+        <li>Mahi-mahi</li>
+        <li>Golden trout</li>
+        <li>Rainbowfish</li>
+        <li>Suckerfish</li>
+      </List>
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "Pass in either `<li>`, `<dt>`, or `<dd>` children or use the `listItems` data prop, but don't use both."
+    );
   });
 
-  it("throws an error when you pass a definition list children that aren't `<dt>`s or `<dd>`s", () => {
-    expect(() =>
-      render(
-        <List type={ListTypes.Definition}>
-          <span>Mahi-mahi</span>
-          <span>Golden trout</span>
-          <span>Rainbowfish</span>
-        </List>
-      )
-    ).toThrowError(
-      "Direct children of `List` (definition) should be `<dt>`s or `<dd>`s"
+  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={ListTypes.Ordered}></List>);
+    expect(warn).toHaveBeenCalledWith(
+      "Either `<li>` children or the `listItems` prop must be used."
     );
   });
 
-  it("throws an error when no children are passed or the `listItems` prop is not passed", () => {
-    expect(() => render(<List type={ListTypes.Ordered}></List>)).toThrowError(
-      "Either `<li>` children or the `listItems` prop must be used."
+  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={ListTypes.Ordered}>
+        <span>Mahi-mahi</span>
+        <span>Golden trout</span>
+        <span>Rainbowfish</span>
+      </List>
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "Direct children of `List` (ol) should be `<li>`s."
     );
   });
 
-  it("throws an error when children and the `listItems` prop are both passed", () => {
-    expect(() =>
-      render(
-        <List type={ListTypes.Ordered} listItems={fishArray}>
-          <li>Mahi-mahi</li>
-          <li>Golden trout</li>
-          <li>Rainbowfish</li>
-          <li>Suckerfish</li>
-        </List>
-      )
-    ).toThrowError(
-      "Pass in either `<li>` children or use the `listItems` data prop, don't use both."
+  it("consoles a warning when you pass a definition list children that aren't `<dt>`s or `<dd>`s", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(
+      <List type={ListTypes.Definition}>
+        <span>Mahi-mahi</span>
+        <span>Golden trout</span>
+        <span>Rainbowfish</span>
+      </List>
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "Direct children of `List` (definition) should be `<dt>`s and `<dd>`s."
     );
   });
+
+  it("Renders the UI snapshot correctly", () => {
+    const unordered = renderer
+      .create(
+        <List id="unordered" type={ListTypes.Unordered} listItems={fishArray} />
+      )
+      .toJSON();
+    const unorderedNoStyling = renderer
+      .create(
+        <List
+          id="ordered"
+          type={ListTypes.Unordered}
+          listItems={fishArray}
+          noStyling
+        />
+      )
+      .toJSON();
+    const ordered = renderer
+      .create(
+        <List
+          id="unordered-no-styling"
+          type={ListTypes.Ordered}
+          listItems={fishArray}
+        />
+      )
+      .toJSON();
+    const orderedNoStyling = renderer
+      .create(
+        <List
+          id="ordered-no-styling"
+          type={ListTypes.Ordered}
+          listItems={fishArray}
+          noStyling
+        />
+      )
+      .toJSON();
+    const definition = renderer
+      .create(
+        <List
+          id="definition"
+          type={ListTypes.Definition}
+          title="Animal Crossing Fish"
+          listItems={fishDefinitions}
+        />
+      )
+      .toJSON();
+
+    expect(unordered).toMatchSnapshot();
+    expect(unorderedNoStyling).toMatchSnapshot();
+    expect(ordered).toMatchSnapshot();
+    expect(orderedNoStyling).toMatchSnapshot();
+    expect(definition).toMatchSnapshot();
+  });
 });