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

package/src/components/SkeletonLoader/SkeletonLoader.stories.mdx

@@ -0,0 +1,142 @@
+import { action } from "@storybook/addon-actions";
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import SimpleGrid from "../Grid/SimpleGrid";
+import SkeletonLoader from "./SkeletonLoader";
+import { getCategory } from "../../utils/componentCategories";
+
+<Meta
+  title={getCategory("SkeletonLoader")}
+  component={SkeletonLoader}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=17219%3A7",
+    },
+    jest: ["SkeletonLoader.test.tsx"],
+  }}
+  argTypes={{
+    className: { control: false },
+    contentSize: { table: { defaultValue: { summary: "3" } } },
+    headingSize: { table: { defaultValue: { summary: "1" } } },
+    imageAspectRatio: {
+      table: {
+        defaultValue: { summary: "square" },
+      },
+    },
+    isBordered: { table: { defaultValue: { summary: "false" } } },
+    layout: {
+      table: { defaultValue: { summary: "column" } },
+    },
+    showButton: { table: { defaultValue: { summary: "false" } } },
+    showContent: { table: { defaultValue: { summary: "true" } } },
+    showHeading: { table: { defaultValue: { summary: "true" } } },
+    showImage: { table: { defaultValue: { summary: "true" } } },
+  }}
+/>
+
+# SkeletonLoader
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.17.3`   |
+| Latest            | `0.28.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Card Placeholders in a Grid](#card-placeholders-in-a-grid)
+- [Text Placeholders in a List](#text-placeholders-in-a-list)
+
+## Overview
+
+<Description of={SkeletonLoader} />
+
+The `layout`, `width`, and placeholder elements within the `SkeletonLoader` can
+be customized.
+
+Please note that the initial rendering below has the `width` prop set to `300px`
+to better view the example. The default value is `100%`.
+
+## Component Props
+
+<Canvas withToolbar>
+  <Story
+    name="SkeletonLoader with Controls"
+    args={{
+      className: undefined,
+      contentSize: 3,
+      headingSize: 1,
+      imageAspectRatio: "square",
+      isBordered: false,
+      layout: "column",
+      showButton: false,
+      showContent: true,
+      showHeading: true,
+      showImage: true,
+      width: "300px",
+    }}
+  >
+    {(args) => <SkeletonLoader {...args} />}
+  </Story>
+</Canvas>
+
+<ArgsTable story="SkeletonLoader with Controls" />
+
+## Accessibility
+
+According to W3C's success criterion 2.2.2 for operable user interfaces:
+
+> For any moving, blinking or scrolling information that (1) starts automatically,
+> (2) lasts more than five seconds, and (3) is presented in parallel with other
+> content, there is a mechanism for the user to pause, stop, or hide it unless
+> the movement, blinking, or scrolling is part of an activity where it is essential;
+
+The `SkeletonLoader` component can be used as a placeholder for local content
+that is loaded in parallel but it typically does not last more than five (5)
+seconds. For the DS usage, this is purely a visual cue and should not be picked
+up by screen readers.
+
+Resources:
+
+- [W3C Perceivable Pause, Stop, Hide](https://www.w3.org/TR/WCAG/#pause-stop-hide)
+- [More Accessible Skeletons](https://adrianroselli.com/2020/11/more-accessible-skeletons.html)
+
+## Card Placeholders in a Grid
+
+<Canvas>
+  <Story name="Placeholders in a Grid">
+    <SimpleGrid columns={3}>
+      <SkeletonLoader imageAspectRatio="landscape" isBordered />
+      <SkeletonLoader imageAspectRatio="landscape" isBordered />
+      <SkeletonLoader imageAspectRatio="landscape" isBordered />
+      <SkeletonLoader imageAspectRatio="landscape" isBordered />
+      <SkeletonLoader imageAspectRatio="landscape" isBordered />
+      <SkeletonLoader imageAspectRatio="landscape" isBordered />
+    </SimpleGrid>
+  </Story>
+</Canvas>
+
+## Text Placeholders in a List
+
+<Canvas>
+  <Story name="Placeholders in a List">
+    <SimpleGrid columns={1}>
+      <SkeletonLoader layout="row" showImage={false} />
+      <SkeletonLoader layout="row" showImage={false} />
+      <SkeletonLoader layout="row" showImage={false} />
+      <SkeletonLoader layout="row" showImage={false} />
+      <SkeletonLoader layout="row" showImage={false} />
+    </SimpleGrid>
+  </Story>
+</Canvas>

package/src/components/SkeletonLoader/SkeletonLoader.test.tsx

@@ -0,0 +1,116 @@
+import * as React from "react";
+import { render } from "@testing-library/react";
+import { axe } from "jest-axe";
+import renderer from "react-test-renderer";
+
+import SkeletonLoader from "./SkeletonLoader";
+
+describe("SkeletonLoader Accessibility", () => {
+  it("passes axe accessibility test", async () => {
+    const { container } = render(<SkeletonLoader />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("SkeletonLoader", () => {
+  it("renders default layout", () => {
+    const { container } = render(
+      <SkeletonLoader className="skeleton-loader" />
+    );
+
+    expect(container.querySelector(".skeleton-loader")).toBeInTheDocument();
+  });
+
+  it("renders in the column or row layout", () => {
+    const { container, rerender } = render(<SkeletonLoader layout="column" />);
+
+    expect(container.querySelector(".column")).toBeInTheDocument();
+
+    rerender(<SkeletonLoader layout="row" />);
+    expect(container.querySelector(".row")).toBeInTheDocument();
+  });
+
+  it("renders default elements", () => {
+    const { container } = render(<SkeletonLoader />);
+
+    // By default, the `SkeletonLoader` renders one image, one heading, and
+    // three content elements.
+    expect(container.querySelectorAll(".chakra-skeleton")).toHaveLength(5);
+  });
+
+  it("renders without image", () => {
+    const { container } = render(<SkeletonLoader showImage={false} />);
+
+    // Only one image is rendered by default.
+    expect(container.querySelectorAll(".chakra-skeleton")).toHaveLength(4);
+  });
+
+  it("renders without heading", () => {
+    const { container } = render(<SkeletonLoader showHeading={false} />);
+
+    // Only one heading is rendered by default.
+    expect(container.querySelectorAll(".chakra-skeleton")).toHaveLength(4);
+  });
+
+  it("renders without content", () => {
+    const { container } = render(<SkeletonLoader showContent={false} />);
+
+    // Three content placeholders are rendered by default.
+    expect(container.querySelectorAll(".chakra-skeleton")).toHaveLength(2);
+  });
+
+  it("renders with button", () => {
+    const { container } = render(<SkeletonLoader showButton={true} />);
+
+    // Only one button is rendered by default.
+    expect(container.querySelectorAll(".chakra-skeleton")).toHaveLength(6);
+  });
+
+  it("renders the UI snapshot correctly", () => {
+    const basic = renderer.create(<SkeletonLoader />).toJSON();
+    const rowLayout = renderer.create(<SkeletonLoader layout="row" />).toJSON();
+    const columnLayout = renderer
+      .create(<SkeletonLoader layout="column" />)
+      .toJSON();
+    const noImage = renderer
+      .create(<SkeletonLoader showImage={false} />)
+      .toJSON();
+    const noHeading = renderer
+      .create(<SkeletonLoader showHeading={false} />)
+      .toJSON();
+    const noContent = renderer
+      .create(<SkeletonLoader showContent={false} />)
+      .toJSON();
+    const withButton = renderer
+      .create(<SkeletonLoader showButton={true} />)
+      .toJSON();
+    const landscape = renderer
+      .create(<SkeletonLoader imageAspectRatio="landscape" />)
+      .toJSON();
+    const portrait = renderer
+      .create(<SkeletonLoader imageAspectRatio="portrait" />)
+      .toJSON();
+    const square = renderer
+      .create(<SkeletonLoader imageAspectRatio="square" />)
+      .toJSON();
+    const withChakraProps = renderer
+      .create(<SkeletonLoader p="20px" color="ui.error.primary" />)
+      .toJSON();
+    const withOtherProps = renderer
+      .create(<SkeletonLoader data-testid="props" />)
+      .toJSON();
+
+    expect(basic).toMatchSnapshot();
+    expect(rowLayout).toMatchSnapshot();
+    expect(columnLayout).toMatchSnapshot();
+    expect(noImage).toMatchSnapshot();
+    expect(noHeading).toMatchSnapshot();
+    expect(noContent).toMatchSnapshot();
+    expect(withButton).toMatchSnapshot();
+    expect(landscape).toMatchSnapshot();
+    expect(portrait).toMatchSnapshot();
+    expect(square).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
+  });
+});

package/src/components/SkeletonLoader/SkeletonLoader.tsx

@@ -0,0 +1,123 @@
+import {
+  Box,
+  chakra,
+  Skeleton as ChakraSkeleton,
+  useMultiStyleConfig,
+} from "@chakra-ui/react";
+import * as React from "react";
+
+import { LayoutTypes } from "../../helpers/types";
+
+export type SkeletonLoaderImageRatios = "landscape" | "portrait" | "square";
+
+export interface SkeletonLoaderProps {
+  /** Additional class name for the Skeleton component. */
+  className?: string;
+  /** Optional numeric value to control the number of lines for content
+   * placeholder; default value is `3`. */
+  contentSize?: number;
+  /** Optional numeric value to control the number of lines for heading
+   * placeholder; default value is `1`. */
+  headingSize?: number;
+  /** Optional value to control the aspect ratio of the image placeholder;
+   * default value is `"square"`. */
+  imageAspectRatio?: SkeletonLoaderImageRatios;
+  /** Optional boolean value to control visibility of border around skeleton loader. */
+  isBordered?: boolean;
+  /** Optional value to control the position of the image placeholder;
+   * default value is `"column"`. */
+  layout?: LayoutTypes;
+  /** Optional boolean value to control visibility of button placeholder. */
+  showButton?: boolean;
+  /** Optional boolean value to control visibility of content placeholder. */
+  showContent?: boolean;
+  /** Optional boolean value to control visibility of heading placeholder. */
+  showHeading?: boolean;
+  /** Optional boolean value to control visibility of image placeholder. */
+  showImage?: boolean;
+  /** Optional width value. This value should be entered with the same
+   * formatting as a CSS width attribute (ex. `50%`, `640px`, `20rem`).
+   * If omitted, the skeleton loader will have a default width of 100%. */
+  width?: string;
+}
+
+/**
+ * The `SkeletonLoader` component renders a placeholder to be used while
+ * dynamic content is loading.
+ */
+export const SkeletonLoader = chakra(
+  (props: React.PropsWithChildren<SkeletonLoaderProps>) => {
+    const {
+      className,
+      contentSize = 3,
+      headingSize = 1,
+      imageAspectRatio = "square",
+      isBordered = false,
+      layout = "column",
+      showButton = false,
+      showContent = true,
+      showHeading = true,
+      showImage = true,
+      width,
+      ...rest
+    } = props;
+    const styles = useMultiStyleConfig("SkeletonLoader", {
+      isBordered,
+      imageAspectRatio,
+      showImage,
+      variant: layout,
+    });
+
+    /**
+     * Generates the Chakra skeleton loader `size` number of times for the
+     * "heading" and "content" areas defined by the `type` argument. The last
+     * element will have width of `lastWidth`.
+     */
+    const getSkeletonElements = (type: string, size = 1, lastWidth = "80%") => {
+      return new Array(size).fill(null).map((_, i) => {
+        const width = i === size - 1 ? lastWidth : "100%";
+        const marginBottomValue =
+          i === size - 1 && type === "content" ? "0" : undefined;
+        return (
+          <ChakraSkeleton key={`${type}-${i}`} width={width}>
+            <Box
+              __css={styles[type]}
+              style={{ marginBottom: marginBottomValue }}
+            />
+          </ChakraSkeleton>
+        );
+      });
+    };
+
+    return (
+      <Box className={className} __css={styles} style={{ width }} {...rest}>
+        {showImage && (
+          <ChakraSkeleton>
+            <Box __css={{ ...styles.element, ...styles.image }} />
+          </ChakraSkeleton>
+        )}
+        <Box className={layout} __css={styles.container}>
+          {showHeading && (
+            <Box __css={styles.section}>
+              {getSkeletonElements("heading", headingSize, "80%")}
+            </Box>
+          )}
+          {showContent && (
+            <Box __css={styles.section}>
+              {getSkeletonElements("content", contentSize, "30%")}
+            </Box>
+          )}
+          {showButton && (
+            <Box __css={{ ...styles.section, ...styles.button }}>
+              <ChakraSkeleton borderRadius="16px">
+                <Box __css={styles.button} />
+              </ChakraSkeleton>
+            </Box>
+          )}
+        </Box>
+      </Box>
+    );
+  }
+);
+
+export default SkeletonLoader;