[XGrid] Add onViewportRowsChange prop

docs/pages/api-docs/data-grid/x-grid.md

@@ -91,6 +91,7 @@ import { XGrid } from '@material-ui/x-grid';
 | <span class="prop-name">onRowsScrollEnd</span> | <span class="prop-type">(param: GridRowScrollEndParams) => void</span> |   | Callback fired when scrolling to the bottom of the grid viewport. |
 | <span class="prop-name">onSelectionModelChange</span> | <span class="prop-type">(param: GridSelectionModelChangeParams) => void</span> |   | Callback fired when the selection state of one or multiple rows changes. |
 | <span class="prop-name">onSortModelChange</span> | <span class="prop-type">(param: GridSortModelParams) => void</span> |   | Callback fired when the sort model changes before a column is sorted. |
+| <span class="prop-name">onVirtualPageChange</span> | <span class="prop-type">(param: GridVirtualPageChangeParams) => void</span> |   | Callback fired when the virtual page changes. |
 | <span class="prop-name">page</span> | <span class="prop-type">number</span> | 1   |  Set the current page. |
 | <span class="prop-name">pageSize</span> | <span class="prop-type">number</span> | 100 | Set the number of rows in one page. |
 | <span class="prop-name">pagination</span> | <span class="prop-type">boolean</span> | false | If `true`, pagination is enabled. |

docs/src/pages/components/data-grid/events/events.json

@@ -181,5 +181,9 @@
   {
     "name": "columnVisibilityChange",
     "description": "Fired when a column visibility changes. Called with a GridColumnVisibilityChangeParams object."
+  },
+  {
+    "name": "virtualPageChange",
+    "description": "Fired when a the virtual page changes. Called with a GridVirtualPageChangeParams object."
   }
 ]

packages/grid/_modules_/grid/constants/eventsConstants.ts

@@ -457,3 +457,9 @@ export const GRID_STATE_CHANGE = 'stateChange';
  * @event
  */
 export const GRID_COLUMN_VISIBILITY_CHANGE = 'columnVisibilityChange';
+
+/**
+ * Fired when a the virtual page changes. Called with a [[GridVirtualPageChangeParams]] object.
+ * @event
+ */
+export const GRID_VIRTUAL_PAGE_CHANGE = 'virtualPageChange';

packages/grid/_modules_/grid/hooks/features/virtualization/useGridVirtualRows.ts

@@ -1,5 +1,9 @@
 import * as React from 'react';
-import { GRID_SCROLL, GRID_ROWS_SCROLL } from '../../../constants/eventsConstants';
+import {
+  GRID_SCROLL,
+  GRID_ROWS_SCROLL,
+  GRID_VIRTUAL_PAGE_CHANGE,
+} from '../../../constants/eventsConstants';
 import { GridApiRef } from '../../../models/api/gridApiRef';
 import { GridVirtualizationApi } from '../../../models/api/gridVirtualizationApi';
 import { GridCellIndexCoordinates } from '../../../models/gridCell';
@@ -25,6 +29,7 @@ import { InternalRenderingState } from './renderingState';
 import { useGridVirtualColumns } from './useGridVirtualColumns';
 import { gridDensityRowHeightSelector } from '../density/densitySelector';
 import { scrollStateSelector } from './renderingStateSelector';
+import { useGridApiOptionHandler } from '../../root/useGridApiEventHandler';
 
 export const useGridVirtualRows = (apiRef: GridApiRef): void => {
   const logger = useLogger('useGridVirtualRows');
@@ -148,6 +153,14 @@ export const useGridVirtualRows = (apiRef: GridApiRef): void => {
         setRenderingState({ virtualPage: nextPage });
         logger.debug(`Changing page from ${page} to ${nextPage}`);
         requireRerender = true;
+
+        apiRef.current.publishEvent(GRID_VIRTUAL_PAGE_CHANGE, {
+          currentPage: nextPage,
+          nextPage: nextPage + 1 < containerProps.lastPage ? nextPage + 1 : containerProps.lastPage,
+          firstRowIndex: nextPage * containerProps.viewportPageSize,
+          pageSize: containerProps.viewportPageSize,
+          api: apiRef,
+        });
       } else {
         if (!containerProps.isVirtualized && page > 0) {
           logger.debug(`Virtualization disabled, setting virtualPage to 0`);
@@ -405,4 +418,5 @@ export const useGridVirtualRows = (apiRef: GridApiRef): void => {
     GRID_SCROLL,
     preventViewportScroll,
   );
+  useGridApiOptionHandler(apiRef, GRID_VIRTUAL_PAGE_CHANGE, options.onVirtualPageChange);
 };

packages/grid/_modules_/grid/models/gridOptions.tsx

@@ -30,6 +30,7 @@ import { GridResizeParams } from './params/gridResizeParams';
 import { GridColumnResizeParams } from './params/gridColumnResizeParams';
 import { GridColumnVisibilityChangeParams } from './params/gridColumnVisibilityChangeParams';
 import { GridClasses } from './gridClasses';
+import { GridVirtualPageChangeParams } from './params/gridVirtualPageChangeParams';
 
 export type MuiEvent<E> = (E | React.SyntheticEvent) & {
   defaultMuiPrevented?: boolean;
@@ -431,6 +432,10 @@ export interface GridOptions {
    * Callback fired when the state of the grid is updated.
    */
   onStateChange?: (params: any) => void;
+  /**
+   * Callback fired when the virtual page changes.
+   */
+  onVirtualPageChange?: (params: GridVirtualPageChangeParams) => void;
   /**
    * Set the current page.
    * @default 1

packages/grid/_modules_/grid/models/params/gridVirtualPageChangeParams.ts

@@ -0,0 +1,25 @@
+/**
+ * Object passed as parameter of the virtual page change event.
+ */
+export interface GridVirtualPageChangeParams {
+  /**
+   * The index of the current page.
+   */
+  currentPage: number;
+  /**
+   * The index of the next page.
+   */
+  nextPage: number;
+  /**
+   * The index of the first row in the current page.
+   */
+  firstRowIndex: number;
+  /**
+   * The size of the virtual page.
+   */
+  pageSize: number;
+  /**
+   * Api that let you manipulate the grid.
+   */
+  api: any;
+}

packages/grid/data-grid/src/DataGrid.tsx

@@ -27,6 +27,7 @@ export type DataGridProps = Omit<
   | 'licenseStatus'
   | 'options'
   | 'onRowsScrollEnd'
+  | 'onVirtualPageChange'
   | 'pagination'
   | 'scrollEndThreshold'
 > & {
@@ -38,6 +39,7 @@ export type DataGridProps = Omit<
   disableMultipleColumnsSorting?: true;
   disableMultipleSelection?: true;
   onRowsScrollEnd?: undefined;
+  onVirtualPageChange?: undefined;
   pagination?: true;
 };
 
@@ -187,6 +189,19 @@ DataGrid.propTypes = {
     }
     return null;
   }),
+  onVirtualPageChange: chainPropTypes(PropTypes.any, (props: any) => {
+    if (props.onVirtualPageChange != null) {
+      return new Error(
+        [
+          `Material-UI: \`onVirtualPageChange\` is not a valid prop.`,
+          'onVirtualPageChange is not available in the MIT version.',
+          '',
+          'You need to upgrade to the XGrid component to unlock this feature.',
+        ].join('\n'),
+      );
+    }
+    return null;
+  }),
   pageSize: chainPropTypes(PropTypes.number, (props: any) => {
     if (props.pageSize && props.pageSize > MAX_PAGE_SIZE) {
       return new Error(

packages/grid/x-grid/src/tests/events.XGrid.test.tsx

@@ -20,6 +20,7 @@ import {
 } from '@material-ui/x-grid';
 import { getCell, getColumnHeaderCell, getRow } from 'test/utils/helperFn';
 import { spy } from 'sinon';
+import { useData } from 'packages/storybook/src/hooks/useData';
 
 describe('<XGrid /> - Events Params', () => {
   // TODO v5: replace with createClientRender
@@ -72,6 +73,16 @@ describe('<XGrid /> - Events Params', () => {
     );
   };
 
+  const TestVirtualization = (props: Partial<XGridProps>) => {
+    apiRef = useGridApiRef();
+    const data = useData(50, 10);
+    return (
+      <div style={{ width: 300, height: 300 }}>
+        <XGrid rows={data.rows} columns={data.columns} apiRef={apiRef} {...props} />
+      </div>
+    );
+  };
+
   describe('columnHeaderParams', () => {
     it('should include the correct params', () => {
       let eventArgs: { params: GridColumnHeaderParams; event: React.MouseEvent } | null = null;
@@ -284,4 +295,23 @@ describe('<XGrid /> - Events Params', () => {
     gridWindow.dispatchEvent(new Event('scroll'));
     expect(handleOnRowsScrollEnd.callCount).to.equal(1);
   });
+
+  it('call onVirtualPageChange when the virtual page changes', () => {
+    const handleOnVirtualPageChange = spy();
+    const { container } = render(
+      <div style={{ width: 300, height: 300 }}>
+        <TestVirtualization onVirtualPageChange={handleOnVirtualPageChange} />
+      </div>,
+    );
+    const gridWindow = container.querySelector('.MuiDataGrid-window');
+    // arbitrary number to make sure that the bottom of the grid window is reached.
+    gridWindow.scrollTop = 12345;
+    gridWindow.dispatchEvent(new Event('scroll'));
+
+    expect(handleOnVirtualPageChange.callCount).to.equal(1);
+    expect(handleOnVirtualPageChange.lastCall.args[0].currentPage).to.equal(15);
+    expect(handleOnVirtualPageChange.lastCall.args[0].nextPage).to.equal(16);
+    expect(handleOnVirtualPageChange.lastCall.args[0].firstRowIndex).to.equal(45);
+    expect(handleOnVirtualPageChange.lastCall.args[0].pageSize).to.equal(3);
+  });
 });