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

package/src/components/Template/Template.test.tsx

@@ -0,0 +1,309 @@
+import * as React from "react";
+import { render, screen } from "@testing-library/react";
+import { axe } from "jest-axe";
+import renderer from "react-test-renderer";
+
+import {
+  Template,
+  TemplateAboveHeader,
+  TemplateHeader,
+  TemplateBreakout,
+  TemplateContent,
+  TemplateContentTop,
+  TemplateContentPrimary,
+  TemplateContentSidebar,
+  TemplateFooter,
+  TemplateAppContainer,
+} from "./Template";
+import Placeholder from "../Placeholder/Placeholder";
+
+const aboveHeader = <Placeholder variant="short">Above Header</Placeholder>;
+const header = <Placeholder variant="short">NYPL Header</Placeholder>;
+const breakout = (
+  <>
+    <Placeholder variant="short">Breadcrumbs</Placeholder>
+    <Placeholder variant="short">Hero</Placeholder>
+  </>
+);
+const sidebar = "left";
+const contentTop = <Placeholder>Content Top</Placeholder>;
+const contentSidebar = <Placeholder>Left Sidebar</Placeholder>;
+const contentPrimary = (
+  <>
+    <Placeholder>Main Content</Placeholder>
+    <Placeholder variant="short">More Content</Placeholder>
+  </>
+);
+const footer = <Placeholder variant="short">Footer</Placeholder>;
+
+describe("TemplateAppContainer accessibility", () => {
+  it("passes axe accessibility test", async () => {
+    const { container } = render(
+      <TemplateAppContainer
+        aboveHeader={aboveHeader}
+        header={header}
+        breakout={breakout}
+        sidebar={sidebar}
+        contentTop={contentTop}
+        contentSidebar={contentSidebar}
+        contentPrimary={contentPrimary}
+        footer={footer}
+      />
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("Template components accessibility", () => {
+  it("passes axe accessibility test", async () => {
+    const { container } = render(
+      <Template>
+        <TemplateAboveHeader>{aboveHeader}</TemplateAboveHeader>
+        <TemplateHeader>
+          {header}
+          <TemplateBreakout>{breakout}</TemplateBreakout>
+        </TemplateHeader>
+        <TemplateContent sidebar={sidebar}>
+          <TemplateContentTop>{contentTop}</TemplateContentTop>
+          <TemplateContentSidebar>{contentSidebar}</TemplateContentSidebar>
+          <TemplateContentPrimary>{contentPrimary}</TemplateContentPrimary>
+        </TemplateContent>
+        <TemplateFooter>{footer}</TemplateFooter>
+      </Template>
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("TemplateAppContainer component", () => {
+  it("renders each section", () => {
+    render(
+      <TemplateAppContainer
+        aboveHeader={aboveHeader}
+        header={header}
+        breakout={breakout}
+        sidebar={sidebar}
+        contentTop={contentTop}
+        contentSidebar={contentSidebar}
+        contentPrimary={contentPrimary}
+        footer={footer}
+      />
+    );
+    expect(screen.getByText("Above Header")).toBeInTheDocument();
+    expect(screen.getByText("NYPL Header")).toBeInTheDocument();
+    expect(screen.getByText("Breadcrumbs")).toBeInTheDocument();
+    expect(screen.getByText("Hero")).toBeInTheDocument();
+    expect(screen.getByText("Content Top")).toBeInTheDocument();
+    expect(screen.getByText("Left Sidebar")).toBeInTheDocument();
+    expect(screen.getByText("Main Content")).toBeInTheDocument();
+    expect(screen.getByText("More Content")).toBeInTheDocument();
+    expect(screen.getByText("Footer")).toBeInTheDocument();
+  });
+
+  it("renders a #mainContent id in the `main` DOM element", () => {
+    const { container } = render(
+      <TemplateAppContainer
+        aboveHeader={aboveHeader}
+        header={header}
+        breakout={breakout}
+        sidebar={sidebar}
+        contentTop={contentTop}
+        contentSidebar={contentSidebar}
+        contentPrimary={contentPrimary}
+        footer={footer}
+      />
+    );
+    expect(container.querySelector("#mainContent")).toBeInTheDocument();
+    expect(screen.getByRole("main")).toHaveAttribute("id", "mainContent");
+  });
+
+  it("renders only one header in a custom header component", () => {
+    const customHeader = <header>Custom header</header>;
+    render(
+      <TemplateAppContainer
+        header={customHeader}
+        renderHeaderElement={false}
+        breakout={breakout}
+        sidebar={sidebar}
+        contentTop={contentTop}
+        contentSidebar={contentSidebar}
+        contentPrimary={contentPrimary}
+        footer={footer}
+      />
+    );
+
+    // The `<header>` HTML element has the same meaning as `role="banner"`.
+    expect(screen.getAllByRole("banner")).toHaveLength(1);
+  });
+
+  it("consoles a warning when a header element was passed without setting `renderHeaderElement` to false", () => {
+    const warn = jest.spyOn(console, "warn");
+    const customHeader = <header>Custom header</header>;
+    render(
+      <TemplateAppContainer
+        header={customHeader}
+        breakout={breakout}
+        sidebar={sidebar}
+        contentTop={contentTop}
+        contentSidebar={contentSidebar}
+        contentPrimary={contentPrimary}
+        footer={footer}
+      />
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir TemplateHeader: An HTML `header` element was passed " +
+        "in. Set `renderHeaderElement` to `false` to avoid nested HTML " +
+        "`header` elements."
+    );
+  });
+
+  it("renders only one footer in a custom footer component", () => {
+    const customFooter = <footer>Custom Footer</footer>;
+    render(
+      <TemplateAppContainer
+        header={header}
+        breakout={breakout}
+        sidebar={sidebar}
+        contentTop={contentTop}
+        contentSidebar={contentSidebar}
+        contentPrimary={contentPrimary}
+        footer={customFooter}
+        renderFooterElement={false}
+      />
+    );
+
+    expect(screen.getAllByRole("contentinfo")).toHaveLength(1);
+  });
+
+  it("consoles a warning when a footer element was passed without setting `renderFooterElement` to false", () => {
+    const warn = jest.spyOn(console, "warn");
+    const customFooter = <footer>Custom Footer</footer>;
+    render(
+      <TemplateAppContainer
+        header={header}
+        breakout={breakout}
+        sidebar={sidebar}
+        contentTop={contentTop}
+        contentSidebar={contentSidebar}
+        contentPrimary={contentPrimary}
+        footer={customFooter}
+      />
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir TemplateFooter: An HTML `footer` element was passed " +
+        "in. Set `renderFooterElement` to `false` to avoid nested HTML " +
+        "`footer` elements."
+    );
+  });
+});
+
+describe("Template components", () => {
+  it("renders each section", () => {
+    render(
+      <Template>
+        <TemplateAboveHeader>{aboveHeader}</TemplateAboveHeader>
+        <TemplateHeader>
+          {header}
+          <TemplateBreakout>{breakout}</TemplateBreakout>
+        </TemplateHeader>
+        <TemplateContent sidebar={sidebar}>
+          <TemplateContentTop>{contentTop}</TemplateContentTop>
+          <TemplateContentSidebar>{contentSidebar}</TemplateContentSidebar>
+          <TemplateContentPrimary>{contentPrimary}</TemplateContentPrimary>
+        </TemplateContent>
+        <TemplateFooter>{footer}</TemplateFooter>
+      </Template>
+    );
+
+    expect(screen.getByText("Above Header")).toBeInTheDocument();
+    expect(screen.getByText("NYPL Header")).toBeInTheDocument();
+    expect(screen.getByText("Breadcrumbs")).toBeInTheDocument();
+    expect(screen.getByText("Hero")).toBeInTheDocument();
+    expect(screen.getByText("Content Top")).toBeInTheDocument();
+    expect(screen.getByText("Left Sidebar")).toBeInTheDocument();
+    expect(screen.getByText("Main Content")).toBeInTheDocument();
+    expect(screen.getByText("More Content")).toBeInTheDocument();
+    expect(screen.getByText("Footer")).toBeInTheDocument();
+  });
+
+  it("renders a #mainContent id in the TemplateContent component", () => {
+    const { container } = render(
+      <TemplateContent>
+        <TemplateContentPrimary>{contentPrimary}</TemplateContentPrimary>
+      </TemplateContent>
+    );
+
+    expect(container.querySelector("#mainContent")).toBeInTheDocument();
+    expect(screen.getByRole("main")).toHaveAttribute("id", "mainContent");
+  });
+
+  it("renders the UI snapshot correctly", () => {
+    const templateComponents = renderer
+      .create(
+        <Template>
+          <TemplateAboveHeader>{aboveHeader}</TemplateAboveHeader>
+          <TemplateHeader>
+            {header}
+            <TemplateBreakout>{breakout}</TemplateBreakout>
+          </TemplateHeader>
+          <TemplateContent sidebar={sidebar}>
+            <TemplateContentTop>{contentTop}</TemplateContentTop>
+            <TemplateContentSidebar>{contentSidebar}</TemplateContentSidebar>
+            <TemplateContentPrimary>{contentPrimary}</TemplateContentPrimary>
+          </TemplateContent>
+          <TemplateFooter>{footer}</TemplateFooter>
+        </Template>
+      )
+      .toJSON();
+    const singleComponent = renderer
+      .create(
+        <TemplateAppContainer
+          aboveHeader={aboveHeader}
+          header={header}
+          breakout={breakout}
+          sidebar={sidebar}
+          contentTop={contentTop}
+          contentSidebar={contentSidebar}
+          contentPrimary={contentPrimary}
+          footer={footer}
+        />
+      )
+      .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <TemplateAppContainer
+          aboveHeader={aboveHeader}
+          header={header}
+          breakout={breakout}
+          sidebar={sidebar}
+          contentTop={contentTop}
+          contentSidebar={contentSidebar}
+          contentPrimary={contentPrimary}
+          footer={footer}
+          p="20px"
+          color="ui.error.primary"
+        />
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(
+        <TemplateAppContainer
+          aboveHeader={aboveHeader}
+          header={header}
+          breakout={breakout}
+          sidebar={sidebar}
+          contentTop={contentTop}
+          contentSidebar={contentSidebar}
+          contentPrimary={contentPrimary}
+          footer={footer}
+          data-testid="props"
+        />
+      )
+      .toJSON();
+
+    expect(templateComponents).toMatchSnapshot();
+    expect(singleComponent).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
+  });
+});

package/src/components/Template/Template.tsx

@@ -0,0 +1,326 @@
+import { Box, chakra, useStyleConfig } from "@chakra-ui/react";
+import * as React from "react";
+
+import SkipNavigation from "../SkipNavigation/SkipNavigation";
+
+export interface TemplateProps {}
+export interface TemplateHeaderProps {
+  /** Flag to render an HTML header element. True by default. */
+  renderHeaderElement?: boolean;
+}
+export interface TemplateFooterProps {
+  /** Flag to render an HTML footer element. True by default. */
+  renderFooterElement?: boolean;
+}
+export interface TemplateSidebarProps {
+  /** Renders the `TemplateContentSidebar` component either on the left or
+   * right side of the `TemplateContentPrimary` component. */
+  sidebar?: "none" | "left" | "right";
+}
+export interface TemplateContentProps extends TemplateSidebarProps {
+  /** ID used for the `main` HTML element. Defaults to "mainContent". Useful
+   * anchor for the application skip navigation. */
+  id?: string;
+}
+
+export interface TemplateAppContainerProps
+  extends TemplateFooterProps,
+    TemplateHeaderProps,
+    TemplateSidebarProps {
+  /** DOM that will be rendered before the rest of the components in
+   * `TemplateAppContainer` and immediately before the `TemplateHeader` component. */
+  aboveHeader?: React.ReactElement;
+  /** DOM that will be rendered in the `TemplateBreakout` component section. */
+  breakout?: React.ReactElement;
+  /** ID used for the `main` HTML element. Defaults to "mainContent". Useful
+   * anchor for the application skip navigation. */
+  contentId?: string;
+  /** DOM that will be rendered in the `TemplateContentPrimary` component section. */
+  contentPrimary?: React.ReactElement;
+  /** DOM that will be rendered in the `TemplateContentSidebar` component section. */
+  contentSidebar?: React.ReactElement;
+  /** DOM that will be rendered in the `TemplateContentTop` component section. */
+  contentTop?: React.ReactElement;
+  /** DOM that will be rendered in the `TemplateFooter` component section. */
+  footer?: React.ReactElement;
+  /** DOM that will be rendered in the `TemplateHeader` component section. */
+  header?: React.ReactElement;
+  /** Render the `SkipNavigation` component or not. False by default. */
+  renderSkipNavigation?: boolean;
+}
+
+/**
+ * The main top-level parent component that wraps all template-related
+ * components.
+ */
+const Template = chakra((props: React.PropsWithChildren<TemplateProps>) => {
+  const styles = useStyleConfig("Template", {});
+  return (
+    <Box __css={styles} {...props}>
+      {props.children}
+    </Box>
+  );
+});
+
+/**
+ * This optional component renders its children from edge-to-edge and should
+ * be used for alerts or notifications that are typically site-wide. This must
+ * be rendered immediately before the `TemplateHeader` component. This is meant
+ * for components that render an `aside` HTML element or HTML element with the
+ * `role="complementary"` attribute. These elements should *not* be rendered
+ * in the `header` HTML section since that's an accessibility violation.
+ */
+const TemplateAboveHeader = (props: React.PropsWithChildren<TemplateProps>) => {
+  const styles = useStyleConfig("TemplateBreakout", {});
+  return <Box __css={styles}>{props.children}</Box>;
+};
+
+/**
+ * This optional component should be the first child of the `Template`
+ * component. This is rendered as an HTML `<header>` element. If an HTML
+ * `<header>` element is already passed in a custom component as the children,
+ * set `renderFooterElement` to `false`. Otherwise, the parent wrapper will
+ * render an HTML `<header>` element.
+ */
+const TemplateHeader = ({
+  children,
+  renderHeaderElement = true,
+}: React.PropsWithChildren<TemplateHeaderProps>) => {
+  const styles = useStyleConfig("TemplateHeader", {});
+  let headerElement = <Box __css={styles}>{children}</Box>;
+
+  // The user wants to render the `header` HTML element.
+  if (renderHeaderElement) {
+    // But if they passed in a component that renders an HTML `<header>`,
+    // then log a warning.
+    React.Children.map(children as JSX.Element, (child: React.ReactElement) => {
+      if (child?.type === "header" || child?.props?.mdxType === "header") {
+        console.warn(
+          "NYPL Reservoir TemplateHeader: An HTML `header` element was passed " +
+            "in. Set `renderHeaderElement` to `false` to avoid nested HTML " +
+            "`header` elements."
+        );
+      }
+    });
+    headerElement = (
+      <Box as="header" __css={styles}>
+        {children}
+      </Box>
+    );
+  }
+  return headerElement;
+};
+
+/**
+ * This optional component should be used inside the `TemplateHeader` component.
+ * This is meant to render its children from edge to edge and is most useful
+ * for the `Breadcrumbs` and `Hero` components, and other banner-like components.
+ */
+const TemplateBreakout = (props: React.PropsWithChildren<TemplateProps>) => {
+  const styles = useStyleConfig("TemplateBreakout", {});
+  return <Box __css={styles}>{props.children}</Box>;
+};
+
+/**
+ * This component is most useful to render content on the page. This renders an
+ * HTML `<main>` element with an id of "mainContent". The "mainContent" id should
+ * be used as the consuming application's skip navigation link. The `TemplateContent`
+ * component also takes a `sidebar` prop with optional "left" or "right" values.
+ * This will set the correct *styling* needed for the `TemplateContentPrimary`
+ * and `TemplateContentSidebar` components. Note that `TemplateContentPrimary`
+ * and `TemplateContentSidebar` must be ordered correctly as children elements
+ * for the appropriate styles to take effect.
+ */
+const TemplateContent = (
+  props: React.PropsWithChildren<TemplateContentProps>
+) => {
+  const { children, id = "mainContent", sidebar = "none" } = props;
+  const styles = useStyleConfig("TemplateContent", {
+    variant: sidebar !== "none" ? "sidebar" : null,
+  });
+  // Manually pass in the `sidebar` prop to the `TemplateContentPrimary` and
+  // `TemplateContentSidebar` components.
+  const newChildren = React.Children.map(
+    children as JSX.Element,
+    (child: React.ReactElement) => {
+      let newChild = child;
+      if (
+        (child && child?.type === TemplateContentPrimary) ||
+        (child?.props && child.props?.mdxType === "TemplateContentPrimary") ||
+        child?.type === TemplateContentSidebar ||
+        (child?.props && child.props?.mdxType === "TemplateContentSidebar")
+      ) {
+        newChild = React.cloneElement(child, { sidebar });
+      }
+
+      return newChild;
+    }
+  );
+
+  return (
+    <Box as="main" id={id} __css={styles}>
+      {newChildren}
+    </Box>
+  );
+};
+
+/**
+ * This optional component must be used inside the `TemplateContent` component.
+ * This renders content in the main width of the container and will always render
+ * above the primary component and the sidebar component (if any).
+ */
+const TemplateContentTop = (props: React.PropsWithChildren<TemplateProps>) => {
+  const styles = useStyleConfig("TemplateContentTop", {});
+  return <Box __css={styles}>{props.children}</Box>;
+};
+
+/**
+ * This component is used to render content in a column when there must be a
+ * sidebar component on either its left or right side. It must go inside the
+ * `TemplateContent` component. An optional `sidebar` prop value of "left" or
+ * "right" can be passed to render the correct CSS styles. If the `sidebar`
+ * prop is used in the `TemplateContent` component, there is no need to pass
+ * the `sidebar` prop to this component -- `TemplateContent` will handle it.
+ */
+const TemplateContentPrimary = (
+  props: React.PropsWithChildren<TemplateContentProps>
+) => {
+  const { sidebar } = props;
+  const styles = useStyleConfig("TemplateContentPrimary", {
+    variant: sidebar,
+  });
+  return <Box __css={styles}>{props.children}</Box>;
+};
+
+/**
+ * This component is used to render content in a sidebar column. It must go
+ * inside the `TemplateContent` component and must be paired with the
+ * `TemplateContentPrimary` component. If this is a left sidebar, it needs to be
+ * rendered before the `TemplateContentPrimary` component. If this is a right
+ * sidebar, it needs to be rendered after the `TemplateContentPrimary` component.
+ * An optional `sidebar` prop value of "left" or "right" can be passed to render
+ * the correct CSS styles. If the `sidebar` prop is used in the `TemplateContent`
+ * component, there is no need to pass the `sidebar` prop to this component --
+ * `TemplateContent` will handle it.
+ */
+const TemplateContentSidebar = (
+  props: React.PropsWithChildren<TemplateContentProps>
+) => {
+  const { sidebar } = props;
+  const styles = useStyleConfig("TemplateContentSidebar", {
+    variant: sidebar,
+  });
+  return <Box __css={styles}>{props.children}</Box>;
+};
+
+/**
+ * This optional component should be the last child of the `Template`
+ * component. This is rendered as an HTML `<footer>` element and spans the full
+ * width of the page. If an HTML `<footer>` element is already passed in a
+ * custom component, set `renderFooterElement` to `false`.
+ */
+const TemplateFooter = ({
+  children,
+  renderFooterElement = true,
+}: React.PropsWithChildren<TemplateFooterProps>) => {
+  let footerElement = <>{children}</>;
+
+  // The user wants to render the `footer` HTML element.
+  if (renderFooterElement) {
+    // But give a warning if one was passed.
+    React.Children.map(children as JSX.Element, (child: React.ReactElement) => {
+      if (child?.type === "footer" || child?.props?.mdxType === "footer") {
+        console.warn(
+          "NYPL Reservoir TemplateFooter: An HTML `footer` element was passed " +
+            "in. Set `renderFooterElement` to `false` to avoid nested HTML " +
+            "`footer` elements."
+        );
+      }
+    });
+    footerElement = <Box as="footer">{children}</Box>;
+  }
+  return footerElement;
+};
+
+/**
+ * This single component can be used instead of all the individual template
+ * components. Instead of importing and rendering the needed "template"
+ * components, each section is passed as a prop to the section where it should
+ * be rendered. For example, if you want to render content in the
+ * `TemplateContentPrimary` section, then pass it as a prop to `contentPrimary`.
+ */
+export const TemplateAppContainer = chakra(
+  (props: React.PropsWithChildren<TemplateAppContainerProps>) => {
+    const {
+      aboveHeader,
+      breakout,
+      contentId = "mainContent",
+      contentPrimary,
+      contentSidebar,
+      contentTop,
+      footer,
+      header,
+      sidebar = "none",
+      renderFooterElement = true,
+      renderHeaderElement = true,
+      renderSkipNavigation = false,
+      ...rest
+    } = props;
+    const aboveHeaderElem = aboveHeader && (
+      <TemplateAboveHeader>{aboveHeader}</TemplateAboveHeader>
+    );
+    const breakoutElem = breakout && (
+      <TemplateBreakout>{breakout}</TemplateBreakout>
+    );
+    const contentTopElem = contentTop && (
+      <TemplateContentTop>{contentTop}</TemplateContentTop>
+    );
+    const contentPrimaryElem = contentPrimary && (
+      <TemplateContentPrimary>{contentPrimary}</TemplateContentPrimary>
+    );
+    const contentSidebarElem = contentSidebar && (
+      <TemplateContentSidebar>{contentSidebar}</TemplateContentSidebar>
+    );
+    return (
+      <Template {...rest}>
+        {renderSkipNavigation ? <SkipNavigation /> : null}
+        {aboveHeaderElem}
+        {(header || breakoutElem) && (
+          <TemplateHeader renderHeaderElement={renderHeaderElement}>
+            {header}
+            {breakoutElem}
+          </TemplateHeader>
+        )}
+        {/* Note that setting `sidebar` as a prop here affects the
+       TemplateContentSidebar and TemplateContentPrimary components. */}
+        <TemplateContent id={contentId} sidebar={sidebar}>
+          {contentTopElem}
+
+          {sidebar === "left" && contentSidebarElem}
+
+          {contentPrimaryElem}
+
+          {sidebar === "right" && contentSidebarElem}
+        </TemplateContent>
+        {footer && (
+          <TemplateFooter renderFooterElement={renderFooterElement}>
+            {footer}
+          </TemplateFooter>
+        )}
+      </Template>
+    );
+  }
+);
+
+export {
+  Template,
+  TemplateAboveHeader,
+  TemplateHeader,
+  TemplateBreakout,
+  TemplateContent,
+  TemplateContentTop,
+  TemplateContentPrimary,
+  TemplateContentSidebar,
+  TemplateFooter,
+};
+export default TemplateAppContainer;