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

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

@@ -2,30 +2,43 @@
 
 exports[`HorizontalRule renders the UI snapshot correctly 1`] = `
 <hr
-  className="css-1bhbd2a"
+  className="css-mvtkpx"
 />
 `;
 
 exports[`HorizontalRule renders the UI snapshot correctly 2`] = `
 <hr
-  className="css-154goob"
+  className="css-j99tgf"
 />
 `;
 
 exports[`HorizontalRule renders the UI snapshot correctly 3`] = `
 <hr
-  className="css-gj8znx"
+  className="css-21sffo"
 />
 `;
 
 exports[`HorizontalRule renders the UI snapshot correctly 4`] = `
 <hr
-  className="css-1bhbd2a"
+  className="css-mvtkpx"
 />
 `;
 
 exports[`HorizontalRule renders the UI snapshot correctly 5`] = `
 <hr
-  className="css-1bhbd2a"
+  className="css-mvtkpx"
+/>
+`;
+
+exports[`HorizontalRule renders the UI snapshot correctly 6`] = `
+<hr
+  className="css-1pg2j4r"
+/>
+`;
+
+exports[`HorizontalRule renders the UI snapshot correctly 7`] = `
+<hr
+  className="css-mvtkpx"
+  data-testid="props"
 />
 `;

package/src/components/Icons/Icon.stories.mdx

@@ -7,6 +7,8 @@ import {
 } from "@storybook/addon-docs";
 import { withDesign } from "storybook-addon-designs";
 
+import Heading from "../Heading/Heading";
+import { HeadingLevels } from "../Heading/HeadingTypes";
 import Icon from "./Icon";
 import {
   IconAlign,
@@ -89,10 +91,25 @@ export const rotationEnumValues = getStorybookEnumValues(
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.0.4`    |
-| Latest            | `0.25.11`  |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Rotation Types](#rotation-types)
+- [IconColors Types](#icon-colors-types)
+- [IconSizes Types](#icon-sizes-types)
+- [All Display Icons](#all-display-icons)
+- [Custom Icons](#custom-icons)
+
+## Overview
 
 <Description of={Icon} />
 
+## Component Props
+
 <Canvas withToolbar>
   <Story
     name="Icon with Controls"
@@ -105,7 +122,7 @@ export const rotationEnumValues = getStorybookEnumValues(
       iconRotation: "IconRotationTypes.Rotate0",
       id: "icon-id",
       name: "IconNames.Check",
-      size: "IconSizes.ExtraLarge",
+      size: "IconSizes.ExtraExtraLarge",
       title: undefined,
       type: IconTypes.Default,
     }}
@@ -128,7 +145,7 @@ export const rotationEnumValues = getStorybookEnumValues(
 export const iconRow = (icon, iconType = IconNames, opts = {}) => {
   // We'll use this setup function to render all the icons in a list item.
   // Some icons display better with a dark background.
-  const styles = { padding: "1rem" };
+  const styles = { display: "block" };
   const {
     size = IconSizes.Large,
     iconRotation = IconRotationTypes.Rotate0,
@@ -138,6 +155,7 @@ export const iconRow = (icon, iconType = IconNames, opts = {}) => {
   let key = icon;
   if (icon.indexOf("Negative") !== -1 || color.indexOf("white") !== -1) {
     styles.backgroundColor = "#000";
+    styles.padding = "1rem";
   }
   // The following is just to fix duplicate React key issues.
   if (iconRotation !== IconRotationTypes.Rotate0) {
@@ -150,7 +168,11 @@ export const iconRow = (icon, iconType = IconNames, opts = {}) => {
     key += `-${size}`;
   }
   return (
-    <li key={key} style={{ marginBottom: "var(--nypl-space-s)" }}>
+    <li
+      key={key}
+      style={{ marginBottom: "var(--nypl-space-l)", textAlign: "center" }}
+    >
+      <Heading level={HeadingLevels.Four}>{displayValue}</Heading>
       <span style={styles}>
         <Icon
           name={iconType[icon]}
@@ -159,7 +181,6 @@ export const iconRow = (icon, iconType = IconNames, opts = {}) => {
           color={color}
         />
       </span>
-      {displayValue}
     </li>
   );
 };
@@ -168,30 +189,36 @@ export const rotations = [];
 export const colors = [];
 export const sizes = [];
 for (const icon in IconNames) {
-  icons.push(iconRow(icon, IconNames, { displayValue: `IconNames.${icon}` }));
+  icons.push(
+    iconRow(icon, IconNames, {
+      displayValue: `IconNames.${icon}`,
+      size: IconSizes.ExtraExtraLarge,
+    })
+  );
 }
 for (const iconRotation in IconRotationTypes) {
   rotations.push(
     iconRow("Arrow", IconNames, {
-      size: IconSizes.Large,
-      iconRotation: IconRotationTypes[iconRotation],
       displayValue: `IconRotationTypes.${iconRotation}`,
+      iconRotation: IconRotationTypes[iconRotation],
+      size: IconSizes.ExtraExtraLarge,
     })
   );
 }
 for (const iconColor in IconColors) {
   colors.push(
-    iconRow("Download", IconNames, {
+    iconRow("ErrorFilled", IconNames, {
       color: IconColors[iconColor],
       displayValue: `IconColors.${iconColor}`,
+      size: IconSizes.ExtraExtraLarge,
     })
   );
 }
 for (const iconSize in IconSizes) {
   sizes.push(
-    iconRow("Arrow", IconNames, {
-      size: IconSizes[iconSize],
+    iconRow("ActionCheckCircle", IconNames, {
       displayValue: `IconSizes.${iconSize}`,
+      size: IconSizes[iconSize],
     })
   );
 }
@@ -202,11 +229,21 @@ export const allIconsType = (list) => (
 
 ## Accessibility
 
-For accessibility purposes, every DS `Icon` will render the `svg` element with
-its icon name in the `title` element. The default text in the `title` element
-is the icon's code name. Pass in better descriptive text in the `title` prop
-when using the `Icon` component in your application. This will give screenreaders
-a better descriptive title for the `svg` graphic.
+For accessibility purposes, every Reservoir Design System (DS) `Icon` will 
+render the `svg` element with its icon name in the `title` element. The default 
+text in the `title` element is the icon's code name. Pass in better descriptive 
+text in the `title` prop when using the `Icon` component in your application. 
+This will give screenreaders a better descriptive title for the `svg` graphic.
+
+`Icon`s are decorative by default. This means that they are presentational and
+screenreaders will not read them because the `aria-hidden` attribute is set to
+`true`.
+
+Resources:
+
+- [W3C Design System SVG Icons](https://design-system.w3.org/styles/svg-icons.html)
+- [CSS-Tricks Accessible SVG Icons](https://css-tricks.com/accessible-svg-icons/)
+- [Chakra UI Icon](https://chakra-ui.com/docs/components/media-and-icons/icon)
 
 ## Rotation Types
 
@@ -214,13 +251,20 @@ Passing an `iconRotation` prop with a value from `IconRotationTypes` allows
 the icon to be rotated when it is rendered. The `IconRotationTypes` enum
 can be found in `src/components/Icons/IconTypes.tsx`.
 
+Note: All of the examples below have been rendered with the `size` prop set to
+`IconSizes.ExtraExtraLarge`.
+
 ```jsx
 // Example
-<Icon name={IconNames.Arrow} iconRotation={IconRotationTypes.Rotate180} />
+<Icon
+  iconRotation={IconRotationTypes.Rotate180}
+  name={IconNames.Arrow}
+  size={IconSizes.ExtraExtraLarge}
+/>
 ```
 
 <Canvas>
-  <Story name="Rotation Types">{allIconsType(rotations)}</Story>
+  <Story name="Icon Rotation">{allIconsType(rotations)}</Story>
 </Canvas>
 
 ## IconColors Types
@@ -228,13 +272,20 @@ can be found in `src/components/Icons/IconTypes.tsx`.
 Update an SVG icon by passing a `color` prop with a value from `IconColors`.
 The `IconColors` enum can be found in `src/components/Icons/IconTypes.tsx`.
 
+Note: All of the examples below have been rendered with the `size` prop set to
+`IconSizes.ExtraExtraLarge`.
+
 ```jsx
 // Example
-<Icon name={IconNames.Speaker_notes} color={IconColors.BrandPrimary} />
+<Icon
+  color={IconColors.BrandPrimary}
+  name={IconNames.ErrorFilled}
+  size={IconSizes.ExtraExtraLarge}
+/>
 ```
 
 <Canvas>
-  <Story name="Color Types">{allIconsType(colors)}</Story>
+  <Story name="Icon Colors">{allIconsType(colors)}</Story>
 </Canvas>
 
 ## IconSizes Types
@@ -242,13 +293,16 @@ The `IconColors` enum can be found in `src/components/Icons/IconTypes.tsx`.
 Update an SVG icon by passing a `size` prop with a value from `IconSizes`.
 The `IconSizes` enum can be found in`src/components/Icons/IconTypes.tsx`.
 
+Note: `IconSizes.Default` sets the width to `100%` and the rendered icon will
+expand to fill the full width of the parent element.
+
 ```jsx
 // Example
-<Icon name={IconNames.Clock} size={IconSizes.ExtraExtraLarge} />
+<Icon name={IconNames.ActionCheckCircle} size={IconSizes.ExtraExtraLarge} />
 ```
 
 <Canvas>
-  <Story name="Sizes Types">{allIconsType(sizes)}</Story>
+  <Story name="Icon Sizes">{allIconsType(sizes)}</Story>
 </Canvas>
 
 ## All Display Icons
@@ -256,8 +310,11 @@ The `IconSizes` enum can be found in`src/components/Icons/IconTypes.tsx`.
 The following icons are for generic purposes. All the available icon names can
 be found in the `IconNames` enum in `src/components/Icons/IconTypes.tsx`.
 
+Note: All of the examples below have been rendered with the `size` prop set to
+`IconSizes.ExtraExtraLarge`.
+
 <Canvas withToolbar>
-  <Story name="All Display Icons">{allIconsType(icons)}</Story>
+  <Story name="All Icons">{allIconsType(icons)}</Story>
 </Canvas>
 
 ## Custom Icons

package/src/components/Icons/Icon.test.tsx

@@ -1,6 +1,7 @@
 import * as React from "react";
 import { render } from "@testing-library/react";
 import { axe } from "jest-axe";
+import renderer from "react-test-renderer";
 
 import Icon from "./Icon";
 import { IconNames } from "./IconTypes";
@@ -27,7 +28,8 @@ describe("Icon", () => {
       </Icon>
     );
     expect(warn).toHaveBeenCalledWith(
-      "Icon accepts either a `name` prop or an `svg` element child, not both."
+      "NYPL Reservoir Icon: Pass in either a `name` prop or an `svg` element " +
+        "child. Do not pass both."
     );
   });
 
@@ -35,7 +37,17 @@ describe("Icon", () => {
     const warn = jest.spyOn(console, "warn");
     render(<Icon />);
     expect(warn).toHaveBeenCalledWith(
-      "Icon: Pass an icon `name` prop or an SVG child to ensure an icon appears."
+      "NYPL Reservoir Icon: Pass an icon `name` prop or an SVG child to " +
+        "ensure an icon appears."
+    );
+  });
+
+  it("consoles a warning if name is not passed and a child is but it's not an SVG element", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(<Icon>Not an SVG</Icon>);
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir Icon: An `svg` element must be passed to the `Icon` " +
+        "component as its child."
     );
   });
 
@@ -76,4 +88,41 @@ describe("Icon", () => {
     );
     expect(container.querySelector("svg")).toBeInTheDocument();
   });
+
+  it("renders the UI snapshot correctly", () => {
+    const basic = renderer
+      .create(<Icon id="basic" name={IconNames.Download} />)
+      .toJSON();
+    const customIcon = renderer
+      .create(
+        <Icon id="customIcon">
+          <svg viewBox="0 0 24 14" xmlns="http://www.w3.org/2000/svg">
+            <path
+              fillRule="evenodd"
+              clipRule="evenodd"
+              d="M10.526 12.871L.263 1.676 1.737.324 12 11.52 22.263.324l1.474 1.352L13.474 12.87a2 2 0 01-2.948 0z"
+            />
+          </svg>
+        </Icon>
+      )
+      .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <Icon
+          id="chakra"
+          name={IconNames.Download}
+          p="20px"
+          color="ui.error.primary"
+        />
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(<Icon id="props" name={IconNames.Download} data-testid="props" />)
+      .toJSON();
+
+    expect(basic).toMatchSnapshot();
+    expect(customIcon).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
+  });
 });

package/src/components/Icons/Icon.tsx

@@ -1,7 +1,11 @@
+import {
+  Icon as ChakraIcon,
+  Box,
+  chakra,
+  useStyleConfig,
+} from "@chakra-ui/react";
 import * as React from "react";
-import { Icon as ChakraIcon, Box, useStyleConfig } from "@chakra-ui/react";
 
-import generateUUID from "../../helpers/generateUUID";
 import {
   IconAlign,
   IconColors,
@@ -43,77 +47,95 @@ export interface IconProps {
 /**
  * Renders SVG-based icons.
  */
-export default function Icon(props: React.PropsWithChildren<IconProps>) {
-  const {
-    additionalStyles = {},
-    align = IconAlign.None,
-    children,
-    className,
-    color = IconColors.UiBlack,
-    decorative = true,
-    iconRotation = IconRotationTypes.Rotate0,
-    id = generateUUID(),
-    name,
-    size = IconSizes.Medium,
-    title = `${name} icon`,
-    type = IconTypes.Default,
-  } = props;
-  const styles = useStyleConfig("Icon", {
-    align,
-    color,
-    iconRotation,
-    size,
-    variant: type,
-  });
-  const iconProps = {
-    "aria-hidden": decorative,
-    className,
-    id,
-    role: "img",
-    title,
-  };
-  let childSVG = null;
+export const Icon = chakra(
+  (props: React.PropsWithChildren<IconProps>) => {
+    const {
+      additionalStyles = {},
+      align = IconAlign.None,
+      children,
+      className,
+      color = IconColors.UiBlack,
+      decorative = true,
+      iconRotation = IconRotationTypes.Rotate0,
+      id,
+      name,
+      size = IconSizes.Default,
+      title = `${name} icon`,
+      type = IconTypes.Default,
+      ...rest
+    } = props;
+    const styles = useStyleConfig("Icon", {
+      align,
+      color,
+      iconRotation,
+      size,
+      variant: type,
+    });
+    const iconProps = {
+      "aria-hidden": decorative,
+      className,
+      id,
+      role: "img",
+      title,
+      ...rest,
+    };
+    let childSVG = null;
 
-  // Component prop validation
-  if (name && children) {
-    console.warn(
-      "Icon accepts either a `name` prop or an `svg` element child, not both."
-    );
-    return null;
-  } else if (!name && !children) {
-    console.warn(
-      "Icon: Pass an icon `name` prop or an SVG child to ensure an icon appears."
-    );
-    return null;
-  }
+    // Component prop validation
+    if (name && children) {
+      console.warn(
+        "NYPL Reservoir Icon: Pass in either a `name` prop or an `svg` element " +
+          "child. Do not pass both."
+      );
+      return null;
+    } else if (!name && !children) {
+      console.warn(
+        "NYPL Reservoir Icon: Pass an icon `name` prop or an SVG child to " +
+          "ensure an icon appears."
+      );
+      return null;
+    }
+
+    // The user wants to render an existing icon. Load the icon and render it
+    // as a component through Chakra's Icon component. Otherwise, we're going to
+    // render the SVG child with NYPL-theme styling.
+    if (name) {
+      const SvgComponent: any = iconSvgs[name];
+      return (
+        <ChakraIcon
+          as={SvgComponent}
+          {...iconProps}
+          __css={{ ...styles, ...additionalStyles }}
+        />
+      );
+    }
+
+    // If no `name` prop was passed, we expect a child SVG element to be passed.
+    // Apply icon props to the SVG child.
+    if (
+      (children as JSX.Element).type === "svg" ||
+      (children as JSX.Element).props?.type === "svg" ||
+      (children as JSX.Element).props?.mdxType === "svg"
+    ) {
+      childSVG = React.cloneElement(children as JSX.Element, {
+        ...iconProps,
+      });
+    } else {
+      console.warn(
+        "NYPL Reservoir Icon: An `svg` element must be passed to the `Icon` " +
+          "component as its child."
+      );
+    }
 
-  // The user wants to render an existing icon. Load the icon and render it
-  // as a component through Chakra's Icon component. Otherwise, we're going to
-  // render the SVG child with NYPL-theme styling.
-  if (name) {
-    const SvgComponent: any = iconSvgs[name];
     return (
-      <ChakraIcon
-        as={SvgComponent}
-        {...iconProps}
-        __css={{ ...styles, ...additionalStyles }}
-      />
+      <Box __css={styles} {...rest}>
+        {childSVG}
+      </Box>
     );
-  }
-
-  // If no `name` prop was passed, we expect a child SVG element to be passed.
-  // Apply icon props to the SVG child.
-  if (
-    (children as JSX.Element).type === "svg" ||
-    (children as JSX.Element).props.type === "svg" ||
-    (children as JSX.Element).props.mdxType === "svg"
-  ) {
-    childSVG = React.cloneElement(children as JSX.Element, {
-      ...iconProps,
-    });
-  } else {
-    console.warn("You must pass an `svg` element to the `Icon` component.");
-  }
+  },
+  // Pass all custom props to Chakra and override, e.g. we want the
+  // DS color prop to use the DS enum and not color strings.
+  { shouldForwardProp: () => true }
+);
 
-  return <Box __css={styles}>{childSVG}</Box>;
-}
+export default Icon;

package/src/components/Icons/IconTypes.tsx

@@ -22,22 +22,25 @@ export enum IconColors {
   UiWhite = "ui.white",
   BrandPrimary = "brand.primary",
   BrandSecondary = "brand.secondary",
-  SectionWhatsOnPrimary = "section.whats-on.primary",
-  SectionWhatsOnSecondary = "section.whats-on.secondary",
+  SectionBlogsPrimary = "section.blogs.primary",
+  SectionBlogsSecondary = "section.blogs.secondary",
   SectionBooksAndMorePrimary = "section.books-and-more.primary",
   SectionBooksAndMoreSecondary = "section.books-and-more.secondary",
-  SectionResearchPrimary = "section.research.primary",
-  SectionResearchSecondary = "section.research.secondary",
+  SectionEducationPrimary = "section.education.primary",
+  SectionEducationSecondary = "section.education.secondary",
   SectionLocationsPrimary = "section.locations.primary",
   SectionLocationsSecondary = "section.locations.secondary",
-  SectionBlogsPrimary = "section.blogs.primary",
-  SectionBlogsSecondary = "section.blogs.secondary",
+  SectionResearchPrimary = "section.research.primary",
+  SectionResearchSecondary = "section.research.secondary",
   SectionResearchLibraryLpa = "section.research-library.lpa",
   SectionResearchLibrarySchomburg = "section.research-library.schomburg",
   SectionResearchLibrarySchwartzman = "section.research-library.schwartzman",
+  SectionWhatsOnPrimary = "section.whats-on.primary",
+  SectionWhatsOnSecondary = "section.whats-on.secondary",
 }
 
 export enum IconSizes {
+  Default = "default",
   Small = "small",
   Medium = "medium",
   Large = "large",