@nypl/design-system-react-components 0.25.13 → 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

@@ -91,10 +91,25 @@ export const rotationEnumValues = getStorybookEnumValues(
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.0.4`    |
-| Latest            | `0.25.13`  |
+| 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"
@@ -214,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
 

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";
@@ -87,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,82 +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.Default,
-    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(
-      "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;
-  }
+    // 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 }}
-      />
-    );
-  }
+    // 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."
+    // 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."
+      );
+    }
+
+    return (
+      <Box __css={styles} {...rest}>
+        {childSVG}
+      </Box>
     );
-  }
+  },
+  // 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/__snapshots__/Icon.test.tsx.snap

@@ -0,0 +1,129 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Icon renders the UI snapshot correctly 1`] = `
+<svg
+  aria-hidden={true}
+  className="chakra-icon css-1grhd2q"
+  focusable={false}
+  id="basic"
+  role="img"
+  title="download icon"
+  viewBox="0 0 24 24"
+>
+  <g
+    stroke="currentColor"
+    strokeWidth="1.5"
+  >
+    <path
+      d="M9,9a3,3,0,1,1,4,2.829,1.5,1.5,0,0,0-1,1.415V14.25"
+      fill="none"
+      strokeLinecap="round"
+    />
+    <path
+      d="M12,17.25a.375.375,0,1,0,.375.375A.375.375,0,0,0,12,17.25h0"
+      fill="currentColor"
+      strokeLinecap="round"
+    />
+    <circle
+      cx="12"
+      cy="12"
+      fill="none"
+      r="11.25"
+      strokeMiterlimit="10"
+    />
+  </g>
+</svg>
+`;
+
+exports[`Icon renders the UI snapshot correctly 2`] = `
+<div
+  className="css-0"
+>
+  <svg
+    aria-hidden={true}
+    className="css-0"
+    id="customIcon"
+    role="img"
+    title="undefined icon"
+    viewBox="0 0 24 14"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <path
+      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"
+      fillRule="evenodd"
+    />
+  </svg>
+</div>
+`;
+
+exports[`Icon renders the UI snapshot correctly 3`] = `
+<svg
+  aria-hidden={true}
+  className="chakra-icon css-7rufou"
+  focusable={false}
+  id="chakra"
+  role="img"
+  title="download icon"
+  viewBox="0 0 24 24"
+>
+  <g
+    stroke="currentColor"
+    strokeWidth="1.5"
+  >
+    <path
+      d="M9,9a3,3,0,1,1,4,2.829,1.5,1.5,0,0,0-1,1.415V14.25"
+      fill="none"
+      strokeLinecap="round"
+    />
+    <path
+      d="M12,17.25a.375.375,0,1,0,.375.375A.375.375,0,0,0,12,17.25h0"
+      fill="currentColor"
+      strokeLinecap="round"
+    />
+    <circle
+      cx="12"
+      cy="12"
+      fill="none"
+      r="11.25"
+      strokeMiterlimit="10"
+    />
+  </g>
+</svg>
+`;
+
+exports[`Icon renders the UI snapshot correctly 4`] = `
+<svg
+  aria-hidden={true}
+  className="chakra-icon css-1grhd2q"
+  data-testid="props"
+  focusable={false}
+  id="props"
+  role="img"
+  title="download icon"
+  viewBox="0 0 24 24"
+>
+  <g
+    stroke="currentColor"
+    strokeWidth="1.5"
+  >
+    <path
+      d="M9,9a3,3,0,1,1,4,2.829,1.5,1.5,0,0,0-1,1.415V14.25"
+      fill="none"
+      strokeLinecap="round"
+    />
+    <path
+      d="M12,17.25a.375.375,0,1,0,.375.375A.375.375,0,0,0,12,17.25h0"
+      fill="currentColor"
+      strokeLinecap="round"
+    />
+    <circle
+      cx="12"
+      cy="12"
+      fill="none"
+      r="11.25"
+      strokeMiterlimit="10"
+    />
+  </g>
+</svg>
+`;

package/src/components/Image/Image.stories.mdx

@@ -82,14 +82,26 @@ export const imageBlockStyles = {
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.0.6`    |
-| Latest            | `0.25.13`  |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Image Figure](#image-figure)
+- [Image Sizes](#image-sizes)
+- [Image Aspect Ratios](#image-aspect-ratios)
+- [Image Types](#image-types)
+
+## Overview
 
 <Description of={Image} />
 
-<p>
-  If you want a simple HTML `img` element then don't pass in values for the
-  `aspectRatio` or `size` props.
-</p>
+If you want a simple HTML `img` element then don't pass in values for the
+`aspectRatio` or `size` props.
+
+## Component Props
 
 <Canvas>
   <Story
@@ -122,6 +134,18 @@ export const imageBlockStyles = {
 
 <ArgsTable story="Image with Controls" />
 
+## Accessibility
+
+All images must have an `alt` attribute, even if it's empty. The `alt` prop should
+be used to concisely describe the image. If the image is decorative, then the
+`alt` prop should be an empty string `""`.
+
+Resources:
+
+- [W3C WAI Images Tutorial](https://www.w3.org/WAI/tutorials/images/)
+- [WebAIM Accessible Images](https://webaim.org/techniques/images/)
+- [Yale Usability & Web Accessibility](https://usability.yale.edu/web-accessibility/articles/images)
+
 ## Image Figure
 
 By passing in `credit` or `caption`, the `Image` component will

package/src/components/Image/Image.test.tsx

@@ -139,6 +139,12 @@ describe("Image", () => {
         />
       )
       .toJSON();
+    const withChakraProps = renderer
+      .create(<Image src="test.png" alt="" p="20px" color="ui.error.primary" />)
+      .toJSON();
+    const withOtherProps = renderer
+      .create(<Image src="test.png" alt="" data-testid="image" />)
+      .toJSON();
 
     expect(basic).toMatchSnapshot();
     expect(figCaption).toMatchSnapshot();
@@ -158,5 +164,7 @@ describe("Image", () => {
     expect(ratioThreeByTwo).toMatchSnapshot();
     expect(ratioTwoByOne).toMatchSnapshot();
     expect(typeCircle).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
   });
 });

package/src/components/Image/Image.tsx

@@ -1,4 +1,4 @@
-import { Box, useMultiStyleConfig } from "@chakra-ui/react";
+import { Box, chakra, useMultiStyleConfig } from "@chakra-ui/react";
 import * as React from "react";
 
 import { ImageRatios, ImageSizes, ImageTypes } from "./ImageTypes";
@@ -55,31 +55,35 @@ export interface ImageProps extends ImageWrapperProps {
   src: string;
 }
 
-function ImageWrapper(props: React.PropsWithChildren<ImageWrapperProps>) {
-  const {
-    additionalWrapperStyles = {},
-    className = "",
-    children,
-    aspectRatio = ImageRatios.Original,
-    size = ImageSizes.Default,
-  } = props;
-  const styles = useMultiStyleConfig("CustomImageWrapper", {
-    ratio: aspectRatio,
-    size,
-  });
-  return (
-    <Box
-      className={`the-wrap ${className}`}
-      __css={{ ...styles, ...additionalWrapperStyles }}
-    >
-      <Box className="the-crop" __css={styles.crop}>
-        {children}
+const ImageWrapper = chakra(
+  (props: React.PropsWithChildren<ImageWrapperProps>) => {
+    const {
+      additionalWrapperStyles = {},
+      className = "",
+      children,
+      aspectRatio = ImageRatios.Original,
+      size = ImageSizes.Default,
+      ...rest
+    } = props;
+    const styles = useMultiStyleConfig("CustomImageWrapper", {
+      ratio: aspectRatio,
+      size,
+    });
+    return (
+      <Box
+        className={`the-wrap ${className}`}
+        __css={{ ...styles, ...additionalWrapperStyles }}
+        {...rest}
+      >
+        <Box className="the-crop" __css={styles.crop}>
+          {children}
+        </Box>
       </Box>
-    </Box>
-  );
-}
+    );
+  }
+);
 
-export default function Image(props: ImageProps) {
+export const Image = chakra((props: ImageProps) => {
   const {
     additionalFigureStyles = {},
     additionalImageStyles = {},
@@ -93,6 +97,7 @@ export default function Image(props: ImageProps) {
     imageType = ImageTypes.Default,
     size = ImageSizes.Default,
     src,
+    ...rest
   } = props;
   const useImageWrapper = aspectRatio !== ImageRatios.Original;
   const styles = useMultiStyleConfig("CustomImage", {
@@ -122,6 +127,7 @@ export default function Image(props: ImageProps) {
       aspectRatio={aspectRatio}
       className={className}
       size={size}
+      {...(caption || credit ? {} : rest)}
     >
       {imageComponent}
     </ImageWrapper>
@@ -130,7 +136,11 @@ export default function Image(props: ImageProps) {
   );
 
   return caption || credit ? (
-    <Box as="figure" __css={{ ...styles.figure, ...additionalFigureStyles }}>
+    <Box
+      as="figure"
+      __css={{ ...styles.figure, ...additionalFigureStyles }}
+      {...rest}
+    >
       {finalImage}
       <Box as="figcaption" __css={styles.figcaption}>
         {caption && <Box __css={styles.captionWrappers}>{caption}</Box>}
@@ -140,4 +150,6 @@ export default function Image(props: ImageProps) {
   ) : (
     finalImage
   );
-}
+});
+
+export default Image;