@nypl/design-system-react-components 0.23.4 → 0.25.1

package/src/components/Grid/SimpleGrid.stories.mdx

@@ -0,0 +1,275 @@
+import {
+  Meta,
+  Story,
+  Canvas,
+  ArgsTable,
+  Description,
+} from "@storybook/addon-docs/blocks";
+import { withDesign } from "storybook-addon-designs";
+
+import SimpleGrid from "./SimpleGrid";
+import Card, {
+  CardImage,
+  CardHeading,
+  CardContent,
+  CardActions,
+} from "../Card/Card";
+import {
+  CardImageRatios,
+  CardImageSizes,
+  CardLayouts,
+} from "../Card/CardTypes";
+import { HeadingDisplaySizes, HeadingLevels } from "../Heading/HeadingTypes";
+import Icon from "../Icons/Icon";
+import {
+  IconNames,
+  LogoNames,
+  IconSizes,
+  IconRotationTypes,
+} from "../Icons/IconTypes";
+import Image from "../Image/Image";
+
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta
+  title={getCategory("SimpleGrid")}
+  component={SimpleGrid}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url:
+        "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=36835%3A26613",
+    },
+    jest: ["SimpleGrid.test.tsx"],
+  }}
+  argTypes={{
+    columns: {
+      control: {
+        type: "number",
+        min: 2,
+      },
+      table: {
+        defaultValue: {
+          summary: 3,
+        },
+      },
+    },
+    gap: {
+      table: {
+        defaultValue: {
+          summary: "l",
+        },
+      },
+    },
+    className: { table: { disable: true } },
+    id: { table: { disable: true } },
+  }}
+/>
+
+# SimpleGrid
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.25.1`   |
+| Latest            | `0.25.1`   |
+
+<Description of={SimpleGrid} />
+
+The `SimpleGrid` component is used to render UI elements in a uniform grid layout, with the column widths and grid spacing fixed throughout the grid.
+
+The NYPL standards for the items per row in a grid is `3` for desktop, `2` for tablet and `1` for mobile. By default, the `SimpleGrid` component uses these standards and the `columns` prop is optional. If the `columns` prop is used, the tablet breakpoint will be dropped and only the mobile breakpoint (1 item per row) will be triggered.
+
+<Canvas withToolbar>
+  <Story name="SimpleGrid Props">
+    {(args) => (
+      <SimpleGrid {...args}>
+        <Card
+          imageSrc="https://placeimg.com/500/200/animals"
+          imageAlt="Alt text"
+          imageAspectRatio={CardImageRatios.TwoByOne}
+        >
+          <CardHeading level={HeadingLevels.Three}>Card Heading</CardHeading>
+          <CardContent>
+            Vestibulum id ligula porta felis euismod semper. Nulla vitae elit
+            libero, a pharetra augue.
+          </CardContent>
+        </Card>
+        <Card
+          imageSrc="https://placeimg.com/400/220/animals"
+          imageAlt="Alt text"
+          imageAspectRatio={CardImageRatios.TwoByOne}
+        >
+          <CardHeading level={HeadingLevels.Three}>Card Heading</CardHeading>
+          <CardContent>
+            Vestibulum id ligula porta felis euismod semper. Nulla vitae elit
+            libero, a pharetra augue.
+          </CardContent>
+        </Card>
+        <Card
+          imageSrc="https://placeimg.com/400/240/animals"
+          imageAlt="Alt text"
+          imageAspectRatio={CardImageRatios.TwoByOne}
+        >
+          <CardHeading level={HeadingLevels.Three}>Card Heading</CardHeading>
+          <CardContent>
+            Vestibulum id ligula porta felis euismod semper. Nulla vitae elit
+            libero, a pharetra augue.
+          </CardContent>
+        </Card>
+        <Card
+          imageSrc="https://placeimg.com/400/260/animals"
+          imageAlt="Alt text"
+          imageAspectRatio={CardImageRatios.TwoByOne}
+        >
+          <CardHeading level={HeadingLevels.Three}>Card Heading</CardHeading>
+          <CardContent>
+            Vestibulum id ligula porta felis euismod semper. Nulla vitae elit
+            libero, a pharetra augue.
+          </CardContent>
+        </Card>
+        <Card
+          imageSrc="https://placeimg.com/400/320/animals"
+          imageAlt="Alt text"
+          imageAspectRatio={CardImageRatios.TwoByOne}
+        >
+          <CardHeading level={HeadingLevels.Three}>Card Heading</CardHeading>
+          <CardContent>
+            Vestibulum id ligula porta felis euismod semper. Nulla vitae elit
+            libero, a pharetra augue.
+          </CardContent>
+        </Card>
+        <Card
+          imageSrc="https://placeimg.com/400/300/animals"
+          imageAlt="Alt text"
+          imageAspectRatio={CardImageRatios.TwoByOne}
+        >
+          <CardHeading level={HeadingLevels.Three}>Card Heading</CardHeading>
+          <CardContent>
+            Vestibulum id ligula porta felis euismod semper. Nulla vitae elit
+            libero, a pharetra augue.
+          </CardContent>
+        </Card>
+      </SimpleGrid>
+    )}
+  </Story>
+</Canvas>
+
+<ArgsTable story="SimpleGrid Props" />
+
+## Other SimpleGrid Examples
+
+### Icons
+
+This example is rendering `Icon` components with the `columns` prop set to `5`.
+
+export const icons = [];
+for (const icon in IconNames) {
+  const iname = `Example icon: ${IconNames[icon]}`;
+  const iconRender = (
+    <Icon
+      name={IconNames[icon]}
+      size={IconSizes.ExtraExtraExtraLarge}
+      titleText={iname}
+    />
+  );
+  icons.push(iconRender);
+}
+
+<Canvas>
+  <Story name="Other SimpleGrid Examples">
+    <SimpleGrid columns={5}>{icons}</SimpleGrid>
+  </Story>
+</Canvas>
+
+### Images
+
+This example is rendering square `Image` components with the `columns` prop set to `6`.
+
+<Canvas>
+  <DSProvider>
+    <SimpleGrid columns={6}>
+      <Image src="https://placeimg.com/300/300/animals?x=1" />
+      <Image src="https://placeimg.com/300/300/animals?x=2" />
+      <Image src="https://placeimg.com/300/300/animals?x=3" />
+      <Image src="https://placeimg.com/300/300/animals?x=4" />
+      <Image src="https://placeimg.com/300/300/animals?x=5" />
+      <Image src="https://placeimg.com/300/300/animals?x=6" />
+      <Image src="https://placeimg.com/300/300/animals?x=7" />
+      <Image src="https://placeimg.com/300/300/animals?x=8" />
+      <Image src="https://placeimg.com/300/300/animals?x=9" />
+      <Image src="https://placeimg.com/300/300/animals?x=10" />
+      <Image src="https://placeimg.com/300/300/animals?x=11" />
+      <Image src="https://placeimg.com/300/300/animals?x=12" />
+      <Image src="https://placeimg.com/300/300/animals?x=13" />
+      <Image src="https://placeimg.com/300/300/animals?x=14" />
+      <Image src="https://placeimg.com/300/300/animals?x=15" />
+      <Image src="https://placeimg.com/300/300/animals?x=16" />
+      <Image src="https://placeimg.com/300/300/animals?x=17" />
+      <Image src="https://placeimg.com/300/300/animals?x=18" />
+    </SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+### Horizontal Cards
+
+This example is rendering horizontal `Card` components with the `columns` prop set to `1`.
+
+<Canvas>
+  <DSProvider>
+    <SimpleGrid columns={1}>
+      <Card
+        layout={CardLayouts.Row}
+        border
+        center
+        imageSrc="https://placeimg.com/400/200/animals"
+        imageAlt="Alt text"
+        imageAspectRatio={CardImageRatios.FourByThree}
+      >
+        <CardHeading level={HeadingLevels.Four} id="heading1">
+          Card Heading
+        </CardHeading>
+        <CardContent>
+          Praesent commodo cursus magna, vel scelerisque nisl consectetur et.
+          Sed posuere consectetur est at lobortis. Cras justo odio, dapibus ac
+          facilisis in, egestas eget quam.
+        </CardContent>
+      </Card>
+      <Card
+        layout={CardLayouts.Row}
+        border
+        center
+        imageSrc="https://placeimg.com/410/210/animals"
+        imageAlt="Alt text"
+        imageAspectRatio={CardImageRatios.FourByThree}
+      >
+        <CardHeading level={HeadingLevels.Four} id="heading2">
+          Card Heading
+        </CardHeading>
+        <CardContent>
+          Praesent commodo cursus magna, vel scelerisque nisl consectetur et.
+          Sed posuere consectetur est at lobortis. Cras justo odio, dapibus ac
+          facilisis in, egestas eget quam.
+        </CardContent>
+      </Card>
+      <Card
+        layout={CardLayouts.Row}
+        border
+        center
+        imageSrc="https://placeimg.com/320/320/animals"
+        imageAlt="Alt text"
+        imageAspectRatio={CardImageRatios.FourByThree}
+      >
+        <CardHeading level={HeadingLevels.Four} id="heading3">
+          Card Heading
+        </CardHeading>
+        <CardContent>
+          Praesent commodo cursus magna, vel scelerisque nisl consectetur et.
+          Sed posuere consectetur est at lobortis. Cras justo odio, dapibus ac
+          facilisis in, egestas eget quam.
+        </CardContent>
+      </Card>
+    </SimpleGrid>
+  </DSProvider>
+</Canvas>

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

@@ -0,0 +1,66 @@
+import * as React from "react";
+import { render } from "@testing-library/react";
+import { axe } from "jest-axe";
+import renderer from "react-test-renderer";
+
+import SimpleGrid from "./SimpleGrid";
+import Card, { CardHeading, CardContent } from "../Card/Card";
+import { CardImageRatios } from "../Card/CardTypes";
+import { HeadingLevels } from "../Heading/HeadingTypes";
+
+describe("Grid Accessibility", () => {
+  it("passes axe accessibility test with children components", async () => {
+    const { container } = render(
+      <SimpleGrid>
+        <Card
+          imageSrc="https://placeimg.com/500/200/animals"
+          imageAlt="Alt text"
+          imageAspectRatio={CardImageRatios.TwoByOne}
+        >
+          <CardHeading level={HeadingLevels.Two}>Card Heading</CardHeading>
+          <CardContent>
+            Vestibulum id ligula porta felis euismod semper. Nulla vitae elit
+            libero, a pharetra augue.
+          </CardContent>
+        </Card>
+        <Card
+          imageSrc="https://placeimg.com/400/220/animals"
+          imageAlt="Alt text"
+          imageAspectRatio={CardImageRatios.TwoByOne}
+        >
+          <CardHeading level={HeadingLevels.Three}>Card Heading</CardHeading>
+          <CardContent>
+            Vestibulum id ligula porta felis euismod semper. Nulla vitae elit
+            libero, a pharetra augue.
+          </CardContent>
+        </Card>
+        <Card
+          imageSrc="https://placeimg.com/400/240/animals"
+          imageAlt="Alt text"
+          imageAspectRatio={CardImageRatios.TwoByOne}
+        >
+          <CardHeading level={HeadingLevels.Three}>Card Heading</CardHeading>
+          <CardContent>
+            Vestibulum id ligula porta felis euismod semper. Nulla vitae elit
+            libero, a pharetra augue.
+          </CardContent>
+        </Card>
+      </SimpleGrid>
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("SimpleGrid", () => {
+  it("Renders the SimpleGrid UI snapshot correctly", () => {
+    const tree = renderer.create(<SimpleGrid id="test-grid" />).toJSON();
+    expect(tree).toMatchSnapshot();
+  });
+
+  it("Renders SimpleGrid component", () => {
+    const utils = render(<SimpleGrid id="test-grid-render" />);
+    expect(
+      utils.container.querySelector("#test-grid-render")
+    ).toBeInTheDocument();
+  });
+});

package/src/components/Grid/SimpleGrid.tsx

@@ -0,0 +1,37 @@
+import * as React from "react";
+import { SimpleGrid as ChakraSimpleGrid } from "@chakra-ui/react";
+import { GridGaps } from "./GridTypes";
+
+import generateUUID from "../../helpers/generateUUID";
+
+export interface SimpleGridProps {
+  /** Additional class name. */
+  className?: string;
+  /** Optional numeric value to override the default column count; the default column count is 3 */
+  columns?: number;
+  /** Optional gap size; if omitted, the default `large` (2rem / 32px) spacing will be used; ```IMPORTANT: for standard grid layouts, this prop should not be used``` */
+  gap?: GridGaps;
+  /** ID that other components can cross reference for accessibility purposes */
+  id?: string;
+}
+
+function SimpleGrid(props: React.PropsWithChildren<SimpleGridProps>) {
+  const { children, columns, className, gap = GridGaps.Large, id } = props;
+
+  const responsiveCols = columns
+    ? { base: 1, md: columns }
+    : { base: 1, md: 2, lg: 3 };
+
+  return (
+    <ChakraSimpleGrid
+      columns={responsiveCols}
+      gap={gap}
+      id={id || generateUUID()}
+      className={className}
+    >
+      {children}
+    </ChakraSimpleGrid>
+  );
+}
+
+export default SimpleGrid;

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

@@ -0,0 +1,8 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`SimpleGrid Renders the SimpleGrid UI snapshot correctly 1`] = `
+<div
+  className="css-1tep0ti"
+  id="test-grid"
+/>
+`;

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

@@ -9,10 +9,11 @@ import {
 import { withDesign } from "storybook-addon-designs";
 
 import Heading from "./Heading";
-import { HeadingDisplaySizes } from "./HeadingDisplaySizes";
+import { HeadingDisplaySizes, HeadingLevels } from "./HeadingTypes";
+import { getCategory } from "../../utils/componentCategories";
 
 <Meta
-  title="Heading"
+  title={getCategory("Heading")}
   component={Heading}
   decorators={[withDesign]}
   parameters={{
@@ -27,107 +28,136 @@ import { HeadingDisplaySizes } from "./HeadingDisplaySizes";
     blockName: { table: { disable: true } },
     className: { table: { disable: true } },
     modifiers: { table: { disable: true } },
+    sx: { table: { disable: true } },
   }}
 />
 
 # Heading
 
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.0.4`    |
+| Latest            | `0.25.0`   |
+
 <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.
 
-<Preview withToolbar>
+<Canvas withToolbar>
   <Story
     name="Heading Props"
     args={{
-      id: "heading1",
-      level: 1,
-      text: "Heading  1",
+      id: "default-heading",
+      text: "Default Heading",
     }}
   >
     {(args) => <Heading {...args} />}
   </Story>
-</Preview>
+</Canvas>
 
 <ArgsTable story="Heading Props" />
 
 ## Default Heading Styles
 
-<Preview>
+<Canvas>
   <Story name="Default Heading Styles">
     <div>
-      <Heading id="heading1" level={1} text="<h1> Heading 1" />
-      <Heading id="heading2" level={2} text="<h2> Heading 2" />
-      <Heading id="heading3" level={3} text="<h3> Heading 3" />
-      <Heading id="heading4" level={4} text="<h4> Heading 4" />
-      <Heading id="heading5" level={5} text="<h5> Heading 5" />
-      <Heading id="heading6" level={6} text="<h6> Heading 6" />
+      <Heading
+        id="heading-one"
+        level={HeadingLevels.One}
+        text="<h1> Heading 1"
+      />
+      <Heading
+        id="heading-two"
+        level={HeadingLevels.Two}
+        text="<h2> Heading 2"
+      />
+      <Heading
+        id="heading-three"
+        level={HeadingLevels.Three}
+        text="<h3> Heading 3"
+      />
+      <Heading
+        id="heading-four"
+        level={HeadingLevels.Four}
+        text="<h4> Heading 4"
+      />
+      <Heading
+        id="heading-five"
+        level={HeadingLevels.Five}
+        text="<h5> Heading 5"
+      />
+      <Heading
+        id="heading-six"
+        level={HeadingLevels.Six}
+        text="<h6> Heading 6"
+      />
     </div>
   </Story>
-</Preview>
+</Canvas>
 
 ## DisplaySize Styles
 
-<Preview>
+<Canvas>
   <Story name="DisplaySize Styles">
     <div>
       <Heading
-        id="heading1"
-        level={1}
+        id="heading-primary"
+        level={HeadingLevels.One}
         displaySize={HeadingDisplaySizes.Primary}
         text="<h1> HeadingDisplaySizes.Primary"
       />
       <Heading
-        id="heading1"
-        level={1}
+        id="heading-secondary"
+        level={HeadingLevels.One}
         displaySize={HeadingDisplaySizes.Secondary}
         text="<h1> HeadingDisplaySizes.Secondary"
       />
       <Heading
-        id="heading1"
-        level={1}
+        id="heading-tertiary"
+        level={HeadingLevels.One}
         displaySize={HeadingDisplaySizes.Tertiary}
         text="<h1> HeadingDisplaySizes.Tertiary"
       />
       <Heading
-        id="heading1"
-        level={1}
+        id="heading-callout"
+        level={HeadingLevels.One}
         displaySize={HeadingDisplaySizes.Callout}
         text="<h1> HeadingDisplaySizes.Callout"
       />
     </div>
   </Story>
-</Preview>
+</Canvas>
 
 ## Heading with Bold
 
-<Preview>
+<Canvas>
   <Story name="Heading with Bold">
-    <Heading id="headingWithBold" level={2}>
+    <Heading id="headingWithBold" level={HeadingLevels.One}>
       <>
         Heading with a <b>Bold</b> Word
       </>
     </Heading>
   </Story>
-</Preview>
+</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.
 
-<Preview>
+<Canvas>
   <Story name="Headings with Links">
     <Heading
-      id="headingWithLink"
-      level={2}
+      id="heading-with-link-url"
+      level={HeadingLevels.Two}
       text="Heading with URL Props"
       url="http://apple.com"
       urlClass="special-link"
     />
-    <Heading id="headingWithLink" level={2}>
+    <Heading id="heading-with-link-child" level={HeadingLevels.Two}>
       <>
         Heading with a Word <a href="hello">Link</a>
       </>
     </Heading>
   </Story>
-</Preview>
+</Canvas>

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

@@ -3,12 +3,12 @@ import { render, screen } from "@testing-library/react";
 import { axe } from "jest-axe";
 
 import Heading from "./Heading";
-import { HeadingDisplaySizes } from "./HeadingDisplaySizes";
+import { HeadingDisplaySizes, HeadingLevels } from "./HeadingTypes";
 
 describe("Heading Accessibility", () => {
   it("passes axe accessibility test", async () => {
     const { container } = render(
-      <Heading id="h1" level={1} text="Heading 1" />
+      <Heading id="h1" level={HeadingLevels.One} text="Heading 1" />
     );
     expect(await axe(container)).toHaveNoViolations();
   });
@@ -16,13 +16,13 @@ describe("Heading Accessibility", () => {
 
 describe("Heading", () => {
   it("Shows heading", () => {
-    render(<Heading id="h1" level={1} text="Heading 1" />);
+    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", () => {
     render(
-      <Heading id="h1" level={2}>
+      <Heading id="h1" level={HeadingLevels.Two}>
         Heading 2
       </Heading>
     );
@@ -32,13 +32,13 @@ describe("Heading", () => {
 
   // TODO: check that header children are links
   // it("Throws error when invalid heading is passed as child", () => {
-  //   expect(() => render(<Heading id="h1" level={3}><span>oh no</span></Heading>))
+  //   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", () => {
     render(
-      <Heading id="h1" level={1}>
+      <Heading id="h1" level={HeadingLevels.One}>
         <span>
           Text <b>hi</b>
         </span>
@@ -49,7 +49,7 @@ describe("Heading", () => {
 
   it("uses child when both child and the text prop are passed", () => {
     render(
-      <Heading id="h1" level={1} text="prop text">
+      <Heading id="h1" level={HeadingLevels.One} text="prop text">
         child text
       </Heading>
     );
@@ -57,7 +57,14 @@ describe("Heading", () => {
   });
 
   it("Has <a> tag when passed URL", () => {
-    render(<Heading id="h1" level={1} url="fake-url" text="Heading 1" />);
+    render(
+      <Heading
+        id="h1"
+        level={HeadingLevels.One}
+        url="fake-url"
+        text="Heading 1"
+      />
+    );
 
     expect(screen.getByRole("link")).toBeInTheDocument();
   });
@@ -66,13 +73,15 @@ describe("Heading", () => {
     render(
       <Heading
         id="h1"
-        level={1}
+        level={HeadingLevels.One}
         url="fake-url"
         urlClass="fake-class"
         text="Heading 1"
       />
     );
-    expect(screen.getByRole("link")).toHaveAttribute("class", "fake-class");
+    expect(screen.getByRole("link").getAttribute("class")).toContain(
+      "fake-class"
+    );
   });
 
   it("Throws error when invalid heading number passed", () => {
@@ -90,7 +99,7 @@ describe("Heading", () => {
   it("Throws error when heading with many children is passed", () => {
     expect(() =>
       render(
-        <Heading id="h1" level={4}>
+        <Heading id="h1" level={HeadingLevels.Four}>
           <span>too</span>
           <span>many</span>
         </Heading>
@@ -102,14 +111,13 @@ describe("Heading", () => {
     render(
       <Heading
         id="h1"
-        level={1}
+        level={HeadingLevels.One}
         text="Heading with Secondary displaySize"
         displaySize={HeadingDisplaySizes.Secondary}
       />
     );
-    expect(screen.getByRole("heading", { level: 1 })).toHaveAttribute(
-      "class",
-      "heading heading--secondary "
-    );
+    expect(screen.getByRole("heading", { level: 1 })).toHaveStyle({
+      "font-size": "2em",
+    });
   });
 });