[EuiLiveAnnouncer][A11y] Support live announcements on mount

packages/eui/changelogs/upcoming/8916.md

@@ -0,0 +1,5 @@
+**Accessibility**
+
+- Added a new beta `EuiLiveAnnouncer` component which supports `aria-live` announcements on mount
+- Added `announceOnMount` prop on `EuiCallOut` to support announcing its content on mount
+

packages/eui/src/components/accessibility/index.ts

@@ -12,3 +12,4 @@ export { EuiScreenReaderOnly, euiScreenReaderOnly } from './screen_reader_only';
 export type { EuiScreenReaderOnlyProps } from './screen_reader_only';
 export { EuiSkipLink } from './skip_link';
 export type { EuiSkipLinkProps } from './skip_link';
+export { type EuiLiveAnnouncerProps, EuiLiveAnnouncer } from './live_announcer';

packages/eui/src/components/accessibility/live_announcer/__snapshots__/live_announcer.test.tsx.snap

@@ -0,0 +1,12 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`EuiLiveAnnouncer renders screen reader content when active 1`] = `
+<div
+  aria-atomic="true"
+  aria-live="polite"
+  class="emotion-euiScreenReaderOnly"
+  role="status"
+>
+  You have new notifications.
+</div>
+`;

packages/eui/src/components/accessibility/live_announcer/index.ts

@@ -0,0 +1,9 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+export * from './live_announcer';

packages/eui/src/components/accessibility/live_announcer/live_announcer.stories.tsx

@@ -0,0 +1,170 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import React, { ReactNode, useEffect, useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { EuiLiveAnnouncer, EuiLiveAnnouncerProps } from './live_announcer';
+import { EuiFlexGroup, EuiFlexItem } from '../../flex';
+import { EuiButton } from '../../button';
+import { EuiCodeBlock } from '../../code';
+import { EuiSpacer } from '../../spacer';
+import { EuiCallOut } from '../../call_out';
+import { EuiFlyout, EuiFlyoutBody } from '../../flyout';
+
+const meta: Meta<EuiLiveAnnouncerProps> = {
+  title: 'Utilities/EuiLiveAnnouncer',
+  component: EuiLiveAnnouncer,
+  args: {
+    // Component defaults
+    role: 'status',
+    isActive: true,
+  },
+  parameters: {
+    loki: {
+      // There are no visual elements to test
+      skip: true,
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<EuiLiveAnnouncerProps>;
+
+export const Playground: Story = {
+  parameters: {
+    codeSnippet: {
+      snippet: `
+        <EuiLiveAnnouncer {{...STORY_ARGS}}>{message}</EuiLiveAnnouncer>
+      `,
+    },
+  },
+  args: {
+    children: 'You have new notifications',
+  },
+  render: function Render(args) {
+    const { children, ...rest } = args;
+    const [announcement, setAnnouncement] = useState<ReactNode>(children);
+    const [isAnnouncementShown, setAnnouncementShown] = useState(false);
+
+    useEffect(() => {
+      setAnnouncement(children);
+    }, [children]);
+
+    const updateAnnouncement = () => {
+      setAnnouncement(
+        `You have ${Math.floor(Math.random() * 1000)} new notifications.`
+      );
+    };
+
+    return (
+      <EuiFlexGroup direction="column" gutterSize="m" css={{ maxWidth: 300 }}>
+        <EuiFlexItem>
+          <EuiButton onClick={() => setAnnouncementShown((shown) => !shown)}>
+            Toggle announcement
+          </EuiButton>
+        </EuiFlexItem>
+
+        <EuiFlexItem>
+          {isAnnouncementShown && (
+            <>
+              <EuiButton onClick={updateAnnouncement}>
+                Update announcement
+              </EuiButton>
+              <EuiSpacer size="m" />
+              <EuiCodeBlock>{announcement}</EuiCodeBlock>
+              <EuiLiveAnnouncer {...rest}>{announcement}</EuiLiveAnnouncer>
+            </>
+          )}
+        </EuiFlexItem>
+      </EuiFlexGroup>
+    );
+  },
+};
+
+export const WithinFlyouts: Story = {
+  parameters: {
+    codeSnippet: {
+      skip: true,
+    },
+  },
+  args: {
+    children: 'You have new notifications',
+  },
+  render: function Render(args) {
+    const { children, ...rest } = args;
+    const [isFlyoutOpen, setFlyoutOpen] = useState(false);
+    const [announcement, setAnnouncement] = useState<ReactNode>(children);
+    const [isShown, setShown] = useState(false);
+
+    useEffect(() => {
+      setAnnouncement(children);
+    }, [children]);
+
+    const updateAnnouncement = () => {
+      setAnnouncement(
+        `You have ${Math.floor(Math.random() * 1000)} new notifications.`
+      );
+    };
+
+    const content = (
+      <>
+        <div>
+          <EuiButton onClick={updateAnnouncement}>
+            Update announcement
+          </EuiButton>
+          <EuiSpacer size="m" />
+          <EuiCodeBlock>{announcement}</EuiCodeBlock>
+          <EuiLiveAnnouncer {...rest}>{announcement}</EuiLiveAnnouncer>
+        </div>
+        <EuiSpacer size="xl" />
+        <EuiButton onClick={() => setShown((show) => !show)}>
+          Toggle CallOut
+        </EuiButton>
+        {isShown && (
+          <>
+            <EuiSpacer size="m" />
+            <EuiCallOut
+              announceOnMount
+              onDismiss={() => setShown(false)}
+              title="Important notification!"
+            >
+              {/* long text is for testing clearTimeout functionality */}
+              <span>
+                Lorem Ipsum is simply dummy text of the printing and typesetting
+                industry. Lorem Ipsum has been the industry's standard dummy
+                text ever since the 1500s, when an unknown printer took a galley
+                of type and scrambled it to make a type specimen book. It has
+                survived not only five centuries, but also the leap into
+                electronic typesetting, remaining essentially unchanged. It was
+                popularised in the 1960s with the release of Letraset sheets
+                containing Lorem Ipsum passages, and more recently with desktop
+                publishing software like Aldus PageMaker including versions of
+                Lorem Ipsum.
+              </span>
+            </EuiCallOut>
+          </>
+        )}
+      </>
+    );
+
+    return (
+      <>
+        <EuiButton onClick={() => setFlyoutOpen((open) => !open)}>
+          Toggle flyout
+        </EuiButton>
+
+        {isFlyoutOpen && (
+          <EuiFlyout onClose={() => setFlyoutOpen(false)}>
+            <EuiFlyoutBody>{content}</EuiFlyoutBody>
+          </EuiFlyout>
+        )}
+      </>
+    );
+  },
+};

packages/eui/src/components/accessibility/live_announcer/live_announcer.test.tsx

@@ -0,0 +1,110 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import React, { ReactElement } from 'react';
+import { act } from '@testing-library/react';
+import { screen, render } from '../../../test/rtl';
+
+import { EuiLiveAnnouncer } from './live_announcer';
+
+const content = 'You have new notifications.';
+
+const renderComponent = (component: ReactElement) => {
+  const testArgs = render(component);
+
+  act(() => {
+    jest.advanceTimersByTime(50);
+  });
+
+  return testArgs;
+};
+
+describe('EuiLiveAnnouncer', () => {
+  jest.useFakeTimers();
+
+  afterEach(() => {
+    jest.clearAllTimers();
+  });
+
+  it('renders screen reader content when active', () => {
+    const { container } = renderComponent(
+      <EuiLiveAnnouncer isActive={true}>{content}</EuiLiveAnnouncer>
+    );
+
+    expect(container.firstChild).toMatchSnapshot();
+  });
+
+  it('renders `children` as string correctly', () => {
+    renderComponent(<EuiLiveAnnouncer>{content}</EuiLiveAnnouncer>);
+
+    const region = screen.getByRole('status');
+    expect(region).toHaveAttribute('aria-live', 'polite');
+    expect(region).toHaveAttribute('aria-atomic', 'true');
+    expect(region).toHaveTextContent('You have new notifications.');
+  });
+
+  it('renders `children` as ReactNode correctly', () => {
+    renderComponent(<EuiLiveAnnouncer>{content}</EuiLiveAnnouncer>);
+
+    const region = screen.getByRole('status').firstChild;
+    expect(region).toHaveTextContent('You have new notifications.');
+  });
+
+  it('clears the message after `clearAfterMs`', () => {
+    renderComponent(
+      <EuiLiveAnnouncer clearAfterMs={1000}>{content}</EuiLiveAnnouncer>
+    );
+    const region = screen.getByRole('status');
+    expect(region).toHaveTextContent('You have new notifications.');
+    act(() => {
+      jest.advanceTimersByTime(1000);
+    });
+    expect(region).toHaveTextContent('');
+  });
+
+  it('does not clear the message if `clearAfterMs=false`', () => {
+    renderComponent(
+      <EuiLiveAnnouncer clearAfterMs={false}>{content}</EuiLiveAnnouncer>
+    );
+    const region = screen.getByRole('status');
+    act(() => {
+      jest.advanceTimersByTime(5000);
+    });
+    expect(region).toHaveTextContent('You have new notifications.');
+  });
+
+  it('sets `aria-live` to off when `isActive=false`', () => {
+    renderComponent(
+      <EuiLiveAnnouncer isActive={false}>{content}</EuiLiveAnnouncer>
+    );
+    const region = screen.getByRole('status');
+    expect(region).toHaveAttribute('aria-live', 'off');
+  });
+
+  it('sets custom `role` and `aria-live`', () => {
+    renderComponent(
+      <EuiLiveAnnouncer role="alert" aria-live="assertive">
+        {content}
+      </EuiLiveAnnouncer>
+    );
+    const region = screen.getByRole('alert');
+    expect(region).toHaveAttribute('aria-live', 'assertive');
+  });
+
+  it('updates the message when `children` change', () => {
+    const { rerender } = renderComponent(
+      <EuiLiveAnnouncer>{content}</EuiLiveAnnouncer>
+    );
+    const region = screen.getByRole('status');
+    expect(region).toHaveTextContent('You have new notifications.');
+    rerender(
+      <EuiLiveAnnouncer>You have additional notifications.</EuiLiveAnnouncer>
+    );
+    expect(region).toHaveTextContent('You have additional notifications.');
+  });
+});