@nypl/design-system-react-components 0.25.5 → 0.25.9

package/src/components/StructuredContent/StructuredContent.test.tsx

@@ -0,0 +1,376 @@
+import * as React from "react";
+import { render, screen } from "@testing-library/react";
+import { axe } from "jest-axe";
+import renderer from "react-test-renderer";
+
+import { ImageRatios, ImageSizes } from "../Image/ImageTypes";
+import StructuredContent from "./StructuredContent";
+import { StructuredContentImagePosition } from "./StructuredContentTypes";
+
+const htmlStringBodyContent =
+  "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do" +
+  "eiusmod tempor incididunt ut labore et dolore magna aliqua." +
+  "Pellentesque massa placerat duis ultricies lacus sed turpis tincidunt. " +
+  "<a href='#'>Porttitor eget dolor</a> morbi non arcu risus quis varius." +
+  "Faucibus in ornare quam viverra orci sagittis.</p><p>Nisl vel pretium lectus" +
+  "quam id leo in. Etiam dignissim diam quis enim lobortis scelerisque fermentum." +
+  "Diam maecenas sed enim ut sem viverra. <b>Diam quam nulla porttitor massa" +
+  "id neque. Sed faucibus turpis in eu mi.</b></p><p>Ornare lectus sit amet est placerat" +
+  "in. Quis blandit turpis cursus in. Aliquam ut porttitor leo a diam sollicitudin" +
+  "tempor id eu. Pellentesque eu tincidunt tortor aliquam nulla facilisi cras" +
+  "fermentum. Porttitor leo a diam sollicitudin tempor id eu nisl nunc. Feugiat" +
+  "nisl pretium fusce id velit ut tortor. Porttitor leo a diam sollicitudin " +
+  "tempor id eu nisl nunc.</p><ul><li>one</li><li>two</li>" +
+  "<li>three</li><li>four</li></ul><p><i>Mauris nunc congue nisi vitae suscipit" +
+  "tellus mauris a diam. Purus gravida quis blandit turpis cursus in hac." +
+  "Morbi tempus iaculis urna id volutpat. Lectus nulla at volutpat diam ut" +
+  "venenatis. Donec ac odio tempor orci dapibus ultrices in iaculis. Dui vivamus" +
+  "arcu felis bibendum ut tristique. Cras semper auctor neque vitae tempus" +
+  "quam pellentesque. Placerat orci nulla pellentesque dignissim enim sit" +
+  "amet. Feugiat pretium nibh ipsum consequat. Placerat orci nulla pellentesque" +
+  "dignissim. Suspendisse faucibus interdum posuere lorem. Nullam non nisi" +
+  "est sit. Turpis egestas integer eget aliquet nibh praesent. Tortor at risus" +
+  "viverra adipiscing at. Eu augue ut lectus arcu bibendum at varius vel" +
+  "pharetra.</i></p>";
+const htmlDOMBodyContent = (
+  <>
+    <p>
+      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+      tempor incididunt ut labore et dolore magna aliqua. Pellentesque massa
+      placerat duis ultricies lacus sed turpis tincidunt.
+      <a href="http://nypl.org">Porttitor eget dolor</a> morbi non arcu risus
+      quis varius. Faucibus in ornare quam viverra orci sagittis.
+    </p>
+    <p>
+      Nisl vel pretium lectus quam id leo in. Etiam dignissim diam quis enim
+      lobortis scelerisque fermentum. Diam maecenas sed enim ut sem viverra.{" "}
+      <b>
+        Diam quam nulla porttitor massa id neque. Sed faucibus turpis in eu mi.
+      </b>
+    </p>
+    <p>
+      Ornare lectus sit amet est placerat in. Quis blandit turpis cursus in.
+      Aliquam ut porttitor leo a diam sollicitudin tempor id eu. Pellentesque eu
+      tincidunt tortor aliquam nulla facilisi cras fermentum. Porttitor leo a
+      diam sollicitudin tempor id eu nisl nunc. Feugiat nisl pretium fusce id
+      velit ut tortor. Porttitor leo a diam sollicitudin tempor id eu nisl nunc.
+    </p>
+    <ul>
+      <li>one</li>
+      <li>two</li>
+      <li>three</li>
+      <li>four</li>
+    </ul>
+    <p>
+      <i>
+        Mauris nunc congue nisi vitae suscipit tellus mauris a diam. Purus
+        gravida quis blandit turpis cursus in hac. Morbi tempus iaculis urna id
+        volutpat. Lectus nulla at volutpat diam ut venenatis. Donec ac odio
+        tempor orci dapibus ultrices in iaculis. Dui vivamus arcu felis bibendum
+        ut tristique. Cras semper auctor neque vitae tempus quam pellentesque.
+        Placerat orci nulla pellentesque dignissim enim sit amet. Feugiat
+        pretium nibh ipsum consequat. Placerat orci nulla pellentesque
+        dignissim. Suspendisse faucibus interdum posuere lorem. Nullam non nisi
+        est sit. Turpis egestas integer eget aliquet nibh praesent. Tortor at
+        risus 'viverra adipiscing at. Eu augue ut lectus arcu bibendum at varius
+        vel' pharetra.
+      </i>
+    </p>
+  </>
+);
+
+describe("StructuredContent Accessibility", () => {
+  it("passes axe accessibility for HTML string text content", async () => {
+    const { container } = render(
+      <StructuredContent
+        calloutText="This is the callout text"
+        headingText="Heading text"
+        imageAlt="Image alt text"
+        imageAspectRatio={ImageRatios.Original}
+        imageCaption="Image caption"
+        imageCredit="Image credit"
+        imagePosition={StructuredContentImagePosition.Left}
+        imageSize={ImageSizes.Medium}
+        imageSrc="https://placeimg.com/400/300/animals"
+        bodyContent={htmlStringBodyContent}
+      />
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+
+  it("passes axe accessibility for HTML DOM text content", async () => {
+    const { container } = render(
+      <StructuredContent
+        calloutText="This is the callout text"
+        headingText="Heading text"
+        imageAlt="Image alt text"
+        imageAspectRatio={ImageRatios.Original}
+        imageCaption="Image caption"
+        imageCredit="Image credit"
+        imagePosition={StructuredContentImagePosition.Left}
+        imageSize={ImageSizes.Medium}
+        imageSrc="https://placeimg.com/400/300/animals"
+        bodyContent={htmlDOMBodyContent}
+      />
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+
+  it("passes axe accessibility without an image", async () => {
+    const { container } = render(
+      <StructuredContent
+        calloutText="This is the callout text"
+        headingText="Heading text"
+        bodyContent={htmlStringBodyContent}
+      />
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("StructuredContent", () => {
+  it("renders two headings, an image, and body text", () => {
+    render(
+      <StructuredContent
+        calloutText="This is the callout text"
+        headingText="Heading text"
+        imageAlt="Image alt text"
+        imageAspectRatio={ImageRatios.Original}
+        imageCaption="Image caption"
+        imageCredit="Image credit"
+        imagePosition={StructuredContentImagePosition.Left}
+        imageSize={ImageSizes.Medium}
+        imageSrc="https://placeimg.com/400/300/animals"
+        bodyContent={htmlStringBodyContent}
+      />
+    );
+    const mainHeading = screen.getByRole("heading", { level: 2 });
+    const calloutHeading = screen.getByRole("heading", { level: 3 });
+
+    expect(mainHeading).toHaveTextContent("Heading text");
+    expect(calloutHeading).toHaveTextContent("This is the callout text");
+    expect(screen.getByRole("img")).toBeInTheDocument();
+    expect(screen.getByText(/Lorem ipsum dolor sit amet/i)).toBeInTheDocument();
+  });
+
+  it("optionally renders without the headings", () => {
+    render(
+      <StructuredContent
+        imageAlt="Image alt text"
+        imageAspectRatio={ImageRatios.Original}
+        imageCaption="Image caption"
+        imageCredit="Image credit"
+        imagePosition={StructuredContentImagePosition.Left}
+        imageSize={ImageSizes.Medium}
+        imageSrc="https://placeimg.com/400/300/animals"
+        bodyContent={htmlStringBodyContent}
+      />
+    );
+    const mainHeading = screen.queryByRole("heading", { level: 2 });
+    const calloutHeading = screen.queryByRole("heading", { level: 3 });
+
+    expect(mainHeading).not.toBeInTheDocument();
+    expect(calloutHeading).not.toBeInTheDocument();
+    expect(screen.getByRole("img")).toBeInTheDocument();
+    expect(screen.getByText(/Lorem ipsum dolor sit amet/i)).toBeInTheDocument();
+  });
+
+  it("optionally renders without the image", () => {
+    render(
+      <StructuredContent
+        calloutText="This is the callout text"
+        headingText="Heading text"
+        bodyContent={htmlStringBodyContent}
+      />
+    );
+    const mainHeading = screen.getByRole("heading", { level: 2 });
+    const calloutHeading = screen.getByRole("heading", { level: 3 });
+
+    expect(mainHeading).toHaveTextContent("Heading text");
+    expect(calloutHeading).toHaveTextContent("This is the callout text");
+    expect(screen.queryByRole("img")).not.toBeInTheDocument();
+    expect(screen.getByText(/Lorem ipsum dolor sit amet/i)).toBeInTheDocument();
+  });
+
+  it("logs a warning when an image is used but no alt text is passed to `imageAlt`", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(
+      <StructuredContent
+        calloutText="This is the callout text"
+        headingText="Heading text"
+        imageAspectRatio={ImageRatios.Original}
+        imageCaption="Image caption"
+        imageCredit="Image credit"
+        imagePosition={StructuredContentImagePosition.Left}
+        imageSize={ImageSizes.Medium}
+        imageSrc="https://placeimg.com/400/300/animals"
+        bodyContent={htmlStringBodyContent}
+      />
+    );
+
+    expect(warn).toHaveBeenCalledWith(
+      "StructuredContent: `imageAlt` prop is required when using an image."
+    );
+    expect(screen.getByRole("img")).toBeInTheDocument();
+  });
+
+  it("renders an image wrapped in figure when provided an image caption or credit", () => {
+    const { rerender } = render(
+      <StructuredContent
+        calloutText="This is the callout text"
+        headingText="Heading text"
+        imageAlt="Image alt text"
+        imageAspectRatio={ImageRatios.Original}
+        imageCaption="Image caption"
+        imageCredit="Image credit"
+        imagePosition={StructuredContentImagePosition.Left}
+        imageSize={ImageSizes.Medium}
+        imageSrc="https://placeimg.com/400/300/animals"
+        bodyContent={htmlStringBodyContent}
+      />
+    );
+    expect(screen.getByRole("img")).toBeInTheDocument();
+    expect(screen.getByRole("figure")).toBeInTheDocument();
+    expect(screen.getByText("Image caption")).toBeInTheDocument();
+    expect(screen.getByText("Image credit")).toBeInTheDocument();
+
+    // Not passing in the image's caption
+    rerender(
+      <StructuredContent
+        calloutText="This is the callout text"
+        headingText="Heading text"
+        imageAlt="Image alt text"
+        imageAspectRatio={ImageRatios.Original}
+        imageCredit="Image credit"
+        imagePosition={StructuredContentImagePosition.Left}
+        imageSize={ImageSizes.Medium}
+        imageSrc="https://placeimg.com/400/300/animals"
+        bodyContent={htmlStringBodyContent}
+      />
+    );
+    expect(screen.getByRole("img")).toBeInTheDocument();
+    expect(screen.getByRole("figure")).toBeInTheDocument();
+    expect(screen.queryByText("Image caption")).not.toBeInTheDocument();
+    expect(screen.getByText("Image credit")).toBeInTheDocument();
+  });
+
+  it("renders a simple image element when no image caption or credit are provided", () => {
+    render(
+      <StructuredContent
+        calloutText="This is the callout text"
+        headingText="Heading text"
+        imageAlt="Image alt text"
+        imageAspectRatio={ImageRatios.Original}
+        imagePosition={StructuredContentImagePosition.Left}
+        imageSize={ImageSizes.Medium}
+        imageSrc="https://placeimg.com/400/300/animals"
+        bodyContent={htmlStringBodyContent}
+      />
+    );
+    expect(screen.getByRole("img")).toBeInTheDocument();
+    expect(screen.queryByRole("figure")).not.toBeInTheDocument();
+    expect(screen.queryByText("Image caption")).not.toBeInTheDocument();
+    expect(screen.queryByText("Image credit")).not.toBeInTheDocument();
+  });
+
+  it("renders the UI snapshot", () => {
+    const withHTMLStringContent = renderer
+      .create(
+        <StructuredContent
+          calloutText="This is the callout text"
+          headingText="Heading text"
+          id="withHTMLStringContent"
+          imageAlt="Image alt text"
+          imageAspectRatio={ImageRatios.Original}
+          imageCaption="Image caption"
+          imageCredit="Image credit"
+          imagePosition={StructuredContentImagePosition.Left}
+          imageSize={ImageSizes.Medium}
+          imageSrc="https://placeimg.com/400/300/animals"
+          bodyContent={htmlStringBodyContent}
+        />
+      )
+      .toJSON();
+    const withHTMLDOMContent = renderer
+      .create(
+        <StructuredContent
+          calloutText="This is the callout text"
+          headingText="Heading text"
+          id="withHTMLDOMContent"
+          imageAlt="Image alt text"
+          imageAspectRatio={ImageRatios.Original}
+          imageCaption="Image caption"
+          imageCredit="Image credit"
+          imagePosition={StructuredContentImagePosition.Left}
+          imageSize={ImageSizes.Medium}
+          imageSrc="https://placeimg.com/400/300/animals"
+          bodyContent={htmlDOMBodyContent}
+        />
+      )
+      .toJSON();
+    const withoutAnImage = renderer
+      .create(
+        <StructuredContent
+          calloutText="This is the callout text"
+          headingText="Heading text"
+          id="withoutAnImage"
+          bodyContent={htmlStringBodyContent}
+        />
+      )
+      .toJSON();
+    const withImageWithoutCaptionOrCredit = renderer
+      .create(
+        <StructuredContent
+          calloutText="This is the callout text"
+          headingText="Heading text"
+          id="withImageWithoutCaptionOrCredit"
+          imageAlt="Image alt text"
+          imageAspectRatio={ImageRatios.Original}
+          imagePosition={StructuredContentImagePosition.Left}
+          imageSize={ImageSizes.Medium}
+          imageSrc="https://placeimg.com/400/300/animals"
+          bodyContent={htmlStringBodyContent}
+        />
+      )
+      .toJSON();
+    const withoutHeading = renderer
+      .create(
+        <StructuredContent
+          calloutText="This is the callout text"
+          id="withoutHeading"
+          imageAlt="Image alt text"
+          imageAspectRatio={ImageRatios.Original}
+          imageCaption="Image caption"
+          imageCredit="Image credit"
+          imagePosition={StructuredContentImagePosition.Left}
+          imageSize={ImageSizes.Medium}
+          imageSrc="https://placeimg.com/400/300/animals"
+          bodyContent={htmlStringBodyContent}
+        />
+      )
+      .toJSON();
+    const withoutCalloutText = renderer
+      .create(
+        <StructuredContent
+          headingText="Heading text"
+          id="withoutCalloutText"
+          imageAlt="Image alt text"
+          imageAspectRatio={ImageRatios.Original}
+          imageCaption="Image caption"
+          imageCredit="Image credit"
+          imagePosition={StructuredContentImagePosition.Left}
+          imageSize={ImageSizes.Medium}
+          imageSrc="https://placeimg.com/400/300/animals"
+          bodyContent={htmlStringBodyContent}
+        />
+      )
+      .toJSON();
+
+    expect(withHTMLStringContent).toMatchSnapshot();
+    expect(withHTMLDOMContent).toMatchSnapshot();
+    expect(withoutAnImage).toMatchSnapshot();
+    expect(withImageWithoutCaptionOrCredit).toMatchSnapshot();
+    expect(withoutHeading).toMatchSnapshot();
+    expect(withoutCalloutText).toMatchSnapshot();
+  });
+});

package/src/components/StructuredContent/StructuredContent.tsx

@@ -0,0 +1,153 @@
+import * as React from "react";
+import { Box, useMultiStyleConfig } from "@chakra-ui/react";
+
+import Heading from "../Heading/Heading";
+import { HeadingDisplaySizes, HeadingLevels } from "../Heading/HeadingTypes";
+import Image, { ImageProps } from "../Image/Image";
+import { ImageRatios, ImageSizes } from "../Image/ImageTypes";
+import { StructuredContentImagePosition } from "./StructuredContentTypes";
+import generateUUID from "../../helpers/generateUUID";
+
+export interface StructuredContentProps {
+  /** Optional value to set the text for the callout heading text. */
+  calloutText?: string;
+  /** Additional class name for the `StructuredContent` component. */
+  className?: string;
+  /** Optional value to set the text for the main heading text. */
+  headingText?: string;
+  /** ID that other components can cross reference for accessibility purposes. */
+  id?: string;
+  /** 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. */
+  imageAlt?: string;
+  /** Optional value to control the aspect ratio of the internal `Image` component.
+   * Defaults to `ImageRatios.Square`. */
+  imageAspectRatio?: ImageRatios;
+  /** Optional value to render as a caption for the internal `Image` component. */
+  imageCaption?: string;
+  /** Optional DOM element to use instead of the DS `Image` component. */
+  imageComponent?: JSX.Element;
+  /** Optional value to render as a credit for the internal `Image` component. */
+  imageCredit?: string;
+  /** Optional value to control the positioning of the internal `Image` component.
+   * Defaults to `StructuredContentImagePosition.Left`. */
+  imagePosition?: StructuredContentImagePosition;
+  /** Optional value to control the size of the internal `Image` component.
+   * Defaults to `ImageSizes.Medium`. */
+  imageSize?: ImageSizes;
+  /** Optional value that contains the path to an image. If omitted, the internal
+   * DS `Image` component will not render. */
+  imageSrc?: string;
+  /** Required value to set the text for the body content. */
+  bodyContent: string | JSX.Element;
+}
+
+/**
+ * Internal component used in the `StructuredContent` component
+ * that renders the DS `Image` component.
+ */
+function StructuredContentImage(props: ImageProps) {
+  const {
+    additionalFigureStyles,
+    additionalImageStyles,
+    additionalWrapperStyles,
+    alt,
+    component,
+    imageAspectRatio,
+    imageCaption,
+    imageCredit,
+    imageSize,
+    src,
+  } = props;
+  return (
+    <Image
+      additionalFigureStyles={additionalFigureStyles}
+      additionalImageStyles={additionalImageStyles}
+      additionalWrapperStyles={additionalWrapperStyles}
+      alt={alt}
+      component={component}
+      imageAspectRatio={imageAspectRatio}
+      imageSize={imageSize}
+      imageCaption={imageCaption}
+      imageCredit={imageCredit}
+      src={src}
+    />
+  );
+}
+
+/**
+ * The `StructuredContent` component that displays a heading, callout content,
+ * an image, and body content. All are optional except for body content.
+ */
+export default function StructuredContent(
+  props: React.PropsWithChildren<StructuredContentProps>
+) {
+  const {
+    calloutText,
+    className,
+    headingText,
+    id = generateUUID(),
+    imageAlt = "",
+    imageAspectRatio = ImageRatios.Square,
+    imageCaption,
+    imageComponent,
+    imageCredit,
+    imagePosition = StructuredContentImagePosition.Left,
+    imageSize = ImageSizes.Medium,
+    imageSrc,
+    bodyContent,
+  } = props;
+  const hasImage = imageSrc || imageComponent;
+  const hasFigureImage = imageCaption || imageCredit;
+  const styles = useMultiStyleConfig("StructuredContent", {
+    hasFigureImage,
+    imageAspectRatio,
+    imagePosition,
+  });
+  const finalBodyContent =
+    typeof bodyContent === "string" ? (
+      <div dangerouslySetInnerHTML={{ __html: bodyContent }} />
+    ) : (
+      <Box>{bodyContent}</Box>
+    );
+
+  if (hasImage && !imageAlt) {
+    console.warn(
+      "StructuredContent: `imageAlt` prop is required when using an image."
+    );
+  }
+
+  return (
+    <Box id={id} className={className} __css={styles}>
+      {headingText && (
+        <Heading id={`${id}-heading`} level={HeadingLevels.Two}>
+          {headingText}
+        </Heading>
+      )}
+      {calloutText && (
+        <Heading
+          displaySize={HeadingDisplaySizes.Callout}
+          id={`${id}-callout`}
+          level={HeadingLevels.Three}
+        >
+          {calloutText}
+        </Heading>
+      )}
+      {hasImage && (
+        <StructuredContentImage
+          additionalFigureStyles={styles.imageFigure}
+          additionalImageStyles={styles.image}
+          additionalWrapperStyles={styles.imageWrapper}
+          alt={imageAlt}
+          component={imageComponent}
+          imageAspectRatio={imageAspectRatio}
+          imageCaption={imageCaption}
+          imageCredit={imageCredit}
+          imageSize={imageSize}
+          src={imageSrc ? imageSrc : null}
+        />
+      )}
+      {finalBodyContent}
+    </Box>
+  );
+}

package/src/components/StructuredContent/StructuredContentTypes.tsx

@@ -0,0 +1,5 @@
+export enum StructuredContentImagePosition {
+  Left = "left",
+  Right = "right",
+  Center = "center",
+}