@nypl/design-system-react-components 0.25.12 → 0.26.1

package/src/components/Heading/Heading.test.tsx

@@ -4,7 +4,7 @@ import { axe } from "jest-axe";
 import renderer from "react-test-renderer";
 
 import Heading from "./Heading";
-import { HeadingDisplaySizes, HeadingLevels } from "./HeadingTypes";
+import { HeadingSizes, HeadingLevels } from "./HeadingTypes";
 
 describe("Heading Accessibility", () => {
   it("passes axe accessibility test", async () => {
@@ -93,7 +93,7 @@ describe("Heading", () => {
 
   it("throws error when neither child nor text is passed", () => {
     expect(() => render(<Heading id="h1" level={HeadingLevels.One} />)).toThrow(
-      "Heading has no children, please pass prop: text"
+      "NYPL Reservoir Heading: No children or value was passed to the `text` prop."
     );
   });
 
@@ -105,7 +105,7 @@ describe("Heading", () => {
           <span>many</span>
         </Heading>
       )
-    ).toThrow("Please only pass one child into Heading, got span, span");
+    ).toThrow("NYPL Reservoir Heading: Only pass one child into Heading.");
   });
 
   it("uses custom display size", () => {
@@ -113,8 +113,8 @@ describe("Heading", () => {
       <Heading
         id="h1"
         level={HeadingLevels.One}
-        text="Heading with Secondary displaySize"
-        displaySize={HeadingDisplaySizes.Secondary}
+        size={HeadingSizes.Secondary}
+        text="Heading with Secondary size"
       />
     );
     expect(screen.getByRole("heading", { level: 1 })).toHaveStyle({
@@ -140,8 +140,8 @@ describe("Heading", () => {
         <Heading
           id="customDisplaySize"
           level={HeadingLevels.One}
-          text="Heading with Secondary displaySize"
-          displaySize={HeadingDisplaySizes.Secondary}
+          size={HeadingSizes.Secondary}
+          text="Heading with Secondary size"
         />
       )
       .toJSON();
@@ -176,6 +176,14 @@ describe("Heading", () => {
         </Heading>
       )
       .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <Heading id="chakra" text="Heading" p="20px" color="ui.red.primary" />
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(<Heading id="props" text="Heading" data-testid="props" />)
+      .toJSON();
 
     expect(basic).toMatchSnapshot();
     expect(basicWithChildText).toMatchSnapshot();
@@ -183,5 +191,7 @@ describe("Heading", () => {
     expect(otherLevel).toMatchSnapshot();
     expect(withLink).toMatchSnapshot();
     expect(withCustomLink).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
   });
 });

package/src/components/Heading/Heading.tsx

@@ -1,24 +1,26 @@
-import { Heading as ChakraHeading, useStyleConfig } from "@chakra-ui/react";
+import {
+  chakra,
+  Heading as ChakraHeading,
+  useStyleConfig,
+} from "@chakra-ui/react";
 import * as React from "react";
 
-import { HeadingDisplaySizes, HeadingLevels } from "./HeadingTypes";
+import { HeadingSizes, HeadingLevels } from "./HeadingTypes";
 import Link from "../Link/Link";
 import { getVariant } from "../../utils/utils";
-import generateUUID from "../../helpers/generateUUID";
-
 export interface HeadingProps {
   /** Optionally pass in additional Chakra-based styles. */
   additionalStyles?: { [key: string]: any };
   /** Optional className that appears in addition to `heading` */
   className?: string;
-  /** Optional size used to override the default styles of the semantic HTM
-   * `<h>` elements */
-  displaySize?: HeadingDisplaySizes;
   /** Optional ID that other components can cross reference for accessibility purposes */
   id?: string;
   /** Optional number 1-6 used to create the `<h*>` tag; if prop is not passed,
    * `Heading` will default to `<h2>` */
   level?: HeadingLevels;
+  /** Optional size used to override the default styles of the semantic HTM
+   * `<h>` elements */
+  size?: HeadingSizes;
   /** Inner text of the `<h*>` element */
   text?: string;
   /** Optional URL that header points to; when `url` prop is passed to
@@ -42,61 +44,61 @@ const getMappedLevel = (level = HeadingLevels.Two) => {
   return levelMap[level] || 2;
 };
 
-function Heading(props: React.PropsWithChildren<HeadingProps>) {
-  const {
-    additionalStyles = {},
-    className,
-    displaySize,
-    id = generateUUID(),
-    level = HeadingLevels.Two,
-    text,
-    url,
-    urlClass,
-  } = props;
-  const finalLevel = getMappedLevel(level);
-  const variant = displaySize
-    ? getVariant(displaySize, HeadingDisplaySizes)
-    : `h${finalLevel}`;
-  const styles = useStyleConfig("Heading", { variant });
-  // Combine native base styles with any additional styles.
-  // This is used in the `Hero` and `Notification` components.
-  const finalStyles = { ...styles, ...additionalStyles };
-  const asHeading: any = `h${finalLevel}`;
+export const Heading = chakra(
+  (props: React.PropsWithChildren<HeadingProps>) => {
+    const {
+      additionalStyles = {},
+      className,
+      id,
+      level = HeadingLevels.Two,
+      size,
+      text,
+      url,
+      urlClass,
+      ...rest
+    } = props;
+    const finalLevel = getMappedLevel(level);
+    const variant = size ? getVariant(size, HeadingSizes) : `h${finalLevel}`;
+    const styles = useStyleConfig("Heading", { variant });
+    // Combine native base styles with any additional styles.
+    // This is used in the `Hero` and `Notification` components.
+    const finalStyles = { ...styles, ...additionalStyles };
+    const asHeading: any = `h${finalLevel}`;
 
-  if (!props.children && !text) {
-    throw new Error("Heading has no children, please pass prop: text");
-  }
+    if (!props.children && !text) {
+      throw new Error(
+        "NYPL Reservoir Heading: No children or value was passed to the `text` prop."
+      );
+    }
 
-  if (React.Children.count(props.children) > 1) {
-    const children = React.Children.map(
-      props.children,
-      (child) => (child as JSX.Element).type
+    if (React.Children.count(props.children) > 1) {
+      // Catching the error because React's error isn't as helpful.
+      throw new Error(
+        "NYPL Reservoir Heading: Only pass one child into Heading."
+      );
+    }
+
+    const contentToRender = props.children ? props.children : text;
+    const content = url ? (
+      <Link className={urlClass} href={url} id={`${id}-link`}>
+        {contentToRender}
+      </Link>
+    ) : (
+      contentToRender
     );
-    // Catching the error because React's error isn't as helpful.
-    throw new Error(
-      `Please only pass one child into Heading, got ${children.join(", ")}`
+
+    return (
+      <ChakraHeading
+        as={asHeading}
+        className={className}
+        id={id}
+        sx={finalStyles}
+        {...rest}
+      >
+        {content}
+      </ChakraHeading>
     );
   }
-
-  const contentToRender = props.children ? props.children : text;
-  const content = url ? (
-    <Link className={urlClass} href={url} id={`${id}-link`}>
-      {contentToRender}
-    </Link>
-  ) : (
-    contentToRender
-  );
-
-  return (
-    <ChakraHeading
-      id={id}
-      as={asHeading}
-      sx={finalStyles}
-      className={className}
-    >
-      {content}
-    </ChakraHeading>
-  );
-}
+);
 
 export default Heading;

package/src/components/Heading/HeadingTypes.tsx

@@ -1,4 +1,4 @@
-export enum HeadingDisplaySizes {
+export enum HeadingSizes {
   Primary = "primary",
   Secondary = "secondary",
   Tertiary = "tertiary",

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

@@ -2,7 +2,7 @@
 
 exports[`Heading renders the UI snapshot correctly 1`] = `
 <h1
-  className="chakra-heading css-0"
+  className="chakra-heading css-1xdhyk6"
   id="basic"
 >
   Heading text
@@ -11,7 +11,7 @@ exports[`Heading renders the UI snapshot correctly 1`] = `
 
 exports[`Heading renders the UI snapshot correctly 2`] = `
 <h1
-  className="chakra-heading css-0"
+  className="chakra-heading css-1xdhyk6"
   id="basicWithChildText"
 >
   Heading text
@@ -20,16 +20,16 @@ exports[`Heading renders the UI snapshot correctly 2`] = `
 
 exports[`Heading renders the UI snapshot correctly 3`] = `
 <h1
-  className="chakra-heading css-0"
+  className="chakra-heading css-1xdhyk6"
   id="customDisplaySize"
 >
-  Heading with Secondary displaySize
+  Heading with Secondary size
 </h1>
 `;
 
 exports[`Heading renders the UI snapshot correctly 4`] = `
 <h6
-  className="chakra-heading css-0"
+  className="chakra-heading css-1xdhyk6"
   id="otherLevel"
 >
   Heading level six
@@ -38,11 +38,11 @@ exports[`Heading renders the UI snapshot correctly 4`] = `
 
 exports[`Heading renders the UI snapshot correctly 5`] = `
 <h1
-  className="chakra-heading css-0"
+  className="chakra-heading css-1xdhyk6"
   id="withLink"
 >
   <a
-    className="css-0"
+    className="css-1xdhyk6"
     href="fake-url"
     id="withLink-link"
     rel={null}
@@ -55,7 +55,7 @@ exports[`Heading renders the UI snapshot correctly 5`] = `
 
 exports[`Heading renders the UI snapshot correctly 6`] = `
 <h1
-  className="chakra-heading css-0"
+  className="chakra-heading css-1xdhyk6"
   id="withCustomLink"
 >
   Part of the heading text is
@@ -69,3 +69,22 @@ exports[`Heading renders the UI snapshot correctly 6`] = `
   </a>
 </h1>
 `;
+
+exports[`Heading renders the UI snapshot correctly 7`] = `
+<h2
+  className="chakra-heading css-10g9ftz"
+  id="chakra"
+>
+  Heading
+</h2>
+`;
+
+exports[`Heading renders the UI snapshot correctly 8`] = `
+<h2
+  className="chakra-heading css-1xdhyk6"
+  data-testid="props"
+  id="props"
+>
+  Heading
+</h2>
+`;

package/src/components/HelperErrorText/HelperErrorText.stories.mdx

@@ -47,10 +47,22 @@ import DSProvider from "../../theme/provider";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.0.10`   |
-| Latest            | `0.25.11`  |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [With HTML Children](#with-html-children)
+- [Invalid State](#invalid-state)
+
+## Overview
 
 <Description of={HelperErrorText} />
 
+## Component Props
+
 <Canvas withToolbar>
   <Story
     name="HelperErrorText with Controls"
@@ -75,6 +87,54 @@ import DSProvider from "../../theme/provider";
 
 <ArgsTable story="HelperErrorText with Controls" />
 
+## Accessibility
+
+In the "invalid" state when `isInvalid` is set to true, the text passed to the
+`invalidText` prop will be presented to screen readers be default. If you need
+to turn this off, set the `ariaLive` prop to `"off"`. This is used in DS "form"
+components for invalid form submissions or incorrect values entered.
+
+### ariaAtomic
+
+The `ariaAtomic` prop sets the `aria-atomic` attribute and it is set to `true`
+by default. This allows the entire DOM element to be presented to assistive
+technologies. When it is set to `false`, only additionals or removals will be
+read by assistive technologies.
+
+### ariaLive
+
+The `ariaLive` prop sets the `aria-live` attribute; `"polite"` is set by default
+in the "invalid" state and `"off"` otherwise. This sets the priority of when the
+text in this component should be read to users by assistive technologies. The
+`"off"` value indicates that the content should not be presented, `"polite"` that
+it will be announced at the next available time slot, and `"assertive"` that it
+should be announced immediately.
+
+<Canvas>
+  <Story
+    name="With Aria Controls"
+    args={{
+      ariaAtomic: true,
+      ariaLive: "polite",
+      isInvalid: true,
+    }}
+  >
+    {(args) => (
+      <HelperErrorText
+        {...args}
+        text="Only invalid text can be read to screen readers with the appropriate aria-atomic and aria-live props."
+      />
+    )}
+  </Story>
+</Canvas>
+
+Resources:
+
+- [MDN ARIA live regions](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions)
+- [W3C WAI-ARIA 1.1 - aria-live (property)](https://www.w3.org/TR/wai-aria-1.1/#aria-live)
+- [W3C ARIA19: Using ARIA role=alert or Live Regions to Identify Errors](https://www.w3.org/TR/WCAG20-TECHS/ARIA19.html)
+- [DigitalA11y WAI-ARIA:aria-live (Property)](https://www.digitala11y.com/aria-live-properties/)
+
 ## With HTML Children
 
 The `HelperErrorText` component can render any React component or HTML element
@@ -93,8 +153,9 @@ through the `text` prop.
     <HelperErrorText
       text={
         <Text>
-          This second example uses DS components, such as the{" "}
-          <Link href="#">`Link`</Link> component, and the `Text` component.
+          This second example uses Reservoir Design System (DS) components, such
+          as the <Link href="#">`Link`</Link> component, and the `Text`
+          component.
         </Text>
       }
     />
@@ -111,42 +172,3 @@ NYPL "invalid" styling.
     <HelperErrorText isInvalid text="This is the error text :(" />
   </Story>
 </Canvas>
-
-## With Aria Props
-
-In the "invalid" state when `isInvalid` is set to true, the rendered text can be
-presented to screen readers if `ariaAtomic` and `ariaLive` are set appropriately.
-
-### ariaAtomic
-
-The `ariaAtomic` prop sets the `aria-atomic` attribute; `true` by default. This
-allows the entire DOM element to be presented to assistive technologies. When it
-is set to `false`, only additionals or removals will be read by assistive
-technologies.
-
-### ariaLive
-
-The `ariaLive` prop sets the `aria-live` attribute; `polite` by default in the
-"invalid" state and `off` otherwise. This sets the priority of when the text in
-this component should be read to users by assistive technologies. The `off` value
-indicates that the content should not be presented, `polite` that it will be
-announced at the next available time slot, and `assertive` that it should be
-announced immediately.
-
-<Canvas>
-  <Story
-    name="With Aria Controls"
-    args={{
-      ariaAtomic: true,
-      ariaLive: "polite",
-      isInvalid: true,
-    }}
-  >
-    {(args) => (
-      <HelperErrorText
-        {...args}
-        text="Only invalid text can be read to screen readers with the appropriate aria-atomic and aria-live props."
-      />
-    )}
-  </Story>
-</Canvas>

package/src/components/HelperErrorText/HelperErrorText.test.tsx

@@ -90,10 +90,25 @@ describe("HelperErrorText", () => {
         />
       )
       .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <HelperErrorText
+          id="chakra"
+          text="Text"
+          p="20px"
+          color="ui.red.primary"
+        />
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(<HelperErrorText id="props" text="Text" data-testid="props" />)
+      .toJSON();
 
     expect(basic).toMatchSnapshot();
     expect(invalid).toMatchSnapshot();
     expect(withHTMLString).toMatchSnapshot();
     expect(withHTMLElement).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
   });
 });

package/src/components/HelperErrorText/HelperErrorText.tsx

@@ -1,7 +1,5 @@
+import { Box, chakra, useStyleConfig } from "@chakra-ui/react";
 import * as React from "react";
-import { Box, useStyleConfig } from "@chakra-ui/react";
-
-import generateUUID from "../../helpers/generateUUID";
 
 export type AriaLiveValues = "assertive" | "off" | "polite";
 export type HelperErrorTextType = string | JSX.Element;
@@ -13,11 +11,12 @@ interface HelperErrorTextProps {
    * read the entire DOM element. When false, only changes (additionals or
    * removals) will be read. True by default. */
   ariaAtomic?: boolean;
-  /** Aria attribute only used in the invalid state to read error text. This
-   * indicates the priority of the text and when it should be presented to users
-   * using screen readers; "off" indicates that the content should not be presented,
-   * "polite" that it will be announced at the next available time slot, and
-   * "assertive" that it should be announced immediately. "polite" by default. */
+  /** Aria attribute used in the invalid state to read error text by default.
+   * This indicates the priority of the text and when it should be presented to
+   * users using screen readers; "off" indicates that the content should not be
+   * presented, "polite" that it will be announced at the next available time
+   * slot, and "assertive" that it should be announced immediately. This is set
+   * to "off" by default and to "polite" by when `isInvalid` is true. */
   ariaLive?: AriaLiveValues;
   /** Additional className to add. */
   className?: string;
@@ -30,32 +29,38 @@ interface HelperErrorTextProps {
 }
 
 /**
- * Helper or Error text for forms
+ * Helper or error text for forms components.
  */
-export default function HelperErrorText({
-  additionalStyles = {},
-  ariaAtomic = true,
-  ariaLive = "polite",
-  className = "",
-  id = generateUUID(),
-  isInvalid = false,
-  text,
-}: HelperErrorTextProps) {
-  // Only announce the text in the invalid state.
-  const announceAriaLive = isInvalid;
-  const styles = useStyleConfig("HelperErrorText", { isInvalid });
-  const finalStyles = { ...styles, ...additionalStyles };
-  const props = {
-    "aria-atomic": ariaAtomic,
-    "aria-live": announceAriaLive ? ariaLive : "off",
-    className,
-    "data-isinvalid": isInvalid,
+export const HelperErrorText = chakra(
+  ({
+    additionalStyles = {},
+    ariaAtomic = true,
+    ariaLive = "polite",
+    className = "",
     id,
-    __css: finalStyles,
-  };
-  return typeof text === "string" ? (
-    <Box {...props} dangerouslySetInnerHTML={{ __html: text }} />
-  ) : (
-    <Box {...props}>{text}</Box>
-  );
-}
+    isInvalid = false,
+    text,
+    ...rest
+  }: HelperErrorTextProps) => {
+    // Only announce the text in the invalid state.
+    const announceAriaLive = isInvalid;
+    const styles = useStyleConfig("HelperErrorText", { isInvalid });
+    const finalStyles = { ...styles, ...additionalStyles };
+    const props = {
+      "aria-atomic": ariaAtomic,
+      "aria-live": announceAriaLive ? ariaLive : "off",
+      className,
+      "data-isinvalid": isInvalid,
+      id,
+      __css: finalStyles,
+      ...rest,
+    };
+    return typeof text === "string" ? (
+      <Box {...props} dangerouslySetInnerHTML={{ __html: text }} />
+    ) : (
+      <Box {...props}>{text}</Box>
+    );
+  }
+);
+
+export default HelperErrorText;

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

@@ -4,7 +4,7 @@ exports[`HelperErrorText Renders the UI snapshot correctly 1`] = `
 <div
   aria-atomic={true}
   aria-live="off"
-  className=" css-0"
+  className="css-1xdhyk6"
   dangerouslySetInnerHTML={
     Object {
       "__html": "Text",
@@ -19,7 +19,7 @@ exports[`HelperErrorText Renders the UI snapshot correctly 2`] = `
 <div
   aria-atomic={true}
   aria-live="polite"
-  className=" css-0"
+  className="css-1xdhyk6"
   dangerouslySetInnerHTML={
     Object {
       "__html": "Text",
@@ -34,7 +34,7 @@ exports[`HelperErrorText Renders the UI snapshot correctly 3`] = `
 <div
   aria-atomic={true}
   aria-live="polite"
-  className=" css-0"
+  className="css-1xdhyk6"
   dangerouslySetInnerHTML={
     Object {
       "__html": "This helper text <b>contains HTML in the string</b>.",
@@ -49,7 +49,7 @@ exports[`HelperErrorText Renders the UI snapshot correctly 4`] = `
 <div
   aria-atomic={true}
   aria-live="polite"
-  className=" css-0"
+  className="css-1xdhyk6"
   data-isinvalid={true}
   id="invalid"
 >
@@ -60,3 +60,34 @@ exports[`HelperErrorText Renders the UI snapshot correctly 4`] = `
   .
 </div>
 `;
+
+exports[`HelperErrorText Renders the UI snapshot correctly 5`] = `
+<div
+  aria-atomic={true}
+  aria-live="off"
+  className="css-10g9ftz"
+  dangerouslySetInnerHTML={
+    Object {
+      "__html": "Text",
+    }
+  }
+  data-isinvalid={false}
+  id="chakra"
+/>
+`;
+
+exports[`HelperErrorText Renders the UI snapshot correctly 6`] = `
+<div
+  aria-atomic={true}
+  aria-live="off"
+  className="css-1xdhyk6"
+  dangerouslySetInnerHTML={
+    Object {
+      "__html": "Text",
+    }
+  }
+  data-isinvalid={false}
+  data-testid="props"
+  id="props"
+/>
+`;