@openmrs/esm-react-utils 10.0.1-pre.5263 → 10.0.1-pre.5299

package/src/useExtensionSlot.ts

@@ -1,33 +1,23 @@
-import { useContext, useEffect, useRef } from 'react';
-import {
-  type ExtensionSlotCustomState,
-  registerExtensionSlot,
-  updateExtensionSlotState,
-} from '@openmrs/esm-extensions';
+import { useContext, useEffect } from 'react';
+import { type ExtensionSlotCustomState, registerExtensionSlot } from '@openmrs/esm-extensions';
 import { ComponentContext } from './ComponentContext';
 import { useAssignedExtensions } from './useAssignedExtensions';
 
 /** @internal */
 export function useExtensionSlot(slotName: string, state?: ExtensionSlotCustomState) {
   const { moduleName } = useContext(ComponentContext);
-  const isInitialRender = useRef(true);
 
   if (!moduleName) {
     throw Error('ComponentContext has not been provided. This should come from @openmrs/esm-react-utils.');
   }
 
   useEffect(() => {
-    registerExtensionSlot(moduleName, slotName, state);
-    isInitialRender.current = false;
-  }, []);
+    registerExtensionSlot(moduleName, slotName);
+  }, [moduleName, slotName]);
 
-  useEffect(() => {
-    if (!isInitialRender.current) {
-      updateExtensionSlotState(slotName, state);
-    }
-  }, [slotName, state]);
-
-  const extensions = useAssignedExtensions(slotName);
+  // `state` must be local to the rendering rather than written to the store as state is
+  // render-specific
+  const extensions = useAssignedExtensions(slotName, state);
 
   return {
     extensions,

package/src/useExtensionSlotStore.ts

@@ -1,6 +1,26 @@
 /** @module @category Extension */
-import { type ExtensionSlotState, type ExtensionStore, getExtensionStore } from '@openmrs/esm-extensions';
+import { useCallback } from 'react';
+import {
+  type AssignedExtension,
+  type ExtensionSlotState,
+  type ExtensionStore,
+  getExtensionStore,
+} from '@openmrs/esm-extensions';
 import { useStore } from './useStore';
 
-export const useExtensionSlotStore = (slot: string) =>
-  useStore<ExtensionStore, ExtensionSlotState>(getExtensionStore(), (state) => state.slots?.[slot]);
+/**
+ * Stands in for a slot that has not been registered or attached to. Shared rather than built per
+ * call, so the snapshot stays reference-stable across renders — and frozen because that sharing
+ * means an in-place sort or push would otherwise corrupt every unregistered slot in the page.
+ */
+const emptyCandidates: Array<AssignedExtension> = [];
+Object.freeze(emptyCandidates);
+
+const emptySlotState: ExtensionSlotState = { candidateExtensions: emptyCandidates };
+Object.freeze(emptySlotState);
+
+export const useExtensionSlotStore = (slot: string) => {
+  // Memoized so that `useStore`'s snapshot function is stable across renders.
+  const select = useCallback((state: ExtensionStore) => state.slots?.[slot] ?? emptySlotState, [slot]);
+  return useStore<ExtensionStore, ExtensionSlotState>(getExtensionStore(), select);
+};

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,