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

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

@@ -60,9 +60,18 @@ import { getCategory } from "../../utils/componentCategories";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.3.6`    |
-| Latest            | `0.25.12`  |
+| Latest            | `0.26.0`   |
 
-## TemplateAppContainer Component
+## Table of Contents
+
+- [TemplateAppContainer Overview](#templateappcontainer-overview)
+- [TemplateAppContainer Component Props](#templateappcontainer-component-props)
+- [TemplateAppContainer Accessibility](#templateappcontainer-accessibility)
+- [Template Children Overview](#template-children-overview)
+- [Template Children Component Props](#template-children-component-props)
+- [Full Example with Template Children Components](#full-example-with-template-children-components)
+
+## TemplateAppContainer Overview
 
 <Description of={TemplateAppContainer} />
 
@@ -74,13 +83,7 @@ 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>
+**This is the recommended way to render an app page template.**
 
 ```jsx
 import { TemplateAppContainer } from "@nypl/design-system-react-components";
@@ -107,6 +110,8 @@ import { TemplateAppContainer } from "@nypl/design-system-react-components";
 />;
 ```
 
+## TemplateAppContainer Component Props
+
 <Canvas>
   <Story
     name="TemplateAppContainer Component"
@@ -124,6 +129,7 @@ import { TemplateAppContainer } from "@nypl/design-system-react-components";
           <Placeholder variant="short">More Content</Placeholder>
         </>
       ),
+      contentId: "mainContent",
       contentSidebar: <Placeholder>Left Sidebar</Placeholder>,
       contentTop: <Placeholder>Content Top</Placeholder>,
       footer: <Placeholder variant="short">Footer</Placeholder>,
@@ -152,13 +158,45 @@ import { TemplateAppContainer } from "@nypl/design-system-react-components";
 
 <ArgsTable story="TemplateAppContainer Component" />
 
-## Template Children Components
+## TemplateAppContainer Accessibility
 
-The DS also provides a set of "template" components that work together to
-render a consistent mobile and desktop layout. More information on individual
-components and how they should be composed can be found below. Even though these
-component are available for use, we recommend using the `TemplateAppContainer`
-component and passing down children component as props as needed.
+**The `TemplateAppContainer` component is the recommended way to render the entire
+application.** Therefore, this accessibility section is specifically for the
+`TemplateAppContainer` but the same rules apply to the individual "Template"
+components.
+
+The `TemplateAppContainer` component renders the header as a `<header>` element,
+the content as a `<main>` element, and the footer as a `<footer>` element.
+
+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.
+
+The `TemplateAppContainer` component renders a full DOM and one of the children
+is the `main` HTML element with a default "id" of `"mainContent"`. This should
+be used as the anchor element that the skip navigation link points to. As of
+v0.25.13, the consuming application is responsible for adding the skip
+navigation feature to the application. If your application is using the current
+NYPL Header, it already contains the skip navigation feature but make sure it is
+pointing to the correct anchor element.
+
+Resources
+
+- [W3C Aria Landmarks Example](https://www.w3.org/TR/wai-aria-practices/examples/landmarks/complementary.html)
+- [Digital A11y Role=Complementary](https://www.digitala11y.com/complementary-role/)
+- [WebAim Skip Navigation Link](https://webaim.org/techniques/skipnav/)
+- [A11ymatters Skip Navigation Link](https://www.a11ymatters.com/pattern/skip-link/)
+
+## Template Children Overview
+
+The Reservoir Design System (DS) also provides a set of "template" components 
+that work together to render a consistent mobile and desktop layout. More 
+information on individual components and how they should be composed can be 
+found below. Even though these component are available for use, we recommend 
+using the `TemplateAppContainer` component and passing down children component 
+as props as needed.
 
 Basic "template" components structure:
 
@@ -203,6 +241,8 @@ import {
 </Template>
 ```
 
+## Template Children Component Props
+
 <Canvas>
   <Story
     name="Template Children Components"
@@ -212,6 +252,7 @@ import {
     argTypes={{
       aboveHeader: { table: { disable: true } },
       breakout: { table: { disable: true } },
+      contentId: { table: { disable: true } },
       contentPrimary: { table: { disable: true } },
       contentSidebar: { table: { disable: true } },
       contentTop: { table: { disable: true } },
@@ -334,7 +375,7 @@ The components consist of:
 ```
 <Template>
   <TemplateHeader>...</TemplateHeader>
-  <TemplateContent sidebar="left">
+  <TemplateContent id="mainContent" sidebar="left">
     // ...
   </TemplateContent>
 <Template>
@@ -513,18 +554,14 @@ This is best viewed in the Storybook "Canvas" and not "Docs" section.
             ]}
           />
           <Hero
+            backgroundImageSrc="https://placeimg.com/2400/800/nature/grayscale"
             heroType={HeroTypes.Campaign}
             heading={
               <Heading level={HeadingLevels.One} id="1" text="Hero Campaign" />
             }
+            imageAlt="Image example"
+            imageSrc="https://placeimg.com/800/400/animals"
             subHeaderText={otherSubHeaderText}
-            backgroundImageSrc="https://placeimg.com/2400/800/nature/grayscale"
-            image={
-              <Image
-                src="https://placeimg.com/800/400/animals"
-                alt="Image example"
-              />
-            }
           />
         </TemplateBreakout>
       </TemplateHeader>
@@ -547,7 +584,7 @@ This is best viewed in the Storybook "Canvas" and not "Docs" section.
         </TemplateContentTop>
         <TemplateContentPrimary>
           <p>This is the main content!</p>
-          <Accordion contentData={faqContent} />
+          <Accordion accordionData={faqContent} />
           <HorizontalRule />
           <p>Fill out the form!</p>
           <Form action="/end/point">
@@ -584,11 +621,13 @@ This is best viewed in the Storybook "Canvas" and not "Docs" section.
         <TemplateContentSidebar>
           <p>Sidebar information in a `Card` component.</p>
           <Card
-            center
-            imageSrc="https://placeimg.com/400/200/animals"
-            imageAlt="Alt text"
-            imageAspectRatio={ImageRatios.Square}
-            imageSize={ImageSizes.Small}
+            imageProps={{
+              alt: "Alt text",
+              aspectRatio: ImageRatios.Square,
+              size: ImageSizes.Small,
+              src: "https://placeimg.com/400/200/animals",
+            }}
+            isCentered
           >
             <CardHeading level={HeadingLevels.Two} id="heading1">
               Small Animal Image
@@ -606,9 +645,11 @@ This is best viewed in the Storybook "Canvas" and not "Docs" section.
       <TemplateFooter>
         <Card
           id="custom-card"
-          imageAlt="Alt text"
-          imageSrc="https://cdn-d8.nypl.org/s3fs-public/2020-05/NYPL_MainFacadeRev2Cam2.png"
-          imageAspectRatio={ImageRatios.SixteenByNine}
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: ImageRatios.SixteenByNine,
+            src: "https://cdn-d8.nypl.org/s3fs-public/2020-05/NYPL_MainFacadeRev2Cam2.png",
+          }}
           layout="horizontal"
           backgroundColor="#616161"
           foregroundColor="#FFF"

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

@@ -100,6 +100,23 @@ describe("TemplateAppContainer component", () => {
     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(
@@ -134,8 +151,9 @@ describe("TemplateAppContainer component", () => {
       />
     );
     expect(warn).toHaveBeenCalledWith(
-      "`TemplateHeader`: An HTML `header` element was passed in. Set " +
-        "`renderHeaderElement` to `false` to avoid nested HTML `header` elements."
+      "NYPL Reservoir TemplateHeader: An HTML `header` element was passed " +
+        "in. Set `renderHeaderElement` to `false` to avoid nested HTML " +
+        "`header` elements."
     );
   });
 
@@ -172,8 +190,9 @@ describe("TemplateAppContainer component", () => {
       />
     );
     expect(warn).toHaveBeenCalledWith(
-      "`TemplateFooter`: An HTML `footer` element was passed in. Set " +
-        "`renderFooterElement` to `false` to avoid nested HTML `footer` elements."
+      "NYPL Reservoir TemplateFooter: An HTML `footer` element was passed " +
+        "in. Set `renderFooterElement` to `false` to avoid nested HTML " +
+        "`footer` elements."
     );
   });
 });
@@ -207,7 +226,18 @@ describe("Template components", () => {
     expect(screen.getByText("Footer")).toBeInTheDocument();
   });
 
-  it("Renders the UI snapshot correctly", () => {
+  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>
@@ -239,8 +269,41 @@ describe("Template components", () => {
         />
       )
       .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

@@ -1,5 +1,5 @@
+import { Box, chakra, useStyleConfig } from "@chakra-ui/react";
 import * as React from "react";
-import { Box, useStyleConfig } from "@chakra-ui/react";
 
 export interface TemplateProps {}
 export interface TemplateHeaderProps {
@@ -15,7 +15,12 @@ export interface TemplateSidebarProps {
    * right side of the `TemplateContentPrimary` component. */
   sidebar?: "none" | "left" | "right";
 }
-export interface TemplateContentProps extends TemplateSidebarProps {}
+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,
@@ -25,6 +30,9 @@ export interface TemplateAppContainerProps
   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. */
@@ -41,10 +49,14 @@ export interface TemplateAppContainerProps
  * The main top-level parent component that wraps all template-related
  * components.
  */
-const Template = (props: React.PropsWithChildren<TemplateProps>) => {
+const Template = chakra((props: React.PropsWithChildren<TemplateProps>) => {
   const styles = useStyleConfig("Template", {});
-  return <Box __css={styles}>{props.children}</Box>;
-};
+  return (
+    <Box __css={styles} {...props}>
+      {props.children}
+    </Box>
+  );
+});
 
 /**
  * This optional component renders its children from edge-to-edge and should
@@ -80,8 +92,9 @@ const TemplateHeader = ({
     React.Children.map(children, (child: React.ReactElement) => {
       if (child?.type === "header" || child?.props?.mdxType === "header") {
         console.warn(
-          "`TemplateHeader`: An HTML `header` element was passed in. Set " +
-            "`renderHeaderElement` to `false` to avoid nested HTML `header` elements."
+          "NYPL Reservoir TemplateHeader: An HTML `header` element was passed " +
+            "in. Set `renderHeaderElement` to `false` to avoid nested HTML " +
+            "`header` elements."
         );
       }
     });
@@ -106,16 +119,18 @@ const TemplateBreakout = (props: React.PropsWithChildren<TemplateProps>) => {
 
 /**
  * This component is most useful to render content on the page. This renders an
- * HTML `<main>` element and 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.
+ * 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 { sidebar = "none", children } = props;
+  const { children, id = "mainContent", sidebar = "none" } = props;
   const styles = useStyleConfig("TemplateContent", {
     variant: sidebar !== "none" ? "sidebar" : null,
   });
@@ -139,7 +154,7 @@ const TemplateContent = (
   );
 
   return (
-    <Box as="main" __css={styles}>
+    <Box as="main" id={id} __css={styles}>
       {newChildren}
     </Box>
   );
@@ -212,8 +227,9 @@ const TemplateFooter = ({
     React.Children.map(children, (child: React.ReactElement) => {
       if (child?.type === "footer" || child?.props?.mdxType === "footer") {
         console.warn(
-          "`TemplateFooter`: An HTML `footer` element was passed in. Set " +
-            "`renderFooterElement` to `false` to avoid nested HTML `footer` elements."
+          "NYPL Reservoir TemplateFooter: An HTML `footer` element was passed " +
+            "in. Set `renderFooterElement` to `false` to avoid nested HTML " +
+            "`footer` elements."
         );
       }
     });
@@ -229,67 +245,68 @@ const TemplateFooter = ({
  * be rendered. For example, if you want to render content in the
  * `TemplateContentPrimary` section, then pass it as a prop to `contentPrimary`.
  */
-const TemplateAppContainer = (
-  props: React.PropsWithChildren<TemplateAppContainerProps>
-) => {
-  const {
-    aboveHeader,
-    breakout,
-    contentPrimary,
-    contentSidebar,
-    contentTop,
-    footer,
-    header,
-    sidebar = "none",
-    renderFooterElement = true,
-    renderHeaderElement = true,
-  } = 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>
-      {aboveHeaderElem}
-      {(header || breakoutElem) && (
-        <TemplateHeader renderHeaderElement={renderHeaderElement}>
-          {header}
-          {breakoutElem}
-        </TemplateHeader>
-      )}
-      {/* Note that setting `sidebar` as a prop here affects the
+export const TemplateAppContainer = chakra(
+  (props: React.PropsWithChildren<TemplateAppContainerProps>) => {
+    const {
+      aboveHeader,
+      breakout,
+      contentId = "mainContent",
+      contentPrimary,
+      contentSidebar,
+      contentTop,
+      footer,
+      header,
+      sidebar = "none",
+      renderFooterElement = true,
+      renderHeaderElement = true,
+      ...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}>
+        {aboveHeaderElem}
+        {(header || breakoutElem) && (
+          <TemplateHeader renderHeaderElement={renderHeaderElement}>
+            {header}
+            {breakoutElem}
+          </TemplateHeader>
+        )}
+        {/* Note that setting `sidebar` as a prop here affects the
        TemplateContentSidebar and TemplateContentPrimary components. */}
-      <TemplateContent sidebar={sidebar}>
-        {contentTopElem}
+        <TemplateContent id={contentId} sidebar={sidebar}>
+          {contentTopElem}
 
-        {sidebar === "left" && contentSidebarElem}
+          {sidebar === "left" && contentSidebarElem}
 
-        {contentPrimaryElem}
+          {contentPrimaryElem}
 
-        {sidebar === "right" && contentSidebarElem}
-      </TemplateContent>
-      {footer && (
-        <TemplateFooter renderFooterElement={renderFooterElement}>
-          {footer}
-        </TemplateFooter>
-      )}
-    </Template>
-  );
-};
+          {sidebar === "right" && contentSidebarElem}
+        </TemplateContent>
+        {footer && (
+          <TemplateFooter renderFooterElement={renderFooterElement}>
+            {footer}
+          </TemplateFooter>
+        )}
+      </Template>
+    );
+  }
+);
 
 export {
-  TemplateAppContainer,
   Template,
   TemplateAboveHeader,
   TemplateHeader,
@@ -300,3 +317,4 @@ export {
   TemplateContentSidebar,
   TemplateFooter,
 };
+export default TemplateAppContainer;