Merge pull request #1443 from NYPL/DSD-1610/heading-better-aria

DSD-1610: better aria attributes for Heading overline

CHANGELOG.md

@@ -8,8 +8,18 @@ Currently, this repo is in Prerelease. When it is released, this project will ad
 
 ## Prerelease
 
+### Adds
+
+- Adds a changelog to the story pages for the `Heading` component.
+
+### Updates
+
+- Updates the `Heading` component to set the `aria-roledescription` value as `"subtitle"` (a more familiar and recognizable value) for the `overline` element.
+
 ## 2.1.0 (October 18, 2023)
 
+### Adds
+
 - Adds the `ComponentChangelogTable` component.
 - Adds a changelog to the story pages for the `DatePicker`, `FeedbackBox`, `Hero`, `Slider`, and `TextInput` components.
 - Adds the `FeaturedContent` component.

src/components/FeaturedContent/__snapshots__/FeaturedContent.test.tsx.snap

@@ -33,7 +33,7 @@ exports[`Renders the UI snapshot correctly 1`] = `
           role="group"
         >
           <p
-            aria-roledescription="Overline"
+            aria-roledescription="Subtitle"
             className="chakra-text css-rwceap"
             role="paragraph"
           >
@@ -94,7 +94,7 @@ exports[`Renders the UI snapshot correctly 2`] = `
           role="group"
         >
           <p
-            aria-roledescription="Overline"
+            aria-roledescription="Subtitle"
             className="chakra-text css-rwceap"
             role="paragraph"
           >
@@ -155,7 +155,7 @@ exports[`Renders the UI snapshot correctly 3`] = `
           role="group"
         >
           <p
-            aria-roledescription="Overline"
+            aria-roledescription="Subtitle"
             className="chakra-text css-rwceap"
             role="paragraph"
           >
@@ -216,7 +216,7 @@ exports[`Renders the UI snapshot correctly 4`] = `
           role="group"
         >
           <p
-            aria-roledescription="Overline"
+            aria-roledescription="Subtitle"
             className="chakra-text css-rwceap"
             role="paragraph"
           >
@@ -277,7 +277,7 @@ exports[`Renders the UI snapshot correctly 5`] = `
           role="group"
         >
           <p
-            aria-roledescription="Overline"
+            aria-roledescription="Subtitle"
             className="chakra-text css-rwceap"
             role="paragraph"
           >
@@ -338,7 +338,7 @@ exports[`Renders the UI snapshot correctly 6`] = `
           role="group"
         >
           <p
-            aria-roledescription="Overline"
+            aria-roledescription="Subtitle"
             className="chakra-text css-rwceap"
             role="paragraph"
           >

src/components/Heading/Heading.mdx

@@ -1,16 +1,18 @@
 import { ArgTypes, Canvas, Description, Meta, Source } from "@storybook/blocks";
 
+import ComponentChangelogTable from "../../utils/ComponentChangelogTable";
 import * as HeadingStories from "./Heading.stories";
 import Link from "../Link/Link";
+import { changelogData } from "./headingChangelogData";
 
 <Meta of={HeadingStories} />
 
 # Heading
 
-| Component Version | DS Version |
-| ----------------- | ---------- |
-| Added             | `0.0.4`    |
-| Latest            | `1.7.1`    |
+| Component Version | DS Version   |
+| ----------------- | ------------ |
+| Added             | `0.0.4`      |
+| Latest            | `Prerelease` |
 
 ## Table of Contents
 
@@ -23,6 +25,7 @@ import Link from "../Link/Link";
 - {<Link href="#overline-and-subtitle" target="_self">Overline and Subtitle Elements</Link>}
 - {<Link href="#heading-with-bold-text" target="_self">Heading with Bold Text</Link>}
 - {<Link href="#heading-with-links" target="_self">Heading with Links</Link>}
+- {<Link href="#changelog" target="_self">Changelog</Link>}
 
 ## Overview
 
@@ -56,13 +59,16 @@ proper order and not skipping any. For example, the following is invalid HTML:
 
 When either the overline or subtitle elements are rendered as part of the
 heading, then the whole lockup will be wrapped in an `<hgroup>` element with
-proper `role` and `aria-roledescription` attributes applied.
+proper `role` and `aria-roledescription` attributes applied. Please note that
+both the overline and subtitle elements use `"Subtitle"` - a familiar and
+recognizable term - for the `aria-roledescription` attribute.
 
 <Source
   code={`
 <hgroup role="group" aria-roledescription="Heading group">
+  <p aria-roledescription="Subtitle">Overline</p>
   <h2>Heading Title</h2>
-  <p aria-roledescription="subtitle">Subtitle</p>
+  <p aria-roledescription="Subtitle">Subtitle</p>
 </hgroup>
 `}
   language="html"
@@ -246,3 +252,7 @@ When the `url` prop is passed to `Heading`, a child `<a>` element is created and
 the heading text becomes an active link.
 
 <Canvas of={HeadingStories.Links} />
+
+## Changelog
+
+<ComponentChangelogTable changelogData={changelogData} />

src/components/Heading/Heading.tsx

@@ -276,7 +276,7 @@ export const Heading = chakra(
         <>
           {overline && (
             <Text
-              aria-roledescription="Overline"
+              aria-roledescription="Subtitle"
               mb="xxs"
               role="paragraph"
               size={overlineSize}

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

@@ -96,7 +96,7 @@ exports[`Heading renders the UI snapshot correctly 9`] = `
   role="group"
 >
   <p
-    aria-roledescription="Overline"
+    aria-roledescription="Subtitle"
     className="chakra-text css-rwceap"
     role="paragraph"
   >
@@ -140,7 +140,7 @@ exports[`Heading renders the UI snapshot correctly 11`] = `
   role="group"
 >
   <p
-    aria-roledescription="Overline"
+    aria-roledescription="Subtitle"
     className="chakra-text css-rwceap"
     role="paragraph"
   >

src/components/Heading/headingChangelogData.ts

@@ -0,0 +1,21 @@
+/** This data is used to populate the ComponentChangelogTable component.
+ *
+ * date: string (when adding new entry during development, set value as "Prerelease")
+ * version: string (when adding new entry during development, set value as "Prerelease")
+ * type: "Bug Fix" | "New Feature" | "Update";
+ * affects: array["Accessibility" | "Documentation" | "Functionality" | "Styles"];
+ * notes: array (will render as a bulleted list, add one array element for each list element)
+ */
+import { ChangelogData } from "../../utils/ComponentChangelogTable";
+
+export const changelogData: ChangelogData[] = [
+  {
+    date: "Prerelease",
+    version: "Prerelease",
+    type: "Update",
+    affects: ["Accessibility"],
+    notes: [
+      'Updated the `aria-roledescription` value to "subtitle" (a more familiar and recognizable term) for the `overline` element.',
+    ],
+  },
+];