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

package/src/components/Hero/Hero.stories.mdx

@@ -0,0 +1,378 @@
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import Heading from "../Heading/Heading";
+import Hero, { heroSecondaryTypes } from "./Hero";
+import SimpleGrid from "../Grid/SimpleGrid";
+import Text from "../Text/Text";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta
+  title={getCategory("Hero")}
+  component={Hero}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=36817%3A23704",
+    },
+    jest: ["Hero.test.tsx"],
+  }}
+  argTypes={{
+    backgroundColor: { control: false },
+    foregroundColor: { control: false },
+    heading: { control: false },
+    heroType: {
+      table: { defaultValue: { summary: "primary" } },
+    },
+    imageProps: { control: false },
+    locationDetails: { control: false },
+    subHeaderText: { control: false },
+  }}
+/>
+
+export const secondarySubHeaderText = (
+  <>
+    Explore our collection of hundreds of online resources and databases. Use
+    our free online content to help with your research, whether it's finding a
+    single article, tracing a family tree, learning a new language, or anything
+    in between.
+  </>
+);
+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.";
+export const imageProps = {
+  alt: "Image example",
+  src: "https://placeimg.com/800/400/animals",
+};
+
+# Hero
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.2.0`    |
+| Latest            | `0.28.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [All Variations](#all-variations)
+- [Color Variations for Secondary Hero](#color-variations-for-secondary-hero)
+
+## Overview
+
+<Description of={Hero} />
+
+The `Hero` component is used to display a full width banner at the top of a page.
+The `Hero` will contain a required `h1` page title and may also include optional
+descriptive text and images.
+
+There are currently five main hero types: `"primary"`, `"secondary"`,
+`"tertiary"`, `"campaign"`, and `"fiftyFifty"`. Under the `"secondary"` hero type,
+there are four additional subtypes: `"secondaryBooksAndMore"`, `"secondaryLocations"`,
+`"secondaryResearch"`, and `"secondaryWhatsOn"`.
+
+For the variations that use image "alt" and "src" attributes, the `imageProps`
+prop should be used:
+
+```jsx
+<Hero
+  backgroundImageSrc="https://placeimg.com/2400/800/nature/grayscale"
+  heroType="campaign"
+  heading={<Heading level="one" id="campaign-hero" text="Hero Campaign" />}
+  imageProps={{
+    alt: "Image example",
+    src: "https://placeimg.com/800/400/animals",
+  }}
+  subHeaderText="Campaign Hero Subheader Text"
+/>
+```
+
+Note: the `imageProps` prop is not the same as the `backgroundImageSrc` prop used
+for some variations. For a full list of what props to use for each variant, check
+the [All Variations](#all-variations) section.
+
+## Component Props
+
+<Canvas withToolbar>
+  <Story
+    name="Hero with Controls"
+    args={{
+      backgroundColor: undefined,
+      backgroundImageSrc: undefined,
+      foregroundColor: undefined,
+      heading: undefined,
+      heroType: "primary",
+      imageProps: undefined,
+      locationDetails: undefined,
+      subHeaderText: undefined,
+    }}
+  >
+    {(args) =>
+      (args.heroType === "primary" && (
+        <Hero
+          {...args}
+          backgroundImageSrc="https://placeimg.com/2400/800/nature"
+          heading={<Heading level="one" id="1" text="Hero Primary" />}
+          heroType={args.heroType}
+          subHeaderText="Example Subtitle"
+        />
+      )) ||
+      (heroSecondaryTypes.includes(args.heroType) && (
+        <div className="nypl--books-and-more">
+          <Hero
+            {...args}
+            heading={<Heading level="one" id="1" text="Hero Secondary" />}
+            heroType={args.heroType}
+            imageProps={args.imageProps}
+            subHeaderText={secondarySubHeaderText}
+          />
+        </div>
+      )) ||
+      (args.heroType === "tertiary" && (
+        <Hero
+          {...args}
+          heading={<Heading level="one" id="1" text="Hero Tertiary" />}
+          heroType={args.heroType}
+          subHeaderText={otherSubHeaderText}
+        />
+      )) ||
+      (args.heroType === "campaign" && (
+        <Hero
+          {...args}
+          backgroundImageSrc="https://placeimg.com/2400/800/nature"
+          heading={<Heading level="one" id="1" text="Hero Campaign" />}
+          heroType={args.heroType}
+          imageProps={args.imageProps}
+          subHeaderText={otherSubHeaderText}
+        />
+      )) ||
+      (args.heroType === "fiftyFifty" && (
+        <Hero
+          {...args}
+          heroType={args.heroType}
+          imageProps={args.imageProps}
+          subHeaderText={otherSubHeaderText}
+        />
+      ))
+    }
+  </Story>
+</Canvas>
+
+<ArgsTable story="Hero with Controls" />
+
+## Accessibility
+
+The `Hero` component is commonly used as a banner below the page's header and
+breadcrumbs and above the main content. This means that if the `Hero` displays
+a heading element, it should be the first on the page and an `h1` element set
+through `Heading`'s `level="one"`.
+
+## All Variations
+
+Each `Hero` variation can be rendered through the `heroType` prop.
+
+### Primary
+
+The `"primary"` hero type can be used with the `backgroundColor`, `backgroundImageSrc`,
+`foregroundColor`, `heading`, `locationDetails`, and `subHeaderText` props. The
+minimum props that should be used are `backgroundImageSrc` and `heading`.
+
+```jsx
+backgroundImageSrc="https://placeimg.com/1600/800/arch"
+heading={<Heading level="one" id="primary-hero" text="Hero Primary" />}
+```
+
+<Canvas>
+  <DSProvider>
+    <Hero
+      backgroundImageSrc="https://placeimg.com/1600/800/arch"
+      heading={<Heading level="one" id="primary-hero" text="Hero Primary" />}
+      heroType="primary"
+    />
+  </DSProvider>
+</Canvas>
+
+### Secondary
+
+The `"secondary"` hero type can be used with the `heading`, `imageProps`, and
+`subHeaderText` props.
+
+```jsx
+heading={
+  <Heading level="one" id="secondary-hero" text="Hero Secondary" />
+}
+imageProps={imageProps}
+subHeaderText={secondarySubHeaderText}
+```
+
+<Canvas>
+  <DSProvider>
+    <Hero
+      heading={
+        <Heading level="one" id="secondary-hero" text="Hero Secondary" />
+      }
+      heroType="secondary"
+      imageProps={imageProps}
+      subHeaderText={secondarySubHeaderText}
+    />
+  </DSProvider>
+</Canvas>
+
+### Tertiary
+
+The `"tertiary"` hero type can be used with the `backgroundColor`, `foregroundColor`,
+`heading`, and `subHeaderText` props. The minimum prop to use is the `heading`
+prop.
+
+```jsx
+heading={
+  <Heading
+    level="one"
+    id="tertiary-hero"
+    text="Hero Tertiary with Sub-Header"
+  />
+}
+subHeaderText={otherSubHeaderText}
+```
+
+<Canvas>
+  <DSProvider>
+    <Hero
+      heading={
+        <Heading
+          level="one"
+          id="tertiary-hero"
+          text="Hero Tertiary with Sub-Header"
+        />
+      }
+      heroType="tertiary"
+      subHeaderText={otherSubHeaderText}
+    />
+    <br />
+    <Hero
+      heading={
+        <Heading
+          level="one"
+          id="tertiary-hero"
+          text="Hero Tertiary without Sub-Header text"
+        />
+      }
+      heroType="tertiary"
+    />
+  </DSProvider>
+</Canvas>
+
+### Campaign
+
+The `"campaign"` hero type can be used with the `backgroundColor`,
+`backgroundImageSrc`, `foregroundColor`, `heading`, `imageProps`, and
+`subHeaderText` props. The minimum props to use are `backgroundImageSrc`,
+`heading`, and `imageProps`.
+
+```jsx
+backgroundImageSrc="https://placeimg.com/2400/800/nature/grayscale"
+heading={
+  <Heading level="one" id="campaign-hero" text="Hero Campaign" />
+}
+imageProps={imageProps}
+subHeaderText={otherSubHeaderText}
+```
+
+<Canvas>
+  <DSProvider>
+    <Hero
+      backgroundImageSrc="https://placeimg.com/2400/800/nature/grayscale"
+      heroType="campaign"
+      heading={<Heading level="one" id="campaign-hero" text="Hero Campaign" />}
+      imageProps={imageProps}
+      subHeaderText={otherSubHeaderText}
+    />
+  </DSProvider>
+</Canvas>
+
+### FiftyFifty
+
+The `"fiftyFifty"` hero type can be used with the `backgroundColor`,
+`foregroundColor`, `heading`, `imageProps`, and `subHeaderText` props. The
+minimum props to use are `imageProps` and `subHeaderText`.
+
+```
+imageProps={imageProps}
+subHeaderText={otherSubHeaderText}
+```
+
+<Canvas>
+  <DSProvider>
+    <Hero
+      heroType="fiftyFifty"
+      imageProps={imageProps}
+      subHeaderText={otherSubHeaderText}
+    />
+  </DSProvider>
+</Canvas>
+
+## Color Variations for Secondary Hero
+
+The background color for the title bar in the `"secondary"` `Hero` changes based
+on the `heroType` variants for the `"secondary"` main variant. There are four
+subtypes: `"secondaryBooksAndMore"`, `"secondaryLocations"`, `"secondaryResearch"`,
+and `"secondaryWhatsOn"`.
+
+```jsx
+// Example `heroType` "secondary" variant.
+<Hero heroType="secondaryBooksAndMore" {...props} />
+```
+
+<Canvas>
+  <Story name="Color Variations for Secondary Hero">
+    <SimpleGrid columns={1}>
+      <Heading id="main-secondary-heading" text="secondary" />
+      <Hero
+        heading={
+          <Heading level="one" id="main-secondary-hero" text="Secondary" />
+        }
+        heroType="secondary"
+        imageProps={imageProps}
+        subHeaderText={secondarySubHeaderText}
+      />
+      <Heading id="books-heading" text="secondaryBooksAndMore" />
+      <Hero
+        heading={<Heading level="one" id="books-hero" text="Books and More" />}
+        heroType="secondaryBooksAndMore"
+        imageProps={imageProps}
+        subHeaderText={secondarySubHeaderText}
+      />
+      <Heading id="location-heading" text="secondaryLocations" />
+      <Hero
+        heading={<Heading level="one" id="locations-hero" text="Locations" />}
+        heroType="secondaryLocations"
+        imageProps={imageProps}
+        subHeaderText={secondarySubHeaderText}
+      />
+      <Heading id="research-heading" text="secondaryResearch" />
+      <Hero
+        heading={<Heading level="one" id="research-hero" text="Research" />}
+        heroType="secondaryResearch"
+        imageProps={imageProps}
+        subHeaderText={secondarySubHeaderText}
+      />
+      <Heading id="whats-on-heading" text="secondaryWhatsOn" />
+      <Hero
+        heading={<Heading level="one" id="whats-on-hero" text="What's On" />}
+        heroType="secondaryWhatsOn"
+        imageProps={imageProps}
+        subHeaderText={secondarySubHeaderText}
+      />
+    </SimpleGrid>
+  </Story>
+</Canvas>