@nypl/design-system-react-components 0.25.8 → 0.25.11

package/src/components/Template/Template.stories.mdx

@@ -1,14 +1,35 @@
 import {
-  Meta,
-  Story,
-  Canvas,
   ArgsTable,
+  Canvas,
   Description,
-} from "@storybook/addon-docs/blocks";
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
 import { withDesign } from "storybook-addon-designs";
 
+import Accordion from "../Accordion/Accordion";
+import { faqContent } from "../Accordion/Accordion.stories.mdx";
+import Breadcrumbs from "../Breadcrumbs/Breadcrumbs";
+import Button from "../Button/Button";
+import Card, { CardHeading, CardContent, CardActions } from "../Card/Card";
+import Form, { FormRow, FormField } from "../Form/Form";
+import Heading from "../Heading/Heading";
+import { HeadingLevels } from "../Heading/HeadingTypes";
+import Hero from "../Hero/Hero";
+import HorizontalRule from "../HorizontalRule/HorizontalRule";
+import { HeroTypes } from "../Hero/HeroTypes";
+import Image from "../Image/Image";
+import { ImageRatios, ImageSizes } from "../Image/ImageTypes";
+import Link from "../Link/Link";
+import Notification, {
+  NotificationContent,
+  NotificationHeading,
+  NotificationProps,
+} from "../Notification/Notification";
+import Placeholder from "../Placeholder/Placeholder";
 import {
   Template,
+  TemplateAboveHeader,
   TemplateHeader,
   TemplateBreakout,
   TemplateContent,
@@ -18,27 +39,7 @@ import {
   TemplateFooter,
   TemplateAppContainer,
 } from "./Template";
-import Placeholder from "../Placeholder/Placeholder";
-import Hero from "../Hero/Hero";
-import { HeroTypes } from "../Hero/HeroTypes";
-import Image from "../Image/Image";
-import { ImageRatios, ImageSizes } from "../Image/ImageTypes";
-import Breadcrumbs from "../Breadcrumbs/Breadcrumbs";
-import HorizontalRule from "../HorizontalRule/HorizontalRule";
-import Heading from "../Heading/Heading";
-import { HeadingLevels } from "../Heading/HeadingTypes";
-import Notification, {
-  NotificationContent,
-  NotificationHeading,
-  NotificationProps,
-} from "../Notification/Notification";
-import Form, { FormRow, FormField } from "../Form/Form";
 import TextInput from "../TextInput/TextInput";
-import Button from "../Button/Button";
-import Link from "../Link/Link";
-import Card, { CardHeading, CardContent, CardActions } from "../Card/Card";
-import Accordion from "../Accordion/Accordion";
-import { faqContent } from "../Accordion/Accordion.stories.mdx";
 import { NotificationTypes } from "../Notification/NotificationTypes";
 import { getCategory } from "../../utils/componentCategories";
 
@@ -49,7 +50,7 @@ import { getCategory } from "../../utils/componentCategories";
   parameters={{
     design: {
       type: "figma",
-      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=11982%3A47778",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=36835%3A26688",
     },
   }}
 />
@@ -59,23 +60,38 @@ import { getCategory } from "../../utils/componentCategories";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.3.6`    |
-| Latest            | `0.25.1`   |
+| Latest            | `0.25.10`  |
 
 ## TemplateAppContainer Component
 
 <Description of={TemplateAppContainer} />
 
+If you have a custom `Header` component that _already_ renders an HTML `<header>`
+element, set `renderHeaderElement` to false so only one `<header>` element is
+rendered.
+
+Likewise, if you have a custom `Footer` component that _already_ renders an HTML
+`<footer>` element, set `renderFooterElement` to false so only one `<footer>`
+element is rendered.
+
+If you need to render an alert or notification at the top of the page with an
+`aside` HTML element or HTML element with the `role="complementary"` attribute,
+then pass that alert or notification component to the `aboveHeader` prop. These
+elements should _not_ be rendered in the `header` HTML section since that's an
+accessibility violation.
+
 <b>This is the recommended way to render an app page template.</b>
 
 ```jsx
 import { TemplateAppContainer } from "@nypl/design-system-react-components";
 
 <TemplateAppContainer
-  header={<Placeholder modifiers={["short"]}>NYPL Header</Placeholder>}
+  aboveHeader={<Placeholder variant="short">Above Header</Placeholder>}
+  header={<Placeholder variant="short">NYPL Header</Placeholder>}
   breakout={
     <>
-      <Placeholder modifiers={["short"]}>Breadcrumbs</Placeholder>
-      <Placeholder modifiers={["short"]}>Hero</Placeholder>
+      <Placeholder variant="short">Breadcrumbs</Placeholder>
+      <Placeholder variant="short">Hero</Placeholder>
     </>
   }
   sidebar="left"
@@ -84,10 +100,10 @@ import { TemplateAppContainer } from "@nypl/design-system-react-components";
   contentPrimary={
     <>
       <Placeholder>Main Content</Placeholder>
-      <Placeholder modifiers={["short"]}>More Content</Placeholder>
+      <Placeholder variant="short">More Content</Placeholder>
     </>
   }
-  footer={<Placeholder modifiers={["short"]}>Footer</Placeholder>}
+  footer={<Placeholder variant="short">Footer</Placeholder>}
 />;
 ```
 
@@ -95,31 +111,39 @@ import { TemplateAppContainer } from "@nypl/design-system-react-components";
   <Story
     name="TemplateAppContainer Component"
     args={{
-      header: <Placeholder modifiers={["short"]}>NYPL Header</Placeholder>,
+      aboveHeader: <Placeholder variant="short">Above Header</Placeholder>,
       breakout: (
         <>
-          <Placeholder modifiers={["short"]}>Breadcrumbs</Placeholder>
-          <Placeholder modifiers={["short"]}>Hero</Placeholder>
+          <Placeholder variant="short">Breadcrumbs</Placeholder>
+          <Placeholder variant="short">Hero</Placeholder>
         </>
       ),
-      sidebar: "left",
-      contentTop: <Placeholder>Content Top</Placeholder>,
-      contentSidebar: <Placeholder>Left Sidebar</Placeholder>,
       contentPrimary: (
         <>
           <Placeholder>Main Content</Placeholder>
-          <Placeholder modifiers={["short"]}>More Content</Placeholder>
+          <Placeholder variant="short">More Content</Placeholder>
         </>
       ),
-      footer: <Placeholder modifiers={["short"]}>Footer</Placeholder>,
+      contentSidebar: <Placeholder>Left Sidebar</Placeholder>,
+      contentTop: <Placeholder>Content Top</Placeholder>,
+      footer: <Placeholder variant="short">Footer</Placeholder>,
+      header: <Placeholder variant="short">NYPL Header</Placeholder>,
+      sidebar: "left",
+      renderFooterElement: true,
+      renderHeaderElement: true,
     }}
     argTypes={{
-      header: { control: false },
+      aboveHeader: { control: false },
       breakout: { control: false },
-      contentTop: { control: false },
-      contentSidebar: { control: false },
       contentPrimary: { control: false },
+      contentSidebar: { control: false },
+      contentTop: { control: false },
       footer: { control: false },
+      header: { control: false },
+      sidebar: {
+        control: false,
+        table: { defaultValue: { summary: "none" } },
+      },
     }}
   >
     {(args) => <TemplateAppContainer {...args} />}
@@ -141,6 +165,7 @@ Basic "template" components structure:
 ```
 import {
   Template,
+  TemplateAboveHeader,
   TemplateHeader,
   TemplateBreakout,
   TemplateContent,
@@ -152,6 +177,9 @@ import {
 
 
 <Template>
+  <TemplateAboveHeader>
+    // ...
+  </TemplateAboveHeader>
   <TemplateHeader>
     // ...
     <TemplateBreakout>
@@ -159,7 +187,7 @@ import {
     </TemplateBreakout>
   </TemplateHeader>
 
-  <TemplateContent>
+  <TemplateContent sidebar="...">
     <TemplateContentTop>
       // ...
     </TemplateContentTop>
@@ -182,21 +210,26 @@ import {
       sidebar: "left",
     }}
     argTypes={{
+      aboveHeader: { table: { disable: true } },
       breakout: { table: { disable: true } },
       contentPrimary: { table: { disable: true } },
       contentSidebar: { table: { disable: true } },
       contentTop: { table: { disable: true } },
       footer: { table: { disable: true } },
       header: { table: { disable: true } },
+      sidebar: { description: "Only used in Storybook." },
     }}
   >
     {(args) => (
       <Template>
+        <TemplateAboveHeader>
+          <Placeholder variant="short">Above Header</Placeholder>
+        </TemplateAboveHeader>
         <TemplateHeader>
-          <Placeholder modifiers={["short"]}>NYPL Header</Placeholder>
+          <Placeholder variant="short">NYPL Header</Placeholder>
           <TemplateBreakout>
-            <Placeholder modifiers={["short"]}>Breadcrumbs</Placeholder>
-            <Placeholder modifiers={["short"]}>Hero</Placeholder>
+            <Placeholder variant="short">Breadcrumbs</Placeholder>
+            <Placeholder variant="short">Hero</Placeholder>
           </TemplateBreakout>
         </TemplateHeader>
         <TemplateContent sidebar={args.sidebar}>
@@ -210,7 +243,7 @@ import {
           )}
           <TemplateContentPrimary>
             <Placeholder>Main Content</Placeholder>
-            <Placeholder modifiers={["short"]}>More Content</Placeholder>
+            <Placeholder variant="short">More Content</Placeholder>
           </TemplateContentPrimary>
           {args.sidebar === "right" && (
             <TemplateContentSidebar>
@@ -219,7 +252,7 @@ import {
           )}
         </TemplateContent>
         <TemplateFooter>
-          <Placeholder modifiers={["short"]}>Footer</Placeholder>
+          <Placeholder variant="short">Footer</Placeholder>
         </TemplateFooter>
       </Template>
     )}
@@ -233,6 +266,7 @@ import {
 The components consist of:
 
 - `Template`
+- `TemplateAboveHeader`
 - `TemplateHeader`
 - `TemplateBreakout`
 - `TemplateContent`
@@ -251,10 +285,25 @@ The components consist of:
 
 <Description of={Template} />
 
+#### TemplateAboveHeader
+
+```
+<Template>
+  <TemplateAboveHeader>
+    // ...
+  </TemplateAboveHeader>
+<Template>
+```
+
+<Description of={TemplateAboveHeader} />
+
 #### TemplateHeader
 
 ```
 <Template>
+  <TemplateAboveHeader>
+    // ...
+  </TemplateAboveHeader>
   <TemplateHeader>
     // ...
   </TemplateHeader>
@@ -267,6 +316,9 @@ The components consist of:
 
 ```
 <Template>
+  <TemplateAboveHeader>
+    // ...
+  </TemplateAboveHeader>
   <TemplateHeader>
     <TemplateBreakout>
       // ...
@@ -294,6 +346,9 @@ The components consist of:
 
 ```
 <Template>
+  <TemplateAboveHeader>
+    // ...
+  </TemplateAboveHeader>
   <TemplateHeader>...</TemplateHeader>
   <TemplateContent>
     <TemplateContentTop>
@@ -309,6 +364,9 @@ The components consist of:
 
 ```
 <Template>
+  <TemplateAboveHeader>
+    // ...
+  </TemplateAboveHeader>
   <TemplateHeader>...</TemplateHeader>
   <TemplateContent>
     <TemplateContentPrimary>
@@ -324,6 +382,9 @@ The components consist of:
 
 ```
 <Template>
+  <TemplateAboveHeader>
+    // ...
+  </TemplateAboveHeader>
   <TemplateHeader>...</TemplateHeader>
   <TemplateContent sidebar="right">
     <TemplateContentPrimary>
@@ -336,6 +397,9 @@ The components consist of:
 <Template>
 
 <Template>
+  <TemplateAboveHeader>
+    // ...
+  </TemplateAboveHeader>
   <TemplateHeader>...</TemplateHeader>
   <TemplateContent sidebar="left">
     <TemplateContentSidebar>
@@ -354,6 +418,9 @@ The components consist of:
 
 ```
 <Template>
+  <TemplateAboveHeader>
+    // ...
+  </TemplateAboveHeader>
   <TemplateHeader>
     // ...
   </TemplateHeader>
@@ -416,6 +483,23 @@ This is best viewed in the Storybook "Canvas" and not "Docs" section.
 <Canvas>
   <Story name="Full Example with Template Children Components">
     <Template>
+      <TemplateAboveHeader>
+        <Notification
+          notificationType={NotificationTypes.Standard}
+          notificationHeading="Standard Notification"
+          notificationContent={
+            <>
+              This is an "announcement" Notification with a heading. Cras mattis
+              consectetur purus sit amet fermentum. Maecenas faucibus mollis
+              interdum. Morbi leo risus, porta ac consectetur ac, vestibulum at
+              eros. Cum sociis natoque penatibus et magnis dis parturient
+              montes, nascetur ridiculus mus. Vivamus sagittis lacus vel augue
+              laoreet rutrum faucibus dolor auctor.
+            </>
+          }
+          showIcon={false}
+        />
+      </TemplateAboveHeader>
       <TemplateHeader>
         <TemplateBreakout>
           <Breadcrumbs

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

@@ -1,9 +1,11 @@
 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,
@@ -15,11 +17,12 @@ import {
 } from "./Template";
 import Placeholder from "../Placeholder/Placeholder";
 
-const header = <Placeholder modifiers={["short"]}>NYPL Header</Placeholder>;
+const aboveHeader = <Placeholder variant="short">Above Header</Placeholder>;
+const header = <Placeholder variant="short">NYPL Header</Placeholder>;
 const breakout = (
   <>
-    <Placeholder modifiers={["short"]}>Breadcrumbs</Placeholder>
-    <Placeholder modifiers={["short"]}>Hero</Placeholder>
+    <Placeholder variant="short">Breadcrumbs</Placeholder>
+    <Placeholder variant="short">Hero</Placeholder>
   </>
 );
 const sidebar = "left";
@@ -28,15 +31,16 @@ const contentSidebar = <Placeholder>Left Sidebar</Placeholder>;
 const contentPrimary = (
   <>
     <Placeholder>Main Content</Placeholder>
-    <Placeholder modifiers={["short"]}>More Content</Placeholder>
+    <Placeholder variant="short">More Content</Placeholder>
   </>
 );
-const footer = <Placeholder modifiers={["short"]}>Footer</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}
@@ -54,6 +58,7 @@ describe("Template components accessibility", () => {
   it("passes axe accessibility test", async () => {
     const { container } = render(
       <Template>
+        <TemplateAboveHeader>{aboveHeader}</TemplateAboveHeader>
         <TemplateHeader>
           {header}
           <TemplateBreakout>{breakout}</TemplateBreakout>
@@ -74,6 +79,7 @@ describe("TemplateAppContainer component", () => {
   it("renders each section", () => {
     render(
       <TemplateAppContainer
+        aboveHeader={aboveHeader}
         header={header}
         breakout={breakout}
         sidebar={sidebar}
@@ -83,7 +89,7 @@ describe("TemplateAppContainer component", () => {
         footer={footer}
       />
     );
-
+    expect(screen.getByText("Above Header")).toBeInTheDocument();
     expect(screen.getByText("NYPL Header")).toBeInTheDocument();
     expect(screen.getByText("Breadcrumbs")).toBeInTheDocument();
     expect(screen.getByText("Hero")).toBeInTheDocument();
@@ -93,12 +99,90 @@ describe("TemplateAppContainer component", () => {
     expect(screen.getByText("More Content")).toBeInTheDocument();
     expect(screen.getByText("Footer")).toBeInTheDocument();
   });
+
+  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(
+      "`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(
+      "`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>
@@ -112,6 +196,7 @@ describe("Template components", () => {
       </Template>
     );
 
+    expect(screen.getByText("Above Header")).toBeInTheDocument();
     expect(screen.getByText("NYPL Header")).toBeInTheDocument();
     expect(screen.getByText("Breadcrumbs")).toBeInTheDocument();
     expect(screen.getByText("Hero")).toBeInTheDocument();
@@ -121,4 +206,41 @@ describe("Template components", () => {
     expect(screen.getByText("More Content")).toBeInTheDocument();
     expect(screen.getByText("Footer")).toBeInTheDocument();
   });
+
+  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();
+
+    expect(templateComponents).toMatchSnapshot();
+    expect(singleComponent).toMatchSnapshot();
+  });
 });