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

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

@@ -0,0 +1,695 @@
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  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 Hero from "../Hero/Hero";
+import HorizontalRule from "../HorizontalRule/HorizontalRule";
+import Image from "../Image/Image";
+import Link from "../Link/Link";
+import Notification, {
+  NotificationContent,
+  NotificationHeading,
+  NotificationProps,
+} from "../Notification/Notification";
+import Placeholder from "../Placeholder/Placeholder";
+import SkipNavigation from "../SkipNavigation/SkipNavigation";
+import {
+  Template,
+  TemplateAboveHeader,
+  TemplateHeader,
+  TemplateBreakout,
+  TemplateContent,
+  TemplateContentTop,
+  TemplateContentPrimary,
+  TemplateContentSidebar,
+  TemplateFooter,
+  TemplateAppContainer,
+} from "./Template";
+import TextInput from "../TextInput/TextInput";
+import { getCategory } from "../../utils/componentCategories";
+
+<Meta
+  title={getCategory("Template")}
+  component={TemplateAppContainer}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=36835%3A26688",
+    },
+  }}
+/>
+
+# Template
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.3.6`    |
+| Latest            | `0.26.0`   |
+
+## 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} />
+
+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.
+
+If you need to render the `SkipNavigation` component, set `renderSkipNavigation`
+to true.
+
+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.
+
+**This is the recommended way to render an app page template.**
+
+```jsx
+import { TemplateAppContainer } from "@nypl/design-system-react-components";
+
+<TemplateAppContainer
+  aboveHeader={<Placeholder variant="short">Above Header</Placeholder>}
+  header={<Placeholder variant="short">NYPL Header</Placeholder>}
+  breakout={
+    <>
+      <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 variant="short">More Content</Placeholder>
+    </>
+  }
+  footer={<Placeholder variant="short">Footer</Placeholder>}
+  renderSkipNavigation={true}
+/>;
+```
+
+## TemplateAppContainer Component Props
+
+<Canvas>
+  <Story
+    name="TemplateAppContainer Component"
+    args={{
+      aboveHeader: <Placeholder variant="short">Above Header</Placeholder>,
+      breakout: (
+        <>
+          <Placeholder variant="short">Breadcrumbs</Placeholder>
+          <Placeholder variant="short">Hero</Placeholder>
+        </>
+      ),
+      contentPrimary: (
+        <>
+          <Placeholder>Main Content</Placeholder>
+          <Placeholder variant="short">More Content</Placeholder>
+        </>
+      ),
+      contentId: "mainContent",
+      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,
+      renderSkipNavigation: true,
+    }}
+    argTypes={{
+      aboveHeader: { control: false },
+      breakout: { 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} />}
+  </Story>
+</Canvas>
+
+<ArgsTable story="TemplateAppContainer Component" />
+
+## TemplateAppContainer Accessibility
+
+**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. 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.
+
+If you are using a custom header component or you need to use the Reservoir
+Design System (DS) `SkipNavigation` component, then set the `renderSkipNavigation`
+prop to true. This will render the `SkipNavigation` component at the top of the
+page before any other elements. The main link will point to the `#mainContent`
+`main` 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.
+
+Note: If you need to render the `SkipNavigation` component, you need to explicitly
+render it immediately before the `TemplateAboveHeader` component. This is done
+automatically in the `TemplateAppContainer` component.
+
+Basic "template" components structure:
+
+```
+import {
+  Template,
+  TemplateAboveHeader,
+  TemplateHeader,
+  TemplateBreakout,
+  TemplateContent,
+  TemplateContentTop,
+  TemplateContentPrimary,
+  TemplateContentSidebar,
+  TemplateFooter,
+} from "@nypl/design-system-react-components";
+
+
+<Template>
+  <SkipNavigation />
+  <TemplateAboveHeader>
+    // ...
+  </TemplateAboveHeader>
+  <TemplateHeader>
+    // ...
+    <TemplateBreakout>
+      // ...
+    </TemplateBreakout>
+  </TemplateHeader>
+
+  <TemplateContent sidebar="...">
+    <TemplateContentTop>
+      // ...
+    </TemplateContentTop>
+
+    <TemplateContentPrimary>
+      // ...
+    </TemplateContentPrimary>
+  </TemplateContent>
+
+  <TemplateFooter>
+    // ...
+  </TemplateFooter>
+</Template>
+```
+
+## Template Children Component Props
+
+<Canvas>
+  <Story
+    name="Template Children Components"
+    args={{
+      sidebar: "left",
+    }}
+    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 } },
+      footer: { table: { disable: true } },
+      header: { table: { disable: true } },
+      sidebar: { description: "Only used in Storybook." },
+    }}
+  >
+    {(args) => (
+      <Template>
+        <SkipNavigation />
+        <TemplateAboveHeader>
+          <Placeholder variant="short">Above Header</Placeholder>
+        </TemplateAboveHeader>
+        <TemplateHeader>
+          <Placeholder variant="short">NYPL Header</Placeholder>
+          <TemplateBreakout>
+            <Placeholder variant="short">Breadcrumbs</Placeholder>
+            <Placeholder variant="short">Hero</Placeholder>
+          </TemplateBreakout>
+        </TemplateHeader>
+        <TemplateContent sidebar={args.sidebar}>
+          <TemplateContentTop>
+            <Placeholder>Content Top</Placeholder>
+          </TemplateContentTop>
+          {args.sidebar === "left" && (
+            <TemplateContentSidebar>
+              <Placeholder>Left Sidebar</Placeholder>
+            </TemplateContentSidebar>
+          )}
+          <TemplateContentPrimary>
+            <Placeholder>Main Content</Placeholder>
+            <Placeholder variant="short">More Content</Placeholder>
+          </TemplateContentPrimary>
+          {args.sidebar === "right" && (
+            <TemplateContentSidebar>
+              <Placeholder>Right Sidebar</Placeholder>
+            </TemplateContentSidebar>
+          )}
+        </TemplateContent>
+        <TemplateFooter>
+          <Placeholder variant="short">Footer</Placeholder>
+        </TemplateFooter>
+      </Template>
+    )}
+  </Story>
+</Canvas>
+
+<ArgsTable story="Template Children Components" />
+
+### Template Components
+
+The components consist of:
+
+- `Template`
+- `TemplateAboveHeader`
+- `TemplateHeader`
+- `TemplateBreakout`
+- `TemplateContent`
+- `TemplateContentTop`
+- `TemplateContentPrimary`
+- `TemplateContentSidebar`
+- `TemplateFooter`
+
+#### Template
+
+```
+<Template>
+  // ...
+</Template>
+```
+
+<Description of={Template} />
+
+#### TemplateAboveHeader
+
+```
+<Template>
+  <TemplateAboveHeader>
+    // ...
+  </TemplateAboveHeader>
+<Template>
+```
+
+<Description of={TemplateAboveHeader} />
+
+#### TemplateHeader
+
+```
+<Template>
+  <TemplateAboveHeader>
+    // ...
+  </TemplateAboveHeader>
+  <TemplateHeader>
+    // ...
+  </TemplateHeader>
+<Template>
+```
+
+<Description of={TemplateHeader} />
+
+#### TemplateBreakout
+
+```
+<Template>
+  <TemplateAboveHeader>
+    // ...
+  </TemplateAboveHeader>
+  <TemplateHeader>
+    <TemplateBreakout>
+      // ...
+    </TemplateBreakout>
+  </TemplateHeader>
+<Template>
+```
+
+<Description of={TemplateBreakout} />
+
+#### TemplateContent
+
+```
+<Template>
+  <TemplateHeader>...</TemplateHeader>
+  <TemplateContent id="mainContent" sidebar="left">
+    // ...
+  </TemplateContent>
+<Template>
+```
+
+<Description of={TemplateContent} />
+
+#### TemplateContentTop
+
+```
+<Template>
+  <TemplateAboveHeader>
+    // ...
+  </TemplateAboveHeader>
+  <TemplateHeader>...</TemplateHeader>
+  <TemplateContent>
+    <TemplateContentTop>
+      // ...
+    </TemplateContent>
+  </TemplateContent>
+<Template>
+```
+
+<Description of={TemplateContentTop} />
+
+#### TemplateContentPrimary
+
+```
+<Template>
+  <TemplateAboveHeader>
+    // ...
+  </TemplateAboveHeader>
+  <TemplateHeader>...</TemplateHeader>
+  <TemplateContent>
+    <TemplateContentPrimary>
+      // ...
+    </TemplateContentPrimary>
+  </TemplateContent>
+<Template>
+```
+
+<Description of={TemplateContentPrimary} />
+
+#### TemplateContentSidebar
+
+```
+<Template>
+  <TemplateAboveHeader>
+    // ...
+  </TemplateAboveHeader>
+  <TemplateHeader>...</TemplateHeader>
+  <TemplateContent sidebar="right">
+    <TemplateContentPrimary>
+      // ...
+    </TemplateContentPrimary>
+    <TemplateContentSidebar>
+      // RIGHT SIDEBAR
+    </TemplateContentSidebar>
+  </TemplateContent>
+<Template>
+
+<Template>
+  <TemplateAboveHeader>
+    // ...
+  </TemplateAboveHeader>
+  <TemplateHeader>...</TemplateHeader>
+  <TemplateContent sidebar="left">
+    <TemplateContentSidebar>
+      // LEFT SIDEBAR
+    </TemplateContentSidebar>
+    <TemplateContentPrimary>
+      // ...
+    </TemplateContentPrimary>
+  </TemplateContent>
+<Template>
+```
+
+<Description of={TemplateContentSidebar} />
+
+#### TemplateFooter
+
+```
+<Template>
+  <TemplateAboveHeader>
+    // ...
+  </TemplateAboveHeader>
+  <TemplateHeader>
+    // ...
+  </TemplateHeader>
+  <TemplateContent sidebar="right">
+    //...
+  </TemplateContent>
+  <TemplateFooter>
+    // ...
+  </TemplateFooter>
+<Template>
+```
+
+<Description of={TemplateFooter} />
+
+### Template Children Components Sidebar Configuration
+
+In order to render a sidebar, two steps must be taken.
+
+1. The `TemplateContent` component needs to be aware of it. Pass the location
+   of the sidebar to the `sidebar` prop as either "left" or "right".
+
+```jsx
+<TemplateContent sidebar="left">
+```
+
+2. Render `TemplateContentSidebar` and `TemplateContentPrimary` next to each
+   other in the appropriate order. If the sidebar must show left, then
+   `TemplateContentSidebar` comes before `TemplateContentPrimary`. Otherwise,
+   `TemplateContentPrimary` must come before `TemplateContentSidebar`.
+
+```jsx
+// Render left sidebar
+<TemplateContent sidebar="left">
+  <TemplateContentSidebar>
+    // ...
+  </TemplateContentSidebar>
+  <TemplateContentPrimary>
+    // ...
+  </TemplateContentPrimary>
+</TemplateContent>
+
+// Render right sidebar
+<TemplateContent sidebar="right">
+  <TemplateContentPrimary>
+    // ...
+  </TemplateContentPrimary>
+  <TemplateContentSidebar>
+    // ...
+  </TemplateContentSidebar>
+</TemplateContent>
+```
+
+## Full Example with Template Children Components
+
+export const otherSubHeaderText =
+  "With 92 locations across the Bronx, Manhattan, and Staten Island, The New York Public Library is an essential part of neighborhoods across the city. Visit us today.";
+
+This is best viewed in the Storybook "Canvas" and not "Docs" section.
+
+<Canvas>
+  <Story name="Full Example with Template Children Components">
+    <Template>
+      <SkipNavigation />
+      <TemplateAboveHeader>
+        <Notification
+          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
+            breadcrumbsData={[
+              { url: "#", text: "Home" },
+              { url: "#", text: "Research" },
+              {
+                url: "#",
+                text: "Catalog",
+              },
+            ]}
+          />
+          <Hero
+            backgroundImageSrc="https://placeimg.com/2400/800/nature/grayscale"
+            heroType="campaign"
+            heading={<Heading level="one" id="1" text="Hero Campaign" />}
+            imageProps={{
+              alt: "Image example",
+              src: "https://placeimg.com/800/400/animals",
+            }}
+            subHeaderText={otherSubHeaderText}
+          />
+        </TemplateBreakout>
+      </TemplateHeader>
+      <TemplateContent sidebar="right">
+        <TemplateContentTop>
+          <Notification
+            notificationType="announcement"
+            notificationHeading="Announcement 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.
+              </>
+            }
+          />
+        </TemplateContentTop>
+        <TemplateContentPrimary>
+          <p>This is the main content!</p>
+          <Accordion accordionData={faqContent} />
+          <HorizontalRule />
+          <p>Fill out the form!</p>
+          <Form action="/end/point" id="form1">
+            <FormField>
+              <TextInput
+                helperText="Make sure to complete this field."
+                id="username"
+                labelText="Username"
+                required
+              />
+            </FormField>
+            <FormField>
+              <TextInput
+                helperText="Make sure to complete this field."
+                id="password"
+                labelText="Password"
+                required
+              />
+            </FormField>
+            <FormRow>
+              <FormField>
+                <TextInput
+                  id="phone-field"
+                  labelText="Phone Field"
+                  type="tel"
+                />
+              </FormField>
+              <FormField>
+                <TextInput id="url-field" labelText="URL Field" type="url" />
+              </FormField>
+              <FormField>
+                <TextInput id="age-field" labelText="Age" type="number" />
+              </FormField>
+            </FormRow>
+            <FormField>
+              <Button id="submit">Submit</Button>
+            </FormField>
+          </Form>
+        </TemplateContentPrimary>
+        <TemplateContentSidebar>
+          <p>Sidebar information in a `Card` component.</p>
+          <Card
+            imageProps={{
+              alt: "Alt text",
+              aspectRatio: "square",
+              size: "small",
+              src: "https://placeimg.com/400/200/animals",
+            }}
+            isCentered
+          >
+            <CardHeading id="heading1">Small Animal Image</CardHeading>
+            <CardHeading level="three" id="heading2">
+              Animal info
+            </CardHeading>
+            <CardContent>
+              Vestibulum id ligula porta felis euismod semper. Nulla vitae elit
+              libero, a pharetra augue.
+            </CardContent>
+          </Card>
+        </TemplateContentSidebar>
+      </TemplateContent>
+      <TemplateFooter>
+        <Card
+          id="custom-card"
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: "sixteenByNine",
+            src: "https://cdn-d8.nypl.org/s3fs-public/2020-05/NYPL_MainFacadeRev2Cam2.png",
+          }}
+          layout="horizontal"
+          backgroundColor="#616161"
+          foregroundColor="#FFF"
+        >
+          <CardHeading id="heading1-footer">Footer</CardHeading>
+          <CardContent>
+            <p>This is an example footer using the `Card` component.</p>
+            <p>
+              © The New York Public Library, 2021 The New York Public Library is
+              a 501(c)(3) | EIN 13-1887440
+            </p>
+          </CardContent>
+          <CardActions>
+            <Link color="#FFF" href="#" textDecoration="underline">
+              Facebook
+            </Link>
+            ,<Link color="#FFF" href="#" textDecoration="underline">
+              Instagram
+            </Link>,<Link color="#FFF" href="#" textDecoration="underline">
+              Twitter
+            </Link>
+          </CardActions>
+        </Card>
+      </TemplateFooter>
+    </Template>
+  </Story>
+</Canvas>