@patternfly/react-data-view 5.0.0 → 5.1.0

package/dist/cjs/Hooks/pagination.d.ts

@@ -1,14 +1,26 @@
+export declare enum PaginationParams {
+    PAGE = "page",
+    PER_PAGE = "perPage"
+}
 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;
+    /** Custom URL parameter name for page */
+    pageParam?: string;
+    /** Custom URL parameter name for per page */
+    perPageParam?: string;
 }
 export interface DataViewPaginationProps extends UseDataViewPaginationProps {
     /** Current page number */
     page: number;
 }
-export declare const useDataViewPagination: ({ page, perPage }: UseDataViewPaginationProps) => {
+export declare const useDataViewPagination: ({ page, perPage, searchParams, setSearchParams, pageParam, perPageParam, }: UseDataViewPaginationProps) => {
     onPerPageSelect: (_event: React.MouseEvent | React.KeyboardEvent | MouseEvent | undefined, newPerPage: number) => void;
     onSetPage: (_event: React.MouseEvent | React.KeyboardEvent | MouseEvent | undefined, newPage: number) => void;
     page: number;

package/dist/cjs/Hooks/pagination.js

@@ -1,13 +1,45 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useDataViewPagination = void 0;
+exports.useDataViewPagination = exports.PaginationParams = void 0;
 const react_1 = require("react");
-const useDataViewPagination = ({ page = 1, perPage }) => {
-    const [state, setState] = (0, react_1.useState)({ page, perPage });
+var PaginationParams;
+(function (PaginationParams) {
+    PaginationParams["PAGE"] = "page";
+    PaginationParams["PER_PAGE"] = "perPage";
+})(PaginationParams || (exports.PaginationParams = PaginationParams = {}));
+const useDataViewPagination = ({ page = 1, perPage, searchParams, setSearchParams, pageParam = PaginationParams.PAGE, perPageParam = PaginationParams.PER_PAGE, }) => {
+    const [state, setState] = (0, react_1.useState)({
+        page: parseInt((searchParams === null || searchParams === void 0 ? void 0 : searchParams.get(pageParam)) || `${page}`),
+        perPage: parseInt((searchParams === null || searchParams === void 0 ? void 0 : searchParams.get(perPageParam)) || `${perPage}`),
+    });
+    const updateSearchParams = (page, perPage) => {
+        if (searchParams && setSearchParams) {
+            const params = new URLSearchParams(searchParams);
+            params.set(pageParam, `${page}`);
+            params.set(perPageParam, `${perPage}`);
+            setSearchParams(params);
+        }
+    };
+    (0, react_1.useEffect)(() => {
+        // Make sure search params are loaded or set if not present on mount
+        updateSearchParams(state.page, state.perPage);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    (0, react_1.useEffect)(() => {
+        // Listen on URL params changes
+        const currentPage = parseInt((searchParams === null || searchParams === void 0 ? void 0 : searchParams.get(pageParam)) || `${state.page}`);
+        const currentPerPage = parseInt((searchParams === null || searchParams === void 0 ? void 0 : searchParams.get(perPageParam)) || `${state.perPage}`);
+        if (currentPage !== state.page || currentPerPage !== state.perPage) {
+            setState({ page: currentPage, perPage: currentPerPage });
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [searchParams === null || searchParams === void 0 ? void 0 : searchParams.toString()]);
     const onPerPageSelect = (_event, newPerPage) => {
-        setState(prev => (Object.assign(Object.assign({}, prev), { perPage: newPerPage })));
+        updateSearchParams(1, newPerPage);
+        setState({ perPage: newPerPage, page: 1 });
     };
     const onSetPage = (_event, newPage) => {
+        updateSearchParams(newPage, state.perPage);
         setState(prev => (Object.assign(Object.assign({}, prev), { page: newPage })));
     };
     return Object.assign(Object.assign({}, state), { onPerPageSelect,

package/dist/cjs/Hooks/pagination.test.js

@@ -42,8 +42,60 @@ 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 } = (0, react_1.renderHook)(() => (0, pagination_1.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 } = (0, react_1.renderHook)(() => (0, pagination_1.useDataViewPagination)({
+            searchParams: new URLSearchParams(),
+            setSearchParams: mockSetSearchParams,
+            page: 1,
+            perPage: 5,
+        }));
+        expect(mockSetSearchParams).toHaveBeenNthCalledWith(1, new URLSearchParams('page=1&perPage=5'));
+        (0, react_1.act)(() => {
+            result.current.onSetPage(undefined, 4);
+        });
+        expect(mockSetSearchParams).toHaveBeenNthCalledWith(2, new URLSearchParams('page=4&perPage=5'));
+    });
+    it('should set pagination state in URL when perPage changes', () => {
+        const mockSetSearchParams = jest.fn();
+        const { result } = (0, react_1.renderHook)(() => (0, pagination_1.useDataViewPagination)({
+            searchParams: new URLSearchParams('page=2'),
+            setSearchParams: mockSetSearchParams,
+            page: 1,
+            perPage: 5,
+        }));
+        (0, react_1.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();
+        (0, react_1.renderHook)(() => (0, pagination_1.useDataViewPagination)({
+            searchParams: new URLSearchParams(),
+            setSearchParams: mockSetSearchParams,
+            page: 1,
+            perPage: 5,
+        }));
+        expect(mockSetSearchParams).toHaveBeenCalledWith(new URLSearchParams('page=1&perPage=5'));
+    });
 });

package/dist/esm/Hooks/pagination.d.ts

@@ -1,14 +1,26 @@
+export declare enum PaginationParams {
+    PAGE = "page",
+    PER_PAGE = "perPage"
+}
 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;
+    /** Custom URL parameter name for page */
+    pageParam?: string;
+    /** Custom URL parameter name for per page */
+    perPageParam?: string;
 }
 export interface DataViewPaginationProps extends UseDataViewPaginationProps {
     /** Current page number */
     page: number;
 }
-export declare const useDataViewPagination: ({ page, perPage }: UseDataViewPaginationProps) => {
+export declare const useDataViewPagination: ({ page, perPage, searchParams, setSearchParams, pageParam, perPageParam, }: UseDataViewPaginationProps) => {
     onPerPageSelect: (_event: React.MouseEvent | React.KeyboardEvent | MouseEvent | undefined, newPerPage: number) => void;
     onSetPage: (_event: React.MouseEvent | React.KeyboardEvent | MouseEvent | undefined, newPage: number) => void;
     page: number;

package/dist/esm/Hooks/pagination.js

@@ -1,10 +1,42 @@
-import { useState } from "react";
-export const useDataViewPagination = ({ page = 1, perPage }) => {
-    const [state, setState] = useState({ page, perPage });
+import { useState, useEffect } from "react";
+export var PaginationParams;
+(function (PaginationParams) {
+    PaginationParams["PAGE"] = "page";
+    PaginationParams["PER_PAGE"] = "perPage";
+})(PaginationParams || (PaginationParams = {}));
+export const useDataViewPagination = ({ page = 1, perPage, searchParams, setSearchParams, pageParam = PaginationParams.PAGE, perPageParam = PaginationParams.PER_PAGE, }) => {
+    const [state, setState] = useState({
+        page: parseInt((searchParams === null || searchParams === void 0 ? void 0 : searchParams.get(pageParam)) || `${page}`),
+        perPage: parseInt((searchParams === null || searchParams === void 0 ? void 0 : searchParams.get(perPageParam)) || `${perPage}`),
+    });
+    const updateSearchParams = (page, perPage) => {
+        if (searchParams && setSearchParams) {
+            const params = new URLSearchParams(searchParams);
+            params.set(pageParam, `${page}`);
+            params.set(perPageParam, `${perPage}`);
+            setSearchParams(params);
+        }
+    };
+    useEffect(() => {
+        // Make sure search params are loaded or set if not present on mount
+        updateSearchParams(state.page, state.perPage);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    useEffect(() => {
+        // Listen on URL params changes
+        const currentPage = parseInt((searchParams === null || searchParams === void 0 ? void 0 : searchParams.get(pageParam)) || `${state.page}`);
+        const currentPerPage = parseInt((searchParams === null || searchParams === void 0 ? void 0 : searchParams.get(perPageParam)) || `${state.perPage}`);
+        if (currentPage !== state.page || currentPerPage !== state.perPage) {
+            setState({ page: currentPage, perPage: currentPerPage });
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [searchParams === null || searchParams === void 0 ? void 0 : searchParams.toString()]);
     const onPerPageSelect = (_event, newPerPage) => {
-        setState(prev => (Object.assign(Object.assign({}, prev), { perPage: newPerPage })));
+        updateSearchParams(1, newPerPage);
+        setState({ perPage: newPerPage, page: 1 });
     };
     const onSetPage = (_event, newPage) => {
+        updateSearchParams(newPage, state.perPage);
         setState(prev => (Object.assign(Object.assign({}, prev), { page: newPage })));
     };
     return Object.assign(Object.assign({}, state), { onPerPageSelect,

package/dist/esm/Hooks/pagination.test.js

@@ -40,8 +40,60 @@ 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,
+        }));
+        expect(mockSetSearchParams).toHaveBeenNthCalledWith(1, new URLSearchParams('page=1&perPage=5'));
+        act(() => {
+            result.current.onSetPage(undefined, 4);
+        });
+        expect(mockSetSearchParams).toHaveBeenNthCalledWith(2, new URLSearchParams('page=4&perPage=5'));
+    });
+    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'));
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patternfly/react-data-view",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "Data view used for Red Hat projects.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

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

@@ -18,6 +18,7 @@ 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**.
 
@@ -25,7 +26,7 @@ This is a list of functionality you can use to manage data displayed in the **da
 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,14 @@ 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.
+
+You can also pass custom `pageParam` or `perPageParam` names, renaming the pagination parameters in the URL.
+
+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 +51,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"
 
 ```

package/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>
+)

package/release.config.js

@@ -2,7 +2,7 @@ module.exports = {
   branches: [
     'do-not-delete',
     { name: 'main', channel: 'prerelease', prerelease: 'prerelease' },
-    { name: 'v5', channel: 'prerelease-v5' },
+    { name: 'v5', channel: 'prerelease-v5', range: '5.x' },
   ],
   analyzeCommits: {
     preset: 'angular'

package/src/Hooks/pagination.test.tsx

@@ -49,9 +49,89 @@ 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,
+      })
+    );
+
+    expect(mockSetSearchParams).toHaveBeenNthCalledWith(
+      1, 
+      new URLSearchParams('page=1&perPage=5')
+    );
+
+    act(() => {
+      result.current.onSetPage(undefined, 4);
+    });
+
+    expect(mockSetSearchParams).toHaveBeenNthCalledWith(
+      2,
+      new URLSearchParams('page=4&perPage=5')
+    );
+  });
+
+  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')
+    );
+  });
 });

package/src/Hooks/pagination.ts

@@ -1,31 +1,87 @@
-import { useState } from "react";
+import { useState, useEffect } from "react";
+
+export enum PaginationParams {
+  PAGE = 'page',
+  PER_PAGE = 'perPage'
+}
 
 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;
+  /** Custom URL parameter name for page */
+  pageParam?: string;
+  /** Custom URL parameter name for per page */
+  perPageParam?: string;
 }
 
 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,
+  pageParam = PaginationParams.PAGE,
+  perPageParam = PaginationParams.PER_PAGE,
+}: UseDataViewPaginationProps) => {
+  const [ state, setState ] = useState({
+    page: parseInt(searchParams?.get(pageParam) || `${page}`),
+    perPage: parseInt(searchParams?.get(perPageParam) || `${perPage}`),
+  });
+
+  const updateSearchParams = (page: number, perPage: number) => {
+    if (searchParams && setSearchParams) {
+      const params = new URLSearchParams(searchParams);
+      params.set(pageParam, `${page}`);
+      params.set(perPageParam, `${perPage}`);
+      setSearchParams(params);
+    }
+  };
+
+  useEffect(() => {
+    // Make sure search params are loaded or set if not present on mount
+    updateSearchParams(state.page, state.perPage);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    // Listen on URL params changes
+    const currentPage = parseInt(searchParams?.get(pageParam) || `${state.page}`);
+    const currentPerPage = parseInt(searchParams?.get(perPageParam) || `${state.perPage}`);
+    if (currentPage !== state.page || currentPerPage !== state.perPage) {
+      setState({ page: currentPage, perPage: currentPerPage });
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [ searchParams?.toString() ]);
+
+  const onPerPageSelect = (
+    _event: React.MouseEvent | React.KeyboardEvent | MouseEvent | undefined,
+    newPerPage: number
+  ) => {
+    updateSearchParams(1, newPerPage);
+    setState({ perPage: newPerPage, page: 1 });
+  };
+
+  const onSetPage = (
+    _event: React.MouseEvent | React.KeyboardEvent | MouseEvent | undefined,
+    newPage: number
+  ) => {
+    updateSearchParams(newPage, state.perPage);
     setState(prev => ({ ...prev, page: newPage }));
-  }
-  
+  };
+
   return {
     ...state,
     onPerPageSelect,
-    onSetPage
-  }
-}
+    onSetPage,
+  };
+};