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

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

@@ -0,0 +1,82 @@
+import { TableCell as MuiTableCell, Link, Typography } from '@mui/material'
+import ReactMarkdown, { type Components } from 'react-markdown'
+import type { TableColumn, TableRow } from '../types'
+import { getCellValue } from '../helpers'
+import type { ReactNode } from 'react'
+
+/**
+ * Props for Cell component
+ */
+export interface CellProps {
+  /** Column definition */
+  column: TableColumn
+  /** Full table row for context */
+  row: TableRow
+  /** Cell value */
+  value: unknown
+}
+
+const DEFAULT_P = ({ children }: { children?: ReactNode }) => (
+  <Typography component='span' variant='body2' color='inherit'>
+    {children}
+  </Typography>
+)
+
+/**
+ * Markdown components for cell content
+ * Uses compact styling suitable for table cells (reusing Note widget pattern)
+ */
+const CELL_MARKDOWN_COMPONENTS: Components = {
+  h1: DEFAULT_P,
+  h2: DEFAULT_P,
+  h3: DEFAULT_P,
+  p: DEFAULT_P,
+  a: ({ children, href }) => {
+    const isExternal = href?.startsWith('http')
+    return (
+      <Link
+        href={href}
+        target={isExternal ? '_blank' : undefined}
+        rel={isExternal ? 'noopener noreferrer' : undefined}
+        color='text.primary'
+        underline='always'
+      >
+        {children}
+      </Link>
+    )
+  },
+  img: () => null,
+  ul: DEFAULT_P,
+  ol: DEFAULT_P,
+  li: DEFAULT_P,
+}
+
+/**
+ * Table cell component with automatic markdown support for string values
+ * Markdown is rendered when the raw value is a string and no formatter is defined.
+ * If a formatter is used, its output is rendered directly without markdown parsing.
+ */
+export function Cell({ column, row, value }: CellProps) {
+  // If formatter is defined, use it directly without markdown
+  if (column.formatter) {
+    return (
+      <MuiTableCell align={column.align}>
+        {column.formatter(value, row)}
+      </MuiTableCell>
+    )
+  }
+
+  // For string values without formatter, render as markdown
+  if (typeof value === 'string') {
+    return (
+      <MuiTableCell align={column.align}>
+        <ReactMarkdown components={CELL_MARKDOWN_COMPONENTS}>
+          {value}
+        </ReactMarkdown>
+      </MuiTableCell>
+    )
+  }
+
+  // For non-string values, render directly
+  return <MuiTableCell align={column.align}>{getCellValue(value)}</MuiTableCell>
+}

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

@@ -0,0 +1,67 @@
+import { Box, IconButton } from '@mui/material'
+import { FirstPage as FirstPageIcon } from '@mui/icons-material'
+import { KeyboardArrowLeft } from '@mui/icons-material'
+import { KeyboardArrowRight } from '@mui/icons-material'
+import { LastPage as LastPageIcon } from '@mui/icons-material'
+import type { PaginationActionsProps } from '../types'
+
+/**
+ * Custom pagination actions with first/prev/next/last buttons
+ */
+export function PaginationActions({
+  count,
+  page,
+  rowsPerPage,
+  onPageChange,
+}: PaginationActionsProps) {
+  const lastPage = Math.max(0, Math.ceil(count / rowsPerPage) - 1)
+
+  const handleFirstPage = (event: React.MouseEvent<HTMLButtonElement>) => {
+    onPageChange(event, 0)
+  }
+
+  const handlePreviousPage = (event: React.MouseEvent<HTMLButtonElement>) => {
+    onPageChange(event, page - 1)
+  }
+
+  const handleNextPage = (event: React.MouseEvent<HTMLButtonElement>) => {
+    onPageChange(event, page + 1)
+  }
+
+  const handleLastPage = (event: React.MouseEvent<HTMLButtonElement>) => {
+    onPageChange(event, lastPage)
+  }
+
+  return (
+    <Box sx={{ flexShrink: 0, ml: 2.5 }}>
+      <IconButton
+        onClick={handleFirstPage}
+        disabled={page === 0}
+        aria-label='first page'
+      >
+        <FirstPageIcon />
+      </IconButton>
+      <IconButton
+        onClick={handlePreviousPage}
+        disabled={page === 0}
+        aria-label='previous page'
+      >
+        <KeyboardArrowLeft />
+      </IconButton>
+      <IconButton
+        onClick={handleNextPage}
+        disabled={page >= lastPage}
+        aria-label='next page'
+      >
+        <KeyboardArrowRight />
+      </IconButton>
+      <IconButton
+        onClick={handleLastPage}
+        disabled={page >= lastPage}
+        aria-label='last page'
+      >
+        <LastPageIcon />
+      </IconButton>
+    </Box>
+  )
+}

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

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

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

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

@@ -0,0 +1,75 @@
+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/helpers.test.ts

@@ -0,0 +1,244 @@
+import { describe, it, expect } from 'vitest'
+import { getCellValue, compareValues, sortData, paginateData } from './helpers'
+
+describe('helpers', () => {
+  describe('getCellValue', () => {
+    it('should return empty string for null', () => {
+      expect(getCellValue(null)).toBe('')
+    })
+
+    it('should return empty string for undefined', () => {
+      expect(getCellValue(undefined)).toBe('')
+    })
+
+    it('should return string as-is', () => {
+      expect(getCellValue('hello')).toBe('hello')
+    })
+
+    it('should return number as-is', () => {
+      expect(getCellValue(42)).toBe(42)
+    })
+
+    it('should return boolean as-is', () => {
+      expect(getCellValue(true)).toBe(true)
+      expect(getCellValue(false)).toBe(false)
+    })
+
+    it('should format array of strings with quotes', () => {
+      expect(getCellValue(['a', 'b', 'c'])).toBe('["a", "b", "c"]')
+    })
+
+    it('should format array of numbers without quotes', () => {
+      expect(getCellValue([1, 2, 3])).toBe('[1, 2, 3]')
+    })
+
+    it('should format mixed array', () => {
+      expect(getCellValue(['hello', 42, true])).toBe('["hello", 42, true]')
+    })
+
+    it('should format empty array', () => {
+      expect(getCellValue([])).toBe('[]')
+    })
+
+    it('should stringify object', () => {
+      expect(getCellValue({ key: 'value' })).toBe('{"key":"value"}')
+    })
+
+    it('should stringify nested object', () => {
+      expect(getCellValue({ a: { b: 'c' } })).toBe('{"a":{"b":"c"}}')
+    })
+  })
+
+  describe('compareValues', () => {
+    describe('null/undefined handling', () => {
+      it('should sort null to end (return 1)', () => {
+        expect(compareValues(null, 'a', 'asc')).toBe(1)
+      })
+
+      it('should sort undefined to end (return 1)', () => {
+        expect(compareValues(undefined, 'a', 'asc')).toBe(1)
+      })
+
+      it('should sort non-null before null (return -1)', () => {
+        expect(compareValues('a', null, 'asc')).toBe(-1)
+      })
+
+      it('should sort non-undefined before undefined (return -1)', () => {
+        expect(compareValues('a', undefined, 'asc')).toBe(-1)
+      })
+    })
+
+    describe('string comparison', () => {
+      it('should compare strings ascending', () => {
+        expect(compareValues('apple', 'banana', 'asc')).toBeLessThan(0)
+        expect(compareValues('banana', 'apple', 'asc')).toBeGreaterThan(0)
+        expect(compareValues('apple', 'apple', 'asc')).toBe(0)
+      })
+
+      it('should compare strings descending', () => {
+        expect(compareValues('apple', 'banana', 'desc')).toBeGreaterThan(0)
+        expect(compareValues('banana', 'apple', 'desc')).toBeLessThan(0)
+        // When values are equal, result is 0 (could be -0 or +0, both equal 0)
+        expect(compareValues('apple', 'apple', 'desc') === 0).toBe(true)
+      })
+    })
+
+    describe('number comparison', () => {
+      it('should compare numbers ascending', () => {
+        expect(compareValues(1, 2, 'asc')).toBeLessThan(0)
+        expect(compareValues(2, 1, 'asc')).toBeGreaterThan(0)
+        expect(compareValues(1, 1, 'asc')).toBe(0)
+      })
+
+      it('should compare numbers descending', () => {
+        expect(compareValues(1, 2, 'desc')).toBeGreaterThan(0)
+        expect(compareValues(2, 1, 'desc')).toBeLessThan(0)
+        // When values are equal, result is 0 (could be -0 or +0, both equal 0)
+        expect(compareValues(1, 1, 'desc') === 0).toBe(true)
+      })
+
+      it('should handle negative numbers', () => {
+        expect(compareValues(-5, 5, 'asc')).toBeLessThan(0)
+        expect(compareValues(5, -5, 'asc')).toBeGreaterThan(0)
+      })
+
+      it('should handle decimal numbers', () => {
+        expect(compareValues(1.5, 2.5, 'asc')).toBeLessThan(0)
+        expect(compareValues(2.5, 1.5, 'asc')).toBeGreaterThan(0)
+      })
+    })
+
+    describe('boolean comparison', () => {
+      it('should compare booleans ascending (false before true)', () => {
+        expect(compareValues(false, true, 'asc')).toBeLessThan(0)
+        expect(compareValues(true, false, 'asc')).toBeGreaterThan(0)
+        expect(compareValues(true, true, 'asc')).toBe(0)
+        expect(compareValues(false, false, 'asc')).toBe(0)
+      })
+
+      it('should compare booleans descending (true before false)', () => {
+        expect(compareValues(false, true, 'desc')).toBeGreaterThan(0)
+        expect(compareValues(true, false, 'desc')).toBeLessThan(0)
+      })
+    })
+
+    describe('object comparison', () => {
+      it('should compare objects as JSON strings', () => {
+        const objA = { a: 1 }
+        const objB = { b: 2 }
+        // Compares '{"a":1}' vs '{"b":2}'
+        expect(compareValues(objA, objB, 'asc')).toBeLessThan(0)
+      })
+
+      it('should handle array comparison', () => {
+        const arrA = [1, 2]
+        const arrB = [3, 4]
+        // Compares '[1,2]' vs '[3,4]'
+        expect(compareValues(arrA, arrB, 'asc')).toBeLessThan(0)
+      })
+    })
+  })
+
+  describe('sortData', () => {
+    const testData = [
+      { id: 1, name: 'Charlie', age: 30 },
+      { id: 2, name: 'Alice', age: 25 },
+      { id: 3, name: 'Bob', age: 35 },
+    ]
+
+    it('should sort by string column ascending', () => {
+      const sorted = sortData(testData, 'name', 'asc')
+      expect(sorted.map((r) => r.name)).toEqual(['Alice', 'Bob', 'Charlie'])
+    })
+
+    it('should sort by string column descending', () => {
+      const sorted = sortData(testData, 'name', 'desc')
+      expect(sorted.map((r) => r.name)).toEqual(['Charlie', 'Bob', 'Alice'])
+    })
+
+    it('should sort by number column ascending', () => {
+      const sorted = sortData(testData, 'age', 'asc')
+      expect(sorted.map((r) => r.age)).toEqual([25, 30, 35])
+    })
+
+    it('should sort by number column descending', () => {
+      const sorted = sortData(testData, 'age', 'desc')
+      expect(sorted.map((r) => r.age)).toEqual([35, 30, 25])
+    })
+
+    it('should not mutate original array', () => {
+      const original = [...testData]
+      sortData(testData, 'name', 'asc')
+      expect(testData).toEqual(original)
+    })
+
+    it('should handle empty array', () => {
+      expect(sortData([], 'name', 'asc')).toEqual([])
+    })
+
+    it('should handle single item array', () => {
+      const single = [{ id: 1, name: 'Alice' }]
+      expect(sortData(single, 'name', 'asc')).toEqual(single)
+    })
+
+    it('should handle null values in data', () => {
+      const dataWithNull = [
+        { id: 1, name: 'Bob' },
+        { id: 2, name: null },
+        { id: 3, name: 'Alice' },
+      ]
+      const sorted = sortData(dataWithNull, 'name', 'asc')
+      // Null should be sorted to end
+      expect(sorted.map((r) => r.name)).toEqual(['Alice', 'Bob', null])
+    })
+  })
+
+  describe('paginateData', () => {
+    const testData = [
+      { id: 1 },
+      { id: 2 },
+      { id: 3 },
+      { id: 4 },
+      { id: 5 },
+      { id: 6 },
+      { id: 7 },
+      { id: 8 },
+      { id: 9 },
+      { id: 10 },
+    ]
+
+    it('should return first page', () => {
+      const result = paginateData(testData, 0, 3)
+      expect(result.map((r) => r.id)).toEqual([1, 2, 3])
+    })
+
+    it('should return second page', () => {
+      const result = paginateData(testData, 1, 3)
+      expect(result.map((r) => r.id)).toEqual([4, 5, 6])
+    })
+
+    it('should return partial last page', () => {
+      const result = paginateData(testData, 3, 3)
+      expect(result.map((r) => r.id)).toEqual([10])
+    })
+
+    it('should return empty array for page beyond data', () => {
+      const result = paginateData(testData, 10, 3)
+      expect(result).toEqual([])
+    })
+
+    it('should handle page size larger than data', () => {
+      const result = paginateData(testData, 0, 100)
+      expect(result.map((r) => r.id)).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    })
+
+    it('should handle empty array', () => {
+      expect(paginateData([], 0, 10)).toEqual([])
+    })
+
+    it('should handle single item', () => {
+      const result = paginateData([{ id: 1 }], 0, 10)
+      expect(result.map((r) => r.id)).toEqual([1])
+    })
+  })
+})