From 34a347f047bf51dacdb231a3ef5ebb292e07e9c0 Mon Sep 17 00:00:00 2001
From: Mathilde Buenerd <mathilde.buenerd@shopify.com>
Date: Wed, 28 Jul 2021 11:50:42 +0200
Subject: [PATCH] Navigation: add ariaLabel and ariaLabelledBy props in order
 to add accessibility labels to the nav

---
 UNRELEASED.md                                 |  1 +
 src/components/Navigation/Navigation.tsx      |  5 ++-
 src/components/Navigation/README.md           | 32 +++++++++++++++++++
 .../Navigation/tests/Navigation.test.tsx      | 10 ++++++
 4 files changed, 47 insertions(+), 1 deletion(-)

diff --git a/UNRELEASED.md b/UNRELEASED.md
index 0b9c30dd843..9bf124c61aa 100644
--- a/UNRELEASED.md
+++ b/UNRELEASED.md
@@ -8,6 +8,7 @@ Use [the changelog guidelines](https://git.io/polaris-changelog-guidelines) to f
 
 - Added `id` prop to `Layout` and `Heading` for hash linking ([#4307](https://github.com/Shopify/polaris-react/pull/4307))
 - Added `external` prop to `Navigation.Item` component ([#4310](https://github.com/Shopify/polaris-react/pull/4310))
+- Added `ariaLabelledBy` props to `Navigation` component to allow a hidden label for accessibility ([#4343](https://github.com/Shopify/polaris-react/pull/4343))
 
 ### Bug fixes
 
diff --git a/src/components/Navigation/Navigation.tsx b/src/components/Navigation/Navigation.tsx
index 5b1076d50fd..5053993e7f0 100644
--- a/src/components/Navigation/Navigation.tsx
+++ b/src/components/Navigation/Navigation.tsx
@@ -16,6 +16,8 @@ export interface NavigationProps {
   children?: React.ReactNode;
   contextControl?: React.ReactNode;
   onDismiss?(): void;
+  /** id of the element used as aria-labelledby */
+  ariaLabelledBy?: string;
 }
 
 export const Navigation: React.FunctionComponent<NavigationProps> & {
@@ -26,6 +28,7 @@ export const Navigation: React.FunctionComponent<NavigationProps> & {
   contextControl,
   location,
   onDismiss,
+  ariaLabelledBy,
 }: NavigationProps) {
   const {logo} = useTheme();
   const width = getWidth(logo, 104);
@@ -61,7 +64,7 @@ export const Navigation: React.FunctionComponent<NavigationProps> & {
   return (
     <NavigationContext.Provider value={context}>
       <WithinContentContext.Provider value>
-        <nav className={styles.Navigation}>
+        <nav className={styles.Navigation} aria-labelledby={ariaLabelledBy}>
           {mediaMarkup}
           <Scrollable className={styles.PrimaryNavigation}>
             {children}
diff --git a/src/components/Navigation/README.md b/src/components/Navigation/README.md
index f95ebad147c..097d90c8340 100644
--- a/src/components/Navigation/README.md
+++ b/src/components/Navigation/README.md
@@ -518,6 +518,38 @@ This example showcases the many elements that can compose a navigation, especial
 </Navigation>
 ```
 
+### Navigation with aria-labelledby
+
+This example shows how to add an aria-labelledby to add a hidden label to the `nav` element.
+
+```jsx
+<Navigation location="/" ariaLabelledBy="label-id">
+  <VisuallyHidden>
+    <p id="label-id">Hidden label</p>
+  </VisuallyHidden>
+  <Navigation.Section
+    items={[
+      {
+        url: '/path/to/place',
+        label: 'Home',
+        icon: HomeMajor,
+      },
+      {
+        url: '/path/to/place',
+        label: 'Orders',
+        icon: OrdersMajor,
+        badge: '15',
+      },
+      {
+        url: '/path/to/place',
+        label: 'Products',
+        icon: ProductsMajor,
+      },
+    ]}
+  />
+</Navigation>
+```
+
 ---
 
 ## Related components
diff --git a/src/components/Navigation/tests/Navigation.test.tsx b/src/components/Navigation/tests/Navigation.test.tsx
index 1e853b3d4f4..220df981032 100644
--- a/src/components/Navigation/tests/Navigation.test.tsx
+++ b/src/components/Navigation/tests/Navigation.test.tsx
@@ -21,6 +21,16 @@ describe('<Navigation />', () => {
     expect(navigation).toContainReactComponent(Image);
   });
 
+  it('renders nav with aria-labelledby when passed as prop', () => {
+    const label = 'label-id';
+    const navigation = mountWithApp(
+      <Navigation location="/" ariaLabelledBy={label} />,
+    );
+    expect(navigation).toContainReactComponent('nav', {
+      'aria-labelledby': label,
+    });
+  });
+
   describe('context', () => {
     it('passes location context', () => {
       const Child: React.SFC = (_props) => {