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

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(
     () => ({

package/src/useShallowStableValue.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { useShallowStableValue } from './useShallowStableValue';
+
+describe('useShallowStableValue', () => {
+  it('keeps its reference across an equal object literal', () => {
+    const { result, rerender } = renderHook(({ value }) => useShallowStableValue(value), {
+      initialProps: { value: { patientUuid: 'abc' } },
+    });
+    const first = result.current;
+
+    rerender({ value: { patientUuid: 'abc' } });
+
+    expect(result.current).toBe(first);
+  });
+
+  it('takes the new reference when a value changes', () => {
+    const { result, rerender } = renderHook(({ value }) => useShallowStableValue(value), {
+      initialProps: { value: { patientUuid: 'abc' } },
+    });
+    const first = result.current;
+    const next = { patientUuid: 'def' };
+
+    rerender({ value: next });
+
+    expect(result.current).not.toBe(first);
+    expect(result.current).toBe(next);
+  });
+
+  it('takes the new reference when a key is added or removed', () => {
+    const { result, rerender } = renderHook(({ value }) => useShallowStableValue(value), {
+      initialProps: { value: { a: 1 } as Record<string, number> },
+    });
+    const first = result.current;
+
+    rerender({ value: { a: 1, b: 2 } });
+    expect(result.current).not.toBe(first);
+
+    const both = result.current;
+    rerender({ value: { a: 1 } });
+    expect(result.current).not.toBe(both);
+  });
+
+  it('returns the latest of two equal values rather than the first one it ever saw', () => {
+    const { result, rerender } = renderHook(({ value }) => useShallowStableValue(value), {
+      initialProps: { value: { n: 1 } },
+    });
+    const first = result.current;
+
+    rerender({ value: { n: 2 } });
+    const third = { n: 1 };
+    rerender({ value: third });
+
+    // Equal to the first value, but the run of equal values was broken, so it is a new reference.
+    expect(result.current).toBe(third);
+    expect(result.current).not.toBe(first);
+  });
+
+  it('compares only one level deep', () => {
+    const { result, rerender } = renderHook(({ value }) => useShallowStableValue(value), {
+      initialProps: { value: { patient: { uuid: 'abc' } } },
+    });
+    const first = result.current;
+
+    rerender({ value: { patient: { uuid: 'abc' } } });
+
+    expect(result.current).not.toBe(first);
+  });
+});

package/src/useShallowStableValue.ts

@@ -0,0 +1,24 @@
+/** @module @category Utility */
+import { useRef } from 'react';
+import { shallowEqual } from '@openmrs/esm-utils';
+
+/**
+ * Returns `value` with a reference that only changes when its contents do, so that it can be used
+ * as a dependency of `useMemo`, `useEffect` and friends.
+ *
+ * This exists for props that are almost always written as object literals — `state={{ patientUuid }}`
+ * — which get a new identity on every render while meaning the same thing. Comparison is shallow,
+ * so a value nested more than one level deep still reads as a change.
+ *
+ * @param value The value to stabilize
+ * @returns `value`, or the last value this hook returned if the two are shallowly equal
+ */
+export function useShallowStableValue<T>(value: T): T {
+  const stable = useRef(value);
+
+  if (!shallowEqual(stable.current, value)) {
+    stable.current = value;
+  }
+
+  return stable.current;
+}

package/src/useStore.test.ts

@@ -1,3 +1,4 @@
+import React from 'react';
 import { describe, expect, it } from 'vitest';
 import { act, renderHook } from '@testing-library/react';
 import { createGlobalStore } from '@openmrs/esm-state';
@@ -25,6 +26,44 @@ describe('useStore', () => {
   });
 });
 
+describe('useStore reference stability', () => {
+  it('returns the store state itself when there are no actions to merge in', () => {
+    const store = createGlobalStore('stability-plain', { renderings: new Map<string, number>() });
+    const { result, rerender } = renderHook(() => useStore(store));
+
+    // Not a copy: consumers of the extension renderings store depend on this, because the map
+    // inside is mutated in place and only the state object around it changes identity.
+    expect(result.current).toBe(store.getState());
+
+    const before = result.current;
+    rerender();
+    expect(result.current).toBe(before);
+  });
+
+  it('keeps its reference across an unrelated re-render, so it can be a memo dependency', () => {
+    const store = createGlobalStore('stability-memo', { a: 1, b: 2 });
+    let memoRuns = 0;
+
+    const { result, rerender } = renderHook(() => {
+      const state = useStore(store);
+
+      const derived = React.useMemo(() => ++memoRuns, [state]);
+      return derived;
+    });
+
+    expect(memoRuns).toBe(1);
+    rerender();
+    expect(memoRuns).toBe(1);
+
+    act(() => {
+      store.setState({ a: 2 });
+    });
+
+    expect(memoRuns).toBe(2);
+    expect(result.current).toBe(2);
+  });
+});
+
 describe('useStoreWithActions', () => {
   it('should correctly bind actions', () => {
     const store = createGlobalStore('counter', { count: 0 });

package/src/useStore.ts

@@ -44,10 +44,14 @@ function bindActions<T>(store: StoreApi<T>, actions: Actions<T>): BoundActions<T
   return bound;
 }
 
-const defaultSelectFunction =
-  <T, U>() =>
-  (x: T) =>
-    x as unknown as U;
+/**
+ * A single shared identity function, rather than one built per call: `getSnapshot` below takes
+ * the selector as a dependency, so a fresh default each render would leave it unstable for every
+ * caller that doesn't pass a selector of its own.
+ */
+const identitySelect = (x: unknown) => x;
+
+const defaultSelectFunction = <T, U>() => identitySelect as (x: T) => U;
 
 function useStore<T>(store: StoreApi<T>): T;
 function useStore<T, U>(store: StoreApi<T>, select: (state: T) => U): U;
@@ -79,12 +83,15 @@ function useStore<T, U, A extends Actions<T>>(
 
   const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 
-  let boundActions: BoundActions<T, Actions<T>> = useMemo(
-    () => (actions ? bindActions(store, actions) : {}),
+  let boundActions: BoundActions<T, Actions<T>> | null = useMemo(
+    () => (actions ? bindActions(store, actions) : null),
     [store, actions],
   );
 
-  return { ...state, ...boundActions };
+  // Returned as-is when there are no actions to merge in, so the reference stays stable for as
+  // long as the selected value does. That value is not a copy — it is whatever the selector
+  // returned, usually the store's own state.
+  return useMemo(() => (boundActions ? { ...state, ...boundActions } : state), [state, boundActions]);
 }
 
 /**
@@ -110,12 +117,12 @@ function createUseStore<T>(store: StoreApi<T>) {
     const getSnapshot = useCallback(() => store.getState(), []);
     const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 
-    let boundActions: BoundActions<T, Actions<T>> = useMemo(
-      () => (actions ? bindActions(store, actions) : {}),
+    let boundActions: BoundActions<T, Actions<T>> | null = useMemo(
+      () => (actions ? bindActions(store, actions) : null),
       [actions],
     );
 
-    return { ...state, ...boundActions };
+    return useMemo(() => (boundActions ? { ...state, ...boundActions } : state), [state, boundActions]);
   }
 
   return useStore;