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

package/src/components/Link/Link.stories.mdx

@@ -0,0 +1,249 @@
+import { VStack } from "@chakra-ui/react";
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import Link from "./Link";
+import Icon from "../Icons/Icon";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta
+  title={getCategory("Link")}
+  component={Link}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=36854%3A24387",
+    },
+    jest: ["Link.test.tsx"],
+  }}
+  argTypes={{
+    children: { table: { disable: true } },
+    key: { table: { disable: true } },
+    ref: { table: { disable: true } },
+    type: {
+      table: { defaultValue: { summary: "default" } },
+    },
+  }}
+/>
+
+# Link
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.0.4`    |
+| Latest            | `0.28.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Links With Icons](#links-with-icons)
+- [Anchor Element Rendering](#anchor-element-rendering)
+- [Link with Routers](#link-with-routers)
+
+## Overview
+
+<Description of={Link} />
+
+## Component Props
+
+<Canvas withToolbar>
+  <Story
+    name="Link with Controls"
+    args={{
+      className: "custom-class",
+      href: "https://nypl.org",
+      id: "nypl-link",
+      type: "action",
+    }}
+  >
+    {(args) => <Link {...args}>Link</Link>}
+  </Story>
+</Canvas>
+
+<ArgsTable story="Link with Controls" />
+
+## Accessibility
+
+The `Link` component should be used for navigation. If an `onClick` user
+interface action is required, a `Button` component should be used instead. The
+`Link` component renders an `<a>` element with the `href` attribute.
+
+Resources:
+
+- [W3C WAI Link Examples](https://www.w3.org/TR/wai-aria-practices-1.1/examples/link/link.html)
+- [Yale Usability & Web Accessibility Links](https://usability.yale.edu/web-accessibility/articles/links)
+
+## Links With Icons
+
+To render an `Icon` as part of the link, make sure that the `Link` component
+wraps the `Icon`. Use `type="action"` to apply appropriate styling to
+links with icons. Icons can be rendered to the left or right of the link text.
+
+<Canvas>
+  <Story name="With Icons">
+    <VStack spacing="xs" align="flex-start">
+      <Link type="action" href="#passed-in-link">
+        <Icon name="headset" align="left" size="small" />
+        Headset Link
+      </Link>
+      <Link type="action" href="#passed-in-link">
+        <Icon name="clock" align="left" size="small" />
+        Clock Link
+      </Link>
+      <Link type="action" href="#passed-in-link">
+        <Icon name="check" align="left" size="small" />
+        Check Link
+      </Link>
+      <Link type="action" href="#passed-in-link-right">
+        Check Link Right
+        <Icon name="check" align="right" size="small" />
+      </Link>
+    </VStack>
+  </Story>
+</Canvas>
+
+## Anchor Element Rendering
+
+`Link` can wrap an existing `<a>` element (and `Icon` component) or it
+can use the `href` prop to generate an `<a>` element.
+
+```jsx
+// Existing anchor element
+<Link type="action">
+  <a href="#existing-anchor-tag">link</a>
+</Link>
+
+// Also works with an icon component. Make sure to wrap the icon and anchor
+// in a single element for this pattern.
+<Link type="action">
+  <>
+    <Icon name="check" align="left" size="small" />
+    <a href="#existing-anchor-tag">check link</a>
+  </>
+</Link>
+
+// Otherwise, the `href` prop will generate an `<a>` tag.
+<Link type="action" href="#passed-in-link">
+  link
+</Link>
+```
+
+<Canvas>
+  <Story name="Anchor Element Rendering">
+    <>
+      This is a{" "}
+      <Link type="action">
+        <a href="#existing-anchor-tag">link</a>
+      </Link>{" "}
+      with the &lt;a&gt; element as a child of the `Link` component. This is a{" "}
+      <Link type="action" href="#passed-in-link">
+        link
+      </Link>{" "}
+      where the `Link` component uses the `href` prop and has a string-only
+      child. Finally, this is a{" "}
+      <Link type="action">
+        <>
+          <Icon name="check" align="left" size="small" />
+          <a href="#existing-anchor-tag">link</a>
+        </>
+      </Link>{" "}
+      with a check icon.
+    </>
+  </Story>
+</Canvas>
+
+## Link with Routers
+
+### React Router
+
+The Design System's `Link` component should wrap around `react-router`'s own
+`Link` component. To avoid name conflicts, rename either the Design System's
+or `react-router`'s `Link` component. Any of the following patterns are valid.
+
+```jsx
+// In this first example, React Router's `Link` component
+// is renamed as `ReactRouterLink`.
+import {
+  BrowserRouter as Router,
+  Link as ReactRouterLink,
+} from "react-router-dom";
+import { Link } from "@nypl/design-system-react-components";
+
+<Link type="action">
+  <ReactRouterLink to="#">Next Page</ReactRouterLink>
+</Link>;
+
+// In this second example, React Router's `Link` component
+// is not renamed but the DS's `Link` component is renamed
+// to `DSLink`.
+import { BrowserRouter, Link } from "react-router-dom";
+import { Link as DSLink } from "@nypl/design-system-react-components";
+
+<DSLink type="action">
+  <Link to="#">Next Page</Link>
+</DSLink>;
+
+// In this third example, React Router's `Link` component
+// is not renamed and the DS's `Link` component is
+// imported and rendered as `DS.Link`.
+import { BrowserRouter, Link } from "react-router-dom";
+import DS from "@nypl/design-system-react-components";
+
+<DS.Link type="action">
+  <Link to="#">Next Page</Link>
+</DS.Link>;
+```
+
+### NextJS
+
+NextJS's `Link` component should wrap the Design System's `Link` component.
+The `href` and `passHref` props MUST be passed into NextJS' `Link` component.
+These props, along with an implicit `ref` from NextJS and the Design System's
+`Link` component `forwardRef` implementation, handle correctly routing between
+pages in a NextJS app.
+
+```jsx
+import { Link } from "@nypl/design-system-react-components";
+
+/**
+ * This is just an example wrapper that works similarly to NextJS' `Link`
+ * component. In real life, NextJS's `Link` component will pass down the
+ * `href` and `passHref` props and a `ref` to make routing functional.
+ */
+export const NextJsLink = (props: HTMLAnchorElement) =>
+  React.cloneElement(
+    props.children,
+    { ...props },
+    props.children.props.children
+  );
+
+// Note that NextJS' `href` and `passHref` props are required.
+<NextJsLink href="#" passHref>
+  <Link type="action">Next Page</Link>
+</NextJsLink>;
+```
+
+export const NextJsLink = (props) =>
+  React.cloneElement(
+    props.children,
+    { href: props.href },
+    props.children.props.children
+  );
+
+<Canvas>
+  <DSProvider>
+    <NextJsLink href="#" passHref>
+      <Link type="action">Next Page</Link>
+    </NextJsLink>
+  </DSProvider>
+</Canvas>

package/src/components/Link/Link.test.tsx

@@ -0,0 +1,224 @@
+import { render, screen } from "@testing-library/react";
+import { axe } from "jest-axe";
+import * as React from "react";
+import renderer from "react-test-renderer";
+
+import Link from "./Link";
+import Icon from "../Icons/Icon";
+
+describe("Link Accessibility", () => {
+  it("passes axe accessibility test for children component", async () => {
+    const { container } = render(
+      <Link>
+        <a href="#test">Test</a>
+      </Link>
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+
+  it("passes axe accessibility test for href prop", async () => {
+    const { container } = render(<Link href="#test">Test</Link>);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("Link", () => {
+  it("Can pass in an icon and text as children and url as prop", () => {
+    const utils = render(
+      <Link href="#passed-in-link" type="action">
+        <Icon
+          className="more-link"
+          name="download"
+          align="left"
+          iconRotation="rotate0"
+        />
+        Download
+      </Link>
+    );
+    expect(screen.getByRole("link")).toBeInTheDocument();
+    expect(utils.container.querySelector(".more-link")).toBeInTheDocument();
+  });
+
+  it("Can pass a link with <a> tag", () => {
+    render(
+      <Link>
+        <a href="#test">Test</a>
+      </Link>
+    );
+    expect(screen.getByRole("link")).toBeInTheDocument();
+  });
+
+  it("Can pass a link with <a> tag and an icon", () => {
+    const utils = render(
+      <Link type="action">
+        <a href="#test2">
+          <Icon
+            className="more-link"
+            name="download"
+            align="left"
+            iconRotation="rotate0"
+          />
+          Test
+        </a>
+      </Link>
+    );
+    expect(screen.getByRole("link")).toBeInTheDocument();
+    expect(utils.container.querySelector(".more-link")).toBeInTheDocument();
+  });
+
+  it("Generated back link has icon", () => {
+    const utils = render(
+      <Link href="#passed-in-link" type="backwards">
+        content
+      </Link>
+    );
+    expect(utils.container.querySelector(".more-link")).toBeInTheDocument();
+    expect(
+      utils.container.querySelector(".more-link")?.getAttribute("class")
+    ).toContain("chakra-icon more-link");
+  });
+
+  it("Generated forwards link has icon", () => {
+    const utils = render(
+      <Link href="#passed-in-link" type="forwards">
+        content
+      </Link>
+    );
+    expect(utils.container.querySelector(".more-link")).toBeInTheDocument();
+    expect(
+      utils.container.querySelector(".more-link")?.getAttribute("class")
+    ).toContain("chakra-icon more-link");
+  });
+
+  it("Can pass in text as child and url as props", () => {
+    render(<Link href="#test">Test</Link>);
+    expect(screen.getByRole("link")).toBeInTheDocument();
+  });
+
+  it("throws an error if text is passed but no url is passed", () => {
+    expect(() => render(<Link>Test</Link>)).toThrowError(
+      "`Link` needs the `href` prop."
+    );
+  });
+
+  it("throws an error if more than one child element is passed", () => {
+    expect(() =>
+      render(
+        <Link>
+          <Icon name="download" align="left" iconRotation="rotate0" />
+          <a href="#test">Test</a>
+        </Link>
+      )
+    ).toThrowError("Please pass only one child into `Link`.");
+  });
+
+  it("renders the UI snapshot correctly", () => {
+    const standard = renderer
+      .create(
+        <Link href="#passed-in-link" id="standard-link" type="action">
+          Standard
+        </Link>
+      )
+      .toJSON();
+    const typeForwards = renderer
+      .create(
+        <Link href="#passed-in-link" id="forwards-link" type="forwards">
+          Forwards
+        </Link>
+      )
+      .toJSON();
+    const typeBackwards = renderer
+      .create(
+        <Link href="#passed-in-link" id="backwards-link" type="backwards">
+          Backwards
+        </Link>
+      )
+      .toJSON();
+    const typeExternal = renderer
+      .create(
+        <Link href="#passed-in-link" id="external-link" type="external">
+          External
+        </Link>
+      )
+      .toJSON();
+    const typeButton = renderer
+      .create(
+        <Link href="#passed-in-link" id="button-link" type="button">
+          Button
+        </Link>
+      )
+      .toJSON();
+    const withIconChild = renderer
+      .create(
+        <Link href="#passed-in-link" id="icon-link" type="action">
+          <Icon
+            align="left"
+            className="more-link"
+            iconRotation="rotate0"
+            id="link-icon"
+            name="download"
+          />
+          Download
+        </Link>
+      )
+      .toJSON();
+    const withAchorChild = renderer
+      .create(
+        <Link id="anchor-link" type="action">
+          <a href="#existing-anchor-tag">check link</a>
+        </Link>
+      )
+      .toJSON();
+    const withAchorChildAndIcon = renderer
+      .create(
+        <Link id="anchor-icon-link" type="action">
+          <>
+            <Icon align="left" id="link-icon" name="check" size="small" />
+            <a href="#existing-anchor-tag">check link</a>
+          </>
+        </Link>
+      )
+      .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <Link
+          href="#passed-in-link"
+          id="chakra"
+          p="20px"
+          color="ui.error.primary"
+        >
+          Standard
+        </Link>
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(
+        <Link href="#passed-in-link" id="props" data-testid="props">
+          Standard
+        </Link>
+      )
+      .toJSON();
+
+    expect(standard).toMatchSnapshot();
+    expect(typeForwards).toMatchSnapshot();
+    expect(typeBackwards).toMatchSnapshot();
+    expect(typeExternal).toMatchSnapshot();
+    expect(typeButton).toMatchSnapshot();
+    expect(withIconChild).toMatchSnapshot();
+    expect(withAchorChild).toMatchSnapshot();
+    expect(withAchorChildAndIcon).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
+  });
+
+  // TODO:
+  // it("Passes the ref to the input element", () => {
+  //   const ref = React.createRef<HTMLAnchorElement>();
+  //   const container = render(
+  //     <Link href="/some-link" ref={ref}>
+  //       Go to page
+  //     </Link>
+  //   );
+  //   expect(container.find("a").instance()).toEqual(ref.current);
+  // });
+});

package/src/components/Link/Link.tsx

@@ -0,0 +1,178 @@
+import { Box, chakra, useStyleConfig } from "@chakra-ui/react";
+import * as React from "react";
+
+import Icon from "../Icons/Icon";
+
+export type LinkTypes =
+  | "action"
+  | "backwards"
+  | "button"
+  | "default"
+  | "external"
+  | "forwards";
+export interface LinkProps {
+  /** Any child node passed to the component. */
+  children: React.ReactNode;
+  /** Additional class name to render in the `Link` component. */
+  className?: string;
+  /** The `href` attribute for the anchor element. */
+  href?: string;
+  /** ID used for accessibility purposes. */
+  id?: string;
+  /** Controls the link visuals: action, button, backwards, forwards, or default. */
+  type?: LinkTypes;
+}
+
+/**
+ * Renders the `Link` children components with a direction arrow icon based
+ * on the `"backwards"` or `"forwards"` `linkType` value.
+ */
+function getWithDirectionIcon(
+  children: JSX.Element,
+  type: LinkTypes,
+  linkId: string
+) {
+  let iconRotation;
+  let iconAlign;
+  let icon = null;
+
+  // An icon needs a position in order for it to be created and
+  // rendered in the link.
+  if (type === "backwards") {
+    iconRotation = "rotate90";
+    iconAlign = "left";
+  } else if (type === "forwards") {
+    iconRotation = "rotate270";
+    iconAlign = "right";
+  }
+
+  const iconId = `${linkId}-icon`;
+
+  icon = (
+    <Icon
+      align={iconAlign}
+      className="more-link"
+      iconRotation={iconRotation}
+      id={iconId}
+      name="arrow"
+      size="medium"
+    />
+  );
+
+  return (
+    <>
+      {type === "backwards" && icon}
+      {children}
+      {type === "forwards" && icon}
+    </>
+  );
+}
+
+function getExternalIcon(children: JSX.Element, linkId: string) {
+  const iconId = `${linkId}-icon`;
+  const icon = (
+    <Icon
+      align={"right"}
+      className="more-link"
+      id={iconId}
+      name="actionLaunch"
+      size="medium"
+    />
+  );
+
+  return (
+    <>
+      {children}
+      {icon}
+    </>
+  );
+}
+
+/**
+ * A component that uses an `href` prop or a child anchor element, to create
+ * an anchor element with added styling and conventions.
+ */
+export const Link = chakra(
+  React.forwardRef<HTMLAnchorElement, LinkProps>((props, ref: any) => {
+    const { children, className, href, id, type = "default", ...rest } = props;
+
+    // Merge the necessary props alongside any extra props for the
+    // anchor element.
+    const linkProps = {
+      id,
+      href,
+      ...rest,
+    };
+    // The "default" type.
+    let variant = "link";
+
+    if (typeof children === "string" && !href) {
+      throw new Error("`Link` needs the `href` prop.");
+    }
+
+    if (
+      type === "action" ||
+      type === "forwards" ||
+      type === "backwards" ||
+      type === "external"
+    ) {
+      variant = "moreLink";
+    } else if (type === "button") {
+      variant = "button";
+    }
+    const style = useStyleConfig("Link", { variant });
+    const rel = type === "external" ? "nofollow" : null;
+    const target = type === "external" ? "_blank" : null;
+    // Render with specific direction arrows if the type is
+    // Forwards or Backwards.  Or render with the launch icon
+    // if the type is External.  Otherwise, do not add an icon.
+    const newChildren =
+      ((type === "forwards" || type === "backwards") &&
+        getWithDirectionIcon(children as JSX.Element, type, id)) ||
+      (type === "external" && getExternalIcon(children as JSX.Element, id)) ||
+      children;
+
+    if (!href) {
+      // React Types error makes this fail:
+      // https://github.com/DefinitelyTyped/DefinitelyTyped/issues/32832
+      // let children = React.Children.only(children);
+      if (React.Children.count(children) > 1) {
+        throw new Error("Please pass only one child into `Link`.");
+      }
+      const childrenToClone: any = children[0] ? children[0] : children;
+      const childProps = childrenToClone.props;
+      return (
+        <Box as="span" __css={style}>
+          {React.cloneElement(
+            childrenToClone,
+            {
+              className,
+              ...linkProps,
+              ...childProps,
+              ref,
+              rel,
+              target,
+            },
+            [childrenToClone.props.children]
+          )}
+        </Box>
+      );
+    } else {
+      return (
+        <Box
+          as="a"
+          className={className}
+          ref={ref}
+          rel={rel}
+          target={target}
+          {...linkProps}
+          __css={style}
+        >
+          {newChildren}
+        </Box>
+      );
+    }
+  })
+);
+
+export default Link;