@carto/ps-react-ui 4.3.2 → 4.3.4

package/src/widgets/table/hooks/use-pagination.test.ts

@@ -0,0 +1,294 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { usePagination } from './use-pagination'
+import { useWidgetStore } from '../../stores/widget-store'
+import type { TableRow } from '../types'
+
+describe('usePagination', () => {
+  const createTestData = (count: number): TableRow[] =>
+    Array.from({ length: count }, (_, i) => ({
+      id: i + 1,
+      name: `Item ${i + 1}`,
+    }))
+
+  // Clear widget store before each test
+  beforeEach(() => {
+    useWidgetStore.getState().clearWidgets()
+  })
+
+  describe('local mode', () => {
+    it('should initialize with default values', () => {
+      const data = createTestData(25)
+      const { result } = renderHook(() => usePagination('test-widget', data))
+
+      expect(result.current.page).toBe(0)
+      expect(result.current.rowsPerPage).toBe(10)
+      expect(result.current.total).toBe(25)
+      expect(result.current.rowsPerPageOptions).toEqual([5, 10, 25, 50])
+    })
+
+    it('should initialize with custom values', () => {
+      useWidgetStore.getState().setWidget('test-widget', {
+        pagination: {
+          page: 0,
+          rowsPerPage: 10,
+          rowsPerPageOptions: [10, 25, 50, 100],
+        },
+      })
+      const data = createTestData(100)
+      const { result } = renderHook(() => usePagination('test-widget', data))
+
+      expect(result.current.page).toBe(0)
+      expect(result.current.rowsPerPage).toBe(10)
+      expect(result.current.rowsPerPageOptions).toEqual([10, 25, 50, 100])
+    })
+
+    it('should paginate data correctly', () => {
+      useWidgetStore.getState().setWidget('test-widget', {
+        pagination: {
+          page: 0,
+          rowsPerPage: 10,
+        },
+      })
+      const data = createTestData(25)
+      const { result } = renderHook(() => usePagination('test-widget', data))
+
+      expect(result.current.paginatedData).toHaveLength(10)
+      expect(result.current.paginatedData[0]?.id).toBe(1)
+      expect(result.current.paginatedData[9]?.id).toBe(10)
+    })
+
+    it('should change page', () => {
+      const data = createTestData(25)
+      const { result } = renderHook(() => usePagination('test-widget', data))
+
+      act(() => {
+        result.current.setPage(1)
+      })
+
+      expect(result.current.page).toBe(1)
+      expect(result.current.paginatedData[0]?.id).toBe(11)
+    })
+
+    it('should bound page to max page', () => {
+      const data = createTestData(25)
+      const { result } = renderHook(() => usePagination('test-widget', data))
+
+      act(() => {
+        result.current.setPage(100)
+      })
+
+      // Max page for 25 items with 10 per page is 2 (pages 0, 1, 2)
+      expect(result.current.page).toBe(2)
+    })
+
+    it('should bound page to 0 for negative values', () => {
+      const data = createTestData(25)
+      const { result } = renderHook(() => usePagination('test-widget', data))
+
+      act(() => {
+        result.current.setPage(-5)
+      })
+
+      expect(result.current.page).toBe(0)
+    })
+
+    it('should change rows per page and reset to first page', () => {
+      const data = createTestData(50)
+      const { result } = renderHook(() => usePagination('test-widget', data))
+
+      // First navigate to page 2
+      act(() => {
+        result.current.setPage(2)
+      })
+
+      expect(result.current.page).toBe(2)
+
+      act(() => {
+        result.current.setRowsPerPage(25)
+      })
+
+      expect(result.current.rowsPerPage).toBe(25)
+      expect(result.current.page).toBe(0)
+    })
+
+    it('should navigate to first page', () => {
+      const data = createTestData(50)
+      const { result } = renderHook(() => usePagination('test-widget', data))
+
+      // First navigate to page 3
+      act(() => {
+        result.current.setPage(3)
+      })
+
+      act(() => {
+        result.current.goToFirstPage()
+      })
+
+      expect(result.current.page).toBe(0)
+    })
+
+    it('should navigate to last page', () => {
+      const data = createTestData(50)
+      const { result } = renderHook(() => usePagination('test-widget', data))
+
+      act(() => {
+        result.current.goToLastPage()
+      })
+
+      // 50 items / 10 per page = 5 pages (0-4)
+      expect(result.current.page).toBe(4)
+    })
+
+    it('should navigate to next page', () => {
+      const data = createTestData(50)
+      const { result } = renderHook(() => usePagination('test-widget', data))
+
+      act(() => {
+        result.current.goToNextPage()
+      })
+
+      expect(result.current.page).toBe(1)
+    })
+
+    it('should navigate to previous page', () => {
+      const data = createTestData(50)
+      const { result } = renderHook(() => usePagination('test-widget', data))
+
+      // First navigate to page 2
+      act(() => {
+        result.current.setPage(2)
+      })
+
+      act(() => {
+        result.current.goToPreviousPage()
+      })
+
+      expect(result.current.page).toBe(1)
+    })
+
+    it('should handle empty data', () => {
+      const { result } = renderHook(() => usePagination('test-widget', []))
+
+      expect(result.current.total).toBe(0)
+      expect(result.current.paginatedData).toEqual([])
+    })
+
+    it('should persist state in widget store', () => {
+      const data = createTestData(50)
+      const { result, unmount } = renderHook(() =>
+        usePagination('test-widget', data),
+      )
+
+      // Change page
+      act(() => {
+        result.current.setPage(2)
+      })
+
+      expect(result.current.page).toBe(2)
+
+      // Unmount and remount - state should persist
+      unmount()
+
+      const { result: newResult } = renderHook(() =>
+        usePagination('test-widget', data),
+      )
+
+      expect(newResult.current.page).toBe(2)
+    })
+  })
+
+  describe('remote mode', () => {
+    it('should use remote total', () => {
+      useWidgetStore.getState().setWidget('test-widget', {
+        mode: 'remote',
+        pagination: {
+          page: 0,
+          rowsPerPage: 10,
+          rowsPerPageOptions: [10],
+          total: 100,
+        },
+      })
+      const data = createTestData(10)
+      const { result } = renderHook(() => usePagination('test-widget', data))
+
+      expect(result.current.total).toBe(100)
+      // In remote mode, data is already paginated from server
+      expect(result.current.paginatedData).toHaveLength(10)
+    })
+
+    it('should update store state when page changes in remote mode', () => {
+      useWidgetStore.getState().setWidget('test-widget', {
+        mode: 'remote',
+        pagination: {
+          page: 0,
+          rowsPerPage: 10,
+          rowsPerPageOptions: [10],
+          total: 100,
+        },
+      })
+      const data = createTestData(10)
+      const { result } = renderHook(() => usePagination('test-widget', data))
+
+      act(() => {
+        result.current.setPage(2)
+      })
+
+      expect(result.current.page).toBe(2)
+    })
+
+    it('should update store state when rows per page changes in remote mode', () => {
+      useWidgetStore.getState().setWidget('test-widget', {
+        mode: 'remote',
+        pagination: {
+          page: 0,
+          rowsPerPage: 10,
+          rowsPerPageOptions: [10],
+          total: 100,
+        },
+      })
+      const data = createTestData(10)
+      const { result } = renderHook(() => usePagination('test-widget', data))
+
+      act(() => {
+        result.current.setRowsPerPage(25)
+      })
+
+      expect(result.current.rowsPerPage).toBe(25)
+      expect(result.current.page).toBe(0)
+    })
+
+    it('should handle undefined remote total', () => {
+      useWidgetStore.getState().setWidget('test-widget', {
+        mode: 'remote',
+        pagination: {
+          page: 0,
+          rowsPerPage: 10,
+          rowsPerPageOptions: [10],
+        },
+      })
+      const data = createTestData(10)
+      const { result } = renderHook(() => usePagination('test-widget', data))
+
+      expect(result.current.total).toBe(10)
+    })
+
+    it('should return data as-is in remote mode', () => {
+      useWidgetStore.getState().setWidget('test-widget', {
+        mode: 'remote',
+        pagination: {
+          page: 0,
+          rowsPerPage: 10,
+          rowsPerPageOptions: [10],
+          total: 100,
+        },
+      })
+      const data = createTestData(5)
+      const { result } = renderHook(() => usePagination('test-widget', data))
+
+      // In remote mode, paginatedData should return the data as-is
+      // since server already handles pagination
+      expect(result.current.paginatedData).toEqual(data)
+    })
+  })
+})

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

@@ -0,0 +1,155 @@
+import { useCallback, useMemo } from 'react'
+import type { TableRow, TableWidgetState } from '../types'
+import { paginateData } from '../helpers'
+import { useWidgetStore } from '../../stores/widget-store'
+import { useShallow } from 'zustand/shallow'
+import {
+  DEFAULT_PAGE,
+  DEFAULT_ROWS_PER_PAGE,
+  DEFAULT_ROWS_PER_PAGE_OPTIONS,
+} from '../config'
+
+export interface UsePaginationResult<T> {
+  /** Whether pagination is enabled */
+  paginationEnabled: boolean
+  /** Current page (0-indexed) */
+  page: number
+  /** Rows per page */
+  rowsPerPage: number
+  /** Total row count */
+  total: number
+  /** Available rows per page options */
+  rowsPerPageOptions: number[]
+  /** Paginated data (for local mode) */
+  paginatedData: T[]
+  /** Set current page */
+  setPage: (page: number) => void
+  /** Set rows per page */
+  setRowsPerPage: (rowsPerPage: number) => void
+  /** Go to first page */
+  goToFirstPage: () => void
+  /** Go to last page */
+  goToLastPage: () => void
+  /** Go to next page */
+  goToNextPage: () => void
+  /** Go to previous page */
+  goToPreviousPage: () => void
+}
+
+/**
+ * Hook for managing table pagination
+ * Supports both local (client-side) and remote (server-side) pagination
+ * State is persisted in the widget store for the given widgetId
+ */
+export function usePagination<T extends TableRow>(
+  widgetId: string,
+  data: T[],
+): UsePaginationResult<T> {
+  // Get store actions and state
+  const setWidget = useWidgetStore((state) => state.setWidget)
+  const getWidget = useWidgetStore((state) => state.getWidget)
+  const paginationState = useWidgetStore(
+    useShallow((state) => {
+      const widget = state.widgets[widgetId] as TableWidgetState | undefined
+      return {
+        paginationEnabled: !!widget?.pagination,
+        page: widget?.pagination?.page ?? DEFAULT_PAGE,
+        rowsPerPage: widget?.pagination?.rowsPerPage ?? DEFAULT_ROWS_PER_PAGE,
+        rowsPerPageOptions:
+          widget?.pagination?.rowsPerPageOptions ??
+          DEFAULT_ROWS_PER_PAGE_OPTIONS,
+        total: widget?.pagination?.total ?? data.length,
+      }
+    }),
+  )
+
+  const mode = useWidgetStore(
+    useShallow((state) => {
+      const widget = state.widgets[widgetId] as TableWidgetState | undefined
+      return widget?.mode
+    }),
+  )
+
+  // Calculate max page
+  const maxPage = Math.max(
+    0,
+    Math.ceil(paginationState.total / (paginationState?.rowsPerPage ?? 1)) - 1,
+  )
+
+  // Set page with bounds checking
+  const setPage = useCallback(
+    (newPage: number) => {
+      // Read current state directly from store to avoid stale closures
+      const widget = getWidget<TableWidgetState>(widgetId)
+      const currentTotal = widget?.pagination?.total ?? data.length
+      const currentRowsPerPage =
+        widget?.pagination?.rowsPerPage ?? DEFAULT_ROWS_PER_PAGE
+      const currentMaxPage = Math.max(
+        0,
+        Math.ceil(currentTotal / currentRowsPerPage) - 1,
+      )
+      const boundedPage = Math.max(0, Math.min(newPage, currentMaxPage))
+
+      setWidget<TableWidgetState>(widgetId, {
+        pagination: {
+          ...widget?.pagination,
+          page: boundedPage,
+        },
+      })
+    },
+    [data.length, getWidget, setWidget, widgetId],
+  )
+
+  // Set rows per page and reset to first page
+  const setRowsPerPage = useCallback(
+    (newRowsPerPage: number) => {
+      const widget = getWidget<TableWidgetState>(widgetId)
+      setWidget<TableWidgetState>(widgetId, {
+        pagination: {
+          ...widget?.pagination,
+          rowsPerPage: newRowsPerPage,
+          page: 0, // Reset to first page when changing rows per page
+        },
+      })
+    },
+    [getWidget, setWidget, widgetId],
+  )
+
+  // Navigation helpers
+  const goToFirstPage = useCallback(() => setPage(0), [setPage])
+  const goToLastPage = useCallback(() => setPage(maxPage), [setPage, maxPage])
+  const goToNextPage = useCallback(
+    () => setPage(paginationState.page + 1),
+    [setPage, paginationState.page],
+  )
+  const goToPreviousPage = useCallback(
+    () => setPage(paginationState.page - 1),
+    [setPage, paginationState.page],
+  )
+
+  // Paginated data for local mode
+  const paginatedData = useMemo(() => {
+    if (mode === 'remote' || !paginationState.paginationEnabled) {
+      // For remote mode, data is already paginated from server
+      return data
+    }
+    return paginateData(data, paginationState.page, paginationState.rowsPerPage)
+  }, [
+    data,
+    mode,
+    paginationState.page,
+    paginationState.paginationEnabled,
+    paginationState.rowsPerPage,
+  ])
+
+  return {
+    ...paginationState,
+    paginatedData,
+    setPage,
+    setRowsPerPage,
+    goToFirstPage,
+    goToLastPage,
+    goToNextPage,
+    goToPreviousPage,
+  }
+}