@carto/ps-react-ui 5.0.0-widgets.8 → 5.0.0

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

@@ -0,0 +1,296 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useSort } from './use-sort'
+import { useWidgetStore } from '../../stores/widget-store'
+import type { TableRow } from '../types'
+
+describe('useSort', () => {
+  const testData: TableRow[] = [
+    { id: 1, name: 'Charlie', age: 30 },
+    { id: 2, name: 'Alice', age: 25 },
+    { id: 3, name: 'Bob', age: 35 },
+  ]
+
+  // Clear widget store before each test
+  beforeEach(() => {
+    useWidgetStore.getState().clearWidgets()
+  })
+
+  describe('initialization', () => {
+    it('should initialize with default values', () => {
+      const { result } = renderHook(() => useSort('test-widget', testData))
+
+      expect(result.current.columnId).toBeNull()
+      expect(result.current.direction).toBe('asc')
+      expect(result.current.sortedData).toEqual(testData)
+    })
+
+    it('should initialize with custom values', () => {
+      const { result } = renderHook(() => useSort('test-widget', testData))
+
+      expect(result.current.columnId).toBeNull()
+      expect(result.current.direction).toBe('asc')
+    })
+
+    it('should sort data when column is set', () => {
+      const { result } = renderHook(() => useSort('test-widget', testData))
+
+      act(() => {
+        result.current.setSort('name', 'asc')
+      })
+
+      expect(result.current.sortedData.map((r) => r.name)).toEqual([
+        'Alice',
+        'Bob',
+        'Charlie',
+      ])
+    })
+  })
+
+  describe('local mode', () => {
+    it('should toggle sort direction on same column', () => {
+      const { result } = renderHook(() => useSort('test-widget', testData))
+
+      // First toggle - set to asc
+      act(() => {
+        result.current.toggleSort('name')
+      })
+
+      expect(result.current.columnId).toBe('name')
+      expect(result.current.direction).toBe('asc')
+
+      // Second toggle - change to desc
+      act(() => {
+        result.current.toggleSort('name')
+      })
+
+      expect(result.current.columnId).toBe('name')
+      expect(result.current.direction).toBe('desc')
+
+      // Third toggle - back to asc
+      act(() => {
+        result.current.toggleSort('name')
+      })
+
+      expect(result.current.direction).toBe('asc')
+    })
+
+    it('should reset to asc when changing column', () => {
+      const { result } = renderHook(() => useSort('test-widget', testData))
+
+      // First set name column to desc
+      act(() => {
+        result.current.setSort('name', 'desc')
+      })
+
+      // Then toggle to age column
+      act(() => {
+        result.current.toggleSort('age')
+      })
+
+      expect(result.current.columnId).toBe('age')
+      expect(result.current.direction).toBe('asc')
+    })
+
+    it('should sort data ascending', () => {
+      const { result } = renderHook(() => useSort('test-widget', testData))
+
+      act(() => {
+        result.current.toggleSort('name')
+      })
+
+      expect(result.current.sortedData.map((r) => r.name)).toEqual([
+        'Alice',
+        'Bob',
+        'Charlie',
+      ])
+    })
+
+    it('should sort data descending', () => {
+      const { result } = renderHook(() => useSort('test-widget', testData))
+
+      // First toggle sets to asc
+      act(() => {
+        result.current.toggleSort('name')
+      })
+
+      // Second toggle sets to desc
+      act(() => {
+        result.current.toggleSort('name')
+      })
+
+      expect(result.current.sortedData.map((r) => r.name)).toEqual([
+        'Charlie',
+        'Bob',
+        'Alice',
+      ])
+    })
+
+    it('should sort numbers correctly', () => {
+      const { result } = renderHook(() => useSort('test-widget', testData))
+
+      act(() => {
+        result.current.toggleSort('age')
+      })
+
+      expect(result.current.sortedData.map((r) => r.age)).toEqual([25, 30, 35])
+    })
+
+    it('should set sort state directly', () => {
+      const { result } = renderHook(() => useSort('test-widget', testData))
+
+      act(() => {
+        result.current.setSort('age', 'desc')
+      })
+
+      expect(result.current.columnId).toBe('age')
+      expect(result.current.direction).toBe('desc')
+      expect(result.current.sortedData.map((r) => r.age)).toEqual([35, 30, 25])
+    })
+
+    it('should clear sort', () => {
+      const { result } = renderHook(() => useSort('test-widget', testData))
+
+      // First set a sort
+      act(() => {
+        result.current.setSort('name', 'desc')
+      })
+
+      // Then clear it
+      act(() => {
+        result.current.clearSort()
+      })
+
+      expect(result.current.columnId).toBeNull()
+      expect(result.current.direction).toBe('asc')
+      expect(result.current.sortedData).toEqual(testData)
+    })
+
+    it('should persist state in widget store', () => {
+      const { result, unmount } = renderHook(() =>
+        useSort('test-widget', testData),
+      )
+
+      act(() => {
+        result.current.toggleSort('name')
+        result.current.toggleSort('name') // toggle to desc
+      })
+
+      expect(result.current.columnId).toBe('name')
+      expect(result.current.direction).toBe('desc')
+
+      // Unmount and remount - state should persist
+      unmount()
+
+      const { result: newResult } = renderHook(() =>
+        useSort('test-widget', testData),
+      )
+
+      expect(newResult.current.columnId).toBe('name')
+      expect(newResult.current.direction).toBe('desc')
+    })
+  })
+
+  describe('remote mode', () => {
+    it('should return data as-is in remote mode', () => {
+      useWidgetStore.getState().setWidget('test-widget', {
+        mode: 'remote',
+        sort: { columnId: null, direction: 'asc' },
+      })
+      const { result } = renderHook(() => useSort('test-widget', testData))
+
+      // In remote mode, sortedData should be the original data
+      // since server handles sorting
+      expect(result.current.sortedData).toEqual(testData)
+    })
+
+    it('should update store state when toggling sort in remote mode', () => {
+      useWidgetStore.getState().setWidget('test-widget', {
+        mode: 'remote',
+        sort: { columnId: null, direction: 'asc' },
+      })
+      const { result } = renderHook(() => useSort('test-widget', testData))
+
+      act(() => {
+        result.current.toggleSort('name')
+      })
+
+      expect(result.current.columnId).toBe('name')
+      expect(result.current.direction).toBe('asc')
+    })
+
+    it('should update store state when setting sort in remote mode', () => {
+      useWidgetStore.getState().setWidget('test-widget', {
+        mode: 'remote',
+        sort: { columnId: null, direction: 'asc' },
+      })
+      const { result } = renderHook(() => useSort('test-widget', testData))
+
+      act(() => {
+        result.current.setSort('age', 'desc')
+      })
+
+      expect(result.current.columnId).toBe('age')
+      expect(result.current.direction).toBe('desc')
+      // Data should still be unmodified in remote mode
+      expect(result.current.sortedData).toEqual(testData)
+    })
+  })
+
+  describe('edge cases', () => {
+    it('should handle empty data', () => {
+      const { result } = renderHook(() => useSort('test-widget', []))
+
+      expect(result.current.sortedData).toEqual([])
+
+      act(() => {
+        result.current.toggleSort('name')
+      })
+
+      expect(result.current.sortedData).toEqual([])
+    })
+
+    it('should handle single item data', () => {
+      const singleItem = [{ id: 1, name: 'Alice' }]
+      const { result } = renderHook(() => useSort('test-widget', singleItem))
+
+      act(() => {
+        result.current.toggleSort('name')
+      })
+
+      expect(result.current.sortedData).toEqual(singleItem)
+    })
+
+    it('should preserve sort when data changes', () => {
+      const { result, rerender } = renderHook(
+        ({ data }) => useSort('test-widget', data),
+        { initialProps: { data: testData } },
+      )
+
+      act(() => {
+        result.current.toggleSort('name')
+      })
+
+      expect(result.current.sortedData.map((r) => r.name)).toEqual([
+        'Alice',
+        'Bob',
+        'Charlie',
+      ])
+
+      // Add new data
+      const newData: TableRow[] = [
+        ...testData,
+        { id: 4, name: 'David', age: 28 },
+      ]
+
+      rerender({ data: newData })
+
+      expect(result.current.sortedData.map((r) => r.name)).toEqual([
+        'Alice',
+        'Bob',
+        'Charlie',
+        'David',
+      ])
+    })
+  })
+})

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

@@ -0,0 +1,131 @@
+import { useCallback, useMemo } from 'react'
+import type {
+  TableRow,
+  SortDirection,
+  SortState,
+  TableWidgetState,
+} from '../types'
+import { sortData } from '../helpers'
+import { widgetStoreActions } from '../../stores/widget-store'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
+import { DEFAULT_COLUMN_ID, DEFAULT_DIRECTION } from '../config'
+
+export interface UseSortResult<T> extends SortState {
+  /** Whether sorting is enabled */
+  sortEnabled: boolean
+  /** Current sort state */
+  columnId: string | null
+  direction: SortDirection
+  /** Sorted data (for local mode) */
+  sortedData: T[]
+  /** Toggle sort on a column */
+  toggleSort: (columnId: string) => void
+  /** Set sort state directly */
+  setSort: (columnId: string | null, direction: SortDirection) => void
+  /** Clear sort */
+  clearSort: () => void
+}
+
+/**
+ * Hook for managing table sorting 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 sort state under.
+ * @param data - The data array to sort (for local mode).
+ * @returns Sort state, sorted data, and sort control functions.
+ *
+ * @example
+ * ```tsx
+ * const { sortedData, sortField, sortDirection, handleSort } = useSort(widgetId, data)
+ * ```
+ */
+export function useSort<T extends TableRow>(
+  widgetId: string,
+  data: T[],
+): UseSortResult<T> {
+  // Get store state
+  const { sortEnabled, columnId, direction, mode } = useWidgetSelector(
+    widgetId,
+    (w) => {
+      const widget = w as TableWidgetState | undefined
+      return {
+        sortEnabled: !!widget?.sort,
+        columnId: widget?.sort?.columnId ?? DEFAULT_COLUMN_ID,
+        direction: widget?.sort?.direction ?? DEFAULT_DIRECTION,
+        mode: widget?.mode,
+      }
+    },
+  )
+
+  // Toggle sort on a column
+  const toggleSort = useCallback(
+    (toggleColumnId: string) => {
+      // Read current state directly from store to avoid stale closures
+      const widget = widgetStoreActions.getWidget<TableWidgetState>(widgetId)
+      const currentColumnId = widget?.sort?.columnId ?? DEFAULT_COLUMN_ID
+      const currentDirection = widget?.sort?.direction ?? DEFAULT_DIRECTION
+
+      let newDirection: SortDirection = 'asc'
+
+      if (currentColumnId === toggleColumnId) {
+        // Same column - toggle direction
+        newDirection = currentDirection === 'asc' ? 'desc' : 'asc'
+      }
+
+      widgetStoreActions.setWidget<TableWidgetState>(widgetId, {
+        sort: {
+          columnId: toggleColumnId,
+          direction: newDirection,
+        },
+      })
+    },
+    [widgetId],
+  )
+
+  // Set sort state directly
+  const setSort = useCallback(
+    (newColumnId: string | null, newDirection: SortDirection) => {
+      widgetStoreActions.setWidget<TableWidgetState>(widgetId, {
+        sort: {
+          columnId: newColumnId,
+          direction: newDirection,
+        },
+      })
+    },
+    [widgetId],
+  )
+
+  // Clear sort
+  const clearSort = useCallback(() => {
+    const widget = widgetStoreActions.getWidget<TableWidgetState>(widgetId)
+    if (!widget?.sort) return
+
+    widgetStoreActions.setWidget<TableWidgetState>(widgetId, {
+      sort: {
+        ...widget.sort,
+        columnId: null,
+        direction: 'asc',
+      },
+    })
+  }, [widgetId])
+
+  // Sorted data for local mode
+  const sortedData = useMemo(() => {
+    if (mode === 'remote' || !columnId || !sortEnabled) {
+      // For remote mode, data is already sorted from server
+      // If no sort column, return original data
+      return data
+    }
+    return sortData(data, columnId, direction)
+  }, [data, mode, columnId, direction, sortEnabled])
+
+  return {
+    sortEnabled,
+    columnId,
+    direction,
+    sortedData,
+    toggleSort,
+    setSort,
+    clearSort,
+  }
+}

package/src/widgets/table/index.ts

@@ -0,0 +1,55 @@
+// Components
+export { CellHeader } from './components/cell-header'
+export { Row } from './components/row'
+export { Pagination } from './components/pagination'
+export { PaginationActions } from './components/pagination-actions'
+
+// Main components
+export { Table } from './table-ui'
+
+// Hooks
+export { usePagination } from './hooks/use-pagination'
+export { useSort } from './hooks/use-sort'
+export { useSelection } from './hooks/use-selection'
+
+// Config
+export { tableConfig, tableDownloadConfig } from './config'
+
+// Skeleton
+export { TableSkeleton } from './skeleton'
+
+// Serializer
+export { sanitizeTableRow, sanitizeTableData } from './serializer'
+
+// Helpers
+export { getCellValue, compareValues, sortData, paginateData } from './helpers'
+
+// Styles
+export { styles as tableStyles } from './style'
+
+// Types
+export type {
+  TableUIProps,
+  TableColumn,
+  TableRow,
+  TableWidgetData,
+  TablePaginationState,
+  SortDirection,
+  SortState,
+  Mode,
+  TableWidgetConfig,
+  TableWidgetState,
+  TableDownloadConfig,
+  TableProps,
+  CellHeaderProps,
+  RowProps,
+  PaginationProps,
+  PaginationActionsProps,
+} from './types'
+
+export type { UsePaginationResult } from './hooks/use-pagination'
+export type { UseSortResult } from './hooks/use-sort'
+export type {
+  UseSelectionOptions,
+  UseSelectionResult,
+} from './hooks/use-selection'

package/src/widgets/table/serializer.ts

@@ -0,0 +1,54 @@
+import type { TableRow, TableWidgetData } from './types'
+
+/**
+ * Sanitizes a table row by ensuring all values are serializable.
+ * Converts ReactNode and function values to undefined.
+ *
+ * @param row - The table row to sanitize
+ * @returns A sanitized table row
+ */
+export function sanitizeTableRow(row: TableRow): TableRow {
+  const sanitized: TableRow = { id: row.id }
+
+  for (const [key, value] of Object.entries(row)) {
+    if (key === 'id') continue
+
+    // Keep primitive values
+    if (
+      typeof value === 'string' ||
+      typeof value === 'number' ||
+      typeof value === 'boolean' ||
+      value === null
+    ) {
+      sanitized[key] = value
+    }
+    // Serialize arrays and plain objects
+    else if (Array.isArray(value) || typeof value === 'object') {
+      try {
+        // Attempt to serialize - if it fails, the value contains non-serializable content
+        JSON.stringify(value)
+        sanitized[key] = value
+      } catch {
+        sanitized[key] = undefined
+      }
+    }
+    // Skip functions and other non-serializable values
+    else {
+      sanitized[key] = undefined
+    }
+  }
+
+  return sanitized
+}
+
+/**
+ * Sanitizes table widget data by ensuring all rows are serializable.
+ *
+ * @param data - The table data to sanitize
+ * @returns Sanitized table data
+ */
+export function sanitizeTableData(
+  data: TableWidgetData | undefined,
+): TableWidgetData | undefined {
+  return data?.map(sanitizeTableRow)
+}

package/src/widgets/table/skeleton.tsx

@@ -0,0 +1,48 @@
+import {
+  Box,
+  Skeleton,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableRow,
+} from '@mui/material'
+
+export interface TableSkeletonProps {
+  /** Number of columns to display */
+  columns?: number
+  /** Number of rows to display */
+  rows?: number
+}
+
+/**
+ * Table skeleton loader component
+ */
+export function TableSkeleton({ columns = 4, rows = 5 }: TableSkeletonProps) {
+  return (
+    <Box aria-label='Table skeleton'>
+      <Table>
+        <TableHead>
+          <TableRow>
+            {Array.from({ length: columns }).map((_, index) => (
+              <TableCell key={index}>
+                <Skeleton width='80%' height={24} />
+              </TableCell>
+            ))}
+          </TableRow>
+        </TableHead>
+        <TableBody>
+          {Array.from({ length: rows }).map((_, rowIndex) => (
+            <TableRow key={rowIndex}>
+              {Array.from({ length: columns }).map((_, colIndex) => (
+                <TableCell key={colIndex}>
+                  <Skeleton width='70%' height={20} />
+                </TableCell>
+              ))}
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </Box>
+  )
+}

package/src/widgets/table/style.ts

@@ -0,0 +1,34 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  container: {
+    width: '100%',
+    overflow: 'auto',
+  },
+  table: {
+    minWidth: 650,
+  },
+  headerCell: {
+    fontWeight: 600,
+    backgroundColor: (theme: Theme) => theme.palette.background.paper,
+  },
+  row: {
+    '&:last-child td, &:last-child th': {
+      border: 0,
+    },
+  },
+  rowHover: {
+    '&:hover': {
+      backgroundColor: (theme: Theme) => theme.palette.action.hover,
+    },
+  },
+  rowSelected: {
+    backgroundColor: (theme: Theme) => theme.palette.action.selected,
+    '&:hover': {
+      backgroundColor: (theme: Theme) => theme.palette.action.selected,
+    },
+  },
+  pagination: {
+    borderTop: (theme: Theme) => `1px solid ${theme.palette.divider}`,
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets/table/table-ui.tsx

@@ -0,0 +1,64 @@
+import {
+  Table as MuiTable,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableContainer as MuiTableContainer,
+  Paper,
+  type TableProps as MuiTableProps,
+} from '@mui/material'
+import type { Ref } from 'react'
+import { CellHeader } from './components/cell-header'
+import { Row } from './components/row'
+import { Pagination } from './components/pagination'
+import { PaginationActions } from './components/pagination-actions'
+import { useWidgetRef } from '../../hooks'
+import type { TableUIProps } from './types'
+
+/**
+ * Props for the base Table component
+ */
+interface TableComponentProps extends MuiTableProps {
+  /** Table element ref */
+  ref?: Ref<HTMLTableElement>
+}
+
+/**
+ * Base Table component with compound component pattern
+ * Provides Table.Head, Table.Body, Table.Row, Table.Cell, Table.CellHeader, Table.Pagination
+ */
+function Table({
+  children,
+  ref,
+  stickyHeader = true,
+  ...props
+}: TableComponentProps) {
+  return (
+    <MuiTable stickyHeader={stickyHeader} ref={ref} {...props}>
+      {children}
+    </MuiTable>
+  )
+}
+
+// Attach sub-components as static properties
+Table.Head = TableHead
+Table.CellHeader = CellHeader
+Table.Body = TableBody
+Table.Row = Row
+Table.Cell = TableCell
+Table.Container = TableContainer
+Table.Paper = Paper
+Table.Pagination = Pagination
+Table.PaginationActions = PaginationActions
+
+export { Table }
+
+/**
+ * TableContainer widget component
+ * Integrates with widget store and provides ref registration using custom hook
+ */
+function TableContainer(props: TableUIProps) {
+  const { ref } = useWidgetRef<HTMLDivElement>(props.id)
+
+  return <MuiTableContainer ref={ref}>{props.children}</MuiTableContainer>
+}