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

CHANGELOG.md

@@ -1,6 +1,6 @@
 ## [`main`](https://github.com/elastic/eui/tree/main)
 
-No public interface changes since `46.2.0`.
+- 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))
 
 ## [`46.2.0`](https://github.com/elastic/eui/tree/v46.2.0)
 

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_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,110 @@
+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 EuiDataGrid. 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."
+              >
+                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="s" />
+              <EuiCallOut iconType="mapMarker" title="Handling cell location">
+                When using <EuiCode>setFocusedCell</EuiCode> or{' '}
+                <EuiCode>openCellPopover</EuiCode>, keep in mind:
+                <ul>
+                  <li>
+                    colIndex 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 size="m" />
+            </li>
+            <li>
+              <p>
+                <EuiCode>closeCellPopover()</EuiCode> - closes any currently
+                open cell popover.
+              </p>
+            </li>
+          </ul>
+          <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 },
+    },
+  ],
+};