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

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"
+/>
+`;

package/src/components/Hero/Hero.stories.mdx

@@ -63,7 +63,17 @@ const imageSrc = "https://placeimg.com/800/400/animals";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.2.0`    |
-| Latest            | `0.25.13`  |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [All Variations](#all-variations)
+- [Color Variations for Secondary Hero](#color-variations-for-secondary-hero)
+
+## Overview
 
 <Description of={Hero} />
 
@@ -71,6 +81,8 @@ The `Hero` component is used to display a full width banner at the top of a page
 The `Hero` will contain a required `h1` page title and may also include optional
 descriptive text and images.
 
+## Component Props
+
 <Canvas withToolbar>
   <Story
     name="Hero with Controls"
@@ -150,101 +162,12 @@ descriptive text and images.
 
 <ArgsTable story="Hero with Controls" />
 
-## Color Variations for Secondary Hero
-
-The background color for the title bar in "Secondary" types changes based on
-variants for the `Secondary` main variant. Before, components relied on the
-parent wrapper's CSS class name for background color updates. Now, the proper
-`HeroType` must be passed in.
+## Accessibility
 
-```jsx
-// Before
-<div className="nypl--books-and-more">
-  <Hero {...props} />
-</div>
-
-// Now
-<Hero heroType={HeroTypes.SecondaryBooksAndMore} {...props} />
-```
-
-<Canvas>
-  <Story name="Color Variations for Secondary Hero">
-    <VStack spacing={10} align="stretch">
-      <Heading
-        id="books-heading"
-        level={HeadingLevels.Two}
-        text="HeroTypes.SecondaryBooksAndMore"
-      />
-      <Hero
-        heading={
-          <Heading
-            level={HeadingLevels.One}
-            id="books-hero"
-            text="Books and More"
-          />
-        }
-        heroType={HeroTypes.SecondaryBooksAndMore}
-        imageAlt={imageAlt}
-        imageSrc={imageSrc}
-        subHeaderText={secondarySubHeaderText}
-      />
-      <Heading
-        id="location-heading"
-        level={HeadingLevels.Two}
-        text="HeroTypes.SecondaryLocations"
-      />
-      <Hero
-        heading={
-          <Heading
-            level={HeadingLevels.One}
-            id="locations-hero"
-            text="Locations"
-          />
-        }
-        heroType={HeroTypes.SecondaryLocations}
-        imageAlt={imageAlt}
-        imageSrc={imageSrc}
-        subHeaderText={secondarySubHeaderText}
-      />
-      <Heading
-        id="research-heading"
-        level={HeadingLevels.Two}
-        text="HeroTypes.SecondaryResearch"
-      />
-      <Hero
-        heading={
-          <Heading
-            level={HeadingLevels.One}
-            id="research-hero"
-            text="Research"
-          />
-        }
-        heroType={HeroTypes.SecondaryResearch}
-        imageAlt={imageAlt}
-        imageSrc={imageSrc}
-        subHeaderText={secondarySubHeaderText}
-      />
-      <Heading
-        id="whats-on-heading"
-        level={HeadingLevels.Two}
-        text="HeroTypes.SecondaryWhatsOn"
-      />
-      <Hero
-        heading={
-          <Heading
-            level={HeadingLevels.One}
-            id="whats-on-hero"
-            text="What's On"
-          />
-        }
-        heroType={HeroTypes.SecondaryWhatsOn}
-        imageAlt={imageAlt}
-        imageSrc={imageSrc}
-        subHeaderText={secondarySubHeaderText}
-      />
-    </VStack>
-  </Story>
-</Canvas>
+The `Hero` component is commonly used as a banner below the page's header and
+breadcrumbs and above the main content. This means that if the `Hero` displays
+a heading element, it should be the first on the page and an `h1` element set
+through `Heading`'s `level={HeadingLevels.One}`.
 
 ## All Variations
 
@@ -343,3 +266,110 @@ parent wrapper's CSS class name for background color updates. Now, the proper
     </VStack>
   </DSProvider>
 </Canvas>
+
+## Color Variations for Secondary Hero
+
+The background color for the title bar in the "Secondary" `Hero` changes based
+on the `HeroTypes` variants for the `Secondary` main variant.
+
+```jsx
+// Example `HeroTypes` "Secondary" variant.
+<Hero heroType={HeroTypes.SecondaryBooksAndMore} {...props} />
+```
+
+<Canvas>
+  <Story name="Color Variations for Secondary Hero">
+    <VStack spacing={10} align="stretch">
+      <Heading
+        id="main-secondary-heading"
+        level={HeadingLevels.Two}
+        text="HeroTypes.Secondary"
+      />
+      <Hero
+        heading={
+          <Heading
+            level={HeadingLevels.One}
+            id="main-secondary-hero"
+            text="Secondary"
+          />
+        }
+        heroType={HeroTypes.Secondary}
+        imageAlt={imageAlt}
+        imageSrc={imageSrc}
+        subHeaderText={secondarySubHeaderText}
+      />
+      <Heading
+        id="books-heading"
+        level={HeadingLevels.Two}
+        text="HeroTypes.SecondaryBooksAndMore"
+      />
+      <Hero
+        heading={
+          <Heading
+            level={HeadingLevels.One}
+            id="books-hero"
+            text="Books and More"
+          />
+        }
+        heroType={HeroTypes.SecondaryBooksAndMore}
+        imageAlt={imageAlt}
+        imageSrc={imageSrc}
+        subHeaderText={secondarySubHeaderText}
+      />
+      <Heading
+        id="location-heading"
+        level={HeadingLevels.Two}
+        text="HeroTypes.SecondaryLocations"
+      />
+      <Hero
+        heading={
+          <Heading
+            level={HeadingLevels.One}
+            id="locations-hero"
+            text="Locations"
+          />
+        }
+        heroType={HeroTypes.SecondaryLocations}
+        imageAlt={imageAlt}
+        imageSrc={imageSrc}
+        subHeaderText={secondarySubHeaderText}
+      />
+      <Heading
+        id="research-heading"
+        level={HeadingLevels.Two}
+        text="HeroTypes.SecondaryResearch"
+      />
+      <Hero
+        heading={
+          <Heading
+            level={HeadingLevels.One}
+            id="research-hero"
+            text="Research"
+          />
+        }
+        heroType={HeroTypes.SecondaryResearch}
+        imageAlt={imageAlt}
+        imageSrc={imageSrc}
+        subHeaderText={secondarySubHeaderText}
+      />
+      <Heading
+        id="whats-on-heading"
+        level={HeadingLevels.Two}
+        text="HeroTypes.SecondaryWhatsOn"
+      />
+      <Hero
+        heading={
+          <Heading
+            level={HeadingLevels.One}
+            id="whats-on-hero"
+            text="What's On"
+          />
+        }
+        heroType={HeroTypes.SecondaryWhatsOn}
+        imageAlt={imageAlt}
+        imageSrc={imageSrc}
+        subHeaderText={secondarySubHeaderText}
+      />
+    </VStack>
+  </Story>
+</Canvas>

package/src/components/Hero/Hero.test.tsx

@@ -680,6 +680,37 @@ describe("Hero", () => {
         />
       )
       .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <Hero
+          heroType={HeroTypes.Primary}
+          heading={
+            <Heading
+              level={HeadingLevels.One}
+              id="chakra"
+              text="Hero Primary"
+            />
+          }
+          subHeaderText="Example Subtitle"
+          backgroundImageSrc="https://placeimg.com/1600/800/arch"
+          p="20px"
+          color="ui.error.primary"
+        />
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(
+        <Hero
+          heroType={HeroTypes.Primary}
+          heading={
+            <Heading level={HeadingLevels.One} id="props" text="Hero Primary" />
+          }
+          subHeaderText="Example Subtitle"
+          backgroundImageSrc="https://placeimg.com/1600/800/arch"
+          data-testid="props"
+        />
+      )
+      .toJSON();
 
     expect(primary).toMatchSnapshot();
     expect(secondary).toMatchSnapshot();
@@ -690,5 +721,7 @@ describe("Hero", () => {
     expect(tertiary).toMatchSnapshot();
     expect(campaign).toMatchSnapshot();
     expect(fiftyFifty).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
   });
 });