Add docs example + copy

cee-chen · cee-chen · commit 4cab7dc5c47c · 2024-03-07T11:13:12.000-08:00
diff --git a/src-docs/src/views/datagrid/_props_table.tsx b/src-docs/src/views/datagrid/_props_table.tsx
@@ -29,6 +29,19 @@ export const DataGridPropsTable: FunctionComponent<{
     .filter((i) => !exclude?.includes(i))
     .sort();
 
+  // Manually move the cellContext prop after renderCellValue
+  const cellContext = gridPropsKeys.splice(
+    gridPropsKeys.findIndex((prop) => prop === 'cellContext'),
+    1
+  )[0];
+  if (cellContext) {
+    gridPropsKeys.splice(
+      gridPropsKeys.findIndex((prop) => prop === 'renderCellValue') + 1,
+      0,
+      cellContext
+    );
+  }
+
   const items: BasicItem[] = gridPropsKeys.map((prop) => {
     return {
       id: prop,
diff --git a/src-docs/src/views/datagrid/_snippets.tsx b/src-docs/src/views/datagrid/_snippets.tsx
@@ -53,6 +53,11 @@ inMemory={{ level: 'sorting' }}`,
   },
 ]}`,
   renderCellValue: 'renderCellValue={({ rowIndex, columnId }) => {}}',
+  cellContext: `cellContext={{
+  // Will be passed to your \`renderCellValue\` function/component as a prop
+  yourData,
+}}
+renderCellValue={({ rowIndex, columnId, yourData }) => {}}`,
   renderCellPopover: `renderCellPopover={({ children, cellActions }) => (
   <>
     <EuiPopoverTitle>I'm a custom popover!</EuiPopoverTitle>
diff --git a/src-docs/src/views/datagrid/basics/_props.tsx b/src-docs/src/views/datagrid/basics/_props.tsx
@@ -24,6 +24,7 @@ const gridLinks = {
   ref: '/tabular-content/data-grid-advanced#ref-methods',
   renderCustomGridBody:
     '/tabular-content/data-grid-advanced#custom-body-renderer',
+  cellContext: '/tabular-content/data-grid-cells-popovers#cell-context',
 };
 
 export const DataGridTopProps = () => {
diff --git a/src-docs/src/views/datagrid/cells_popovers/cell_context.tsx b/src-docs/src/views/datagrid/cells_popovers/cell_context.tsx
@@ -0,0 +1,102 @@
+import React, { useState, useEffect, useCallback, ReactNode } from 'react';
+import { faker } from '@faker-js/faker';
+
+import {
+  EuiDataGrid,
+  EuiDataGridColumn,
+  type RenderCellValue,
+  EuiButton,
+  EuiSpacer,
+  EuiSkeletonText,
+} from '../../../../../src';
+
+type DataType = Array<{ [key: string]: ReactNode }>;
+
+const columns: EuiDataGridColumn[] = [
+  { id: 'firstName' },
+  { id: 'lastName' },
+  { id: 'suffix' },
+  { id: 'boolean' },
+];
+
+const CellValue: RenderCellValue = ({
+  rowIndex,
+  columnId,
+  // Props from cellContext
+  data,
+  isLoading,
+}) => {
+  if (isLoading) {
+    return <EuiSkeletonText lines={1} />;
+  }
+
+  const value = data[rowIndex][columnId];
+  return value;
+};
+
+export default () => {
+  const [visibleColumns, setVisibleColumns] = useState(
+    columns.map(({ id }) => id)
+  );
+
+  const [data, setData] = useState<DataType>([]);
+  const [cellContext, setCellContext] = useState({
+    data,
+    isLoading: false,
+  });
+
+  // Mock fetching data from an async API
+  const mockLoading = useCallback(() => {
+    setCellContext((context) => ({
+      ...context,
+      isLoading: true,
+    }));
+
+    // End the loading state after 3 seconds
+    const timeout = setTimeout(() => {
+      setCellContext((context) => ({
+        ...context,
+        isLoading: false,
+      }));
+    }, 3000);
+    return () => clearTimeout(timeout);
+  }, []);
+
+  const fetchData = useCallback(() => {
+    mockLoading();
+
+    const data: DataType = [];
+    for (let i = 1; i < 5; i++) {
+      data.push({
+        firstName: faker.person.firstName(),
+        lastName: faker.person.lastName(),
+        suffix: faker.person.suffix(),
+        boolean: `${faker.datatype.boolean()}`,
+      });
+    }
+    setData(data);
+    setCellContext((context) => ({ ...context, data }));
+  }, [mockLoading]);
+
+  // Fetch data on page load
+  useEffect(() => {
+    fetchData();
+  }, [fetchData]);
+
+  return (
+    <>
+      <EuiButton size="s" onClick={fetchData}>
+        Fetch grid data
+      </EuiButton>
+      <EuiSpacer size="s" />
+      <EuiDataGrid
+        aria-label="Data grid example of cellContext"
+        columns={columns}
+        columnVisibility={{ visibleColumns, setVisibleColumns }}
+        rowCount={data.length}
+        renderCellValue={CellValue}
+        cellContext={cellContext}
+      />
+    </>
+  );
+};
diff --git a/src-docs/src/views/datagrid/cells_popovers/datagrid_cells_example.js b/src-docs/src/views/datagrid/cells_popovers/datagrid_cells_example.js
@@ -21,6 +21,9 @@ import { DataGridCellPopoverExample } from './datagrid_cell_popover_example';
 import DataGridFocus from './focus';
 const dataGridFocusSource = require('!!raw-loader!./focus');
 
+import CellContext from './cell_context';
+const cellContextSource = require('!!raw-loader!./cell_context');
+
 import {
   EuiDataGridColumn,
   EuiDataGridColumnCellAction,
@@ -218,5 +221,32 @@ export const DataGridCellsExample = {
       ),
       demo: <DataGridFocus />,
     },
+    {
+      title: 'Cell context',
+      source: [
+        {
+          type: GuideSectionTypes.TSX,
+          code: cellContextSource,
+        },
+      ],
+      text: (
+        <>
+          <p>
+            The <EuiCode>cellContext</EuiCode> prop is an easy way of passing
+            your custom data or context from the top level of{' '}
+            <strong>EuiDataGrid</strong> down to the cell content rendered by
+            your <EuiCode>renderCellValue</EuiCode> function component.
+          </p>
+          <p>
+            The primary use of the cell context API is performance: if your data
+            relies on state from your app, it allows you to more easily define
+            your <EuiCode>renderCellValue</EuiCode> function statically, instead
+            of within your app, which in turn reduces the number of rerenders
+            within your data grid.
+          </p>
+        </>
+      ),
+      demo: <CellContext />,
+    },
   ],
 };
