@nypl/design-system-react-components 0.25.13 → 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

@@ -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
@@ -162,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
@@ -225,12 +253,12 @@ This example is rendering horizontal `Card` components with the `columns` prop s
   <DSProvider>
     <SimpleGrid columns={1}>
       <Card
-        border
         imageProps={{
           alt: "Alt text",
           aspectRatio: ImageRatios.FourByThree,
           src: "https://placeimg.com/400/200/animals",
         }}
+        isBordered
         isCentered
         layout={LayoutTypes.Row}
       >
@@ -244,12 +272,12 @@ This example is rendering horizontal `Card` components with the `columns` prop s
         </CardContent>
       </Card>
       <Card
-        border
         imageProps={{
           alt: "Alt text",
           aspectRatio: ImageRatios.FourByThree,
           src: "https://placeimg.com/410/210/animals",
         }}
+        isBordered
         isCentered
         layout={LayoutTypes.Row}
       >
@@ -263,12 +291,12 @@ This example is rendering horizontal `Card` components with the `columns` prop s
         </CardContent>
       </Card>
       <Card
-        border
         imageProps={{
           alt: "Alt text",
           aspectRatio: ImageRatios.FourByThree,
           src: "https://placeimg.com/320/320/animals",
         }}
+        isBordered
         isCentered
         layout={LayoutTypes.Row}
       >

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

@@ -60,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

@@ -53,7 +53,19 @@ export const levelsEnumValues = getStorybookEnumValues(
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.0.4`    |
-| Latest            | `0.25.13`  |
+| 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} />
 
@@ -61,6 +73,8 @@ 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"
@@ -87,6 +101,25 @@ semantic elements can be overwritten using the `size` 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>
@@ -162,10 +195,10 @@ Note: The `level` prop for the `Heading`s in the next example are all set to
   </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

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

@@ -176,6 +176,14 @@ describe("Heading", () => {
         </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();
@@ -183,5 +191,7 @@ describe("Heading", () => {
     expect(otherLevel).toMatchSnapshot();
     expect(withLink).toMatchSnapshot();
     expect(withCustomLink).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
   });
 });

package/src/components/Heading/Heading.tsx

@@ -1,11 +1,13 @@
-import { Heading as ChakraHeading, useStyleConfig } from "@chakra-ui/react";
+import {
+  chakra,
+  Heading as ChakraHeading,
+  useStyleConfig,
+} from "@chakra-ui/react";
 import * as React from "react";
 
 import { HeadingSizes, 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 };
@@ -42,57 +44,61 @@ const getMappedLevel = (level = HeadingLevels.Two) => {
   return levelMap[level] || 2;
 };
 
-function Heading(props: React.PropsWithChildren<HeadingProps>) {
-  const {
-    additionalStyles = {},
-    className,
-    id = generateUUID(),
-    level = HeadingLevels.Two,
-    size,
-    text,
-    url,
-    urlClass,
-  } = props;
-  const finalLevel = getMappedLevel(level);
-  const variant = size ? getVariant(size, HeadingSizes) : `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${finalLevel}`;
+export const Heading = chakra(
+  (props: React.PropsWithChildren<HeadingProps>) => {
+    const {
+      additionalStyles = {},
+      className,
+      id,
+      level = HeadingLevels.Two,
+      size,
+      text,
+      url,
+      urlClass,
+      ...rest
+    } = props;
+    const finalLevel = getMappedLevel(level);
+    const variant = size ? getVariant(size, HeadingSizes) : `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${finalLevel}`;
+
+    if (!props.children && !text) {
+      throw new Error(
+        "NYPL Reservoir Heading: No children or value was passed to the `text` prop."
+      );
+    }
 
-  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
     );
-  }
 
-  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."
+    return (
+      <ChakraHeading
+        as={asHeading}
+        className={className}
+        id={id}
+        sx={finalStyles}
+        {...rest}
+      >
+        {content}
+      </ChakraHeading>
     );
   }
-
-  const contentToRender = props.children ? props.children : text;
-  const content = url ? (
-    <Link className={urlClass} href={url} id={`${id}-link`}>
-      {contentToRender}
-    </Link>
-  ) : (
-    contentToRender
-  );
-
-  return (
-    <ChakraHeading
-      id={id}
-      as={asHeading}
-      sx={finalStyles}
-      className={className}
-    >
-      {content}
-    </ChakraHeading>
-  );
-}
+);
 
 export default Heading;

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

@@ -2,7 +2,7 @@
 
 exports[`Heading renders the UI snapshot correctly 1`] = `
 <h1
-  className="chakra-heading css-0"
+  className="chakra-heading css-1xdhyk6"
   id="basic"
 >
   Heading text
@@ -11,7 +11,7 @@ exports[`Heading renders the UI snapshot correctly 1`] = `
 
 exports[`Heading renders the UI snapshot correctly 2`] = `
 <h1
-  className="chakra-heading css-0"
+  className="chakra-heading css-1xdhyk6"
   id="basicWithChildText"
 >
   Heading text
@@ -20,7 +20,7 @@ exports[`Heading renders the UI snapshot correctly 2`] = `
 
 exports[`Heading renders the UI snapshot correctly 3`] = `
 <h1
-  className="chakra-heading css-0"
+  className="chakra-heading css-1xdhyk6"
   id="customDisplaySize"
 >
   Heading with Secondary size
@@ -29,7 +29,7 @@ exports[`Heading renders the UI snapshot correctly 3`] = `
 
 exports[`Heading renders the UI snapshot correctly 4`] = `
 <h6
-  className="chakra-heading css-0"
+  className="chakra-heading css-1xdhyk6"
   id="otherLevel"
 >
   Heading level six
@@ -38,11 +38,11 @@ exports[`Heading renders the UI snapshot correctly 4`] = `
 
 exports[`Heading renders the UI snapshot correctly 5`] = `
 <h1
-  className="chakra-heading css-0"
+  className="chakra-heading css-1xdhyk6"
   id="withLink"
 >
   <a
-    className="css-0"
+    className="css-1xdhyk6"
     href="fake-url"
     id="withLink-link"
     rel={null}
@@ -55,7 +55,7 @@ exports[`Heading renders the UI snapshot correctly 5`] = `
 
 exports[`Heading renders the UI snapshot correctly 6`] = `
 <h1
-  className="chakra-heading css-0"
+  className="chakra-heading css-1xdhyk6"
   id="withCustomLink"
 >
   Part of the heading text is
@@ -69,3 +69,22 @@ exports[`Heading renders the UI snapshot correctly 6`] = `
   </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>
+`;