fix(pagination): Enhance useDataViewPagination with URL persisting

Author: fhlavac

packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/Functionality.md

@@ -18,14 +18,15 @@ import { useDataViewPagination, useDataViewSelection } from '@patternfly/react-d
 import { DataView } from '@patternfly/react-data-view/dist/dynamic/DataView';
 import { BulkSelect, BulkSelectValue } from '@patternfly/react-component-groups/dist/dynamic/BulkSelect';
 import { DataViewToolbar } from '@patternfly/react-data-view/dist/dynamic/DataViewToolbar';
+import { BrowserRouter, useSearchParams } from 'react-router-dom';
 
 This is a list of functionality you can use to manage data displayed in the **data view**.
 
 # Pagination
 Allows to display data records on multiple pages and display the pagination state.
 
 ### Toolbar usage
-Data view toolbar can display a pagination using the `pagination` property accepting a React node. You can also pass a custom `ouiaId` for testing purposes.
+Data view toolbar can display a pagination using the `pagination` property accepting a React node. You can also pass a custom `ouiaId` for testing purposes. Additionally, it offers an option to persist pagination values in the URL, which makes it easier to share or bookmark specific pages of your data.
 
 ### Pagination state
 
@@ -34,8 +35,12 @@ The `useDataViewPagination` hook manages the pagination state of the data view.
 **Initial values:**
 - `perPage` initial value
 - (optional) `page` initial value
+- (optional) `searchParams` object
+- (optional) `seSearchParams` function
 
-The retrieved values are named to match the PatternFly [pagination](/components/pagination) component props, so you can easily spread them.
+While the hook works seamlessly with React Router library, you do not need to use it to take advantage of URL persistence. The `searchParams` and `setSearchParams` props can be managed using native browser APIs (`URLSearchParams` and `window.history.pushState`) or any other routing library of your choice. If you don't pass these two props, the pagination state will be stored internally without the URL usage.
+
+The retrieved values are named to match the PatternFly [pagination](/components/pagination) component props, so you can easily spread them to the component.
 
 **Return values:**
 - current `page` number
@@ -44,6 +49,8 @@ The retrieved values are named to match the PatternFly [pagination](/components/
 - `onPerPageSelect` to modify per page value
 
 ### Pagination example
+This example uses the URL for persisting the pagination state.
+
 ```js file="./PaginationExample.tsx"
 
 ```

packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/PaginationExample.tsx

@@ -4,6 +4,7 @@ import { Table, Tbody, Th, Thead, Tr, Td } from '@patternfly/react-table';
 import { useDataViewPagination } from '@patternfly/react-data-view/dist/dynamic/Hooks';
 import DataView from '@patternfly/react-data-view/dist/dynamic/DataView';
 import DataViewToolbar from '@patternfly/react-data-view/dist/dynamic/DataViewToolbar';
+import { BrowserRouter, useSearchParams } from 'react-router-dom';
 
 const perPageOptions = [
   { title: '5', value: 5 },
@@ -37,12 +38,12 @@ const cols = {
 
 const ouiaId = 'LayoutExample';
 
-export const BasicExample: React.FunctionComponent = () => { 
-  const pagination = useDataViewPagination({ perPage: 5 });
+const MyTable: React.FunctionComponent = () => {
+  const [ searchParams, setSearchParams ] = useSearchParams()
+  const pagination = useDataViewPagination({ perPage: 5, searchParams, setSearchParams });
   const { page, perPage } = pagination;
 
   const data = useMemo(() => repositories.slice((page - 1) * perPage, ((page - 1) * perPage) + perPage), [ page, perPage ]);
-
   return (
     <DataView>
       <DataViewToolbar ouiaId='DataViewHeader' pagination={<Pagination perPageOptions={perPageOptions} itemCount={repositories.length} {...pagination} />} />
@@ -62,4 +63,11 @@ export const BasicExample: React.FunctionComponent = () => {
       </Table>
       <DataViewToolbar ouiaId='DataViewFooter' pagination={<Pagination isCompact perPageOptions={perPageOptions} itemCount={repositories.length} {...pagination} />} />
     </DataView>
-  )}
+  )
+}
+
+export const BasicExample: React.FunctionComponent = () => (
+  <BrowserRouter>
+    <MyTable/>
+  </BrowserRouter>
+)

packages/module/src/Hooks/pagination.test.tsx

@@ -49,9 +49,81 @@ describe('useDataViewPagination', () => {
     expect(result.current).toEqual({ 
       onPerPageSelect: expect.any(Function),
       onSetPage: expect.any(Function),
-      page: 3,
+      page: 1,
       perPage: 50
     })
   });
 
+  it('should read pagination state from URL', () => {
+    const mockSearchParams = new URLSearchParams('page=2&perPage=10');
+    const { result } = renderHook(() =>
+      useDataViewPagination({
+        searchParams: mockSearchParams,
+        setSearchParams: jest.fn(),
+        page: 1,
+        perPage: 5,
+      })
+    );
+
+    expect(result.current).toEqual({
+      onPerPageSelect: expect.any(Function),
+      onSetPage: expect.any(Function),
+      page: 2,
+      perPage: 10,
+    });
+  });
+
+  it('should set pagination state in URL when page changes', () => {
+    const mockSetSearchParams = jest.fn();
+    const { result } = renderHook(() =>
+      useDataViewPagination({
+        searchParams: new URLSearchParams(),
+        setSearchParams: mockSetSearchParams,
+        page: 1,
+        perPage: 5,
+      })
+    );
+
+    act(() => {
+      result.current.onSetPage(undefined, 4);
+    });
+
+    expect(mockSetSearchParams).toHaveBeenCalledTimes(2);
+  });
+
+  it('should set pagination state in URL when perPage changes', () => {
+    const mockSetSearchParams = jest.fn();
+    const { result } = renderHook(() =>
+      useDataViewPagination({
+        searchParams: new URLSearchParams('page=2'),
+        setSearchParams: mockSetSearchParams,
+        page: 1,
+        perPage: 5,
+      })
+    );
+
+    act(() => {
+      result.current.onPerPageSelect(undefined, 20);
+    });
+
+    expect(mockSetSearchParams).toHaveBeenCalledWith(
+      new URLSearchParams('page=1&perPage=20')
+    );
+  });
+
+  it('should initialize URL with default values if not present', () => {
+    const mockSetSearchParams = jest.fn();
+    renderHook(() =>
+      useDataViewPagination({
+        searchParams: new URLSearchParams(),
+        setSearchParams: mockSetSearchParams,
+        page: 1,
+        perPage: 5,
+      })
+    );
+
+    expect(mockSetSearchParams).toHaveBeenCalledWith(
+      new URLSearchParams('page=1&perPage=5')
+    );
+  });
 });

packages/module/src/Hooks/pagination.ts

@@ -1,31 +1,84 @@
-import { useState } from "react";
+import { useState, useEffect } from "react";
 
 export interface UseDataViewPaginationProps {
   /** Initial page */
   page?: number;
   /** Items per page */
   perPage: number;
+  /** Current search parameters as a string */
+  searchParams?: URLSearchParams;
+  /** Function to set search parameters */
+  setSearchParams?: (params: URLSearchParams) => void;
 }
 
 export interface DataViewPaginationProps extends UseDataViewPaginationProps {
   /** Current page number */
-    page: number;
+  page: number;
 }
 
-export const useDataViewPagination = ({ page = 1, perPage }: UseDataViewPaginationProps) => { 
-  const [ state, setState ] = useState({ page, perPage });
-  
-  const onPerPageSelect = (_event: React.MouseEvent | React.KeyboardEvent | MouseEvent | undefined, newPerPage: number) => {
-    setState(prev => ({ ...prev, perPage: newPerPage }));
-  }
-  
-  const onSetPage = (_event: React.MouseEvent | React.KeyboardEvent | MouseEvent | undefined, newPage: number) => {
+export const useDataViewPagination = ({
+  page = 1,
+  perPage,
+  searchParams,
+  setSearchParams,
+}: UseDataViewPaginationProps) => {
+  const [ state, setState ] = useState({
+    page: searchParams?.get('page') !== null
+      ? parseInt(searchParams?.get('page') || `${page}`)
+      : page,
+    perPage: searchParams?.get('perPage') !== null
+      ? parseInt(searchParams?.get('perPage') || `${perPage}`)
+      : perPage,
+  });
+
+  useEffect(() => {
+    if (searchParams && setSearchParams) {
+      const params = new URLSearchParams(searchParams);
+      let updated = false;
+
+      if (!params.has('page')) {
+        params.set('page', `${page}`);
+        updated = true;
+      }
+
+      if (!params.has('perPage')) {
+        params.set('perPage', `${perPage}`);
+        updated = true;
+      }
+
+      updated && setSearchParams(params);
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const onPerPageSelect = (
+    _event: React.MouseEvent | React.KeyboardEvent | MouseEvent | undefined,
+    newPerPage: number
+  ) => {
+    if (searchParams && setSearchParams) {
+      const params = new URLSearchParams(searchParams);
+      params.set('perPage', newPerPage.toString());
+      params.set('page', '1');
+      setSearchParams(params);
+    }
+    setState({ perPage: newPerPage, page: 1 });
+  };
+
+  const onSetPage = (
+    _event: React.MouseEvent | React.KeyboardEvent | MouseEvent | undefined,
+    newPage: number
+  ) => {
+    if (searchParams && setSearchParams) {
+      const params = new URLSearchParams(searchParams);
+      params.set('page', newPage.toString());
+      setSearchParams(params);
+    }
     setState(prev => ({ ...prev, page: newPage }));
-  }
-  
+  };
+
   return {
     ...state,
     onPerPageSelect,
     onSetPage
-  }
-}
+  };
+};