fix: Hide new pageIndex logic behind flag

Author: gethinwebster

src/__tests__/operations/paginate.test.ts

@@ -17,12 +17,23 @@ test('default pagination', () => {
 test('should reset the currentPageIndex to 1 when out of range', () => {
   const items = generateItems(25);
 
-  // Page number is below the minimum
+  // Page number is above the maximum
   let {
     items: processed,
     pagesCount,
     actualPageIndex,
-  } = processItems(items, { currentPageIndex: 0 }, { pagination: {} });
+  } = processItems(items, { currentPageIndex: 4 }, { pagination: {} });
+  expect(actualPageIndex).toEqual(1);
+  expect(pagesCount).toEqual(3);
+  expect(processed).toHaveLength(10);
+  expect(processed[0]).toEqual(items[0]);
+
+  // Page number is below the minimum
+  ({
+    items: processed,
+    pagesCount,
+    actualPageIndex,
+  } = processItems(items, { currentPageIndex: 0 }, { pagination: {} }));
   expect(actualPageIndex).toEqual(1);
   expect(pagesCount).toEqual(3);
   expect(processed).toHaveLength(10);
@@ -40,6 +51,19 @@ test('should reset the currentPageIndex to 1 when out of range', () => {
   expect(processed[0]).toEqual(items[0]);
 });
 
+test('should not reset the currentPageIndex if `allowPageOutOfRange=true`', () => {
+  const items = generateItems(25);
+
+  const {
+    items: processed,
+    pagesCount,
+    actualPageIndex,
+  } = processItems(items, { currentPageIndex: 4 }, { pagination: { allowPageOutOfRange: true } });
+  expect(actualPageIndex).toEqual(4);
+  expect(pagesCount).toEqual(3);
+  expect(processed).toHaveLength(0);
+});
+
 test('displays all items of it is less than the page size', () => {
   const items = generateItems(7);
   const { items: processed, pagesCount } = processItems(items, {}, { pagination: {} });
@@ -87,18 +111,6 @@ test('displays the last page when the number of items is divisible by page size'
   expect(processed[9]).toEqual(items[19]);
 });
 
-test('displays an out of range page', () => {
-  const items = generateItems(20);
-  const {
-    items: processed,
-    pagesCount,
-    actualPageIndex,
-  } = processItems(items, { currentPageIndex: 3 }, { pagination: {} });
-  expect(actualPageIndex).toEqual(3);
-  expect(pagesCount).toEqual(2);
-  expect(processed).toHaveLength(0);
-});
-
 test('supports custom page size', () => {
   const items = generateItems(35);
   const { items: processed, pagesCount } = processItems(

src/__tests__/use-collection.test.tsx

@@ -165,8 +165,8 @@ test('should prevent pagination from going out of bounds', () => {
   expect(getCurrentPage()).toEqual('2');
   expect(getVisibleItems()[0]).toEqual('11');
   fireEvent.click(findNextPage());
-  expect(getCurrentPage()).toEqual('2');
-  expect(getVisibleItems()[0]).toEqual('11');
+  expect(getCurrentPage()).toEqual('1');
+  expect(getVisibleItems()[0]).toEqual('1');
 });
 
 test('should evoke scrollToTop from the ref on pagination, filtering, property filtering and sorting', () => {

src/interfaces.ts

@@ -44,7 +44,7 @@ export interface UseCollectionOptions<T> {
     freeTextFiltering?: PropertyFilterFreeTextFiltering;
   };
   sorting?: { defaultState?: SortingState<T> };
-  pagination?: { defaultPage?: number; pageSize?: number };
+  pagination?: { defaultPage?: number; pageSize?: number; allowPageOutOfRange?: boolean };
   selection?: {
     defaultSelectedItems?: ReadonlyArray<T>;
     keepSelection?: boolean;

src/operations/pagination.ts

@@ -16,7 +16,7 @@ export function createPageProps<T>(
   const pageSize = pagination.pageSize ?? DEFAULT_PAGE_SIZE;
   const pagesCount = Math.ceil(items.length / pageSize);
   let pageIndex = currentPageIndex ?? 1;
-  if (pageIndex < 1 || Number.isNaN(pageIndex)) {
+  if (pageIndex < 1 || (pageIndex > pagesCount && !pagination.allowPageOutOfRange) || Number.isNaN(pageIndex)) {
     pageIndex = 1;
   }
   return { pageSize, pagesCount, pageIndex };