@nypl/design-system-react-components 0.25.0 → 0.25.4

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

@@ -3,18 +3,21 @@ import {
   Story,
   Canvas,
   ArgsTable,
-  Preview,
   Description,
 } from "@storybook/addon-docs/blocks";
 import { withDesign } from "storybook-addon-designs";
-import Link from "./Link";
 import {
   BrowserRouter as Router,
   Link as ReactRouterLink,
 } from "react-router-dom";
+import { VStack } from "@chakra-ui/react";
+
+import Link from "./Link";
 import { LinkTypes } from "./LinkTypes";
 import Icon from "../Icons/Icon";
+import { IconAlign, IconSizes } from "../Icons/IconTypes";
 import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
 
 <Meta
   title={getCategory("Link")}
@@ -24,18 +27,18 @@ import { getCategory } from "../../utils/componentCategories";
     design: {
       type: "figma",
       url:
-        "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=16115%3A407",
+        "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=36854%3A24387",
     },
     jest: ["Link.test.tsx"],
   }}
   argTypes={{
-    blockName: { table: { disable: true } },
-    modifiers: { table: { disable: true } },
+    attributes: { table: { disable: true } },
     children: { table: { disable: true } },
     type: {
       control: {
         type: "select",
       },
+      options: LinkTypes,
     },
   }}
 />
@@ -45,11 +48,11 @@ import { getCategory } from "../../utils/componentCategories";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.0.4`    |
-| Latest            | `0.20.2`   |
+| Latest            | `0.25.1`   |
 
 <Description of={Link} />
 
-<Preview withToolbar>
+<Canvas withToolbar>
   <Story
     name="Basic"
     args={{
@@ -65,7 +68,7 @@ import { getCategory } from "../../utils/componentCategories";
   >
     {(args) => <Link {...args}>Link</Link>}
   </Story>
-</Preview>
+</Canvas>
 
 <ArgsTable story="Basic" />
 
@@ -75,42 +78,35 @@ To render an `Icon` as part of the link, make sure that the `Link` component
 wraps the `Icon`. Use `type={LinkTypes.Action}` to apply appropriate styling to
 links with icons. Icons can be rendered to the left or right of the link text.
 
-<Preview>
+<Canvas>
   <Story name="With Icons">
-    <>
+    <VStack spacing="xs" align="flex-start">
       <Link type={LinkTypes.Action} href="#passed-in-link">
-        <Icon
-          name={"headset"}
-          modifiers={["left", "small"]}
-          decorative={true}
-        />
+        <Icon name="headset" align={IconAlign.Left} size={IconSizes.Small} />
         Headset Link
       </Link>
-      <br />
       <Link type={LinkTypes.Action} href="#passed-in-link">
-        <Icon name={"clock"} modifiers={["left", "small"]} decorative={true} />
+        <Icon name="clock" align={IconAlign.Left} size={IconSizes.Small} />
         Clock Link
       </Link>
-      <br />
       <Link type={LinkTypes.Action} href="#passed-in-link">
-        <Icon name={"check"} modifiers={["left", "small"]} decorative={true} />
+        <Icon name="check" align={IconAlign.Left} size={IconSizes.Small} />
         Check Link
       </Link>
-      <br />
       <Link type={LinkTypes.Action} href="#passed-in-link-right">
         Check Link Right
-        <Icon name={"check"} modifiers={["right", "small"]} decorative={true} />
+        <Icon name="check" align={IconAlign.Right} size={IconSizes.Small} />
       </Link>
-    </>
+    </VStack>
   </Story>
-</Preview>
+</Canvas>
 
 ## Anchor Element Rendering
 
 `Link` can wrap an existing `<a>` tag or it can use the `href` prop to generate
 an `<a>` tag.
 
-<Preview>
+<Canvas>
   <Story name="Anchor Element Rendering">
     <>
       This is a{" "}
@@ -124,11 +120,11 @@ an `<a>` tag.
       where the Link component uses the `href` prop and has a string-only child.
     </>
   </Story>
-</Preview>
+</Canvas>
 
 ## Link with Routers
 
-<Preview>
+<Canvas>
   <Story name="Link with Routers">
     <div>With React Router</div>
     <Router>
@@ -143,7 +139,7 @@ an `<a>` tag.
       <Link type={LinkTypes.Action}>Next Page</Link>
     </NextJsLink>
   </Story>
-</Preview>
+</Canvas>
 
 ### React Router
 
@@ -151,7 +147,7 @@ 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.
 
-```js
+```jsx
 import {
   BrowserRouter as Router,
   Link as ReactRouterLink,
@@ -184,13 +180,15 @@ import DS from "@nypl/design-system-react-components";
 </DS.Link>;
 ```
 
-<Preview>
-  <Router>
-    <Link type={LinkTypes.Action}>
-      <ReactRouterLink to="#">Next Page</ReactRouterLink>
-    </Link>
-  </Router>
-</Preview>
+<Canvas>
+  <DSProvider>
+    <Router>
+      <Link type={LinkTypes.Action}>
+        <ReactRouterLink to="#">Next Page</ReactRouterLink>
+      </Link>
+    </Router>
+  </DSProvider>
+</Canvas>
 
 ### NextJS
 
@@ -200,7 +198,7 @@ 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.
 
-```js
+```jsx
 import { Link, LinkTypes } from "@nypl/design-system-react-components";
 
 /* This is just an example wrapper that works similarly to NextJS' `Link`
@@ -232,8 +230,10 @@ export const NextJsLink = (props) => (
   </div>
 );
 
-<Preview>
-  <NextJsLink href="#" passHref>
-    <Link type={LinkTypes.Action}>Next Page</Link>
-  </NextJsLink>
-</Preview>
+<Canvas>
+  <DSProvider>
+    <NextJsLink href="#" passHref>
+      <Link type={LinkTypes.Action}>Next Page</Link>
+    </NextJsLink>
+  </DSProvider>
+</Canvas>

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

@@ -9,10 +9,10 @@ import {
   Link as ReactRouterLink,
 } from "react-router-dom";
 import Icon from "../Icons/Icon";
-import { IconRotationTypes, IconNames } from "../Icons/IconTypes";
+import { IconRotationTypes, IconNames, IconAlign } from "../Icons/IconTypes";
 
 describe("Link Accessibility", () => {
-  it("passes axe accessibility test", async () => {
+  it("passes axe accessibility test for children component", async () => {
     const { container } = render(
       <Link>
         <a href="#test">Test</a>
@@ -20,26 +20,28 @@ describe("Link Accessibility", () => {
     );
     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 icon, text as child and url as props", () => {
+  it("Can pass in an icon and text as children and url as prop", () => {
     const utils = render(
       <Link href="#passed-in-link" type={LinkTypes.Action}>
         <Icon
-          name={IconNames.download}
-          blockName="more-link"
-          modifiers={["left"]}
-          decorative={true}
-          iconRotation={IconRotationTypes.rotate0}
+          className="more-link"
+          name={IconNames.Download}
+          align={IconAlign.Left}
+          iconRotation={IconRotationTypes.Rotate0}
         />
         Download
       </Link>
     );
     expect(screen.getByRole("link")).toBeInTheDocument();
-    expect(
-      utils.container.querySelector(".more-link__icon")
-    ).toBeInTheDocument();
+    expect(utils.container.querySelector(".more-link")).toBeInTheDocument();
   });
 
   it("Can pass a link with <a> tag", () => {
@@ -56,20 +58,17 @@ describe("Link", () => {
       <Link type={LinkTypes.Action}>
         <a href="#test2">
           <Icon
-            name={IconNames.download}
-            blockName="more-link"
-            modifiers={["left"]}
-            decorative={true}
-            iconRotation={IconRotationTypes.rotate0}
+            className="more-link"
+            name={IconNames.Download}
+            align={IconAlign.Left}
+            iconRotation={IconRotationTypes.Rotate0}
           />
           Test
         </a>
       </Link>
     );
     expect(screen.getByRole("link")).toBeInTheDocument();
-    expect(
-      utils.container.querySelector(".more-link__icon")
-    ).toBeInTheDocument();
+    expect(utils.container.querySelector(".more-link")).toBeInTheDocument();
   });
 
   it("Generated back link has icon", () => {
@@ -78,13 +77,10 @@ describe("Link", () => {
         content
       </Link>
     );
+    expect(utils.container.querySelector(".more-link")).toBeInTheDocument();
     expect(
-      utils.container.querySelector(".more-link__icon")
-    ).toBeInTheDocument();
-    expect(utils.container.querySelector(".more-link__icon")).toHaveAttribute(
-      "class",
-      "more-link__icon more-link__icon--left more-link__icon--rotate-90 "
-    );
+      utils.container.querySelector(".more-link").getAttribute("class")
+    ).toContain("chakra-icon more-link");
   });
 
   it("Generated forwards link has icon", () => {
@@ -93,13 +89,10 @@ describe("Link", () => {
         content
       </Link>
     );
+    expect(utils.container.querySelector(".more-link")).toBeInTheDocument();
     expect(
-      utils.container.querySelector(".more-link__icon")
-    ).toBeInTheDocument();
-    expect(utils.container.querySelector(".more-link__icon")).toHaveAttribute(
-      "class",
-      "more-link__icon more-link__icon--right more-link__icon--rotate-270 "
-    );
+      utils.container.querySelector(".more-link").getAttribute("class")
+    ).toContain("chakra-icon more-link");
   });
 
   it("Can pass in text as child and url as props", () => {
@@ -113,12 +106,10 @@ describe("Link", () => {
         <Link type={LinkTypes.Action}>
           <ReactRouterLink to="#">
             <Icon
-              name={IconNames.download}
-              blockName="more-link"
-              modifiers={["left"]}
-              decorative={true}
-              iconRotation={IconRotationTypes.rotate0}
-            ></Icon>
+              name={IconNames.Download}
+              align={IconAlign.Left}
+              iconRotation={IconRotationTypes.Rotate0}
+            />
             Download
           </ReactRouterLink>
         </Link>
@@ -138,16 +129,14 @@ describe("Link", () => {
       render(
         <Link>
           <Icon
-            name={IconNames.download}
-            blockName="more-link"
-            modifiers={["left"]}
-            decorative={true}
-            iconRotation={IconRotationTypes.rotate0}
-          ></Icon>
+            name={IconNames.Download}
+            align={IconAlign.Left}
+            iconRotation={IconRotationTypes.Rotate0}
+          />
           <a href="#test">Test</a>
         </Link>
       )
-    ).toThrowError("Please pass only one child into Link");
+    ).toThrowError("Please pass only one child into `Link`.");
   });
 
   // TODO:

package/src/components/Link/Link.tsx

@@ -1,128 +1,145 @@
 import * as React from "react";
-import bem from "../../utils/bem";
+import { Box, useStyleConfig } from "@chakra-ui/react";
+
 import { LinkTypes } from "./LinkTypes";
-import Icon, { IconProps } from "../Icons/Icon";
-import { IconRotationTypes, IconNames } from "../Icons/IconTypes";
+import Icon from "../Icons/Icon";
+import { IconRotationTypes, IconNames, IconAlign } from "../Icons/IconTypes";
+import generateUUID from "../../helpers/generateUUID";
 
 export interface LinkProps {
+  /** Optionally pass in additional Chakra-based styles. */
+  additionalStyles?: { [key: string]: any };
   /** Additional attributes, such as `rel=nofollow`, to pass to the `<a>` tag. */
   attributes?: { [key: string]: any };
-  /** BlockName for use with BEM. See how to work with blockNames and BEM here: http://getbem.com/introduction/ */
-  blockName?: string;
-  /** className that appears in addition to "link" */
+  /** Any child node passed to the component. */
+  children: React.ReactNode;
+  /** Additional class name to render in the `Link` component. */
   className?: string;
-  /** Href attribute */
+  /** The `href` attribute for the anchor element. */
   href?: string;
-  /** ID */
+  /** ID used for accessibility purposes. */
   id?: string;
-  /** Controls the link visuals—action, button, or default. */
+  /** Controls the link visuals: action, button, backwards, forwards, or default. */
   type?: LinkTypes;
-  /** Modifiers array for use with BEM. See how to work with modifiers and BEM here: http://getbem.com/introduction/ */
-  modifiers?: string[];
-  /** Any child node passed to the component. */
-  children: React.ReactNode;
 }
 
 /**
- * A component that uses an `href` prop or a child anchor element, to create an
- * anchor element with added styling and conventions.
+ * Renders the `Link` children components with a direction arrow icon based
+ * on the `Backwards` or `Forwards` `LinkTypes` type.
  */
-const Link = React.forwardRef<HTMLAnchorElement, LinkProps>((props, ref) => {
-  const {
-    attributes,
-    blockName,
-    className,
-    href,
-    id,
-    type = LinkTypes.Default,
-    modifiers = [],
-    children,
-  } = props;
-
-  // Merge the necessary props alongside any extra props for the
-  // anchor element.
-  const linkProps = {
-    id,
-    href,
-    ...attributes,
-  };
-  let baseClass = "link";
-
-  let childProps = {};
+function getWithDirectionIcon(children, type: LinkTypes) {
+  let iconRotation;
+  let iconAlign;
+  let icon = null;
 
-  if (typeof children === "string" && !href) {
-    throw new Error("Link needs prop 'href'");
-  }
-
-  if (
-    type === LinkTypes.Action ||
-    type === LinkTypes.Forwards ||
-    type === LinkTypes.Backwards
-  ) {
-    baseClass = "more-link";
-  } else if (type === LinkTypes.Button) {
-    baseClass = "button";
-  }
-
-  let iconRotation, iconPosition, iconLeft, iconRight;
   // An icon needs a position in order for it to be created and
   // rendered in the link.
   if (type === LinkTypes.Backwards) {
-    iconRotation = IconRotationTypes.rotate90;
-    iconPosition = "left";
+    iconRotation = IconRotationTypes.Rotate90;
+    iconAlign = IconAlign.Left;
   } else if (type === LinkTypes.Forwards) {
-    iconRotation = IconRotationTypes.rotate270;
-    iconPosition = "right";
+    iconRotation = IconRotationTypes.Rotate270;
+    iconAlign = IconAlign.Right;
   }
 
-  const navigationIconProps: IconProps = {
-    name: IconNames.arrow,
-    modifiers: [iconPosition, iconRotation, ...modifiers],
-    blockName: "more-link",
-    decorative: true,
-  };
+  icon = (
+    <Icon
+      name={IconNames.Arrow}
+      align={iconAlign}
+      iconRotation={iconRotation}
+      className="more-link"
+    />
+  );
 
-  if (type === LinkTypes.Backwards) {
-    iconLeft = <Icon {...navigationIconProps} />;
-  } else if (type === LinkTypes.Forwards) {
-    iconRight = <Icon {...navigationIconProps} />;
-  }
-  const linkClassName = bem(baseClass, modifiers, blockName, [className]);
+  return (
+    <>
+      {type === LinkTypes.Backwards && icon}
+      {children}
+      {type === LinkTypes.Forwards && icon}
+    </>
+  );
+}
+
+/**
+ * A component that uses an `href` prop or a child anchor element, to create
+ * an anchor element with added styling and conventions.
+ */
+const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
+  (props, ref: any) => {
+    const {
+      additionalStyles = {},
+      attributes,
+      children,
+      className,
+      href,
+      id = generateUUID(),
+      type = LinkTypes.Default,
+    } = props;
 
-  if (!props.href) {
-    // React Types error makes this fail:  https://github.com/DefinitelyTyped/DefinitelyTyped/issues/32832
-    // let children = React.Children.only(props.children);
-    if (React.Children.count(props.children) > 1) {
-      throw new Error("Please pass only one child into Link");
+    // Merge the necessary props alongside any extra props for the
+    // anchor element.
+    const linkProps = {
+      id,
+      href,
+      ...attributes,
+    };
+    // The LinkTypes.Default type.
+    let variant = "link";
+
+    if (typeof children === "string" && !href) {
+      throw new Error("Link needs prop 'href'");
     }
-    const children = props.children[0] ? props.children[0] : props.children;
-    childProps = children.props;
 
-    return React.cloneElement(
-      children,
-      {
-        className: linkClassName,
-        ...linkProps,
-        ...childProps,
-        ref,
-      },
-      [children.props.children]
-    );
-  } else {
-    return React.createElement(
-      "a",
-      {
-        ...linkProps,
-        className: linkClassName,
-        ref,
-      },
-      iconLeft,
-      props.children,
-      iconRight
-    );
-  }
-});
+    if (
+      type === LinkTypes.Action ||
+      type === LinkTypes.Forwards ||
+      type === LinkTypes.Backwards
+    ) {
+      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.
+    const newChildren =
+      type === LinkTypes.Forwards || type === LinkTypes.Backwards
+        ? getWithDirectionIcon(children, type)
+        : children;
 
-Link.displayName = "Link";
+    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 React.cloneElement(
+        childrenToClone,
+        {
+          className,
+          ...linkProps,
+          ...childProps,
+          ref,
+        },
+        [childrenToClone.props.children]
+      );
+    } else {
+      return (
+        <Box
+          as="a"
+          className={className}
+          ref={ref}
+          {...linkProps}
+          __css={{ ...style, ...additionalStyles }}
+        >
+          {newChildren}
+        </Box>
+      );
+    }
+  }
+);
 
 export default Link;