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

package/src/components/Hero/Hero.tsx

@@ -2,6 +2,7 @@ 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;
@@ -52,7 +56,8 @@ export default function Hero(props: React.PropsWithChildren<HeroProps>) {
     foregroundColor,
     heading,
     heroType,
-    image,
+    imageAlt,
+    imageSrc,
     locationDetails,
     subHeaderText,
   } = props;
@@ -65,38 +70,54 @@ export default function Hero(props: React.PropsWithChildren<HeroProps>) {
   let backgroundImageStyle = {};
   let contentBoxStyling = {};
 
+  if (imageSrc && !imageAlt) {
+    console.warn(
+      `NYPL Reservoir: The "imageSrc" prop was passed but the "imageAlt" props was not. This will make the rendered image inaccessible.`
+    );
+  }
+
   if (heroType === HeroTypes.Primary) {
     if (!backgroundImageSrc) {
       console.warn(
-        `Warning: it is recommended to use the "backgroundImageSrc" prop for PRIMARY hero.`
+        "NYPL Reservoir Hero: It is recommended to use the `backgroundImageSrc` " +
+          "prop for the `HeroTypes.Primary` `heroType` variant."
       );
     }
-    if (image) {
+    if (imageAlt && imageSrc) {
       console.warn(
-        `Warning: the "image" prop has been passed, but PRIMARY hero will not use it.`
+        "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: Please provide "locationDetails" only to PRIMARY hero.`
+      "NYPL Reservoir Hero: The `locationDetails` prop should only be used " +
+        "with the `HeroTypes.Primary` `heroType` variant."
     );
   }
   if (HeroSecondaryTypes.includes(heroType) && backgroundImageSrc) {
     console.warn(
-      `Warning: the "backgroundImageSrc" prop has been passed, but SECONDARY hero will not use it.`
+      "NYPL Reservoir Hero: The `backgroundImageSrc` prop has been passed, " +
+        "but the `HeroTypes.Secondary` `heroType` variant 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.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 || !image)) {
+  if (heroType === HeroTypes.Campaign && (!backgroundImageSrc || !imageSrc)) {
     console.warn(
-      `Warning: it is recommended to use both "backgroundImageSrc" and "image" props for CAMPAIGN hero.`
+      "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(
-      `Warning: the "backgroundImageSrc" prop has been passed, but FIFTYFIFTY hero will not use it.`
+      "NYPL Reservoir Hero: The `backgroundImageSrc` prop has been passed, " +
+        "but the `HeroTypes.FiftyFifty` `heroType` variant hero will not use it."
     );
   }
 
@@ -122,14 +143,16 @@ export default function Hero(props: React.PropsWithChildren<HeroProps>) {
     };
   } else if (foregroundColor || backgroundColor) {
     console.warn(
-      `Warning: the "foregroundColor" and/or "backgroundColor" props have been passed, but SECONDARY Hero will not use them.`
+      "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}
+        <Image alt={imageAlt} src={imageSrc} />
         <Box __css={styles.interior}>
           {finalHeading}
           {subHeaderText}
@@ -137,9 +160,9 @@ export default function Hero(props: React.PropsWithChildren<HeroProps>) {
       </>
     ) : (
       <>
-        {heroType !== HeroTypes.Primary &&
-          heroType !== HeroTypes.Tertiary &&
-          image}
+        {heroType !== HeroTypes.Primary && heroType !== HeroTypes.Tertiary && (
+          <Image alt={imageAlt} src={imageSrc} />
+        )}
         {finalHeading}
         {heroType === HeroTypes.Tertiary && subHeaderText ? (
           <p>{subHeaderText}</p>

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

@@ -30,14 +30,16 @@ describe("HorizontalRule", () => {
       <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."
+      "NYPL Reservoir HorizontalRule: An invalid value was passed for the " +
+        "`height` prop, so the default value of 2px will be used.  A valid " +
+        "value should be a whole number, a `px` value, a `em` value, or a `rem` value."
     );
 
     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."
+      "NYPL Reservoir HorizontalRule: An invalid value was passed for the " +
+        "`height` prop, so the default value of 2px will be used.  A valid " +
+        "value should be a whole number, a `px` value, a `em` value, or a `rem` value."
     );
   });
 

package/src/components/HorizontalRule/HorizontalRule.tsx

@@ -27,8 +27,9 @@ export default function HorizontalRule(props: HorizontalRuleProps) {
 
   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."
+      "NYPL Reservoir HorizontalRule: An invalid value was passed for the " +
+        "`height` prop, so the default value of 2px will be used.  A valid " +
+        "value should be a whole number, a `px` value, a `em` value, or a `rem` value."
     );
     finalHeight = "2px";
   }

package/src/components/Icons/Icon.stories.mdx

@@ -7,6 +7,8 @@ import {
 } from "@storybook/addon-docs";
 import { withDesign } from "storybook-addon-designs";
 
+import Heading from "../Heading/Heading";
+import { HeadingLevels } from "../Heading/HeadingTypes";
 import Icon from "./Icon";
 import {
   IconAlign,
@@ -89,7 +91,7 @@ export const rotationEnumValues = getStorybookEnumValues(
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.0.4`    |
-| Latest            | `0.25.12`  |
+| Latest            | `0.25.13`  |
 
 <Description of={Icon} />
 
@@ -105,7 +107,7 @@ export const rotationEnumValues = getStorybookEnumValues(
       iconRotation: "IconRotationTypes.Rotate0",
       id: "icon-id",
       name: "IconNames.Check",
-      size: "IconSizes.ExtraLarge",
+      size: "IconSizes.ExtraExtraLarge",
       title: undefined,
       type: IconTypes.Default,
     }}
@@ -128,7 +130,7 @@ export const rotationEnumValues = getStorybookEnumValues(
 export const iconRow = (icon, iconType = IconNames, opts = {}) => {
   // We'll use this setup function to render all the icons in a list item.
   // Some icons display better with a dark background.
-  const styles = { padding: "1rem" };
+  const styles = { display: "block" };
   const {
     size = IconSizes.Large,
     iconRotation = IconRotationTypes.Rotate0,
@@ -138,6 +140,7 @@ export const iconRow = (icon, iconType = IconNames, opts = {}) => {
   let key = icon;
   if (icon.indexOf("Negative") !== -1 || color.indexOf("white") !== -1) {
     styles.backgroundColor = "#000";
+    styles.padding = "1rem";
   }
   // The following is just to fix duplicate React key issues.
   if (iconRotation !== IconRotationTypes.Rotate0) {
@@ -150,7 +153,11 @@ export const iconRow = (icon, iconType = IconNames, opts = {}) => {
     key += `-${size}`;
   }
   return (
-    <li key={key} style={{ marginBottom: "var(--nypl-space-s)" }}>
+    <li
+      key={key}
+      style={{ marginBottom: "var(--nypl-space-l)", textAlign: "center" }}
+    >
+      <Heading level={HeadingLevels.Four}>{displayValue}</Heading>
       <span style={styles}>
         <Icon
           name={iconType[icon]}
@@ -159,7 +166,6 @@ export const iconRow = (icon, iconType = IconNames, opts = {}) => {
           color={color}
         />
       </span>
-      {displayValue}
     </li>
   );
 };
@@ -168,30 +174,36 @@ export const rotations = [];
 export const colors = [];
 export const sizes = [];
 for (const icon in IconNames) {
-  icons.push(iconRow(icon, IconNames, { displayValue: `IconNames.${icon}` }));
+  icons.push(
+    iconRow(icon, IconNames, {
+      displayValue: `IconNames.${icon}`,
+      size: IconSizes.ExtraExtraLarge,
+    })
+  );
 }
 for (const iconRotation in IconRotationTypes) {
   rotations.push(
     iconRow("Arrow", IconNames, {
-      size: IconSizes.Large,
-      iconRotation: IconRotationTypes[iconRotation],
       displayValue: `IconRotationTypes.${iconRotation}`,
+      iconRotation: IconRotationTypes[iconRotation],
+      size: IconSizes.ExtraExtraLarge,
     })
   );
 }
 for (const iconColor in IconColors) {
   colors.push(
-    iconRow("Download", IconNames, {
+    iconRow("ErrorFilled", IconNames, {
       color: IconColors[iconColor],
       displayValue: `IconColors.${iconColor}`,
+      size: IconSizes.ExtraExtraLarge,
     })
   );
 }
 for (const iconSize in IconSizes) {
   sizes.push(
-    iconRow("Arrow", IconNames, {
-      size: IconSizes[iconSize],
+    iconRow("ActionCheckCircle", IconNames, {
       displayValue: `IconSizes.${iconSize}`,
+      size: IconSizes[iconSize],
     })
   );
 }
@@ -214,13 +226,20 @@ Passing an `iconRotation` prop with a value from `IconRotationTypes` allows
 the icon to be rotated when it is rendered. The `IconRotationTypes` enum
 can be found in `src/components/Icons/IconTypes.tsx`.
 
+Note: All of the examples below have been rendered with the `size` prop set to
+`IconSizes.ExtraExtraLarge`.
+
 ```jsx
 // Example
-<Icon name={IconNames.Arrow} iconRotation={IconRotationTypes.Rotate180} />
+<Icon
+  iconRotation={IconRotationTypes.Rotate180}
+  name={IconNames.Arrow}
+  size={IconSizes.ExtraExtraLarge}
+/>
 ```
 
 <Canvas>
-  <Story name="Rotation Types">{allIconsType(rotations)}</Story>
+  <Story name="Icon Rotation">{allIconsType(rotations)}</Story>
 </Canvas>
 
 ## IconColors Types
@@ -228,13 +247,20 @@ can be found in `src/components/Icons/IconTypes.tsx`.
 Update an SVG icon by passing a `color` prop with a value from `IconColors`.
 The `IconColors` enum can be found in `src/components/Icons/IconTypes.tsx`.
 
+Note: All of the examples below have been rendered with the `size` prop set to
+`IconSizes.ExtraExtraLarge`.
+
 ```jsx
 // Example
-<Icon name={IconNames.Speaker_notes} color={IconColors.BrandPrimary} />
+<Icon
+  color={IconColors.BrandPrimary}
+  name={IconNames.ErrorFilled}
+  size={IconSizes.ExtraExtraLarge}
+/>
 ```
 
 <Canvas>
-  <Story name="Color Types">{allIconsType(colors)}</Story>
+  <Story name="Icon Colors">{allIconsType(colors)}</Story>
 </Canvas>
 
 ## IconSizes Types
@@ -242,13 +268,16 @@ The `IconColors` enum can be found in `src/components/Icons/IconTypes.tsx`.
 Update an SVG icon by passing a `size` prop with a value from `IconSizes`.
 The `IconSizes` enum can be found in`src/components/Icons/IconTypes.tsx`.
 
+Note: `IconSizes.Default` sets the width to `100%` and the rendered icon will
+expand to fill the full width of the parent element.
+
 ```jsx
 // Example
-<Icon name={IconNames.Clock} size={IconSizes.ExtraExtraLarge} />
+<Icon name={IconNames.ActionCheckCircle} size={IconSizes.ExtraExtraLarge} />
 ```
 
 <Canvas>
-  <Story name="Sizes Types">{allIconsType(sizes)}</Story>
+  <Story name="Icon Sizes">{allIconsType(sizes)}</Story>
 </Canvas>
 
 ## All Display Icons
@@ -256,8 +285,11 @@ The `IconSizes` enum can be found in`src/components/Icons/IconTypes.tsx`.
 The following icons are for generic purposes. All the available icon names can
 be found in the `IconNames` enum in `src/components/Icons/IconTypes.tsx`.
 
+Note: All of the examples below have been rendered with the `size` prop set to
+`IconSizes.ExtraExtraLarge`.
+
 <Canvas withToolbar>
-  <Story name="All Display Icons">{allIconsType(icons)}</Story>
+  <Story name="All Icons">{allIconsType(icons)}</Story>
 </Canvas>
 
 ## Custom Icons

package/src/components/Icons/Icon.test.tsx

@@ -27,7 +27,8 @@ describe("Icon", () => {
       </Icon>
     );
     expect(warn).toHaveBeenCalledWith(
-      "Icon accepts either a `name` prop or an `svg` element child, not both."
+      "NYPL Reservoir Icon: Pass in either a `name` prop or an `svg` element " +
+        "child. Do not pass both."
     );
   });
 
@@ -35,7 +36,17 @@ describe("Icon", () => {
     const warn = jest.spyOn(console, "warn");
     render(<Icon />);
     expect(warn).toHaveBeenCalledWith(
-      "Icon: Pass an icon `name` prop or an SVG child to ensure an icon appears."
+      "NYPL Reservoir Icon: Pass an icon `name` prop or an SVG child to " +
+        "ensure an icon appears."
+    );
+  });
+
+  it("consoles a warning if name is not passed and a child is but it's not an SVG element", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(<Icon>Not an SVG</Icon>);
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir Icon: An `svg` element must be passed to the `Icon` " +
+        "component as its child."
     );
   });
 

package/src/components/Icons/Icon.tsx

@@ -54,7 +54,7 @@ export default function Icon(props: React.PropsWithChildren<IconProps>) {
     iconRotation = IconRotationTypes.Rotate0,
     id = generateUUID(),
     name,
-    size = IconSizes.Medium,
+    size = IconSizes.Default,
     title = `${name} icon`,
     type = IconTypes.Default,
   } = props;
@@ -77,12 +77,14 @@ export default function Icon(props: React.PropsWithChildren<IconProps>) {
   // Component prop validation
   if (name && children) {
     console.warn(
-      "Icon accepts either a `name` prop or an `svg` element child, not both."
+      "NYPL Reservoir Icon: Pass in either a `name` prop or an `svg` element " +
+        "child. Do not pass both."
     );
     return null;
   } else if (!name && !children) {
     console.warn(
-      "Icon: Pass an icon `name` prop or an SVG child to ensure an icon appears."
+      "NYPL Reservoir Icon: Pass an icon `name` prop or an SVG child to " +
+        "ensure an icon appears."
     );
     return null;
   }
@@ -105,14 +107,17 @@ export default function Icon(props: React.PropsWithChildren<IconProps>) {
   // Apply icon props to the SVG child.
   if (
     (children as JSX.Element).type === "svg" ||
-    (children as JSX.Element).props.type === "svg" ||
-    (children as JSX.Element).props.mdxType === "svg"
+    (children as JSX.Element).props?.type === "svg" ||
+    (children as JSX.Element).props?.mdxType === "svg"
   ) {
     childSVG = React.cloneElement(children as JSX.Element, {
       ...iconProps,
     });
   } else {
-    console.warn("You must pass an `svg` element to the `Icon` component.");
+    console.warn(
+      "NYPL Reservoir Icon: An `svg` element must be passed to the `Icon` " +
+        "component as its child."
+    );
   }
 
   return <Box __css={styles}>{childSVG}</Box>;

package/src/components/Icons/IconTypes.tsx

@@ -40,6 +40,7 @@ export enum IconColors {
 }
 
 export enum IconSizes {
+  Default = "default",
   Small = "small",
   Medium = "medium",
   Large = "large",