@nypl/design-system-react-components 1.0.1 → 1.0.2

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

@@ -0,0 +1,172 @@
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import HelperErrorText from "./HelperErrorText";
+import Link from "../Link/Link";
+import Text from "../Text/Text";
+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: {
+      control: false,
+      table: { defaultValue: { summary: true } },
+    },
+    ariaLive: {
+      table: { defaultValue: { summary: "polite" } },
+    },
+    children: { table: { disable: true } },
+    className: { control: false },
+    id: { control: false },
+    isInvalid: {
+      table: { defaultValue: { summary: false } },
+    },
+  }}
+/>
+
+# HelperErrorText
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.0.10`   |
+| Latest            | `0.28.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"
+    args={{
+      ariaAtomic: undefined,
+      ariaLive: "polite",
+      className: undefined,
+      id: "helperErrorText-id",
+      isInvalid: false,
+      text: "This is the helper text!",
+    }}
+  >
+    {(args) => (
+      <HelperErrorText
+        {...args}
+        text={args.isInvalid ? "This is the error text :(" : args.text}
+      />
+    )}
+  </Story>
+</Canvas>
+
+<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
+through the `text` prop.
+
+<Canvas>
+  <Story name="With HTML Children">
+    <HelperErrorText
+      text={
+        <>
+          This first example uses an HTML anchor element for{" "}
+          <a href="#">a link</a>.
+        </>
+      }
+    />
+    <HelperErrorText
+      text={
+        <Text>
+          This second example uses Reservoir Design System (DS) components, such
+          as the <Link href="#">`Link`</Link> component, and the `Text`
+          component.
+        </Text>
+      }
+    />
+  </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 text="This is the error text :(" />
+  </Story>
+</Canvas>

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

@@ -0,0 +1,114 @@
+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 text="Text" />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("HelperErrorText", () => {
+  it("renders the text passed", () => {
+    render(<HelperErrorText text="Text" />);
+    expect(screen.getByText("Text")).toBeInTheDocument();
+  });
+
+  it("renders the text passed as an HTML string", () => {
+    render(<HelperErrorText text="<b>This text is bold</b>" />);
+    expect(screen.getByText("This text is bold")).toBeInTheDocument();
+  });
+
+  it("renders the text passed as HTML", () => {
+    render(<HelperErrorText text={<b>This text is bold</b>} />);
+    expect(screen.getByText("This text is bold")).toBeInTheDocument();
+  });
+
+  it("renders the invalid state", () => {
+    const utils = render(<HelperErrorText text="Text" />);
+
+    // 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="Text" />);
+    expect(screen.getByText("Text")).toHaveAttribute("data-isinvalid", "true");
+  });
+
+  it("has aria-live and aria-atomic attributes when errored", () => {
+    render(<HelperErrorText isInvalid text="Text" />);
+    expect(screen.getByText("Text")).toHaveAttribute("aria-live", "polite");
+    expect(screen.getByText("Text")).toHaveAttribute("aria-atomic");
+  });
+
+  it("accepts an aria-atomic value of false", () => {
+    const utils = render(<HelperErrorText isInvalid text="Static Text" />);
+    // The default is "true".
+    expect(screen.getByText("Static Text")).toHaveAttribute("aria-atomic");
+
+    utils.rerender(
+      <HelperErrorText ariaAtomic={false} isInvalid text="Static Text" />
+    );
+    // But the prop accepts false in case only part of the helper text
+    // should only be read instead of the whole region.
+    expect(screen.getByText("Static Text")).toHaveAttribute(
+      "aria-atomic",
+      "false"
+    );
+  });
+
+  it("Renders the UI snapshot correctly", () => {
+    const basic = renderer
+      .create(<HelperErrorText id="basic" text="Text" />)
+      .toJSON();
+    const invalid = renderer
+      .create(<HelperErrorText id="invalid" isInvalid text="Text" />)
+      .toJSON();
+    const withHTMLString = renderer
+      .create(
+        <HelperErrorText
+          id="invalid"
+          isInvalid
+          text="This helper text <b>contains HTML in the string</b>."
+        />
+      )
+      .toJSON();
+    const withHTMLElement = renderer
+      .create(
+        <HelperErrorText
+          id="invalid"
+          isInvalid
+          text={
+            <>
+              This helper text <b>contains HTML</b>.
+            </>
+          }
+        />
+      )
+      .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

@@ -0,0 +1,62 @@
+import { Box, chakra, useStyleConfig } from "@chakra-ui/react";
+import * as React from "react";
+
+export type AriaLiveValues = "assertive" | "off" | "polite";
+export type HelperErrorTextType = string | JSX.Element;
+
+interface HelperErrorTextProps {
+  /** 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;
+  /** 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;
+  /** Unique ID for accessibility purposes. */
+  id?: string;
+  /** Toggles between helper and invalid styling. */
+  isInvalid?: boolean;
+  /** The text to display. */
+  text: HelperErrorTextType;
+}
+
+/**
+ * Helper or error text for forms components.
+ */
+export const HelperErrorText = chakra(
+  ({
+    ariaAtomic = true,
+    ariaLive = "polite",
+    className = "",
+    id,
+    isInvalid = false,
+    text,
+    ...rest
+  }: HelperErrorTextProps) => {
+    // Only announce the text in the invalid state.
+    const announceAriaLive = isInvalid;
+    const styles = useStyleConfig("HelperErrorText", { isInvalid });
+    const props = {
+      "aria-atomic": ariaAtomic,
+      "aria-live": announceAriaLive ? ariaLive : "off",
+      className,
+      "data-isinvalid": isInvalid,
+      id,
+      __css: styles,
+      ...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

@@ -0,0 +1,93 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`HelperErrorText Renders the UI snapshot correctly 1`] = `
+<div
+  aria-atomic={true}
+  aria-live="off"
+  className="css-1xdhyk6"
+  dangerouslySetInnerHTML={
+    Object {
+      "__html": "Text",
+    }
+  }
+  data-isinvalid={false}
+  id="basic"
+/>
+`;
+
+exports[`HelperErrorText Renders the UI snapshot correctly 2`] = `
+<div
+  aria-atomic={true}
+  aria-live="polite"
+  className="css-1xdhyk6"
+  dangerouslySetInnerHTML={
+    Object {
+      "__html": "Text",
+    }
+  }
+  data-isinvalid={true}
+  id="invalid"
+/>
+`;
+
+exports[`HelperErrorText Renders the UI snapshot correctly 3`] = `
+<div
+  aria-atomic={true}
+  aria-live="polite"
+  className="css-1xdhyk6"
+  dangerouslySetInnerHTML={
+    Object {
+      "__html": "This helper text <b>contains HTML in the string</b>.",
+    }
+  }
+  data-isinvalid={true}
+  id="invalid"
+/>
+`;
+
+exports[`HelperErrorText Renders the UI snapshot correctly 4`] = `
+<div
+  aria-atomic={true}
+  aria-live="polite"
+  className="css-1xdhyk6"
+  data-isinvalid={true}
+  id="invalid"
+>
+  This helper text 
+  <b>
+    contains HTML
+  </b>
+  .
+</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"
+/>
+`;