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

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

@@ -3,30 +3,31 @@
 exports[`Form Snapshot Renders the UI snapshot correctly 1`] = `
 <form
   aria-label="form"
+  className="css-0"
   id="snapshot-form"
 >
   <div
-    className="css-aq1pyb"
+    className="css-fadkce"
     id="snapshot-form-parent"
   >
     <div
-      className="css-1ao258g"
+      className="css-dofnwd"
       id="snapshot-form-child0"
     >
       <div
-        className="css-aq1pyb"
+        className="css-7ajbp2"
         id="snapshot-form-child0-grandchild0"
       >
         Form Field 1
       </div>
       <div
-        className="css-aq1pyb"
+        className="css-7ajbp2"
         id="snapshot-form-child0-grandchild1"
       >
         Form Field 2
       </div>
       <div
-        className="css-aq1pyb"
+        className="css-7ajbp2"
         id="snapshot-form-child0-grandchild2"
       >
         Form Field 3
@@ -35,3 +36,80 @@ exports[`Form Snapshot Renders the UI snapshot correctly 1`] = `
   </div>
 </form>
 `;
+
+exports[`Form Snapshot Renders the UI snapshot correctly 2`] = `
+<form
+  aria-label="form"
+  className="css-qvgr6z"
+  color="ui.error.primary"
+  id="chakra"
+  p="20px"
+>
+  <div
+    className="css-fadkce"
+    id="chakra-parent"
+  >
+    <div
+      className="css-dofnwd"
+      id="chakra-child0"
+    >
+      <div
+        className="css-7ajbp2"
+        id="chakra-child0-grandchild0"
+      >
+        Form Field 1
+      </div>
+      <div
+        className="css-7ajbp2"
+        id="chakra-child0-grandchild1"
+      >
+        Form Field 2
+      </div>
+      <div
+        className="css-7ajbp2"
+        id="chakra-child0-grandchild2"
+      >
+        Form Field 3
+      </div>
+    </div>
+  </div>
+</form>
+`;
+
+exports[`Form Snapshot Renders the UI snapshot correctly 3`] = `
+<form
+  aria-label="form"
+  className="css-0"
+  data-testid="props"
+  id="props"
+>
+  <div
+    className="css-fadkce"
+    id="props-parent"
+  >
+    <div
+      className="css-dofnwd"
+      id="props-child0"
+    >
+      <div
+        className="css-7ajbp2"
+        id="props-child0-grandchild0"
+      >
+        Form Field 1
+      </div>
+      <div
+        className="css-7ajbp2"
+        id="props-child0-grandchild1"
+      >
+        Form Field 2
+      </div>
+      <div
+        className="css-7ajbp2"
+        id="props-child0-grandchild2"
+      >
+        Form Field 3
+      </div>
+    </div>
+  </div>
+</form>
+`;

package/src/components/Grid/GridTypes.tsx

@@ -1,9 +1,9 @@
 export enum GridGaps {
-  ExtraExtraSmall = "xxs",
-  ExtraSmall = "xs",
-  Small = "s",
-  Medium = "m",
-  Large = "l",
-  ExtraLarge = "xl",
-  ExtraExtraLarge = "xxl",
+  ExtraExtraSmall = "grid.xxs",
+  ExtraSmall = "grid.xs",
+  Small = "grid.s",
+  Medium = "grid.m",
+  Large = "grid.l",
+  ExtraLarge = "grid.xl",
+  ExtraExtraLarge = "grid.xxl",
 }

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

@@ -10,8 +10,7 @@ import { withDesign } from "storybook-addon-designs";
 import SimpleGrid from "./SimpleGrid";
 import { GridGaps } from "./GridTypes";
 import Card, { CardHeading, CardContent, CardActions } from "../Card/Card";
-import { CardLayouts } from "../Card/CardTypes";
-import { HeadingDisplaySizes, HeadingLevels } from "../Heading/HeadingTypes";
+import { HeadingSizes, HeadingLevels } from "../Heading/HeadingTypes";
 import Icon from "../Icons/Icon";
 import {
   IconNames,
@@ -21,6 +20,7 @@ import {
 } from "../Icons/IconTypes";
 import Image from "../Image/Image";
 import { ImageRatios } from "../Image/ImageTypes";
+import { LayoutTypes } from "../../helpers/enums";
 import { getCategory } from "../../utils/componentCategories";
 import DSProvider from "../../theme/provider";
 import { getStorybookEnumValues } from "../../utils/utils";
@@ -57,13 +57,29 @@ export const enumValues = getStorybookEnumValues(GridGaps, "GridGaps");
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.25.1`   |
-| Latest            | `0.25.1`   |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Other SimpleGrid Examples](#other-simplegrid-examples)
+
+## Overview
 
 <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 `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.
 
-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.
+## Component Props
 
 <Canvas withToolbar>
   <Story
@@ -78,9 +94,11 @@ The NYPL standards for the items per row in a grid is `3` for desktop, `2` for t
     {(args) => (
       <SimpleGrid {...args} gap={enumValues.getValue(args.gap)}>
         <Card
-          imageSrc="https://placeimg.com/400/220/animals"
-          imageAlt="Alt text"
-          imageAspectRatio={ImageRatios.TwoByOne}
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: ImageRatios.TwoByOne,
+            src: "https://placeimg.com/400/220/animals",
+          }}
         >
           <CardHeading level={HeadingLevels.Three}>Card Heading</CardHeading>
           <CardContent>
@@ -89,9 +107,11 @@ The NYPL standards for the items per row in a grid is `3` for desktop, `2` for t
           </CardContent>
         </Card>
         <Card
-          imageSrc="https://placeimg.com/400/220/animals"
-          imageAlt="Alt text"
-          imageAspectRatio={ImageRatios.TwoByOne}
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: ImageRatios.TwoByOne,
+            src: "https://placeimg.com/400/220/animals",
+          }}
         >
           <CardHeading level={HeadingLevels.Three}>Card Heading</CardHeading>
           <CardContent>
@@ -100,9 +120,11 @@ The NYPL standards for the items per row in a grid is `3` for desktop, `2` for t
           </CardContent>
         </Card>
         <Card
-          imageSrc="https://placeimg.com/400/240/animals"
-          imageAlt="Alt text"
-          imageAspectRatio={ImageRatios.TwoByOne}
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: ImageRatios.TwoByOne,
+            src: "https://placeimg.com/400/240/animals",
+          }}
         >
           <CardHeading level={HeadingLevels.Three}>Card Heading</CardHeading>
           <CardContent>
@@ -111,9 +133,11 @@ The NYPL standards for the items per row in a grid is `3` for desktop, `2` for t
           </CardContent>
         </Card>
         <Card
-          imageSrc="https://placeimg.com/400/260/animals"
-          imageAlt="Alt text"
-          imageAspectRatio={ImageRatios.TwoByOne}
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: ImageRatios.TwoByOne,
+            src: "https://placeimg.com/400/260/animals",
+          }}
         >
           <CardHeading level={HeadingLevels.Three}>Card Heading</CardHeading>
           <CardContent>
@@ -122,9 +146,11 @@ The NYPL standards for the items per row in a grid is `3` for desktop, `2` for t
           </CardContent>
         </Card>
         <Card
-          imageSrc="https://placeimg.com/400/320/animals"
-          imageAlt="Alt text"
-          imageAspectRatio={ImageRatios.TwoByOne}
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: ImageRatios.TwoByOne,
+            src: "https://placeimg.com/400/320/animals",
+          }}
         >
           <CardHeading level={HeadingLevels.Three}>Card Heading</CardHeading>
           <CardContent>
@@ -133,9 +159,11 @@ The NYPL standards for the items per row in a grid is `3` for desktop, `2` for t
           </CardContent>
         </Card>
         <Card
-          imageSrc="https://placeimg.com/400/300/animals"
-          imageAlt="Alt text"
-          imageAspectRatio={ImageRatios.TwoByOne}
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: ImageRatios.TwoByOne,
+            src: "https://placeimg.com/400/300/animals",
+          }}
         >
           <CardHeading level={HeadingLevels.Three}>Card Heading</CardHeading>
           <CardContent>
@@ -150,6 +178,18 @@ The NYPL standards for the items per row in a grid is `3` for desktop, `2` for t
 
 <ArgsTable story="SimpleGrid with Controls" />
 
+## Accessibility
+
+The CSS grid layout properties are used for the `SimpleGrid` component. We don't
+recommend using property rules that change the visual order of elements on the
+page that don't match with its DOM order. This is because a screenreader won't
+pick up `SimpleGrid` CSS rules and will read the page in the expected DOM order
+rather than the visual order.
+
+Resources:
+
+- [MDN CSS Grid Layout and Accessibility](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout/CSS_Grid_Layout_and_Accessibility)
+
 ## Other SimpleGrid Examples
 
 ### Icons
@@ -213,12 +253,14 @@ This example is rendering horizontal `Card` components with the `columns` prop s
   <DSProvider>
     <SimpleGrid columns={1}>
       <Card
-        layout={CardLayouts.Row}
-        border
-        center
-        imageSrc="https://placeimg.com/400/200/animals"
-        imageAlt="Alt text"
-        imageAspectRatio={ImageRatios.FourByThree}
+        imageProps={{
+          alt: "Alt text",
+          aspectRatio: ImageRatios.FourByThree,
+          src: "https://placeimg.com/400/200/animals",
+        }}
+        isBordered
+        isCentered
+        layout={LayoutTypes.Row}
       >
         <CardHeading level={HeadingLevels.Four} id="heading1">
           Card Heading
@@ -230,12 +272,14 @@ This example is rendering horizontal `Card` components with the `columns` prop s
         </CardContent>
       </Card>
       <Card
-        layout={CardLayouts.Row}
-        border
-        center
-        imageSrc="https://placeimg.com/410/210/animals"
-        imageAlt="Alt text"
-        imageAspectRatio={ImageRatios.FourByThree}
+        imageProps={{
+          alt: "Alt text",
+          aspectRatio: ImageRatios.FourByThree,
+          src: "https://placeimg.com/410/210/animals",
+        }}
+        isBordered
+        isCentered
+        layout={LayoutTypes.Row}
       >
         <CardHeading level={HeadingLevels.Four} id="heading2">
           Card Heading
@@ -247,12 +291,14 @@ This example is rendering horizontal `Card` components with the `columns` prop s
         </CardContent>
       </Card>
       <Card
-        layout={CardLayouts.Row}
-        border
-        center
-        imageSrc="https://placeimg.com/320/320/animals"
-        imageAlt="Alt text"
-        imageAspectRatio={ImageRatios.FourByThree}
+        imageProps={{
+          alt: "Alt text",
+          aspectRatio: ImageRatios.FourByThree,
+          src: "https://placeimg.com/320/320/animals",
+        }}
+        isBordered
+        isCentered
+        layout={LayoutTypes.Row}
       >
         <CardHeading level={HeadingLevels.Four} id="heading3">
           Card Heading

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

@@ -13,9 +13,11 @@ describe("Grid Accessibility", () => {
     const { container } = render(
       <SimpleGrid>
         <Card
-          imageSrc="https://placeimg.com/500/200/animals"
-          imageAlt="Alt text"
-          imageAspectRatio={ImageRatios.TwoByOne}
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: ImageRatios.TwoByOne,
+            src: "https://placeimg.com/500/200/animals",
+          }}
         >
           <CardHeading level={HeadingLevels.Two}>Card Heading</CardHeading>
           <CardContent>
@@ -24,9 +26,11 @@ describe("Grid Accessibility", () => {
           </CardContent>
         </Card>
         <Card
-          imageSrc="https://placeimg.com/400/220/animals"
-          imageAlt="Alt text"
-          imageAspectRatio={ImageRatios.TwoByOne}
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: ImageRatios.TwoByOne,
+            src: "https://placeimg.com/400/220/animals",
+          }}
         >
           <CardHeading level={HeadingLevels.Three}>Card Heading</CardHeading>
           <CardContent>
@@ -35,9 +39,11 @@ describe("Grid Accessibility", () => {
           </CardContent>
         </Card>
         <Card
-          imageSrc="https://placeimg.com/400/240/animals"
-          imageAlt="Alt text"
-          imageAspectRatio={ImageRatios.TwoByOne}
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: ImageRatios.TwoByOne,
+            src: "https://placeimg.com/400/240/animals",
+          }}
         >
           <CardHeading level={HeadingLevels.Three}>Card Heading</CardHeading>
           <CardContent>
@@ -54,7 +60,16 @@ describe("Grid Accessibility", () => {
 describe("SimpleGrid", () => {
   it("Renders the SimpleGrid UI snapshot correctly", () => {
     const tree = renderer.create(<SimpleGrid id="test-grid" />).toJSON();
+    const withChakraProps = renderer
+      .create(<SimpleGrid id="chakra" p="20px" color="ui.error.primary" />)
+      .toJSON();
+    const withOtherProps = renderer
+      .create(<SimpleGrid id="props" data-testid="props" />)
+      .toJSON();
+
     expect(tree).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
   });
 
   it("Renders SimpleGrid component", () => {

package/src/components/Grid/SimpleGrid.tsx

@@ -1,9 +1,7 @@
+import { chakra, SimpleGrid as ChakraSimpleGrid } from "@chakra-ui/react";
 import * as React from "react";
-import { SimpleGrid as ChakraSimpleGrid } from "@chakra-ui/react";
-import { GridGaps } from "./GridTypes";
-
-import generateUUID from "../../helpers/generateUUID";
 
+import { GridGaps } from "./GridTypes";
 export interface SimpleGridProps {
   /** Additional class name. */
   className?: string;
@@ -15,23 +13,34 @@ export interface SimpleGridProps {
   id?: string;
 }
 
-function SimpleGrid(props: React.PropsWithChildren<SimpleGridProps>) {
-  const { children, columns, className, gap = GridGaps.Large, id } = props;
+export const SimpleGrid = chakra(
+  (props: React.PropsWithChildren<SimpleGridProps>) => {
+    const {
+      children,
+      columns,
+      className,
+      gap = GridGaps.Large,
+      id,
+      ...rest
+    } = props;
 
-  const responsiveCols = columns
-    ? { base: 1, md: columns }
-    : { base: 1, md: 2, lg: 3 };
+    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>
-  );
-}
+    return (
+      <ChakraSimpleGrid
+        columns={responsiveCols}
+        gap={gap}
+        id={id}
+        className={className}
+        {...rest}
+      >
+        {children}
+      </ChakraSimpleGrid>
+    );
+  },
+  { shouldForwardProp: () => true }
+);
 
 export default SimpleGrid;

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

@@ -2,7 +2,22 @@
 
 exports[`SimpleGrid Renders the SimpleGrid UI snapshot correctly 1`] = `
 <div
-  className="css-1tep0ti"
+  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

@@ -8,13 +8,13 @@ import {
 import { withDesign } from "storybook-addon-designs";
 
 import Heading from "./Heading";
-import { HeadingDisplaySizes, HeadingLevels } from "./HeadingTypes";
+import { HeadingSizes, HeadingLevels } from "./HeadingTypes";
 import { getCategory } from "../../utils/componentCategories";
 import { getStorybookEnumValues } from "../../utils/utils";
 
 export const sizesEnumValues = getStorybookEnumValues(
-  HeadingDisplaySizes,
-  "HeadingDisplaySizes"
+  HeadingSizes,
+  "HeadingSizes"
 );
 export const levelsEnumValues = getStorybookEnumValues(
   HeadingLevels,
@@ -35,16 +35,16 @@ export const levelsEnumValues = getStorybookEnumValues(
   argTypes={{
     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" } },
     },
+    size: {
+      control: { type: "select" },
+      options: sizesEnumValues.options,
+    },
   }}
 />
 
@@ -53,13 +53,27 @@ export const levelsEnumValues = getStorybookEnumValues(
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.0.4`    |
-| Latest            | `0.25.9`   |
+| Latest            | `0.26.0`   |
+
+## 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 `displaySize` prop.
+semantic elements can be overwritten using the `size` prop.
+
+## Component Props
 
 <Canvas withToolbar>
   <Story
@@ -67,9 +81,9 @@ semantic elements can be overwritten using the `displaySize` prop.
     args={{
       additionalStyles: undefined,
       className: undefined,
-      displaySize: undefined,
       id: "heading-id",
       level: "HeadingLevels.Two",
+      size: undefined,
       text: "Default Heading",
       url: undefined,
       urlClass: undefined,
@@ -78,10 +92,8 @@ semantic elements can be overwritten using the `displaySize` prop.
     {(args) => (
       <Heading
         {...args}
-        displaySize={
-          args.displaySize && sizesEnumValues.getValue(args.displaySize)
-        }
         level={levelsEnumValues.getValue(args.level)}
+        size={args.size && sizesEnumValues.getValue(args.size)}
       />
     )}
   </Story>
@@ -89,6 +101,25 @@ semantic elements can be overwritten using the `displaySize` prop.
 
 <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>
@@ -128,46 +159,46 @@ semantic elements can be overwritten using the `displaySize` prop.
   </Story>
 </Canvas>
 
-## DisplaySize Styles
+## Size 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">
+  <Story name="Size Styles">
     <div>
       <Heading
         id="heading-primary"
         level={HeadingLevels.One}
-        displaySize={HeadingDisplaySizes.Primary}
-        text="<h1> HeadingDisplaySizes.Primary"
+        size={HeadingSizes.Primary}
+        text="<h1> HeadingSizes.Primary"
       />
       <Heading
         id="heading-secondary"
         level={HeadingLevels.One}
-        displaySize={HeadingDisplaySizes.Secondary}
-        text="<h1> HeadingDisplaySizes.Secondary"
+        size={HeadingSizes.Secondary}
+        text="<h1> HeadingSizes.Secondary"
       />
       <Heading
         id="heading-tertiary"
         level={HeadingLevels.One}
-        displaySize={HeadingDisplaySizes.Tertiary}
-        text="<h1> HeadingDisplaySizes.Tertiary"
+        size={HeadingSizes.Tertiary}
+        text="<h1> HeadingSizes.Tertiary"
       />
       <Heading
         id="heading-callout"
         level={HeadingLevels.One}
-        displaySize={HeadingDisplaySizes.Callout}
-        text="<h1> HeadingDisplaySizes.Callout"
+        size={HeadingSizes.Callout}
+        text="<h1> HeadingSizes.Callout"
       />
     </div>
   </Story>
 </Canvas>
 
-## Heading with Bold
+## Heading with Bold Text
 
 <Canvas>
-  <Story name="Heading with Bold">
+  <Story name="Heading with Bold Text">
     <Heading id="headingWithBold" level={HeadingLevels.One}>
       <>
         Heading with a <b>Bold</b> Word