@carto/ps-react-ui 5.0.0 → 6.0.0

package/src/widgets/table/components/pagination.tsx

@@ -1,41 +0,0 @@
-import { TablePagination as MuiTablePagination } from '@mui/material'
-import type { PaginationProps } from '../types'
-import { PaginationActions } from './pagination-actions'
-
-/**
- * Table pagination component
- */
-export function Pagination({
-  page,
-  rowsPerPage,
-  total,
-  rowsPerPageOptions = [5, 10, 25, 50],
-  onPageChange,
-  onRowsPerPageChange,
-}: PaginationProps) {
-  const handlePageChange = (
-    _event: React.MouseEvent<HTMLButtonElement> | null,
-    newPage: number,
-  ) => {
-    onPageChange(newPage)
-  }
-
-  const handleRowsPerPageChange = (
-    event: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>,
-  ) => {
-    onRowsPerPageChange(parseInt(event.target.value, 10))
-  }
-
-  return (
-    <MuiTablePagination
-      component='div'
-      count={total}
-      page={page}
-      rowsPerPage={rowsPerPage}
-      rowsPerPageOptions={rowsPerPageOptions}
-      onPageChange={handlePageChange}
-      onRowsPerPageChange={handleRowsPerPageChange}
-      ActionsComponent={PaginationActions}
-    />
-  )
-}

package/src/widgets/table/components/row.tsx

@@ -1,65 +0,0 @@
-import { TableRow as MuiTableRow, TableCell, Checkbox } from '@mui/material'
-import type { RowProps } from '../types'
-import { Cell } from './cell'
-
-/**
- * Table row component with selection and hover support
- */
-export function Row({
-  row,
-  columns,
-  isSelected = false,
-  selectable = false,
-  onClick,
-  onSelect,
-  onMouseEnter,
-  onMouseLeave,
-}: RowProps) {
-  const handleClick = () => {
-    onClick?.(row)
-  }
-
-  const handleCheckboxClick = (event: React.MouseEvent) => {
-    event.stopPropagation()
-    onSelect?.(row)
-  }
-
-  const handleMouseEnter = () => {
-    onMouseEnter?.(row)
-  }
-
-  const handleMouseLeave = () => {
-    onMouseLeave?.()
-  }
-
-  return (
-    <MuiTableRow
-      hover={!!onMouseEnter || !!onMouseLeave || !!onClick}
-      selected={isSelected}
-      onClick={handleClick}
-      onMouseEnter={handleMouseEnter}
-      onMouseLeave={handleMouseLeave}
-      sx={{
-        cursor: onClick ? 'pointer' : 'default',
-      }}
-    >
-      {selectable && (
-        <TableCell padding='checkbox'>
-          <Checkbox
-            checked={isSelected}
-            onClick={handleCheckboxClick}
-            inputProps={{ 'aria-label': `select row ${row.id}` }}
-          />
-        </TableCell>
-      )}
-      {columns.map((column) => (
-        <Cell
-          key={column.id}
-          row={row}
-          column={column}
-          value={row[column.id]}
-        />
-      ))}
-    </MuiTableRow>
-  )
-}

package/src/widgets/table/config.test.ts

@@ -1,65 +0,0 @@
-import { describe, it, expect } from 'vitest'
-import { createRef } from 'react'
-import { tableConfig, tableDownloadConfig } from './config'
-
-describe('tableConfig', () => {
-  it('returns config with the provided columns', () => {
-    const columns = [
-      { id: 'name', label: 'Name' },
-      { id: 'age', label: 'Age' },
-    ] satisfies Parameters<typeof tableConfig>[0]
-    const cfg = tableConfig(columns)
-    expect(cfg.columns).toBe(columns)
-    expect(cfg.mode).toBe('local')
-    expect(cfg.selectable).toBe(false)
-  })
-
-  it('defaults to empty columns when no argument passed', () => {
-    const cfg = tableConfig()
-    expect(cfg.columns).toEqual([])
-  })
-})
-
-describe('tableDownloadConfig', () => {
-  const refUI = createRef<HTMLDivElement>()
-
-  it('returns a two-item download config (PNG + CSV)', () => {
-    const cfg = tableDownloadConfig({ refUI })
-    expect(cfg).toHaveLength(2)
-  })
-
-  it('CSV modifier handles populated row data with mixed value types', async () => {
-    const cfg = tableDownloadConfig({ refUI })
-    const csvItem = cfg[1]!
-    const rows = [
-      { id: '1', name: 'A', value: 10, meta: { tag: 'x' } },
-      { id: '2', name: 'B', value: null, meta: { tag: 'y' } },
-      { id: '3', name: 'C', value: undefined, meta: undefined },
-    ] as unknown as Parameters<NonNullable<typeof csvItem.modifier>>[0]
-    await expect(csvItem.modifier(rows)).resolves.not.toThrow()
-  })
-
-  it('CSV modifier short-circuits when data is empty', async () => {
-    const cfg = tableDownloadConfig({ refUI })
-    const csvItem = cfg[1]!
-    await expect(csvItem.modifier([])).resolves.not.toThrow()
-    await expect(
-      csvItem.modifier(
-        undefined as unknown as Parameters<
-          NonNullable<typeof csvItem.modifier>
-        >[0],
-      ),
-    ).resolves.not.toThrow()
-  })
-
-  it('CSV modifier handles first-row being undefined (edge case)', async () => {
-    const cfg = tableDownloadConfig({ refUI })
-    const csvItem = cfg[1]!
-    // Pass an array containing a falsy first item — should not throw.
-    await expect(
-      csvItem.modifier([undefined] as unknown as Parameters<
-        NonNullable<typeof csvItem.modifier>
-      >[0]),
-    ).resolves.not.toThrow()
-  })
-})

package/src/widgets/table/config.ts

@@ -1,75 +0,0 @@
-import { downloadToCSV, downloadToPNG } from '../actions'
-import type { ConfigProps } from '../loader/types'
-import type {
-  TableDownloadConfig,
-  TableWidgetConfig,
-  TableColumn,
-  Mode,
-  SortDirection,
-} from './types'
-
-const DEFAULT_MODE: Mode = 'local'
-export const DEFAULT_PAGE = 0
-export const DEFAULT_ROWS_PER_PAGE = 10
-export const DEFAULT_ROWS_PER_PAGE_OPTIONS = [5, 10, 25, 50]
-
-export const DEFAULT_COLUMN_ID = null
-export const DEFAULT_DIRECTION: SortDirection = 'asc'
-
-/**
- * Creates download configuration for table widgets, supporting PNG (screenshot) and CSV (data) exports. CSV output uses column keys as headers and filters out `id` fields.
- *
- * @param props - Configuration with `refUI` reference for PNG export.
- * @returns Array of download items for use with the Download action.
- */
-export function tableDownloadConfig({
-  refUI,
-}: ConfigProps): TableDownloadConfig {
-  return [
-    {
-      ...downloadToPNG,
-      modifier: () => downloadToPNG.modifier(refUI),
-    },
-    {
-      ...downloadToCSV,
-      modifier: async (data) => {
-        if (!data?.length) {
-          return downloadToCSV.modifier([])
-        }
-
-        // Convert table data to CSV format
-        // First row contains headers (column keys)
-        const firstRow = data[0]
-        if (!firstRow) {
-          return downloadToCSV.modifier([])
-        }
-
-        const headers = Object.keys(firstRow).filter((key) => key !== 'id')
-        const rows = data.map((row) =>
-          headers.map((header) => {
-            const value = row[header]
-            if (value === null || value === undefined) return ''
-            if (typeof value === 'object') return JSON.stringify(value)
-            return value
-          }),
-        )
-
-        return downloadToCSV.modifier([headers, ...rows])
-      },
-    },
-  ]
-}
-
-/**
- * Returns the default configuration for table widgets with pagination and sorting, including column definitions and local data mode.
- *
- * @param columns - Array of column definitions for the table.
- * @returns Default table widget config.
- */
-export function tableConfig(columns: TableColumn[] = []): TableWidgetConfig {
-  return {
-    columns,
-    selectable: false,
-    mode: DEFAULT_MODE,
-  }
-}

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

@@ -1,294 +0,0 @@
-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

@@ -1,148 +0,0 @@
-import { useCallback, useMemo } from 'react'
-import type { TableRow, TableWidgetState } from '../types'
-import { paginateData } from '../helpers'
-import { widgetStoreActions } from '../../stores/widget-store'
-import { useWidgetSelector } from '../../stores/use-widget-selector'
-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 with support for both local (client-side) and remote (server-side) modes.
- * State is persisted in the widget store for the given widget ID.
- *
- * @param widgetId - The widget ID to persist pagination state under.
- * @param data - The full data array (used for local pagination and total count fallback).
- * @returns Pagination state and navigation helpers.
- *
- * @example
- * ```tsx
- * const { page, setPage, paginatedData, totalPages } = usePagination(widgetId, data)
- * ```
- */
-export function usePagination<T extends TableRow>(
-  widgetId: string,
-  data: T[],
-): UsePaginationResult<T> {
-  // Get store state
-  const {
-    paginationEnabled,
-    page,
-    rowsPerPage,
-    rowsPerPageOptions,
-    total,
-    mode,
-  } = useWidgetSelector(widgetId, (w) => {
-    const widget = w 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,
-      mode: widget?.mode,
-    }
-  })
-
-  // Calculate max page
-  const maxPage = Math.max(0, Math.ceil(total / (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 = widgetStoreActions.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))
-
-      widgetStoreActions.setWidget<TableWidgetState>(widgetId, {
-        pagination: {
-          ...widget?.pagination,
-          page: boundedPage,
-        },
-      })
-    },
-    [data.length, widgetId],
-  )
-
-  // Set rows per page and reset to first page
-  const setRowsPerPage = useCallback(
-    (newRowsPerPage: number) => {
-      const widget = widgetStoreActions.getWidget<TableWidgetState>(widgetId)
-      widgetStoreActions.setWidget<TableWidgetState>(widgetId, {
-        pagination: {
-          ...widget?.pagination,
-          rowsPerPage: newRowsPerPage,
-          page: 0, // Reset to first page when changing rows per page
-        },
-      })
-    },
-    [widgetId],
-  )
-
-  // Navigation helpers
-  const goToFirstPage = useCallback(() => setPage(0), [setPage])
-  const goToLastPage = useCallback(() => setPage(maxPage), [setPage, maxPage])
-  const goToNextPage = useCallback(() => setPage(page + 1), [setPage, page])
-  const goToPreviousPage = useCallback(() => setPage(page - 1), [setPage, page])
-
-  // Paginated data for local mode
-  const paginatedData = useMemo(() => {
-    if (mode === 'remote' || !paginationEnabled) {
-      // For remote mode, data is already paginated from server
-      return data
-    }
-    return paginateData(data, page, rowsPerPage)
-  }, [data, mode, page, paginationEnabled, rowsPerPage])
-
-  return {
-    paginationEnabled,
-    page,
-    rowsPerPage,
-    rowsPerPageOptions,
-    total,
-    paginatedData,
-    setPage,
-    setRowsPerPage,
-    goToFirstPage,
-    goToLastPage,
-    goToNextPage,
-    goToPreviousPage,
-  }
-}