Add visually-hidden text to headers of ComparisonTable feature columns (

#695) * add visually-hidden featured indicator to header of featured ComparisonTable columns * add changeset * add featuredColumnAccessibleLabel prop * update changeset * enfoce parens in featuredColumnAccessibleLabel * rename visuallyHiddenFeaturedLabel to featuredColumnAccessibleLabel * remove rogue code block tag * add missing quotes
primer · Aug 14, 2024 · 2bb68ea · 2bb68ea
1 parent 826932a
commit 2bb68ea
Show file tree

Hide file tree

Showing 3 changed files with 18 additions and 7 deletions.
diff --git a/.changeset/cuddly-beds-speak.md b/.changeset/cuddly-beds-speak.md
@@ -0,0 +1,5 @@
+---
+'@primer/react-brand': patch
+---
+
+`ComparisonTable` featured columns now identify themselves to screen readers by appending the text `featured` to the column title. This text can be customized using the `visuallyHiddenFeaturedLabel` prop.
diff --git a/apps/docs/content/components/ComparisonTable.mdx b/apps/docs/content/components/ComparisonTable.mdx
@@ -124,6 +124,8 @@ For granular control over heading markup or appearance, we recommend using [`Hea
 
 By default, the first data column will be marked as `featured`. This is to draw attention to a particular product as the basis of a comparison against adjacent columns.
 
+Featured columns will have the visually-hidden text `featured` appended to their column title. This text is used to identify the featured column to screen reader users and can be customized using the `visuallyHiddenFeaturedLabel` prop.
+
 Use `featuredColumn` to alternate the highlighted column if needed.
 
 #### Color customization
@@ -356,12 +358,13 @@ This variant is suitable for embedding into long-form content, or in situations
 
 ### ComparisonTable <Label>Required</Label>
 
-| name             | type                                                                                    | default     | required | description                                                                                                                                               |
-| ---------------- | --------------------------------------------------------------------------------------- | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `children`       | `ComparisonTable.Row`, `ComparisonTable.Cell`, `ComparisonTable.Footnotes`, `ReactNode` | undefined   | `true`   | Valid children. Accepts `ReactNode` for conditional rendering.                                                                                            |
-| `heading`        | `string`                                                                                | undefined   | `false`  | Optional heading that appears above table, preconfigured as a `h3`.                                                                                       |
-| `featuredColumn` | `number`                                                                                | `1`         | `false`  | Indicates that the data column at the specified index is visually important and unique in relation to its adjacent cells, and will be styled accordingly. |
-| `variant`        | `"default"`, `"minimal"`                                                                | `"default"` | `false`  | Applies alternative presentation.                                                                                                                         |
+| name                          | type                                                                                    | default      | required | description                                                                                                                                               |
+| ----------------------------- | --------------------------------------------------------------------------------------- | ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children`                    | `ComparisonTable.Row`, `ComparisonTable.Cell`, `ComparisonTable.Footnotes`, `ReactNode` | undefined    | `true`   | Valid children. Accepts `ReactNode` for conditional rendering.                                                                                            |
+| `heading`                     | `string`                                                                                | undefined    | `false`  | Optional heading that appears above table, preconfigured as a `h3`.                                                                                       |
+| `featuredColumn`              | `number`                                                                                | `1`          | `false`  | Indicates that the data column at the specified index is visually important and unique in relation to its adjacent cells, and will be styled accordingly. |
+| `visuallyHiddenFeaturedLabel` | `string`                                                                                | `"featured"` | `false`  | A visually-hidden label which is appended to the end of the column title. Used to identify the featured column to screen reader users.                    |
+| `variant`                     | `"default"`, `"minimal"`                                                                | `"default"`  | `false`  | Applies alternative presentation.                                                                                                                         |
 
 ### ComparisonTable.Row <Label>Required</Label>
 

diff --git a/packages/react/src/ComparisonTable/ComparisonTable.tsx b/packages/react/src/ComparisonTable/ComparisonTable.tsx
@@ -29,6 +29,7 @@ export const _ComparisonTable = forwardRef(
       className,
       heading,
       featuredColumn = 1,
+      visuallyHiddenFeaturedLabel = 'featured',
       variant = 'default',
       style,
       ...props
@@ -54,6 +55,7 @@ export const _ComparisonTable = forwardRef(
             className: clsx(styles['ComparisonTable-row'], child.props.className),
             children: React.Children.map(child.props.children, (rowChild, rowChildIndex) => {
               if (rowChild.type === Cell) {
+                const isFeatured = rowChildIndex === featuredColumn
                 return React.cloneElement(rowChild, {
                   as: 'th',
                   'aria-hidden': !rowChild.props.children ? 'true' : undefined,
@@ -62,7 +64,7 @@ export const _ComparisonTable = forwardRef(
                     styles[`ComparisonTable-cell-heading`],
                     styles[`ComparisonTable-cell-heading--${variant}`],
                     rowChildIndex === 0 && styles[`ComparisonTable-cell-heading--first`],
-                    rowChildIndex === featuredColumn && styles[`ComparisonTable-cell-heading--featured`],
+                    isFeatured && styles[`ComparisonTable-cell-heading--featured`],
                     child.props.className,
                   ),
                   children: (
@@ -72,6 +74,7 @@ export const _ComparisonTable = forwardRef(
                       )}
                     >
                       {rowChild.props.children}
+                      {isFeatured && <span className="visually-hidden">({visuallyHiddenFeaturedLabel})</span>}
                     </span>
                   ),
                 })