@boxcustodia/library 2.0.0-alpha.22 → 2.0.0-alpha.23

package/src/hooks/use-pagination/use-pagination.test.tsx

@@ -1,98 +1,610 @@
-import { act, renderHook, waitFor } from "@testing-library/react";
-import { describe, expect, it } from "vitest";
+import {
+  act,
+  fireEvent,
+  render,
+  renderHook,
+  screen,
+} from "@testing-library/react";
+import { useEffect, useState } from "react";
+import { describe, expect, it, vi } from "vitest";
 import { usePagination } from "../use-pagination";
 
-describe("usePagination hook", () => {
-  it("should be defined", () => {
-    expect(usePagination).toBeDefined();
+// ---------------------------------------------------------------------------
+// Scenarios 1–5: Default Initial State
+// ---------------------------------------------------------------------------
+
+describe("usePagination — Default Initial State", () => {
+  it("Scenario 1 — default initialization: page=1, pageSize=10, pageCount=10", () => {
+    const { result } = renderHook(() => usePagination({ totalItems: 100 }));
+    expect(result.current.page).toBe(1);
+    expect(result.current.pageSize).toBe(10);
+    expect(result.current.pageCount).toBe(10);
+  });
+
+  it("Scenario 2 — defaultPage seeds initial page", () => {
+    const { result } = renderHook(() =>
+      usePagination({ totalItems: 100, defaultPage: 3, defaultPageSize: 10 }),
+    );
+    expect(result.current.page).toBe(3);
+  });
+
+  it("Scenario 3 — defaultPageSize seeds initial pageSize", () => {
+    const { result } = renderHook(() =>
+      usePagination({ totalItems: 100, defaultPageSize: 20 }),
+    );
+    expect(result.current.pageSize).toBe(20);
+    expect(result.current.pageCount).toBe(5);
   });
 
-  it("should show total items and items per page", () => {
+  it("Scenario 4 — totalItems=0 edge case", () => {
+    const { result } = renderHook(() => usePagination({ totalItems: 0 }));
+    expect(result.current.pageCount).toBe(0);
+    expect(result.current.page).toBe(1);
+    expect(result.current.isFirstPage).toBe(true);
+    expect(result.current.isLastPage).toBe(true);
+    expect(result.current.hasPrevPage).toBe(false);
+    expect(result.current.hasNextPage).toBe(false);
+    expect(result.current.range).toEqual({ start: 0, end: 0 });
+  });
+
+  it("Scenario 5 — pageSize=0 guard: coerced to 1, console.warn called", () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { result } = renderHook(() =>
+      usePagination({ totalItems: 100, defaultPageSize: 0 }),
+    );
+    expect(result.current.pageSize).toBe(1);
+    expect(warnSpy).toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scenarios 6–16: Navigation Actions
+// ---------------------------------------------------------------------------
+
+describe("usePagination — Navigation Actions", () => {
+  it("Scenario 6 — next() increments page", () => {
+    const onPageChange = vi.fn();
     const { result } = renderHook(() =>
       usePagination({
-        totalItems: 100,
-        pageSize: 10,
+        totalItems: 50,
+        defaultPageSize: 10,
+        defaultPage: 2,
+        onPageChange,
+      }),
+    );
+    act(() => result.current.next());
+    expect(result.current.page).toBe(3);
+    expect(onPageChange).toHaveBeenCalledWith(3);
+  });
+
+  it("Scenario 7 — next() no-op at last page", () => {
+    const onPageChange = vi.fn();
+    const { result } = renderHook(() =>
+      usePagination({
+        totalItems: 50,
+        defaultPageSize: 10,
+        defaultPage: 5,
+        onPageChange,
+      }),
+    );
+    act(() => result.current.next());
+    expect(result.current.page).toBe(5);
+    expect(onPageChange).not.toHaveBeenCalled();
+  });
+
+  it("Scenario 8 — prev() decrements page", () => {
+    const onPageChange = vi.fn();
+    const { result } = renderHook(() =>
+      usePagination({
+        totalItems: 50,
+        defaultPageSize: 10,
+        defaultPage: 3,
+        onPageChange,
+      }),
+    );
+    act(() => result.current.prev());
+    expect(result.current.page).toBe(2);
+    expect(onPageChange).toHaveBeenCalledWith(2);
+  });
+
+  it("Scenario 9 — prev() no-op at first page", () => {
+    const onPageChange = vi.fn();
+    const { result } = renderHook(() =>
+      usePagination({
+        totalItems: 50,
+        defaultPageSize: 10,
+        defaultPage: 1,
+        onPageChange,
+      }),
+    );
+    act(() => result.current.prev());
+    expect(result.current.page).toBe(1);
+    expect(onPageChange).not.toHaveBeenCalled();
+  });
+
+  it("Scenario 10 — firstPage() jumps to page 1", () => {
+    const onPageChange = vi.fn();
+    const { result } = renderHook(() =>
+      usePagination({
+        totalItems: 50,
+        defaultPageSize: 10,
+        defaultPage: 4,
+        onPageChange,
+      }),
+    );
+    act(() => result.current.firstPage());
+    expect(result.current.page).toBe(1);
+    expect(onPageChange).toHaveBeenCalledWith(1);
+  });
+
+  it("Scenario 10b — firstPage() no-op when already first", () => {
+    const onPageChange = vi.fn();
+    const { result } = renderHook(() =>
+      usePagination({
+        totalItems: 50,
+        defaultPageSize: 10,
+        defaultPage: 1,
+        onPageChange,
+      }),
+    );
+    act(() => result.current.firstPage());
+    expect(result.current.page).toBe(1);
+    expect(onPageChange).not.toHaveBeenCalled();
+  });
+
+  it("Scenario 11 — lastPage() jumps to pageCount", () => {
+    const onPageChange = vi.fn();
+    const { result } = renderHook(() =>
+      usePagination({
+        totalItems: 50,
+        defaultPageSize: 10,
+        defaultPage: 2,
+        onPageChange,
+      }),
+    );
+    act(() => result.current.lastPage());
+    expect(result.current.page).toBe(5);
+    expect(onPageChange).toHaveBeenCalledWith(5);
+  });
+
+  it("Scenario 11b — lastPage() no-op when already last", () => {
+    const onPageChange = vi.fn();
+    const { result } = renderHook(() =>
+      usePagination({
+        totalItems: 50,
+        defaultPageSize: 10,
+        defaultPage: 5,
+        onPageChange,
+      }),
+    );
+    act(() => result.current.lastPage());
+    expect(result.current.page).toBe(5);
+    expect(onPageChange).not.toHaveBeenCalled();
+  });
+
+  it("Scenario 12 — goTo(n) jumps to n", () => {
+    const onPageChange = vi.fn();
+    const { result } = renderHook(() =>
+      usePagination({
+        totalItems: 50,
+        defaultPageSize: 10,
+        defaultPage: 1,
+        onPageChange,
+      }),
+    );
+    act(() => result.current.goTo(3));
+    expect(result.current.page).toBe(3);
+    expect(onPageChange).toHaveBeenCalledWith(3);
+  });
+
+  it("Scenario 13 — goTo clamps above pageCount", () => {
+    const onPageChange = vi.fn();
+    const { result } = renderHook(() =>
+      usePagination({
+        totalItems: 50,
+        defaultPageSize: 10,
+        defaultPage: 1,
+        onPageChange,
       }),
     );
-    const { maxPage, currentPage } = result.current;
+    act(() => result.current.goTo(99));
+    expect(result.current.page).toBe(5);
+    expect(onPageChange).toHaveBeenCalledWith(5);
+  });
 
-    expect(maxPage).toBe(10);
-    expect(currentPage).toBe(1);
+  it("Scenario 14 — goTo clamps below 1", () => {
+    const onPageChange = vi.fn();
+    const { result } = renderHook(() =>
+      usePagination({ totalItems: 50, defaultPageSize: 10, onPageChange }),
+    );
+    act(() => result.current.goTo(-2));
+    expect(result.current.page).toBe(1);
+    // Already at page 1, no change → no-op
+    expect(onPageChange).not.toHaveBeenCalled();
   });
 
-  it("should recive initial current page", () => {
+  it("Scenario 15 — goTo(currentPage) is no-op", () => {
+    const onPageChange = vi.fn();
+    const { result } = renderHook(() =>
+      usePagination({
+        totalItems: 50,
+        defaultPageSize: 10,
+        defaultPage: 3,
+        onPageChange,
+      }),
+    );
+    act(() => result.current.goTo(3));
+    expect(result.current.page).toBe(3);
+    expect(onPageChange).not.toHaveBeenCalled();
+  });
+
+  it("Scenario 16 — goTo when pageCount=0 is no-op", () => {
+    const onPageChange = vi.fn();
+    const { result } = renderHook(() =>
+      usePagination({ totalItems: 0, onPageChange }),
+    );
+    act(() => result.current.goTo(1));
+    expect(onPageChange).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scenarios 17–19: Page Size Control
+// ---------------------------------------------------------------------------
+
+describe("usePagination — Page Size Control", () => {
+  it("Scenario 17 — setPageSize(n) changes pageSize and resets page to 1", () => {
+    const { result } = renderHook(() =>
+      usePagination({ totalItems: 100, defaultPageSize: 10, defaultPage: 3 }),
+    );
+    act(() => result.current.setPageSize(20));
+    expect(result.current.pageSize).toBe(20);
+    expect(result.current.page).toBe(1);
+    expect(result.current.pageCount).toBe(5);
+  });
+
+  it("Scenario 18 — setPageSize fires callbacks in order: onPageSizeChange then onPageChange(1)", () => {
+    const onPageSizeChange = vi.fn();
+    const onPageChange = vi.fn();
     const { result } = renderHook(() =>
       usePagination({
         totalItems: 100,
-        pageSize: 10,
-        initialCurrentPage: 5,
+        defaultPageSize: 10,
+        defaultPage: 3,
+        onPageSizeChange,
+        onPageChange,
       }),
     );
-    const { currentPage } = result.current;
-    expect(currentPage).toBe(5);
+    act(() => result.current.setPageSize(20));
+    expect(onPageSizeChange).toHaveBeenCalledWith(20);
+    expect(onPageChange).toHaveBeenCalledWith(1);
   });
 
-  it("should go next", () => {
+  it("Scenario 19 — setPageSize same size is no-op", () => {
+    const onPageSizeChange = vi.fn();
+    const onPageChange = vi.fn();
     const { result } = renderHook(() =>
       usePagination({
         totalItems: 100,
-        pageSize: 10,
+        defaultPageSize: 10,
+        onPageSizeChange,
+        onPageChange,
+      }),
+    );
+    act(() => result.current.setPageSize(10));
+    expect(onPageSizeChange).not.toHaveBeenCalled();
+    expect(onPageChange).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scenarios 20–23: Controllable Page
+// ---------------------------------------------------------------------------
+
+describe("usePagination — Controllable Page", () => {
+  it("Scenario 20 — page prop controls current page", () => {
+    const { result } = renderHook(() =>
+      usePagination({ totalItems: 50, defaultPageSize: 10, page: 3 }),
+    );
+    expect(result.current.page).toBe(3);
+  });
+
+  it("Scenario 21 — onPageChange fires on navigation (controlled)", () => {
+    const onPageChange = vi.fn();
+    const { result } = renderHook(() =>
+      usePagination({
+        totalItems: 50,
+        defaultPageSize: 10,
+        page: 2,
+        onPageChange,
       }),
     );
-    const { next } = result.current;
-    act(() => next());
+    act(() => result.current.next());
+    expect(onPageChange).toHaveBeenCalledWith(3);
+  });
 
-    const { currentPage } = result.current;
-    expect(currentPage).toBe(2);
+  it("Scenario 22 — onPageChange NOT fired on mount", () => {
+    const onPageChange = vi.fn();
+    renderHook(() =>
+      usePagination({
+        totalItems: 50,
+        defaultPageSize: 10,
+        page: 1,
+        onPageChange,
+      }),
+    );
+    expect(onPageChange).not.toHaveBeenCalled();
   });
 
-  it("should go previous", () => {
+  it("Scenario 23 — onPageChange NOT fired for no-op actions", () => {
+    const onPageChange = vi.fn();
     const { result } = renderHook(() =>
       usePagination({
-        totalItems: 100,
-        pageSize: 10,
-        initialCurrentPage: 3,
+        totalItems: 50,
+        defaultPageSize: 10,
+        page: 1,
+        onPageChange,
       }),
     );
-    const { prev } = result.current;
-    act(() => prev());
+    act(() => result.current.prev());
+    expect(onPageChange).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scenarios 24–26: Controllable Page Size
+// ---------------------------------------------------------------------------
+
+describe("usePagination — Controllable Page Size", () => {
+  it("Scenario 24 — pageSize prop controls current pageSize", () => {
+    const { result } = renderHook(() =>
+      usePagination({ totalItems: 100, pageSize: 20 }),
+    );
+    expect(result.current.pageSize).toBe(20);
+  });
+
+  it("Scenario 25 — onPageSizeChange fires after setPageSize (controlled)", () => {
+    const onPageSizeChange = vi.fn();
+    const { result } = renderHook(() =>
+      usePagination({ totalItems: 100, pageSize: 10, onPageSizeChange }),
+    );
+    act(() => result.current.setPageSize(25));
+    expect(onPageSizeChange).toHaveBeenCalledWith(25);
+  });
 
-    const { currentPage } = result.current;
-    expect(currentPage).toBe(2);
+  it("Scenario 26 — onPageSizeChange NOT fired on mount", () => {
+    const onPageSizeChange = vi.fn();
+    renderHook(() =>
+      usePagination({ totalItems: 100, pageSize: 10, onPageSizeChange }),
+    );
+    expect(onPageSizeChange).not.toHaveBeenCalled();
   });
 
-  it("should go to page number", () => {
+  it("Scenario 26b — setPageSize fires onPageChange(1) in controlled mode when page prop > 1", () => {
+    const onPageChange = vi.fn();
+    const { result } = renderHook(() =>
+      usePagination({ totalItems: 100, page: 3, onPageChange }),
+    );
+    act(() => result.current.setPageSize(20));
+    expect(onPageChange).toHaveBeenCalledWith(1);
+  });
+
+  it("Scenario 26c — fully controlled: setPageSize batches page+pageSize so a consumer effect keyed on [page, pageSize] runs once", () => {
+    const fetchSpy = vi.fn();
+
+    function Consumer() {
+      const [page, setPage] = useState(3);
+      const [pageSize, setPageSize] = useState(10);
+      const pagination = usePagination({
+        totalItems: 100,
+        page,
+        onPageChange: setPage,
+        pageSize,
+        onPageSizeChange: setPageSize,
+      });
+
+      useEffect(() => {
+        fetchSpy({ page: pagination.page, pageSize: pagination.pageSize });
+      }, [pagination.page, pagination.pageSize]);
+
+      return (
+        <button type="button" onClick={() => pagination.setPageSize(20)}>
+          change
+        </button>
+      );
+    }
+
+    render(<Consumer />);
+    // Ignore the mount fire — we only care about the transition.
+    fetchSpy.mockClear();
+
+    fireEvent.click(screen.getByText("change"));
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    expect(fetchSpy).toHaveBeenCalledWith({ page: 1, pageSize: 20 });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scenarios 26d–26g: Unified onPaginationChange
+// ---------------------------------------------------------------------------
+
+describe("usePagination — Unified onPaginationChange", () => {
+  it("Scenario 26d — NOT fired on mount", () => {
+    const onPaginationChange = vi.fn();
+    renderHook(() => usePagination({ totalItems: 100, onPaginationChange }));
+    expect(onPaginationChange).not.toHaveBeenCalled();
+  });
+
+  it("Scenario 26e — fires once with both values when navigating", () => {
+    const onPaginationChange = vi.fn();
     const { result } = renderHook(() =>
       usePagination({
         totalItems: 100,
-        pageSize: 10,
+        defaultPageSize: 10,
+        onPaginationChange,
       }),
     );
-    const { goTo, currentPage } = result.current;
-    act(() => goTo(5));
-
-    waitFor(() => {
-      expect(currentPage).toBe(5);
-    });
+    act(() => result.current.next());
+    expect(onPaginationChange).toHaveBeenCalledTimes(1);
+    expect(onPaginationChange).toHaveBeenCalledWith({ page: 2, pageSize: 10 });
   });
 
-  it("should show isFirstPage and isLastPage", () => {
+  it("Scenario 26f — fires once with both final values when setPageSize resets page", () => {
+    const onPaginationChange = vi.fn();
     const { result } = renderHook(() =>
       usePagination({
         totalItems: 100,
-        pageSize: 10,
-        initialCurrentPage: 5,
+        defaultPage: 3,
+        defaultPageSize: 10,
+        onPaginationChange,
       }),
     );
+    act(() => result.current.setPageSize(20));
+    expect(onPaginationChange).toHaveBeenCalledTimes(1);
+    expect(onPaginationChange).toHaveBeenCalledWith({ page: 1, pageSize: 20 });
+  });
+
+  it("Scenario 26g — fully controlled: setPageSize triggers a single onPaginationChange with both values", () => {
+    const changeSpy = vi.fn();
+
+    function Consumer() {
+      const [page, setPage] = useState(3);
+      const [pageSize, setPageSize] = useState(10);
+      const pagination = usePagination({
+        totalItems: 100,
+        page,
+        onPageChange: setPage,
+        pageSize,
+        onPageSizeChange: setPageSize,
+        onPaginationChange: changeSpy,
+      });
+
+      return (
+        <button type="button" onClick={() => pagination.setPageSize(20)}>
+          change
+        </button>
+      );
+    }
+
+    render(<Consumer />);
+    changeSpy.mockClear();
+
+    fireEvent.click(screen.getByText("change"));
+
+    expect(changeSpy).toHaveBeenCalledTimes(1);
+    expect(changeSpy).toHaveBeenCalledWith({ page: 1, pageSize: 20 });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scenarios 27–33: Derived State
+// ---------------------------------------------------------------------------
+
+describe("usePagination — Derived State", () => {
+  it("Scenario 27 — isFirstPage=true when page=1", () => {
+    const { result } = renderHook(() =>
+      usePagination({ totalItems: 50, defaultPageSize: 10, defaultPage: 1 }),
+    );
+    expect(result.current.isFirstPage).toBe(true);
+    expect(result.current.hasPrevPage).toBe(false);
+  });
+
+  it("Scenario 28 — isLastPage=true when page=pageCount", () => {
+    const { result } = renderHook(() =>
+      usePagination({ totalItems: 50, defaultPageSize: 10, defaultPage: 5 }),
+    );
+    expect(result.current.isLastPage).toBe(true);
+    expect(result.current.hasNextPage).toBe(false);
+  });
+
+  it("Scenario 29 — hasPrevPage is inverse of isFirstPage", () => {
+    const { result } = renderHook(() =>
+      usePagination({ totalItems: 50, defaultPageSize: 10, defaultPage: 3 }),
+    );
+    expect(result.current.hasPrevPage).toBe(!result.current.isFirstPage);
+  });
 
-    const { isFirstPage, isLastPage, goTo, maxPage } = result.current;
-    expect(isFirstPage).toBe(false);
-    expect(isLastPage).toBe(false);
+  it("Scenario 30 — hasNextPage is inverse of isLastPage", () => {
+    const { result } = renderHook(() =>
+      usePagination({ totalItems: 50, defaultPageSize: 10, defaultPage: 3 }),
+    );
+    expect(result.current.hasNextPage).toBe(!result.current.isLastPage);
+  });
+
+  it("Scenario 31 — range.start and range.end correct for mid-page", () => {
+    const { result } = renderHook(() =>
+      usePagination({ totalItems: 100, defaultPageSize: 10, defaultPage: 2 }),
+    );
+    expect(result.current.range).toEqual({ start: 11, end: 20 });
+  });
+
+  it("Scenario 32 — range.end clamped to totalItems on last partial page", () => {
+    const { result } = renderHook(() =>
+      usePagination({ totalItems: 25, defaultPageSize: 10, defaultPage: 3 }),
+    );
+    expect(result.current.range).toEqual({ start: 21, end: 25 });
+  });
+
+  it("Scenario 33 — pageCount = ceil(totalItems / pageSize)", () => {
+    const { result } = renderHook(() =>
+      usePagination({ totalItems: 25, defaultPageSize: 10 }),
+    );
+    expect(result.current.pageCount).toBe(3);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scenarios 34–35: Reference Stability
+// ---------------------------------------------------------------------------
+
+describe("usePagination — Reference Stability", () => {
+  it("Scenario 34 — action refs are stable across re-renders", () => {
+    const { result, rerender } = renderHook(
+      (props: { totalItems: number }) => usePagination(props),
+      { initialProps: { totalItems: 100 } },
+    );
+    const { next, prev, firstPage, lastPage, goTo, setPageSize } =
+      result.current;
+    rerender({ totalItems: 100 });
+    expect(result.current.next).toBe(next);
+    expect(result.current.prev).toBe(prev);
+    expect(result.current.firstPage).toBe(firstPage);
+    expect(result.current.lastPage).toBe(lastPage);
+    expect(result.current.goTo).toBe(goTo);
+    expect(result.current.setPageSize).toBe(setPageSize);
+  });
+
+  it("Scenario 35 — latest onPageChange is called even after inline function re-creation", () => {
+    let callCount = 0;
+    let lastCallValue = 0;
+
+    // Simulate a parent that passes a new inline function on every render
+    let currentHandler = (_page: number) => {
+      callCount++;
+      lastCallValue = _page;
+    };
+    const { result, rerender } = renderHook(
+      ({ handler }: { handler: (p: number) => void }) =>
+        usePagination({
+          totalItems: 50,
+          defaultPageSize: 10,
+          onPageChange: handler,
+        }),
+      { initialProps: { handler: currentHandler } },
+    );
 
-    act(() => goTo(maxPage));
+    // Re-render with a new function reference
+    currentHandler = (_page: number) => {
+      callCount += 10;
+      lastCallValue = _page;
+    };
+    rerender({ handler: currentHandler });
 
-    waitFor(() => {
-      expect(isLastPage).toBe(true);
-    });
+    act(() => result.current.next());
+    // Should call the LATEST handler (callCount would be 10, not 1)
+    expect(callCount).toBe(10);
+    expect(lastCallValue).toBe(2);
   });
 });