@nypl/design-system-react-components 0.25.8 → 0.25.11

package/src/components/Label/Label.stories.mdx

@@ -1,11 +1,11 @@
+import { Box } from "@chakra-ui/react";
 import {
-  Meta,
-  Story,
-  Canvas,
   ArgsTable,
+  Canvas,
   Description,
-} from "@storybook/addon-docs/blocks";
-import { Box } from "@chakra-ui/react";
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
 
 import Label from "./Label";
 import { getCategory } from "../../utils/componentCategories";
@@ -17,8 +17,15 @@ import { getCategory } from "../../utils/componentCategories";
     jest: ["Label.test.tsx"],
   }}
   argTypes={{
-    className: { table: { disable: true } },
-    id: { table: { disable: true } },
+    className: { control: false },
+    id: { control: false },
+    optReqFlag: {
+      control: { type: "select" },
+      options: ["Required", "Optional", ""],
+    },
+    text: {
+      description: "Only used for Storybook",
+    },
   }}
 />
 
@@ -33,26 +40,20 @@ import { getCategory } from "../../utils/componentCategories";
 
 <Canvas>
   <Story
-    name="Label"
+    name="Label with Controls"
     args={{
-      text: "A label for a villager.",
-      optReqFlag: "Required",
+      className: undefined,
       htmlFor: "id-of-input-element",
-    }}
-    argTypes={{
-      optReqFlag: {
-        control: {
-          type: "select",
-        },
-        options: ["Required", "Optional", ""],
-      },
+      id: "label-id",
+      optReqFlag: "Required",
+      text: "A label for a villager.",
     }}
   >
     {(args) => <Label {...args}>{args.text}</Label>}
   </Story>
 </Canvas>
 
-<ArgsTable story="Label" />
+<ArgsTable story="Label with Controls" />
 
 ## Required/Optional helper text
 

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")}
@@ -31,13 +34,15 @@ import DSProvider from "../../theme/provider";
     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,
     },
   }}
 />
@@ -47,29 +52,34 @@ import DSProvider from "../../theme/provider";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.0.4`    |
-| Latest            | `0.25.8`   |
+| 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
 
@@ -89,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>
@@ -102,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">
@@ -112,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>
@@ -144,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,
@@ -157,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,
@@ -169,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";
 
@@ -200,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,16 +1,21 @@
-import * as React from "react";
 import { render, screen } from "@testing-library/react";
 import { axe } from "jest-axe";
-import renderer from "react-test-renderer";
-
-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 () => {
@@ -121,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>
@@ -202,12 +207,37 @@ describe("Link", () => {
         </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:

package/src/components/Link/Link.tsx

@@ -109,7 +109,7 @@ 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 (
@@ -144,17 +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,
-          rel,
-          target,
-        },
-        [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 (

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

@@ -199,3 +199,63 @@ exports[`Link renders the UI snapshot correctly 6`] = `
   Download
 </a>
 `;
+
+exports[`Link renders the UI snapshot correctly 7`] = `
+<span
+  className="css-0"
+>
+  <a
+    href="#existing-anchor-tag"
+    id="anchor-link"
+    rel={null}
+    style={Object {}}
+    target={null}
+  >
+    check link
+  </a>
+</span>
+`;
+
+exports[`Link renders the UI snapshot correctly 8`] = `
+<span
+  className="css-0"
+>
+  <svg
+    aria-hidden={true}
+    className="chakra-icon css-onkibi"
+    focusable={false}
+    id="link-icon"
+    role="img"
+    title="check icon"
+    viewBox="0 0 24 24"
+  >
+    <g
+      stroke="currentColor"
+      strokeWidth="1.5"
+    >
+      <path
+        d="M9,9a3,3,0,1,1,4,2.829,1.5,1.5,0,0,0-1,1.415V14.25"
+        fill="none"
+        strokeLinecap="round"
+      />
+      <path
+        d="M12,17.25a.375.375,0,1,0,.375.375A.375.375,0,0,0,12,17.25h0"
+        fill="currentColor"
+        strokeLinecap="round"
+      />
+      <circle
+        cx="12"
+        cy="12"
+        fill="none"
+        r="11.25"
+        strokeMiterlimit="10"
+      />
+    </g>
+  </svg>
+  <a
+    href="#existing-anchor-tag"
+  >
+    check link
+  </a>
+</span>
+`;