From e0a1584762f0fa9ef1296d5e999bc3a69a118996 Mon Sep 17 00:00:00 2001
From: Cee Chen <constance.chen@elastic.co>
Date: Thu, 4 Jan 2024 15:24:30 -0800
Subject: [PATCH] Add screen reader text for Enter key behavior

---
 changelogs/upcoming/7448.md                   |  1 +
 .../__snapshots__/data_grid.test.tsx.snap     | 48 +++++++++++++++++++
 .../data_grid_body_custom.test.tsx.snap       |  8 ++++
 .../data_grid_body_virtualized.test.tsx.snap  |  4 ++
 .../data_grid_cell.test.tsx.snap              |  2 +
 .../datagrid/body/cell/data_grid_cell.tsx     |  9 ++++
 .../datagrid/body/cell/focus_utils.test.tsx   | 17 +++++++
 .../datagrid/body/cell/focus_utils.tsx        | 13 +++++
 8 files changed, 102 insertions(+)

diff --git a/changelogs/upcoming/7448.md b/changelogs/upcoming/7448.md
index bc8e1e3eecc7..ac918fe177bb 100644
--- a/changelogs/upcoming/7448.md
+++ b/changelogs/upcoming/7448.md
@@ -4,3 +4,4 @@
   - Headers are now always navigable by arrow key, regardless of whether the header cells contain interactive content
   - Non-expandable cells containing any amount of interactive content now must be entered via Enter or F2 keypress
   - Expandable cells continue to be toggled via Enter or F2 keypress
+- `EuiDataGrid` now provides a direct screen reader hint for Enter key behavior for expandable & interactive cells
diff --git a/src/components/datagrid/__snapshots__/data_grid.test.tsx.snap b/src/components/datagrid/__snapshots__/data_grid.test.tsx.snap
index 4327dfe50c4c..e0ec7f6aa4aa 100644
--- a/src/components/datagrid/__snapshots__/data_grid.test.tsx.snap
+++ b/src/components/datagrid/__snapshots__/data_grid.test.tsx.snap
@@ -725,6 +725,8 @@ exports[`EuiDataGrid rendering renders additional toolbar controls 1`] = `
               >
                 - 
                 A, column 1, row 1
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -773,6 +775,8 @@ exports[`EuiDataGrid rendering renders additional toolbar controls 1`] = `
               >
                 - 
                 B, column 2, row 1
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -821,6 +825,8 @@ exports[`EuiDataGrid rendering renders additional toolbar controls 1`] = `
               >
                 - 
                 A, column 1, row 2
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -869,6 +875,8 @@ exports[`EuiDataGrid rendering renders additional toolbar controls 1`] = `
               >
                 - 
                 B, column 2, row 2
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -917,6 +925,8 @@ exports[`EuiDataGrid rendering renders additional toolbar controls 1`] = `
               >
                 - 
                 A, column 1, row 3
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -965,6 +975,8 @@ exports[`EuiDataGrid rendering renders additional toolbar controls 1`] = `
               >
                 - 
                 B, column 2, row 3
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -1348,6 +1360,8 @@ exports[`EuiDataGrid rendering renders control columns 1`] = `
               >
                 - 
                 A, column 2, row 1
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -1396,6 +1410,8 @@ exports[`EuiDataGrid rendering renders control columns 1`] = `
               >
                 - 
                 B, column 3, row 1
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -1496,6 +1512,8 @@ exports[`EuiDataGrid rendering renders control columns 1`] = `
               >
                 - 
                 A, column 2, row 2
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -1544,6 +1562,8 @@ exports[`EuiDataGrid rendering renders control columns 1`] = `
               >
                 - 
                 B, column 3, row 2
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -1644,6 +1664,8 @@ exports[`EuiDataGrid rendering renders control columns 1`] = `
               >
                 - 
                 A, column 2, row 3
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -1692,6 +1714,8 @@ exports[`EuiDataGrid rendering renders control columns 1`] = `
               >
                 - 
                 B, column 3, row 3
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -2036,6 +2060,8 @@ exports[`EuiDataGrid rendering renders custom column headers 1`] = `
               >
                 - 
                 A, column 1, row 1
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -2084,6 +2110,8 @@ exports[`EuiDataGrid rendering renders custom column headers 1`] = `
               >
                 - 
                 B, column 2, row 1
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -2132,6 +2160,8 @@ exports[`EuiDataGrid rendering renders custom column headers 1`] = `
               >
                 - 
                 A, column 1, row 2
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -2180,6 +2210,8 @@ exports[`EuiDataGrid rendering renders custom column headers 1`] = `
               >
                 - 
                 B, column 2, row 2
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -2228,6 +2260,8 @@ exports[`EuiDataGrid rendering renders custom column headers 1`] = `
               >
                 - 
                 A, column 1, row 3
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -2276,6 +2310,8 @@ exports[`EuiDataGrid rendering renders custom column headers 1`] = `
               >
                 - 
                 B, column 2, row 3
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -2592,6 +2628,8 @@ exports[`EuiDataGrid rendering renders with common and div attributes 1`] = `
               >
                 - 
                 A, column 1, row 1
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -2640,6 +2678,8 @@ exports[`EuiDataGrid rendering renders with common and div attributes 1`] = `
               >
                 - 
                 B, column 2, row 1
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -2688,6 +2728,8 @@ exports[`EuiDataGrid rendering renders with common and div attributes 1`] = `
               >
                 - 
                 A, column 1, row 2
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -2736,6 +2778,8 @@ exports[`EuiDataGrid rendering renders with common and div attributes 1`] = `
               >
                 - 
                 B, column 2, row 2
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -2784,6 +2828,8 @@ exports[`EuiDataGrid rendering renders with common and div attributes 1`] = `
               >
                 - 
                 A, column 1, row 3
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
@@ -2832,6 +2878,8 @@ exports[`EuiDataGrid rendering renders with common and div attributes 1`] = `
               >
                 - 
                 B, column 2, row 3
+                 - 
+                Press the Enter key to expand this cell.
               </p>
               <div
                 class="euiDataGridRowCell__actions"
diff --git a/src/components/datagrid/body/__snapshots__/data_grid_body_custom.test.tsx.snap b/src/components/datagrid/body/__snapshots__/data_grid_body_custom.test.tsx.snap
index 064c0d43817a..c3765012c9a9 100644
--- a/src/components/datagrid/body/__snapshots__/data_grid_body_custom.test.tsx.snap
+++ b/src/components/datagrid/body/__snapshots__/data_grid_body_custom.test.tsx.snap
@@ -139,6 +139,8 @@ exports[`EuiDataGridBodyCustomRender treats \`renderCustomGridBody\` as a render
       >
         - 
         columnA, column 1, row 1
+         - 
+        Press the Enter key to expand this cell.
       </p>
       <div
         class="euiDataGridRowCell__actions"
@@ -187,6 +189,8 @@ exports[`EuiDataGridBodyCustomRender treats \`renderCustomGridBody\` as a render
       >
         - 
         columnB, column 2, row 1
+         - 
+        Press the Enter key to expand this cell.
       </p>
       <div
         class="euiDataGridRowCell__actions"
@@ -239,6 +243,8 @@ exports[`EuiDataGridBodyCustomRender treats \`renderCustomGridBody\` as a render
       >
         - 
         columnA, column 1, row 2
+         - 
+        Press the Enter key to expand this cell.
       </p>
       <div
         class="euiDataGridRowCell__actions"
@@ -287,6 +293,8 @@ exports[`EuiDataGridBodyCustomRender treats \`renderCustomGridBody\` as a render
       >
         - 
         columnB, column 2, row 2
+         - 
+        Press the Enter key to expand this cell.
       </p>
       <div
         class="euiDataGridRowCell__actions"
diff --git a/src/components/datagrid/body/__snapshots__/data_grid_body_virtualized.test.tsx.snap b/src/components/datagrid/body/__snapshots__/data_grid_body_virtualized.test.tsx.snap
index 7a16c48647e0..ab61e5ced8f3 100644
--- a/src/components/datagrid/body/__snapshots__/data_grid_body_virtualized.test.tsx.snap
+++ b/src/components/datagrid/body/__snapshots__/data_grid_body_virtualized.test.tsx.snap
@@ -142,6 +142,8 @@ exports[`EuiDataGridBodyVirtualized renders 1`] = `
       >
         - 
         columnA, column 1, row 1
+         - 
+        Press the Enter key to expand this cell.
       </p>
       <div
         class="euiDataGridRowCell__actions"
@@ -192,6 +194,8 @@ exports[`EuiDataGridBodyVirtualized renders 1`] = `
       >
         - 
         columnB, column 2, row 1
+         - 
+        Press the Enter key to expand this cell.
       </p>
       <div
         class="euiDataGridRowCell__actions"
diff --git a/src/components/datagrid/body/cell/__snapshots__/data_grid_cell.test.tsx.snap b/src/components/datagrid/body/cell/__snapshots__/data_grid_cell.test.tsx.snap
index c455eda3dfe2..7cdbbfab6688 100644
--- a/src/components/datagrid/body/cell/__snapshots__/data_grid_cell.test.tsx.snap
+++ b/src/components/datagrid/body/cell/__snapshots__/data_grid_cell.test.tsx.snap
@@ -71,6 +71,8 @@ exports[`EuiDataGridCell renders 1`] = `
   >
     - 
     someColumn, column 1, row 1
+     - 
+    Press the Enter key to expand this cell.
   </p>
   <div
     class="euiDataGridRowCell__actions"
diff --git a/src/components/datagrid/body/cell/data_grid_cell.tsx b/src/components/datagrid/body/cell/data_grid_cell.tsx
index 7166d75e3ee3..90cb364055b0 100644
--- a/src/components/datagrid/body/cell/data_grid_cell.tsx
+++ b/src/components/datagrid/body/cell/data_grid_cell.tsx
@@ -125,6 +125,15 @@ const EuiDataGridCellContent: FunctionComponent<
               row: ariaRowIndex,
             }}
           />
+          {cellActions && (
+            <>
+              {' - '}
+              <EuiI18n
+                token="euiDataGridCell.expansionEnterPrompt"
+                default="Press the Enter key to expand this cell."
+              />
+            </>
+          )}
         </p>
       </EuiScreenReaderOnly>
     );
diff --git a/src/components/datagrid/body/cell/focus_utils.test.tsx b/src/components/datagrid/body/cell/focus_utils.test.tsx
index 1dcbccacb071..a35407d00dce 100644
--- a/src/components/datagrid/body/cell/focus_utils.test.tsx
+++ b/src/components/datagrid/body/cell/focus_utils.test.tsx
@@ -124,6 +124,23 @@ describe('HandleInteractiveChildren', () => {
 });
 
 describe('FocusTrappedChildren', () => {
+  it('renders a screen reader hint', () => {
+    const cell = getCellWithInteractiveChildren();
+    const { container } = render(<FocusTrappedChildren cellEl={cell} />);
+    expect(container.childNodes[1]).toMatchInlineSnapshot(`
+      <div
+        data-focus-lock-disabled="disabled"
+      >
+        <p
+          class="emotion-euiScreenReaderOnly"
+        >
+           - 
+          Press the Enter key to interact with this cell's contents.
+        </p>
+      </div>
+    `);
+  });
+
   describe('on enter', () => {
     it('enables the focus trap, all interactive children, and moves focus to the first focusable child', () => {
       const cell = getCellWithInteractiveChildren();
diff --git a/src/components/datagrid/body/cell/focus_utils.tsx b/src/components/datagrid/body/cell/focus_utils.tsx
index 77b655eb6cb5..4d425244f839 100644
--- a/src/components/datagrid/body/cell/focus_utils.tsx
+++ b/src/components/datagrid/body/cell/focus_utils.tsx
@@ -17,6 +17,8 @@ import { tabbable } from 'tabbable';
 
 import { keys } from '../../../../services';
 import { EuiFocusTrap } from '../../../focus_trap';
+import { EuiScreenReaderOnly } from '../../../accessibility';
+import { EuiI18n } from '../../../i18n';
 
 /**
  * This internal utility component is used by all cells, both header and body/footer cells.
@@ -120,6 +122,17 @@ export const FocusTrappedChildren: FunctionComponent<
       clickOutsideDisables={true}
     >
       {children}
+
+      <EuiScreenReaderOnly>
+        <p>
+          {' - '}
+          <EuiI18n
+            // eslint-disable-next-line local/i18n
+            token="euiDataGridCell.focusTrapEnterPrompt"
+            default="Press the Enter key to interact with this cell's contents."
+          />
+        </p>
+      </EuiScreenReaderOnly>
     </EuiFocusTrap>
   );
 };