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

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

@@ -1,4 +1,4 @@
-import { Box } from "@chakra-ui/react";
+import { Box, VStack } from "@chakra-ui/react";
 import {
   ArgsTable,
   Canvas,
@@ -19,10 +19,7 @@ import { getCategory } from "../../utils/componentCategories";
   argTypes={{
     className: { control: false },
     id: { control: false },
-    optReqFlag: {
-      control: { type: "select" },
-      options: ["Required", "Optional", ""],
-    },
+    isInlined: { table: { disable: true } },
     text: {
       description: "Only used for Storybook",
     },
@@ -34,10 +31,21 @@ import { getCategory } from "../../utils/componentCategories";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.0.10`   |
-| Latest            | `0.25.8`   |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [isRequired helper text](#isrequired-helper-text)
+
+## Overview
 
 <Description of={Label} />
 
+## Component Props
+
 <Canvas>
   <Story
     name="Label with Controls"
@@ -45,7 +53,7 @@ import { getCategory } from "../../utils/componentCategories";
       className: undefined,
       htmlFor: "id-of-input-element",
       id: "label-id",
-      optReqFlag: "Required",
+      isRequired: false,
       text: "A label for a villager.",
     }}
   >
@@ -55,24 +63,38 @@ import { getCategory } from "../../utils/componentCategories";
 
 <ArgsTable story="Label with Controls" />
 
-## Required/Optional helper text
+## Accessibility
+
+The `Label` component is an accessible HTML `<label>` element. The JSX prop
+`htmlFor` should be set to the `id` of the input element that the label is
+associated with. This is the proper way to label inputs so that screenreaders
+can read the label, without the use of the `aria-label` attribute on the input
+element.
+
+Note: All form-related Reservoir components already implement this `Label`
+component so there is no need to use this component unless if you are building
+a new form-related input component.
+
+Resources:
+
+- [WebAIM Creating Accessible Forms](https://webaim.org/techniques/forms/advanced)
+
+## isRequired helper text
 
 An optional helper string can be rendered at the end of the `Label` text through
-the `optReqFlag` prop. Pass in either `"Required"`, `"Optional"`, or `""`. The
-default value is undefined for no helper text to appear.
+the `isRequired` prop. This is useful for visually labeling a field as required
+with the `"(Required)"` text next to the label's text. This is set to `false`
+by default.
 
 <Canvas>
-  <Story name="Required/Optional helper text">
-    <Box width="300px">
-      <Label htmlFor="some-id1" optReqFlag="">
-        No text
-      </Label>
-      <Label htmlFor="some-id2" optReqFlag="Required">
-        Required helper text
+  <Story name="isRequired helper text">
+    <VStack>
+      <Label htmlFor="label-id1" id="regular">
+        A regular label
       </Label>
-      <Label htmlFor="some-id3" optReqFlag="Optional">
-        Optional helper text
+      <Label htmlFor="label-id2" id="required" isRequired>
+        A label that is required
       </Label>
-    </Box>
+    </VStack>
   </Story>
 </Canvas>

package/src/components/Label/Label.test.tsx

@@ -14,6 +14,15 @@ describe("Label Accessibility", () => {
     );
     expect(await axe(container)).toHaveNoViolations();
   });
+
+  it("passes axe accessibility test with required text", async () => {
+    const { container } = render(
+      <Label id="label" htmlFor="some-input-id" isRequired>
+        Cupcakes
+      </Label>
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
 });
 
 describe("Label", () => {
@@ -35,30 +44,33 @@ describe("Label", () => {
     expect(screen.getByText("Cupcakes")).toBeInTheDocument();
   });
 
-  it("renders the optional or required helper text", () => {
+  it("renders the '(Required)' helper text", () => {
     const { rerender } = render(
       <Label id="label" htmlFor="some-input-id">
         <span>Cupcakes</span>
       </Label>
     );
-    expect(screen.queryByText("Optional")).not.toBeInTheDocument();
-    expect(screen.queryByText("Required")).not.toBeInTheDocument();
+    expect(screen.queryByText(/Required/i)).not.toBeInTheDocument();
 
     rerender(
-      <Label id="label2" htmlFor="some-input-id" optReqFlag="Optional">
+      <Label id="label" htmlFor="some-input-id" isRequired>
         <span>Cupcakes</span>
       </Label>
     );
-    expect(screen.getByText("Optional")).toBeInTheDocument();
-    expect(screen.queryByText("Required")).not.toBeInTheDocument();
 
-    rerender(
-      <Label id="label3" htmlFor="some-input-id" optReqFlag="Required">
-        <span>Cupcakes</span>
-      </Label>
+    expect(screen.queryByText(/Required/i)).toBeInTheDocument();
+  });
+
+  it("Logs a warning when there is no `id` passed", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(
+      // @ts-ignore: Typescript complains when a required prop is not passed, but
+      // here we don't want to pass the required prop to make sure the warning appears.
+      <Label htmlFor="some-input-id">Cupcakes</Label>
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir Label: This component's required `id` prop was not passed."
     );
-    expect(screen.queryByText("Optional")).not.toBeInTheDocument();
-    expect(screen.getByText("Required")).toBeInTheDocument();
   });
 
   it("Renders the UI snapshot correctly", () => {
@@ -69,23 +81,36 @@ describe("Label", () => {
         </Label>
       )
       .toJSON();
-    const optional = renderer
+    const required = renderer
       .create(
-        <Label id="label2" htmlFor="some-input-id" optReqFlag="Optional">
+        <Label id="label3" htmlFor="some-input-id" isRequired>
           Cupcakes
         </Label>
       )
       .toJSON();
-    const required = renderer
+    const withChakraProps = renderer
+      .create(
+        <Label
+          id="chakra"
+          htmlFor="some-input-id"
+          p="20px"
+          color="ui.error.primary"
+        >
+          Cupcakes
+        </Label>
+      )
+      .toJSON();
+    const withOtherProps = renderer
       .create(
-        <Label id="label3" htmlFor="some-input-id" optReqFlag="Required">
+        <Label id="props" htmlFor="some-input-id" data-testid="props">
           Cupcakes
         </Label>
       )
       .toJSON();
 
     expect(simple).toMatchSnapshot();
-    expect(optional).toMatchSnapshot();
     expect(required).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
   });
 });

package/src/components/Label/Label.tsx

@@ -1,9 +1,5 @@
+import { Box, chakra, useStyleConfig } from "@chakra-ui/react";
 import * as React from "react";
-import { Box, useMultiStyleConfig } from "@chakra-ui/react";
-
-import generateUUID from "../../helpers/generateUUID";
-
-type optReqFlagType = "Required" | "Optional" | "" | undefined;
 
 interface LabelProps {
   /** Additional CSS class name to render in the `label` element. */
@@ -12,22 +8,34 @@ interface LabelProps {
   htmlFor: string;
   /** ID that other components can cross reference for accessibility purposes */
   id?: string;
-  /** Displays "Required" or "Optional" string alongside the label */
-  optReqFlag?: optReqFlagType;
+  /** Controls whether the label should be inline with the input it goes with.
+   * This prop should only be used internally. */
+  isInlined?: boolean;
+  /** Controls whether the "(Required)" text should be displayed alongside the
+   * label's text. False by default. */
+  isRequired?: boolean;
 }
 
 /**
  * A label for form inputs. It should never be used alone.
  */
-function Label(props: React.PropsWithChildren<LabelProps>) {
+export const Label = chakra((props: React.PropsWithChildren<LabelProps>) => {
   const {
     children,
     className,
     htmlFor,
-    id = generateUUID(),
-    optReqFlag,
+    id,
+    isInlined = false,
+    isRequired = false,
+    ...rest
   } = props;
-  const styles = useMultiStyleConfig("Label", {});
+  const styles = useStyleConfig("Label", { isInlined });
+
+  if (!id) {
+    console.warn(
+      "NYPL Reservoir Label: This component's required `id` prop was not passed."
+    );
+  }
 
   return (
     <Box
@@ -36,11 +44,12 @@ function Label(props: React.PropsWithChildren<LabelProps>) {
       className={className}
       htmlFor={htmlFor}
       __css={styles}
+      {...rest}
     >
       {children}
-      {optReqFlag && <Box __css={styles.helper}>{optReqFlag}</Box>}
+      {isRequired && <span> (Required)</span>}
     </Box>
   );
-}
+});
 
 export default Label;

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

@@ -2,7 +2,7 @@
 
 exports[`Label Renders the UI snapshot correctly 1`] = `
 <label
-  className="css-0"
+  className="css-1xdhyk6"
   htmlFor="some-input-id"
   id="label"
 >
@@ -12,30 +12,34 @@ exports[`Label Renders the UI snapshot correctly 1`] = `
 
 exports[`Label Renders the UI snapshot correctly 2`] = `
 <label
-  className="css-0"
+  className="css-1xdhyk6"
   htmlFor="some-input-id"
-  id="label2"
+  id="label3"
 >
   Cupcakes
-  <div
-    className="css-0"
-  >
-    Optional
-  </div>
+  <span>
+     (Required)
+  </span>
 </label>
 `;
 
 exports[`Label Renders the UI snapshot correctly 3`] = `
 <label
-  className="css-0"
+  className="css-kle7zy"
   htmlFor="some-input-id"
-  id="label3"
+  id="chakra"
+>
+  Cupcakes
+</label>
+`;
+
+exports[`Label Renders the UI snapshot correctly 4`] = `
+<label
+  className="css-1xdhyk6"
+  data-testid="props"
+  htmlFor="some-input-id"
+  id="props"
 >
   Cupcakes
-  <div
-    className="css-0"
-  >
-    Required
-  </div>
 </label>
 `;

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

@@ -52,10 +52,23 @@ export const enumValues = getStorybookEnumValues(LinkTypes, "LinkTypes");
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.0.4`    |
-| Latest            | `0.25.9`   |
+| Latest            | `0.26.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"
@@ -81,6 +94,17 @@ export const enumValues = getStorybookEnumValues(LinkTypes, "LinkTypes");
 
 <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

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

@@ -229,6 +229,25 @@ describe("Link", () => {
         </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();
@@ -238,6 +257,8 @@ describe("Link", () => {
     expect(withIconChild).toMatchSnapshot();
     expect(withAchorChild).toMatchSnapshot();
     expect(withAchorChildAndIcon).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
   });
 
   // TODO:

package/src/components/Link/Link.tsx

@@ -1,11 +1,14 @@
+import { Box, chakra, useStyleConfig } from "@chakra-ui/react";
 import * as React from "react";
-import { Box, useStyleConfig } from "@chakra-ui/react";
 
 import { LinkTypes } from "./LinkTypes";
 import Icon from "../Icons/Icon";
-import { IconRotationTypes, IconNames, IconAlign } from "../Icons/IconTypes";
-import generateUUID from "../../helpers/generateUUID";
-
+import {
+  IconRotationTypes,
+  IconNames,
+  IconAlign,
+  IconSizes,
+} from "../Icons/IconTypes";
 export interface LinkProps {
   /** Optionally pass in additional Chakra-based styles. */
   additionalStyles?: { [key: string]: any };
@@ -51,6 +54,7 @@ function getWithDirectionIcon(children, type: LinkTypes, linkId) {
       iconRotation={iconRotation}
       id={iconId}
       name={IconNames.Arrow}
+      size={IconSizes.Medium}
     />
   );
 
@@ -71,6 +75,7 @@ function getExternalIcon(children, linkId) {
       className="more-link"
       id={iconId}
       name={IconNames.ActionLaunch}
+      size={IconSizes.Medium}
     />
   );
 
@@ -86,16 +91,17 @@ function getExternalIcon(children, linkId) {
  * 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) => {
+export const Link = chakra(
+  React.forwardRef<HTMLAnchorElement, LinkProps>((props, ref: any) => {
     const {
       additionalStyles = {},
       attributes,
       children,
       className,
       href,
-      id = generateUUID(),
+      id,
       type = LinkTypes.Default,
+      ...rest
     } = props;
 
     // Merge the necessary props alongside any extra props for the
@@ -145,7 +151,7 @@ const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
       const childrenToClone: any = children[0] ? children[0] : children;
       const childProps = childrenToClone.props;
       return (
-        <Box as="span" __css={style}>
+        <Box as="span" __css={style} {...rest}>
           {React.cloneElement(
             childrenToClone,
             {
@@ -173,12 +179,13 @@ const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
           target={target}
           {...linkProps}
           __css={{ ...style, ...additionalStyles }}
+          {...rest}
         >
           {newChildren}
         </Box>
       );
     }
-  }
+  })
 );
 
 export default Link;

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

@@ -2,7 +2,7 @@
 
 exports[`Link renders the UI snapshot correctly 1`] = `
 <a
-  className="css-0"
+  className="css-1xdhyk6"
   href="#passed-in-link"
   id="standard-link"
   rel={null}
@@ -14,7 +14,7 @@ exports[`Link renders the UI snapshot correctly 1`] = `
 
 exports[`Link renders the UI snapshot correctly 2`] = `
 <a
-  className="css-0"
+  className="css-1xdhyk6"
   href="#passed-in-link"
   id="forwards-link"
   rel={null}
@@ -23,7 +23,7 @@ exports[`Link renders the UI snapshot correctly 2`] = `
   Forwards
   <svg
     aria-hidden={true}
-    className="chakra-icon more-link css-onkibi"
+    className="chakra-icon more-link css-1grhd2q"
     focusable={false}
     id="forwards-link-icon"
     role="img"
@@ -58,7 +58,7 @@ exports[`Link renders the UI snapshot correctly 2`] = `
 
 exports[`Link renders the UI snapshot correctly 3`] = `
 <a
-  className="css-0"
+  className="css-1xdhyk6"
   href="#passed-in-link"
   id="backwards-link"
   rel={null}
@@ -66,7 +66,7 @@ exports[`Link renders the UI snapshot correctly 3`] = `
 >
   <svg
     aria-hidden={true}
-    className="chakra-icon more-link css-onkibi"
+    className="chakra-icon more-link css-1grhd2q"
     focusable={false}
     id="backwards-link-icon"
     role="img"
@@ -102,7 +102,7 @@ exports[`Link renders the UI snapshot correctly 3`] = `
 
 exports[`Link renders the UI snapshot correctly 4`] = `
 <a
-  className="css-0"
+  className="css-1xdhyk6"
   href="#passed-in-link"
   id="external-link"
   rel="nofollow"
@@ -111,7 +111,7 @@ exports[`Link renders the UI snapshot correctly 4`] = `
   External
   <svg
     aria-hidden={true}
-    className="chakra-icon more-link css-onkibi"
+    className="chakra-icon more-link css-1grhd2q"
     focusable={false}
     id="external-link-icon"
     role="img"
@@ -146,7 +146,7 @@ exports[`Link renders the UI snapshot correctly 4`] = `
 
 exports[`Link renders the UI snapshot correctly 5`] = `
 <a
-  className="css-0"
+  className="css-1xdhyk6"
   href="#passed-in-link"
   id="button-link"
   rel={null}
@@ -158,7 +158,7 @@ exports[`Link renders the UI snapshot correctly 5`] = `
 
 exports[`Link renders the UI snapshot correctly 6`] = `
 <a
-  className="css-0"
+  className="css-1xdhyk6"
   href="#passed-in-link"
   id="icon-link"
   rel={null}
@@ -166,7 +166,7 @@ exports[`Link renders the UI snapshot correctly 6`] = `
 >
   <svg
     aria-hidden={true}
-    className="chakra-icon more-link css-onkibi"
+    className="chakra-icon more-link css-1grhd2q"
     focusable={false}
     id="link-icon"
     role="img"
@@ -205,6 +205,7 @@ exports[`Link renders the UI snapshot correctly 7`] = `
   className="css-0"
 >
   <a
+    className="css-0"
     href="#existing-anchor-tag"
     id="anchor-link"
     rel={null}
@@ -222,7 +223,7 @@ exports[`Link renders the UI snapshot correctly 8`] = `
 >
   <svg
     aria-hidden={true}
-    className="chakra-icon css-onkibi"
+    className="chakra-icon css-1grhd2q"
     focusable={false}
     id="link-icon"
     role="img"
@@ -259,3 +260,28 @@ exports[`Link renders the UI snapshot correctly 8`] = `
   </a>
 </span>
 `;
+
+exports[`Link renders the UI snapshot correctly 9`] = `
+<a
+  className="css-kle7zy"
+  href="#passed-in-link"
+  id="chakra"
+  rel={null}
+  target={null}
+>
+  Standard
+</a>
+`;
+
+exports[`Link renders the UI snapshot correctly 10`] = `
+<a
+  className="css-1xdhyk6"
+  data-testid="props"
+  href="#passed-in-link"
+  id="props"
+  rel={null}
+  target={null}
+>
+  Standard
+</a>
+`;