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

package/src/components/Hero/Hero.tsx

@@ -0,0 +1,203 @@
+import { Box, chakra, useMultiStyleConfig } from "@chakra-ui/react";
+import * as React from "react";
+
+import Image, { ComponentImageProps } from "../Image/Image";
+
+export type HeroTypes =
+  | "primary"
+  | "secondary"
+  | "secondaryBooksAndMore"
+  | "secondaryLocations"
+  | "secondaryResearch"
+  | "secondaryWhatsOn"
+  | "tertiary"
+  | "campaign"
+  | "fiftyFifty";
+// Only used for internal purposes.
+export const heroSecondaryTypes = [
+  "secondary",
+  "secondaryBooksAndMore",
+  "secondaryLocations",
+  "secondaryResearch",
+  "secondaryWhatsOn",
+];
+export interface HeroImageProps
+  extends Pick<ComponentImageProps, "alt" | "src"> {}
+export interface HeroProps {
+  /** Optional hex color value used to override the default background
+   * color for a given `Hero` variation.
+   * Note: not all `Hero` variations utilize this prop. */
+  backgroundColor?: string;
+  /** Optional path to an image that will be used as a background image for the
+   * `Hero` component.
+   * Note: not all `Hero` variations utilize this prop. */
+  backgroundImageSrc?: string;
+  /** Optional hex color value used to override the default text color for a
+   * given `Hero` variation.
+   * Note: not all `Hero` variations utilize this prop. */
+  foregroundColor?: string;
+  /** Optional heading element. */
+  heading?: JSX.Element;
+  /** Used to control how the `Hero` component will be rendered. */
+  heroType?: HeroTypes;
+  /** Object used to create and render the `Image` component. Note that only
+   * `src` and `alt` are the available attributes to pass. If `imageProps.alt`
+   * is left blank, a warning will be logged to the console and will cause
+   * accessibility issues. For `imageProps.src`, it will only work for the
+   * "secondary", "fiftyFifty" and "campaign" `Hero` types; Note: `imageProps.src`
+   * can only be used in conjunction with `backgroundImageSrc` for the "campaign"
+   * `Hero` type. Note: not all `Hero` variations utilize this prop. */
+  imageProps?: HeroImageProps;
+  /** Optional details area that contains location data.
+   * Note: not all `Hero` variations utilize this prop. */
+  locationDetails?: JSX.Element;
+  /** Optional string used for the subheader that displays
+   * underneath the heading element. */
+  subHeaderText?: string | JSX.Element;
+}
+
+export const Hero = chakra(
+  (props: React.PropsWithChildren<HeroProps>) => {
+    const {
+      backgroundColor,
+      backgroundImageSrc,
+      foregroundColor,
+      heading,
+      heroType,
+      imageProps = {
+        alt: "",
+        src: "",
+      },
+      locationDetails,
+      subHeaderText,
+      ...rest
+    } = props;
+    const styles = useMultiStyleConfig("Hero", { variant: heroType });
+    const headingStyles = styles.heading;
+    // We want to add `Hero`-specific styling to the `Heading` component.
+    const finalHeading =
+      heading && React.cloneElement(heading, { __css: headingStyles });
+    let backgroundImageStyle = {};
+    let contentBoxStyling = {};
+
+    if (imageProps.src && !imageProps.alt) {
+      console.warn(
+        `NYPL Reservoir Hero: The "imageProps.src" prop was passed but the "imageProps.alt" props was not. This will make the rendered image inaccessible.`
+      );
+    }
+
+    if (heroType === "primary") {
+      if (!backgroundImageSrc) {
+        console.warn(
+          "NYPL Reservoir Hero: It is recommended to use the `backgroundImageSrc` " +
+            "prop for the `'primary'` `heroType` variant."
+        );
+      }
+      if (imageProps.alt && imageProps.src) {
+        console.warn(
+          "NYPL Reservoir Hero: The `imageProps.src` and `imageProps.alt` props have been " +
+            "passed, but the `'primary'` `heroType` variant will not use it."
+        );
+      }
+    } else if (locationDetails) {
+      console.warn(
+        "NYPL Reservoir Hero: The `locationDetails` prop should only be used " +
+          "with the `'primary'` `heroType` variant."
+      );
+    }
+    if (heroSecondaryTypes.includes(heroType) && backgroundImageSrc) {
+      console.warn(
+        "NYPL Reservoir Hero: The `backgroundImageSrc` prop has been passed, " +
+          "but the `'secondary'` `heroType` variant will not use it."
+      );
+    }
+    if (heroType === "tertiary" && (backgroundImageSrc || imageProps.src)) {
+      console.warn(
+        "NYPL Reservoir Hero: The `'tertiary'` `heroType` variant hero " +
+          "will not use any of the image props."
+      );
+    }
+    if (heroType === "campaign" && (!backgroundImageSrc || !imageProps.src)) {
+      console.warn(
+        "NYPL Reservoir Hero: It is recommended to use both the " +
+          "`backgroundImageSrc` and `imageProps.src` props for the " +
+          "`'campaign'` `heroType` variant."
+      );
+    }
+    if (heroType === "fiftyFifty" && backgroundImageSrc) {
+      console.warn(
+        "NYPL Reservoir Hero: The `backgroundImageSrc` prop has been passed, " +
+          "but the `'fiftyFifty'` `heroType` variant hero will not use it."
+      );
+    }
+
+    if (heroType === "primary") {
+      backgroundImageStyle = backgroundImageSrc
+        ? { backgroundImage: `url(${backgroundImageSrc})` }
+        : {};
+    } else if (heroType === "campaign") {
+      backgroundImageStyle = backgroundImageSrc
+        ? { backgroundImage: `url(${backgroundImageSrc})` }
+        : { backgroundColor };
+    } else if (heroType === "tertiary" || heroType === "fiftyFifty") {
+      backgroundImageStyle = { backgroundColor };
+    }
+
+    if (!heroSecondaryTypes.includes(heroType)) {
+      contentBoxStyling = {
+        color: foregroundColor,
+        backgroundColor,
+      };
+    } else if (foregroundColor || backgroundColor) {
+      console.warn(
+        "NYPL Reservoir Hero: The `foregroundColor` and/or `backgroundColor` " +
+          "props have been passed, but the `'secondary'` `heroType` " +
+          "variant will not use them."
+      );
+    }
+
+    const childrenToRender =
+      heroType === "campaign" ? (
+        <>
+          <Image alt={imageProps.alt} src={imageProps.src} />
+          <Box __css={styles.interior}>
+            {finalHeading}
+            {subHeaderText}
+          </Box>
+        </>
+      ) : (
+        <>
+          {heroType !== "primary" && heroType !== "tertiary" && (
+            <Image alt={imageProps.alt} src={imageProps.src} />
+          )}
+          {finalHeading}
+          {heroType === "tertiary" && subHeaderText ? (
+            <p>{subHeaderText}</p>
+          ) : (
+            <Box __css={styles.bodyText}>{subHeaderText}</Box>
+          )}
+        </>
+      );
+
+    return (
+      <Box
+        data-testid="hero"
+        data-responsive-background-image
+        style={backgroundImageStyle}
+        __css={styles}
+        {...rest}
+      >
+        <Box
+          data-testid="hero-content"
+          style={contentBoxStyling}
+          __css={styles.content}
+        >
+          {childrenToRender}
+        </Box>
+      </Box>
+    );
+  },
+  { shouldForwardProp: () => true }
+);
+
+export default Hero;

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

@@ -0,0 +1,379 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Hero Renders the UI snapshot correctly 1`] = `
+<div
+  className="css-1xdhyk6"
+  data-responsive-background-image={true}
+  data-testid="hero"
+  style={
+    Object {
+      "backgroundImage": "url(https://placeimg.com/1600/800/arch)",
+    }
+  }
+>
+  <div
+    className="css-0"
+    data-testid="hero-content"
+    style={
+      Object {
+        "backgroundColor": undefined,
+        "color": undefined,
+      }
+    }
+  >
+    <h1
+      className="chakra-heading css-1xdhyk6"
+      id="primary-hero"
+    >
+      Hero Primary
+    </h1>
+    <div
+      className="css-0"
+    >
+      Example Subtitle
+    </div>
+  </div>
+</div>
+`;
+
+exports[`Hero Renders the UI snapshot correctly 2`] = `
+<div
+  className="css-1xdhyk6"
+  data-responsive-background-image={true}
+  data-testid="hero"
+  style={Object {}}
+>
+  <div
+    className="css-0"
+    data-testid="hero-content"
+    style={Object {}}
+  >
+    <img
+      alt="Image example"
+      className="css-0"
+      src="https://placeimg.com/800/400/animals"
+    />
+    <h1
+      className="chakra-heading css-1xdhyk6"
+      id="secondary-hero"
+    >
+      Hero Secondary
+    </h1>
+    <div
+      className="css-0"
+    >
+      Explore our collection of hundreds of online resources and databases. Use our free online content to help with your research, whether it's finding a single article, tracing a family tree, learning a new language, or anything in between.
+    </div>
+  </div>
+</div>
+`;
+
+exports[`Hero Renders the UI snapshot correctly 3`] = `
+<div
+  className="css-1xdhyk6"
+  data-responsive-background-image={true}
+  data-testid="hero"
+  style={Object {}}
+>
+  <div
+    className="css-0"
+    data-testid="hero-content"
+    style={Object {}}
+  >
+    <img
+      alt="Image example"
+      className="css-0"
+      src="https://placeimg.com/800/400/animals"
+    />
+    <h1
+      className="chakra-heading css-1xdhyk6"
+      id="secondary-hero"
+    >
+      Hero Secondary Books and More
+    </h1>
+    <div
+      className="css-0"
+    >
+      Explore our collection of hundreds of online resources and databases. Use our free online content to help with your research, whether it's finding a single article, tracing a family tree, learning a new language, or anything in between.
+    </div>
+  </div>
+</div>
+`;
+
+exports[`Hero Renders the UI snapshot correctly 4`] = `
+<div
+  className="css-1xdhyk6"
+  data-responsive-background-image={true}
+  data-testid="hero"
+  style={Object {}}
+>
+  <div
+    className="css-0"
+    data-testid="hero-content"
+    style={Object {}}
+  >
+    <img
+      alt="Image example"
+      className="css-0"
+      src="https://placeimg.com/800/400/animals"
+    />
+    <h1
+      className="chakra-heading css-1xdhyk6"
+      id="secondary-hero"
+    >
+      Hero Secondary Locations
+    </h1>
+    <div
+      className="css-0"
+    >
+      Explore our collection of hundreds of online resources and databases. Use our free online content to help with your research, whether it's finding a single article, tracing a family tree, learning a new language, or anything in between.
+    </div>
+  </div>
+</div>
+`;
+
+exports[`Hero Renders the UI snapshot correctly 5`] = `
+<div
+  className="css-1xdhyk6"
+  data-responsive-background-image={true}
+  data-testid="hero"
+  style={Object {}}
+>
+  <div
+    className="css-0"
+    data-testid="hero-content"
+    style={Object {}}
+  >
+    <img
+      alt="Image example"
+      className="css-0"
+      src="https://placeimg.com/800/400/animals"
+    />
+    <h1
+      className="chakra-heading css-1xdhyk6"
+      id="secondary-hero"
+    >
+      Hero Secondary
+    </h1>
+    <div
+      className="css-0"
+    >
+      Explore our collection of hundreds of online resources and databases. Use our free online content to help with your research, whether it's finding a single article, tracing a family tree, learning a new language, or anything in between.
+    </div>
+  </div>
+</div>
+`;
+
+exports[`Hero Renders the UI snapshot correctly 6`] = `
+<div
+  className="css-1xdhyk6"
+  data-responsive-background-image={true}
+  data-testid="hero"
+  style={Object {}}
+>
+  <div
+    className="css-0"
+    data-testid="hero-content"
+    style={Object {}}
+  >
+    <img
+      alt="Image example"
+      className="css-0"
+      src="https://placeimg.com/800/400/animals"
+    />
+    <h1
+      className="chakra-heading css-1xdhyk6"
+      id="secondary-hero"
+    >
+      Hero Secondary What's On
+    </h1>
+    <div
+      className="css-0"
+    >
+      Explore our collection of hundreds of online resources and databases. Use our free online content to help with your research, whether it's finding a single article, tracing a family tree, learning a new language, or anything in between.
+    </div>
+  </div>
+</div>
+`;
+
+exports[`Hero Renders the UI snapshot correctly 7`] = `
+<div
+  className="css-1xdhyk6"
+  data-responsive-background-image={true}
+  data-testid="hero"
+  style={
+    Object {
+      "backgroundColor": undefined,
+    }
+  }
+>
+  <div
+    className="css-0"
+    data-testid="hero-content"
+    style={
+      Object {
+        "backgroundColor": undefined,
+        "color": undefined,
+      }
+    }
+  >
+    <h1
+      className="chakra-heading css-1xdhyk6"
+      id="tertiary-hero"
+    >
+      Hero Tertiary
+    </h1>
+    <p>
+      With 92 locations across the Bronx, Manhattan, and Staten Island, The New York Public Library is an essential part of neighborhoods across the city. Visit us today.
+    </p>
+  </div>
+</div>
+`;
+
+exports[`Hero Renders the UI snapshot correctly 8`] = `
+<div
+  className="css-1xdhyk6"
+  data-responsive-background-image={true}
+  data-testid="hero"
+  style={
+    Object {
+      "backgroundImage": "url(https://placeimg.com/2400/800/nature/grayscale)",
+    }
+  }
+>
+  <div
+    className="css-0"
+    data-testid="hero-content"
+    style={
+      Object {
+        "backgroundColor": undefined,
+        "color": undefined,
+      }
+    }
+  >
+    <img
+      alt="Image example"
+      className="css-0"
+      src="https://placeimg.com/800/400/animals"
+    />
+    <div
+      className="css-0"
+    >
+      <h1
+        className="chakra-heading css-1xdhyk6"
+        id="campaign-hero"
+      >
+        Hero Campaign
+      </h1>
+      With 92 locations across the Bronx, Manhattan, and Staten Island, The New York Public Library is an essential part of neighborhoods across the city. Visit us today.
+    </div>
+  </div>
+</div>
+`;
+
+exports[`Hero Renders the UI snapshot correctly 9`] = `
+<div
+  className="css-1xdhyk6"
+  data-responsive-background-image={true}
+  data-testid="hero"
+  style={
+    Object {
+      "backgroundColor": undefined,
+    }
+  }
+>
+  <div
+    className="css-0"
+    data-testid="hero-content"
+    style={
+      Object {
+        "backgroundColor": undefined,
+        "color": undefined,
+      }
+    }
+  >
+    <img
+      alt="Image example"
+      className="css-0"
+      src="https://placeimg.com/800/400/animals"
+    />
+    <div
+      className="css-0"
+    >
+      With 92 locations across the Bronx, Manhattan, and Staten Island, The New York Public Library is an essential part of neighborhoods across the city. Visit us today.
+    </div>
+  </div>
+</div>
+`;
+
+exports[`Hero Renders the UI snapshot correctly 10`] = `
+<div
+  className="css-16h1ce8"
+  data-responsive-background-image={true}
+  data-testid="hero"
+  style={
+    Object {
+      "backgroundImage": "url(https://placeimg.com/1600/800/arch)",
+    }
+  }
+>
+  <div
+    className="css-0"
+    data-testid="hero-content"
+    style={
+      Object {
+        "backgroundColor": undefined,
+        "color": undefined,
+      }
+    }
+  >
+    <h1
+      className="chakra-heading css-1xdhyk6"
+      id="chakra"
+    >
+      Hero Primary
+    </h1>
+    <div
+      className="css-0"
+    >
+      Example Subtitle
+    </div>
+  </div>
+</div>
+`;
+
+exports[`Hero Renders the UI snapshot correctly 11`] = `
+<div
+  className="css-1xdhyk6"
+  data-responsive-background-image={true}
+  data-testid="props"
+  style={
+    Object {
+      "backgroundImage": "url(https://placeimg.com/1600/800/arch)",
+    }
+  }
+>
+  <div
+    className="css-0"
+    data-testid="hero-content"
+    style={
+      Object {
+        "backgroundColor": undefined,
+        "color": undefined,
+      }
+    }
+  >
+    <h1
+      className="chakra-heading css-1xdhyk6"
+      id="props"
+    >
+      Hero Primary
+    </h1>
+    <div
+      className="css-0"
+    >
+      Example Subtitle
+    </div>
+  </div>
+</div>
+`;

package/src/components/HorizontalRule/HorizontalRule.stories.mdx

@@ -0,0 +1,73 @@
+import { action } from "@storybook/addon-actions";
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import HorizontalRule from "./HorizontalRule";
+import SimpleGrid from "../Grid/SimpleGrid";
+import { getCategory } from "../../utils/componentCategories";
+
+<Meta
+  title={getCategory("HorizontalRule")}
+  component={HorizontalRule}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=19659%3A0",
+    },
+    jest: ["HorizontalRule.test.tsx"],
+  }}
+  argTypes={{
+    className: { control: false },
+  }}
+/>
+
+# Horizontal Rule
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.23.0`   |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+
+## Overview
+
+<Description of={HorizontalRule} />
+
+The `HorizontalRule` component renders a basic `<hr>` element. The `height`,
+`width`, and `align` props can be customized. For the `height` prop, use a whole
+number, a `px` value, a `em` value, or a `rem` value. Otherwise, the default
+value of "2px" will be used.
+
+## Component Props
+
+<Canvas withToolbar>
+  <Story name="HorizontalRule" args={{ align: "left" }}>
+    {(args) => <HorizontalRule {...args} />}
+  </Story>
+</Canvas>
+
+<ArgsTable story="HorizontalRule" />
+
+## Accessibility
+
+The `HorizontalRule` component is not just a visual thematic break between
+content or interfaces, it is also picked up by screenreaders. Internally, the
+`HorizontalRule` component uses the `<hr>` element which has a `role` of
+`"separator"`.
+
+Resources:
+
+- [MDN hr: The Thematic Break (Horizontal Rule) element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/hr)
+- [Not Your Typical Horizontal Rules](https://www.sarasoueidan.com/blog/horizontal-rules/#)

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

@@ -0,0 +1,54 @@
+import * as React from "react";
+import { render, screen } from "@testing-library/react";
+import { axe } from "jest-axe";
+import renderer from "react-test-renderer";
+
+import HorizontalRule from "./HorizontalRule";
+
+describe("HorizontalRule Accessibility", () => {
+  it("passes axe accessibility test", async () => {
+    const { container } = render(<HorizontalRule />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("HorizontalRule", () => {
+  it("renders HorizontalRule component", () => {
+    render(<HorizontalRule />);
+    expect(screen.getByRole("separator")).toBeInTheDocument();
+  });
+
+  it("renders with proper custom class", () => {
+    render(<HorizontalRule className="custom-hr" />);
+    const hrClass = screen.getByRole("separator").getAttribute("class");
+    expect(hrClass).toContain("custom-hr");
+  });
+
+  it("renders the UI snapshot correctly", () => {
+    const basic = renderer.create(<HorizontalRule />).toJSON();
+    const updatedHeight = renderer
+      .create(<HorizontalRule height="5rem" />)
+      .toJSON();
+    const updatedWidth = renderer
+      .create(<HorizontalRule width="720px" />)
+      .toJSON();
+    const alignLeft = renderer.create(<HorizontalRule align="left" />).toJSON();
+    const alignRight = renderer
+      .create(<HorizontalRule align="right" />)
+      .toJSON();
+    const withChakraProps = renderer
+      .create(<HorizontalRule p="20px" color="ui.error.primary" />)
+      .toJSON();
+    const withOtherProps = renderer
+      .create(<HorizontalRule data-testid="props" />)
+      .toJSON();
+
+    expect(basic).toMatchSnapshot();
+    expect(updatedHeight).toMatchSnapshot();
+    expect(updatedWidth).toMatchSnapshot();
+    expect(alignLeft).toMatchSnapshot();
+    expect(alignRight).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
+  });
+});