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

package/src/components/Button/Button.stories.mdx

@@ -0,0 +1,320 @@
+import { VStack } from "@chakra-ui/react";
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import Button, { ButtonElementType } from "./Button";
+import ButtonGroup from "../ButtonGroup/ButtonGroup";
+import Icon from "../Icons/Icon";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+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",
+];
+
+<Meta
+  title={getCategory("Button")}
+  component={Button}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=11477%3A2298",
+    },
+    jest: ["Button.test.tsx"],
+  }}
+  argTypes={{
+    buttonText: { description: "Only used for Storybook" },
+    buttonType: {
+      table: { defaultValue: { summary: "primary" } },
+    },
+    className: { control: false },
+    displayIcon: { description: "Only used for Storybook." },
+    displayIconLeft: {
+      description: "Move the icon left or right. Only used for Storybook.",
+    },
+    iconType: {
+      control: { type: "select" },
+      options: iconNames,
+      description: "Select the icon. Only used for Storybook.",
+    },
+    id: { control: false },
+    isDisabled: { table: { defaultValue: { summary: false } } },
+    mouseDown: { table: { defaultValue: { summary: false } } },
+    onClick: { control: false },
+  }}
+/>
+
+# Button
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.0.4`    |
+| Latest            | `1.0.2`    |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Button Groups](#button-groups)
+- [With Icons](#with-icons)
+- [Patterns](#patterns)
+- [Other Examples](#other-examples)
+
+## Overview
+
+<Description of={Button} />
+
+Update the `buttonType` in the Controls section to see the types of buttons
+that can be rendered.
+
+- `"primary"` is used for actions that move the user forward. This is the default.
+- `"secondary"` is used for actions that move the user back, such as cancellations.
+- `"callout"` is used for call to action text such as "Donate".
+- `"pill"` is used for equally weighted actions within cards and always in a set.
+- `"link"` is used for equally weighted actions in a text based list.
+- `"noBrand"` is a variant used when there is no brand and will display the
+  background color as black.
+
+When one and only one `Icon` component is passed inside a `Button` component with
+no text, it will automatically be configured to use the `"iconOnly"` type.
+
+## Component Props
+
+<Canvas withToolbar>
+  <Story
+    name="Button with Controls"
+    args={{
+      buttonText: "Button Text",
+      buttonType: "primary",
+      className: undefined,
+      displayIcon: false,
+      displayIconLeft: true,
+      iconType: "search",
+      id: "button-id",
+      isDisabled: false,
+      mouseDown: undefined,
+      onClick: undefined,
+      type: "button",
+    }}
+  >
+    {(args) => (
+      <Button
+        buttonType={args.buttonType}
+        className={args.className}
+        id={args.id}
+        isDisabled={args.isDisabled}
+        mouseDown={args.mouseDown}
+        onClick={args.onClick}
+        type={args.type}
+      >
+        {args.displayIcon && args.displayIconLeft && (
+          <Icon name={args.iconType} align="left" size="small" />
+        )}
+        {args.buttonText}
+        {args.displayIcon && !args.displayIconLeft && (
+          <Icon name={args.iconType} align="right" size="small" />
+        )}
+      </Button>
+    )}
+  </Story>
+</Canvas>
+
+<ArgsTable story="Button with Controls" />
+
+## Accessibility
+
+The Reservoir `Button` component renders an HTML `<button>` element that is
+accessible. `Button`s should be used to perform user actions or submit forms,
+never to link and go to another page. For `Button`s without text and only an
+icon, make sure to pass an `aria-label` value to the `Button`. `Button`s cannot
+have images of text.
+
+Resources:
+
+- [W3C WAI ARIA Button](https://www.w3.org/TR/wai-aria-practices-1.1/#button)
+- [W3C WAI ARIA Button Examples](https://www.w3.org/TR/wai-aria-practices-1.1/examples/button/button.html)
+- [MDN ARIA: button role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/button_role)
+- [Chakra UI Button](https://chakra-ui.com/docs/components/form/button)
+
+## Button Groups
+
+Primary and secondary buttons should be grouped like in the following example.
+The `ButtonGroup` component should be used to wrap the `Button` component.
+
+<Canvas>
+  <Story name="Button Groups">
+    <ButtonGroup>
+      <Button buttonType="secondary" id="group-1">
+        Button
+      </Button>
+      <Button id="group-2">Submit</Button>
+    </ButtonGroup>
+  </Story>
+</Canvas>
+
+## With Icons
+
+The `Icon` component collaborates great with the `Button` component. Check out
+[`src/components/Icons/Icon.tsx`](https://github.com/NYPL/nypl-design-system/blob/development/src/components/Icons/Icon.tsx)
+to see the full list of icon names that can be rendered.
+
+<Canvas>
+  <Story name="With Icon">
+    <VStack align="left" spacing="input.group.button.vstack" width="150px">
+      <Button id="icon-1">
+        <Icon name="search" align="left" size="small" />
+        Button Text
+      </Button>
+      <Button id="icon-2">
+        Button Text
+        <Icon name="search" align="right" size="small" />
+      </Button>
+    </VStack>
+  </Story>
+</Canvas>
+
+The icon can be placed to the left or the right of the button text.
+
+<Canvas>
+  <DSProvider>
+    <ButtonGroup>
+      <Button buttonType="secondary" id="icon-left">
+        <Icon name="arrow" iconRotation="rotate90" align="left" size="small" />
+        Previous
+      </Button>
+      <Button buttonType="secondary" id="icon-right">
+        Next
+        <Icon
+          name="arrow"
+          iconRotation="rotate270"
+          align="right"
+          size="small"
+        />
+      </Button>
+    </ButtonGroup>
+  </DSProvider>
+</Canvas>
+
+Text in a button is optional if an icon is rendered, but make sure that there
+is an `aria-label` passed to the `Button` component `aria-label="Previous"`.
+
+<Canvas>
+  <DSProvider>
+    <ButtonGroup>
+      <Button aria-label="Previous" buttonType="secondary" id="prev-btn">
+        <Icon name="arrow" iconRotation="rotate90" size="small" />
+      </Button>
+      <Button aria-label="Next" buttonType="secondary" id="next-btn">
+        <Icon name="arrow" iconRotation="rotate270" size="small" />
+      </Button>
+      <Button aria-label="Close" buttonType="secondary" id="close-btn">
+        <Icon name="close" size="small" />
+      </Button>
+    </ButtonGroup>
+  </DSProvider>
+</Canvas>
+
+## Patterns
+
+Buttons are blue by default but should be red when it is intended to be used as
+a call out. The "Back to Top" button must be of `buttonType="secondary"` and
+must include an up arrow icon on the right side.
+
+<Canvas>
+  <Story name="Patterns">
+    <ButtonGroup>
+      <Button buttonType="callout" id="donate-btn">
+        Donate to this library
+      </Button>
+      <Button buttonType="secondary" id="top-btn">
+        Back to Top
+        <Icon
+          name="arrow"
+          iconRotation="rotate180"
+          size="small"
+          className="right"
+          align="right"
+        />
+      </Button>
+    </ButtonGroup>
+  </Story>
+</Canvas>
+
+## Other Examples
+
+The variations modified by the `buttonType` prop:
+
+<Canvas>
+  <DSProvider>
+    <ButtonGroup>
+      <Button id="primary-btn">primary</Button>
+      <Button buttonType="secondary" id="secondary-btn">
+        secondary
+      </Button>
+      <Button buttonType="callout" id="callout-btn">
+        callout
+      </Button>
+      <Button buttonType="pill" id="pill-btn">
+        pill
+      </Button>
+      <Button buttonType="link" id="link-btn">
+        link
+      </Button>
+      <Button buttonType="noBrand" id="nobrand-btn">
+        noBrand
+      </Button>
+    </ButtonGroup>
+  </DSProvider>
+</Canvas>
+
+Modifying the `isDisabled` prop:
+
+<Canvas>
+  <DSProvider>
+    <ButtonGroup>
+      <Button id="enabled-btn" isDisabled={false}>
+        Enabled
+      </Button>
+      <Button id="disabled-btn" isDisabled>
+        isDisabled
+      </Button>
+    </ButtonGroup>
+  </DSProvider>
+</Canvas>

package/src/components/Button/Button.test.tsx

@@ -0,0 +1,184 @@
+import * as React from "react";
+import {
+  render,
+  RenderResult,
+  screen,
+  fireEvent,
+} from "@testing-library/react";
+import { axe } from "jest-axe";
+import userEvent from "@testing-library/user-event";
+import renderer from "react-test-renderer";
+
+import Button from "./Button";
+import Icon from "../Icons/Icon";
+
+describe("Button Accessibility", () => {
+  it("passes axe accessibility test", async () => {
+    const onClick = jest.fn();
+    const { container } = render(
+      <Button id="button" onClick={onClick}>
+        Submit
+      </Button>
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("Button", () => {
+  let onClick: jest.MockedFunction<() => void>;
+  let utils: RenderResult;
+
+  beforeEach(() => {
+    onClick = jest.fn();
+    utils = render(
+      <Button id="button" onClick={onClick}>
+        Submit
+      </Button>
+    );
+  });
+
+  it("calls the onClick", () => {
+    expect(onClick).toHaveBeenCalledTimes(0);
+    userEvent.click(screen.getByText("Submit"));
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("optionally renders a component", () => {
+    expect(screen.getByText("Submit")).toBeInTheDocument();
+  });
+
+  it("optionally calls the onClick on mouseDown instead of on click", () => {
+    expect(onClick).toHaveBeenCalledTimes(0);
+    utils.rerender(
+      <Button id="button5" mouseDown={true}>
+        Submit
+      </Button>
+    );
+    userEvent.click(screen.getByText("Submit"));
+    expect(onClick).toHaveBeenCalledTimes(0);
+    fireEvent.mouseDown(screen.getByText("Submit"));
+    // TODO:
+    // expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("rendering content from its children prop", () => {
+  const onClick = jest.fn();
+  it("should render string children", () => {
+    render(
+      <Button id="button2" onClick={onClick}>
+        Submit
+      </Button>
+    );
+    expect(screen.getByText("Submit")).toBeInTheDocument();
+  });
+
+  it("should render element children", () => {
+    const { container } = render(
+      <Button id="button3" onClick={onClick}>
+        <em>I'm an em element</em>
+      </Button>
+    );
+    expect(screen.getByText(/an em element/i)).toBeInTheDocument();
+    expect(container.querySelector("em")).toBeInTheDocument();
+  });
+});
+
+describe("padding for icon only button", () => {
+  it("button has proper child svg for the icon only button", () => {
+    const onClick = jest.fn();
+    const { container } = render(
+      <Button id="button" onClick={onClick} type="button">
+        <Icon align="left" name="check" size="small" />
+      </Button>
+    );
+    expect(container.querySelector("button svg")).toBeInTheDocument();
+  });
+
+  it("logs a warning when there is no `id` passed", () => {
+    const warn = jest.spyOn(console, "warn");
+    // @ts-ignore: Typescript complains when a required prop is not passed, but
+    // here we don't want to pass the required prop to make sure the warning appears.
+    render(<Button>Submit</Button>);
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir Button: This component's required `id` prop was not passed."
+    );
+  });
+});
+
+describe("Button Snapshot", () => {
+  it("Renders the UI snapshot correctly", () => {
+    const primary = renderer
+      .create(
+        <Button id="button" onClick={jest.fn()}>
+          Primary
+        </Button>
+      )
+      .toJSON();
+    const disabled = renderer
+      .create(
+        <Button id="button" onClick={jest.fn()} isDisabled>
+          Disabled
+        </Button>
+      )
+      .toJSON();
+    const secondary = renderer
+      .create(
+        <Button id="button" onClick={jest.fn()} buttonType="secondary">
+          Seconday
+        </Button>
+      )
+      .toJSON();
+    const callout = renderer
+      .create(
+        <Button id="button" onClick={jest.fn()} buttonType="callout">
+          Callout
+        </Button>
+      )
+      .toJSON();
+    const pill = renderer
+      .create(
+        <Button id="button" onClick={jest.fn()} buttonType="pill">
+          Pill
+        </Button>
+      )
+      .toJSON();
+    const link = renderer
+      .create(
+        <Button id="button" onClick={jest.fn()} buttonType="link">
+          Link
+        </Button>
+      )
+      .toJSON();
+    const noBrand = renderer
+      .create(
+        <Button id="button" onClick={jest.fn()} buttonType="noBrand">
+          NoBrand
+        </Button>
+      )
+      .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <Button
+          id="button"
+          onClick={jest.fn()}
+          p="s"
+          color="ui.error.primary"
+        />
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(<Button id="button" onClick={jest.fn()} data-testid="testid" />)
+      .toJSON();
+
+    expect(primary).toMatchSnapshot();
+    expect(disabled).toMatchSnapshot();
+    expect(secondary).toMatchSnapshot();
+    expect(callout).toMatchSnapshot();
+    expect(pill).toMatchSnapshot();
+    expect(link).toMatchSnapshot();
+    expect(noBrand).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
+  });
+});

package/src/components/Button/Button.tsx

@@ -0,0 +1,95 @@
+import {
+  Button as ChakraButton,
+  chakra,
+  useStyleConfig,
+} from "@chakra-ui/react";
+import * as React from "react";
+
+import Icon from "../Icons/Icon";
+
+export type ButtonElementType = "submit" | "button" | "reset";
+export type ButtonTypes =
+  | "primary"
+  | "secondary"
+  | "callout"
+  | "pill"
+  | "link"
+  | "noBrand";
+
+interface ButtonProps {
+  /** The button variation to render based on the `ButtonTypes` type.*/
+  buttonType?: ButtonTypes;
+  /** Additional className to use. */
+  className?: string;
+  /** ID that other components can cross reference for accessibility purposes. */
+  id: string;
+  /** Adds 'disabled' property to the button. */
+  isDisabled?: boolean;
+  /** Trigger the Button's action through the `mouseDown` event handler instead
+   * of `onClick`. `false` by default. */
+  mouseDown?: boolean;
+  /** The action to perform on the `<button>`'s onClick function. */
+  onClick?: (event: React.MouseEvent | React.KeyboardEvent) => void;
+  /** The HTML button type attribute. */
+  type?: ButtonElementType;
+}
+
+/**
+ * Renders a simple `button` element with custom variant styles.
+ */
+export const Button = chakra((props: React.PropsWithChildren<ButtonProps>) => {
+  const {
+    buttonType = "primary",
+    children,
+    className = "",
+    id,
+    isDisabled = false,
+    mouseDown = false,
+    onClick,
+    type = "button",
+    ...rest
+  } = props;
+  const btnCallback = mouseDown ? { onMouseDown: onClick } : { onClick };
+  let childCount = 0;
+  let hasIcon = false;
+  let variant: string | ButtonTypes = buttonType;
+  let styles = {};
+
+  if (!id) {
+    console.warn(
+      "NYPL Reservoir Button: This component's required `id` prop was not passed."
+    );
+  }
+
+  React.Children.map(children as JSX.Element, (child: React.ReactElement) => {
+    childCount++;
+    if (child !== undefined && child !== null) {
+      if (child.type === Icon || child?.props?.mdxType === "Icon") {
+        hasIcon = true;
+      }
+    }
+  });
+
+  if (childCount === 1 && hasIcon) {
+    variant = "iconOnly";
+  }
+
+  styles = useStyleConfig("Button", { variant });
+
+  return (
+    <ChakraButton
+      id={id}
+      data-testid="button"
+      className={className}
+      type={type}
+      isDisabled={isDisabled}
+      {...btnCallback}
+      __css={styles}
+      {...rest}
+    >
+      {children}
+    </ChakraButton>
+  );
+});
+
+export default Button;

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

@@ -0,0 +1,106 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Button Snapshot Renders the UI snapshot correctly 1`] = `
+<button
+  className="chakra-button css-1xdhyk6"
+  data-testid="button"
+  id="button"
+  onClick={[MockFunction]}
+  type="button"
+>
+  Primary
+</button>
+`;
+
+exports[`Button Snapshot Renders the UI snapshot correctly 2`] = `
+<button
+  className="chakra-button css-1xdhyk6"
+  data-testid="button"
+  disabled={true}
+  id="button"
+  onClick={[MockFunction]}
+  type="button"
+>
+  Disabled
+</button>
+`;
+
+exports[`Button Snapshot Renders the UI snapshot correctly 3`] = `
+<button
+  className="chakra-button css-1xdhyk6"
+  data-testid="button"
+  id="button"
+  onClick={[MockFunction]}
+  type="button"
+>
+  Seconday
+</button>
+`;
+
+exports[`Button Snapshot Renders the UI snapshot correctly 4`] = `
+<button
+  className="chakra-button css-1xdhyk6"
+  data-testid="button"
+  id="button"
+  onClick={[MockFunction]}
+  type="button"
+>
+  Callout
+</button>
+`;
+
+exports[`Button Snapshot Renders the UI snapshot correctly 5`] = `
+<button
+  className="chakra-button css-1xdhyk6"
+  data-testid="button"
+  id="button"
+  onClick={[MockFunction]}
+  type="button"
+>
+  Pill
+</button>
+`;
+
+exports[`Button Snapshot Renders the UI snapshot correctly 6`] = `
+<button
+  className="chakra-button css-1xdhyk6"
+  data-testid="button"
+  id="button"
+  onClick={[MockFunction]}
+  type="button"
+>
+  Link
+</button>
+`;
+
+exports[`Button Snapshot Renders the UI snapshot correctly 7`] = `
+<button
+  className="chakra-button css-1xdhyk6"
+  data-testid="button"
+  id="button"
+  onClick={[MockFunction]}
+  type="button"
+>
+  NoBrand
+</button>
+`;
+
+exports[`Button Snapshot Renders the UI snapshot correctly 8`] = `
+<button
+  className="chakra-button css-1t0bvx9"
+  data-testid="button"
+  id="button"
+  onClick={[MockFunction]}
+  type="button"
+/>
+`;
+
+exports[`Button Snapshot Renders the UI snapshot correctly 9`] = `
+<button
+  className="chakra-button css-1xdhyk6"
+  data-testid="testid"
+  id="button"
+  onClick={[MockFunction]}
+  type="button"
+/>
+`;