From 3b315c1eef5d13246d27247cb7b8a3634a82637d Mon Sep 17 00:00:00 2001
From: Armagan Ersoz <broccolinisoup@github.com>
Date: Mon, 13 Feb 2023 15:45:34 +1000
Subject: [PATCH] a11y remediations

---
 src/PageHeader/PageHeader.tsx       | 37 +++++++++++++++++++----------
 src/PageHeader/features.stories.tsx | 22 +++++++++++++++++
 2 files changed, 47 insertions(+), 12 deletions(-)

diff --git a/src/PageHeader/PageHeader.tsx b/src/PageHeader/PageHeader.tsx
index 7dba207d30a..a0b3f32c026 100644
--- a/src/PageHeader/PageHeader.tsx
+++ b/src/PageHeader/PageHeader.tsx
@@ -99,17 +99,7 @@ type LinkProps = Pick<
 export type ParentLinkProps = React.PropsWithChildren<PageHeaderProps & LinkProps>
 
 const ParentLink = React.forwardRef<HTMLAnchorElement, ParentLinkProps>(
-  (
-    {
-      children,
-      sx = {},
-      href,
-      'aria-label': ariaLabel = `Back to ${children}`,
-      as = 'a',
-      hidden = hiddenOnRegularAndWide,
-    },
-    ref,
-  ) => {
+  ({children, sx = {}, href, 'aria-label': ariaLabel, as = 'a', hidden = hiddenOnRegularAndWide}, ref) => {
     return (
       <>
         <Link
@@ -435,10 +425,33 @@ const Description: React.FC<React.PropsWithChildren<PageHeaderProps>> = ({childr
   )
 }
 
+export type NavigationProps = {
+  as?: 'nav' | 'div'
+  'aria-label'?: React.AriaAttributes['aria-label']
+  'aria-labelledby'?: React.AriaAttributes['aria-labelledby']
+} & PageHeaderProps
+
 // PageHeader.Navigation: The local navigation area of the header. Visible on all viewports
-const Navigation: React.FC<React.PropsWithChildren<PageHeaderProps>> = ({children, sx = {}, hidden = false}) => {
+const Navigation: React.FC<React.PropsWithChildren<NavigationProps>> = ({
+  children,
+  sx = {},
+  hidden = false,
+  as,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
+}) => {
+  if (as === 'nav' && !ariaLabel && !ariaLabelledBy) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      'Use `aria-label` or `aria-labelledby` prop to provide an accessible label to the `nav` landmark for assistive technology',
+    )
+  }
   return (
     <Box
+      as={as}
+      // Render `aria-label` and `aria-labelledby` only on `nav` elements
+      aria-label={as === 'nav' ? ariaLabel : undefined}
+      aria-labelledby={as === 'nav' ? ariaLabelledBy : undefined}
       sx={merge<BetterSystemStyleObject>(
         {
           display: 'flex',
diff --git a/src/PageHeader/features.stories.tsx b/src/PageHeader/features.stories.tsx
index 260945d71c4..bc177a86879 100644
--- a/src/PageHeader/features.stories.tsx
+++ b/src/PageHeader/features.stories.tsx
@@ -147,6 +147,28 @@ export const WithNavigationSlot = () => (
   </Box>
 )
 
+export const WithCustomNavigation = () => (
+  <Box sx={{padding: 3}}>
+    <PageHeader>
+      <PageHeader.TitleArea>
+        <PageHeader.Title>Pull request title</PageHeader.Title>
+      </PageHeader.TitleArea>
+      <PageHeader.Navigation as="nav" aria-label="Item list">
+        <ul>
+          <li>
+            <Link href="#" aria-current="page">
+              Item 1
+            </Link>
+          </li>
+          <li>
+            <Link href="#">Item 2</Link>
+          </li>
+        </ul>
+      </PageHeader.Navigation>
+    </PageHeader>
+  </Box>
+)
+
 export const WithLeadingAndTrailingActions = () => (
   <Box sx={{padding: 3}}>
     <PageHeader>