@openmrs/esm-react-utils 10.0.1-pre.5295 → 10.0.1-pre.5309

package/.turbo/turbo-build.log

@@ -1,3 +1,3 @@
-[0] Successfully compiled: 55 files with swc (152.36ms)
+[0] Successfully compiled: 55 files with swc (154.06ms)
 [0] swc --strip-leading-paths src -d dist exited with code 0
 [1] tsc --project tsconfig.build.json exited with code 0

package/dist/useFhirPagination.d.ts

@@ -28,7 +28,7 @@ export declare function useFhirPagination<T extends fhir.ResourceBase>(url: stri
     totalPages: number;
     totalCount: number;
     currentPage: number;
-    currentPageSize: import("react").MutableRefObject<number>;
+    currentPageSize: number;
     paginated: boolean;
     showNextButton: boolean;
     showPreviousButton: boolean;

package/dist/useOpenmrsPagination.d.ts

@@ -61,7 +61,7 @@ export declare function useOpenmrsPagination<T>(url: string | URL, pageSize: num
     totalPages: number;
     totalCount: number;
     currentPage: number;
-    currentPageSize: import("react").MutableRefObject<number>;
+    currentPageSize: number;
     paginated: boolean;
     showNextButton: boolean;
     showPreviousButton: boolean;
@@ -87,7 +87,7 @@ export declare function useServerPagination<T, R>(url: string | URL, pageSize: n
     totalPages: number;
     totalCount: number;
     currentPage: number;
-    currentPageSize: import("react").MutableRefObject<number>;
+    currentPageSize: number;
     paginated: boolean;
     showNextButton: boolean;
     showPreviousButton: boolean;

package/dist/useOpenmrsPagination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useOpenmrsPagination.d.ts","sourceRoot":"","sources":["../src/useOpenmrsPagination.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,OAAO,EAAE,KAAK,aAAa,EAAyB,MAAM,kBAAkB,CAAC;AAE7E,OAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,KAAK,CAAC;AAGpD,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAClB,KAAK,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,0BAA0B,CAAC,CAAC;IAC3C;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IAErD;;OAEG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,0BAA0B,CAAC,wBAAwB,CAAC,CAAC,CAAC,CAAM;;;;;;;;;;;;;iBAgF5D,MAAM;;;EA7EhB;AAED,KAAK,+BAA+B,CAAC,CAAC,IAAI,wBAAwB,CAAC,CAAC,EAAE,wBAAwB,CAAC,CAAC,CAAC,CAAC,CAAC;AACnG,eAAO,MAAM,+BAA+B,EAAE,+BAA+B,CAAC,GAAG,CA6BhF,CAAC;AAEF,MAAM,WAAW,wBAAwB,CAAC,CAAC,EAAE,CAAC;IAC5C,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACzF,UAAU,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,SAAS,KAAK,MAAM,GAAG,IAAI,CAAC;IACvD,aAAa,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,SAAS,KAAK,MAAM,CAAC;IACnD,kBAAkB,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,SAAS,KAAK,MAAM,CAAC;IACxD,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;CAC5D;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,CAAC,EACtC,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,QAAQ,EAAE,MAAM,EAChB,wBAAwB,EAAE,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,EACxD,OAAO,GAAE,0BAA0B,CAAC,CAAC,CAAM;;;;;;;;;;;;;iBA+BlC,MAAM;;;EA+BhB"}
+{"version":3,"file":"useOpenmrsPagination.d.ts","sourceRoot":"","sources":["../src/useOpenmrsPagination.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,OAAO,EAAE,KAAK,aAAa,EAAyB,MAAM,kBAAkB,CAAC;AAE7E,OAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,KAAK,CAAC;AAGpD,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAClB,KAAK,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,0BAA0B,CAAC,CAAC;IAC3C;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IAErD;;OAEG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,0BAA0B,CAAC,wBAAwB,CAAC,CAAC,CAAC,CAAM;;;;;;;;;;;;;iBAyG5D,MAAM;;;EAtGhB;AAED,KAAK,+BAA+B,CAAC,CAAC,IAAI,wBAAwB,CAAC,CAAC,EAAE,wBAAwB,CAAC,CAAC,CAAC,CAAC,CAAC;AACnG,eAAO,MAAM,+BAA+B,EAAE,+BAA+B,CAAC,GAAG,CA6BhF,CAAC;AAEF,MAAM,WAAW,wBAAwB,CAAC,CAAC,EAAE,CAAC;IAC5C,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACzF,UAAU,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,SAAS,KAAK,MAAM,GAAG,IAAI,CAAC;IACvD,aAAa,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,SAAS,KAAK,MAAM,CAAC;IACnD,kBAAkB,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,SAAS,KAAK,MAAM,CAAC;IACxD,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;CAC5D;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,CAAC,EACtC,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,QAAQ,EAAE,MAAM,EAChB,wBAAwB,EAAE,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,EACxD,OAAO,GAAE,0BAA0B,CAAC,CAAC,CAAM;;;;;;;;;;;;;iBAwDlC,MAAM;;;EAoEhB"}

package/dist/useOpenmrsPagination.js

@@ -1,5 +1,5 @@
 /** @module @category UI */ import { makeUrl, openmrsFetch } from "@openmrs/esm-api";
-import { useCallback, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import useSWR from "swr";
 import useSWRImmutable from "swr/immutable";
 /**
@@ -65,12 +65,31 @@ export function useServerPagination(url, pageSize, serverPaginationHandlers, opt
     const { getPaginatedUrl, getTotalCount, getCurrentPageSize, getData } = serverPaginationHandlers;
     const { immutable, swrConfig } = options;
     const fetcher = options.fetcher ?? openmrsFetch;
-    const [currentPage, setCurrentPage] = useState(1); // 1-indexing instead of 0-indexing, to keep consistency with `usePagination`
+    // 1-indexing instead of 0-indexing, to keep consistency with `usePagination`
+    const [currentPage, setCurrentPage] = useState(1);
     // Cache the totalCount and currentPageSize so we don't lose them
     // as we wait for next page's result to load while navigating to a different page.
     // This can be used to prevent jarring UI changes while loading
     const totalCount = useRef(Number.NaN);
-    const currentPageSize = useRef(Number.NaN); // this value is usually same as pageSize, except when currentPage is last page.
+    // this value is usually same as pageSize, except when currentPage is last page.
+    const currentPageSize = useRef(Number.NaN);
+    // tracked as a ref so we don't need to make the current page a dependency of `goTo()`, etc.
+    const currentPageRef = useRef(currentPage);
+    // use to differentiate "endpoint doesn't return a total" from "we haven't run a request yet"
+    const hasResponded = useRef(false);
+    const warnedMissingTotal = useRef(false);
+    // if the URL we're querying changes, reset to page 1
+    const urlKey = url?.toString() ?? '';
+    const [lastUrlKey, setLastUrlKey] = useState(urlKey);
+    if (urlKey !== lastUrlKey) {
+        setLastUrlKey(urlKey);
+        setCurrentPage(1);
+        currentPageRef.current = 1;
+        totalCount.current = Number.NaN;
+        currentPageSize.current = Number.NaN;
+        hasResponded.current = false;
+        warnedMissingTotal.current = false;
+    }
     const limit = pageSize;
     const startIndex = (currentPage - 1) * pageSize;
     const urlUrl = useMemo(()=>{
@@ -85,39 +104,71 @@ export function useServerPagination(url, pageSize, serverPaginationHandlers, opt
     if (data?.data) {
         totalCount.current = getTotalCount(data?.data);
         currentPageSize.current = getCurrentPageSize(data?.data);
+        hasResponded.current = true;
     }
     const totalPages = Math.ceil(totalCount.current / pageSize);
+    // The bound is read from `totalCount` at call time rather than captured from the creating render,
+    // which is what keeps this callback referentially stable, apart from a change in `pageSize`.
     const goTo = useCallback((page)=>{
-        if (0 < page && page <= totalPages) {
+        if (!Number.isInteger(page) || page < 1) {
+            console.warn(`useServerPagination: ignoring goTo(${page}); page must be a positive integer.`);
+            return;
+        }
+        // page count is not known prior to running any query when `bound` will be `NaN`, so in this
+        // case we assume the requested page is fine; after results return, things will settle properly
+        // clamped
+        const bound = Math.ceil(totalCount.current / pageSize);
+        if (!hasResponded.current || Number.isNaN(bound) || page <= bound) {
+            currentPageRef.current = page;
             setCurrentPage(page);
         } else {
             console.warn('Invalid attempt to go to out of bounds page: ' + page);
         }
     }, [
-        url,
+        pageSize
+    ]);
+    // A page accepted before the total was known may turn out not to exist, so put the user on the last
+    // real page once the response settles it. Costs an extra request, but only for a page that was out of
+    // range to begin with; without it the hook sits on an empty page with no way back.
+    useEffect(()=>{
+        if (!hasResponded.current) {
+            return;
+        }
+        if (Number.isNaN(totalCount.current)) {
+            if (!warnedMissingTotal.current) {
+                warnedMissingTotal.current = true;
+                console.warn(`useServerPagination: ${urlKey} returned no total count, so out-of-range pages cannot be detected.`);
+            }
+            return;
+        }
+        const lastPage = Math.max(1, Math.ceil(totalCount.current / pageSize));
+        if (currentPage > lastPage) {
+            console.warn(`Invalid attempt to go to out of bounds page: ${currentPage}; returning to page ${lastPage}.`);
+            currentPageRef.current = lastPage;
+            setCurrentPage(lastPage);
+        }
+    }, [
         currentPage,
-        totalPages
+        pageSize,
+        urlKey,
+        data
     ]);
     const goToNext = useCallback(()=>{
-        goTo(currentPage + 1);
+        goTo(currentPageRef.current + 1);
     }, [
-        url,
-        currentPage,
-        totalPages
+        goTo
     ]);
     const goToPrevious = useCallback(()=>{
-        goTo(currentPage - 1);
+        goTo(currentPageRef.current - 1);
     }, [
-        url,
-        currentPage,
-        totalPages
+        goTo
     ]);
     return {
         data: getData(data?.data),
         totalPages,
         totalCount: totalCount.current,
         currentPage,
-        currentPageSize,
+        currentPageSize: currentPageSize.current,
         paginated: totalPages > 1,
         showNextButton: currentPage < totalPages,
         showPreviousButton: currentPage > 1,

package/dist/usePagination.d.ts

@@ -1,6 +1,11 @@
 /**
  * Use this hook to paginate data that already exists on the client side.
  * Note that if the data is obtained from server-side, the caller must handle server-side pagination manually.
+ *
+ * `goTo`, `goToNext` and `goToPrevious` keep the same identity for the life of the component, so they are
+ * safe to list in a dependency array. `currentPage` is bounded by the data, so it can change on its own
+ * when the data shrinks; a component reacting to `currentPage` should expect that.
+ *
  * @see `useServerPagination` for hook that automatically manages server-side pagination.
  * @see `useServerInfinite` for hook to get all data loaded onto the client-side
  * @param data

package/dist/usePagination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePagination.d.ts","sourceRoot":"","sources":["../src/usePagination.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,GAAE,KAAK,CAAC,CAAC,CAAM,EAAE,cAAc,SAAwB;;;;;;;iBAiBjF,MAAM;;;EAiChB"}
+{"version":3,"file":"usePagination.d.ts","sourceRoot":"","sources":["../src/usePagination.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,GAAE,KAAK,CAAC,CAAC,CAAM,EAAE,cAAc,SAAwB;;;;;;;iBAwB1D,MAAM;;;EAiCvC"}

package/dist/usePagination.js

@@ -3,17 +3,28 @@ const defaultResultsPerPage = 10;
 /**
  * Use this hook to paginate data that already exists on the client side.
  * Note that if the data is obtained from server-side, the caller must handle server-side pagination manually.
+ *
+ * `goTo`, `goToNext` and `goToPrevious` keep the same identity for the life of the component, so they are
+ * safe to list in a dependency array. `currentPage` is bounded by the data, so it can change on its own
+ * when the data shrinks; a component reacting to `currentPage` should expect that.
+ *
  * @see `useServerPagination` for hook that automatically manages server-side pagination.
  * @see `useServerInfinite` for hook to get all data loaded onto the client-side
  * @param data
  * @param resultsPerPage
  * @returns
  */ export function usePagination(data = [], resultsPerPage = defaultResultsPerPage) {
-    const [page, setPage] = useState(1);
+    const [requestedPage, setRequestedPage] = useState(1);
     const totalPages = useMemo(()=>typeof resultsPerPage === 'number' && resultsPerPage > 0 ? Math.max(1, Math.ceil(data.length / resultsPerPage)) : 1, [
         data.length,
         resultsPerPage
     ]);
+    // If requested page is past the end, set to the end. Done here to retain referential stability
+    // on the functions returned by this hook
+    if (requestedPage > totalPages) {
+        setRequestedPage(totalPages);
+    }
+    const page = Math.min(Math.max(1, requestedPage), totalPages);
     const results = useMemo(()=>{
         const lowerBound = (page - 1) * resultsPerPage;
         const upperBound = (page + 0) * resultsPerPage;
@@ -24,28 +35,19 @@ const defaultResultsPerPage = 10;
         resultsPerPage
     ]);
     const goTo = useCallback((page)=>{
-        setPage(Math.max(1, Math.min(totalPages, page)));
-    }, [
-        setPage,
-        totalPages
-    ]);
-    const goToNext = useCallback(()=>{
-        if (page < totalPages) {
-            setPage(page + 1);
+        if (!Number.isInteger(page) || page < 1) {
+            console.warn(`usePagination: ignoring goTo(${page}); page must be a positive integer.`);
+            return;
         }
-    }, [
-        page,
-        totalPages,
-        setPage
-    ]);
+        setRequestedPage(page);
+    }, []);
+    // overflow clamping happens in render; see the setRequestedPage() call above
+    const goToNext = useCallback(()=>{
+        setRequestedPage((p)=>p + 1);
+    }, []);
     const goToPrevious = useCallback(()=>{
-        if (page > 1) {
-            setPage(page - 1);
-        }
-    }, [
-        page,
-        setPage
-    ]);
+        setRequestedPage((p)=>Math.max(1, p - 1));
+    }, []);
     const memoisedPaginatedData = useMemo(()=>({
             results,
             totalPages,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-react-utils",
-  "version": "10.0.1-pre.5295",
+  "version": "10.0.1-pre.5309",
   "license": "MPL-2.0",
   "description": "React utilities for OpenMRS.",
   "type": "module",
@@ -60,17 +60,17 @@
     "single-spa-react": "^6.0.2"
   },
   "peerDependencies": {
-    "@openmrs/esm-api": "^10.0.1-pre.5295",
-    "@openmrs/esm-config": "^10.0.1-pre.5295",
-    "@openmrs/esm-context": "^10.0.1-pre.5295",
-    "@openmrs/esm-emr-api": "^10.0.1-pre.5295",
-    "@openmrs/esm-error-handling": "^10.0.1-pre.5295",
-    "@openmrs/esm-extensions": "^10.0.1-pre.5295",
-    "@openmrs/esm-feature-flags": "^10.0.1-pre.5295",
-    "@openmrs/esm-globals": "^10.0.1-pre.5295",
-    "@openmrs/esm-navigation": "^10.0.1-pre.5295",
-    "@openmrs/esm-state": "^10.0.1-pre.5295",
-    "@openmrs/esm-utils": "^10.0.1-pre.5295",
+    "@openmrs/esm-api": "^10.0.1-pre.5309",
+    "@openmrs/esm-config": "^10.0.1-pre.5309",
+    "@openmrs/esm-context": "^10.0.1-pre.5309",
+    "@openmrs/esm-emr-api": "^10.0.1-pre.5309",
+    "@openmrs/esm-error-handling": "^10.0.1-pre.5309",
+    "@openmrs/esm-extensions": "^10.0.1-pre.5309",
+    "@openmrs/esm-feature-flags": "^10.0.1-pre.5309",
+    "@openmrs/esm-globals": "^10.0.1-pre.5309",
+    "@openmrs/esm-navigation": "^10.0.1-pre.5309",
+    "@openmrs/esm-state": "^10.0.1-pre.5309",
+    "@openmrs/esm-utils": "^10.0.1-pre.5309",
     "dayjs": "1.x",
     "i18next": "25.x",
     "react": "18.x",
@@ -80,17 +80,17 @@
     "swr": "2.x"
   },
   "devDependencies": {
-    "@openmrs/esm-api": "10.0.1-pre.5295",
-    "@openmrs/esm-config": "10.0.1-pre.5295",
-    "@openmrs/esm-context": "10.0.1-pre.5295",
-    "@openmrs/esm-emr-api": "10.0.1-pre.5295",
-    "@openmrs/esm-error-handling": "10.0.1-pre.5295",
-    "@openmrs/esm-extensions": "10.0.1-pre.5295",
-    "@openmrs/esm-feature-flags": "10.0.1-pre.5295",
-    "@openmrs/esm-globals": "10.0.1-pre.5295",
-    "@openmrs/esm-navigation": "10.0.1-pre.5295",
-    "@openmrs/esm-state": "10.0.1-pre.5295",
-    "@openmrs/esm-utils": "10.0.1-pre.5295",
+    "@openmrs/esm-api": "10.0.1-pre.5309",
+    "@openmrs/esm-config": "10.0.1-pre.5309",
+    "@openmrs/esm-context": "10.0.1-pre.5309",
+    "@openmrs/esm-emr-api": "10.0.1-pre.5309",
+    "@openmrs/esm-error-handling": "10.0.1-pre.5309",
+    "@openmrs/esm-extensions": "10.0.1-pre.5309",
+    "@openmrs/esm-feature-flags": "10.0.1-pre.5309",
+    "@openmrs/esm-globals": "10.0.1-pre.5309",
+    "@openmrs/esm-navigation": "10.0.1-pre.5309",
+    "@openmrs/esm-state": "10.0.1-pre.5309",
+    "@openmrs/esm-utils": "10.0.1-pre.5309",
     "@swc/cli": "0.8.1",
     "@swc/core": "1.15.21",
     "@vitest/coverage-v8": "^4.1.2",

package/src/useOpenmrsPagination.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { renderHook, waitFor, act } from '@testing-library/react';
 import { useOpenmrsPagination, type OpenMRSPaginatedResponse } from './useOpenmrsPagination';
 
@@ -25,6 +25,11 @@ export async function getTestData(url: string, totalCount: number): Promise<Open
   return { results, links, totalCount } as OpenMRSPaginatedResponse<number>;
 }
 
+/** Whether any warning mentions `page`, so the exact wording stays free to change. */
+function warned(warn: { mock: { calls: Array<Array<unknown>> } }, page: string) {
+  return warn.mock.calls.some((call) => String(call[0]).includes(page));
+}
+
 describe('useOpenmrsPagination', () => {
   it('should not fetch anything if url is null', async () => {
     const { result } = renderHook(() =>
@@ -53,6 +58,24 @@ describe('useOpenmrsPagination', () => {
     expect(result.current.data).toEqual(getIntArray(0, 17));
   });
 
+  it('reports currentPageSize as a number, matching the rows on the current page', async () => {
+    const pageSize = 20;
+    const expectedRowCount = 50;
+    const { result } = renderHook(() =>
+      useOpenmrsPagination('http://localhost/page-size', pageSize, {
+        fetcher: (url) => getTestData(url, expectedRowCount).then((data) => ({ data }) as any),
+      }),
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBeFalsy());
+    expect(result.current.currentPageSize).toBe(20);
+
+    // the last page is short, and the reported size follows it
+    act(() => result.current.goTo(3));
+    await waitFor(() => expect(result.current.currentPage).toBe(3));
+    await waitFor(() => expect(result.current.currentPageSize).toBe(10));
+  });
+
   it('should fetch 2 pages if pageSize < number of rows <= 2 * pageSize', async () => {
     const pageSize = 20;
     const expectedRowCount = 40;
@@ -134,4 +157,277 @@ describe('useOpenmrsPagination', () => {
     expect(result.current.totalCount).toBe(expectedRowCount);
     expect(result.current.data).toEqual(getIntArray(1320, 17));
   });
+
+  describe('callback identity', () => {
+    it('keeps the same callbacks when the total count arrives and when the page changes', async () => {
+      const { result } = renderHook(() =>
+        useOpenmrsPagination('http://localhost/identity', 20, {
+          fetcher: (url) => getTestData(url, 1337).then((data) => ({ data }) as any),
+        }),
+      );
+
+      // captured before any response, while totalCount is still NaN
+      const { goTo, goToNext, goToPrevious } = result.current;
+      expect(result.current.totalPages).toBeNaN();
+
+      await waitFor(() => expect(result.current.isLoading).toBeFalsy());
+      expect(result.current.totalPages).toBe(67);
+
+      act(() => result.current.goTo(4));
+      await waitFor(() => expect(result.current.currentPage).toBe(4));
+
+      act(() => result.current.goToNext());
+      await waitFor(() => expect(result.current.currentPage).toBe(5));
+
+      expect(result.current.goTo).toBe(goTo);
+      expect(result.current.goToNext).toBe(goToNext);
+      expect(result.current.goToPrevious).toBe(goToPrevious);
+    });
+  });
+
+  describe('out of bounds navigation', () => {
+    it('warns, stays put and issues no further request', async () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const fetcher = vi.fn((url: string) => getTestData(url, 40).then((data) => ({ data }) as any));
+
+      const { result } = renderHook(() => useOpenmrsPagination('http://localhost/bounds', 20, { fetcher }));
+
+      await waitFor(() => expect(result.current.isLoading).toBeFalsy());
+      expect(result.current.totalPages).toBe(2);
+
+      const fetchCount = fetcher.mock.calls.length;
+
+      act(() => result.current.goTo(999));
+      act(() => result.current.goTo(0));
+
+      expect(result.current.currentPage).toBe(1);
+      // asserted as substrings so the wording can be improved without breaking these
+      expect(warned(warn, '999')).toBe(true);
+      expect(warned(warn, '0')).toBe(true);
+      expect(fetcher.mock.calls.length).toBe(fetchCount);
+
+      warn.mockRestore();
+    });
+
+    it('warns when going to the previous page from the first page', async () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      const { result } = renderHook(() =>
+        useOpenmrsPagination('http://localhost/previous', 20, {
+          fetcher: (url) => getTestData(url, 40).then((data) => ({ data }) as any),
+        }),
+      );
+
+      await waitFor(() => expect(result.current.isLoading).toBeFalsy());
+
+      act(() => result.current.goToPrevious());
+
+      expect(result.current.currentPage).toBe(1);
+      expect(warned(warn, '0')).toBe(true);
+
+      warn.mockRestore();
+    });
+  });
+
+  describe('stepping', () => {
+    // Batching the two calls into one commit is what distinguishes stepping from the page as it stands
+    // from stepping from a page captured when the callback was created; the latter is a commit behind.
+    it('steps from the latest requested page when batched with a goTo', async () => {
+      const { result } = renderHook(() =>
+        useOpenmrsPagination('http://localhost/batched-next', 20, {
+          fetcher: (url) => getTestData(url, 200).then((data) => ({ data }) as any),
+        }),
+      );
+      await waitFor(() => expect(result.current.isLoading).toBeFalsy());
+
+      const { goTo, goToNext } = result.current;
+      act(() => {
+        goTo(3);
+        goToNext();
+      });
+
+      await waitFor(() => expect(result.current.isValidating).toBeFalsy());
+      expect(result.current.currentPage).toBe(4);
+      expect(result.current.data).toEqual(getIntArray(60, 20));
+    });
+
+    it('steps back from the latest requested page when batched with a goTo', async () => {
+      const { result } = renderHook(() =>
+        useOpenmrsPagination('http://localhost/batched-prev', 20, {
+          fetcher: (url) => getTestData(url, 200).then((data) => ({ data }) as any),
+        }),
+      );
+      await waitFor(() => expect(result.current.isLoading).toBeFalsy());
+
+      const { goTo, goToPrevious } = result.current;
+      act(() => {
+        goTo(5);
+        goToPrevious();
+      });
+
+      await waitFor(() => expect(result.current.isValidating).toBeFalsy());
+      expect(result.current.currentPage).toBe(4);
+    });
+  });
+
+  describe('changing the url', () => {
+    it('returns to page 1 and does not request the old offset against the new url', async () => {
+      const urls: Array<string> = [];
+      const fetcher = (url: string) => {
+        urls.push(url);
+        return getTestData(url, url.includes('wide') ? 1337 : 10).then((data) => ({ data }) as any);
+      };
+
+      const { result, rerender } = renderHook(({ url }) => useOpenmrsPagination(url, 20, { fetcher }), {
+        initialProps: { url: 'http://localhost/search?q=wide' },
+      });
+      await waitFor(() => expect(result.current.isLoading).toBeFalsy());
+
+      act(() => result.current.goTo(5));
+      await waitFor(() => expect(result.current.currentPage).toBe(5));
+
+      rerender({ url: 'http://localhost/search?q=narrow' });
+      await waitFor(() => expect(result.current.isValidating).toBeFalsy());
+
+      expect(result.current.currentPage).toBe(1);
+      expect(result.current.totalCount).toBe(10);
+      expect(result.current.data).toEqual(getIntArray(0, 10));
+      expect(urls.filter((u) => u.includes('narrow') && u.includes('startIndex=80'))).toEqual([]);
+    });
+  });
+
+  describe('navigation before the first response', () => {
+    it('applies a page requested while the total count is still unknown', async () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      let release: () => void;
+      const firstResponse = new Promise<void>((resolve) => {
+        release = resolve;
+      });
+
+      const { result } = renderHook(() =>
+        useOpenmrsPagination('http://localhost/race', 20, {
+          fetcher: async (url) => {
+            await firstResponse;
+            return { data: await getTestData(url, 1337) } as any;
+          },
+        }),
+      );
+
+      expect(result.current.totalCount).toBeNaN();
+      expect(result.current.totalPages).toBeNaN();
+
+      act(() => result.current.goTo(2));
+      expect(result.current.currentPage).toBe(2);
+      expect(warn).not.toHaveBeenCalled();
+
+      release!();
+
+      await waitFor(() => expect(result.current.data).toBeDefined());
+      await waitFor(() => expect(result.current.isLoading).toBeFalsy());
+
+      expect(result.current.currentPage).toBe(2);
+      expect(result.current.totalPages).toBe(67);
+      expect(result.current.data).toEqual(getIntArray(20, 20));
+
+      warn.mockRestore();
+    });
+
+    it('returns to the last real page when the requested one turns out not to exist', async () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      let release: () => void;
+      const firstResponse = new Promise<void>((resolve) => {
+        release = resolve;
+      });
+
+      const { result } = renderHook(() =>
+        useOpenmrsPagination('http://localhost/strand', 20, {
+          fetcher: async (url) => {
+            await firstResponse;
+            return { data: await getTestData(url, 40) } as any;
+          },
+        }),
+      );
+
+      act(() => result.current.goTo(999999));
+      expect(result.current.currentPage).toBe(999999);
+
+      release!();
+      await waitFor(() => expect(result.current.totalPages).toBe(2));
+      await waitFor(() => expect(result.current.currentPage).toBe(2));
+
+      expect(result.current.data).toEqual(getIntArray(20, 20));
+      expect(result.current.showPreviousButton).toBe(true);
+      expect(warn).toHaveBeenCalled();
+
+      // and the user is not stuck: navigation still works
+      act(() => result.current.goToPrevious());
+      await waitFor(() => expect(result.current.currentPage).toBe(1));
+
+      warn.mockRestore();
+    });
+
+    it('rejects a non-integer page instead of putting NaN in the request url', async () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const urls: Array<string> = [];
+
+      let release: () => void;
+      const firstResponse = new Promise<void>((resolve) => {
+        release = resolve;
+      });
+
+      const { result } = renderHook(() =>
+        useOpenmrsPagination('http://localhost/nan', 20, {
+          fetcher: async (url) => {
+            urls.push(url);
+            await firstResponse;
+            return { data: await getTestData(url, 100) } as any;
+          },
+        }),
+      );
+
+      act(() => result.current.goTo(Number('nope')));
+      expect(result.current.currentPage).toBe(1);
+      expect(warn).toHaveBeenCalled();
+
+      release!();
+      await waitFor(() => expect(result.current.isLoading).toBeFalsy());
+
+      expect(urls.some((u) => u.includes('startIndex=NaN'))).toBe(false);
+      expect(result.current.currentPage).toBe(1);
+
+      warn.mockRestore();
+    });
+  });
+
+  describe('a server that reports no total count', () => {
+    it('warns once and keeps navigation usable rather than silently dropping every request', async () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      const { result } = renderHook(() =>
+        useOpenmrsPagination('http://localhost/nototal', 20, {
+          fetcher: async (url) => {
+            const u = new URL(url, window.location.toString());
+            const startIndex = Number.parseInt(u.searchParams.get('startIndex') ?? '0');
+            // no totalCount field, as a FHIR bundle without `total` would give
+            return { data: { results: getIntArray(startIndex, 20), links: [] } } as any;
+          },
+        }),
+      );
+
+      await waitFor(() => expect(result.current.isLoading).toBeFalsy());
+      expect(result.current.totalCount).toBeNaN();
+
+      await waitFor(() => expect(warn).toHaveBeenCalled());
+      const missingTotalWarnings = warn.mock.calls.filter((c) => String(c[0]).includes('no total count'));
+      expect(missingTotalWarnings).toHaveLength(1);
+
+      // navigation still works, since there is no bound to check against
+      act(() => result.current.goTo(3));
+      await waitFor(() => expect(result.current.currentPage).toBe(3));
+
+      warn.mockRestore();
+    });
+  });
 });

package/src/useOpenmrsPagination.ts

@@ -1,6 +1,6 @@
 /** @module @category UI */
 import { type FetchResponse, makeUrl, openmrsFetch } from '@openmrs/esm-api';
-import { useCallback, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import useSWR, { type SWRConfiguration } from 'swr';
 import useSWRImmutable from 'swr/immutable';
 
@@ -113,13 +113,35 @@ export function useServerPagination<T, R>(
   const { getPaginatedUrl, getTotalCount, getCurrentPageSize, getData } = serverPaginationHandlers;
   const { immutable, swrConfig } = options;
   const fetcher: (key: string) => Promise<FetchResponse<R>> = options.fetcher ?? openmrsFetch;
-  const [currentPage, setCurrentPage] = useState<number>(1); // 1-indexing instead of 0-indexing, to keep consistency with `usePagination`
+  // 1-indexing instead of 0-indexing, to keep consistency with `usePagination`
+  const [currentPage, setCurrentPage] = useState<number>(1);
 
   // Cache the totalCount and currentPageSize so we don't lose them
   // as we wait for next page's result to load while navigating to a different page.
   // This can be used to prevent jarring UI changes while loading
   const totalCount = useRef<number>(Number.NaN);
-  const currentPageSize = useRef<number>(Number.NaN); // this value is usually same as pageSize, except when currentPage is last page.
+  // this value is usually same as pageSize, except when currentPage is last page.
+  const currentPageSize = useRef<number>(Number.NaN);
+
+  // tracked as a ref so we don't need to make the current page a dependency of `goTo()`, etc.
+  const currentPageRef = useRef(currentPage);
+
+  // use to differentiate "endpoint doesn't return a total" from "we haven't run a request yet"
+  const hasResponded = useRef(false);
+  const warnedMissingTotal = useRef(false);
+
+  // if the URL we're querying changes, reset to page 1
+  const urlKey = url?.toString() ?? '';
+  const [lastUrlKey, setLastUrlKey] = useState(urlKey);
+  if (urlKey !== lastUrlKey) {
+    setLastUrlKey(urlKey);
+    setCurrentPage(1);
+    currentPageRef.current = 1;
+    totalCount.current = Number.NaN;
+    currentPageSize.current = Number.NaN;
+    hasResponded.current = false;
+    warnedMissingTotal.current = false;
+  }
 
   const limit = pageSize;
   const startIndex = (currentPage - 1) * pageSize;
@@ -134,34 +156,74 @@ export function useServerPagination<T, R>(
   if (data?.data) {
     totalCount.current = getTotalCount(data?.data);
     currentPageSize.current = getCurrentPageSize(data?.data);
+    hasResponded.current = true;
   }
 
   const totalPages = Math.ceil(totalCount.current / pageSize);
 
+  // The bound is read from `totalCount` at call time rather than captured from the creating render,
+  // which is what keeps this callback referentially stable, apart from a change in `pageSize`.
   const goTo = useCallback(
     (page: number) => {
-      if (0 < page && page <= totalPages) {
+      if (!Number.isInteger(page) || page < 1) {
+        console.warn(`useServerPagination: ignoring goTo(${page}); page must be a positive integer.`);
+        return;
+      }
+
+      // page count is not known prior to running any query when `bound` will be `NaN`, so in this
+      // case we assume the requested page is fine; after results return, things will settle properly
+      // clamped
+      const bound = Math.ceil(totalCount.current / pageSize);
+      if (!hasResponded.current || Number.isNaN(bound) || page <= bound) {
+        currentPageRef.current = page;
         setCurrentPage(page);
       } else {
         console.warn('Invalid attempt to go to out of bounds page: ' + page);
       }
     },
-    [url, currentPage, totalPages],
+    [pageSize],
   );
+
+  // A page accepted before the total was known may turn out not to exist, so put the user on the last
+  // real page once the response settles it. Costs an extra request, but only for a page that was out of
+  // range to begin with; without it the hook sits on an empty page with no way back.
+  useEffect(() => {
+    if (!hasResponded.current) {
+      return;
+    }
+
+    if (Number.isNaN(totalCount.current)) {
+      if (!warnedMissingTotal.current) {
+        warnedMissingTotal.current = true;
+        console.warn(
+          `useServerPagination: ${urlKey} returned no total count, so out-of-range pages cannot be detected.`,
+        );
+      }
+      return;
+    }
+
+    const lastPage = Math.max(1, Math.ceil(totalCount.current / pageSize));
+    if (currentPage > lastPage) {
+      console.warn(`Invalid attempt to go to out of bounds page: ${currentPage}; returning to page ${lastPage}.`);
+      currentPageRef.current = lastPage;
+      setCurrentPage(lastPage);
+    }
+  }, [currentPage, pageSize, urlKey, data]);
+
   const goToNext = useCallback(() => {
-    goTo(currentPage + 1);
-  }, [url, currentPage, totalPages]);
+    goTo(currentPageRef.current + 1);
+  }, [goTo]);
 
   const goToPrevious = useCallback(() => {
-    goTo(currentPage - 1);
-  }, [url, currentPage, totalPages]);
+    goTo(currentPageRef.current - 1);
+  }, [goTo]);
 
   return {
     data: getData(data?.data),
     totalPages,
     totalCount: totalCount.current,
     currentPage,
-    currentPageSize,
+    currentPageSize: currentPageSize.current,
     paginated: totalPages > 1,
     showNextButton: currentPage < totalPages,
     showPreviousButton: currentPage > 1,

package/src/usePagination.test.tsx

@@ -0,0 +1,315 @@
+import React, { useEffect } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { act, render, renderHook } from '@testing-library/react';
+import { usePagination } from './usePagination';
+
+function rows(length: number) {
+  return Array.from({ length }, (_, i) => i);
+}
+
+describe('usePagination', () => {
+  describe('callback identity', () => {
+    it('keeps the same callbacks as the data grows', () => {
+      const { result, rerender } = renderHook(({ data }) => usePagination(data, 20), {
+        initialProps: { data: rows(50) },
+      });
+
+      const { goTo, goToNext, goToPrevious } = result.current;
+      expect(result.current.totalPages).toBe(3);
+
+      for (const length of [100, 150, 200, 250, 300, 350, 373]) {
+        rerender({ data: rows(length) });
+      }
+
+      expect(result.current.totalPages).toBe(19);
+      expect(result.current.goTo).toBe(goTo);
+      expect(result.current.goToNext).toBe(goToNext);
+      expect(result.current.goToPrevious).toBe(goToPrevious);
+    });
+
+    it('keeps the same callbacks as the page changes', () => {
+      const { result } = renderHook(() => usePagination(rows(100), 20));
+
+      const { goTo, goToNext, goToPrevious } = result.current;
+
+      act(() => result.current.goTo(3));
+      act(() => result.current.goToNext());
+      act(() => result.current.goToPrevious());
+
+      expect(result.current.currentPage).toBe(3);
+      expect(result.current.goTo).toBe(goTo);
+      expect(result.current.goToNext).toBe(goToNext);
+      expect(result.current.goToPrevious).toBe(goToPrevious);
+    });
+
+    it('does not reset the page when a consumer effect depends on goTo', () => {
+      // Mirrors the advanced patient search, where results accumulate in 50-row batches while an
+      // effect keyed on `goTo` resets to page 1 — the shape that produced the reported snap-back.
+      const { result, rerender } = renderHook(
+        ({ data }) => {
+          const pagination = usePagination(data, 20);
+          const { goTo } = pagination;
+          useEffect(() => {
+            goTo(1);
+          }, [goTo]);
+          return pagination;
+        },
+        { initialProps: { data: rows(50) } },
+      );
+
+      act(() => result.current.goTo(2));
+      expect(result.current.currentPage).toBe(2);
+
+      for (const length of [100, 150, 200, 250, 300, 350, 373]) {
+        rerender({ data: rows(length) });
+      }
+
+      expect(result.current.currentPage).toBe(2);
+      expect(result.current.results).toEqual(rows(40).slice(20));
+    });
+  });
+
+  describe('clamping', () => {
+    it('clamps the page and results when the data shrinks', () => {
+      const { result, rerender } = renderHook(({ data }) => usePagination(data, 20), {
+        initialProps: { data: rows(100) },
+      });
+
+      act(() => result.current.goTo(5));
+      expect(result.current.currentPage).toBe(5);
+      expect(result.current.results).toEqual(rows(100).slice(80));
+
+      rerender({ data: rows(10) });
+
+      expect(result.current.totalPages).toBe(1);
+      expect(result.current.currentPage).toBe(1);
+      expect(result.current.results).toEqual(rows(10));
+      expect(result.current.showPreviousButton).toBe(false);
+    });
+
+    it('clamps to page 1 when the data empties', () => {
+      const { result, rerender } = renderHook(({ data }) => usePagination(data, 20), {
+        initialProps: { data: rows(100) },
+      });
+
+      act(() => result.current.goTo(4));
+      rerender({ data: [] });
+
+      expect(result.current.totalPages).toBe(1);
+      expect(result.current.currentPage).toBe(1);
+      expect(result.current.results).toEqual([]);
+    });
+
+    it('never goes below page 1', () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const { result } = renderHook(() => usePagination(rows(100), 20));
+
+      act(() => result.current.goTo(0));
+      expect(result.current.currentPage).toBe(1);
+
+      act(() => result.current.goTo(-5));
+      expect(result.current.currentPage).toBe(1);
+
+      act(() => result.current.goToPrevious());
+      expect(result.current.currentPage).toBe(1);
+      warn.mockRestore();
+    });
+
+    it('rejects a non-integer page rather than letting NaN through', () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const { result } = renderHook(() => usePagination(rows(100), 20));
+
+      act(() => result.current.goTo(Number('nope')));
+      expect(result.current.currentPage).toBe(1);
+      expect(result.current.results).toEqual(rows(20));
+      expect(warn).toHaveBeenCalled();
+
+      act(() => result.current.goTo(2.5));
+      expect(result.current.currentPage).toBe(1);
+
+      // the hook is still usable afterwards
+      act(() => result.current.goTo(3));
+      expect(result.current.currentPage).toBe(3);
+      warn.mockRestore();
+    });
+  });
+
+  describe('out-of-range requests do not linger', () => {
+    it('does not follow the tail of a growing data set after an out-of-range goTo', () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const { result, rerender } = renderHook(({ data }) => usePagination(data, 20), {
+        initialProps: { data: rows(60) },
+      });
+
+      act(() => result.current.goTo(999));
+      expect(result.current.currentPage).toBe(3);
+
+      rerender({ data: rows(200) });
+      expect(result.current.currentPage).toBe(3);
+
+      rerender({ data: rows(2000) });
+      expect(result.current.currentPage).toBe(3);
+      warn.mockRestore();
+    });
+
+    it('does not advance later when Next is pressed at the last page and the data then grows', () => {
+      const { result, rerender } = renderHook(({ data }) => usePagination(data, 20), {
+        initialProps: { data: rows(60) },
+      });
+
+      act(() => result.current.goTo(3));
+      expect(result.current.showNextButton).toBe(false);
+
+      act(() => result.current.goToNext());
+      expect(result.current.currentPage).toBe(3);
+
+      rerender({ data: rows(100) });
+      expect(result.current.currentPage).toBe(3);
+    });
+
+    it('does not restore an old page when the data shrinks and grows again', () => {
+      const { result, rerender } = renderHook(({ data }) => usePagination(data, 20), {
+        initialProps: { data: rows(380) },
+      });
+
+      act(() => result.current.goTo(19));
+      rerender({ data: rows(40) });
+      expect(result.current.currentPage).toBe(2);
+
+      rerender({ data: rows(380) });
+      expect(result.current.currentPage).toBe(2);
+    });
+  });
+
+  describe('stepping', () => {
+    it('holds the last page when Next is pressed at the end, and Previous then moves one page', () => {
+      const { result } = renderHook(() => usePagination(rows(60), 20));
+
+      act(() => result.current.goTo(3));
+      expect(result.current.currentPage).toBe(3);
+      expect(result.current.showNextButton).toBe(false);
+
+      act(() => result.current.goToNext());
+      expect(result.current.currentPage).toBe(3);
+
+      act(() => result.current.goToNext());
+      expect(result.current.currentPage).toBe(3);
+
+      act(() => result.current.goToPrevious());
+      expect(result.current.currentPage).toBe(2);
+    });
+
+    it('moves Previous one page from what is displayed after a large shrink', () => {
+      const { result, rerender } = renderHook(({ data }) => usePagination(data, 20), {
+        initialProps: { data: rows(380) },
+      });
+
+      act(() => result.current.goTo(19));
+      expect(result.current.currentPage).toBe(19);
+
+      rerender({ data: rows(40) });
+      expect(result.current.currentPage).toBe(2);
+
+      act(() => result.current.goToPrevious());
+      expect(result.current.currentPage).toBe(1);
+    });
+
+    // Batching the two calls into one commit is what distinguishes stepping from the latest queued page
+    // from stepping from a page captured when the callback was created; the latter is a commit behind.
+    it('steps from the latest queued page when batched with a goTo', () => {
+      const { result } = renderHook(() => usePagination(rows(200), 20));
+      const { goTo, goToNext } = result.current;
+
+      act(() => {
+        goTo(3);
+        goToNext();
+      });
+
+      expect(result.current.currentPage).toBe(4);
+    });
+
+    it('steps back from the latest queued page when batched with a goTo', () => {
+      const { result } = renderHook(() => usePagination(rows(200), 20));
+      const { goTo, goToPrevious } = result.current;
+
+      act(() => {
+        goTo(5);
+        goToPrevious();
+      });
+
+      expect(result.current.currentPage).toBe(4);
+    });
+
+    it('steps correctly when called from a child effect during a shrink', () => {
+      const seen: Array<number> = [];
+      const box: { goTo?: (n: number) => void } = {};
+      let armed = false;
+
+      function Child({ onPrev }: { onPrev: () => void }) {
+        useEffect(() => {
+          if (armed) {
+            armed = false;
+            onPrev();
+          }
+        });
+        return null;
+      }
+
+      function Parent({ data }: { data: Array<number> }) {
+        const { currentPage, goTo, goToPrevious } = usePagination(data, 20);
+        seen.push(currentPage);
+        box.goTo = goTo;
+        return <Child onPrev={goToPrevious} />;
+      }
+
+      const { rerender } = render(<Parent data={rows(380)} />);
+      act(() => box.goTo!(19));
+      expect(seen[seen.length - 1]).toBe(19);
+
+      // the data shrinks to 2 pages and Previous is pressed in that same commit
+      armed = true;
+      rerender(<Parent data={rows(40)} />);
+
+      expect(seen[seen.length - 1]).toBe(1);
+    });
+  });
+
+  describe('returned shape', () => {
+    it('paginates and reports flags as before', () => {
+      const { result } = renderHook(() => usePagination(rows(45), 20));
+
+      expect(result.current.totalPages).toBe(3);
+      expect(result.current.currentPage).toBe(1);
+      expect(result.current.paginated).toBe(true);
+      expect(result.current.showNextButton).toBe(true);
+      expect(result.current.showPreviousButton).toBe(false);
+      expect(result.current.results).toEqual(rows(20));
+
+      act(() => result.current.goToNext());
+      expect(result.current.results).toEqual(rows(40).slice(20));
+      expect(result.current.showPreviousButton).toBe(true);
+
+      act(() => result.current.goToNext());
+      expect(result.current.results).toEqual(rows(45).slice(40));
+      expect(result.current.showNextButton).toBe(false);
+    });
+
+    it('is not paginated when the data fits on one page', () => {
+      const { result } = renderHook(() => usePagination(rows(5), 20));
+
+      expect(result.current.totalPages).toBe(1);
+      expect(result.current.paginated).toBe(false);
+      expect(result.current.results).toEqual(rows(5));
+    });
+
+    // Characterises a long-standing quirk rather than endorsing it: an unusable `resultsPerPage` reports
+    // a single page but slices no rows out of it, so the caller gets an empty list with no diagnostic.
+    it('reports one page and no results when resultsPerPage is not a usable number', () => {
+      const { result } = renderHook(() => usePagination(rows(50), 0));
+
+      expect(result.current.totalPages).toBe(1);
+      expect(result.current.currentPage).toBe(1);
+      expect(result.current.results).toEqual([]);
+    });
+  });
+});

package/src/usePagination.ts

@@ -6,6 +6,11 @@ const defaultResultsPerPage = 10;
 /**
  * Use this hook to paginate data that already exists on the client side.
  * Note that if the data is obtained from server-side, the caller must handle server-side pagination manually.
+ *
+ * `goTo`, `goToNext` and `goToPrevious` keep the same identity for the life of the component, so they are
+ * safe to list in a dependency array. `currentPage` is bounded by the data, so it can change on its own
+ * when the data shrinks; a component reacting to `currentPage` should expect that.
+ *
  * @see `useServerPagination` for hook that automatically manages server-side pagination.
  * @see `useServerInfinite` for hook to get all data loaded onto the client-side
  * @param data
@@ -13,7 +18,7 @@ const defaultResultsPerPage = 10;
  * @returns
  */
 export function usePagination<T>(data: Array<T> = [], resultsPerPage = defaultResultsPerPage) {
-  const [page, setPage] = useState(1);
+  const [requestedPage, setRequestedPage] = useState(1);
   const totalPages = useMemo(
     () =>
       typeof resultsPerPage === 'number' && resultsPerPage > 0
@@ -22,29 +27,36 @@ export function usePagination<T>(data: Array<T> = [], resultsPerPage = defaultRe
     [data.length, resultsPerPage],
   );
 
+  // If requested page is past the end, set to the end. Done here to retain referential stability
+  // on the functions returned by this hook
+  if (requestedPage > totalPages) {
+    setRequestedPage(totalPages);
+  }
+
+  const page = Math.min(Math.max(1, requestedPage), totalPages);
+
   const results = useMemo(() => {
     const lowerBound = (page - 1) * resultsPerPage;
     const upperBound = (page + 0) * resultsPerPage;
     return data.slice(lowerBound, upperBound);
   }, [data, page, resultsPerPage]);
 
-  const goTo = useCallback(
-    (page: number) => {
-      setPage(Math.max(1, Math.min(totalPages, page)));
-    },
-    [setPage, totalPages],
-  );
-  const goToNext = useCallback(() => {
-    if (page < totalPages) {
-      setPage(page + 1);
+  const goTo = useCallback((page: number) => {
+    if (!Number.isInteger(page) || page < 1) {
+      console.warn(`usePagination: ignoring goTo(${page}); page must be a positive integer.`);
+      return;
     }
-  }, [page, totalPages, setPage]);
+    setRequestedPage(page);
+  }, []);
+
+  // overflow clamping happens in render; see the setRequestedPage() call above
+  const goToNext = useCallback(() => {
+    setRequestedPage((p) => p + 1);
+  }, []);
 
   const goToPrevious = useCallback(() => {
-    if (page > 1) {
-      setPage(page - 1);
-    }
-  }, [page, setPage]);
+    setRequestedPage((p) => Math.max(1, p - 1));
+  }, []);
 
   const memoisedPaginatedData = useMemo(
     () => ({