Fix invalid HTML nesting in ActionList.Heading

.changeset/actionlist-heading-span-fix.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': patch
+---
+
+Fix invalid HTML nesting in `ActionList.Heading` by applying the visually-hidden styles directly to the heading element instead of wrapping it in a `span`.

packages/react/src/ActionList/Heading.test.tsx

@@ -5,6 +5,7 @@ import {ActionList} from '.'
 import {ActionMenu} from '../ActionMenu'
 import {implementsClassName, withExpectedConsoleError} from '../utils/testing'
 import classes from './Heading.module.css'
+import visuallyHiddenClasses from '../_VisuallyHidden.module.css'
 
 describe('ActionList.Heading', () => {
   implementsClassName(
@@ -29,6 +30,41 @@ describe('ActionList.Heading', () => {
     expect(heading).toHaveTextContent('Heading')
   })
 
+  it('should not wrap the heading in a span', async () => {
+    const {getByRole} = HTMLRender(
+      <ActionList>
+        <ActionList.Heading as="h1">Heading</ActionList.Heading>
+      </ActionList>,
+    )
+    const heading = getByRole('heading', {level: 1})
+    expect(heading.parentElement?.tagName).not.toBe('SPAN')
+    expect(heading).toHaveClass(classes.ActionListHeader)
+  })
+
+  it('should apply the visually-hidden class to the heading when visuallyHidden is set', async () => {
+    const {getByRole} = HTMLRender(
+      <ActionList>
+        <ActionList.Heading as="h1" visuallyHidden>
+          Heading
+        </ActionList.Heading>
+      </ActionList>,
+    )
+    const heading = getByRole('heading', {level: 1})
+    expect(heading).toHaveClass(visuallyHiddenClasses.InternalVisuallyHidden)
+    expect(heading).toHaveClass(classes.ActionListHeader)
+  })
+
+  it('should not apply the visually-hidden class to the heading by default', async () => {
+    const {getByRole} = HTMLRender(
+      <ActionList>
+        <ActionList.Heading as="h1">Heading</ActionList.Heading>
+      </ActionList>,
+    )
+    const heading = getByRole('heading', {level: 1})
+    expect(heading).not.toHaveClass(visuallyHiddenClasses.InternalVisuallyHidden)
+    expect(heading).toHaveClass(classes.ActionListHeader)
+  })
+
   it('should label the action list with the heading id', async () => {
     const {container, getByRole} = HTMLRender(
       <ActionList>

packages/react/src/ActionList/Heading.tsx

@@ -3,11 +3,11 @@ import {useMergedRefs} from '../hooks'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import {default as HeadingComponent} from '../Heading'
 import {ListContext} from './shared'
-import VisuallyHidden from '../_VisuallyHidden'
 import {ActionListContainerContext} from './ActionListContainerContext'
 import {invariant} from '../utils/invariant'
 import {clsx} from 'clsx'
 import classes from './Heading.module.css'
+import visuallyHiddenClasses from '../_VisuallyHidden.module.css'
 
 type HeadingLevels = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
 type HeadingVariants = 'large' | 'medium' | 'small'
@@ -33,21 +33,23 @@ export const Heading = forwardRef(({as, size, children, visuallyHidden = false,
   )
 
   return (
-    <VisuallyHidden isVisible={!visuallyHidden}>
-      <HeadingComponent
-        as={as}
-        variant={size}
-        ref={mergedRef}
-        // use custom id if it is provided. Otherwise, use the id from the context
-        id={props.id ?? headingId}
-        className={clsx(className, classes.ActionListHeader)}
-        data-component="ActionList.Heading"
-        data-list-variant={listVariant}
-        {...props}
-      >
-        {children}
-      </HeadingComponent>
-    </VisuallyHidden>
+    <HeadingComponent
+      as={as}
+      variant={size}
+      ref={mergedRef}
+      // use custom id if it is provided. Otherwise, use the id from the context
+      id={props.id ?? headingId}
+      // Apply the visually-hidden styles directly to the heading rather than wrapping
+      // it in a span (a heading isn't valid phrasing content inside a span).
+      className={clsx(className, classes.ActionListHeader, {
+        [visuallyHiddenClasses.InternalVisuallyHidden]: visuallyHidden,
+      })}
+      data-component="ActionList.Heading"
+      data-list-variant={listVariant}
+      {...props}
+    >
+      {children}
+    </HeadingComponent>
   )
 }) as PolymorphicForwardRefComponent<HeadingLevels, ActionListHeadingProps>