@nypl/design-system-react-components 0.25.7 → 0.25.10

package/src/components/Heading/Heading.stories.mdx

@@ -1,16 +1,25 @@
 import {
-  Meta,
-  Story,
-  Canvas,
   ArgsTable,
-  Preview,
+  Canvas,
   Description,
-} from "@storybook/addon-docs/blocks";
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
 import { withDesign } from "storybook-addon-designs";
 
 import Heading from "./Heading";
 import { HeadingDisplaySizes, HeadingLevels } from "./HeadingTypes";
 import { getCategory } from "../../utils/componentCategories";
+import { getStorybookEnumValues } from "../../utils/utils";
+
+export const sizesEnumValues = getStorybookEnumValues(
+  HeadingDisplaySizes,
+  "HeadingDisplaySizes"
+);
+export const levelsEnumValues = getStorybookEnumValues(
+  HeadingLevels,
+  "HeadingLevels"
+);
 
 <Meta
   title={getCategory("Heading")}
@@ -19,15 +28,23 @@ import { getCategory } from "../../utils/componentCategories";
   parameters={{
     design: {
       type: "figma",
-      url:
-        "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=10975%3A16",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=10975%3A16",
     },
     jest: ["Heading.test.tsx"],
   }}
   argTypes={{
-    additionalStyles: { table: { disable: true } },
-    className: { table: { disable: true } },
-    id: { table: { disable: true } },
+    additionalStyles: { control: false },
+    className: { control: false },
+    displaySize: {
+      control: { type: "select" },
+      options: sizesEnumValues.options,
+    },
+    id: { control: false },
+    level: {
+      control: { type: "select" },
+      options: levelsEnumValues.options,
+      table: { defaultValue: { summary: "HeadingLevels.Two" } },
+    },
   }}
 />
 
@@ -36,25 +53,41 @@ import { getCategory } from "../../utils/componentCategories";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.0.4`    |
-| Latest            | `0.25.2`   |
+| Latest            | `0.25.9`   |
 
 <Description of={Heading} />
 
-A `Heading` component will render a standard HTML `<h>` tag (1-6). The heading's text can be passed in through a `text` prop or as a child. Default styles for semantic elements can be overwritten using the `displaySize` prop.
+A `Heading` component will render a standard HTML `<h>` tag (1-6). The heading's
+text can be passed in through a `text` prop or as a child. Default styles for
+semantic elements can be overwritten using the `displaySize` prop.
 
 <Canvas withToolbar>
   <Story
-    name="Heading Props"
+    name="Heading with Controls"
     args={{
-      id: "default-heading",
+      additionalStyles: undefined,
+      className: undefined,
+      displaySize: undefined,
+      id: "heading-id",
+      level: "HeadingLevels.Two",
       text: "Default Heading",
+      url: undefined,
+      urlClass: undefined,
     }}
   >
-    {(args) => <Heading {...args} />}
+    {(args) => (
+      <Heading
+        {...args}
+        displaySize={
+          args.displaySize && sizesEnumValues.getValue(args.displaySize)
+        }
+        level={levelsEnumValues.getValue(args.level)}
+      />
+    )}
   </Story>
 </Canvas>
 
-<ArgsTable story="Heading Props" />
+<ArgsTable story="Heading with Controls" />
 
 ## Default Heading Styles
 
@@ -64,32 +97,32 @@ A `Heading` component will render a standard HTML `<h>` tag (1-6). The heading's
       <Heading
         id="heading-one"
         level={HeadingLevels.One}
-        text="<h1> Heading 1"
+        text="<h1> Heading 1 - HeadingLevels.One"
       />
       <Heading
         id="heading-two"
         level={HeadingLevels.Two}
-        text="<h2> Heading 2"
+        text="<h2> Heading 2 - HeadingLevels.Two"
       />
       <Heading
         id="heading-three"
         level={HeadingLevels.Three}
-        text="<h3> Heading 3"
+        text="<h3> Heading 3 - HeadingLevels.Three"
       />
       <Heading
         id="heading-four"
         level={HeadingLevels.Four}
-        text="<h4> Heading 4"
+        text="<h4> Heading 4 - HeadingLevels.Four"
       />
       <Heading
         id="heading-five"
         level={HeadingLevels.Five}
-        text="<h5> Heading 5"
+        text="<h5> Heading 5 - HeadingLevels.Five"
       />
       <Heading
         id="heading-six"
         level={HeadingLevels.Six}
-        text="<h6> Heading 6"
+        text="<h6> Heading 6 - HeadingLevels.Six"
       />
     </div>
   </Story>
@@ -97,6 +130,9 @@ A `Heading` component will render a standard HTML `<h>` tag (1-6). The heading's
 
 ## DisplaySize Styles
 
+Note: The `level` prop for the `Heading`s in the next example are all set to
+`level={HeadingLevels.One}`.
+
 <Canvas>
   <Story name="DisplaySize Styles">
     <div>
@@ -155,7 +191,7 @@ When the `url` prop is passed to `Heading`, a child `<a>` element is created and
     />
     <Heading id="heading-with-link-child" level={HeadingLevels.Two}>
       <>
-        Heading with a Word <a href="hello">Link</a>
+        Heading with a Word <a href="#hello">Link</a>
       </>
     </Heading>
   </Story>

package/src/components/Heading/Heading.test.tsx

@@ -1,6 +1,7 @@
 import * as React from "react";
 import { render, screen } from "@testing-library/react";
 import { axe } from "jest-axe";
+import renderer from "react-test-renderer";
 
 import Heading from "./Heading";
 import { HeadingDisplaySizes, HeadingLevels } from "./HeadingTypes";
@@ -15,12 +16,13 @@ describe("Heading Accessibility", () => {
 });
 
 describe("Heading", () => {
-  it("Shows heading", () => {
+  it("renders and HTML heading element with the correct level", () => {
     render(<Heading id="h1" level={HeadingLevels.One} text="Heading 1" />);
     expect(screen.getByRole("heading", { level: 1 })).toBeInTheDocument();
     expect(screen.getByText("Heading 1")).toBeInTheDocument();
   });
-  it("Can pass heading content as child", () => {
+
+  it("can pass heading content as child", () => {
     render(
       <Heading id="h1" level={HeadingLevels.Two}>
         Heading 2
@@ -30,13 +32,18 @@ describe("Heading", () => {
     expect(screen.getByText("Heading 2")).toBeInTheDocument();
   });
 
+  it("renders the default level two if no `level` prop is passed", () => {
+    render(<Heading id="h2">Heading 2</Heading>);
+    expect(screen.getByRole("heading", { level: 2 })).toBeInTheDocument();
+  });
+
   // TODO: check that header children are links
   // it("Throws error when invalid heading is passed as child", () => {
   //   expect(() => render(<Heading id="h1" level={HeadingLevels.Three}><span>oh no</span></Heading>))
   //   .to.throw("Headings can only be plain text or bold");
   // });
 
-  it("Can pass heading content as child span", () => {
+  it("can pass a span element as a child", () => {
     render(
       <Heading id="h1" level={HeadingLevels.One}>
         <span>
@@ -47,7 +54,7 @@ describe("Heading", () => {
     expect(screen.getByText(/Text/i)).toBeInTheDocument();
   });
 
-  it("uses child when both child and the text prop are passed", () => {
+  it("prioritizes the child when both child and the text prop are passed", () => {
     render(
       <Heading id="h1" level={HeadingLevels.One} text="prop text">
         child text
@@ -56,20 +63,20 @@ describe("Heading", () => {
     expect(screen.getByText("child text")).toBeInTheDocument();
   });
 
-  it("Has <a> tag when passed URL", () => {
+  it("renders an anchor element when the `url` prop is passed", () => {
     render(
       <Heading
         id="h1"
         level={HeadingLevels.One}
-        url="fake-url"
         text="Heading 1"
+        url="fake-url"
       />
     );
 
     expect(screen.getByRole("link")).toBeInTheDocument();
   });
 
-  it("<a> has class when passed urlClass", () => {
+  it("adds the `urlClass` prop to the anchor element as its class name", () => {
     render(
       <Heading
         id="h1"
@@ -84,19 +91,13 @@ describe("Heading", () => {
     );
   });
 
-  it("Throws error when invalid heading number passed", () => {
-    expect(() =>
-      render(<Heading id="h1" level={9} text="Heading 9" />)
-    ).toThrow("Heading only supports levels 1-6");
-  });
-
-  it("Throws error when neither child nor text is passed", () => {
-    expect(() => render(<Heading id="h1" level={9} />)).toThrow(
-      "Heading only supports levels 1-6"
+  it("throws error when neither child nor text is passed", () => {
+    expect(() => render(<Heading id="h1" level={HeadingLevels.One} />)).toThrow(
+      "Heading has no children, please pass prop: text"
     );
   });
 
-  it("Throws error when heading with many children is passed", () => {
+  it("throws error when heading with many children is passed", () => {
     expect(() =>
       render(
         <Heading id="h1" level={HeadingLevels.Four}>
@@ -107,7 +108,7 @@ describe("Heading", () => {
     ).toThrow("Please only pass one child into Heading, got span, span");
   });
 
-  it("Uses custom display size", () => {
+  it("uses custom display size", () => {
     render(
       <Heading
         id="h1"
@@ -120,4 +121,67 @@ describe("Heading", () => {
       "font-size": "2em",
     });
   });
+
+  it("renders the UI snapshot correctly", () => {
+    const basic = renderer
+      .create(
+        <Heading id="basic" level={HeadingLevels.One} text="Heading text" />
+      )
+      .toJSON();
+    const basicWithChildText = renderer
+      .create(
+        <Heading id="basicWithChildText" level={HeadingLevels.One}>
+          Heading text
+        </Heading>
+      )
+      .toJSON();
+    const customDisplaySize = renderer
+      .create(
+        <Heading
+          id="customDisplaySize"
+          level={HeadingLevels.One}
+          text="Heading with Secondary displaySize"
+          displaySize={HeadingDisplaySizes.Secondary}
+        />
+      )
+      .toJSON();
+    const otherLevel = renderer
+      .create(
+        <Heading
+          id="otherLevel"
+          level={HeadingLevels.Six}
+          text="Heading level six"
+        />
+      )
+      .toJSON();
+    const withLink = renderer
+      .create(
+        <Heading
+          id="withLink"
+          level={HeadingLevels.One}
+          text="Heading text is a link"
+          url="fake-url"
+        />
+      )
+      .toJSON();
+    const withCustomLink = renderer
+      .create(
+        <Heading id="withCustomLink" level={HeadingLevels.One}>
+          <>
+            Part of the heading text is
+            <a href="fake-url" className="custom-link">
+              <span>a link</span>
+            </a>
+          </>
+        </Heading>
+      )
+      .toJSON();
+
+    expect(basic).toMatchSnapshot();
+    expect(basicWithChildText).toMatchSnapshot();
+    expect(customDisplaySize).toMatchSnapshot();
+    expect(otherLevel).toMatchSnapshot();
+    expect(withLink).toMatchSnapshot();
+    expect(withCustomLink).toMatchSnapshot();
+  });
 });

package/src/components/Heading/Heading.tsx

@@ -1,67 +1,67 @@
-// MT-82, MT 225, etc
+import { Heading as ChakraHeading, useStyleConfig } from "@chakra-ui/react";
 import * as React from "react";
-import {
-  Box,
-  Heading as ChakraHeading,
-  Link as ChakraLink,
-  useStyleConfig,
-} from "@chakra-ui/react";
 
 import { HeadingDisplaySizes, HeadingLevels } from "./HeadingTypes";
+import Link from "../Link/Link";
+import { getVariant } from "../../utils/utils";
+import generateUUID from "../../helpers/generateUUID";
 
 export interface HeadingProps {
   /** Optionally pass in additional Chakra-based styles. */
   additionalStyles?: { [key: string]: any };
   /** Optional className that appears in addition to `heading` */
   className?: string;
-  /** Optional size used to override the default styles of the semantic HTML `<h>` elements */
+  /** Optional size used to override the default styles of the semantic HTM
+   * `<h>` elements */
   displaySize?: HeadingDisplaySizes;
   /** Optional ID that other components can cross reference for accessibility purposes */
   id?: string;
-  /** Optional number 1-6 used to create the `<h*>` tag; if prop is not passed, `Heading` will default to `<h2>` */
+  /** Optional number 1-6 used to create the `<h*>` tag; if prop is not passed,
+   * `Heading` will default to `<h2>` */
   level?: HeadingLevels;
   /** Inner text of the `<h*>` element */
   text?: string;
-  /** Optional URL that header points to; when `url` prop is passed to `Heading`, a child `<a>` element is created and the heading text becomes an active link */
+  /** Optional URL that header points to; when `url` prop is passed to
+   * `Heading`, a child `<a>` element is created and the heading text becomes
+   * an active link */
   url?: string;
   /** Optional className for the URL when the `url` prop is passed */
   urlClass?: string;
 }
 
-// Used to map between ButtonTypes enum values and Chakra variant options.
-const variantMap = {};
-for (const type in HeadingDisplaySizes) {
-  variantMap[HeadingDisplaySizes[type]] = HeadingDisplaySizes[type];
-}
-
-/**
- * Map the HeadingDisplaySizes to the Heading Chakra theme variant object. If a wrong
- * value is passed (typically in non-Typescript scenarios), then the default
- * is "null" and displaySize is not envoked.
- */
-const getVariant = (displaySize) => variantMap[displaySize] || null;
+/** Map the word heading level to the number heading level. The default is 2. */
+const getMappedLevel = (level = HeadingLevels.Two) => {
+  const levelMap = {
+    one: 1,
+    two: 2,
+    three: 3,
+    four: 4,
+    five: 5,
+    six: 6,
+  };
+  return levelMap[level] || 2;
+};
 
 function Heading(props: React.PropsWithChildren<HeadingProps>) {
   const {
     additionalStyles = {},
     className,
     displaySize,
-    id,
+    id = generateUUID(),
     level = HeadingLevels.Two,
     text,
     url,
     urlClass,
   } = props;
-  const variant = displaySize ? getVariant(displaySize) : `h${level}`;
+  const finalLevel = getMappedLevel(level);
+  const variant = displaySize
+    ? getVariant(displaySize, HeadingDisplaySizes)
+    : `h${finalLevel}`;
   const styles = useStyleConfig("Heading", { variant });
   // Combine native base styles with any additional styles.
   // This is used in the `Hero` and `Notification` components.
   const finalStyles = { ...styles, ...additionalStyles };
-  const asHeading: any = `h${level}`;
-
-  if (level < 1 || level > 6) {
-    throw new Error("Heading only supports levels 1-6");
-  }
+  const asHeading: any = `h${finalLevel}`;
 
   if (!props.children && !text) {
     throw new Error("Heading has no children, please pass prop: text");
@@ -80,9 +80,9 @@ function Heading(props: React.PropsWithChildren<HeadingProps>) {
 
   const contentToRender = props.children ? props.children : text;
   const content = url ? (
-    <Box as={ChakraLink} href={url} className={urlClass}>
+    <Link className={urlClass} href={url} id={`${id}-link`}>
       {contentToRender}
-    </Box>
+    </Link>
   ) : (
     contentToRender
   );

package/src/components/Heading/HeadingTypes.tsx

@@ -6,10 +6,10 @@ export enum HeadingDisplaySizes {
 }
 
 export enum HeadingLevels {
-  One = 1,
-  Two = 2,
-  Three = 3,
-  Four = 4,
-  Five = 5,
-  Six = 6,
+  One = "one",
+  Two = "two",
+  Three = "three",
+  Four = "four",
+  Five = "five",
+  Six = "six",
 }

package/src/components/Heading/__snapshots__/Heading.test.tsx.snap

@@ -0,0 +1,71 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Heading renders the UI snapshot correctly 1`] = `
+<h1
+  className="chakra-heading css-0"
+  id="basic"
+>
+  Heading text
+</h1>
+`;
+
+exports[`Heading renders the UI snapshot correctly 2`] = `
+<h1
+  className="chakra-heading css-0"
+  id="basicWithChildText"
+>
+  Heading text
+</h1>
+`;
+
+exports[`Heading renders the UI snapshot correctly 3`] = `
+<h1
+  className="chakra-heading css-0"
+  id="customDisplaySize"
+>
+  Heading with Secondary displaySize
+</h1>
+`;
+
+exports[`Heading renders the UI snapshot correctly 4`] = `
+<h6
+  className="chakra-heading css-0"
+  id="otherLevel"
+>
+  Heading level six
+</h6>
+`;
+
+exports[`Heading renders the UI snapshot correctly 5`] = `
+<h1
+  className="chakra-heading css-0"
+  id="withLink"
+>
+  <a
+    className="css-0"
+    href="fake-url"
+    id="withLink-link"
+    rel={null}
+    target={null}
+  >
+    Heading text is a link
+  </a>
+</h1>
+`;
+
+exports[`Heading renders the UI snapshot correctly 6`] = `
+<h1
+  className="chakra-heading css-0"
+  id="withCustomLink"
+>
+  Part of the heading text is
+  <a
+    className="custom-link"
+    href="fake-url"
+  >
+    <span>
+      a link
+    </span>
+  </a>
+</h1>
+`;

package/src/components/HelperErrorText/HelperErrorText.stories.mdx

@@ -1,13 +1,15 @@
 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 HelperErrorText from "./HelperErrorText";
+import Link from "../Link/Link";
+import Text from "../Text/Text";
 import { getCategory } from "../../utils/componentCategories";
 import DSProvider from "../../theme/provider";
 
@@ -23,10 +25,20 @@ import DSProvider from "../../theme/provider";
     jest: ["HelperErrorText.test.tsx"],
   }}
   argTypes={{
-    ariaAtomic: { table: { disable: true } },
+    additionalStyles: { control: false },
+    ariaAtomic: {
+      control: false,
+      table: { defaultValue: { summary: true } },
+    },
+    ariaLive: {
+      table: { defaultValue: { summary: "polite" } },
+    },
     children: { table: { disable: true } },
-    className: { table: { disable: true } },
-    id: { table: { disable: true } },
+    className: { control: false },
+    id: { control: false },
+    isInvalid: {
+      table: { defaultValue: { summary: false } },
+    },
   }}
 />
 
@@ -35,41 +47,57 @@ import DSProvider from "../../theme/provider";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.0.10`   |
-| Latest            | `0.25.3`   |
+| Latest            | `0.25.9`   |
 
 <Description of={HelperErrorText} />
 
 <Canvas withToolbar>
   <Story
-    name="Basic with Props"
+    name="HelperErrorText with Controls"
     args={{
+      additionalStyles: undefined,
+      ariaAtomic: undefined,
       ariaLive: "polite",
+      className: undefined,
+      id: "helperErrorText-id",
       isInvalid: false,
+      text: "This is the helper text!",
     }}
   >
     {(args) => (
-      <HelperErrorText {...args}>
-        {args.isInvalid
-          ? "This is the error text :("
-          : "This is the helper text!"}
-      </HelperErrorText>
+      <HelperErrorText
+        {...args}
+        text={args.isInvalid ? "This is the error text :(" : args.text}
+      />
     )}
   </Story>
 </Canvas>
 
-<ArgsTable story="Basic with Props" />
+<ArgsTable story="HelperErrorText with Controls" />
 
 ## With HTML Children
 
-The `HelperErrorText` component can take any React component or HTML element as
-its children.
+The `HelperErrorText` component can render any React component or HTML element
+through the `text` prop.
 
 <Canvas>
   <Story name="With HTML Children">
-    <HelperErrorText>
-      If you're unsure of your size, please view the{" "}
-      <a href="#sizing-chart">Sizing Chart</a>.
-    </HelperErrorText>
+    <HelperErrorText
+      text={
+        <>
+          This first example uses an HTML anchor element for{" "}
+          <a href="#">a link</a>.
+        </>
+      }
+    />
+    <HelperErrorText
+      text={
+        <Text>
+          This second example uses DS components, such as the{" "}
+          <Link href="#">`Link`</Link> component, and the `Text` component.
+        </Text>
+      }
+    />
   </Story>
 </Canvas>
 
@@ -80,7 +108,7 @@ NYPL "invalid" styling.
 
 <Canvas>
   <Story name="Invalid State">
-    <HelperErrorText isInvalid>This is the error text :(</HelperErrorText>
+    <HelperErrorText isInvalid text="This is the error text :(" />
   </Story>
 </Canvas>
 
@@ -107,7 +135,7 @@ announced immediately.
 
 <Canvas>
   <Story
-    name="With Aria Props"
+    name="With Aria Controls"
     args={{
       ariaAtomic: true,
       ariaLive: "polite",
@@ -115,10 +143,10 @@ announced immediately.
     }}
   >
     {(args) => (
-      <HelperErrorText {...args}>
-        Only invalid text can be read to screen readers with the appropriate
-        aria-atomic and aria-live props.
-      </HelperErrorText>
+      <HelperErrorText
+        {...args}
+        text="Only invalid text can be read to screen readers with the appropriate aria-atomic and aria-live props."
+      />
     )}
   </Story>
 </Canvas>