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

package/src/components/Grid/__snapshots__/SimpleGrid.test.tsx.snap

@@ -0,0 +1,23 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`SimpleGrid Renders the SimpleGrid UI snapshot correctly 1`] = `
+<div
+  className="css-bjq6jk"
+  id="test-grid"
+/>
+`;
+
+exports[`SimpleGrid Renders the SimpleGrid UI snapshot correctly 2`] = `
+<div
+  className="css-161u8yz"
+  id="chakra"
+/>
+`;
+
+exports[`SimpleGrid Renders the SimpleGrid UI snapshot correctly 3`] = `
+<div
+  className="css-bjq6jk"
+  data-testid="props"
+  id="props"
+/>
+`;

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

@@ -0,0 +1,187 @@
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import Heading from "./Heading";
+import { getCategory } from "../../utils/componentCategories";
+
+<Meta
+  title={getCategory("Heading")}
+  component={Heading}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=10975%3A16",
+    },
+    jest: ["Heading.test.tsx"],
+  }}
+  argTypes={{
+    className: { control: false },
+    id: { control: false },
+    level: {
+      table: { defaultValue: { summary: "two" } },
+    },
+    noSpace: { table: { defaultValue: { summary: false } } },
+  }}
+/>
+
+# Heading
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.0.4`    |
+| Latest            | `1.0.2`    |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Default Heading Styles](#default-heading-styles)
+- [Size Styles](#size-styles)
+- [Heading with Bold Text](#heading-with-bold-text)
+- [Headings with Links](#headings-with-links)
+
+## Overview
+
+<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 `size` prop.
+
+## Component Props
+
+<Canvas withToolbar>
+  <Story
+    name="Heading with Controls"
+    args={{
+      className: undefined,
+      id: "heading-id",
+      level: "HeadingLevels.Two",
+      noSpace: false,
+      level: "two",
+      size: undefined,
+      text: "Default Heading",
+      url: undefined,
+      urlClass: undefined,
+    }}
+  >
+    {(args) => <Heading {...args} />}
+  </Story>
+</Canvas>
+
+<ArgsTable story="Heading with Controls" />
+
+## Accessibility
+
+When adding headings to a webpage, it is important to ensure that the heading
+hierarchy is consistent. This means they should start with only one `h1` for the
+page title and then proceed with `h2`s, `h3`s, `h4`s, `h5`s and `h6`s in the
+proper order and not skipping any. For example, the following is invalid HTML:
+
+```html
+<h1>Page Title</h1>
+<h2>Subtitle</h2>
+<h4>Sub-subtitle</h4>
+```
+
+Resources:
+
+- [W3C WAI Headings](https://www.w3.org/WAI/tutorials/page-structure/headings/)
+- [A11y Project Accessible heading structure](https://www.a11yproject.com/posts/how-to-accessible-heading-structure/)
+- [Chakra UI Heading](https://chakra-ui.com/docs/components/typography/heading)
+
+## Default Heading Styles
+
+<Canvas>
+  <Story name="Default Heading Styles">
+    <div>
+      <Heading id="heading-one" level="one" text="<h1> Heading 1 - 'one'" />
+      <Heading id="heading-two" level="two" text="<h2> Heading 2 - 'two'" />
+      <Heading
+        id="heading-three"
+        level="three"
+        text="<h3> Heading 3 - 'three'"
+      />
+      <Heading id="heading-four" level="four" text="<h4> Heading 4 - 'four'" />
+      <Heading id="heading-five" level="five" text="<h5> Heading 5 - 'five'" />
+      <Heading id="heading-six" level="six" text="<h6> Heading 6 - 'six'" />
+    </div>
+  </Story>
+</Canvas>
+
+## Size Styles
+
+Note: The `level` prop for the `Heading`s in the next example are all set to
+`level="one"`.
+
+<Canvas>
+  <Story name="Size Styles">
+    <div>
+      <Heading
+        id="heading-primary"
+        level="one"
+        size="primary"
+        text="<h1> 'primary'"
+      />
+      <Heading
+        id="heading-secondary"
+        level="one"
+        size="secondary"
+        text="<h1> 'secondary'"
+      />
+      <Heading
+        id="heading-tertiary"
+        level="one"
+        size="tertiary"
+        text="<h1> 'tertiary'"
+      />
+      <Heading
+        id="heading-callout"
+        level="one"
+        size="callout"
+        text="<h1> 'callout'"
+      />
+    </div>
+  </Story>
+</Canvas>
+
+## Heading with Bold Text
+
+<Canvas>
+  <Story name="Heading with Bold Text">
+    <Heading id="headingWithBold" level="one">
+      <>
+        Heading with a <b>Bold</b> Word
+      </>
+    </Heading>
+  </Story>
+</Canvas>
+
+## Headings with Links
+
+When the `url` prop is passed to `Heading`, a child `<a>` element is created and the heading text becomes an active link.
+
+<Canvas>
+  <Story name="Headings with Links">
+    <Heading
+      id="heading-with-link-url"
+      level="two"
+      text="Heading with URL Props"
+      url="http://apple.com"
+      urlClass="special-link"
+    />
+    <Heading id="heading-with-link-child">
+      <>
+        Heading with a Word <a href="#hello">Link</a>
+      </>
+    </Heading>
+  </Story>
+</Canvas>

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

@@ -0,0 +1,171 @@
+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";
+
+describe("Heading Accessibility", () => {
+  it("passes axe accessibility test", async () => {
+    const { container } = render(
+      <Heading id="h1" level="one" text="Heading 1" />
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("Heading", () => {
+  it("renders and HTML heading element with the correct level", () => {
+    render(<Heading id="h1" level="one" text="Heading 1" />);
+    expect(screen.getByRole("heading", { level: 1 })).toBeInTheDocument();
+    expect(screen.getByText("Heading 1")).toBeInTheDocument();
+  });
+
+  it("can pass heading content as child", () => {
+    render(<Heading id="h1">Heading 2</Heading>);
+    expect(screen.getByRole("heading", { level: 2 })).toBeInTheDocument();
+    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();
+  });
+
+  it("can pass a span element as a child", () => {
+    render(
+      <Heading id="h1" level="one">
+        <span>
+          Text <b>hi</b>
+        </span>
+      </Heading>
+    );
+    expect(screen.getByText(/Text/i)).toBeInTheDocument();
+  });
+
+  it("prioritizes the child when both child and the text prop are passed", () => {
+    render(
+      <Heading id="h1" level="one" text="prop text">
+        child text
+      </Heading>
+    );
+    expect(screen.getByText("child text")).toBeInTheDocument();
+  });
+
+  it("renders an anchor element when the `url` prop is passed", () => {
+    render(<Heading id="h1" level="one" text="Heading 1" url="fake-url" />);
+
+    expect(screen.getByRole("link")).toBeInTheDocument();
+  });
+
+  it("adds the `urlClass` prop to the anchor element as its class name", () => {
+    render(
+      <Heading
+        id="h1"
+        level="one"
+        url="fake-url"
+        urlClass="fake-class"
+        text="Heading 1"
+      />
+    );
+    expect(screen.getByRole("link").getAttribute("class")).toContain(
+      "fake-class"
+    );
+  });
+
+  it("throws error when neither child nor text is passed", () => {
+    expect(() => render(<Heading id="h1" level="one" />)).toThrow(
+      "NYPL Reservoir Heading: No children or value was passed to the `text` prop."
+    );
+  });
+
+  it("throws error when heading with many children is passed", () => {
+    expect(() =>
+      render(
+        <Heading id="h1" level="four">
+          <span>too</span>
+          <span>many</span>
+        </Heading>
+      )
+    ).toThrow("NYPL Reservoir Heading: Only pass one child into Heading.");
+  });
+
+  it("uses custom display size", () => {
+    render(
+      <Heading
+        id="h1"
+        level="one"
+        size="secondary"
+        text="Heading with Secondary size"
+      />
+    );
+    expect(screen.getByRole("heading", { level: 1 })).toHaveStyle({
+      "font-size": "2em",
+    });
+  });
+
+  it("renders the UI snapshot correctly", () => {
+    const basic = renderer
+      .create(<Heading id="basic" level="one" text="Heading text" />)
+      .toJSON();
+    const basicWithChildText = renderer
+      .create(
+        <Heading id="basicWithChildText" level="one">
+          Heading text
+        </Heading>
+      )
+      .toJSON();
+    const customDisplaySize = renderer
+      .create(
+        <Heading
+          id="customDisplaySize"
+          level="one"
+          size="secondary"
+          text="Heading with Secondary size"
+        />
+      )
+      .toJSON();
+    const otherLevel = renderer
+      .create(<Heading id="otherLevel" level="six" text="Heading level six" />)
+      .toJSON();
+    const withLink = renderer
+      .create(
+        <Heading
+          id="withLink"
+          level="one"
+          text="Heading text is a link"
+          url="fake-url"
+        />
+      )
+      .toJSON();
+    const withCustomLink = renderer
+      .create(
+        <Heading id="withCustomLink" level="one">
+          <>
+            Part of the heading text is
+            <a href="fake-url" className="custom-link">
+              <span>a link</span>
+            </a>
+          </>
+        </Heading>
+      )
+      .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <Heading id="chakra" text="Heading" p="20px" color="ui.red.primary" />
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(<Heading id="props" text="Heading" data-testid="props" />)
+      .toJSON();
+
+    expect(basic).toMatchSnapshot();
+    expect(basicWithChildText).toMatchSnapshot();
+    expect(customDisplaySize).toMatchSnapshot();
+    expect(otherLevel).toMatchSnapshot();
+    expect(withLink).toMatchSnapshot();
+    expect(withCustomLink).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
+  });
+});

package/src/components/Heading/Heading.tsx

@@ -0,0 +1,104 @@
+import {
+  chakra,
+  Heading as ChakraHeading,
+  useStyleConfig,
+} from "@chakra-ui/react";
+import * as React from "react";
+
+import Link from "../Link/Link";
+
+export type HeadingSizes = "primary" | "secondary" | "tertiary" | "callout";
+export type HeadingLevels = "one" | "two" | "three" | "four" | "five" | "six";
+export interface HeadingProps {
+  /** Optional className that appears in addition to `heading` */
+  className?: string;
+  /** 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>` */
+  level?: HeadingLevels;
+  /** Optional size used to override the default styles of the semantic HTM
+   * `<h>` elements */
+  size?: HeadingSizes;
+  /** Optional prop used to remove default spacing */
+  noSpace?: boolean;
+  /** 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 */
+  url?: string;
+  /** Optional className for the URL when the `url` prop is passed */
+  urlClass?: string;
+}
+
+/** Map the word heading level to the number heading level. The default is 2. */
+const getMappedLevel = (level = "two") => {
+  const levelMap = {
+    one: 1,
+    two: 2,
+    three: 3,
+    four: 4,
+    five: 5,
+    six: 6,
+  };
+  return levelMap[level] || 2;
+};
+
+export const Heading = chakra(
+  (props: React.PropsWithChildren<HeadingProps>) => {
+    const {
+      className,
+      id,
+      level = "two",
+      size,
+      noSpace,
+      text,
+      url,
+      urlClass,
+      ...rest
+    } = props;
+    const finalLevel = getMappedLevel(level);
+    const variant = size ? size : `h${finalLevel}`;
+    const styles = useStyleConfig("Heading", { variant, noSpace });
+    // Combine native base styles with any additional styles.
+    // This is used in the `Hero` and `Notification` components.
+    const asHeading: any = `h${finalLevel}`;
+
+    if (!props.children && !text) {
+      throw new Error(
+        "NYPL Reservoir Heading: No children or value was passed to the `text` prop."
+      );
+    }
+
+    if (React.Children.count(props.children) > 1) {
+      // Catching the error because React's error isn't as helpful.
+      throw new Error(
+        "NYPL Reservoir Heading: Only pass one child into Heading."
+      );
+    }
+
+    const contentToRender = props.children ? props.children : text;
+    const content = url ? (
+      <Link className={urlClass} href={url} id={`${id}-link`}>
+        {contentToRender}
+      </Link>
+    ) : (
+      contentToRender
+    );
+
+    return (
+      <ChakraHeading
+        as={asHeading}
+        className={className}
+        id={id}
+        sx={styles}
+        {...rest}
+      >
+        {content}
+      </ChakraHeading>
+    );
+  }
+);
+
+export default Heading;

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

@@ -0,0 +1,90 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Heading renders the UI snapshot correctly 1`] = `
+<h1
+  className="chakra-heading css-1xdhyk6"
+  id="basic"
+>
+  Heading text
+</h1>
+`;
+
+exports[`Heading renders the UI snapshot correctly 2`] = `
+<h1
+  className="chakra-heading css-1xdhyk6"
+  id="basicWithChildText"
+>
+  Heading text
+</h1>
+`;
+
+exports[`Heading renders the UI snapshot correctly 3`] = `
+<h1
+  className="chakra-heading css-1xdhyk6"
+  id="customDisplaySize"
+>
+  Heading with Secondary size
+</h1>
+`;
+
+exports[`Heading renders the UI snapshot correctly 4`] = `
+<h6
+  className="chakra-heading css-1xdhyk6"
+  id="otherLevel"
+>
+  Heading level six
+</h6>
+`;
+
+exports[`Heading renders the UI snapshot correctly 5`] = `
+<h1
+  className="chakra-heading css-1xdhyk6"
+  id="withLink"
+>
+  <a
+    className="css-1xdhyk6"
+    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-1xdhyk6"
+  id="withCustomLink"
+>
+  Part of the heading text is
+  <a
+    className="custom-link"
+    href="fake-url"
+  >
+    <span>
+      a link
+    </span>
+  </a>
+</h1>
+`;
+
+exports[`Heading renders the UI snapshot correctly 7`] = `
+<h2
+  className="chakra-heading css-10g9ftz"
+  id="chakra"
+>
+  Heading
+</h2>
+`;
+
+exports[`Heading renders the UI snapshot correctly 8`] = `
+<h2
+  className="chakra-heading css-1xdhyk6"
+  data-testid="props"
+  id="props"
+>
+  Heading
+</h2>
+`;