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

package/src/hooks/use-pagination/use-pagination.ts

@@ -0,0 +1,266 @@
+import {
+  type MutableRefObject,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { useLatestRef } from "../internal/use-latest-ref";
+
+// ---------------------------------------------------------------------------
+// Interfaces
+// ---------------------------------------------------------------------------
+
+export interface UsePaginationProps {
+  /** Total number of items. Required. */
+  totalItems: number;
+  /** Controlled page size. Pair with defaultPageSize / onPageSizeChange. */
+  pageSize?: number;
+  /** Initial page size (uncontrolled). @default 10 */
+  defaultPageSize?: number;
+  /** Fired when page size changes. Stable via useLatestRef. */
+  onPageSizeChange?: (size: number) => void;
+  /** Controlled current page. */
+  page?: number;
+  /** Initial page (uncontrolled). @default 1 */
+  defaultPage?: number;
+  /** Fired when page changes. Stable via useLatestRef. */
+  onPageChange?: (page: number) => void;
+  /**
+   * Fired once with BOTH resolved values whenever page or pageSize changes.
+   * Ideal as a single data-fetching trigger — no need to wire a `useEffect` on
+   * both `page` and `pageSize`. NOT called on mount. Stable via useLatestRef.
+   */
+  onPaginationChange?: (state: { page: number; pageSize: number }) => void;
+}
+
+export interface UsePaginationActions {
+  /** Go to the next page. No-op on last page. Stable reference. */
+  next: () => void;
+  /** Go to the previous page. No-op on first page. Stable reference. */
+  prev: () => void;
+  /** Jump to the first page. Stable reference. */
+  firstPage: () => void;
+  /** Jump to the last page. Stable reference. */
+  lastPage: () => void;
+  /** Jump to a specific page, clamped to [1, pageCount]. Stable reference. */
+  goTo: (page: number) => void;
+  /** Change the page size. Resets to page 1. Stable reference. */
+  setPageSize: (size: number) => void;
+}
+
+export interface UsePaginationReturn extends UsePaginationActions {
+  /** Current active page (1-indexed). */
+  page: number;
+  /** Current page size. */
+  pageSize: number;
+  /** Total number of pages. 0 when there are no items. */
+  pageCount: number;
+  /** Whether the current page is the first. */
+  isFirstPage: boolean;
+  /** Whether the current page is the last. */
+  isLastPage: boolean;
+  /** Whether there is a previous page. */
+  hasPrevPage: boolean;
+  /** Whether there is a next page. */
+  hasNextPage: boolean;
+  /** 1-based item range for the current page. */
+  range: { start: number; end: number };
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_PAGE_SIZE = 10;
+const DEFAULT_PAGE = 1;
+
+// ---------------------------------------------------------------------------
+// Pure helpers (no React)
+// ---------------------------------------------------------------------------
+
+function coercePageSize(
+  size: number,
+  warnedRef?: MutableRefObject<boolean>,
+): number {
+  if (size <= 0 || Number.isNaN(size)) {
+    if (process.env.NODE_ENV !== "production") {
+      if (!warnedRef || !warnedRef.current) {
+        if (warnedRef) warnedRef.current = true;
+        console.warn(
+          `[usePagination] pageSize must be a positive number, received ${size}. Coercing to 1.`,
+        );
+      }
+    }
+    return 1;
+  }
+  return Math.floor(size);
+}
+
+function computePageCount(totalItems: number, pageSize: number): number {
+  if (totalItems <= 0) return 0;
+  return Math.ceil(totalItems / pageSize);
+}
+
+function clampPage(page: number, pageCount: number): number {
+  if (pageCount <= 0) return 1;
+  if (Number.isNaN(page)) return 1;
+  return Math.min(Math.max(1, Math.floor(page)), pageCount);
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+export function usePagination({
+  totalItems,
+  pageSize: pageSizeProp,
+  defaultPageSize = DEFAULT_PAGE_SIZE,
+  onPageSizeChange,
+  page: pageProp,
+  defaultPage = DEFAULT_PAGE,
+  onPageChange,
+  onPaginationChange,
+}: UsePaginationProps): UsePaginationReturn {
+  // Internal state (uncontrolled path)
+  const [pageState, setPageState] = useState(defaultPage);
+  const [pageSizeState, setPageSizeState] = useState(defaultPageSize);
+
+  // Warn once per instance when pageSize is invalid
+  const warnedRef = useRef(false);
+
+  // Resolve controlled-vs-uncontrolled each render
+  const pageSize = coercePageSize(pageSizeProp ?? pageSizeState, warnedRef);
+  const pageCount = computePageCount(totalItems, pageSize);
+  const page = clampPage(pageProp ?? pageState, pageCount);
+
+  // Refs so memoized actions read live values without stale closures
+  const pageRef = useLatestRef(page);
+  const pageSizeRef = useLatestRef(pageSize);
+  const pageCountRef = useLatestRef(pageCount);
+  const onPageChangeRef = useLatestRef(onPageChange);
+  const onPageSizeChangeRef = useLatestRef(onPageSizeChange);
+  const onPaginationChangeRef = useLatestRef(onPaginationChange);
+
+  // Fire callbacks on real transitions, never on mount
+  const mountedRef = useRef(false);
+
+  // Track last-emitted page/pageSize to detect real changes.
+  // We watch pageState (not the resolved page) so controlled mode also fires the callback.
+  // The callback receives the resolved/clamped value.
+  const lastEmittedPageRef = useRef<number | null>(null);
+  const lastEmittedPageSizeRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    if (!mountedRef.current) return;
+    // Compute what page the current pageState would resolve to (for callback)
+    const resolved = clampPage(pageState, pageCountRef.current);
+    if (lastEmittedPageRef.current === resolved) return;
+    lastEmittedPageRef.current = resolved;
+    onPageChangeRef.current?.(resolved);
+  }, [pageState]);
+
+  useEffect(() => {
+    if (!mountedRef.current) return;
+    const resolved = coercePageSize(pageSizeState);
+    if (lastEmittedPageSizeRef.current === resolved) return;
+    lastEmittedPageSizeRef.current = resolved;
+    onPageSizeChangeRef.current?.(resolved);
+  }, [pageSizeState]);
+
+  // Unified change callback. Keyed on the RESOLVED render-time values (not the
+  // internal state) so it fires exactly once per logical transition in both
+  // controlled and uncontrolled modes: when setPageSize batches a page+pageSize
+  // change into a single render, this effect sees both final values together.
+  useEffect(() => {
+    if (!mountedRef.current) return;
+    onPaginationChangeRef.current?.({ page, pageSize });
+  }, [page, pageSize]);
+
+  useEffect(() => {
+    mountedRef.current = true;
+  }, []);
+
+  // Actions built once — setState identities are stable → memo computes once
+  const actions = useMemo<UsePaginationActions>(() => {
+    const applyPage = (target: number) => {
+      const clamped = clampPage(target, pageCountRef.current);
+      if (clamped === pageRef.current) return; // no-op for same page
+      setPageState(clamped);
+    };
+
+    return {
+      goTo: (target) => {
+        if (pageCountRef.current <= 0) return;
+        applyPage(target);
+      },
+      next: () => {
+        if (pageRef.current >= pageCountRef.current) return;
+        applyPage(pageRef.current + 1);
+      },
+      prev: () => {
+        if (pageRef.current <= 1) return;
+        applyPage(pageRef.current - 1);
+      },
+      firstPage: () => {
+        if (pageCountRef.current <= 0) return;
+        applyPage(1);
+      },
+      lastPage: () => {
+        if (pageCountRef.current <= 0) return;
+        applyPage(pageCountRef.current);
+      },
+      setPageSize: (size) => {
+        const coerced = coercePageSize(size);
+        // No-op if same size
+        if (coerced === pageSizeRef.current) return;
+
+        // setPageSize mutates TWO values: pageSize and (reset) page. Both
+        // callbacks MUST fire synchronously here, inside the same event-handler
+        // tick, so a fully-controlled consumer's two setState calls batch into a
+        // single render. If pageSize fired from its useEffect while page fired
+        // synchronously, the controlled values would land in separate renders and
+        // a consumer effect keyed on [page, pageSize] would run twice (once per
+        // value), causing a duplicate fetch.
+        //
+        // We stamp the lastEmitted refs first so the useEffect transitions below
+        // recognize these values as already-emitted and skip re-firing.
+        lastEmittedPageSizeRef.current = coerced;
+        setPageSizeState(coerced);
+        onPageSizeChangeRef.current?.(coerced);
+
+        // Reset to page 1. In controlled mode the internal pageState may already
+        // be 1 (its default), so setPageState(1) alone would be a no-op and the
+        // page useEffect would never fire — onPageChange would be silently
+        // skipped. Fire it directly when the resolved page is not already 1.
+        if (pageRef.current !== 1) {
+          lastEmittedPageRef.current = 1;
+          onPageChangeRef.current?.(1);
+        }
+        setPageState(1);
+      },
+    };
+  }, [setPageState, setPageSizeState]);
+
+  const isFirstPage = pageCount <= 0 ? true : page <= 1;
+  const isLastPage = pageCount <= 0 ? true : page >= pageCount;
+  const range =
+    totalItems <= 0
+      ? { start: 0, end: 0 }
+      : {
+          start: (page - 1) * pageSize + 1,
+          end: Math.min(page * pageSize, totalItems),
+        };
+
+  return {
+    page,
+    pageSize,
+    pageCount,
+    isFirstPage,
+    isLastPage,
+    hasPrevPage: !isFirstPage,
+    hasNextPage: !isLastPage,
+    range,
+    ...actions,
+  };
+}

package/src/hooks/use-prevent-page-close/use-prevent-page-close.stories.tsx

@@ -11,7 +11,6 @@ import { usePreventPageClose } from "./use-prevent-page-close";
  */
 const meta: Meta = {
   title: "hooks/usePreventPageClose",
-  tags: ["beta"],
   args: {
     enabled: true,
   },

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

@@ -34,7 +34,7 @@ describe("usePagination hook", () => {
       useRangePagination({
         totalItems: 10,
         pageSize: 1,
-        initialCurrentPage: 8,
+        defaultPage: 8,
       }),
     );
 
@@ -46,7 +46,7 @@ describe("usePagination hook", () => {
       useRangePagination({
         totalItems: 10,
         pageSize: 1,
-        initialCurrentPage: 5,
+        defaultPage: 5,
       }),
     );
 

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

@@ -3,24 +3,24 @@ import { useMemo } from "react";
 const range = (start: number, end: number): number[] =>
   Array.from({ length: end - start }, (_, i) => i + start);
 
-import { usePagination, type usePaginationProps } from "../../hooks";
+import { type UsePaginationProps, usePagination } from "../../hooks";
 
 export const DOTS = "...";
 
-export type useRangePaginationProps = {
+export type UseRangePaginationProps = {
   /**
-   * Cantidad de elementos visibles al lado de la pagina actual
+   * Visible siblings on each side of the current page.
    */
   siblingCount?: number;
-} & usePaginationProps;
+} & UsePaginationProps;
 
 export const useRangePagination = ({
   siblingCount = 1,
   ...paginationProps
-}: useRangePaginationProps) => {
+}: UseRangePaginationProps) => {
   const pagination = usePagination(paginationProps);
-  const { currentPage, maxPage } = pagination;
-  const { totalItems, pageSize } = paginationProps;
+  const { page, pageCount, pageSize } = pagination;
+  const { totalItems } = paginationProps;
 
   const generateRange = () => {
     const DOTS_THRESHOLD = 2;
@@ -28,33 +28,36 @@ export const useRangePagination = ({
     const ITEMS_UNTIL_DOTS = DOTS_THRESHOLD + EXTRA_ITEMS * siblingCount;
     const FIRST_PAGE = 1;
 
-    // No hay suficientes elementos para agregar DOTS
-    if (ITEMS_UNTIL_DOTS >= maxPage) {
-      return range(FIRST_PAGE, maxPage + 1);
+    // Not enough pages to show dots
+    if (ITEMS_UNTIL_DOTS >= pageCount) {
+      return range(FIRST_PAGE, pageCount + 1);
     }
 
-    // índice de elemento de izquierda y derecha
-    const leftSiblingIndex = Math.max(currentPage - siblingCount, 1);
-    const rightSiblingIndex = Math.min(currentPage + siblingCount, maxPage);
+    // Left and right sibling indices
+    const leftSiblingIndex = Math.max(page - siblingCount, 1);
+    const rightSiblingIndex = Math.min(page + siblingCount, pageCount);
 
     const shouldShowLeftDots = leftSiblingIndex > DOTS_THRESHOLD;
-    const shouldShowRightDots = rightSiblingIndex < maxPage - DOTS_THRESHOLD;
+    const shouldShowRightDots = rightSiblingIndex < pageCount - DOTS_THRESHOLD;
 
-    // Debe mostrar DOTS de ambos lados
+    // Show dots on both sides
     if (shouldShowLeftDots && shouldShowRightDots) {
       const middleElements = range(leftSiblingIndex, rightSiblingIndex + 1);
-      return [FIRST_PAGE, DOTS, ...middleElements, DOTS, maxPage];
+      return [FIRST_PAGE, DOTS, ...middleElements, DOTS, pageCount];
     }
 
-    // Debe mostrar DOTS a la derecha
+    // Show dots on the right only
     if (shouldShowRightDots) {
       const leftElements = range(FIRST_PAGE, ITEMS_UNTIL_DOTS + 1);
-      return [...leftElements, DOTS, maxPage];
+      return [...leftElements, DOTS, pageCount];
     }
 
-    // Debe mostrar DOTS a la izquierda
+    // Show dots on the left only
     if (shouldShowLeftDots) {
-      const rightElements = range(maxPage - ITEMS_UNTIL_DOTS + 1, maxPage + 1);
+      const rightElements = range(
+        pageCount - ITEMS_UNTIL_DOTS + 1,
+        pageCount + 1,
+      );
       return [FIRST_PAGE, DOTS, ...rightElements];
     }
   };
@@ -62,7 +65,7 @@ export const useRangePagination = ({
   const paginationRange = useMemo(generateRange, [
     totalItems,
     pageSize,
-    currentPage,
+    page,
     siblingCount,
   ]);