[Discover] [Unified Doc Viewer] Fix doc viewer not receiving focus on…

… open (elastic#191039)

## Summary

This PR fixes an issue where the new resizable doc viewer push flyout
was not receiving focus on open, resulting in the flyout having to be
manually focused in before users can navigate between docs using the
arrow keys. It also re-adds support for closing the flyout when pressing
the escape key, improves overall focus management, ensures the proper
a11y attributes are used when the push flyout is shown, and introduces a
new set of functional tests for doc viewer keyboard navigation and a11y.

Fixes elastic#190946.

### Checklist

- [x] Any text added follows [EUI's writing
guidelines](https://elastic.github.io/eui/#/guidelines/writing), uses
sentence case text and includes [i18n
support](https://github.com/elastic/kibana/blob/main/packages/kbn-i18n/README.md)
- [ ]
[Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html)
was added for features that require explanation or tutorials
- [x] [Unit or functional
tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)
were updated or added to match the most common scenarios
- [ ] [Flaky Test
Runner](https://ci-stats.kibana.dev/trigger_flaky_test_runner/1) was
used on any tests changed
- [x] Any UI touched in this PR is usable by keyboard only (learn more
about [keyboard accessibility](https://webaim.org/techniques/keyboard/))
- [x] Any UI touched in this PR does not create any new axe failures
(run axe in browser:
[FF](https://addons.mozilla.org/en-US/firefox/addon/axe-devtools/),
[Chrome](https://chrome.google.com/webstore/detail/axe-web-accessibility-tes/lhdoppojpmngadmnindnejefpokejbdd?hl=en-US))
- [ ] If a plugin configuration key changed, check if it needs to be
allowlisted in the cloud and added to the [docker
list](https://github.com/elastic/kibana/blob/main/src/dev/build/tasks/os_packages/docker_generator/resources/base/bin/kibana-docker)
- [x] This renders correctly on smaller devices using a responsive
layout. (You can test this [in your
browser](https://www.browserstack.com/guide/responsive-testing-on-local-server))
- [x] This was checked for [cross-browser
compatibility](https://www.elastic.co/support/matrix#matrix_browsers)

### For maintainers

- [ ] This was checked for breaking API changes and was [labeled
appropriately](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process)

---------

Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>

src/plugins/unified_doc_viewer/public/components/doc_viewer_flyout/doc_viewer_flyout.tsx

@@ -7,7 +7,6 @@
  */
 
 import React, { useMemo, useCallback, type ComponentType } from 'react';
-import { get } from 'lodash';
 import { i18n } from '@kbn/i18n';
 import { css } from '@emotion/react';
 import type { DataView } from '@kbn/data-views-plugin/public';
@@ -34,6 +33,7 @@ import useLocalStorage from 'react-use/lib/useLocalStorage';
 import type { ToastsStart } from '@kbn/core-notifications-browser';
 import type { DocViewFilterFn, DocViewRenderProps } from '@kbn/unified-doc-viewer/types';
 import { UnifiedDocViewer } from '../lazy_doc_viewer';
+import { useFlyoutA11y } from './use_flyout_a11y';
 
 export interface UnifiedDocViewerFlyoutProps {
   'data-test-subj'?: string;
@@ -71,6 +71,7 @@ function getIndexByDocId(hits: DataTableRecord[], id: string) {
 }
 
 export const FLYOUT_WIDTH_KEY = 'unifiedDocViewer:flyoutWidth';
+
 /**
  * Flyout displaying an expanded row details
  */
@@ -129,24 +130,29 @@ export function UnifiedDocViewerFlyout({
 
   const onKeyDown = useCallback(
     (ev: React.KeyboardEvent) => {
-      const nodeClasses = get(ev, 'target.className', '');
-      if (typeof nodeClasses === 'string' && nodeClasses.includes('euiDataGrid')) {
+      if (ev.target instanceof HTMLElement && ev.target.closest('.euiDataGrid__content')) {
         // ignore events triggered from the data grid
         return;
       }
 
-      const nodeName = get(ev, 'target.nodeName', null);
-      if (typeof nodeName === 'string' && nodeName.toLowerCase() === 'input') {
+      if (ev.key === keys.ESCAPE) {
+        ev.preventDefault();
+        ev.stopPropagation();
+        onClose();
+      }
+
+      if (ev.target instanceof HTMLInputElement) {
         // ignore events triggered from the search input
         return;
       }
+
       if (ev.key === keys.ARROW_LEFT || ev.key === keys.ARROW_RIGHT) {
         ev.preventDefault();
         ev.stopPropagation();
         setPage(activePage + (ev.key === keys.ARROW_RIGHT ? 1 : -1));
       }
     },
-    [activePage, setPage]
+    [activePage, onClose, setPage]
   );
 
   const addColumn = useCallback(
@@ -231,6 +237,7 @@ export function UnifiedDocViewerFlyout({
         defaultMessage: 'Document',
       });
   const currentFlyoutTitle = flyoutTitle ?? defaultFlyoutTitle;
+  const { a11yProps, screenReaderDescription } = useFlyoutA11y({ isXlScreen });
 
   return (
     <EuiPortal>
@@ -250,7 +257,9 @@ export function UnifiedDocViewerFlyout({
           maxWidth: `${isXlScreen ? `calc(100vw - ${DEFAULT_WIDTH}px)` : '90vw'} !important`,
         }}
         paddingSize="m"
+        {...a11yProps}
       >
+        {screenReaderDescription}
         <EuiFlyoutHeader hasBorder>
           <EuiFlexGroup
             direction="row"

src/plugins/unified_doc_viewer/public/components/doc_viewer_flyout/use_flyout_a11y.tsx

@@ -0,0 +1,53 @@
+/*
+ * 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 { EuiScreenReaderOnly, useGeneratedHtmlId } from '@elastic/eui';
+import { i18n } from '@kbn/i18n';
+import React, { useEffect, useState } from 'react';
+import useUnmount from 'react-use/lib/useUnmount';
+
+export const useFlyoutA11y = ({ isXlScreen }: { isXlScreen: boolean }) => {
+  const descriptionId = useGeneratedHtmlId();
+  const [triggerEl] = useState(document.activeElement);
+  const [flyoutEl, setFlyoutEl] = useState<HTMLElement>();
+
+  // Auto-focus push flyout on open or when switching to XL screen
+  useEffect(() => {
+    if (isXlScreen && flyoutEl && document.contains(flyoutEl)) {
+      // Wait a tick before focusing or focus will be stolen by the trigger element when
+      // switching from an overlay flyout to a push flyout (due to EUI focus lock)
+      setTimeout(() => flyoutEl.focus());
+    }
+  }, [flyoutEl, isXlScreen]);
+
+  // Return focus to the trigger element when the flyout is closed
+  useUnmount(() => {
+    if (triggerEl instanceof HTMLElement && document.contains(triggerEl)) {
+      triggerEl.focus();
+    }
+  });
+
+  return {
+    a11yProps: {
+      ref: setFlyoutEl,
+      role: isXlScreen ? 'dialog' : undefined,
+      tabindex: isXlScreen ? 0 : undefined,
+      'aria-describedby': isXlScreen ? descriptionId : undefined,
+      'data-no-focus-lock': isXlScreen || undefined,
+    },
+    screenReaderDescription: isXlScreen && (
+      <EuiScreenReaderOnly>
+        <p id={descriptionId} data-test-subj="unifiedDocViewerScreenReaderDescription">
+          {i18n.translate('unifiedDocViewer.flyout.screenReaderDescription', {
+            defaultMessage: 'You are in a non-modal dialog. To close the dialog, press Escape.',
+          })}
+        </p>
+      </EuiScreenReaderOnly>
+    ),
+  };
+};

test/functional/apps/discover/group2_data_grid1/_data_grid_doc_table.ts

@@ -185,9 +185,9 @@ export default function ({ getService, getPageObjects }: FtrProviderContext) {
       it('should allow paginating docs in the flyout by clicking in the doc table', async function () {
         await retry.try(async function () {
           await dataGrid.clickRowToggle({ rowIndex: rowToInspect - 1 });
-          await testSubjects.exists(`docViewerFlyoutNavigationPage0`);
+          await testSubjects.existOrFail('docViewerFlyoutNavigationPage-0');
           await dataGrid.clickRowToggle({ rowIndex: rowToInspect });
-          await testSubjects.exists(`docViewerFlyoutNavigationPage1`);
+          await testSubjects.existOrFail('docViewerFlyoutNavigationPage-1');
           await dataGrid.closeFlyout();
         });
       });

test/functional/apps/discover/group3/_doc_viewer.ts

@@ -6,6 +6,7 @@
  * Side Public License, v 1.
  */
 
+import expect from '@kbn/expect';
 import { FtrProviderContext } from '../ftr_provider_context';
 
 export default function ({ getService, getPageObjects }: FtrProviderContext) {
@@ -16,6 +17,7 @@ export default function ({ getService, getPageObjects }: FtrProviderContext) {
   const find = getService('find');
   const retry = getService('retry');
   const dataGrid = getService('dataGrid');
+  const browser = getService('browser');
 
   describe('discover doc viewer', function describeIndexTests() {
     before(async function () {
@@ -97,5 +99,214 @@ export default function ({ getService, getPageObjects }: FtrProviderContext) {
         });
       });
     });
+
+    describe('flyout', () => {
+      let originalScreenSize = { width: 0, height: 0 };
+
+      const reduceScreenWidth = async () => {
+        await browser.setWindowSize(800, originalScreenSize.height);
+      };
+
+      const restoreScreenWidth = async () => {
+        await browser.setWindowSize(originalScreenSize.width, originalScreenSize.height);
+      };
+
+      before(async () => {
+        originalScreenSize = await browser.getWindowSize();
+      });
+
+      beforeEach(async () => {
+        // open the flyout once initially to ensure table is the default tab
+        await dataGrid.clickRowToggle();
+        await PageObjects.discover.isShowingDocViewer();
+        await dataGrid.closeFlyout();
+      });
+
+      afterEach(async () => {
+        await restoreScreenWidth();
+      });
+
+      describe('keyboard navigation', () => {
+        it('should navigate between documents with arrow keys', async () => {
+          await dataGrid.clickRowToggle();
+          await PageObjects.discover.isShowingDocViewer();
+          await testSubjects.existOrFail(`docViewerFlyoutNavigationPage-0`);
+          await browser.pressKeys(browser.keys.ARROW_RIGHT);
+          await testSubjects.existOrFail(`docViewerFlyoutNavigationPage-1`);
+          await browser.pressKeys(browser.keys.ARROW_RIGHT);
+          await testSubjects.existOrFail(`docViewerFlyoutNavigationPage-2`);
+          await browser.pressKeys(browser.keys.ARROW_LEFT);
+          await testSubjects.existOrFail(`docViewerFlyoutNavigationPage-1`);
+          await browser.pressKeys(browser.keys.ARROW_LEFT);
+          await testSubjects.existOrFail(`docViewerFlyoutNavigationPage-0`);
+        });
+
+        it('should not navigate between documents with arrow keys when the search input is focused', async () => {
+          await dataGrid.clickRowToggle();
+          await PageObjects.discover.isShowingDocViewer();
+          await testSubjects.existOrFail(`docViewerFlyoutNavigationPage-0`);
+          await browser.pressKeys(browser.keys.ARROW_RIGHT);
+          await testSubjects.existOrFail(`docViewerFlyoutNavigationPage-1`);
+          await testSubjects.click('unifiedDocViewerFieldsSearchInput');
+          await browser.pressKeys(browser.keys.ARROW_RIGHT);
+          await testSubjects.existOrFail(`docViewerFlyoutNavigationPage-1`);
+          await browser.pressKeys(browser.keys.TAB);
+          await browser.pressKeys(browser.keys.ARROW_RIGHT);
+          await testSubjects.existOrFail(`docViewerFlyoutNavigationPage-2`);
+        });
+
+        it('should not navigate between documents with arrow keys when the data grid is focused', async () => {
+          await dataGrid.clickRowToggle();
+          await PageObjects.discover.isShowingDocViewer();
+          await testSubjects.existOrFail(`docViewerFlyoutNavigationPage-0`);
+          await browser.pressKeys(browser.keys.ARROW_RIGHT);
+          await testSubjects.existOrFail(`docViewerFlyoutNavigationPage-1`);
+          await testSubjects.click('dataGridHeaderCell-name');
+          await browser.pressKeys(browser.keys.ARROW_RIGHT);
+          await testSubjects.existOrFail(`docViewerFlyoutNavigationPage-1`);
+          await browser.pressKeys(browser.keys.TAB);
+          await browser.pressKeys(browser.keys.ARROW_RIGHT);
+          await testSubjects.existOrFail(`docViewerFlyoutNavigationPage-2`);
+        });
+
+        it('should close the flyout with the escape key', async () => {
+          await dataGrid.clickRowToggle();
+          expect(await PageObjects.discover.isShowingDocViewer()).to.be(true);
+          await browser.pressKeys(browser.keys.ESCAPE);
+          expect(await PageObjects.discover.isShowingDocViewer()).to.be(false);
+        });
+
+        it('should close the flyout with the escape key when the search input is focused', async () => {
+          await dataGrid.clickRowToggle();
+          expect(await PageObjects.discover.isShowingDocViewer()).to.be(true);
+          await testSubjects.click('unifiedDocViewerFieldsSearchInput');
+          await browser.pressKeys(browser.keys.ESCAPE);
+          expect(await PageObjects.discover.isShowingDocViewer()).to.be(false);
+        });
+
+        it('should not close the flyout with the escape key when the data grid is focused', async () => {
+          await dataGrid.clickRowToggle();
+          expect(await PageObjects.discover.isShowingDocViewer()).to.be(true);
+          await testSubjects.click('dataGridHeaderCell-name');
+          await browser.pressKeys(browser.keys.ESCAPE);
+          expect(await PageObjects.discover.isShowingDocViewer()).to.be(true);
+          await browser.pressKeys(browser.keys.TAB);
+          await browser.pressKeys(browser.keys.ESCAPE);
+          expect(await PageObjects.discover.isShowingDocViewer()).to.be(false);
+        });
+      });
+
+      describe('accessibility', () => {
+        it('should focus the flyout on open, and retain focus when resizing between push and overlay flyouts', async () => {
+          // push -> overlay -> push
+          await dataGrid.clickRowToggle();
+          await PageObjects.discover.isShowingDocViewer();
+          let activeElement = await find.activeElement();
+          expect(await activeElement.getAttribute('data-test-subj')).to.be('docViewerFlyout');
+          await reduceScreenWidth();
+          activeElement = await find.activeElement();
+          expect(await activeElement.getAttribute('data-test-subj')).to.be('docViewerFlyout');
+          await restoreScreenWidth();
+          activeElement = await find.activeElement();
+          expect(await activeElement.getAttribute('data-test-subj')).to.be('docViewerFlyout');
+          // overlay -> push -> overlay
+          await browser.pressKeys(browser.keys.ESCAPE);
+          await reduceScreenWidth();
+          await dataGrid.clickRowToggle();
+          await PageObjects.discover.isShowingDocViewer();
+          activeElement = await find.activeElement();
+          expect(await activeElement.getAttribute('data-test-subj')).to.be('docViewerFlyout');
+          await restoreScreenWidth();
+          activeElement = await find.activeElement();
+          expect(await activeElement.getAttribute('data-test-subj')).to.be('docViewerFlyout');
+          await reduceScreenWidth();
+          activeElement = await find.activeElement();
+          expect(await activeElement.getAttribute('data-test-subj')).to.be('docViewerFlyout');
+        });
+
+        it('should return focus to the trigger element when the flyout is closed', async () => {
+          // push
+          await dataGrid.clickRowToggle();
+          await PageObjects.discover.isShowingDocViewer();
+          await browser.pressKeys(browser.keys.ESCAPE);
+          let activeElement = await find.activeElement();
+          expect(await activeElement.getAttribute('data-test-subj')).to.be(
+            'docTableExpandToggleColumn'
+          );
+          // push -> overlay
+          await dataGrid.clickRowToggle();
+          await PageObjects.discover.isShowingDocViewer();
+          await reduceScreenWidth();
+          await browser.pressKeys(browser.keys.ESCAPE);
+          activeElement = await find.activeElement();
+          expect(await activeElement.getAttribute('data-test-subj')).to.be(
+            'docTableExpandToggleColumn'
+          );
+          // overlay
+          await dataGrid.clickRowToggle();
+          await PageObjects.discover.isShowingDocViewer();
+          await browser.pressKeys(browser.keys.ESCAPE);
+          activeElement = await find.activeElement();
+          expect(await activeElement.getAttribute('data-test-subj')).to.be(
+            'docTableExpandToggleColumn'
+          );
+          // overlay -> push
+          await dataGrid.clickRowToggle();
+          await PageObjects.discover.isShowingDocViewer();
+          await restoreScreenWidth();
+          await browser.pressKeys(browser.keys.ESCAPE);
+          activeElement = await find.activeElement();
+          expect(await activeElement.getAttribute('data-test-subj')).to.be(
+            'docTableExpandToggleColumn'
+          );
+        });
+
+        it('should show custom screen reader description push flyout is active', async () => {
+          await dataGrid.clickRowToggle();
+          await PageObjects.discover.isShowingDocViewer();
+          await testSubjects.existOrFail('unifiedDocViewerScreenReaderDescription', {
+            allowHidden: true,
+          });
+        });
+
+        it('should not show custom screen reader description when overlay flyout active', async () => {
+          await dataGrid.clickRowToggle();
+          await PageObjects.discover.isShowingDocViewer();
+          await reduceScreenWidth();
+          expect(
+            await testSubjects.exists('unifiedDocViewerScreenReaderDescription', {
+              allowHidden: true,
+            })
+          ).to.be(false);
+        });
+
+        it('should use expected a11y attributes', async () => {
+          // push flyout
+          await dataGrid.clickRowToggle();
+          await PageObjects.discover.isShowingDocViewer();
+          let role = await testSubjects.getAttribute('docViewerFlyout', 'role');
+          let tabindex = await testSubjects.getAttribute('docViewerFlyout', 'tabindex');
+          let describedBy = await testSubjects.getAttribute('docViewerFlyout', 'aria-describedby');
+          let noFocusLock = await testSubjects.getAttribute(
+            'docViewerFlyout',
+            'data-no-focus-lock'
+          );
+          expect(role).to.be('dialog');
+          expect(tabindex).to.be('0');
+          expect(await find.existsByCssSelector(`#${describedBy}`)).to.be(true);
+          expect(noFocusLock).to.be('true');
+          // overlay flyout
+          await reduceScreenWidth();
+          role = await testSubjects.getAttribute('docViewerFlyout', 'role');
+          tabindex = await testSubjects.getAttribute('docViewerFlyout', 'tabindex');
+          describedBy = await testSubjects.getAttribute('docViewerFlyout', 'aria-describedby');
+          noFocusLock = await testSubjects.getAttribute('docViewerFlyout', 'data-no-focus-lock');
+          expect(role).to.be('dialog');
+          expect(tabindex).to.be('0');
+          expect(await find.existsByCssSelector(`#${describedBy}`)).to.be(true);
+          expect(noFocusLock).to.be(null);
+        });
+      });
+    });
   });
 }