[Header] Add hidden live region to announce when the page title chang…

…es. (#10958) ### WHY are these changes introduced? Relates to Shopify/web#101295 Merchants using a screen reader have no idea when pages change, so this PR adds a hidden live element which will announce to the merchant the page title followed by "This page is ready". ### How to 🎩 🖥 [Local development instructions](https://github.com/Shopify/polaris/blob/main/README.md#local-development) 🗒 [General tophatting guidelines](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md) 📄 [Changelog guidelines](https://github.com/Shopify/polaris/blob/main/.github/CONTRIBUTING.md#changelog) </details> ### 🎩 checklist - [x] Tested on [mobile](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md#cross-browser-testing) - [x] Tested on [multiple browsers](https://help.shopify.com/en/manual/shopify-admin/supported-browsers) - [x] Tested for [accessibility](https://github.com/Shopify/polaris/blob/main/documentation/Accessibility%20testing.md) - [x] Updated the component's `README.md` with documentation changes - [x] [Tophatted documentation](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting%20documentation.md) changes in the style guide --------- Co-authored-by: translation-platform[bot] <34770790+translation-platform[bot]@users.noreply.github.com> Co-authored-by: Chloe Rice <[email protected]>
Shopify · Dec 13, 2023 · 5c183e0 · 5c183e0 · kaitoukid-1412 · Dec 14, 2023
1 parent a749323
commit 5c183e0
Show file tree

Hide file tree

Showing 24 changed files with 90 additions and 21 deletions.
diff --git a/.changeset/strong-moose-remain.md b/.changeset/strong-moose-remain.md
@@ -0,0 +1,5 @@
+---
+'@shopify/polaris': minor
+---
+
+Added a live region to the `Page` `Header` to announce the `title` after navigation changes
diff --git a/polaris-react/locales/cs.json b/polaris-react/locales/cs.json
@@ -350,7 +350,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "Zobrazte akce pro: {title}"
+        "rollupActionsLabel": "Zobrazte akce pro: {title}",
+        "pageReadyAccessibilityLabel": "{title}. Tato stránka je připravena."
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/locales/da.json b/polaris-react/locales/da.json
@@ -348,7 +348,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "Se handlinger for {title}"
+        "rollupActionsLabel": "Se handlinger for {title}",
+        "pageReadyAccessibilityLabel": "{title}. Denne side er klar"
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/locales/de.json b/polaris-react/locales/de.json
@@ -348,7 +348,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "Aktionen für {title} anzeigen"
+        "rollupActionsLabel": "Aktionen für {title} anzeigen",
+        "pageReadyAccessibilityLabel": "{title}. Diese Seite ist bereit"
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/locales/en.json b/polaris-react/locales/en.json
@@ -242,7 +242,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "View actions for {title}"
+        "rollupActionsLabel": "View actions for {title}",
+        "pageReadyAccessibilityLabel": "{title}. This page is ready"
       }
     },
     "Pagination": {

diff --git a/polaris-react/locales/es.json b/polaris-react/locales/es.json
@@ -349,7 +349,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "Ver acciones para {title}"
+        "rollupActionsLabel": "Ver acciones para {title}",
+        "pageReadyAccessibilityLabel": "{title}. Esta página está lista"
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/locales/fi.json b/polaris-react/locales/fi.json
@@ -348,7 +348,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "Tarkastele nimikettä {title} koskevia toimintoja"
+        "rollupActionsLabel": "Tarkastele nimikettä {title} koskevia toimintoja",
+        "pageReadyAccessibilityLabel": "{title}. Tämä sivu on valmis"
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/locales/fr.json b/polaris-react/locales/fr.json
@@ -349,7 +349,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "Afficher les actions pour {title}"
+        "rollupActionsLabel": "Afficher les actions pour {title}",
+        "pageReadyAccessibilityLabel": "{title}. Cette page est prête"
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/locales/it.json b/polaris-react/locales/it.json
@@ -349,7 +349,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "Visualizza azioni per {title}"
+        "rollupActionsLabel": "Visualizza azioni per {title}",
+        "pageReadyAccessibilityLabel": "{title}. Questa pagina è pronta"
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/locales/ja.json b/polaris-react/locales/ja.json
@@ -348,7 +348,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "{title}のアクションを表示"
+        "rollupActionsLabel": "{title}のアクションを表示",
+        "pageReadyAccessibilityLabel": "{title}。このページの準備が整いました"
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/locales/ko.json b/polaris-react/locales/ko.json
@@ -348,7 +348,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "{title} 작업 보기"
+        "rollupActionsLabel": "{title} 작업 보기",
+        "pageReadyAccessibilityLabel": "{title}. 이 페이지가 준비되었습니다"
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/locales/nb.json b/polaris-react/locales/nb.json
@@ -348,7 +348,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "Vis handlinger for {title}"
+        "rollupActionsLabel": "Vis handlinger for {title}",
+        "pageReadyAccessibilityLabel": "{title}. Denne siden er klar"
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/locales/nl.json b/polaris-react/locales/nl.json
@@ -348,7 +348,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "Acties voor {title} bekijken"
+        "rollupActionsLabel": "Acties voor {title} bekijken",
+        "pageReadyAccessibilityLabel": "{title}. Deze pagina is klaar"
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/locales/pl.json b/polaris-react/locales/pl.json
@@ -350,7 +350,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "Wyświetl czynności dla {title}"
+        "rollupActionsLabel": "Wyświetl czynności dla {title}",
+        "pageReadyAccessibilityLabel": "{title}. Ta strona jest gotowa"
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/locales/pt-BR.json b/polaris-react/locales/pt-BR.json
@@ -349,7 +349,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "Ver ações para {title}"
+        "rollupActionsLabel": "Ver ações para {title}",
+        "pageReadyAccessibilityLabel": "{title}. A página está pronta"
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/locales/pt-PT.json b/polaris-react/locales/pt-PT.json
@@ -349,7 +349,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "Ver ações para {title}"
+        "rollupActionsLabel": "Ver ações para {title}",
+        "pageReadyAccessibilityLabel": "{title}. Esta página está pronta"
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/locales/sv.json b/polaris-react/locales/sv.json
@@ -348,7 +348,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "Visa åtgärder för {title}"
+        "rollupActionsLabel": "Visa åtgärder för {title}",
+        "pageReadyAccessibilityLabel": "{title}. Den här sidan är redo"
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/locales/th.json b/polaris-react/locales/th.json
@@ -348,7 +348,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "ดูการดำเนินการสำหรับ {title}"
+        "rollupActionsLabel": "ดูการดำเนินการสำหรับ {title}",
+        "pageReadyAccessibilityLabel": "{title} หน้านี้พร้อมแล้ว"
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/locales/tr.json b/polaris-react/locales/tr.json
@@ -348,7 +348,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "{title} ile ilgili işlemleri görüntüle"
+        "rollupActionsLabel": "{title} ile ilgili işlemleri görüntüle",
+        "pageReadyAccessibilityLabel": "{title}. Bu sayfa hazır"
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/locales/vi.json b/polaris-react/locales/vi.json
@@ -348,7 +348,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "Xem thao tác đối với {title}"
+        "rollupActionsLabel": "Xem thao tác đối với {title}",
+        "pageReadyAccessibilityLabel": "{title}. Trang này đã sẵn sàng"
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/locales/zh-CN.json b/polaris-react/locales/zh-CN.json
@@ -348,7 +348,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "查看用于 {title} 的操作"
+        "rollupActionsLabel": "查看用于 {title} 的操作",
+        "pageReadyAccessibilityLabel": "{title}。此页面已就绪"
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/locales/zh-TW.json b/polaris-react/locales/zh-TW.json
@@ -348,7 +348,8 @@
     },
     "Page": {
       "Header": {
-        "rollupActionsLabel": "檢視 {title} 的動作"
+        "rollupActionsLabel": "檢視 {title} 的動作",
+        "pageReadyAccessibilityLabel": "{title}。此頁面已準備就緒"
       }
     },
     "FullscreenBar": {

diff --git a/polaris-react/src/components/Page/components/Header/Header.tsx b/polaris-react/src/components/Page/components/Header/Header.tsx
@@ -49,6 +49,8 @@ interface PrimaryAction
 export interface HeaderProps extends TitleProps {
   /** Visually hide the title */
   titleHidden?: boolean;
+  /** A label to use for the page when the page is ready, used by screen readers. Will override the title prop if present */
+  pageReadyAccessibilityLabel?: string;
   /** Enables filtering action list items */
   filterActions?: boolean;
   /** Primary page-level action */
@@ -74,6 +76,7 @@ const LONG_TITLE = 34;
 export function Header({
   title,
   subtitle,
+  pageReadyAccessibilityLabel,
   titleMetadata,
   additionalMetadata,
   titleHidden = false,
@@ -128,6 +131,20 @@ export function Header({
     </div>
   );
 
+  const labelForPageReadyAccessibilityLabel =
+    pageReadyAccessibilityLabel || title;
+
+  const pageReadyAccessibilityLabelMarkup =
+    labelForPageReadyAccessibilityLabel ? (
+      <div role="status">
+        <Text visuallyHidden as="p">
+          {i18n.translate('Polaris.Page.Header.pageReadyAccessibilityLabel', {
+            title: labelForPageReadyAccessibilityLabel,
+          })}
+        </Text>
+      </div>
+    ) : undefined;
+
   const primaryActionMarkup = primaryAction ? (
     <PrimaryActionMarkup primaryAction={primaryAction} />
   ) : null;
@@ -208,6 +225,7 @@ export function Header({
       paddingInlineEnd={{xs: '400', sm: '0'}}
       visuallyHidden={titleHidden}
     >
+      {pageReadyAccessibilityLabelMarkup}
       <div className={headerClassNames}>
         <FilterActionsProvider filterActions={Boolean(filterActions)}>
           <ConditionalRender

diff --git a/polaris-react/src/components/Page/components/Header/tests/Header.test.tsx b/polaris-react/src/components/Page/components/Header/tests/Header.test.tsx
@@ -9,6 +9,7 @@ import {Button} from '../../../../Button';
 import {ButtonGroup} from '../../../../ButtonGroup';
 import {Pagination} from '../../../../Pagination';
 import {Tooltip} from '../../../../Tooltip';
+import {Text} from '../../../../Text';
 import type {LinkAction, MenuActionDescriptor} from '../../../../../types';
 import {Header} from '../Header';
 import type {HeaderProps} from '../Header';
@@ -45,6 +46,30 @@ describe('<Header />', () => {
         titleMetadata: mockProps.titleMetadata,
       });
     });
+
+    it('renders an aria-live region with the title', () => {
+      const header = mountWithApp(<Header {...mockProps} />);
+      const liveRegion = header.find('div', {role: 'status'});
+      expect(liveRegion).toContainReactComponent(Text, {
+        visuallyHidden: true,
+        children: `${mockProps.title}. This page is ready`,
+      });
+    });
+
+    it('renders an aria-live region with the pageReadyAccessibilityLabel which overrides the title', () => {
+      const pageReadyAccessibilityLabel = 'page ready';
+      const header = mountWithApp(
+        <Header
+          {...mockProps}
+          pageReadyAccessibilityLabel={pageReadyAccessibilityLabel}
+        />,
+      );
+      const liveRegion = header.find('div', {role: 'status'});
+      expect(liveRegion).toContainReactComponent(Text, {
+        visuallyHidden: true,
+        children: `${pageReadyAccessibilityLabel}. This page is ready`,
+      });
+    });
   });
 
   describe('breadcrumbs', () => {