@nypl/design-system-react-components 0.26.0 → 0.28.0

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

@@ -1,4 +1,3 @@
-import { Box, VStack } from "@chakra-ui/react";
 import {
   ArgsTable,
   Canvas,
@@ -9,14 +8,11 @@ import {
 import { withDesign } from "storybook-addon-designs";
 
 import Heading from "../Heading/Heading";
-import { HeadingLevels } from "../Heading/HeadingTypes";
-import Hero from "./Hero";
-import { HeroTypes, HeroSecondaryTypes } from "./HeroTypes";
+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";
-import { getStorybookEnumValues } from "../../utils/utils";
-
-export const enumValues = getStorybookEnumValues(HeroTypes, "HeroTypes");
 
 <Meta
   title={getCategory("Hero")}
@@ -34,12 +30,9 @@ export const enumValues = getStorybookEnumValues(HeroTypes, "HeroTypes");
     foregroundColor: { control: false },
     heading: { control: false },
     heroType: {
-      control: { type: "select" },
-      table: { defaultValue: { summary: "HeroTypes.Primary" } },
-      options: enumValues.options,
+      table: { defaultValue: { summary: "primary" } },
     },
-    imageAlt: { control: false },
-    imageSrc: { control: false },
+    imageProps: { control: false },
     locationDetails: { control: false },
     subHeaderText: { control: false },
   }}
@@ -55,15 +48,17 @@ export const secondarySubHeaderText = (
 );
 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.";
-const imageAlt = "Image example";
-const imageSrc = "https://placeimg.com/800/400/animals";
+export const imageProps = {
+  alt: "Image example",
+  src: "https://placeimg.com/800/400/animals",
+};
 
 # Hero
 
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.2.0`    |
-| Latest            | `0.26.0`   |
+| Latest            | `0.28.0`   |
 
 ## Table of Contents
 
@@ -81,6 +76,31 @@ 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>
@@ -91,68 +111,56 @@ descriptive text and images.
       backgroundImageSrc: undefined,
       foregroundColor: undefined,
       heading: undefined,
-      heroType: "HeroTypes.Primary",
-      imageAlt: undefined,
-      imageSrc: undefined,
+      heroType: "primary",
+      imageProps: undefined,
       locationDetails: undefined,
       subHeaderText: undefined,
     }}
   >
     {(args) =>
-      (args.heroType === "HeroTypes.Primary" && (
+      (args.heroType === "primary" && (
         <Hero
           {...args}
           backgroundImageSrc="https://placeimg.com/2400/800/nature"
-          heading={
-            <Heading level={HeadingLevels.One} id="1" text="Hero Primary" />
-          }
-          heroType={enumValues.getValue(args.heroType)}
+          heading={<Heading level="one" id="1" text="Hero Primary" />}
+          heroType={args.heroType}
           subHeaderText="Example Subtitle"
         />
       )) ||
-      (HeroSecondaryTypes.includes(enumValues.getValue(args.heroType)) && (
+      (heroSecondaryTypes.includes(args.heroType) && (
         <div className="nypl--books-and-more">
           <Hero
             {...args}
-            heading={
-              <Heading level={HeadingLevels.One} id="1" text="Hero Secondary" />
-            }
-            heroType={enumValues.getValue(args.heroType)}
-            imageAlt={args.imageAlt}
-            imageSrc={args.imageSrc}
+            heading={<Heading level="one" id="1" text="Hero Secondary" />}
+            heroType={args.heroType}
+            imageProps={args.imageProps}
             subHeaderText={secondarySubHeaderText}
           />
         </div>
       )) ||
-      (args.heroType === "HeroTypes.Tertiary" && (
+      (args.heroType === "tertiary" && (
         <Hero
           {...args}
-          heading={
-            <Heading level={HeadingLevels.One} id="1" text="Hero Tertiary" />
-          }
-          heroType={enumValues.getValue(args.heroType)}
+          heading={<Heading level="one" id="1" text="Hero Tertiary" />}
+          heroType={args.heroType}
           subHeaderText={otherSubHeaderText}
         />
       )) ||
-      (args.heroType === "HeroTypes.Campaign" && (
+      (args.heroType === "campaign" && (
         <Hero
           {...args}
           backgroundImageSrc="https://placeimg.com/2400/800/nature"
-          heading={
-            <Heading level={HeadingLevels.One} id="1" text="Hero Campaign" />
-          }
-          heroType={enumValues.getValue(args.heroType)}
-          imageAlt={args.imageAlt}
-          imageSrc={args.imageSrc}
+          heading={<Heading level="one" id="1" text="Hero Campaign" />}
+          heroType={args.heroType}
+          imageProps={args.imageProps}
           subHeaderText={otherSubHeaderText}
         />
       )) ||
-      (args.heroType === "HeroTypes.FiftyFifty" && (
+      (args.heroType === "fiftyFifty" && (
         <Hero
           {...args}
-          heroType={enumValues.getValue(args.heroType)}
-          imageAlt={args.imageAlt}
-          imageSrc={args.imageSrc}
+          heroType={args.heroType}
+          imageProps={args.imageProps}
           subHeaderText={otherSubHeaderText}
         />
       ))
@@ -167,209 +175,204 @@ descriptive text and images.
 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={HeadingLevels.One}`.
+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>
-    <VStack spacing={10} align="stretch">
-      <Heading level={HeadingLevels.Two} text="Primary" id="primary-heading" />
-      <Hero
-        backgroundImageSrc="https://placeimg.com/1600/800/arch"
-        heading={
-          <Heading
-            level={HeadingLevels.One}
-            id="primary-hero"
-            text="Hero Primary"
-          />
-        }
-        heroType={HeroTypes.Primary}
-      />
-      <Heading
-        id="secondary-heading"
-        level={HeadingLevels.Two}
-        text="Secondary"
-      />
-      <div className="nypl--locations">
-        <Hero
-          heading={
-            <Heading
-              level={HeadingLevels.One}
-              id="secondary-hero"
-              text="Hero Secondary"
-            />
-          }
-          heroType={HeroTypes.Secondary}
-          imageAlt={imageAlt}
-          imageSrc={imageSrc}
-          subHeaderText={secondarySubHeaderText}
+    <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"
         />
-      </div>
-      <Heading
-        id="tertiary-heading"
-        level={HeadingLevels.Two}
-        text="Tertiary"
-      />
-      <Hero
-        heading={
-          <Heading
-            level={HeadingLevels.One}
-            id="tertiary-hero"
-            text="Hero Tertiary with Sub-Header"
-          />
-        }
-        heroType={HeroTypes.Tertiary}
-        subHeaderText={otherSubHeaderText}
-      />
-      <Hero
-        heading={
-          <Heading
-            level={HeadingLevels.One}
-            id="tertiary-hero"
-            text="Hero Tertiary without Sub-Header"
-          />
-        }
-        heroType={HeroTypes.Tertiary}
-      />
-      <Heading
-        id="campaign-heading"
-        level={HeadingLevels.Two}
-        text="Campaign"
-      />
-      <Hero
-        backgroundImageSrc="https://placeimg.com/2400/800/nature/grayscale"
-        heroType={HeroTypes.Campaign}
-        heading={
-          <Heading
-            level={HeadingLevels.One}
-            id="campaign-hero"
-            text="Hero Campaign"
-          />
-        }
-        imageAlt={imageAlt}
-        imageSrc={imageSrc}
-        subHeaderText={otherSubHeaderText}
-      />
-      <Box marginTop="30px" />
-      <Heading
-        id="fiftyfifty-heading"
-        level={HeadingLevels.Two}
-        text="FiftyFifty"
-      />
-      <Hero
-        heroType={HeroTypes.FiftyFifty}
-        imageAlt={imageAlt}
-        imageSrc={imageSrc}
-        subHeaderText={otherSubHeaderText}
-      />
-    </VStack>
+      }
+      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 `HeroTypes` variants for the `Secondary` main variant.
+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 `HeroTypes` "Secondary" variant.
-<Hero heroType={HeroTypes.SecondaryBooksAndMore} {...props} />
+// Example `heroType` "secondary" variant.
+<Hero heroType="secondaryBooksAndMore" {...props} />
 ```
 
 <Canvas>
   <Story name="Color Variations for Secondary Hero">
-    <VStack spacing={10} align="stretch">
-      <Heading
-        id="main-secondary-heading"
-        level={HeadingLevels.Two}
-        text="HeroTypes.Secondary"
-      />
+    <SimpleGrid columns={1}>
+      <Heading id="main-secondary-heading" text="secondary" />
       <Hero
         heading={
-          <Heading
-            level={HeadingLevels.One}
-            id="main-secondary-hero"
-            text="Secondary"
-          />
+          <Heading level="one" id="main-secondary-hero" text="Secondary" />
         }
-        heroType={HeroTypes.Secondary}
-        imageAlt={imageAlt}
-        imageSrc={imageSrc}
+        heroType="secondary"
+        imageProps={imageProps}
         subHeaderText={secondarySubHeaderText}
       />
-      <Heading
-        id="books-heading"
-        level={HeadingLevels.Two}
-        text="HeroTypes.SecondaryBooksAndMore"
-      />
+      <Heading id="books-heading" text="secondaryBooksAndMore" />
       <Hero
-        heading={
-          <Heading
-            level={HeadingLevels.One}
-            id="books-hero"
-            text="Books and More"
-          />
-        }
-        heroType={HeroTypes.SecondaryBooksAndMore}
-        imageAlt={imageAlt}
-        imageSrc={imageSrc}
+        heading={<Heading level="one" id="books-hero" text="Books and More" />}
+        heroType="secondaryBooksAndMore"
+        imageProps={imageProps}
         subHeaderText={secondarySubHeaderText}
       />
-      <Heading
-        id="location-heading"
-        level={HeadingLevels.Two}
-        text="HeroTypes.SecondaryLocations"
-      />
+      <Heading id="location-heading" text="secondaryLocations" />
       <Hero
-        heading={
-          <Heading
-            level={HeadingLevels.One}
-            id="locations-hero"
-            text="Locations"
-          />
-        }
-        heroType={HeroTypes.SecondaryLocations}
-        imageAlt={imageAlt}
-        imageSrc={imageSrc}
+        heading={<Heading level="one" id="locations-hero" text="Locations" />}
+        heroType="secondaryLocations"
+        imageProps={imageProps}
         subHeaderText={secondarySubHeaderText}
       />
-      <Heading
-        id="research-heading"
-        level={HeadingLevels.Two}
-        text="HeroTypes.SecondaryResearch"
-      />
+      <Heading id="research-heading" text="secondaryResearch" />
       <Hero
-        heading={
-          <Heading
-            level={HeadingLevels.One}
-            id="research-hero"
-            text="Research"
-          />
-        }
-        heroType={HeroTypes.SecondaryResearch}
-        imageAlt={imageAlt}
-        imageSrc={imageSrc}
+        heading={<Heading level="one" id="research-hero" text="Research" />}
+        heroType="secondaryResearch"
+        imageProps={imageProps}
         subHeaderText={secondarySubHeaderText}
       />
-      <Heading
-        id="whats-on-heading"
-        level={HeadingLevels.Two}
-        text="HeroTypes.SecondaryWhatsOn"
-      />
+      <Heading id="whats-on-heading" text="secondaryWhatsOn" />
       <Hero
-        heading={
-          <Heading
-            level={HeadingLevels.One}
-            id="whats-on-hero"
-            text="What's On"
-          />
-        }
-        heroType={HeroTypes.SecondaryWhatsOn}
-        imageAlt={imageAlt}
-        imageSrc={imageSrc}
+        heading={<Heading level="one" id="whats-on-hero" text="What's On" />}
+        heroType="secondaryWhatsOn"
+        imageProps={imageProps}
         subHeaderText={secondarySubHeaderText}
       />
-    </VStack>
+    </SimpleGrid>
   </Story>
 </Canvas>