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

package/src/components/Image/Image.tsx

@@ -1,17 +1,39 @@
-import { Box, useMultiStyleConfig } from "@chakra-ui/react";
+import { Box, chakra, useMultiStyleConfig } from "@chakra-ui/react";
 import * as React from "react";
 
 import { ImageRatios, ImageSizes, ImageTypes } from "./ImageTypes";
 
+// 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.Medium`. */
+  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 cartd image; default value is `square` */
-  imageAspectRatio?: ImageRatios;
+  aspectRatio?: ImageRatios;
   /** Optional value to control the size of the image */
-  imageSize?: ImageSizes;
+  size?: ImageSizes;
 }
 
 export interface ImageProps extends ImageWrapperProps {
@@ -21,67 +43,72 @@ export interface ImageProps extends ImageWrapperProps {
   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> */
-  imageCaption?: string;
-  /** Adding will wrap the image in a <figure> */
-  imageCredit?: string;
-  /** Optional value to control the size of the image */
-  imageSize?: ImageSizes;
+  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;
 }
 
-function ImageWrapper(props: React.PropsWithChildren<ImageWrapperProps>) {
-  const {
-    additionalWrapperStyles = {},
-    className = "",
-    children,
-    imageAspectRatio = ImageRatios.Original,
-    imageSize = ImageSizes.Default,
-  } = props;
-  const styles = useMultiStyleConfig("CustomImageWrapper", {
-    ratio: imageAspectRatio,
-    size: imageSize,
-  });
-  return (
-    <Box
-      className={`the-wrap ${className}`}
-      __css={{ ...styles, ...additionalWrapperStyles }}
-    >
-      <Box className="the-crop" __css={styles.crop}>
-        {children}
+const ImageWrapper = chakra(
+  (props: React.PropsWithChildren<ImageWrapperProps>) => {
+    const {
+      additionalWrapperStyles = {},
+      className = "",
+      children,
+      aspectRatio = ImageRatios.Original,
+      size = ImageSizes.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>
-    </Box>
-  );
-}
+    );
+  }
+);
 
-export default function Image(props: ImageProps) {
+export const Image = chakra((props: ImageProps) => {
   const {
     additionalFigureStyles = {},
     additionalImageStyles = {},
     additionalWrapperStyles = {},
     alt,
+    aspectRatio = ImageRatios.Original,
+    caption,
     className = "",
     component,
-    imageAspectRatio = ImageRatios.Original,
-    imageCaption,
-    imageCredit,
-    imageSize = ImageSizes.Default,
+    credit,
     imageType = ImageTypes.Default,
+    size = ImageSizes.Default,
     src,
+    ...rest
   } = props;
-  const useImageWrapper = imageAspectRatio !== ImageRatios.Original;
+  const useImageWrapper = aspectRatio !== ImageRatios.Original;
   const styles = useMultiStyleConfig("CustomImage", {
     variant: imageType,
-    size: imageSize,
+    size,
   });
 
   if (alt && alt.length > 300) {
-    throw new Error("Alt Text must be less than 300 characters");
+    throw new Error(
+      "NYPL Reservoir Image: Alt text must be less than 300 characters."
+    );
   }
 
   const imageComponent: JSX.Element = component ? (
@@ -96,10 +123,11 @@ export default function Image(props: ImageProps) {
   );
   const finalImage = useImageWrapper ? (
     <ImageWrapper
-      className={className}
-      imageAspectRatio={imageAspectRatio}
-      imageSize={imageSize}
       additionalWrapperStyles={additionalWrapperStyles}
+      aspectRatio={aspectRatio}
+      className={className}
+      size={size}
+      {...(caption || credit ? {} : rest)}
     >
       {imageComponent}
     </ImageWrapper>
@@ -107,17 +135,21 @@ export default function Image(props: ImageProps) {
     imageComponent
   );
 
-  return imageCaption || imageCredit ? (
-    <Box as="figure" __css={{ ...styles.figure, ...additionalFigureStyles }}>
+  return caption || credit ? (
+    <Box
+      as="figure"
+      __css={{ ...styles.figure, ...additionalFigureStyles }}
+      {...rest}
+    >
       {finalImage}
       <Box as="figcaption" __css={styles.figcaption}>
-        {imageCaption && (
-          <Box __css={styles.captionWrappers}>{imageCaption}</Box>
-        )}
-        {imageCredit && <Box __css={styles.captionWrappers}>{imageCredit}</Box>}
+        {caption && <Box __css={styles.captionWrappers}>{caption}</Box>}
+        {credit && <Box __css={styles.captionWrappers}>{credit}</Box>}
       </Box>
     </Box>
   ) : (
     finalImage
   );
-}
+});
+
+export default Image;

package/src/components/Image/ImageTypes.ts

@@ -11,11 +11,11 @@ export enum ImageRatios {
 
 export enum ImageSizes {
   Default = "default",
-  Large = "large",
-  Medium = "medium",
-  Small = "small",
-  ExtraSmall = "xsmall",
   ExtraExtraSmall = "xxsmall",
+  ExtraSmall = "xsmall",
+  Small = "small",
+  Medium = "medium",
+  Large = "large",
 }
 
 export enum ImageTypes {

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

@@ -30,6 +30,53 @@ exports[`Image Renders the UI snapshot correctly 2`] = `
 `;
 
 exports[`Image Renders the UI snapshot correctly 3`] = `
+<figure
+  className="css-0"
+>
+  <img
+    alt=""
+    className="css-0"
+    src="test.png"
+  />
+  <figcaption
+    className="css-0"
+  >
+    <div
+      className="css-0"
+    >
+      Credit
+    </div>
+  </figcaption>
+</figure>
+`;
+
+exports[`Image Renders the UI snapshot correctly 4`] = `
+<figure
+  className="css-0"
+>
+  <img
+    alt=""
+    className="css-0"
+    src="test.png"
+  />
+  <figcaption
+    className="css-0"
+  >
+    <div
+      className="css-0"
+    >
+      Caption
+    </div>
+    <div
+      className="css-0"
+    >
+      Credit
+    </div>
+  </figcaption>
+</figure>
+`;
+
+exports[`Image Renders the UI snapshot correctly 5`] = `
 <img
   alt=""
   className="css-0"
@@ -37,7 +84,7 @@ exports[`Image Renders the UI snapshot correctly 3`] = `
 />
 `;
 
-exports[`Image Renders the UI snapshot correctly 4`] = `
+exports[`Image Renders the UI snapshot correctly 6`] = `
 <img
   alt=""
   className="css-0"
@@ -45,7 +92,7 @@ exports[`Image Renders the UI snapshot correctly 4`] = `
 />
 `;
 
-exports[`Image Renders the UI snapshot correctly 5`] = `
+exports[`Image Renders the UI snapshot correctly 7`] = `
 <img
   alt=""
   className="css-0"
@@ -53,7 +100,7 @@ exports[`Image Renders the UI snapshot correctly 5`] = `
 />
 `;
 
-exports[`Image Renders the UI snapshot correctly 6`] = `
+exports[`Image Renders the UI snapshot correctly 8`] = `
 <img
   alt=""
   className="css-0"
@@ -61,7 +108,7 @@ exports[`Image Renders the UI snapshot correctly 6`] = `
 />
 `;
 
-exports[`Image Renders the UI snapshot correctly 7`] = `
+exports[`Image Renders the UI snapshot correctly 9`] = `
 <img
   alt=""
   className="css-0"
@@ -69,9 +116,9 @@ exports[`Image Renders the UI snapshot correctly 7`] = `
 />
 `;
 
-exports[`Image Renders the UI snapshot correctly 8`] = `
+exports[`Image Renders the UI snapshot correctly 10`] = `
 <div
-  className="the-wrap  css-0"
+  className="the-wrap css-1u8qly9"
 >
   <div
     className="the-crop css-0"
@@ -85,9 +132,9 @@ exports[`Image Renders the UI snapshot correctly 8`] = `
 </div>
 `;
 
-exports[`Image Renders the UI snapshot correctly 9`] = `
+exports[`Image Renders the UI snapshot correctly 11`] = `
 <div
-  className="the-wrap  css-0"
+  className="the-wrap css-1u8qly9"
 >
   <div
     className="the-crop css-0"
@@ -101,7 +148,7 @@ exports[`Image Renders the UI snapshot correctly 9`] = `
 </div>
 `;
 
-exports[`Image Renders the UI snapshot correctly 10`] = `
+exports[`Image Renders the UI snapshot correctly 12`] = `
 <img
   alt=""
   className="css-0"
@@ -109,9 +156,9 @@ exports[`Image Renders the UI snapshot correctly 10`] = `
 />
 `;
 
-exports[`Image Renders the UI snapshot correctly 11`] = `
+exports[`Image Renders the UI snapshot correctly 13`] = `
 <div
-  className="the-wrap  css-0"
+  className="the-wrap css-1u8qly9"
 >
   <div
     className="the-crop css-0"
@@ -125,9 +172,9 @@ exports[`Image Renders the UI snapshot correctly 11`] = `
 </div>
 `;
 
-exports[`Image Renders the UI snapshot correctly 12`] = `
+exports[`Image Renders the UI snapshot correctly 14`] = `
 <div
-  className="the-wrap  css-0"
+  className="the-wrap css-1u8qly9"
 >
   <div
     className="the-crop css-0"
@@ -141,9 +188,9 @@ exports[`Image Renders the UI snapshot correctly 12`] = `
 </div>
 `;
 
-exports[`Image Renders the UI snapshot correctly 13`] = `
+exports[`Image Renders the UI snapshot correctly 15`] = `
 <div
-  className="the-wrap  css-0"
+  className="the-wrap css-1u8qly9"
 >
   <div
     className="the-crop css-0"
@@ -157,9 +204,9 @@ exports[`Image Renders the UI snapshot correctly 13`] = `
 </div>
 `;
 
-exports[`Image Renders the UI snapshot correctly 14`] = `
+exports[`Image Renders the UI snapshot correctly 16`] = `
 <div
-  className="the-wrap  css-0"
+  className="the-wrap css-1u8qly9"
 >
   <div
     className="the-crop css-0"
@@ -173,9 +220,9 @@ exports[`Image Renders the UI snapshot correctly 14`] = `
 </div>
 `;
 
-exports[`Image Renders the UI snapshot correctly 15`] = `
+exports[`Image Renders the UI snapshot correctly 17`] = `
 <div
-  className="the-wrap  css-0"
+  className="the-wrap css-1u8qly9"
 >
   <div
     className="the-crop css-0"
@@ -189,9 +236,9 @@ exports[`Image Renders the UI snapshot correctly 15`] = `
 </div>
 `;
 
-exports[`Image Renders the UI snapshot correctly 16`] = `
+exports[`Image Renders the UI snapshot correctly 18`] = `
 <div
-  className="the-wrap  css-0"
+  className="the-wrap css-1u8qly9"
 >
   <div
     className="the-crop css-0"
@@ -204,3 +251,19 @@ exports[`Image Renders the UI snapshot correctly 16`] = `
   </div>
 </div>
 `;
+
+exports[`Image Renders the UI snapshot correctly 19`] = `
+<img
+  alt=""
+  className="css-0"
+  src="test.png"
+/>
+`;
+
+exports[`Image Renders the UI snapshot correctly 20`] = `
+<img
+  alt=""
+  className="css-0"
+  src="test.png"
+/>
+`;

package/src/components/Label/Label.stories.mdx

@@ -1,4 +1,4 @@
-import { Box } from "@chakra-ui/react";
+import { Box, VStack } from "@chakra-ui/react";
 import {
   ArgsTable,
   Canvas,
@@ -19,10 +19,7 @@ import { getCategory } from "../../utils/componentCategories";
   argTypes={{
     className: { control: false },
     id: { control: false },
-    optReqFlag: {
-      control: { type: "select" },
-      options: ["Required", "Optional", ""],
-    },
+    isInlined: { table: { disable: true } },
     text: {
       description: "Only used for Storybook",
     },
@@ -34,10 +31,21 @@ import { getCategory } from "../../utils/componentCategories";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.0.10`   |
-| Latest            | `0.25.8`   |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [isRequired helper text](#isrequired-helper-text)
+
+## Overview
 
 <Description of={Label} />
 
+## Component Props
+
 <Canvas>
   <Story
     name="Label with Controls"
@@ -45,7 +53,7 @@ import { getCategory } from "../../utils/componentCategories";
       className: undefined,
       htmlFor: "id-of-input-element",
       id: "label-id",
-      optReqFlag: "Required",
+      isRequired: false,
       text: "A label for a villager.",
     }}
   >
@@ -55,24 +63,38 @@ import { getCategory } from "../../utils/componentCategories";
 
 <ArgsTable story="Label with Controls" />
 
-## Required/Optional helper text
+## Accessibility
+
+The `Label` component is an accessible HTML `<label>` element. The JSX prop
+`htmlFor` should be set to the `id` of the input element that the label is
+associated with. This is the proper way to label inputs so that screenreaders
+can read the label, without the use of the `aria-label` attribute on the input
+element.
+
+Note: All form-related Reservoir components already implement this `Label`
+component so there is no need to use this component unless if you are building
+a new form-related input component.
+
+Resources:
+
+- [WebAIM Creating Accessible Forms](https://webaim.org/techniques/forms/advanced)
+
+## isRequired helper text
 
 An optional helper string can be rendered at the end of the `Label` text through
-the `optReqFlag` prop. Pass in either `"Required"`, `"Optional"`, or `""`. The
-default value is undefined for no helper text to appear.
+the `isRequired` prop. This is useful for visually labeling a field as required
+with the `"(Required)"` text next to the label's text. This is set to `false`
+by default.
 
 <Canvas>
-  <Story name="Required/Optional helper text">
-    <Box width="300px">
-      <Label htmlFor="some-id1" optReqFlag="">
-        No text
-      </Label>
-      <Label htmlFor="some-id2" optReqFlag="Required">
-        Required helper text
+  <Story name="isRequired helper text">
+    <VStack>
+      <Label htmlFor="label-id1" id="regular">
+        A regular label
       </Label>
-      <Label htmlFor="some-id3" optReqFlag="Optional">
-        Optional helper text
+      <Label htmlFor="label-id2" id="required" isRequired>
+        A label that is required
       </Label>
-    </Box>
+    </VStack>
   </Story>
 </Canvas>

package/src/components/Label/Label.test.tsx

@@ -14,6 +14,15 @@ describe("Label Accessibility", () => {
     );
     expect(await axe(container)).toHaveNoViolations();
   });
+
+  it("passes axe accessibility test with required text", async () => {
+    const { container } = render(
+      <Label id="label" htmlFor="some-input-id" isRequired>
+        Cupcakes
+      </Label>
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
 });
 
 describe("Label", () => {
@@ -35,30 +44,33 @@ describe("Label", () => {
     expect(screen.getByText("Cupcakes")).toBeInTheDocument();
   });
 
-  it("renders the optional or required helper text", () => {
+  it("renders the '(Required)' helper text", () => {
     const { rerender } = render(
       <Label id="label" htmlFor="some-input-id">
         <span>Cupcakes</span>
       </Label>
     );
-    expect(screen.queryByText("Optional")).not.toBeInTheDocument();
-    expect(screen.queryByText("Required")).not.toBeInTheDocument();
+    expect(screen.queryByText(/Required/i)).not.toBeInTheDocument();
 
     rerender(
-      <Label id="label2" htmlFor="some-input-id" optReqFlag="Optional">
+      <Label id="label" htmlFor="some-input-id" isRequired>
         <span>Cupcakes</span>
       </Label>
     );
-    expect(screen.getByText("Optional")).toBeInTheDocument();
-    expect(screen.queryByText("Required")).not.toBeInTheDocument();
 
-    rerender(
-      <Label id="label3" htmlFor="some-input-id" optReqFlag="Required">
-        <span>Cupcakes</span>
-      </Label>
+    expect(screen.queryByText(/Required/i)).toBeInTheDocument();
+  });
+
+  it("Logs a warning when there is no `id` passed", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(
+      // @ts-ignore: Typescript complains when a required prop is not passed, but
+      // here we don't want to pass the required prop to make sure the warning appears.
+      <Label htmlFor="some-input-id">Cupcakes</Label>
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir Label: This component's required `id` prop was not passed."
     );
-    expect(screen.queryByText("Optional")).not.toBeInTheDocument();
-    expect(screen.getByText("Required")).toBeInTheDocument();
   });
 
   it("Renders the UI snapshot correctly", () => {
@@ -69,23 +81,36 @@ describe("Label", () => {
         </Label>
       )
       .toJSON();
-    const optional = renderer
+    const required = renderer
       .create(
-        <Label id="label2" htmlFor="some-input-id" optReqFlag="Optional">
+        <Label id="label3" htmlFor="some-input-id" isRequired>
           Cupcakes
         </Label>
       )
       .toJSON();
-    const required = renderer
+    const withChakraProps = renderer
+      .create(
+        <Label
+          id="chakra"
+          htmlFor="some-input-id"
+          p="20px"
+          color="ui.error.primary"
+        >
+          Cupcakes
+        </Label>
+      )
+      .toJSON();
+    const withOtherProps = renderer
       .create(
-        <Label id="label3" htmlFor="some-input-id" optReqFlag="Required">
+        <Label id="props" htmlFor="some-input-id" data-testid="props">
           Cupcakes
         </Label>
       )
       .toJSON();
 
     expect(simple).toMatchSnapshot();
-    expect(optional).toMatchSnapshot();
     expect(required).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
   });
 });

package/src/components/Label/Label.tsx

@@ -1,9 +1,5 @@
+import { Box, chakra, useStyleConfig } from "@chakra-ui/react";
 import * as React from "react";
-import { Box, useMultiStyleConfig } from "@chakra-ui/react";
-
-import generateUUID from "../../helpers/generateUUID";
-
-type optReqFlagType = "Required" | "Optional" | "" | undefined;
 
 interface LabelProps {
   /** Additional CSS class name to render in the `label` element. */
@@ -12,22 +8,34 @@ interface LabelProps {
   htmlFor: string;
   /** ID that other components can cross reference for accessibility purposes */
   id?: string;
-  /** Displays "Required" or "Optional" string alongside the label */
-  optReqFlag?: optReqFlagType;
+  /** Controls whether the label should be inline with the input it goes with.
+   * This prop should only be used internally. */
+  isInlined?: boolean;
+  /** Controls whether the "(Required)" text should be displayed alongside the
+   * label's text. False by default. */
+  isRequired?: boolean;
 }
 
 /**
  * A label for form inputs. It should never be used alone.
  */
-function Label(props: React.PropsWithChildren<LabelProps>) {
+export const Label = chakra((props: React.PropsWithChildren<LabelProps>) => {
   const {
     children,
     className,
     htmlFor,
-    id = generateUUID(),
-    optReqFlag,
+    id,
+    isInlined = false,
+    isRequired = false,
+    ...rest
   } = props;
-  const styles = useMultiStyleConfig("Label", {});
+  const styles = useStyleConfig("Label", { isInlined });
+
+  if (!id) {
+    console.warn(
+      "NYPL Reservoir Label: This component's required `id` prop was not passed."
+    );
+  }
 
   return (
     <Box
@@ -36,11 +44,12 @@ function Label(props: React.PropsWithChildren<LabelProps>) {
       className={className}
       htmlFor={htmlFor}
       __css={styles}
+      {...rest}
     >
       {children}
-      {optReqFlag && <Box __css={styles.helper}>{optReqFlag}</Box>}
+      {isRequired && <span> (Required)</span>}
     </Box>
   );
-}
+});
 
 export default Label;