@nypl/design-system-react-components 0.25.7 → 0.25.10

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

@@ -1,23 +1,26 @@
+import { VStack } from "@chakra-ui/react";
 import {
-  Meta,
-  Story,
-  Canvas,
   ArgsTable,
+  Canvas,
   Description,
-} from "@storybook/addon-docs/blocks";
-import { withDesign } from "storybook-addon-designs";
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
 import {
   BrowserRouter as Router,
   Link as ReactRouterLink,
 } from "react-router-dom";
-import { VStack } from "@chakra-ui/react";
+import { withDesign } from "storybook-addon-designs";
 
 import Link from "./Link";
 import { LinkTypes } from "./LinkTypes";
 import Icon from "../Icons/Icon";
-import { IconAlign, IconSizes } from "../Icons/IconTypes";
+import { IconAlign, IconNames, IconSizes } from "../Icons/IconTypes";
 import { getCategory } from "../../utils/componentCategories";
 import DSProvider from "../../theme/provider";
+import { getStorybookEnumValues } from "../../utils/utils";
+
+export const enumValues = getStorybookEnumValues(LinkTypes, "LinkTypes");
 
 <Meta
   title={getCategory("Link")}
@@ -26,19 +29,20 @@ import DSProvider from "../../theme/provider";
   parameters={{
     design: {
       type: "figma",
-      url:
-        "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=36854%3A24387",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=36854%3A24387",
     },
     jest: ["Link.test.tsx"],
   }}
   argTypes={{
-    attributes: { table: { disable: true } },
+    additionalStyles: { control: false },
+    attributes: { control: false },
     children: { table: { disable: true } },
+    key: { table: { disable: true } },
+    ref: { table: { disable: true } },
     type: {
-      control: {
-        type: "select",
-      },
-      options: LinkTypes,
+      control: { type: "select" },
+      table: { defaultValue: { summary: "LinkTypes.Default" } },
+      options: enumValues.options,
     },
   }}
 />
@@ -48,29 +52,34 @@ import DSProvider from "../../theme/provider";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.0.4`    |
-| Latest            | `0.25.1`   |
+| Latest            | `0.25.9`   |
 
 <Description of={Link} />
 
 <Canvas withToolbar>
   <Story
-    name="Basic"
+    name="Link with Controls"
     args={{
-      id: "nypl-link",
-      type: LinkTypes.Action,
-      href: "https://nypl.org",
-      className: "custom-class",
+      additionalStyles: undefined,
       attributes: {
         rel: "nofollow",
         onClick: (e) => e.preventDefault(),
       },
+      className: "custom-class",
+      href: "https://nypl.org",
+      id: "nypl-link",
+      type: "LinkTypes.Action",
     }}
   >
-    {(args) => <Link {...args}>Link</Link>}
+    {(args) => (
+      <Link {...args} type={enumValues.getValue(args.type)}>
+        Link
+      </Link>
+    )}
   </Story>
 </Canvas>
 
-<ArgsTable story="Basic" />
+<ArgsTable story="Link with Controls" />
 
 ## Links With Icons
 
@@ -90,12 +99,20 @@ links with icons. Icons can be rendered to the left or right of the link text.
         Clock Link
       </Link>
       <Link type={LinkTypes.Action} href="#passed-in-link">
-        <Icon name="check" align={IconAlign.Left} size={IconSizes.Small} />
+        <Icon
+          name={IconNames.Check}
+          align={IconAlign.Left}
+          size={IconSizes.Small}
+        />
         Check Link
       </Link>
       <Link type={LinkTypes.Action} href="#passed-in-link-right">
         Check Link Right
-        <Icon name="check" align={IconAlign.Right} size={IconSizes.Small} />
+        <Icon
+          name={IconNames.Check}
+          align={IconAlign.Right}
+          size={IconSizes.Small}
+        />
       </Link>
     </VStack>
   </Story>
@@ -103,8 +120,29 @@ links with icons. Icons can be rendered to the left or right of the link text.
 
 ## Anchor Element Rendering
 
-`Link` can wrap an existing `<a>` tag or it can use the `href` prop to generate
-an `<a>` tag.
+`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={LinkTypes.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={LinkTypes.Action}>
+  <>
+    <Icon name={IconNames.Check} align={IconAlign.Left} size={IconSizes.Small} />
+    <a href="#existing-anchor-tag">check link</a>
+  </>
+</Link>
+
+// Otherwise, the `href` prop will generate an `<a>` tag.
+<Link type={LinkTypes.Action} href="#passed-in-link">
+  link
+</Link>
+```
 
 <Canvas>
   <Story name="Anchor Element Rendering">
@@ -113,11 +151,23 @@ an `<a>` tag.
       <Link type={LinkTypes.Action}>
         <a href="#existing-anchor-tag">link</a>
       </Link>{" "}
-      with the &lt;a&gt; tag as a child of the Link component. And this is a{" "}
+      with the &lt;a&gt; element as a child of the `Link` component. This is a{" "}
       <Link type={LinkTypes.Action} href="#passed-in-link">
         link
       </Link>{" "}
-      where the Link component uses the `href` prop and has a string-only child.
+      where the `Link` component uses the `href` prop and has a string-only
+      child. Finally, this is a{" "}
+      <Link type={LinkTypes.Action}>
+        <>
+          <Icon
+            name={IconNames.Check}
+            align={IconAlign.Left}
+            size={IconSizes.Small}
+          />
+          <a href="#existing-anchor-tag">link</a>
+        </>
+      </Link>{" "}
+      with a check icon.
     </>
   </Story>
 </Canvas>
@@ -145,9 +195,11 @@ an `<a>` tag.
 
 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.
+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,
@@ -158,8 +210,9 @@ import { Link, LinkTypes } from "@nypl/design-system-react-components";
   <ReactRouterLink to="#">Next Page</ReactRouterLink>
 </Link>;
 
-// or
-
+// 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,
@@ -170,8 +223,9 @@ import {
   <Link to="#">Next Page</Link>
 </DSLink>;
 
-// or
-
+// 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";
 
@@ -201,34 +255,30 @@ pages in a NextJS app.
 ```jsx
 import { Link, LinkTypes } from "@nypl/design-system-react-components";
 
-/* This is just an example wrapper that works similarly to NextJS' `Link`
+/**
+ * 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) => (
-  <div>
-    {React.cloneElement(
-      props.children,
-      { ...props },
-      props.children.props.children
-    )}
-  </div>
-);
-
+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={LinkTypes.Action}>Next Page</Link>
 </NextJsLink>;
 ```
 
-export const NextJsLink = (props) => (
-  <div>
-    {React.cloneElement(
-      props.children,
-      { ...props },
-      props.children.props.children
-    )}
-  </div>
-);
+export const NextJsLink = (props) =>
+  React.cloneElement(
+    props.children,
+    { ...props },
+    props.children.props.children
+  );
 
 <Canvas>
   <DSProvider>

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

@@ -1,15 +1,21 @@
-import * as React from "react";
 import { render, screen } from "@testing-library/react";
 import { axe } from "jest-axe";
-
-import Link from "./Link";
-import { LinkTypes } from "./LinkTypes";
+import * as React from "react";
 import {
   BrowserRouter as Router,
   Link as ReactRouterLink,
 } from "react-router-dom";
+import renderer from "react-test-renderer";
+
+import Link from "./Link";
+import { LinkTypes } from "./LinkTypes";
 import Icon from "../Icons/Icon";
-import { IconRotationTypes, IconNames, IconAlign } from "../Icons/IconTypes";
+import {
+  IconAlign,
+  IconNames,
+  IconRotationTypes,
+  IconSizes,
+} from "../Icons/IconTypes";
 
 describe("Link Accessibility", () => {
   it("passes axe accessibility test for children component", async () => {
@@ -120,11 +126,11 @@ describe("Link", () => {
 
   it("throws an error if text is passed but no url is passed", () => {
     expect(() => render(<Link>Test</Link>)).toThrowError(
-      "Link needs prop 'href'"
+      "`Link` needs the `href` prop."
     );
   });
 
-  it("throws an error if more than one child is passed", () => {
+  it("throws an error if more than one child element is passed", () => {
     expect(() =>
       render(
         <Link>
@@ -139,6 +145,101 @@ describe("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={LinkTypes.Action}>
+          Standard
+        </Link>
+      )
+      .toJSON();
+    const typeForwards = renderer
+      .create(
+        <Link
+          href="#passed-in-link"
+          id="forwards-link"
+          type={LinkTypes.Forwards}
+        >
+          Forwards
+        </Link>
+      )
+      .toJSON();
+    const typeBackwards = renderer
+      .create(
+        <Link
+          href="#passed-in-link"
+          id="backwards-link"
+          type={LinkTypes.Backwards}
+        >
+          Backwards
+        </Link>
+      )
+      .toJSON();
+    const typeExternal = renderer
+      .create(
+        <Link
+          href="#passed-in-link"
+          id="external-link"
+          type={LinkTypes.External}
+        >
+          External
+        </Link>
+      )
+      .toJSON();
+    const typeButton = renderer
+      .create(
+        <Link href="#passed-in-link" id="button-link" type={LinkTypes.Button}>
+          Button
+        </Link>
+      )
+      .toJSON();
+    const withIconChild = renderer
+      .create(
+        <Link href="#passed-in-link" id="icon-link" type={LinkTypes.Action}>
+          <Icon
+            align={IconAlign.Left}
+            className="more-link"
+            iconRotation={IconRotationTypes.Rotate0}
+            id="link-icon"
+            name={IconNames.Download}
+          />
+          Download
+        </Link>
+      )
+      .toJSON();
+    const withAchorChild = renderer
+      .create(
+        <Link id="anchor-link" type={LinkTypes.Action}>
+          <a href="#existing-anchor-tag">check link</a>
+        </Link>
+      )
+      .toJSON();
+    const withAchorChildAndIcon = renderer
+      .create(
+        <Link id="anchor-icon-link" type={LinkTypes.Action}>
+          <>
+            <Icon
+              align={IconAlign.Left}
+              id="link-icon"
+              name={IconNames.Check}
+              size={IconSizes.Small}
+            />
+            <a href="#existing-anchor-tag">check link</a>
+          </>
+        </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();
+  });
+
   // TODO:
   // it("Passes the ref to the input element", () => {
   //   const ref = React.createRef<HTMLAnchorElement>();

package/src/components/Link/Link.tsx

@@ -27,7 +27,7 @@ export interface LinkProps {
  * Renders the `Link` children components with a direction arrow icon based
  * on the `Backwards` or `Forwards` `LinkTypes` type.
  */
-function getWithDirectionIcon(children, type: LinkTypes) {
+function getWithDirectionIcon(children, type: LinkTypes, linkId) {
   let iconRotation;
   let iconAlign;
   let icon = null;
@@ -42,12 +42,15 @@ function getWithDirectionIcon(children, type: LinkTypes) {
     iconAlign = IconAlign.Right;
   }
 
+  const iconId = `${linkId}-icon`;
+
   icon = (
     <Icon
-      name={IconNames.Arrow}
       align={iconAlign}
-      iconRotation={iconRotation}
       className="more-link"
+      iconRotation={iconRotation}
+      id={iconId}
+      name={IconNames.Arrow}
     />
   );
 
@@ -60,6 +63,25 @@ function getWithDirectionIcon(children, type: LinkTypes) {
   );
 }
 
+function getExternalIcon(children, linkId) {
+  const iconId = `${linkId}-icon`;
+  const icon = (
+    <Icon
+      align={IconAlign.Right}
+      className="more-link"
+      id={iconId}
+      name={IconNames.ActionLaunch}
+    />
+  );
+
+  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.
@@ -87,25 +109,31 @@ const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
     let variant = "link";
 
     if (typeof children === "string" && !href) {
-      throw new Error("Link needs prop 'href'");
+      throw new Error("`Link` needs the `href` prop.");
     }
 
     if (
       type === LinkTypes.Action ||
       type === LinkTypes.Forwards ||
-      type === LinkTypes.Backwards
+      type === LinkTypes.Backwards ||
+      type === LinkTypes.External
     ) {
       variant = "moreLink";
     } else if (type === LinkTypes.Button) {
       variant = "button";
     }
     const style = useStyleConfig("Link", { variant });
-    // Render with specific direction arrows only if the type
-    // is Forwards or Backwards.
+    // 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 === LinkTypes.Forwards || type === LinkTypes.Backwards
-        ? getWithDirectionIcon(children, type)
-        : children;
+      ((type === LinkTypes.Forwards || type === LinkTypes.Backwards) &&
+        getWithDirectionIcon(children, type, id)) ||
+      (type === LinkTypes.External && getExternalIcon(children, id)) ||
+      children;
+
+    const rel = type === LinkTypes.External ? "nofollow" : null;
+    const target = type === LinkTypes.External ? "_blank" : null;
 
     if (!href) {
       // React Types error makes this fail:
@@ -116,15 +144,24 @@ const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
       }
       const childrenToClone: any = children[0] ? children[0] : children;
       const childProps = childrenToClone.props;
-      return React.cloneElement(
-        childrenToClone,
-        {
-          className,
-          ...linkProps,
-          ...childProps,
-          ref,
-        },
-        [childrenToClone.props.children]
+      return (
+        <Box as="span" __css={style}>
+          {React.cloneElement(
+            childrenToClone,
+            {
+              className,
+              ...linkProps,
+              ...childProps,
+              ref,
+              rel,
+              target,
+              // Useful if more styles are needed for the custom
+              // anchor element or link component.
+              style: additionalStyles,
+            },
+            [childrenToClone.props.children]
+          )}
+        </Box>
       );
     } else {
       return (
@@ -132,6 +169,8 @@ const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
           as="a"
           className={className}
           ref={ref}
+          rel={rel}
+          target={target}
           {...linkProps}
           __css={{ ...style, ...additionalStyles }}
         >

package/src/components/Link/LinkTypes.tsx

@@ -3,5 +3,6 @@ export enum LinkTypes {
   Backwards = "backwards",
   Button = "button",
   Default = "default",
+  External = "external",
   Forwards = "forwards",
 }