@nypl/design-system-react-components 0.25.13 → 0.26.0

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

@@ -51,19 +51,30 @@ export const enumValues = getStorybookEnumValues(ListTypes, "ListTypes");
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.7.0`    |
-| Latest            | `0.25.13`  |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Description List](#description-list)
+- [Description List of Links](#description-list-of-links)
+- [Lists with Data Props](#lists-with-data-props)
+
+## Overview
 
 <Description of={List} />
 
-export const animalCrossingDefinitions = [
+export const animalCrossingDescriptions = [
   {
     term: "Mahi-mahi",
-    definition:
+    description:
       '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: (
+    description: (
       <p>
         The golden trout is a <b>beautifully</b> colored fish that can only live
         in very clean waters. They are difficult to come across since they are
@@ -75,12 +86,12 @@ export const animalCrossingDefinitions = [
   },
   {
     term: "Rainbowfish",
-    definition:
+    description:
       '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: (
+    description: (
       <p>
         The{" "}
         <Link href="https://animalcrossing.fandom.com/wiki/Suckerfish">
@@ -111,30 +122,30 @@ export const itemGroups = [
   "Tools",
   "Villagers",
 ];
-export const definitions = [
+export const descriptions = [
   {
     term: "Balrogs",
-    definition:
+    description:
       '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:
+    description:
       "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:
+    description:
       '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:
+    description:
       "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:
+    description:
       '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.',
   },
 ];
@@ -155,11 +166,11 @@ export const definitions = [
   >
     {(args) => (
       <List {...args} type={enumValues.getValue(args.type)}>
-        {args.type !== "ListTypes.Definition"
+        {args.type !== "ListTypes.Description"
           ? itemGroups.map((item, i) => <li key={i}>{item}</li>)
-          : definitions.map((item, i) => [
+          : descriptions.map((item, i) => [
               <dt key={`dt_${i}`}>{item.term}</dt>,
-              <dd key={`dd_${i}`}>{item.definition}</dd>,
+              <dd key={`dd_${i}`}>{item.description}</dd>,
             ])}
       </List>
     )}
@@ -168,22 +179,46 @@ export const definitions = [
 
 <ArgsTable story="List with Controls" />
 
-## Definition List
+## Accessibility
+
+Internally, the `List` component implements native HTML markup for unordered,
+ordered, and description lists. This includes `ul`, `ol`, and `dl` elements.
+When data is passed into the `listItems` data prop, the appropriate children
+HTML elements are used. This includes `li` for unorder and ordered lists, and
+`dt` and `dd` elements for description lists.
+
+The description type for the `List` component is wrapped in a `section` element
+with an `h2` header. Keep that in mind when ordering headings on the page.
+
+Resources:
+
+- [W3C WAI Content Structure](https://www.w3.org/WAI/tutorials/page-structure/content/)
+- [Deque University Appropriate Semantic Markup for Lists](https://dequeuniversity.com/tips/list-markup)
+
+## Description List
+
+_Note: This element is officially called the "Description List" element in HTML5.
+Before HTML5, it was called the "Definition List" element and some online resources
+may still use this name. In the Reservoir Design System, we will use the
+"Description List" name._
+
+- [W3C Using description lists](https://www.w3.org/WAI/WCAG21/Techniques/html/H40.html)
+- [MDN dl: The Description List element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl)
 
-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.
+To render a description list, pass in `ListTypes.Description` to the `type` prop.
+The optional `title` prop will now render above the description list element.
 This type of list renders `dt` and `dd` elements.
 
 ```jsx
-<List type={ListTypes.Definition}>
+<List type={ListTypes.Description}>
   <dt>Term</dt>
-  <dd>Definition</dd>
+  <dd>Description</dd>
 </List>
 ```
 
 <Canvas>
   <Story
-    name="Definition List"
+    name="Description List"
     args={{
       id: "nypl-list2",
       noStyling: false,
@@ -202,23 +237,23 @@ This type of list renders `dt` and `dd` elements.
     }}
   >
     {(args) => (
-      <List {...args} type={ListTypes.Definition}>
-        {definitions.map((item, i) => [
+      <List {...args} type={ListTypes.Description}>
+        {descriptions.map((item, i) => [
           <dt key={`dt_${i}`}>{item.term}</dt>,
-          <dd key={`dd_${i}`}>{item.definition}</dd>,
+          <dd key={`dd_${i}`}>{item.description}</dd>,
         ])}
       </List>
     )}
   </Story>
 </Canvas>
 
-## Definition List of Links
+## Description List of Links
 
 An example with HTML elements inside of the `dd` elements.
 
 <Canvas>
   <Story
-    name="Definition List of Links"
+    name="Description List of Links"
     args={{
       noStyling: false,
       title: "Details",
@@ -236,7 +271,7 @@ An example with HTML elements inside of the `dd` elements.
     }}
   >
     {(args) => (
-      <List {...args} type={ListTypes.Definition}>
+      <List {...args} type={ListTypes.Description}>
         <dt>Authors</dt>
         <dd>
           <a href="#">Chirwa, Ephraim Wadonda, author</a>
@@ -304,16 +339,16 @@ const fishArray = ["Mahi-mahi", "Golden trout", "Rainbowfish", "Suckerfish"];
 <List type={ListTypes.Unordered} listItems={fishArray} />
 ```
 
-### Definition
+### Description
 
-For lists of type `ListTypes.Definition` (dl), `dt` and `dd` elements can be
+For lists of type `ListTypes.Description` (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
-object must have two keys, `term` and `definition`.
+object must have two keys, `term` and `description`.
 
 ```jsx
 // With `dt`/`dd` elements
-<List type={ListTypes.Definition} title="Animal Corssing Fish">
+<List type={ListTypes.Description} title="Animal Crossing Fish">
   <dt>Mahi-mahi</dt>
   <dd>The mahi-mahi is an ocean fish known...</dd>
   <dt>Golden trout</dt>
@@ -325,28 +360,28 @@ object must have two keys, `term` and `definition`.
 </List>
 
 // With `itemList` data prop
-const fishDefinitions = [
+const fishDescriptions = [
   {
     term: "Mahi-mahi",
-    definition: "The mahi-mahi is an ocean fish known..."
+    description: "The mahi-mahi is an ocean fish known..."
   },
   {
     term: "Golden trout",
-    definition: "The golden trout is a beautifully colored fish..."
+    description: "The golden trout is a beautifully colored fish..."
   },
   {
     term: "Rainbowfish",
-    definition: "The rainbowfish is a tropical fish known..."
+    description: "The rainbowfish is a tropical fish known..."
   },
   {
     term: "Suckerfish"
-    definition: "he suckerfish is a curious fish that..."
+    description: "he suckerfish is a curious fish that..."
   }
 ];
 <List
-  listItems={fishDefinitions}
+  listItems={fishDescriptions}
   title="Animal Crossing Fish"
-  type={ListTypes.Definition}
+  type={ListTypes.Description}
 />
 ```
 
@@ -354,7 +389,7 @@ const fishDefinitions = [
   <Story
     name="List with Data Props"
     args={{
-      listItems: animalCrossingDefinitions,
+      listItems: animalCrossingDescriptions,
       noStyling: false,
       title: "Animal Crossing Fish",
     }}
@@ -364,6 +399,6 @@ const fishDefinitions = [
       type: { control: false },
     }}
   >
-    {(args) => <List {...args} type={ListTypes.Definition} />}
+    {(args) => <List {...args} type={ListTypes.Description} />}
   </Story>
 </Canvas>

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

@@ -7,14 +7,14 @@ import List from "./List";
 import { ListTypes } from "./ListTypes";
 
 const fishArray = ["Mahi-mahi", "Golden trout", "Rainbowfish", "Suckerfish"];
-const fishDefinitions = [
+const fishDescriptions = [
   {
     term: "Mahi-mahi",
-    definition: <p>The mahi-mahi is an ocean fish known...</p>,
+    description: <p>The mahi-mahi is an ocean fish known...</p>,
   },
   {
     term: "Golden trout",
-    definition: "The golden trout is a beautifully colored fish...",
+    description: "The golden trout is a beautifully colored fish...",
   },
 ];
 
@@ -43,12 +43,12 @@ describe("List Accessibility", () => {
     rerender(<List type={ListTypes.Ordered} listItems={fishArray} />);
     expect(await axe(container)).toHaveNoViolations();
   });
-  it("passes axe accessibility test for definition list", async () => {
+  it("passes axe accessibility test for description list", async () => {
     const { container } = render(
       <List
-        type={ListTypes.Definition}
+        type={ListTypes.Description}
         title="Animal Crossing Fish"
-        listItems={fishDefinitions}
+        listItems={fishDescriptions}
       />
     );
     expect(await axe(container)).toHaveNoViolations();
@@ -102,9 +102,9 @@ describe("List", () => {
     expect(screen.getByText("Suckerfish")).toBeInTheDocument();
   });
 
-  it("returns definition list", () => {
+  it("returns description list", () => {
     render(
-      <List type={ListTypes.Definition}>
+      <List type={ListTypes.Description}>
         <dt>Mahi-mahi</dt>
         <dd>The mahi-mahi is an ocean fish known...</dd>
       </List>
@@ -116,12 +116,12 @@ describe("List", () => {
     ).toBeInTheDocument();
   });
 
-  it("returns definition list with the `listItems` prop", () => {
+  it("returns description list with the `listItems` prop", () => {
     render(
       <List
-        type={ListTypes.Definition}
+        type={ListTypes.Description}
         title="Animal Crossing Fish"
-        listItems={fishDefinitions}
+        listItems={fishDescriptions}
       />
     );
     expect(screen.getAllByRole("definition")).toHaveLength(2);
@@ -166,17 +166,17 @@ describe("List", () => {
     );
   });
 
-  it("consoles a warning when you pass a definition list children that aren't `<dt>`s or `<dd>`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={ListTypes.Definition}>
+      <List type={ListTypes.Description}>
         <span>Mahi-mahi</span>
         <span>Golden trout</span>
         <span>Rainbowfish</span>
       </List>
     );
     expect(warn).toHaveBeenCalledWith(
-      "NYPL Reservoir List: Direct children of `List` (definition) must be " +
+      "NYPL Reservoir List: Direct children of `List` (description) must be " +
         "`<dt>`s and `<dd>`s."
     );
   });
@@ -216,13 +216,57 @@ describe("List", () => {
         />
       )
       .toJSON();
-    const definition = renderer
+    const description = renderer
       .create(
         <List
-          id="definition"
-          type={ListTypes.Definition}
+          id="description"
+          type={ListTypes.Description}
           title="Animal Crossing Fish"
-          listItems={fishDefinitions}
+          listItems={fishDescriptions}
+        />
+      )
+      .toJSON();
+    const withChakraPropsUnordered = renderer
+      .create(
+        <List
+          id="chakra"
+          type={ListTypes.Unordered}
+          listItems={fishArray}
+          p="20px"
+          color="ui.error.primary"
+        />
+      )
+      .toJSON();
+    const withOtherPropsUnordered = renderer
+      .create(
+        <List
+          id="other"
+          type={ListTypes.Unordered}
+          listItems={fishArray}
+          data-testid="other"
+        />
+      )
+      .toJSON();
+    const withChakraPropsDescription = renderer
+      .create(
+        <List
+          id="chakra"
+          type={ListTypes.Description}
+          title="Animal Crossing Fish"
+          listItems={fishDescriptions}
+          p="20px"
+          color="ui.error.primary"
+        />
+      )
+      .toJSON();
+    const withOtherPropsDescription = renderer
+      .create(
+        <List
+          id="other"
+          type={ListTypes.Description}
+          title="Animal Crossing Fish"
+          listItems={fishDescriptions}
+          data-testid="other"
         />
       )
       .toJSON();
@@ -231,6 +275,10 @@ describe("List", () => {
     expect(unorderedNoStyling).toMatchSnapshot();
     expect(ordered).toMatchSnapshot();
     expect(orderedNoStyling).toMatchSnapshot();
-    expect(definition).toMatchSnapshot();
+    expect(description).toMatchSnapshot();
+    expect(withChakraPropsUnordered).toMatchSnapshot();
+    expect(withOtherPropsUnordered).toMatchSnapshot();
+    expect(withChakraPropsDescription).toMatchSnapshot();
+    expect(withOtherPropsDescription).toMatchSnapshot();
   });
 });

package/src/components/List/List.tsx

@@ -1,14 +1,12 @@
+import { As, Box, chakra, useStyleConfig } from "@chakra-ui/react";
 import * as React from "react";
-import { As, Box, useStyleConfig } from "@chakra-ui/react";
 
 import { ListTypes } from "./ListTypes";
 import Heading from "../Heading/Heading";
 import { HeadingLevels } from "../Heading/HeadingTypes";
-import generateUUID from "../../helpers/generateUUID";
-
-interface DefinitionProps {
+interface DescriptionProps {
   term: string;
-  definition: string | JSX.Element;
+  description: string | JSX.Element;
 }
 export interface ListProps {
   /** Optionally pass in additional Chakra-based styles. */
@@ -21,36 +19,37 @@ export interface ListProps {
   inline?: boolean;
   /** Data to render if children are not passed. For `ListTypes.Ordered` and
    * `ListTypes.Unordered` `List` types, the data structure is an array of
-   * strings to renders as `li` items. For `ListTypes.Definition` `List` types,
-   * the data structure is an array of objects with `term` and `definition`
+   * strings to renders as `li` items. For `ListTypes.Description` `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 | DefinitionProps)[];
+  listItems?: (string | JSX.Element | DescriptionProps)[];
   /** Remove list styling. */
   noStyling?: boolean;
   /** An optional title that will appear over the list. This prop only applies
-   * to Definition Lists. */
+   * to Description Lists. */
   title?: string;
-  /** The type of list: Ordered, Unordered, or Definition. Unordered by default. */
+  /** The type of list: Ordered, Unordered, or Description. Unordered by default. */
   type: ListTypes;
 }
 
 /**
- * A component that renders list item `li` elements or definition item `dt`
+ * 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 `Definition` list type.
+ * only display for the `Description` list type.
  */
-export default function List(props: React.PropsWithChildren<ListProps>) {
+export const List = chakra((props: React.PropsWithChildren<ListProps>) => {
   const {
     additionalStyles = {},
     children,
     className,
-    id = generateUUID(),
+    id,
     inline = false,
     listItems,
     noStyling = false,
     title,
     type = ListTypes.Unordered,
+    ...rest
   } = props;
   const styles = useStyleConfig("List", { inline, noStyling, variant: type });
   const finalStyles = { ...styles, ...additionalStyles };
@@ -78,7 +77,7 @@ export default function List(props: React.PropsWithChildren<ListProps>) {
    * 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 "Definition" type.
+   * combination of `dt` and `dd` elements for the "Description" type.
    */
   const listChildrenElms = (listType: ListTypes) => {
     if (children) {
@@ -86,10 +85,10 @@ export default function List(props: React.PropsWithChildren<ListProps>) {
     }
     if (listType === ListTypes.Ordered || listType === ListTypes.Unordered) {
       return listItems.map((item, i) => <li key={i}>{item}</li>);
-    } else if (listType === ListTypes.Definition) {
-      return (listItems as DefinitionProps[]).map((item, i) => [
+    } else if (listType === ListTypes.Description) {
+      return (listItems as DescriptionProps[]).map((item, i) => [
         <dt key={`${i}-term`}>{item.term}</dt>,
-        <dd key={`${i}-def`}>{item.definition}</dd>,
+        <dd key={`${i}-des`}>{item.description}</dd>,
       ]);
     }
     return null;
@@ -111,7 +110,7 @@ export default function List(props: React.PropsWithChildren<ListProps>) {
    * Checks for `dt` and `dd` elements and consoles a warning if the
    * children are different HTML elements.
    */
-  const checkDefinitionChildrenError = () => {
+  const checkDescriptionChildrenError = () => {
     React.Children.map(children, function (child: React.ReactElement) {
       if (
         child.type !== "dt" &&
@@ -122,7 +121,7 @@ export default function List(props: React.PropsWithChildren<ListProps>) {
         child.props.mdxType !== React.Fragment
       ) {
         console.warn(
-          "NYPL Reservoir List: Direct children of `List` (definition) must " +
+          "NYPL Reservoir List: Direct children of `List` (description) must " +
             "be `<dt>`s and `<dd>`s."
         );
       }
@@ -132,14 +131,26 @@ export default function List(props: React.PropsWithChildren<ListProps>) {
   if (type === ListTypes.Ordered || type === ListTypes.Unordered) {
     checkListChildrenError(type);
     listElement = (
-      <Box as={type as As} id={id} className={className} __css={finalStyles}>
+      <Box
+        as={type as As}
+        id={id}
+        className={className}
+        __css={finalStyles}
+        {...rest}
+      >
         {listChildrenElms(type)}
       </Box>
     );
-  } else if (type === ListTypes.Definition) {
-    checkDefinitionChildrenError();
+  } else if (type === ListTypes.Description) {
+    checkDescriptionChildrenError();
     listElement = (
-      <Box as="section" id={id} className={className} __css={finalStyles}>
+      <Box
+        as="section"
+        id={id}
+        className={className}
+        __css={finalStyles}
+        {...rest}
+      >
         {title && (
           <Heading id={`${id}-heading`} level={HeadingLevels.Two}>
             {title}
@@ -151,4 +162,6 @@ export default function List(props: React.PropsWithChildren<ListProps>) {
   }
 
   return listElement;
-}
+});
+
+export default List;

package/src/components/List/ListTypes.tsx

@@ -1,5 +1,5 @@
 export enum ListTypes {
   Ordered = "ol",
   Unordered = "ul",
-  Definition = "dl",
+  Description = "dl",
 }