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

package/src/components/Form/Form.tsx

@@ -0,0 +1,124 @@
+import { chakra } from "@chakra-ui/react";
+import * as React from "react";
+
+import SimpleGrid, { GridGaps } from "../Grid/SimpleGrid";
+
+interface FormBaseProps {
+  /** className to be applied to FormRow, FormField, and Form */
+  className?: string;
+  /** Optional spacing size; if omitted, the default `large` (2rem / 32px)
+   * spacing will be used; ```IMPORTANT: for general form layout, this prop
+   * should not be used``` */
+  gap?: GridGaps;
+  /** ID that other components can cross reference (internal use) */
+  id: string;
+}
+
+export interface FormChildProps extends Partial<FormBaseProps> {}
+
+export interface FormProps extends FormBaseProps {
+  /** Optional form `action` attribute */
+  action?: string;
+  /** Optional form `method` attribute */
+  method?: "get" | "post";
+  /** Function to call for the `onSubmit` form event. */
+  onSubmit?: (e: React.FormEvent<HTMLFormElement>) => void;
+}
+
+/** FormRow child-component */
+export const FormRow = chakra(
+  (props: React.PropsWithChildren<FormChildProps>) => {
+    const { children, className, gap, id, ...rest } = props;
+    const count = React.Children.count(children);
+    const alteredChildren = React.Children.map(
+      children as JSX.Element,
+      (child: React.ReactElement, i) => {
+        if (!child) return null;
+        if (child.type === FormField || child.props.mdxType === "FormField") {
+          return React.cloneElement(child, { id: `${id}-grandchild${i}` });
+        }
+        console.warn(
+          "NYPL Reservoir FormRow: Children must be `FormField` components."
+        );
+        return null;
+      }
+    );
+    return (
+      <SimpleGrid
+        columns={count}
+        className={className}
+        gap={gap}
+        id={id}
+        {...rest}
+      >
+        {alteredChildren}
+      </SimpleGrid>
+    );
+  }
+);
+
+/** FormField child-component */
+export const FormField = chakra(
+  (props: React.PropsWithChildren<FormChildProps>) => {
+    const { children, className, gap, id, ...rest } = props;
+    return (
+      <SimpleGrid columns={1} className={className} gap={gap} id={id} {...rest}>
+        {children}
+      </SimpleGrid>
+    );
+  }
+);
+
+/** Main Form component */
+export const Form = chakra(
+  (props: React.PropsWithChildren<FormProps>) => {
+    const {
+      action,
+      children,
+      className,
+      gap = "grid.l",
+      id,
+      method,
+      onSubmit,
+      ...rest
+    } = props;
+
+    if (!id) {
+      console.warn(
+        "NYPL Reservoir Form: This component's required `id` prop was not passed."
+      );
+    }
+
+    const attributes: Partial<FormProps> = {};
+    action && (attributes["action"] = action);
+
+    method &&
+      (method === "get" || method === "post") &&
+      (attributes["method"] = method);
+
+    const alteredChildren = React.Children.map(
+      children as JSX.Element,
+      (child: React.ReactElement, i) => {
+        return React.cloneElement(child, { gap, id: `${id}-child${i}` });
+      }
+    );
+
+    return (
+      <form
+        aria-label="form"
+        className={className}
+        id={id}
+        onSubmit={onSubmit}
+        {...attributes}
+        {...rest}
+      >
+        <SimpleGrid columns={1} gap={gap} id={`${id}-parent`}>
+          {alteredChildren}
+        </SimpleGrid>
+      </form>
+    );
+  },
+  { shouldForwardProp: () => true }
+);
+
+export default Form;

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

@@ -0,0 +1,115 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Form Snapshot Renders the UI snapshot correctly 1`] = `
+<form
+  aria-label="form"
+  className="css-0"
+  id="snapshot-form"
+>
+  <div
+    className="css-fadkce"
+    id="snapshot-form-parent"
+  >
+    <div
+      className="css-dofnwd"
+      id="snapshot-form-child0"
+    >
+      <div
+        className="css-7ajbp2"
+        id="snapshot-form-child0-grandchild0"
+      >
+        Form Field 1
+      </div>
+      <div
+        className="css-7ajbp2"
+        id="snapshot-form-child0-grandchild1"
+      >
+        Form Field 2
+      </div>
+      <div
+        className="css-7ajbp2"
+        id="snapshot-form-child0-grandchild2"
+      >
+        Form Field 3
+      </div>
+    </div>
+  </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/SimpleGrid.stories.mdx

@@ -0,0 +1,336 @@
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import SimpleGrid from "./SimpleGrid";
+import Card, { CardHeading, CardContent, CardActions } from "../Card/Card";
+import Icon from "../Icons/Icon";
+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={{
+    className: { control: false },
+    columns: {
+      control: { min: 2, type: "number" },
+    },
+    gap: {
+      control: { type: "select" },
+      table: { defaultValue: { summary: "grid.l" } },
+      options: [
+        "grid.xxs",
+        "grid.xs",
+        "grid.s",
+        "grid.m",
+        "grid.l",
+        "grid.xl",
+        "grid.xxl",
+      ],
+    },
+    id: { control: false },
+  }}
+/>
+
+# SimpleGrid
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.25.1`   |
+| Latest            | `0.28.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 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
+    name="SimpleGrid with Controls"
+    args={{
+      className: undefined,
+      columns: undefined,
+      gap: "grid.l",
+      id: "simpleGrid-id",
+    }}
+  >
+    {(args) => (
+      <SimpleGrid {...args}>
+        <Card
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: "twoByOne",
+            src: "https://placeimg.com/400/220/animals",
+          }}
+        >
+          <CardHeading level="three">Card Heading</CardHeading>
+          <CardContent>
+            Vestibulum id ligula porta felis euismod semper. Nulla vitae elit
+            libero, a pharetra augue.
+          </CardContent>
+        </Card>
+        <Card
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: "twoByOne",
+            src: "https://placeimg.com/400/220/animals",
+          }}
+        >
+          <CardHeading level="three">Card Heading</CardHeading>
+          <CardContent>
+            Vestibulum id ligula porta felis euismod semper. Nulla vitae elit
+            libero, a pharetra augue.
+          </CardContent>
+        </Card>
+        <Card
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: "twoByOne",
+            src: "https://placeimg.com/400/240/animals",
+          }}
+        >
+          <CardHeading level="three">Card Heading</CardHeading>
+          <CardContent>
+            Vestibulum id ligula porta felis euismod semper. Nulla vitae elit
+            libero, a pharetra augue.
+          </CardContent>
+        </Card>
+        <Card
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: "twoByOne",
+            src: "https://placeimg.com/400/260/animals",
+          }}
+        >
+          <CardHeading level="three">Card Heading</CardHeading>
+          <CardContent>
+            Vestibulum id ligula porta felis euismod semper. Nulla vitae elit
+            libero, a pharetra augue.
+          </CardContent>
+        </Card>
+        <Card
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: "twoByOne",
+            src: "https://placeimg.com/400/320/animals",
+          }}
+        >
+          <CardHeading level="three">Card Heading</CardHeading>
+          <CardContent>
+            Vestibulum id ligula porta felis euismod semper. Nulla vitae elit
+            libero, a pharetra augue.
+          </CardContent>
+        </Card>
+        <Card
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: "twoByOne",
+            src: "https://placeimg.com/400/300/animals",
+          }}
+        >
+          <CardHeading level="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 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
+
+This example is rendering `Icon` components with the `columns` prop set to `5`.
+
+export const icons = [];
+export const iconNames = [
+  "accessibilityFull",
+  "accessibilityPartial",
+  "actionCheckCircle",
+  "actionHelpDefault",
+  "actionHelpOutline",
+  "alertNotificationImportant",
+  "actionLaunch",
+  "arrow",
+  "check",
+  "clock",
+  "close",
+  "download",
+  "errorFilled",
+  "errorOutline",
+  "fileTypeAudio",
+  "fileTypeDoc",
+  "fileTypeGenericDoc",
+  "fileTypeImage",
+  "fileTypePdf",
+  "fileTypeSpreadsheet",
+  "fileTypeVideo",
+  "headset",
+  "minus",
+  "plus",
+  "search",
+  "speakerNotes",
+  "utilityAccountFilled",
+  "utilityAccountUnfilled",
+  "utilityHamburger",
+  "utilitySearch",
+];
+for (const name in iconNames) {
+  const iname = `Example icon: ${iconNames[name]}`;
+  const iconRender = <Icon key={name} name={iconNames[name]} size="xxxlarge" />;
+  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" alt="" />
+      <Image src="https://placeimg.com/300/300/animals?x=2" alt="" />
+      <Image src="https://placeimg.com/300/300/animals?x=3" alt="" />
+      <Image src="https://placeimg.com/300/300/animals?x=4" alt="" />
+      <Image src="https://placeimg.com/300/300/animals?x=5" alt="" />
+      <Image src="https://placeimg.com/300/300/animals?x=6" alt="" />
+      <Image src="https://placeimg.com/300/300/animals?x=7" alt="" />
+      <Image src="https://placeimg.com/300/300/animals?x=8" alt="" />
+      <Image src="https://placeimg.com/300/300/animals?x=9" alt="" />
+      <Image src="https://placeimg.com/300/300/animals?x=10" alt="" />
+      <Image src="https://placeimg.com/300/300/animals?x=11" alt="" />
+      <Image src="https://placeimg.com/300/300/animals?x=12" alt="" />
+      <Image src="https://placeimg.com/300/300/animals?x=13" alt="" />
+      <Image src="https://placeimg.com/300/300/animals?x=14" alt="" />
+      <Image src="https://placeimg.com/300/300/animals?x=15" alt="" />
+      <Image src="https://placeimg.com/300/300/animals?x=16" alt="" />
+      <Image src="https://placeimg.com/300/300/animals?x=17" alt="" />
+      <Image src="https://placeimg.com/300/300/animals?x=18" alt="" />
+    </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
+        imageProps={{
+          alt: "Alt text",
+          aspectRatio: "fourByThree",
+          src: "https://placeimg.com/400/200/animals",
+        }}
+        isBordered
+        isCentered
+        layout="row"
+      >
+        <CardHeading level="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
+        imageProps={{
+          alt: "Alt text",
+          aspectRatio: "fourByThree",
+          src: "https://placeimg.com/410/210/animals",
+        }}
+        isBordered
+        isCentered
+        layout="row"
+      >
+        <CardHeading level="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
+        imageProps={{
+          alt: "Alt text",
+          aspectRatio: "fourByThree",
+          src: "https://placeimg.com/320/320/animals",
+        }}
+        isBordered
+        isCentered
+        layout="row"
+      >
+        <CardHeading level="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,79 @@
+import * as React from "react";
+import { render } from "@testing-library/react";
+import { axe } from "jest-axe";
+import renderer from "react-test-renderer";
+
+import Card, { CardHeading, CardContent } from "../Card/Card";
+import SimpleGrid from "./SimpleGrid";
+
+describe("Grid Accessibility", () => {
+  it("passes axe accessibility test with children components", async () => {
+    const { container } = render(
+      <SimpleGrid>
+        <Card
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: "twoByOne",
+            src: "https://placeimg.com/500/200/animals",
+          }}
+        >
+          <CardHeading level="two">Card Heading</CardHeading>
+          <CardContent>
+            Vestibulum id ligula porta felis euismod semper. Nulla vitae elit
+            libero, a pharetra augue.
+          </CardContent>
+        </Card>
+        <Card
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: "twoByOne",
+            src: "https://placeimg.com/400/220/animals",
+          }}
+        >
+          <CardHeading level="three">Card Heading</CardHeading>
+          <CardContent>
+            Vestibulum id ligula porta felis euismod semper. Nulla vitae elit
+            libero, a pharetra augue.
+          </CardContent>
+        </Card>
+        <Card
+          imageProps={{
+            alt: "Alt text",
+            aspectRatio: "twoByOne",
+            src: "https://placeimg.com/400/240/animals",
+          }}
+        >
+          <CardHeading level="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();
+    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", () => {
+    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,49 @@
+import { chakra, SimpleGrid as ChakraSimpleGrid } from "@chakra-ui/react";
+import * as React from "react";
+
+export type GridGaps =
+  | "grid.xxs"
+  | "grid.xs"
+  | "grid.s"
+  | "grid.m"
+  | "grid.l"
+  | "grid.xl"
+  | "grid.xxl";
+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;
+}
+
+export const SimpleGrid = chakra(
+  (props: React.PropsWithChildren<SimpleGridProps>) => {
+    const { children, columns, className, gap = "grid.l", id, ...rest } = props;
+
+    const responsiveCols = columns
+      ? { base: 1, md: columns }
+      : { base: 1, md: 2, lg: 3 };
+
+    return (
+      <ChakraSimpleGrid
+        columns={responsiveCols}
+        gap={gap}
+        id={id}
+        className={className}
+        {...rest}
+      >
+        {children}
+      </ChakraSimpleGrid>
+    );
+  },
+  { shouldForwardProp: () => true }
+);
+
+export default SimpleGrid;