Add descriptive labels to Footnote return links

.changeset/lucky-socks-carry.md

@@ -0,0 +1,5 @@
+---
+'@primer/react-brand': patch
+---
+
+Added descriptive labels to `Footnote` return links for an improved screen-reader experience. Return links will now be read aloud as "Back to content {Link label}"

packages/react/src/Footnotes/Footnotes.test.tsx

@@ -4,6 +4,7 @@ import '@testing-library/jest-dom'
 import {axe, toHaveNoViolations} from 'jest-axe'
 
 import {Footnotes} from './Footnotes'
+import {InlineLink} from '../InlineLink'
 import '../test-utils/mocks/match-media-mock'
 
 expect.extend(toHaveNoViolations)
@@ -89,18 +90,35 @@ describe('Footnotes', () => {
     const mockHref = 'https://github.com'
     const {getByText, getByRole} = render(
       <Footnotes>
-        <Footnotes.Item href={mockHref}>{mockItemText} </Footnotes.Item>
+        <Footnotes.Item href={mockHref}>{mockItemText}</Footnotes.Item>
       </Footnotes>,
     )
 
     const itemEl = getByText(mockItemText)
     expect(itemEl).toBeInTheDocument()
 
-    const backLink = getByRole('link', {name: 'Back to content'})
+    const backLink = getByRole('link', {name: `Back to content ${mockItemText}`})
     expect(backLink).toBeInTheDocument()
     expect(backLink).toHaveAttribute('href', mockHref)
 
     const iconEl = backLink.querySelector('svg')
     expect(iconEl).toBeInTheDocument()
   })
+
+  it('extracts text content from nested children for aria-label', async () => {
+    const mockHref = 'https://github.com'
+    const {getByRole} = render(
+      <Footnotes>
+        <Footnotes.Item href={mockHref}>
+          This factor is based on data from the industry&apos;s{' '}
+          <InlineLink href="#">longest running analysis</InlineLink> by Acme Corp.
+        </Footnotes.Item>
+      </Footnotes>,
+    )
+
+    const backLink = getByRole('link', {
+      name: "Back to content This factor is based on data from the industry's longest running analysis by Acme Corp.",
+    })
+    expect(backLink).toBeInTheDocument()
+  })
 })

packages/react/src/Footnotes/Footnotes.tsx

@@ -7,6 +7,7 @@ import type {BaseProps} from '../component-helpers'
 
 /** * Main Stylesheet (as a CSS Module) */
 import styles from './Footnotes.module.css'
+import {getTextContent} from '../utils/getTextContent'
 
 export const FootnotesTags = ['div', 'ol'] as const
 
@@ -92,7 +93,7 @@ function Item({className, children, _variant = 'citation', ...rest}: FootnotesIt
       <Text as="p" variant="muted" size="100" className={clsx(styles.FootnotesItem__citationText)}>
         {children}
         {href && (
-          <InlineLink href={href} aria-label="Back to content">
+          <InlineLink href={href} aria-label={`Back to content ${getTextContent(children)}`}>
             <ReplyIcon className={styles.FootnotesItem__citationIcon} />
           </InlineLink>
         )}

packages/react/src/utils/getTextContent.ts

@@ -0,0 +1,20 @@
+import React from 'react'
+
+export function getTextContent(node: React.ReactNode): string {
+  if (!node) return ''
+
+  if (typeof node === 'string' || typeof node === 'number') {
+    return String(node)
+  }
+
+  if (Array.isArray(node)) {
+    return node.map(getTextContent).join('')
+  }
+
+  if (React.isValidElement(node)) {
+    const props = node.props as {children?: React.ReactNode}
+    return getTextContent(props.children)
+  }
+
+  return ''
+}