@nypl/design-system-react-components 1.0.1 → 1.0.2

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

@@ -0,0 +1,332 @@
+import { VStack } from "@chakra-ui/react";
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import Heading from "../Heading/Heading";
+import Image from "./Image";
+import SimpleGrid from "../Grid/SimpleGrid";
+import { getCategory } from "../../utils/componentCategories";
+
+export const imageBlockStyles = {
+  margin: "auto",
+  maxWidth: "360px",
+  textAlign: "center",
+  width: "100%",
+};
+
+<Meta
+  title={getCategory("Image")}
+  component={Image}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=11896%3A45379",
+    },
+    jest: ["Image.test.tsx"],
+  }}
+  argTypes={{
+    additionalFigureStyles: { control: false },
+    additionalImageStyles: { control: false },
+    additionalWrapperStyles: { control: false },
+    alt: {
+      control: false,
+      description:
+        "Alternate text description of the image. Needed for accessibility purposes.",
+    },
+    aspectRatio: {
+      table: { defaultValue: { summary: "original" } },
+    },
+    className: {
+      control: false,
+      description: "Additional class name for the component to use.",
+    },
+    component: { control: false },
+    imageType: {
+      table: { defaultValue: { summary: "default" } },
+    },
+    size: {
+      table: { defaultValue: { summary: "default" } },
+    },
+    src: {
+      description:
+        "The src attribute is required, and contains the path to the image you want to embed.",
+    },
+  }}
+/>
+
+# Image
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.0.6`    |
+| Latest            | `1.0.2`    |
+
+## 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} />
+
+If you want a simple HTML `img` element then don't pass in values for the
+`aspectRatio` or `size` props.
+
+## Component Props
+
+<Canvas>
+  <Story
+    name="Image with Controls"
+    args={{
+      additionalFigureStyles: undefined,
+      additionalImageStyles: undefined,
+      additionalWrapperStyles: undefined,
+      alt: "Alt text",
+      aspectRatio: "twoByOne",
+      caption: "Image caption",
+      className: undefined,
+      component: undefined,
+      credit: "Image credit",
+      imageType: "default",
+      size: "medium",
+      src: "https://placeimg.com/400/300/animals",
+    }}
+  >
+    {(args) => <Image {...args} />}
+  </Story>
+</Canvas>
+
+<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
+render an HTML `figure` element and render an `img` element inside with the
+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>
+  <Story
+    name="Figure and figcaption"
+    args={{
+      alt: "Alt text",
+      aspectRatio: "threeByTwo",
+      caption: "Image caption",
+      credit: "Image credit",
+      imageType: "default",
+      size: "medium",
+      src: "https://placeimg.com/400/300/animals",
+    }}
+    argTypes={{
+      aspectRatio: { table: { disable: true } },
+      caption: { table: { disable: true } },
+      credit: { table: { disable: true } },
+      imageType: { table: { disable: true } },
+      size: { table: { disable: true } },
+      src: { table: { disable: true } },
+    }}
+  >
+    {(args) => <Image {...args} />}
+  </Story>
+</Canvas>
+
+## Image Sizes
+
+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" level="four" text="xxsmall" />
+        <Image
+          alt="Alt text"
+          caption="64px"
+          size="xxsmall"
+          src="https://placeimg.com/400/300/animals"
+        />
+      </div>
+      <div style={{ textAlign: "center" }}>
+        <Heading id="ExtraSmall" level="four" text="xsmall" />
+        <Image
+          alt="Alt text"
+          caption="96px"
+          size="xsmall"
+          src="https://placeimg.com/400/300/animals"
+        />
+      </div>
+      <div style={{ textAlign: "center" }}>
+        <Heading id="Small" level="four" text="small" />
+        <Image
+          alt="Alt text"
+          caption="165px"
+          size="small"
+          src="https://placeimg.com/400/300/animals"
+        />
+      </div>
+      <div style={{ textAlign: "center" }}>
+        <Heading id="Medium" level="four" text="medium" />
+        <Image
+          alt="Alt text"
+          caption="225px"
+          size="medium"
+          src="https://placeimg.com/400/300/animals"
+        />
+      </div>
+      <div style={{ textAlign: "center" }}>
+        <Heading id="Large" level="four" text="large" />
+        <Image
+          alt="Alt text"
+          caption="360px"
+          size="large"
+          src="https://placeimg.com/400/300/animals"
+        />
+      </div>
+      <div style={{ textAlign: "center" }}>
+        <Heading id="Default" level="four" text="default" />
+        <Image
+          alt="Alt text"
+          caption="100%"
+          src="https://placeimg.com/400/300/animals"
+        />
+      </div>
+    </SimpleGrid>
+  </Story>
+</Canvas>
+
+## Image Aspect Ratios
+
+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.
+
+<Canvas>
+  <Story name="Image Aspect Ratios">
+    <SimpleGrid columns={1}>
+      <div style={imageBlockStyles}>
+        <Heading id="fourbythree" level="four" text="fourByThree" />
+        <Image
+          alt="Alt text"
+          aspectRatio="fourByThree"
+          src="https://placeimg.com/400/300/animals"
+        />
+      </div>
+      <div style={imageBlockStyles}>
+        <Heading id="onebytwo" level="four" text="oneByTwo" />
+        <Image
+          alt="Alt text"
+          aspectRatio="oneByTwo"
+          src="https://placeimg.com/400/300/animals"
+        />
+      </div>
+      <div style={imageBlockStyles}>
+        <Heading id="original" level="four" text="original" />
+        <Image
+          alt="Alt text"
+          aspectRatio="original"
+          src="https://placeimg.com/400/300/animals"
+        />
+      </div>
+      <div style={imageBlockStyles}>
+        <Heading id="sixteenbynine" level="four" text="sixteenByNine" />
+        <Image
+          alt="Alt text"
+          aspectRatio="sixteenByNine"
+          src="https://placeimg.com/400/300/animals"
+        />
+      </div>
+      <div style={imageBlockStyles}>
+        <Heading id="square" level="four" text="square" />
+        <Image
+          alt="Alt text"
+          aspectRatio="square"
+          src="https://placeimg.com/400/300/animals"
+        />
+      </div>
+      <div style={imageBlockStyles}>
+        <Heading id="threebyfour" level="four" text="threeByFour" />
+        <Image
+          alt="Alt text"
+          aspectRatio="threeByFour"
+          src="https://placeimg.com/400/300/animals"
+        />
+      </div>
+      <div style={imageBlockStyles}>
+        <Heading id="threebytwo" level="four" text="threeByTwo" />
+        <Image
+          alt="Alt text"
+          aspectRatio="threeByTwo"
+          src="https://placeimg.com/400/300/animals"
+        />
+      </div>
+      <div style={imageBlockStyles}>
+        <Heading id="twobyone" level="four" text="twoByOne" />
+        <Image
+          alt="Alt text"
+          aspectRatio="twoByOne"
+          src="https://placeimg.com/400/300/animals"
+        />
+      </div>
+    </SimpleGrid>
+  </Story>
+</Canvas>
+
+## Image Types
+
+Use the `imageType` prop to get an image variant. Note that to get a perfect
+circle, the `aspectRatio` prop _must_ be set to `"square"`.
+
+For a better viewing experience, the `Image` components below have been wrapped
+in an element with a fixed width value.
+
+<Canvas>
+  <Story name="Image Types">
+    <SimpleGrid columns={1}>
+      <div style={imageBlockStyles}>
+        <Heading id="default" level="four" text="default" />
+        <Image
+          alt="Alt text"
+          aspectRatio="square"
+          imageType="default"
+          src="https://placeimg.com/400/400/animals"
+        />
+      </div>
+      <div style={imageBlockStyles}>
+        <Heading id="circle" level="four" text="circle" />
+        <Image
+          alt="Alt text"
+          aspectRatio="square"
+          imageType="circle"
+          src="https://placeimg.com/400/400/animals"
+        />
+      </div>
+    </SimpleGrid>
+  </Story>
+</Canvas>

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

@@ -0,0 +1,155 @@
+import * as React from "react";
+import { render, screen } from "@testing-library/react";
+import { axe } from "jest-axe";
+import renderer from "react-test-renderer";
+
+import Image from "./Image";
+
+describe("Image Accessibility", () => {
+  it("passes axe accessibility for regular img element", async () => {
+    const { container } = render(<Image src="test.png" alt="" />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+
+  it("passes axe accessibility for figure element wrapper", async () => {
+    const { container } = render(
+      <Image src="test.png" alt="" caption="This is a caption" />
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("Image", () => {
+  const tooManyChars =
+    "UNwbNIp1GFehVO1LBBIFYF6Nv5IhHeCPgW5JHet2VRuuKnKlGxSgjbFcfCbcttVTkxbE7I" +
+    "tibBIuG9cTA9HGntZSKv31u7egV88bIg7DGDHmi2nKq3ssZkBDl7oWfYpyjWbfV4kZx9EDP" +
+    "sKHUTKb2xIKZWSbRMuTUtsJWonQyfitDp8ui1P7QR80LA236yE5fCkRImbltEsqJWEYxyot" +
+    "QpLjFbruJsPcGSCp6ET6DCrNQeWFsRVaM2Co99ewZjLuY42kdpBEXjcw9HPcTjKKZw141sK" +
+    "BNOoFfNMueYaHtNjNI";
+
+  it("renders a simple image not wrapped in a figure element", () => {
+    render(<Image src="test.png" alt="" />);
+    expect(screen.getByRole("img")).toBeInTheDocument();
+    expect(screen.queryByRole("figure")).not.toBeInTheDocument();
+  });
+
+  it("renders an image wrapped in figure when provided a caption", () => {
+    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" 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" caption="caption" credit="credit" alt="" />);
+    expect(screen.getByRole("img")).toBeInTheDocument();
+    expect(screen.getByRole("figure")).toBeInTheDocument();
+    expect(screen.getByText("caption")).toBeInTheDocument();
+    expect(screen.getByText("credit")).toBeInTheDocument();
+  });
+
+  it("throws error when alt text is too long", () => {
+    expect(() =>
+      render(<Image src="test.png" alt={tooManyChars} />)
+    ).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="" 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="" size="xxsmall" />)
+      .toJSON();
+    const sizeExtraSmall = renderer
+      .create(<Image src="test.png" alt="" size="xsmall" />)
+      .toJSON();
+    const sizeSmall = renderer
+      .create(<Image src="test.png" alt="" size="small" />)
+      .toJSON();
+    const sizeMedium = renderer
+      .create(<Image src="test.png" alt="" size="medium" />)
+      .toJSON();
+    const sizeLarge = renderer
+      .create(<Image src="test.png" alt="" size="large" />)
+      .toJSON();
+    const ratioFourByThree = renderer
+      .create(<Image src="test.png" alt="" aspectRatio="fourByThree" />)
+      .toJSON();
+    const ratioOneByTwo = renderer
+      .create(<Image src="test.png" alt="" aspectRatio="oneByTwo" />)
+      .toJSON();
+    const ratioOriginal = renderer
+      .create(<Image src="test.png" alt="" aspectRatio="original" />)
+      .toJSON();
+    const ratioSixteenByNine = renderer
+      .create(<Image src="test.png" alt="" aspectRatio="sixteenByNine" />)
+      .toJSON();
+    const ratioSquare = renderer
+      .create(<Image src="test.png" alt="" aspectRatio="square" />)
+      .toJSON();
+    const ratioThreeByFour = renderer
+      .create(<Image src="test.png" alt="" aspectRatio="threeByFour" />)
+      .toJSON();
+    const ratioThreeByTwo = renderer
+      .create(<Image src="test.png" alt="" aspectRatio="threeByTwo" />)
+      .toJSON();
+    const ratioTwoByOne = renderer
+      .create(<Image src="test.png" alt="" aspectRatio="twoByOne" />)
+      .toJSON();
+    const typeCircle = renderer
+      .create(
+        <Image
+          src="test.png"
+          alt=""
+          aspectRatio="square"
+          size="small"
+          imageType="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();
+    expect(sizeMedium).toMatchSnapshot();
+    expect(sizeLarge).toMatchSnapshot();
+    expect(ratioFourByThree).toMatchSnapshot();
+    expect(ratioOneByTwo).toMatchSnapshot();
+    expect(ratioOriginal).toMatchSnapshot();
+    expect(ratioSixteenByNine).toMatchSnapshot();
+    expect(ratioSquare).toMatchSnapshot();
+    expect(ratioThreeByFour).toMatchSnapshot();
+    expect(ratioThreeByTwo).toMatchSnapshot();
+    expect(ratioTwoByOne).toMatchSnapshot();
+    expect(typeCircle).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
+  });
+});

package/src/components/Image/Image.tsx

@@ -0,0 +1,171 @@
+import { Box, chakra, useMultiStyleConfig } from "@chakra-ui/react";
+import * as React from "react";
+
+export type ImageRatios =
+  | "fourByThree"
+  | "oneByTwo"
+  | "original"
+  | "sixteenByNine"
+  | "square"
+  | "threeByFour"
+  | "threeByTwo"
+  | "twoByOne";
+export type ImageSizes =
+  | "default"
+  | "xxsmall"
+  | "xsmall"
+  | "small"
+  | "medium"
+  | "large";
+export type ImageTypes = "default" | "circle";
+// Used for components that have an `imageProps` prop.
+export interface ComponentImageProps {
+  /** String value used to populate the `alt` attribute of the internal `Image`
+   * component's `img` element. @NOTE if an image is used, this value must be passed. */
+  alt?: string;
+  /** Optional value to control the aspect ratio of the internal `Image` component.
+   * Defaults to `ImageRatios.Square`. */
+  aspectRatio?: ImageRatios;
+  /** Optional value to render as a caption for the internal `Image` component. */
+  caption?: string;
+  /** Optional DOM element to use instead of the DS `Image` component. */
+  component?: JSX.Element;
+  /** Optional value to render as a credit for the internal `Image` component. */
+  credit?: string;
+  /** Optional value to control the size of the internal `Image` component.
+   * Defaults to `ImageSizes.Default`. */
+  size?: ImageSizes;
+  /** Optional value that contains the path to an image. If omitted, the internal
+   * DS `Image` component will not render. */
+  src?: string;
+}
+
+interface ImageWrapperProps {
+  /** Optionally pass in additional Chakra-based styles. */
+  additionalWrapperStyles?: { [key: string]: any };
+  /** ClassName you can add in addition to 'image' */
+  className?: string;
+  /** Optional value to control the aspect ratio of the card image; default
+   * value is `"original"` */
+  aspectRatio?: ImageRatios;
+  /** Optional value to control the size of the image */
+  size?: ImageSizes;
+}
+
+export interface ImageProps extends ImageWrapperProps {
+  /** Optionally pass in additional Chakra-based styles only for the figure. */
+  additionalFigureStyles?: { [key: string]: any };
+  /** Optionally pass in additional Chakra-based styles only for the image. */
+  additionalImageStyles?: { [key: string]: any };
+  /** Alternate text description of the image */
+  alt?: string;
+  /** Adding will wrap the image in a <figure> */
+  caption?: string;
+  /** Custom image component */
+  component?: JSX.Element | null;
+  /** Adding will wrap the image in a <figure> */
+  credit?: string;
+  /** Optional value for the image type */
+  imageType?: ImageTypes;
+  /** The src attribute is required, and contains the path to the image you want to embed. */
+  src?: string;
+}
+
+const ImageWrapper = chakra(
+  (props: React.PropsWithChildren<ImageWrapperProps>) => {
+    const {
+      additionalWrapperStyles = {},
+      className = "",
+      children,
+      aspectRatio = "original",
+      size = "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>
+    );
+  }
+);
+
+export const Image = chakra((props: ImageProps) => {
+  const {
+    additionalFigureStyles = {},
+    additionalImageStyles = {},
+    additionalWrapperStyles = {},
+    alt,
+    aspectRatio = "original",
+    caption,
+    className = "",
+    component,
+    credit,
+    imageType = "default",
+    size = "default",
+    src,
+    ...rest
+  } = props;
+  const useImageWrapper = aspectRatio !== "original";
+  const styles = useMultiStyleConfig("CustomImage", {
+    variant: imageType,
+    size,
+  });
+
+  if (alt && alt.length > 300) {
+    throw new Error(
+      "NYPL Reservoir Image: Alt text must be less than 300 characters."
+    );
+  }
+
+  const imageComponent: JSX.Element = component ? (
+    component
+  ) : (
+    <Box
+      as="img"
+      src={src}
+      alt={alt}
+      __css={{ ...styles.img, ...additionalImageStyles }}
+    />
+  );
+  const finalImage = useImageWrapper ? (
+    <ImageWrapper
+      additionalWrapperStyles={additionalWrapperStyles}
+      aspectRatio={aspectRatio}
+      className={className}
+      size={size}
+      {...(caption || credit ? {} : rest)}
+    >
+      {imageComponent}
+    </ImageWrapper>
+  ) : (
+    imageComponent
+  );
+
+  return caption || credit ? (
+    <Box
+      as="figure"
+      __css={{ ...styles.figure, ...additionalFigureStyles }}
+      {...rest}
+    >
+      {finalImage}
+      <Box as="figcaption" __css={styles.figcaption}>
+        {caption && <Box __css={styles.captionWrappers}>{caption}</Box>}
+        {credit && <Box __css={styles.captionWrappers}>{credit}</Box>}
+      </Box>
+    </Box>
+  ) : (
+    finalImage
+  );
+});
+
+export default Image;