[EuiGlobalToastList] Add configurable role prop and default to `log…

…` role (#7328)
elastic · Nov 1, 2023 · 92efeb4 · 92efeb4
1 parent 1792727
commit 92efeb4
Show file tree

Hide file tree

Showing 4 changed files with 35 additions and 6 deletions.
diff --git a/src/components/toast/__snapshots__/global_toast_list.test.tsx.snap b/src/components/toast/__snapshots__/global_toast_list.test.tsx.snap
@@ -6,15 +6,15 @@ exports[`EuiGlobalToastList is rendered 1`] = `
   aria-live="polite"
   class="euiGlobalToastList testClass1 testClass2 emotion-euiGlobalToastList-right-euiTestCss"
   data-test-subj="test subject string"
-  role="region"
+  role="log"
 />
 `;
 
 exports[`EuiGlobalToastList props side can be changed to left 1`] = `
 <div
   aria-live="polite"
   class="euiGlobalToastList emotion-euiGlobalToastList-left"
-  role="region"
+  role="log"
 >
   <div
     class="euiToast euiGlobalToastListItem emotion-euiToast-success-euiGlobalToastListItem"
@@ -117,7 +117,7 @@ exports[`EuiGlobalToastList props toasts is rendered 1`] = `
 <div
   aria-live="polite"
   class="euiGlobalToastList emotion-euiGlobalToastList-right"
-  role="region"
+  role="log"
 >
   <div
     class="euiToast euiGlobalToastListItem emotion-euiToast-success-euiGlobalToastListItem"

diff --git a/src/components/toast/global_toast_list.test.tsx b/src/components/toast/global_toast_list.test.tsx
@@ -271,5 +271,18 @@ describe('EuiGlobalToastList', () => {
         expect(sharedProps.dismissToast).toHaveBeenCalledTimes(TOAST_COUNT);
       });
     });
+
+    test('role', () => {
+      const { queryByRole } = render(
+        <EuiGlobalToastList
+          dismissToast={() => {}}
+          toastLifeTimeMs={5}
+          role="alert"
+        />
+      );
+
+      expect(queryByRole('alert')).toBeInTheDocument();
+      expect(queryByRole('log')).not.toBeInTheDocument();
+    });
   });
 });
diff --git a/src/components/toast/global_toast_list.tsx b/src/components/toast/global_toast_list.tsx
@@ -8,7 +8,8 @@
 
 import React, {
   FunctionComponent,
-  ReactChild,
+  HTMLAttributes,
+  ReactNode,
   useCallback,
   useEffect,
   useRef,
@@ -40,7 +41,7 @@ export const CLEAR_ALL_TOASTS_THRESHOLD_DEFAULT = 3;
 
 export interface Toast extends EuiToastProps {
   id: string;
-  text?: ReactChild;
+  text?: ReactNode;
   toastLifeTimeMs?: number;
 }
 
@@ -63,6 +64,16 @@ export interface EuiGlobalToastListProps extends CommonProps {
    * Optional callback that fires when a user clicks the "Clear all" button.
    */
   onClearAllToasts?: () => void;
+  /**
+   * Defaults to the [log role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/log_role).
+   *
+   * The [alert role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role)
+   * can be considered only if *all* toasts in this list will require immediate user attention.
+   * Several alerts at once, and unnecessary alerts, will a create bad screen reader user experience.
+   *
+   * @default log
+   */
+  role?: HTMLAttributes<HTMLElement>['role'];
 }
 
 export const EuiGlobalToastList: FunctionComponent<EuiGlobalToastListProps> = ({
@@ -345,7 +356,7 @@ export const EuiGlobalToastList: FunctionComponent<EuiGlobalToastListProps> = ({
   return (
     <div
       aria-live="polite"
-      role="region"
+      role="log"
       ref={listElement}
       css={cssStyles}
       className={classes}

diff --git a/upcoming_changelogs/7328.md b/upcoming_changelogs/7328.md
@@ -0,0 +1,5 @@
+- Added a configurable `role` prop to `EuiGlobalToastList`
+
+**Accessibility**
+
+- `EuiGlobalToastList` now defaults to a `log` role. If your toasts will always require immediate user action, consider (with caution) using the `alert` role instead.