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

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

@@ -0,0 +1,124 @@
+import {
+  Meta,
+  Story,
+  Canvas,
+  ArgsTable,
+  Description,
+} from "@storybook/addon-docs/blocks";
+import { withDesign } from "storybook-addon-designs";
+
+import HelperErrorText from "./HelperErrorText";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta
+  title={getCategory("HelperErrorText")}
+  component={HelperErrorText}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "",
+    },
+    jest: ["HelperErrorText.test.tsx"],
+  }}
+  argTypes={{
+    ariaAtomic: { table: { disable: true } },
+    children: { table: { disable: true } },
+    className: { table: { disable: true } },
+    id: { table: { disable: true } },
+  }}
+/>
+
+# HelperErrorText
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.0.10`   |
+| Latest            | `0.25.3`   |
+
+<Description of={HelperErrorText} />
+
+<Canvas withToolbar>
+  <Story
+    name="Basic with Props"
+    args={{
+      ariaLive: "polite",
+      isInvalid: false,
+    }}
+  >
+    {(args) => (
+      <HelperErrorText {...args}>
+        {args.isInvalid
+          ? "This is the error text :("
+          : "This is the helper text!"}
+      </HelperErrorText>
+    )}
+  </Story>
+</Canvas>
+
+<ArgsTable story="Basic with Props" />
+
+## With HTML Children
+
+The `HelperErrorText` component can take any React component or HTML element as
+its children.
+
+<Canvas>
+  <Story name="With HTML Children">
+    <HelperErrorText>
+      If you're unsure of your size, please view the{" "}
+      <a href="#sizing-chart">Sizing Chart</a>.
+    </HelperErrorText>
+  </Story>
+</Canvas>
+
+## Invalid State
+
+Set the `isInvalid` prop to `true` to render the passed text in the
+NYPL "invalid" styling.
+
+<Canvas>
+  <Story name="Invalid State">
+    <HelperErrorText isInvalid>This is the error text :(</HelperErrorText>
+  </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 Props"
+    args={{
+      ariaAtomic: true,
+      ariaLive: "polite",
+      isInvalid: true,
+    }}
+  >
+    {(args) => (
+      <HelperErrorText {...args}>
+        Only invalid text can be read to screen readers with the appropriate
+        aria-atomic and aria-live props.
+      </HelperErrorText>
+    )}
+  </Story>
+</Canvas>

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

@@ -1,77 +1,72 @@
 import * as React from "react";
 import { render, screen } from "@testing-library/react";
 import { axe } from "jest-axe";
+import renderer from "react-test-renderer";
 
 import HelperErrorText from "./HelperErrorText";
 
 describe("HelperErrorText Accessibility", () => {
   it("passes axe accessibility test", async () => {
-    const { container } = render(
-      <HelperErrorText id="helperTextWithLink" isError={false}>
-        Text
-      </HelperErrorText>
-    );
+    const { container } = render(<HelperErrorText>Text</HelperErrorText>);
     expect(await axe(container)).toHaveNoViolations();
   });
 });
 
 describe("HelperErrorText", () => {
-  it("Renders HelperErrorText", () => {
-    render(
-      <HelperErrorText id="helperTextWithLink" isError={false}>
-        Text
-      </HelperErrorText>
-    );
+  it("renders the text passed", () => {
+    render(<HelperErrorText>Text</HelperErrorText>);
     expect(screen.getByText("Text")).toBeInTheDocument();
-    expect(screen.getByText("Text")).toHaveAttribute("class", "helper-text");
   });
 
-  it("Has 'error' modifier if error is passed", () => {
-    render(
-      <HelperErrorText id="helperTextWithLink" isError={true}>
-        Text
-      </HelperErrorText>
-    );
-    expect(screen.getByText("Text")).toHaveAttribute(
-      "class",
-      "helper-text helper-text--error"
-    );
+  it("renders the invalid state", () => {
+    const utils = render(<HelperErrorText>Text</HelperErrorText>);
+
+    // False by default. Note, this is a custom `data-*` attribute only used
+    // for testing the invalid state.
+    expect(screen.getByText("Text")).toHaveAttribute("data-isinvalid", "false");
+
+    utils.rerender(<HelperErrorText isInvalid>Text</HelperErrorText>);
+    expect(screen.getByText("Text")).toHaveAttribute("data-isinvalid", "true");
   });
 
-  it("Has aria-live and aria-atomic properties when errored", () => {
-    render(
-      <HelperErrorText id="helperTextWithLink" isError={true}>
-        Text
-      </HelperErrorText>
-    );
+  it("has aria-live and aria-atomic attributes when errored", () => {
+    render(<HelperErrorText isInvalid>Text</HelperErrorText>);
     expect(screen.getByText("Text")).toHaveAttribute("aria-live", "polite");
     expect(screen.getByText("Text")).toHaveAttribute("aria-atomic");
   });
 
-  it("Accepts an aria-atomic value of false", () => {
+  it("accepts an aria-atomic value of false", () => {
     const utils = render(
-      <HelperErrorText id="helperTextWithLink" isError={true}>
-        Text
-      </HelperErrorText>
+      <HelperErrorText isInvalid>Static Text</HelperErrorText>
     );
     // The default is "true".
-    expect(screen.getByText("Text")).toHaveAttribute("aria-atomic");
+    expect(screen.getByText("Static Text")).toHaveAttribute("aria-atomic");
 
     utils.rerender(
-      <HelperErrorText
-        id="helperTextWithLink"
-        isError={true}
-        ariaAtomic={false}
-      >
-        <p>
-          This is static <span>but this part changes often!</span>
-        </p>
+      <HelperErrorText ariaAtomic={false} isInvalid>
+        Static Text
       </HelperErrorText>
     );
     // But the prop accepts false in case only part of the helper text
     // should only be read instead of the whole region.
-    expect(
-      utils.container.querySelector("#helperTextWithLink")
-    ).toHaveAttribute("aria-atomic", "false");
+    expect(screen.getByText("Static Text")).toHaveAttribute(
+      "aria-atomic",
+      "false"
+    );
+  });
+
+  it("Renders the UI snapshot correctly", () => {
+    const basic = renderer
+      .create(<HelperErrorText id="basic">Text</HelperErrorText>)
+      .toJSON();
+    const invalid = renderer
+      .create(
+        <HelperErrorText id="invalid" isInvalid>
+          Text
+        </HelperErrorText>
+      )
+      .toJSON();
+    expect(basic).toMatchSnapshot();
+    expect(invalid).toMatchSnapshot();
   });
 });

package/src/components/HelperErrorText/HelperErrorText.tsx

@@ -1,24 +1,29 @@
 import * as React from "react";
-import bem from "../../utils/bem";
+import { Box, useStyleConfig } from "@chakra-ui/react";
+
+import generateUUID from "../../helpers/generateUUID";
+
+export type AriaLiveValues = "assertive" | "off" | "polite";
 
 interface HelperErrorTextProps {
-  /** Added prop when HelperText is errored */
-  ariaLive?: "polite" | "off" | "assertive";
-  /** Added prop when HelperText is errored */
+  /** Optionally pass in additional Chakra-based styles. */
+  additionalStyles?: { [key: string]: any };
+  /** Aria attribute. When true, assistive technologies will
+   * read the entire DOM element. When false, only changes (additionals or
+   * removals) will be read. True by default. */
   ariaAtomic?: boolean;
-  /** Additional attributes passed to <HelperErrorText> */
-  attributes?: { [key: string]: any };
-
-  /** Additional className to add to the helperErrorText */
+  /** 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. */
+  ariaLive?: AriaLiveValues;
+  /** Additional className to add. */
   className?: string;
-  /** BlockName for use with BEM. See how to work with blockNames and BEM here: http://getbem.com/introduction/ */
-  blockName?: string;
-  /** unique ID for helper */
+  /** Unique ID for accessibility purposes. */
   id?: string;
-  /** Toggles between helper and error styling */
-  isError: boolean;
-  /** Modifiers array for use with BEM. See how to work with modifiers and BEM here: http://getbem.com/introduction/ */
-  modifiers?: string[];
+  /** Toggles between helper and invalid styling. */
+  isInvalid?: boolean;
 }
 
 /**
@@ -28,36 +33,29 @@ export default function HelperErrorText(
   props: React.PropsWithChildren<HelperErrorTextProps>
 ) {
   const {
-    attributes,
-    id,
-    blockName,
-    isError,
-    ariaLive = "polite",
+    additionalStyles = {},
     ariaAtomic = true,
+    ariaLive = "polite",
+    children,
+    className = "",
+    id = generateUUID(),
+    isInvalid = false,
   } = props;
-
-  const baseClass = "helper-text";
-  const modifiers = [];
-  let announceAriaLive = false;
-
-  if (isError) {
-    modifiers.push("error");
-    announceAriaLive = true;
-  }
-
-  if (props.modifiers) {
-    modifiers.push(...props.modifiers);
-  }
+  // Only announce the text in the invalid state.
+  const announceAriaLive = isInvalid;
+  const styles = useStyleConfig("HelperErrorText", { isInvalid });
+  const finalStyles = { ...styles, ...additionalStyles };
 
   return (
-    <div
+    <Box
       id={id}
-      className={bem(baseClass, modifiers, blockName)}
-      aria-live={announceAriaLive ? ariaLive : "off"}
+      className={className}
       aria-atomic={ariaAtomic}
-      {...attributes}
+      data-isinvalid={isInvalid}
+      aria-live={announceAriaLive ? ariaLive : "off"}
+      __css={finalStyles}
     >
-      {props.children}
-    </div>
+      {children}
+    </Box>
   );
 }

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

@@ -0,0 +1,25 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`HelperErrorText Renders the UI snapshot correctly 1`] = `
+<div
+  aria-atomic={true}
+  aria-live="off"
+  className=" css-0"
+  data-isinvalid={false}
+  id="basic"
+>
+  Text
+</div>
+`;
+
+exports[`HelperErrorText Renders the UI snapshot correctly 2`] = `
+<div
+  aria-atomic={true}
+  aria-live="polite"
+  className=" css-0"
+  data-isinvalid={true}
+  id="invalid"
+>
+  Text
+</div>
+`;