@nypl/design-system-react-components 0.25.11 → 0.26.0

package/src/components/Hero/Hero.tsx

@@ -1,7 +1,8 @@
+import { Box, chakra, useMultiStyleConfig } from "@chakra-ui/react";
 import * as React from "react";
-import { Box, useMultiStyleConfig } from "@chakra-ui/react";
 
 import { HeroTypes, HeroSecondaryTypes } from "./HeroTypes";
+import Image from "../Image/Image";
 
 export interface HeroProps {
   /** Optional hex color value used to override the default background
@@ -20,11 +21,14 @@ export interface HeroProps {
   heading?: JSX.Element;
   /** Used to control how the `Hero` component will be rendered. */
   heroType?: HeroTypes;
-  /** Optional `Image` component used for SECONDARY, FIFTYFIFTY and CAMPAIGN
-   * `Hero` types; Note: `image` can only be used in conjunction with
-   * `backgroundImageSrc` for CAMPAIGN the `Hero` type.
+  /** Text description of the image; to follow best practices for accessibility,
+   * this prop should not be left blank if `imageSrc` is passed. */
+  imageAlt?: string;
+  /** Optional `imageSrc` used for SECONDARY, FIFTYFIFTY and CAMPAIGN
+   * `Hero` types; Note: `imageSrc` can only be used in conjunction with
+   * `backgroundImageSrc` for the CAMPAIGN `Hero` type.
    * Note: not all `Hero` variations utilize this prop. */
-  image?: JSX.Element;
+  imageSrc?: string;
   /** Optional details area that contains location data.
    * Note: not all `Hero` variations utilize this prop. */
   locationDetails?: JSX.Element;
@@ -45,125 +49,153 @@ for (const type in HeroTypes) {
  */
 const getVariant = (type) => variantMap[type] || HeroTypes.Primary;
 
-export default function Hero(props: React.PropsWithChildren<HeroProps>) {
-  const {
-    backgroundColor,
-    backgroundImageSrc,
-    foregroundColor,
-    heading,
-    heroType,
-    image,
-    locationDetails,
-    subHeaderText,
-  } = props;
-  const variant = getVariant(heroType);
-  const styles = useMultiStyleConfig("Hero", { variant });
-  const headingStyles = styles.heading;
-  // We want to add `Hero`-specific styling to the `Heading` component.
-  const finalHeading =
-    heading && React.cloneElement(heading, { additionalStyles: headingStyles });
-  let backgroundImageStyle = {};
-  let contentBoxStyling = {};
+export const Hero = chakra(
+  (props: React.PropsWithChildren<HeroProps>) => {
+    const {
+      backgroundColor,
+      backgroundImageSrc,
+      foregroundColor,
+      heading,
+      heroType,
+      imageAlt,
+      imageSrc,
+      locationDetails,
+      subHeaderText,
+      ...rest
+    } = props;
+    const variant = getVariant(heroType);
+    const styles = useMultiStyleConfig("Hero", { variant });
+    const headingStyles = styles.heading;
+    // We want to add `Hero`-specific styling to the `Heading` component.
+    const finalHeading =
+      heading &&
+      React.cloneElement(heading, { additionalStyles: headingStyles });
+    let backgroundImageStyle = {};
+    let contentBoxStyling = {};
 
-  if (heroType === HeroTypes.Primary) {
-    if (!backgroundImageSrc) {
+    if (imageSrc && !imageAlt) {
       console.warn(
-        `Warning: it is recommended to use the "backgroundImageSrc" prop for PRIMARY hero.`
+        `NYPL Reservoir: The "imageSrc" prop was passed but the "imageAlt" props was not. This will make the rendered image inaccessible.`
       );
     }
-    if (image) {
+
+    if (heroType === HeroTypes.Primary) {
+      if (!backgroundImageSrc) {
+        console.warn(
+          "NYPL Reservoir Hero: It is recommended to use the `backgroundImageSrc` " +
+            "prop for the `HeroTypes.Primary` `heroType` variant."
+        );
+      }
+      if (imageAlt && imageSrc) {
+        console.warn(
+          "NYPL Reservoir Hero: The `imageSrc` and `imageAlt` props have been " +
+            "passed, but the `HeroTypes.Primary` `heroType` variant will not use it."
+        );
+      }
+    } else if (locationDetails) {
       console.warn(
-        `Warning: the "image" prop has been passed, but PRIMARY hero will not use it.`
+        "NYPL Reservoir Hero: The `locationDetails` prop should only be used " +
+          "with the `HeroTypes.Primary` `heroType` variant."
+      );
+    }
+    if (HeroSecondaryTypes.includes(heroType) && backgroundImageSrc) {
+      console.warn(
+        "NYPL Reservoir Hero: The `backgroundImageSrc` prop has been passed, " +
+          "but the `HeroTypes.Secondary` `heroType` variant will not use it."
+      );
+    }
+    if (heroType === HeroTypes.Tertiary && (backgroundImageSrc || imageSrc)) {
+      console.warn(
+        "NYPL Reservoir Hero: The `HeroTypes.Tertiary` `heroType` variant hero " +
+          "will not use any of the image props."
+      );
+    }
+    if (heroType === HeroTypes.Campaign && (!backgroundImageSrc || !imageSrc)) {
+      console.warn(
+        "NYPL Reservoir Hero: It is recommended to use both the " +
+          "`backgroundImageSrc` and `imageSrc` props for the " +
+          "`HeroTypes.Campaign` `heroType` variant."
+      );
+    }
+    if (heroType === HeroTypes.FiftyFifty && backgroundImageSrc) {
+      console.warn(
+        "NYPL Reservoir Hero: The `backgroundImageSrc` prop has been passed, " +
+          "but the `HeroTypes.FiftyFifty` `heroType` variant hero will not use it."
       );
     }
-  } else if (locationDetails) {
-    console.warn(
-      `Warning: Please provide "locationDetails" only to PRIMARY hero.`
-    );
-  }
-  if (HeroSecondaryTypes.includes(heroType) && backgroundImageSrc) {
-    console.warn(
-      `Warning: the "backgroundImageSrc" prop has been passed, but SECONDARY hero will not use it.`
-    );
-  }
-  if (heroType === HeroTypes.Tertiary && (backgroundImageSrc || image)) {
-    console.warn(`Warning: TERTIARY hero will not use any of the image props.`);
-  }
-  if (heroType === HeroTypes.Campaign && (!backgroundImageSrc || !image)) {
-    console.warn(
-      `Warning: it is recommended to use both "backgroundImageSrc" and "image" props for CAMPAIGN hero.`
-    );
-  }
-  if (heroType === HeroTypes.FiftyFifty && backgroundImageSrc) {
-    console.warn(
-      `Warning: the "backgroundImageSrc" prop has been passed, but FIFTYFIFTY hero will not use it.`
-    );
-  }
 
-  if (heroType === HeroTypes.Primary) {
-    backgroundImageStyle = backgroundImageSrc
-      ? { backgroundImage: `url(${backgroundImageSrc})` }
-      : {};
-  } else if (heroType === HeroTypes.Campaign) {
-    backgroundImageStyle = backgroundImageSrc
-      ? { backgroundImage: `url(${backgroundImageSrc})` }
-      : { backgroundColor };
-  } else if (
-    heroType === HeroTypes.Tertiary ||
-    heroType === HeroTypes.FiftyFifty
-  ) {
-    backgroundImageStyle = { backgroundColor };
-  }
+    if (heroType === HeroTypes.Primary) {
+      backgroundImageStyle = backgroundImageSrc
+        ? { backgroundImage: `url(${backgroundImageSrc})` }
+        : {};
+    } else if (heroType === HeroTypes.Campaign) {
+      backgroundImageStyle = backgroundImageSrc
+        ? { backgroundImage: `url(${backgroundImageSrc})` }
+        : { backgroundColor };
+    } else if (
+      heroType === HeroTypes.Tertiary ||
+      heroType === HeroTypes.FiftyFifty
+    ) {
+      backgroundImageStyle = { backgroundColor };
+    }
 
-  if (!HeroSecondaryTypes.includes(heroType)) {
-    contentBoxStyling = {
-      color: foregroundColor,
-      backgroundColor,
-    };
-  } else if (foregroundColor || backgroundColor) {
-    console.warn(
-      `Warning: the "foregroundColor" and/or "backgroundColor" props have been passed, but SECONDARY Hero will not use them.`
-    );
-  }
+    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 `HeroTypes.Secondary` `heroType` " +
+          "variant will not use them."
+      );
+    }
 
-  const childrenToRender =
-    heroType === HeroTypes.Campaign ? (
-      <>
-        {image}
-        <Box __css={styles.interior}>
+    const childrenToRender =
+      heroType === HeroTypes.Campaign ? (
+        <>
+          <Image alt={imageAlt} src={imageSrc} />
+          <Box __css={styles.interior}>
+            {finalHeading}
+            {subHeaderText}
+          </Box>
+        </>
+      ) : (
+        <>
+          {heroType !== HeroTypes.Primary &&
+            heroType !== HeroTypes.Tertiary && (
+              <Image alt={imageAlt} src={imageSrc} />
+            )}
           {finalHeading}
-          {subHeaderText}
-        </Box>
-      </>
-    ) : (
-      <>
-        {heroType !== HeroTypes.Primary &&
-          heroType !== HeroTypes.Tertiary &&
-          image}
-        {finalHeading}
-        {heroType === HeroTypes.Tertiary && subHeaderText ? (
-          <p>{subHeaderText}</p>
-        ) : (
-          <Box __css={styles.bodyText}>{subHeaderText}</Box>
-        )}
-      </>
-    );
+          {heroType === HeroTypes.Tertiary && subHeaderText ? (
+            <p>{subHeaderText}</p>
+          ) : (
+            <Box __css={styles.bodyText}>{subHeaderText}</Box>
+          )}
+        </>
+      );
 
-  return (
-    <Box
-      data-testid="hero"
-      data-responsive-background-image
-      style={backgroundImageStyle}
-      __css={styles}
-    >
+    return (
       <Box
-        data-testid="hero-content"
-        style={contentBoxStyling}
-        __css={styles.content}
+        data-testid="hero"
+        data-responsive-background-image
+        style={backgroundImageStyle}
+        __css={styles}
+        {...rest}
       >
-        {childrenToRender}
+        <Box
+          data-testid="hero-content"
+          style={contentBoxStyling}
+          __css={styles.content}
+        >
+          {childrenToRender}
+        </Box>
+        {locationDetails}
       </Box>
-      {locationDetails}
-    </Box>
-  );
-}
+    );
+  },
+  { shouldForwardProp: () => true }
+);
+
+export default Hero;

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

@@ -2,7 +2,7 @@
 
 exports[`Hero Renders the UI snapshot correctly 1`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
   data-responsive-background-image={true}
   data-testid="hero"
   style={
@@ -22,7 +22,7 @@ exports[`Hero Renders the UI snapshot correctly 1`] = `
     }
   >
     <h1
-      className="chakra-heading css-0"
+      className="chakra-heading css-1xdhyk6"
       id="primary-hero"
     >
       Hero Primary
@@ -38,7 +38,7 @@ exports[`Hero Renders the UI snapshot correctly 1`] = `
 
 exports[`Hero Renders the UI snapshot correctly 2`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
   data-responsive-background-image={true}
   data-testid="hero"
   style={Object {}}
@@ -54,7 +54,7 @@ exports[`Hero Renders the UI snapshot correctly 2`] = `
       src="https://placeimg.com/800/400/animals"
     />
     <h1
-      className="chakra-heading css-0"
+      className="chakra-heading css-1xdhyk6"
       id="secondary-hero"
     >
       Hero Secondary
@@ -70,7 +70,7 @@ exports[`Hero Renders the UI snapshot correctly 2`] = `
 
 exports[`Hero Renders the UI snapshot correctly 3`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
   data-responsive-background-image={true}
   data-testid="hero"
   style={Object {}}
@@ -86,7 +86,7 @@ exports[`Hero Renders the UI snapshot correctly 3`] = `
       src="https://placeimg.com/800/400/animals"
     />
     <h1
-      className="chakra-heading css-0"
+      className="chakra-heading css-1xdhyk6"
       id="secondary-hero"
     >
       Hero Secondary Books and More
@@ -102,7 +102,7 @@ exports[`Hero Renders the UI snapshot correctly 3`] = `
 
 exports[`Hero Renders the UI snapshot correctly 4`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
   data-responsive-background-image={true}
   data-testid="hero"
   style={Object {}}
@@ -118,7 +118,7 @@ exports[`Hero Renders the UI snapshot correctly 4`] = `
       src="https://placeimg.com/800/400/animals"
     />
     <h1
-      className="chakra-heading css-0"
+      className="chakra-heading css-1xdhyk6"
       id="secondary-hero"
     >
       Hero Secondary Locations
@@ -134,7 +134,7 @@ exports[`Hero Renders the UI snapshot correctly 4`] = `
 
 exports[`Hero Renders the UI snapshot correctly 5`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
   data-responsive-background-image={true}
   data-testid="hero"
   style={Object {}}
@@ -150,7 +150,7 @@ exports[`Hero Renders the UI snapshot correctly 5`] = `
       src="https://placeimg.com/800/400/animals"
     />
     <h1
-      className="chakra-heading css-0"
+      className="chakra-heading css-1xdhyk6"
       id="secondary-hero"
     >
       Hero Secondary
@@ -166,7 +166,7 @@ exports[`Hero Renders the UI snapshot correctly 5`] = `
 
 exports[`Hero Renders the UI snapshot correctly 6`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
   data-responsive-background-image={true}
   data-testid="hero"
   style={Object {}}
@@ -182,7 +182,7 @@ exports[`Hero Renders the UI snapshot correctly 6`] = `
       src="https://placeimg.com/800/400/animals"
     />
     <h1
-      className="chakra-heading css-0"
+      className="chakra-heading css-1xdhyk6"
       id="secondary-hero"
     >
       Hero Secondary What's On
@@ -198,7 +198,7 @@ exports[`Hero Renders the UI snapshot correctly 6`] = `
 
 exports[`Hero Renders the UI snapshot correctly 7`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
   data-responsive-background-image={true}
   data-testid="hero"
   style={
@@ -218,7 +218,7 @@ exports[`Hero Renders the UI snapshot correctly 7`] = `
     }
   >
     <h1
-      className="chakra-heading css-0"
+      className="chakra-heading css-1xdhyk6"
       id="tertiary-hero"
     >
       Hero Tertiary
@@ -232,7 +232,7 @@ exports[`Hero Renders the UI snapshot correctly 7`] = `
 
 exports[`Hero Renders the UI snapshot correctly 8`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
   data-responsive-background-image={true}
   data-testid="hero"
   style={
@@ -260,7 +260,7 @@ exports[`Hero Renders the UI snapshot correctly 8`] = `
       className="css-0"
     >
       <h1
-        className="chakra-heading css-0"
+        className="chakra-heading css-1xdhyk6"
         id="campaign-hero"
       >
         Hero Campaign
@@ -273,7 +273,7 @@ exports[`Hero Renders the UI snapshot correctly 8`] = `
 
 exports[`Hero Renders the UI snapshot correctly 9`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
   data-responsive-background-image={true}
   data-testid="hero"
   style={
@@ -305,3 +305,75 @@ exports[`Hero Renders the UI snapshot correctly 9`] = `
   </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

@@ -25,8 +25,6 @@ import { getCategory } from "../../utils/componentCategories";
   }}
   argTypes={{
     className: { control: false },
-    height: { table: { defaultValue: { summary: "2px" } } },
-    width: { table: { defaultValue: { summary: "100%" } } },
   }}
 />
 
@@ -35,7 +33,15 @@ import { getCategory } from "../../utils/componentCategories";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.23.0`   |
-| Latest            | `0.25.10`  |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+
+## Overview
 
 <Description of={HorizontalRule} />
 
@@ -44,8 +50,24 @@ The `HorizontalRule` component renders a basic `<hr>` element. The `height`,
 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) => <HorizontalRule {...args} />}</Story>
+  <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

@@ -24,23 +24,6 @@ describe("HorizontalRule", () => {
     expect(hrClass).toContain("custom-hr");
   });
 
-  it("renders with proper custom class", () => {
-    const warn = jest.spyOn(console, "warn");
-    const { rerender } = render(
-      <HorizontalRule className="custom-hr" height="20px" />
-    );
-    expect(warn).not.toHaveBeenCalledWith(
-      "`HorizontalRule`: For the `height` prop, use a whole number, a `px` " +
-        "value, a `em` value, or a `rem` value. Using the default of 2px."
-    );
-
-    rerender(<HorizontalRule className="custom-hr" height="20%" />);
-    expect(warn).toHaveBeenCalledWith(
-      "`HorizontalRule`: For the `height` prop, use a whole number, a `px` " +
-        "value, a `em` value, or a `rem` value. Using the default of 2px."
-    );
-  });
-
   it("renders the UI snapshot correctly", () => {
     const basic = renderer.create(<HorizontalRule />).toJSON();
     const updatedHeight = renderer
@@ -53,10 +36,19 @@ describe("HorizontalRule", () => {
     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();
   });
 });

package/src/components/HorizontalRule/HorizontalRule.tsx

@@ -1,5 +1,5 @@
 // HorizontalRule
-import { Box, useStyleConfig } from "@chakra-ui/react";
+import { Box, chakra, useStyleConfig } from "@chakra-ui/react";
 import * as React from "react";
 
 export interface HorizontalRuleProps {
@@ -9,35 +9,19 @@ export interface HorizontalRuleProps {
   align?: "left" | "right";
   /** ClassName you can add in addition to `horizontal-rule` */
   className?: string;
-  /** Optional height value. This value should be entered with the same
-   * formatting as a CSS height attribute except for percent values (ex. `2`,
-   * `5px`, `1.5rem`). If this prop is omitted or a percent value is used, the
-   * horizontal rule will have a default height of 2px. */
-  height?: string;
-  /** Optional width value. This value should be entered with the same
-   * formatting as a CSS width attribute (ex. `50%`, `640px`, `20rem`). If
-   * omitted, the horizontal rule will have a default width of "100%". */
-  width?: string;
 }
 
-export default function HorizontalRule(props: HorizontalRuleProps) {
-  const { align, className, height = "2px", width = "100%" } = props;
+export const HorizontalRule = chakra((props: HorizontalRuleProps) => {
+  const { align, className, ...rest } = props;
   const styles = useStyleConfig("HorizontalRule", { align });
-  let finalHeight = height;
-
-  if (height.endsWith("%")) {
-    console.warn(
-      "`HorizontalRule`: For the `height` prop, use a whole number, a `px`" +
-        " value, a `em` value, or a `rem` value. Using the default of 2px."
-    );
-    finalHeight = "2px";
-  }
 
   const finalStyles = {
     ...styles,
-    height: finalHeight,
-    width,
+    height: "2px",
+    width: "100%",
   };
 
-  return <Box as="hr" className={className} __css={finalStyles} />;
-}
+  return <Box as="hr" className={className} __css={finalStyles} {...rest} />;
+});
+
+export default HorizontalRule;