[EuiDataGrid] Allow consuming applications to control various internal state via ref

CHANGELOG.md

@@ -1,5 +1,7 @@
 ## [`main`](https://github.com/elastic/eui/tree/main)
 
+- Added the ability to control internal `EuiDataGrid` fullscreen, cell focus, and cell popover state via the `ref` prop ([#5590](https://github.com/elastic/eui/pull/5590))
+
 **Bug fixes**
 
 - Fixed `EuiInMemoryTable`'s `onTableChange` callback not returning the correct `sort.field` value on pagination ([#5588](https://github.com/elastic/eui/pull/5588))

src-docs/src/routes.js

@@ -89,6 +89,7 @@ import { DataGridControlColumnsExample } from './views/datagrid/datagrid_control
 import { DataGridFooterRowExample } from './views/datagrid/datagrid_footer_row_example';
 import { DataGridVirtualizationExample } from './views/datagrid/datagrid_virtualization_example';
 import { DataGridRowHeightOptionsExample } from './views/datagrid/datagrid_height_options_example';
+import { DataGridRefExample } from './views/datagrid/datagrid_ref_example';
 
 import { DatePickerExample } from './views/date_picker/date_picker_example';
 
@@ -489,6 +490,7 @@ const navigation = [
       DataGridFooterRowExample,
       DataGridVirtualizationExample,
       DataGridRowHeightOptionsExample,
+      DataGridRefExample,
       TableExample,
       TableInMemoryExample,
     ].map((example) => createExample(example)),

src-docs/src/views/datagrid/datagrid.js

@@ -6,6 +6,7 @@ import React, {
   createContext,
   useContext,
   useRef,
+  createRef,
 } from 'react';
 import { Link } from 'react-router-dom';
 import { fake } from 'faker';
@@ -29,11 +30,13 @@ import {
   EuiModalHeader,
   EuiModalHeaderTitle,
   EuiPopover,
+  EuiScreenReaderOnly,
   EuiText,
   EuiTitle,
 } from '../../../../src/components/';
-const DataContext = createContext();
 
+const gridRef = createRef();
+const DataContext = createContext();
 const raw_data = [];
 
 for (let i = 1; i < 100; i++) {
@@ -216,13 +219,20 @@ const trailingControlColumns = [
   {
     id: 'actions',
     width: 40,
-    headerCellRender: () => null,
-    rowCellRender: function RowCellRender() {
+    headerCellRender: () => (
+      <EuiScreenReaderOnly>
+        <span>Controls</span>
+      </EuiScreenReaderOnly>
+    ),
+    rowCellRender: function RowCellRender({ rowIndex, colIndex }) {
       const [isPopoverVisible, setIsPopoverVisible] = useState(false);
       const closePopover = () => setIsPopoverVisible(false);
 
       const [isModalVisible, setIsModalVisible] = useState(false);
-      const closeModal = () => setIsModalVisible(false);
+      const closeModal = () => {
+        setIsModalVisible(false);
+        gridRef.current.setFocusedCell({ rowIndex, colIndex });
+      };
       const showModal = () => {
         closePopover();
         setIsModalVisible(true);
@@ -263,7 +273,10 @@ const trailingControlColumns = [
       }
 
       const [isFlyoutVisible, setIsFlyoutVisible] = useState(false);
-      const closeFlyout = () => setIsFlyoutVisible(false);
+      const closeFlyout = () => {
+        setIsFlyoutVisible(false);
+        gridRef.current.setFocusedCell({ rowIndex, colIndex });
+      };
       const showFlyout = () => {
         closePopover();
         setIsFlyoutVisible(true);
@@ -415,6 +428,7 @@ export default () => {
           onChangePage: onChangePage,
         }}
         onColumnResize={onColumnResize.current}
+        ref={gridRef}
       />
     </DataContext.Provider>
   );

src-docs/src/views/datagrid/datagrid_example.js

@@ -33,6 +33,7 @@ import {
   EuiDataGridRowHeightsOptions,
   EuiDataGridCellValueElementProps,
   EuiDataGridSchemaDetector,
+  EuiDataGridRefProps,
 } from '!!prop-loader!../../../../src/components/datagrid/data_grid_types';
 
 const gridSnippet = `
@@ -164,6 +165,8 @@ const gridSnippet = `
         );
       },
     }}
+    // Optional. For advanced control of internal data grid popover/focus state, passes back an object of API methods
+    ref={dataGridRef}
   />
 `;
 
@@ -323,6 +326,19 @@ const gridConcepts = [
       </span>
     ),
   },
+  {
+    title: 'ref',
+    description: (
+      <span>
+        Passes back an object of internal <strong>EuiDataGridRefProps</strong>{' '}
+        methods for advanced control of data grid popover/focus state. See{' '}
+        <Link to="/tabular-content/data-grid-ref-methods">
+          Data grid ref methods
+        </Link>{' '}
+        for more details and examples.
+      </span>
+    ),
+  },
 ];
 
 export const DataGridExample = {
@@ -414,6 +430,7 @@ export const DataGridExample = {
         EuiDataGridToolBarAdditionalControlsLeftOptions,
         EuiDataGridPopoverContentProps,
         EuiDataGridRowHeightsOptions,
+        EuiDataGridRefProps,
       },
       demo: (
         <Fragment>

src-docs/src/views/datagrid/datagrid_ref_example.js

@@ -0,0 +1,117 @@
+import React from 'react';
+
+import { GuideSectionTypes } from '../../components';
+import { EuiCode, EuiSpacer, EuiCallOut } from '../../../../src/components';
+
+import { EuiDataGridRefProps } from '!!prop-loader!../../../../src/components/datagrid/data_grid_types';
+import DataGridRef from './ref';
+const dataGridRefSource = require('!!raw-loader!./ref');
+const dataGridRefSnippet = `const dataGridRef = useRef();
+<EuiDataGrid ref={dataGridRef} {...props} />
+
+// Mnaually toggle the data grid's full screen state
+dataGridRef.current.setIsFullScreen(true);
+
+// Mnaually focus a specific cell within the data grid
+dataGridRef.current.setFocusedCell({ rowIndex, colIndex });
+
+// Manually opens the popover of a specified cell within the data grid
+dataGridRef.current.openCellPopover({ rowIndex, colIndex });
+
+// Close any open cell popover
+dataGridRef.current.closeCellPopover();
+`;
+
+export const DataGridRefExample = {
+  title: 'Data grid ref methods',
+  sections: [
+    {
+      source: [
+        {
+          type: GuideSectionTypes.TSX,
+          code: dataGridRefSource,
+        },
+      ],
+      text: (
+        <>
+          <p>
+            For advanced use cases, and particularly for data grids that manage
+            associated modals/flyouts and need to manually control their grid
+            cell popovers & focus states, we expose certain internal methods via
+            the <EuiCode>ref</EuiCode> prop of <strong>EuiDataGrid</strong>.
+            These methods are:
+          </p>
+          <ul>
+            <li>
+              <p>
+                <EuiCode>setIsFullScreen(isFullScreen)</EuiCode> - controls the
+                full screen state of the data grid. Accepts a true/false boolean
+                flag.
+              </p>
+            </li>
+            <li>
+              <EuiCode>setFocusedCell({'{ rowIndex, colIndex }'})</EuiCode> -
+              focuses the specified cell in the grid.
+              <EuiSpacer size="s" />
+              <EuiCallOut
+                iconType="accessibility"
+                title="Using this method is an accessibility requirement if your data
+                grid toggles a modal or flyout."
+                color="warning"
+              >
+                Your modal or flyout should restore focus into the grid on close
+                to prevent keyboard or screen reader users from being stranded.
+              </EuiCallOut>
+              <EuiSpacer size="m" />
+            </li>
+            <li>
+              <EuiCode>openCellPopover({'{ rowIndex, colIndex }'})</EuiCode> -
+              opens the specified cell&apos;s popover contents.
+              <EuiSpacer size="m" />
+            </li>
+            <li>
+              <p>
+                <EuiCode>closeCellPopover()</EuiCode> - closes any currently
+                open cell popover.
+              </p>
+            </li>
+          </ul>
+
+          <EuiSpacer size="s" />
+
+          <EuiCallOut title="Handling cell location">
+            When using <EuiCode>setFocusedCell</EuiCode> or{' '}
+            <EuiCode>openCellPopover</EuiCode>, keep in mind:
+            <ul>
+              <li>
+                <EuiCode>colIndex</EuiCode> is affected by the user reordering
+                or hiding columns.
+              </li>
+              <li>
+                If the passed cell indices are outside the data grid&apos;s
+                total row count or visible column count, an error will be
+                thrown.
+              </li>
+              <li>
+                If the data grid is paginated or sorted, the grid will handle
+                automatically finding specified row index&apos;s correct
+                location for you.
+              </li>
+            </ul>
+          </EuiCallOut>
+
+          <EuiSpacer />
+
+          <p>
+            The below example shows how to use the internal APIs for a data grid
+            that opens a modal via cell actions.
+          </p>
+        </>
+      ),
+      components: { DataGridRef },
+      demo: <DataGridRef />,
+      snippet: dataGridRefSnippet,
+      props: { EuiDataGridRefProps },
+    },
+  ],
+};