@nypl/design-system-react-components 0.25.12 → 0.26.1

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

@@ -9,6 +9,7 @@ import {
 import { withDesign } from "storybook-addon-designs";
 
 import Heading from "../Heading/Heading";
+import { HeadingLevels } from "../Heading/HeadingTypes";
 import Image from "./Image";
 import { ImageRatios, ImageSizes, ImageTypes } from "./ImageTypes";
 import SimpleGrid from "../Grid/SimpleGrid";
@@ -49,26 +50,26 @@ export const imageBlockStyles = {
       description:
         "Alternate text description of the image. Needed for accessibility purposes.",
     },
+    aspectRatio: {
+      control: { type: "select" },
+      table: { defaultValue: { summary: "ImageRatios.Original" } },
+      options: ratiosEnumValues.options,
+    },
     className: {
       control: false,
       description: "Additional class name for the component to use.",
     },
     component: { control: false },
-    imageAspectRatio: {
+    imageType: {
       control: { type: "select" },
-      table: { defaultValue: { summary: "ImageRatios.Original" } },
-      options: ratiosEnumValues.options,
+      table: { defaultValue: { summary: "ImageTypes.Default" } },
+      options: typesEnumValues.options,
     },
-    imageSize: {
+    size: {
       control: { type: "select" },
       table: { defaultValue: { summary: "ImageSizes.Default" } },
       options: sizesEnumValues.options,
     },
-    imageType: {
-      control: { type: "select" },
-      table: { defaultValue: { summary: "ImageTypes.Default" } },
-      options: typesEnumValues.options,
-    },
     src: {
       description:
         "The src attribute is required, and contains the path to the image you want to embed.",
@@ -81,14 +82,26 @@ export const imageBlockStyles = {
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.0.6`    |
-| Latest            | `0.25.9`   |
+| 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
-  `imageAspectRatio` or `imageSize` 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
@@ -98,22 +111,22 @@ export const imageBlockStyles = {
       additionalImageStyles: undefined,
       additionalWrapperStyles: undefined,
       alt: "Alt text",
+      aspectRatio: "ImageRatios.TwoByOne",
+      caption: "Image caption",
       className: undefined,
       component: undefined,
-      imageAspectRatio: "ImageRatios.TwoByOne",
-      imageCaption: "Image caption",
-      imageCredit: "Image credit",
-      imageSize: "ImageSizes.Medium",
+      credit: "Image credit",
       imageType: "ImageTypes.Default",
+      size: "ImageSizes.Medium",
       src: "https://placeimg.com/400/300/animals",
     }}
   >
     {(args) => (
       <Image
         {...args}
-        imageAspectRatio={ratiosEnumValues.getValue(args.imageAspectRatio)}
-        imageSize={sizesEnumValues.getValue(args.imageSize)}
+        aspectRatio={ratiosEnumValues.getValue(args.aspectRatio)}
         imageType={typesEnumValues.getValue(args.imageType)}
+        size={sizesEnumValues.getValue(args.size)}
       />
     )}
   </Story>
@@ -121,11 +134,23 @@ 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 `imageCredit` or `imageCaption`, the `Image` component will
+By passing in `credit` or `caption`, the `Image` component will
 render an HTML `figure` element and render an `img` element inside with the
-proper props. If no `imageCredit` or `imageCaption` prop values are passed,
+proper props. If no `credit` or `caption` prop values are passed,
 then an `img` element will be rendered with or without wrapper style divs.
 
 <Canvas>
@@ -133,19 +158,19 @@ then an `img` element will be rendered with or without wrapper style divs.
     name="Figure and figcaption"
     args={{
       alt: "Alt text",
-      imageAspectRatio: ImageRatios.ThreeByTwo,
-      imageCaption: "Image caption",
-      imageCredit: "Image credit",
-      imageSize: ImageSizes.Medium,
+      aspectRatio: ImageRatios.ThreeByTwo,
+      caption: "Image caption",
+      credit: "Image credit",
       imageType: ImageTypes.Default,
+      size: ImageSizes.Medium,
       src: "https://placeimg.com/400/300/animals",
     }}
     argTypes={{
-      imageAspectRatio: { table: { disable: true } },
-      imageCaption: { table: { disable: true } },
-      imageCredit: { table: { disable: true } },
-      imageSize: { table: { disable: true } },
+      aspectRatio: { table: { disable: true } },
+      caption: { table: { disable: true } },
+      credit: { table: { disable: true } },
       imageType: { table: { disable: true } },
+      size: { table: { disable: true } },
       src: { table: { disable: true } },
     }}
   >
@@ -155,61 +180,85 @@ then an `img` element will be rendered with or without wrapper style divs.
 
 ## Image Sizes
 
-Use the `ImageSizes` prop to set the desired size.
+Use the `size` prop to set the desired size with the `ImageSizes` enum.
 
 <Canvas>
   <Story name="Image Sizes">
     <SimpleGrid columns={1}>
       <div style={{ textAlign: "center" }}>
-        <Heading id="ExtraExtraSmall" text="ImageSizes.ExtraExtraSmall" />
+        <Heading
+          id="ExtraExtraSmall"
+          level={HeadingLevels.Four}
+          text="ImageSizes.ExtraExtraSmall"
+        />
         <Image
           alt="Alt text"
-          imageCaption="64px"
-          imageSize={ImageSizes.ExtraExtraSmall}
+          caption="64px"
+          size={ImageSizes.ExtraExtraSmall}
           src="https://placeimg.com/400/300/animals"
         />
       </div>
       <div style={{ textAlign: "center" }}>
-        <Heading id="ExtraSmall" text="ImageSizes.ExtraSmall" />
+        <Heading
+          id="ExtraSmall"
+          level={HeadingLevels.Four}
+          text="ImageSizes.ExtraSmall"
+        />
         <Image
           alt="Alt text"
-          imageCaption="96px"
-          imageSize={ImageSizes.ExtraSmall}
+          caption="96px"
+          size={ImageSizes.ExtraSmall}
           src="https://placeimg.com/400/300/animals"
         />
       </div>
       <div style={{ textAlign: "center" }}>
-        <Heading id="Small" text="ImageSizes.Small" />
+        <Heading
+          id="Small"
+          level={HeadingLevels.Four}
+          text="ImageSizes.Small"
+        />
         <Image
           alt="Alt text"
-          imageCaption="165px"
-          imageSize={ImageSizes.Small}
+          caption="165px"
+          size={ImageSizes.Small}
           src="https://placeimg.com/400/300/animals"
         />
       </div>
       <div style={{ textAlign: "center" }}>
-        <Heading id="Medium" text="ImageSizes.Medium" />
+        <Heading
+          id="Medium"
+          level={HeadingLevels.Four}
+          text="ImageSizes.Medium"
+        />
         <Image
           alt="Alt text"
-          imageCaption="225px"
-          imageSize={ImageSizes.Medium}
+          caption="225px"
+          size={ImageSizes.Medium}
           src="https://placeimg.com/400/300/animals"
         />
       </div>
       <div style={{ textAlign: "center" }}>
-        <Heading id="Large" text="ImageSizes.Large" />
+        <Heading
+          id="Large"
+          level={HeadingLevels.Four}
+          text="ImageSizes.Large"
+        />
         <Image
           alt="Alt text"
-          imageCaption="360px"
-          imageSize={ImageSizes.Large}
+          caption="360px"
+          size={ImageSizes.Large}
           src="https://placeimg.com/400/300/animals"
         />
       </div>
       <div style={{ textAlign: "center" }}>
-        <Heading id="Default" text="ImageSizes.Default" />
+        <Heading
+          id="Default"
+          level={HeadingLevels.Four}
+          text="ImageSizes.Default"
+        />
         <Image
           alt="Alt text"
-          imageCaption="100%"
+          caption="100%"
           src="https://placeimg.com/400/300/animals"
         />
       </div>
@@ -219,8 +268,8 @@ Use the `ImageSizes` prop to set the desired size.
 
 ## Image Aspect Ratios
 
-Use the `imageAspectRatio` prop to set the desired aspect ratio. Note: the
-following example has `imageSize` set to `ImageSizes.Small`.
+Use the `aspectRatio` prop to set the desired aspect ratio. Note: the
+following example has `size` set to `ImageSizes.Small`.
 
 For a better viewing experience, the `Image` components below have been wrapped
 in an element with a fixed width value.
@@ -229,66 +278,98 @@ in an element with a fixed width value.
   <Story name="Image Aspect Ratios">
     <SimpleGrid columns={1}>
       <div style={imageBlockStyles}>
-        <Heading id="fourbythree" text="ImageRatios.FourByThree" />
+        <Heading
+          id="fourbythree"
+          level={HeadingLevels.Four}
+          text="ImageRatios.FourByThree"
+        />
         <Image
           alt="Alt text"
-          imageAspectRatio={ImageRatios.FourByThree}
+          aspectRatio={ImageRatios.FourByThree}
           src="https://placeimg.com/400/300/animals"
         />
       </div>
       <div style={imageBlockStyles}>
-        <Heading id="onebytwo" text="ImageRatios.OneByTwo" />
+        <Heading
+          id="onebytwo"
+          level={HeadingLevels.Four}
+          text="ImageRatios.OneByTwo"
+        />
         <Image
           alt="Alt text"
-          imageAspectRatio={ImageRatios.OneByTwo}
+          aspectRatio={ImageRatios.OneByTwo}
           src="https://placeimg.com/400/300/animals"
         />
       </div>
       <div style={imageBlockStyles}>
-        <Heading id="original" text="ImageRatios.Original" />
+        <Heading
+          id="original"
+          level={HeadingLevels.Four}
+          text="ImageRatios.Original"
+        />
         <Image
           alt="Alt text"
-          imageAspectRatio={ImageRatios.Original}
+          aspectRatio={ImageRatios.Original}
           src="https://placeimg.com/400/300/animals"
         />
       </div>
       <div style={imageBlockStyles}>
-        <Heading id="sixteenbynine" text="ImageRatios.SixteenByNine" />
+        <Heading
+          id="sixteenbynine"
+          level={HeadingLevels.Four}
+          text="ImageRatios.SixteenByNine"
+        />
         <Image
           alt="Alt text"
-          imageAspectRatio={ImageRatios.SixteenByNine}
+          aspectRatio={ImageRatios.SixteenByNine}
           src="https://placeimg.com/400/300/animals"
         />
       </div>
       <div style={imageBlockStyles}>
-        <Heading id="square" text="ImageRatios.Square" />
+        <Heading
+          id="square"
+          level={HeadingLevels.Four}
+          text="ImageRatios.Square"
+        />
         <Image
           alt="Alt text"
-          imageAspectRatio={ImageRatios.Square}
+          aspectRatio={ImageRatios.Square}
           src="https://placeimg.com/400/300/animals"
         />
       </div>
       <div style={imageBlockStyles}>
-        <Heading id="threebyfour" text="ImageRatios.ThreeByFour" />
+        <Heading
+          id="threebyfour"
+          level={HeadingLevels.Four}
+          text="ImageRatios.ThreeByFour"
+        />
         <Image
           alt="Alt text"
-          imageAspectRatio={ImageRatios.ThreeByFour}
+          aspectRatio={ImageRatios.ThreeByFour}
           src="https://placeimg.com/400/300/animals"
         />
       </div>
       <div style={imageBlockStyles}>
-        <Heading id="threebytwo" text="ImageRatios.ThreeByTwo" />
+        <Heading
+          id="threebytwo"
+          level={HeadingLevels.Four}
+          text="ImageRatios.ThreeByTwo"
+        />
         <Image
           alt="Alt text"
-          imageAspectRatio={ImageRatios.ThreeByTwo}
+          aspectRatio={ImageRatios.ThreeByTwo}
           src="https://placeimg.com/400/300/animals"
         />
       </div>
       <div style={imageBlockStyles}>
-        <Heading id="twobyone" text="ImageRatios.TwoByOne" />
+        <Heading
+          id="twobyone"
+          level={HeadingLevels.Four}
+          text="ImageRatios.TwoByOne"
+        />
         <Image
           alt="Alt text"
-          imageAspectRatio={ImageRatios.TwoByOne}
+          aspectRatio={ImageRatios.TwoByOne}
           src="https://placeimg.com/400/300/animals"
         />
       </div>
@@ -299,7 +380,7 @@ in an element with a fixed width value.
 ## Image Types
 
 Use the `imageType` prop to get an image variant. Note that to get a perfect
-circle, the `imageAspectRatio` prop _must_ be set to `ImageRatios.Square`.
+circle, the `aspectRatio` prop _must_ be set to `ImageRatios.Square`.
 
 For a better viewing experience, the `Image` components below have been wrapped
 in an element with a fixed width value.
@@ -308,19 +389,27 @@ in an element with a fixed width value.
   <Story name="Image Types">
     <SimpleGrid columns={1}>
       <div style={imageBlockStyles}>
-        <Heading id="default" text="ImageTypes.Default" />
+        <Heading
+          id="default"
+          level={HeadingLevels.Four}
+          text="ImageTypes.Default"
+        />
         <Image
           alt="Alt text"
-          imageAspectRatio={ImageRatios.Square}
+          aspectRatio={ImageRatios.Square}
           imageType={ImageTypes.Default}
           src="https://placeimg.com/400/400/animals"
         />
       </div>
       <div style={imageBlockStyles}>
-        <Heading id="circle" text="ImageTypes.Circle" />
+        <Heading
+          id="circle"
+          level={HeadingLevels.Four}
+          text="ImageTypes.Circle"
+        />
         <Image
           alt="Alt text"
-          imageAspectRatio={ImageRatios.Square}
+          aspectRatio={ImageRatios.Square}
           imageType={ImageTypes.Circle}
           src="https://placeimg.com/400/400/animals"
         />

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

@@ -14,7 +14,7 @@ describe("Image Accessibility", () => {
 
   it("passes axe accessibility for figure element wrapper", async () => {
     const { container } = render(
-      <Image src="test.png" alt="" imageCaption="This is a caption" />
+      <Image src="test.png" alt="" caption="This is a caption" />
     );
     expect(await axe(container)).toHaveNoViolations();
   });
@@ -35,28 +35,21 @@ describe("Image", () => {
   });
 
   it("renders an image wrapped in figure when provided a caption", () => {
-    render(<Image src="test.png" imageCaption="caption" alt="" />);
+    render(<Image src="test.png" caption="caption" alt="" />);
     expect(screen.getByRole("img")).toBeInTheDocument();
     expect(screen.getByRole("figure")).toBeInTheDocument();
     expect(screen.getByText("caption")).toBeInTheDocument();
   });
 
   it("renders an image wrapped in figure when provided an image credit", () => {
-    render(<Image src="test.png" imageCredit="credit" alt="" />);
+    render(<Image src="test.png" credit="credit" alt="" />);
     expect(screen.getByRole("img")).toBeInTheDocument();
     expect(screen.getByRole("figure")).toBeInTheDocument();
     expect(screen.getByText("credit")).toBeInTheDocument();
   });
 
   it("renders an image wrapped in figure with credit and caption", () => {
-    render(
-      <Image
-        src="test.png"
-        imageCaption="caption"
-        imageCredit="credit"
-        alt=""
-      />
-    );
+    render(<Image src="test.png" caption="caption" credit="credit" alt="" />);
     expect(screen.getByRole("img")).toBeInTheDocument();
     expect(screen.getByRole("figure")).toBeInTheDocument();
     expect(screen.getByText("caption")).toBeInTheDocument();
@@ -66,85 +59,73 @@ describe("Image", () => {
   it("throws error when alt text is too long", () => {
     expect(() =>
       render(<Image src="test.png" alt={tooManyChars} />)
-    ).toThrowError("Alt Text must be less than 300 characters");
+    ).toThrowError(
+      "NYPL Reservoir Image: Alt text must be less than 300 characters."
+    );
   });
 
   it("Renders the UI snapshot correctly", () => {
     const basic = renderer.create(<Image src="test.png" alt="" />).toJSON();
     const figCaption = renderer
-      .create(<Image src="test.png" alt="" imageCaption="Caption" />)
+      .create(<Image src="test.png" alt="" caption="Caption" />)
+      .toJSON();
+    const figCredit = renderer
+      .create(<Image src="test.png" alt="" credit="Credit" />)
+      .toJSON();
+    const figCaptionCredit = renderer
+      .create(<Image src="test.png" alt="" caption="Caption" credit="Credit" />)
       .toJSON();
     const sizeExtraExtraSmall = renderer
-      .create(
-        <Image src="test.png" alt="" imageSize={ImageSizes.ExtraExtraSmall} />
-      )
+      .create(<Image src="test.png" alt="" size={ImageSizes.ExtraExtraSmall} />)
       .toJSON();
     const sizeExtraSmall = renderer
-      .create(<Image src="test.png" alt="" imageSize={ImageSizes.ExtraSmall} />)
+      .create(<Image src="test.png" alt="" size={ImageSizes.ExtraSmall} />)
       .toJSON();
     const sizeSmall = renderer
-      .create(<Image src="test.png" alt="" imageSize={ImageSizes.Small} />)
+      .create(<Image src="test.png" alt="" size={ImageSizes.Small} />)
       .toJSON();
     const sizeMedium = renderer
-      .create(<Image src="test.png" alt="" imageSize={ImageSizes.Medium} />)
+      .create(<Image src="test.png" alt="" size={ImageSizes.Medium} />)
       .toJSON();
     const sizeLarge = renderer
-      .create(<Image src="test.png" alt="" imageSize={ImageSizes.Large} />)
+      .create(<Image src="test.png" alt="" size={ImageSizes.Large} />)
       .toJSON();
     const ratioFourByThree = renderer
       .create(
-        <Image
-          src="test.png"
-          alt=""
-          imageAspectRatio={ImageRatios.FourByThree}
-        />
+        <Image src="test.png" alt="" aspectRatio={ImageRatios.FourByThree} />
       )
       .toJSON();
     const ratioOneByTwo = renderer
       .create(
-        <Image src="test.png" alt="" imageAspectRatio={ImageRatios.OneByTwo} />
+        <Image src="test.png" alt="" aspectRatio={ImageRatios.OneByTwo} />
       )
       .toJSON();
     const ratioOriginal = renderer
       .create(
-        <Image src="test.png" alt="" imageAspectRatio={ImageRatios.Original} />
+        <Image src="test.png" alt="" aspectRatio={ImageRatios.Original} />
       )
       .toJSON();
     const ratioSixteenByNine = renderer
       .create(
-        <Image
-          src="test.png"
-          alt=""
-          imageAspectRatio={ImageRatios.SixteenByNine}
-        />
+        <Image src="test.png" alt="" aspectRatio={ImageRatios.SixteenByNine} />
       )
       .toJSON();
     const ratioSquare = renderer
-      .create(
-        <Image src="test.png" alt="" imageAspectRatio={ImageRatios.Square} />
-      )
+      .create(<Image src="test.png" alt="" aspectRatio={ImageRatios.Square} />)
       .toJSON();
     const ratioThreeByFour = renderer
       .create(
-        <Image
-          src="test.png"
-          alt=""
-          imageAspectRatio={ImageRatios.ThreeByFour}
-        />
+        <Image src="test.png" alt="" aspectRatio={ImageRatios.ThreeByFour} />
       )
       .toJSON();
     const ratioThreeByTwo = renderer
       .create(
-        <Image
-          src="test.png"
-          alt=""
-          imageAspectRatio={ImageRatios.ThreeByTwo}
-        />
+        <Image src="test.png" alt="" aspectRatio={ImageRatios.ThreeByTwo} />
       )
       .toJSON();
     const ratioTwoByOne = renderer
       .create(
-        <Image src="test.png" alt="" imageAspectRatio={ImageRatios.TwoByOne} />
+        <Image src="test.png" alt="" aspectRatio={ImageRatios.TwoByOne} />
       )
       .toJSON();
     const typeCircle = renderer
@@ -152,14 +133,23 @@ describe("Image", () => {
         <Image
           src="test.png"
           alt=""
-          imageAspectRatio={ImageRatios.Square}
-          imageSize={ImageSizes.Small}
+          aspectRatio={ImageRatios.Square}
+          size={ImageSizes.Small}
           imageType={ImageTypes.Circle}
         />
       )
       .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();
+    expect(figCredit).toMatchSnapshot();
+    expect(figCaptionCredit).toMatchSnapshot();
     expect(sizeExtraExtraSmall).toMatchSnapshot();
     expect(sizeExtraSmall).toMatchSnapshot();
     expect(sizeSmall).toMatchSnapshot();
@@ -174,5 +164,7 @@ describe("Image", () => {
     expect(ratioThreeByTwo).toMatchSnapshot();
     expect(ratioTwoByOne).toMatchSnapshot();
     expect(typeCircle).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
   });
 });