@nypl/design-system-react-components 1.0.0 → 1.0.3-beta

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

@@ -1,249 +0,0 @@
-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

@@ -1,224 +0,0 @@
-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

@@ -1,178 +0,0 @@
-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;