Merge pull request #728 from City-of-Helsinki/feature/navigation-aria…

…-labels

Feature/navigation aria labels

new-site/src/components/layout.js

@@ -191,7 +191,7 @@ const Layout = ({ children, pageContext }) => {
           skipTo={`#${contentId}`}
           skipToContentLabel="Skip to content"
         >
-          <Navigation.Row>
+          <Navigation.Row ariaLabel="Site navigation">
             {uiMenuLinks.map(({ name, link, uiId }) => (
               <Navigation.Item
                 active={withPrefix(currentMenuItem?.link || '') === withPrefix(link)}
@@ -210,6 +210,7 @@ const Layout = ({ children, pageContext }) => {
                 defaultOpenMainLevels={[...Array(uiSubMenuLinks.length).keys()]}
                 id="side-navigation"
                 toggleButtonLabel="Navigate to page"
+                ariaLabel={`${currentMenuItem.name}`}
               >
                 {uiSubMenuLinks.map(({ name, link, prefixedLink, uiId, withDivider, subLevels }) => {
                   const hasSubLevels = subLevels.length > 0;

new-site/src/docs/components/navigation/accessibility.mdx

@@ -12,3 +12,4 @@ export default ({ children, pageContext }) => <TabsLayout pageContext={pageConte
 ### Pay attention to
 - HDS Navigation is designed to support many different brand colours. When customising colours, refer to [colour guidelines](/foundation/design-tokens/colour "Colour") to ensure accessibility.
 - **When designing a menu link hierarchy, always think about keyboard and screen reader users.** First, make sure top-level menu labels are clear, and submenu items contextually fit under it. Next, make sure the menu option order is logical and reasonable. Remember that keyboard users need to manually navigate to each element and thus placing a commonly used menu option last is not optimal.
+- If there are multiple navigational components on the page, they should have individual aria-labels. This helps screen reader users to distinguish them from each other. The NavigationRow component has an ariaLabel property for that purpose.

new-site/src/docs/components/navigation/code.mdx

@@ -143,9 +143,10 @@ Note! You can find the full list of properties in the <Link size="M" href="/stor
 | `titleUrl`               | URL to navigate to when the logo or title is clicked.                                      | `string`               | -             |
 [Table 1:Navigation properties]|
 
-| Property              | Description                                                                                | Values                                     | Default value |
-| --------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------ | ------------- |
-| `variant`             | Defines where the navigation row will be displayed.                                        | `"default"`, `"inline"`,                   | `"default"`   |
+| Property              | Description                                                                                                       | Values                                     | Default value |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------- |
+| `variant`             | Defines where the navigation row will be displayed.                                                               | `"default"`, `"inline"`,                   | `"default"`   |
+| `ariaLabel`           | The aria-label for helping screen reader users to distinguish navigation row from other navigational components   | `string`                                   | -             |
 [Table 2:NavigationRow properties]|
 
 | Property  | Description                                                                                          | Values                                        | Default value |

new-site/src/docs/components/side-navigation/accessibility.mdx

@@ -12,3 +12,4 @@ export default ({ children, pageContext }) => <TabsLayout pageContext={pageConte
 ### Pay attention to
 - **When designing a menu link hierarchy, always think about keyboard and screen reader users.** First, make sure top-level menu labels are clear, and submenu items contextually fit under the top-level. Next, make sure the menu option order is logical and reasonable. Remember that keyboard users need to manually navigate to each element and thus placing a commonly used menu option last is not optimal.
 - If you are using both the main (top) and the side navigation, it is a good practice to include an anchor link to the side navigation at the beginning of the main (top) navigation. This way assistive technologies can easily access the side navigation after a page load.
+- If there are multiple navigational components on the page, they should have individual aria-labels. This helps screen reader users to distinguish them from each other. The SideNavigation component has an ariaLabel property for that purpose.

new-site/src/docs/components/side-navigation/code.mdx

@@ -238,8 +238,9 @@ export default ({ children, pageContext }) => <TabsLayout pageContext={pageConte
 Note! You can find the full list of properties in the <Link size="M" href="/storybook/react/?path=/docs/components-sidenavigation--default" external>React Storybook.</Link>
 
 
-| Property                | Description                                 | Values     | Default value |
-| ----------------------- | ------------------------------------------- | ---------- | ------------- |
-| `defaultOpenMainLevels` | Default value for open main levels.         | `number[]` | \[]           |
-| `toggleButtonLabel`     | The label for the mobile menu toggle button | `string`   | -             |
+| Property                | Description                                                                                                      | Values     | Default value |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------- | ------------- |
+| `defaultOpenMainLevels` | Default value for open main levels.                                                                              | `number[]` | \[]           |
+| `toggleButtonLabel`     | The label for the mobile menu toggle button                                                                      | `string`   | -             |
+| `ariaLabel`             | The aria-label for helping screen reader users to distinguish navigation row from other navigational components  | `string`   | -             |
 [Table 1:SideNavigation properties]|

packages/react/src/components/navigation/Navigation.stories.tsx

@@ -52,7 +52,7 @@ export const Default = ({ searchLabel, searchPlaceholder, authenticated, userNam
   // @ts-ignore
   <Navigation {...args}>
     {/* NAVIGATION ROW */}
-    <Navigation.Row>
+    <Navigation.Row ariaLabel="Main navigation">
       <Navigation.Item href="#" label="Link" active onClick={(e) => e.preventDefault()} />
       <Navigation.Item href="#" label="Link" onClick={(e) => e.preventDefault()} />
       <Navigation.Item href="#" label="Link" onClick={(e) => e.preventDefault()} />

packages/react/src/components/navigation/navigationRow/NavigationRow.test.tsx

@@ -7,11 +7,12 @@ import { NavigationWrapper } from '../../../utils/test-utils';
 
 describe('<Navigation.Row /> spec', () => {
   it('renders the component', () => {
-    const { asFragment } = render(<NavigationRow />, { wrapper: NavigationWrapper });
+    const { asFragment } = render(<NavigationRow ariaLabel="Main navigation" />, { wrapper: NavigationWrapper });
     expect(asFragment()).toMatchSnapshot();
   });
+
   it('should not have basic accessibility issues', async () => {
-    const { container } = render(<NavigationRow />, { wrapper: NavigationWrapper });
+    const { container } = render(<NavigationRow ariaLabel="Main navigation" />, { wrapper: NavigationWrapper });
     const results = await axe(container);
     expect(results).toHaveNoViolations();
   });

packages/react/src/components/navigation/navigationRow/NavigationRow.tsx

@@ -17,9 +17,13 @@ export type NavigationRowProps = React.PropsWithChildren<{
    * `inline` - items will be displayed in the header
    */
   variant?: NavigationVariant;
+  /**
+   * aria-label for helping screen reader users to distinguish navigation row from other navigational components
+   */
+  ariaLabel?: string;
 }>;
 
-export const NavigationRow = ({ variant = 'default', children }: NavigationRowProps) => {
+export const NavigationRow = ({ variant = 'default', ariaLabel, children }: NavigationRowProps) => {
   const { setNavigationVariant } = useContext(NavigationContext);
 
   useEffect(() => setNavigationVariant(variant), [setNavigationVariant, variant]);
@@ -43,7 +47,9 @@ export const NavigationRow = ({ variant = 'default', children }: NavigationRowPr
   });
 
   return (
-    <nav className={classNames(styles.navigation, variant === 'default' && styles.subNav)}>{childrenWithClassName}</nav>
+    <nav className={classNames(styles.navigation, variant === 'default' && styles.subNav)} aria-label={ariaLabel}>
+      {childrenWithClassName}
+    </nav>
   );
 };
 NavigationRow.componentName = 'NavigationRow';

packages/react/src/components/navigation/navigationRow/__snapshots__/NavigationRow.test.tsx.snap

@@ -114,6 +114,7 @@ exports[`<Navigation.Row /> spec renders the component 1`] = `
         </div>
       </div>
       <nav
+        aria-label="Main navigation"
         class="navigation subNav"
       />
     </div>

packages/react/src/components/sideNavigation/SideNavigation.stories.tsx

@@ -48,7 +48,7 @@ export const Default = (args) => {
       </style>
       <div className="example-page">
         <div className="example-page-side-navigation">
-          <SideNavigation {...args}>
+          <SideNavigation ariaLabel="Getting started" {...args}>
             <SideNavigation.MainLevel id="main-level-link-1" label="Main level accordion">
               <SideNavigation.SubLevel
                 active={active === '/sub-level-1'}

packages/react/src/components/sideNavigation/SideNavigation.test.tsx

@@ -18,7 +18,7 @@ const url = '#';
 
 const renderSideNavigation = () =>
   render(
-    <SideNavigation id="sideNavigation" toggleButtonLabel={labels.toggleButton}>
+    <SideNavigation id="sideNavigation" toggleButtonLabel={labels.toggleButton} ariaLabel="Side navigation">
       <SideNavigation.MainLevel id="mainLevel1" icon={<IconHome />} label={labels.mainLevel1}>
         <SideNavigation.SubLevel id="subLevel1" active href={url} label={labels.subLevel1} />
       </SideNavigation.MainLevel>

packages/react/src/components/sideNavigation/SideNavigation.tsx

@@ -44,6 +44,10 @@ export type SideNavigationProps = React.PropsWithChildren<{
    * The id of the side navigation.
    */
   id: string;
+  /**
+   * aria-label for helping screen reader users to distinguish SideNavigation from other navigational components
+   */
+  ariaLabel?: string;
   /**
    * Override or extend the styles applied to the component
    */
@@ -63,6 +67,7 @@ export const SideNavigation = ({
   className,
   defaultOpenMainLevels = [],
   id,
+  ariaLabel,
   style,
   theme,
   toggleButtonLabel,
@@ -127,6 +132,7 @@ export const SideNavigation = ({
       <nav
         className={classNames(styles.sideNavigation, customThemeClass, className)}
         id={id}
+        aria-label={ariaLabel}
         ref={container}
         style={style}
       >

packages/react/src/components/sideNavigation/__snapshots__/SideNavigation.test.tsx.snap

@@ -3,6 +3,7 @@
 exports[`<SideNavigation /> spec renders the component 1`] = `
 <DocumentFragment>
   <nav
+    aria-label="Side navigation"
     class="sideNavigation"
     id="sideNavigation"
   >

site/docs/components/navigation.mdx

@@ -34,6 +34,7 @@ import LargeParagraph from "../../src/components/LargeParagraph";
 
 - HDS Navigation is designed to support many different brand colours. When customising colours, refer to [colour guidelines](/design-tokens/colour "Colour") to ensure accessibility.
 - **When designing a menu link hierarchy, always think about keyboard and screen reader users.** First, make sure top-level menu labels are clear, and submenu items contextually fit under it. Next, make sure the menu option order is logical and reasonable. Remember that keyboard users need to manually navigate to each element and thus placing a commonly used menu option last is not optimal.
+- If there are multiple navigational components on the page, they should have individual aria-labels. This helps screen reader users to distinguish them from each other. The NavigationRow component has an ariaLabel property for that purpose.
 
 ## Usage and variations
 

site/docs/components/side_navigation.mdx

@@ -47,6 +47,7 @@ import Link from "../../src/components/Link";
 ## Accessibility
 - **When designing a menu link hierarchy, always think about keyboard and screen reader users.** First, make sure top-level menu labels are clear, and submenu items contextually fit under the top-level. Next, make sure the menu option order is logical and reasonable. Remember that keyboard users need to manually navigate to each element and thus placing a commonly used menu option last is not optimal.
 - If you are using both the main (top) and the side navigation, it is a good practice to include an anchor link to the side navigation at the beginning of the main (top) navigation. This way assistive technologies can easily access the side navigation after a page load.
+- If there are multiple navigational components on the page, they should have individual aria-labels. This helps screen reader users to distinguish them from each other. The SideNavigation component has an ariaLabel property for that purpose.
 
 ## Usage and variations