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

package/src/components/Card/Card.tsx

@@ -1,209 +1,259 @@
 import * as React from "react";
-import bem from "../../utils/bem";
+import {
+  Box,
+  LinkBox as ChakraLinkBox,
+  LinkOverlay as ChakraLinkOverlay,
+  useMultiStyleConfig,
+  useStyleConfig,
+} from "@chakra-ui/react";
 
-import { CardImageRatios, CardImageSizes, CardLayouts } from "./CardTypes";
+import { CardLayouts } from "./CardTypes";
 import Heading from "../Heading/Heading";
-import Image from "../Image/Image";
-
-interface CardImageProps {
-  /** Text description of the image */
-  alt: string;
-  /** Custom image component used in place of DS `Image` component */
-  component?: React.ReactNode;
-  /** 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?: CardImageRatios;
-  /** Optional value to control the size of the card image */
-  imageSize?: CardImageSizes;
-  /** The src attribute is required, and contains the path to the image you want to embed. */
-  src: string;
+import Image, { ImageProps } from "../Image/Image";
+import { ImageRatios, ImageSizes } from "../Image/ImageTypes";
+import generateUUID from "../../helpers/generateUUID";
+
+interface CardBaseProps {
+  /** Optional value to control the alignment of the text and elements. */
+  center?: boolean;
+  /** Optional value to render the layout in a row or column (default). */
+  layout?: CardLayouts;
 }
 
-interface CardContentProps {
-  /** Optional className that would be applied to the `card-content` element */
-  className?: string;
+interface CardLinkBoxProps {
+  /** Main link to use when the full `Card` component should be clickable. */
+  mainActionLink?: string;
 }
 
-interface CardActionsProps {
-  /** Optional boolean value to control visibility of border on the bottom edge of the card actions element */
+interface CardActionsProps extends CardBaseProps {
+  /** Optional boolean value to control visibility of border on the bottom edge
+   * of the card actions element */
   bottomBorder?: boolean;
-  /** Optional className that would be applied to the `card-actions` element */
-  className?: string;
-  /** Modifiers array for use with BEM. See how to work with modifiers and BEM here: http://getbem.com/introduction/ */
-  modifiers?: string[];
-  /** Optional boolean value to control visibility of border on the top edge of the card actions element */
+  /** Optional boolean value to control visibility of border on the top edge of
+   * the card actions element */
   topBorder?: boolean;
 }
 
-export interface CardProps {
-  /** Optional hex color value used to set the card background color */
+interface CardImageProps extends CardBaseProps, ImageProps {
+  /** Optional boolean value to control the position of the `CardImage`. */
+  imageAtEnd?: boolean;
+}
+
+export interface CardProps extends CardBaseProps, CardLinkBoxProps {
+  /** Optional hex color value used to set the card background color. */
   backgroundColor?: string;
-  /** BlockName for use with BEM. See how to work with blockNames and BEM here: http://getbem.com/introduction/ */
-  blockName?: string;
-  /** Optional boolean value to control the visibility of a border around the card */
+  /** Optional boolean value to control the visibility of a border around
+   * the card. */
   border?: boolean;
-  /** Optional boolean value to control the alignment of the text and elements within the card */
-  center?: boolean;
-  /** ClassName that appears in addition to "card" */
+  /** Optional CSS class name to add. */
   className?: string;
-  /** Optional hex color value used to override the default text color */
+  /** Optional hex color value used to override the default text color. */
   foregroundColor?: string;
-  /** ID that other components can cross reference for accessibility purposes */
+  /** ID that other components can cross reference for accessibility purposes. */
   id?: string;
-  /** Text description of the image; to follow best practices for accessibility, this prop should not be left blank if `imageSrc` is passed */
+  /** 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 value to control the aspect ratio of the card image; default value is `square` */
-  imageAspectRatio?: CardImageRatios;
-  /** Optional boolean value to control the position of the card image */
+  /** Optional value to control the aspect ratio of the `CardIage`; default
+   * value is `square`. */
+  imageAspectRatio?: ImageRatios;
+  /** Optional boolean value to control the position of the `CardImage`. */
   imageAtEnd?: boolean;
-  /** Custom image component used in place of DS `Image` component */
-  imageComponent?: React.ReactNode;
-  /** Optional value to control the size of the card image */
-  imageSize?: CardImageSizes;
-  /** The path to the image displayed with the card */
+  /** Custom image component used in place of DS `Image` component. */
+  imageComponent?: JSX.Element;
+  /** Optional value to control the size of the `CardImage`. */
+  imageSize?: ImageSizes;
+  /** The path to the image displayed within the `Card` component. */
   imageSrc?: string;
-  /** Optional value to control the position of the image placeholder; default value is `column` */
-  layout?: CardLayouts;
-  /** Modifiers array for use with BEM. See how to work with modifiers and BEM here: http://getbem.com/introduction/ */
-  modifiers?: string[];
-  /** Optional padding value.  This value should be entered with the same formatting as a CSS padding attribute (ex. `5%`, `20px`, `2rem`).  If omitted, the Card will use the default padding. */
-  padding?: string;
 }
 
-// CardImage component
-export function CardImage(props: React.PropsWithChildren<CardImageProps>) {
-  const { src, alt, className, imageAspectRatio, imageSize, component } = props;
-  const classNames = ["image-wrap"];
-  imageAspectRatio && classNames.push(`image-wrap--` + imageAspectRatio);
-  const imageModifiers = [];
-  imageSize && imageModifiers.push(imageSize);
+/**
+ * The CardImage component is used internally in the `Card` component. It
+ * renders an `Image` component but with overriding styles specific to the
+ * `Card` component.
+ */
+function CardImage(props: React.ComponentProps<"img"> & CardImageProps) {
+  const {
+    alt,
+    center,
+    component,
+    imageSize,
+    imageAspectRatio,
+    src,
+    imageAtEnd,
+    layout,
+  } = props;
+  // Additional styles to add to the `Image` component.
+  const styles = useStyleConfig("CardImage", {
+    center,
+    imageAtEnd,
+    imageSize,
+    layout,
+  });
   return (
-    (src || component) && (
-      <>
-        <div className={bem("image", imageModifiers, "card", [])}>
-          <div className={classNames.join(" ")}>
-            <div className="image-crop">
-              {component ? (
-                component
-              ) : (
-                <Image className={className} src={src} alt={alt} />
-              )}
-            </div>
-          </div>
-        </div>
-      </>
-    )
+    <Image
+      alt={alt}
+      component={component}
+      imageAspectRatio={imageAspectRatio}
+      imageSize={imageSize}
+      src={src}
+      additionalStyles={styles}
+    />
   );
 }
 
 // CardHeading child-component
-export const CardHeading = (props) => <Heading {...props} />;
+export const CardHeading = Heading;
 
 // CardContent child-component
-export function CardContent(props: React.PropsWithChildren<CardContentProps>) {
-  const { children, className } = props;
-  return (
-    children && (
-      <div className={bem("card-content", [], "", [className])}>{children}</div>
-    )
-  );
+export function CardContent(props: React.PropsWithChildren<{}>) {
+  const { children } = props;
+  const styles = useStyleConfig("CardContent");
+  return children && <Box __css={styles}>{children}</Box>;
 }
 
 // CardActions child-component
 export function CardActions(props: React.PropsWithChildren<CardActionsProps>) {
-  const {
+  const { bottomBorder, children, topBorder, center, layout } = props;
+  const styles = useStyleConfig("CardActions", {
     bottomBorder,
-    children,
-    className,
-    modifiers = [],
     topBorder,
-  } = props;
+    center,
+    layout,
+  });
 
-  bottomBorder && modifiers.push("bottom-border");
-  topBorder && modifiers.push("top-border");
+  return children && <Box __css={styles}>{children}</Box>;
+}
 
-  return (
-    children && (
-      <div className={bem("card-actions", modifiers, "", [className])}>
-        {children}
-      </div>
-    )
+/**
+ * If `mainActionLink` is passed, then this adds Chakra's `LinkBox` wrapper
+ * component to the entire `Card` component. This works together with the
+ * `CardLinkOverlay` component to provide a clickable overlay.
+ */
+function CardLinkBox({
+  children,
+  mainActionLink,
+}: React.PropsWithChildren<CardLinkBoxProps>) {
+  return mainActionLink ? (
+    <ChakraLinkBox>{children}</ChakraLinkBox>
+  ) : (
+    <>{children}</>
+  );
+}
+
+/**
+ * If `mainActionLink` is passed, then this adds Chakra's `LinkOverlay` around
+ * text that should be linked, in this case the `CardHeading` text. This works
+ * together with the `CardLinkBox` component to provide a clickable overlay to
+ * the `Card` component while still allowing links in the `CardActions` to be
+ * clickable.
+ */
+function CardLinkOverlay({
+  children,
+  mainActionLink,
+}: React.PropsWithChildren<CardLinkBoxProps>) {
+  return mainActionLink ? (
+    <ChakraLinkOverlay href={mainActionLink}>{children}</ChakraLinkOverlay>
+  ) : (
+    <>{children}</>
   );
 }
 
 export default function Card(props: React.PropsWithChildren<CardProps>) {
   const {
     backgroundColor,
-    blockName,
-    center,
+    border,
+    center = false,
     children,
     className,
     foregroundColor,
-    id,
+    id = generateUUID(),
+    imageAlt = "",
+    imageAspectRatio = ImageRatios.Square,
     imageAtEnd,
-    layout,
-    border,
-    padding,
-    modifiers = [],
-    imageAlt,
     imageComponent,
-    imageAspectRatio,
-    imageSize,
+    imageSize = ImageSizes.Default,
     imageSrc,
+    layout = CardLayouts.Column,
+    mainActionLink,
   } = props;
-  const baseClass = "card";
-
-  const styles = {};
-  let imageCount = 0;
+  const hasImage = imageSrc || imageComponent;
+  const customColors = {};
   const cardContents = [];
+  let cardHeadingCount = 0;
 
-  layout && modifiers.push(layout);
-  border && modifiers.push("with-border");
-  center && modifiers.push("center");
-  (imageSrc || imageComponent) && modifiers.push("has-image");
-  imageAtEnd && modifiers.push("at-end");
+  backgroundColor && (customColors["backgroundColor"] = backgroundColor);
+  foregroundColor && (customColors["color"] = foregroundColor);
 
-  padding && (styles["padding"] = padding);
-  backgroundColor && (styles["backgroundColor"] = backgroundColor);
-  foregroundColor && (styles["color"] = foregroundColor);
+  const styles = useMultiStyleConfig("Card", {
+    border,
+    center,
+    hasImage,
+    imageAtEnd,
+    layout,
+  });
 
-  React.Children.map(children, (child: React.ReactElement) => {
-    if (
-      child.type === CardHeading ||
-      child.props.mdxType === "CardHeading" ||
+  React.Children.map(children, (child: React.ReactElement, key) => {
+    if (child.type === CardHeading || child.props.mdxType === "CardHeading") {
+      // If the child is a `CardHeading` component, then we add the
+      // `CardLinkOverlay` inside of the `Heading` component and wrap its text.
+      // This allows other links in the `CardActions` to be clickable. This is
+      // only done for the first `CardHeading` component but does not affect
+      // the full-click feature.
+      const newChildren =
+        cardHeadingCount === 0 ? (
+          <CardLinkOverlay mainActionLink={mainActionLink}>
+            {child.props.children}
+          </CardLinkOverlay>
+        ) : (
+          child.props.children
+        );
+      const elem = React.cloneElement(child, {
+        additionalStyles: styles.heading,
+        key,
+        center,
+        // Override the child text with the potential `CardLinkOverlay`.
+        children: newChildren,
+        layout,
+      });
+      cardContents.push(elem);
+      cardHeadingCount++;
+    } else if (
       child.type === CardContent ||
       child.props.mdxType === "CardContent" ||
       child.type === CardActions ||
       child.props.mdxType === "CardActions"
     ) {
-      cardContents.push(child);
+      const elem = React.cloneElement(child, { key, center, layout });
+      cardContents.push(elem);
     }
   });
 
-  if (imageCount > 1) {
-    console.error(`Only one CardIimage child component may be passed to Card.`);
-    cardContents.length = 0;
-    cardContents.push(
-      "Error: Only one CardImage child component may be passed to Card."
-    );
-  }
   return (
-    <div
-      className={bem(baseClass, modifiers, blockName, [className])}
-      id={id}
-      style={styles}
-    >
-      {(imageSrc || imageComponent) && (
-        <CardImage
-          src={imageSrc ? imageSrc : null}
-          component={imageComponent ? imageComponent : null}
-          alt={imageAlt ? imageAlt : null}
-          imageSize={imageSize ? imageSize : null}
-          imageAspectRatio={imageAspectRatio ? imageAspectRatio : null}
-        />
-      )}
-      <div className={bem("body", [], baseClass)}>{cardContents}</div>
-    </div>
+    <CardLinkBox mainActionLink={mainActionLink}>
+      <Box
+        id={id}
+        className={className}
+        __css={{
+          ...styles,
+          ...customColors,
+        }}
+      >
+        {hasImage && (
+          <CardImage
+            src={imageSrc ? imageSrc : null}
+            component={imageComponent}
+            alt={imageAlt}
+            imageSize={imageSize}
+            imageAspectRatio={imageAspectRatio}
+            imageAtEnd={imageAtEnd}
+            layout={layout}
+          />
+        )}
+        <Box className="card-body" __css={styles.body}>
+          {cardContents}
+        </Box>
+      </Box>
+    </CardLinkBox>
   );
 }

package/src/components/Card/CardTypes.tsx

@@ -2,20 +2,3 @@ export enum CardLayouts {
   Row = "row",
   Column = "column",
 }
-
-export enum CardImageRatios {
-  FourByThree = "four-by-three",
-  OneByTwo = "one-by-two",
-  Original = "original",
-  SixteenByNine = "sixteen-by-nine",
-  Square = "square",
-  ThreeByFour = "three-by-four",
-  ThreeByTwo = "three-by-two",
-  TwoByOne = "two-by-one",
-}
-
-export enum CardImageSizes {
-  Large = "large",
-  Medium = "medium",
-  Small = "small",
-}