@carto/ps-react-ui 4.7.0 → 4.8.0

package/src/widgets-v2/table/download.ts

@@ -0,0 +1,47 @@
+import { buildPngDownloadItem, type DownloadItem } from '../actions/download'
+import { tableDataToCsv } from './helpers'
+import type { TableColumn, TableWidgetData } from './types'
+
+/**
+ * Download menu items for the Table widget. Always includes a CSV item
+ * that pulls the latest data from the widget store via `getData()` (so
+ * locked / sorted / filtered state is honored); headers come from
+ * `column.label`, cells from `row[column.id]`. When `getCaptureEl` is
+ * supplied, prepends a PNG item that rasterises the captured element via
+ * `html2canvas`.
+ */
+export function createTableDownloadConfig(opts: {
+  filename: string
+  getData: () => TableWidgetData
+  columns: readonly TableColumn[]
+  getCaptureEl?: () => HTMLElement | null
+  pngPixelRatio?: number
+  pngBackgroundColor?: string | null
+}): DownloadItem[] {
+  const items: DownloadItem[] = []
+  if (opts.getCaptureEl) {
+    items.push(
+      buildPngDownloadItem({
+        filename: opts.filename,
+        getCaptureEl: opts.getCaptureEl,
+        pixelRatio: opts.pngPixelRatio,
+        backgroundColor: opts.pngBackgroundColor,
+      }),
+    )
+  }
+  items.push({
+    id: 'csv',
+    label: 'Download as CSV',
+    resolve: () => {
+      const csv = tableDataToCsv(opts.getData(), opts.columns)
+      const blob = new Blob([csv], { type: 'text/csv;charset=utf-8;' })
+      const url = URL.createObjectURL(blob)
+      return Promise.resolve({
+        url,
+        filename: `${opts.filename}.csv`,
+        revoke: () => URL.revokeObjectURL(url),
+      })
+    },
+  })
+  return items
+}

package/src/widgets-v2/table/helpers.test.ts

@@ -0,0 +1,214 @@
+import { describe, it, expect } from 'vitest'
+import {
+  compareValues,
+  deriveVisibleRows,
+  paginateRows,
+  resolveColumns,
+  sortRows,
+  tableDataToCsv,
+} from './helpers'
+import type { TableColumn, TableRow } from './types'
+
+const ROWS: TableRow[] = [
+  { id: 1, name: 'Alpha', score: 12 },
+  { id: 2, name: 'beta', score: 7 },
+  { id: 3, name: 'Gamma', score: 25 },
+  { id: 4, name: null, score: null },
+]
+
+describe('compareValues', () => {
+  it('orders strings via locale compare', () => {
+    expect(compareValues('a', 'b', 'asc')).toBeLessThan(0)
+    expect(compareValues('b', 'a', 'asc')).toBeGreaterThan(0)
+  })
+
+  it('orders numbers numerically', () => {
+    expect(compareValues(1, 10, 'asc')).toBeLessThan(0)
+    expect(compareValues(10, 1, 'asc')).toBeGreaterThan(0)
+  })
+
+  it('flips comparison for desc', () => {
+    expect(compareValues(1, 10, 'desc')).toBeGreaterThan(0)
+  })
+
+  it('sorts null/undefined to the end', () => {
+    expect(compareValues(null, 5, 'asc')).toBeGreaterThan(0)
+    expect(compareValues(5, null, 'asc')).toBeLessThan(0)
+  })
+})
+
+describe('sortRows', () => {
+  it('sorts numeric column ascending and descending', () => {
+    expect(sortRows(ROWS, 'score', 'asc').map((r) => r.id)).toEqual([
+      2, 1, 3, 4,
+    ])
+    expect(sortRows(ROWS, 'score', 'desc').map((r) => r.id)).toEqual([
+      3, 1, 2, 4,
+    ])
+  })
+
+  it('does not mutate the input', () => {
+    const before = [...ROWS]
+    sortRows(ROWS, 'score', 'asc')
+    expect(ROWS).toEqual(before)
+  })
+})
+
+describe('paginateRows', () => {
+  it('returns the requested slice', () => {
+    expect(paginateRows([1, 2, 3, 4, 5], 0, 2)).toEqual([1, 2])
+    expect(paginateRows([1, 2, 3, 4, 5], 1, 2)).toEqual([3, 4])
+    expect(paginateRows([1, 2, 3, 4, 5], 2, 2)).toEqual([5])
+  })
+
+  it('returns empty for out-of-range pages', () => {
+    expect(paginateRows([1, 2, 3], 5, 2)).toEqual([])
+  })
+})
+
+describe('resolveColumns', () => {
+  const cols: TableColumn[] = [
+    { id: 'a', label: 'A' },
+    { id: 'b', label: 'B' },
+    { id: 'c', label: 'C' },
+  ]
+
+  it('returns input unchanged when no order is provided', () => {
+    expect(resolveColumns(cols, undefined)).toBe(cols)
+  })
+
+  it('reorders by id', () => {
+    expect(resolveColumns(cols, ['c', 'a', 'b']).map((c) => c.id)).toEqual([
+      'c',
+      'a',
+      'b',
+    ])
+  })
+
+  it('skips unknown ids and appends columns missing from the order', () => {
+    expect(resolveColumns(cols, ['c', 'unknown']).map((c) => c.id)).toEqual([
+      'c',
+      'a',
+      'b',
+    ])
+  })
+})
+
+describe('deriveVisibleRows', () => {
+  it('paginates without sort when sort columnId is null', () => {
+    const out = deriveVisibleRows(ROWS, {
+      sort: { columnId: null, direction: 'asc' },
+      page: 0,
+      pageSize: 2,
+    })
+    expect(out.visible.map((r) => r.id)).toEqual([1, 2])
+    expect(out.sorted.length).toBe(4)
+  })
+
+  it('sorts then paginates', () => {
+    const out = deriveVisibleRows(ROWS, {
+      sort: { columnId: 'score', direction: 'asc' },
+      page: 0,
+      pageSize: 2,
+    })
+    expect(out.visible.map((r) => r.id)).toEqual([2, 1])
+  })
+})
+
+describe('compareValues — broader types', () => {
+  it('ranks booleans (false < true)', () => {
+    expect(compareValues(false, true, 'asc')).toBeLessThan(0)
+    expect(compareValues(true, false, 'asc')).toBeGreaterThan(0)
+    expect(compareValues(true, true, 'asc')).toBe(0)
+  })
+
+  it('compares objects/arrays via JSON serialization', () => {
+    expect(compareValues({ a: 1 }, { a: 2 }, 'asc')).toBeLessThan(0)
+    expect(compareValues([1, 2], [1, 1], 'desc')).toBeLessThan(0)
+  })
+
+  it('returns 0 when both sides are null/undefined', () => {
+    expect(compareValues(null, undefined, 'asc')).toBe(0)
+    expect(compareValues(undefined, null, 'desc')).toBe(0)
+  })
+
+  it('returns 0 for mismatched primitive types it does not know how to order', () => {
+    // Not a documented contract but the implementation falls through to cmp = 0
+    // when types don't match — guard the fallthrough behavior so future
+    // refactors notice if they change it.
+    expect(compareValues(1, 'a', 'asc')).toBe(0)
+  })
+})
+
+describe('paginateRows — edge cases', () => {
+  it('returns a copy when pageSize is 0 or negative', () => {
+    const rows = [1, 2, 3]
+    const out = paginateRows(rows, 0, 0)
+    expect(out).toEqual(rows)
+    expect(out).not.toBe(rows)
+    expect(paginateRows(rows, 0, -5)).toEqual(rows)
+  })
+})
+
+describe('resolveColumns — edge cases', () => {
+  const cols: TableColumn[] = [
+    { id: 'a', label: 'A' },
+    { id: 'b', label: 'B' },
+  ]
+  it('returns input unchanged when order is empty', () => {
+    expect(resolveColumns(cols, [])).toBe(cols)
+  })
+
+  it('deduplicates repeated ids in the order', () => {
+    expect(resolveColumns(cols, ['a', 'a', 'b']).map((c) => c.id)).toEqual([
+      'a',
+      'b',
+    ])
+  })
+})
+
+describe('tableDataToCsv', () => {
+  const cols: TableColumn[] = [
+    { id: 'name', label: 'Name' },
+    { id: 'score', label: 'Score' },
+  ]
+
+  it('emits header row + cell rows', () => {
+    const csv = tableDataToCsv(ROWS, cols)
+    const lines = csv.split('\n')
+    expect(lines[0]).toBe('Name,Score')
+    expect(lines[1]).toBe('Alpha,12')
+    expect(lines[2]).toBe('beta,7')
+  })
+
+  it('escapes commas, newlines, and quotes', () => {
+    const csv = tableDataToCsv([{ id: 1, name: 'a, b "c"\nd', score: 1 }], cols)
+    expect(csv).toContain('"a, b ""c""\nd",1')
+  })
+
+  it('renders null cells as empty strings', () => {
+    const csv = tableDataToCsv([ROWS[3]!], cols)
+    expect(csv.split('\n')[1]).toBe(',')
+  })
+
+  it('coerces numeric/boolean header labels and skips ReactNode labels', () => {
+    const numericLabel: TableColumn[] = [
+      { id: 'a', label: 7 as unknown as TableColumn['label'] },
+      { id: 'b', label: true as unknown as TableColumn['label'] },
+      // ReactNode (object) labels degrade to empty string by design.
+      { id: 'c', label: { type: 'span' } as unknown as TableColumn['label'] },
+    ]
+    const csv = tableDataToCsv([], numericLabel)
+    expect(csv).toBe('7,true,')
+  })
+
+  it('serialises array and object cell values as JSON', () => {
+    const csv = tableDataToCsv(
+      [{ id: 1, name: ['x', 'y'], score: { z: 1 } }],
+      cols,
+    )
+    // The JSON contains quotes so the cell wraps + escapes.
+    expect(csv).toContain('"[""x"",""y""]"')
+    expect(csv).toContain('"{""z"":1}"')
+  })
+})

package/src/widgets-v2/table/helpers.ts

@@ -0,0 +1,136 @@
+import type {
+  TableColumn,
+  TableRow,
+  TableSortDirection,
+  TableWidgetData,
+} from './types'
+
+/**
+ * Compares two values with a consistent ordering across primitive types.
+ * Strings use locale comparison; numbers subtract; booleans rank false < true;
+ * objects/arrays compare by JSON serialization. Null/undefined sort to the end
+ * regardless of direction.
+ */
+export function compareValues(
+  a: unknown,
+  b: unknown,
+  direction: TableSortDirection,
+): number {
+  if (a == null && b == null) return 0
+  if (a == null) return 1
+  if (b == null) return -1
+  let cmp = 0
+  if (typeof a === 'string' && typeof b === 'string') {
+    cmp = a.localeCompare(b)
+  } else if (typeof a === 'number' && typeof b === 'number') {
+    cmp = a - b
+  } else if (typeof a === 'boolean' && typeof b === 'boolean') {
+    cmp = a === b ? 0 : a ? 1 : -1
+  } else if (typeof a === 'object' || typeof b === 'object') {
+    cmp = JSON.stringify(a).localeCompare(JSON.stringify(b))
+  }
+  return direction === 'asc' ? cmp : -cmp
+}
+
+/** Returns a new array sorted by the named column. Does not mutate the input. */
+export function sortRows<T extends TableRow>(
+  rows: readonly T[],
+  columnId: string,
+  direction: TableSortDirection,
+): T[] {
+  return [...rows].sort((a, b) =>
+    compareValues(a[columnId], b[columnId], direction),
+  )
+}
+
+/** Returns the slice for the requested page. Out-of-range pages return []. */
+export function paginateRows<T>(
+  rows: readonly T[],
+  page: number,
+  pageSize: number,
+): T[] {
+  if (pageSize <= 0) return rows.slice()
+  const start = page * pageSize
+  return rows.slice(start, start + pageSize)
+}
+
+/**
+ * Resolves the effective column list. When the widget store has a
+ * `columnOrder` set (e.g. ChangeColumn was used), the column array is
+ * reordered to match. Unknown ids in the order are skipped; columns not
+ * present in the order keep their original relative position at the end.
+ */
+export function resolveColumns(
+  columns: readonly TableColumn[],
+  columnOrder: readonly string[] | undefined,
+): readonly TableColumn[] {
+  if (!columnOrder || columnOrder.length === 0) return columns
+  const byId = new Map(columns.map((c) => [c.id, c]))
+  const ordered: TableColumn[] = []
+  const seen = new Set<string>()
+  for (const id of columnOrder) {
+    const c = byId.get(id)
+    if (c && !seen.has(id)) {
+      ordered.push(c)
+      seen.add(id)
+    }
+  }
+  for (const c of columns) {
+    if (!seen.has(c.id)) ordered.push(c)
+  }
+  return ordered
+}
+
+/** Applies sort and pagination to the input data. Pure. */
+export function deriveVisibleRows<T extends TableRow>(
+  rows: readonly T[],
+  options: {
+    sort?: { columnId: string | null; direction: TableSortDirection }
+    page: number
+    pageSize: number
+  },
+): { sorted: readonly T[]; visible: T[] } {
+  const sorted =
+    options.sort?.columnId != null
+      ? sortRows(rows, options.sort.columnId, options.sort.direction)
+      : rows
+  const visible = paginateRows(sorted, options.page, options.pageSize)
+  return { sorted, visible }
+}
+
+export function tableDataToCsv(
+  data: TableWidgetData,
+  columns: readonly TableColumn[],
+): string {
+  const head = columns.map((c) => csvEscape(stringifyHeader(c.label))).join(',')
+  const lines = [head]
+  for (const row of data) {
+    const cells = columns.map((c) => csvEscape(stringifyCell(row[c.id])))
+    lines.push(cells.join(','))
+  }
+  return lines.join('\n')
+}
+
+function csvEscape(value: string): string {
+  if (/[",\n\r]/.test(value)) {
+    return `"${value.replace(/"/g, '""')}"`
+  }
+  return value
+}
+
+function stringifyHeader(label: unknown): string {
+  if (typeof label === 'string') return label
+  if (typeof label === 'number' || typeof label === 'boolean')
+    return String(label)
+  return ''
+}
+
+function stringifyCell(value: unknown): string {
+  if (value == null) return ''
+  if (typeof value === 'string') return value
+  if (typeof value === 'number' || typeof value === 'boolean')
+    return String(value)
+  if (Array.isArray(value) || typeof value === 'object')
+    return JSON.stringify(value)
+  return ''
+}

package/src/widgets-v2/table/index.ts

@@ -0,0 +1,23 @@
+export { Table, type TableProps } from './table'
+export { TableUI, type TableUIProps } from './table-ui'
+export { TableSkeleton, type TableSkeletonProps } from './skeleton'
+export { createTableDownloadConfig } from './download'
+export {
+  compareValues,
+  sortRows,
+  paginateRows,
+  resolveColumns,
+  deriveVisibleRows,
+  tableDataToCsv,
+} from './helpers'
+export { DEFAULT_TABLE_LABELS, type TableLabels } from './labels'
+export {
+  DEFAULT_TABLE_PAGE_SIZE,
+  DEFAULT_TABLE_PAGE_SIZE_OPTIONS,
+  type TableColumn,
+  type TableRow,
+  type TableWidgetData,
+  type TableWidgetState,
+  type TableSortDirection,
+  type TableSortState,
+} from './types'

package/src/widgets-v2/table/labels.tsx

@@ -0,0 +1,41 @@
+import { Box, type SxProps, type Theme } from '@mui/material'
+import type { ReactNode } from 'react'
+
+export interface TableLabels {
+  selectAll: string
+  selectRow: (rowId: string | number) => string
+  rowsPerPage: string
+  /**
+   * Renders the displayed-rows summary in the pagination footer. Returns
+   * a `ReactNode` so the default can emphasise the active range
+   * (`from-to`) with a bolder weight while keeping the trailing
+   * ` of total` muted. Override to localise wording or restyle.
+   */
+  paginationOf: (from: number, to: number, total: number) => ReactNode
+  /** aria-label for the first-page pagination button. */
+  firstPage: string
+  /** aria-label for the previous-page pagination button. */
+  previousPage: string
+  /** aria-label for the next-page pagination button. */
+  nextPage: string
+  /** aria-label for the last-page pagination button. */
+  lastPage: string
+}
+
+const boldRange: SxProps<Theme> = { fontWeight: 600, color: 'text.primary' }
+
+export const DEFAULT_TABLE_LABELS: TableLabels = {
+  selectAll: 'Select all rows',
+  selectRow: (id) => `Select row ${id}`,
+  rowsPerPage: 'Rows per page:',
+  paginationOf: (from, to, total) => (
+    <>
+      <Box component='span' sx={boldRange}>{`${from}–${to}`}</Box>
+      {` of ${total}`}
+    </>
+  ),
+  firstPage: 'First page',
+  previousPage: 'Previous page',
+  nextPage: 'Next page',
+  lastPage: 'Last page',
+}

package/src/widgets-v2/table/skeleton.test.tsx

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import { TableSkeleton } from './skeleton'
+
+describe('<TableSkeleton>', () => {
+  it('renders the default 5×4 grid of skeleton cells', () => {
+    const { container, getByLabelText } = render(<TableSkeleton />)
+    expect(getByLabelText('Table skeleton')).toBeTruthy()
+    // 4 header + (5×4) body = 24 cells, each containing one Skeleton.
+    expect(container.querySelectorAll('.MuiSkeleton-root').length).toBe(24)
+  })
+
+  it('honours custom rows × columns', () => {
+    const { container } = render(<TableSkeleton rows={2} columns={3} />)
+    // 3 header + (2×3) body = 9.
+    expect(container.querySelectorAll('.MuiSkeleton-root').length).toBe(9)
+  })
+
+  it('forwards the size prop to MUI Table', () => {
+    const { container } = render(<TableSkeleton size='small' />)
+    // MUI Table doesn't apply a `sizeSmall` class but does set `padding=none`
+    // on header cells when size='small'. Confirm a TableCell got the small
+    // padding class so we know the size prop propagated.
+    expect(container.querySelector('.MuiTableCell-sizeSmall')).not.toBeNull()
+  })
+})

package/src/widgets-v2/table/skeleton.tsx

@@ -0,0 +1,65 @@
+import {
+  Box,
+  Skeleton,
+  Table as MuiTable,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableRow as MuiTableRow,
+  type TableProps as MuiTableProps,
+} from '@mui/material'
+import { styles } from './style'
+
+export interface TableSkeletonProps {
+  /** Number of body rows to render. Defaults to `5` (matches v1). */
+  rows?: number
+  /** Number of columns to render. Defaults to `4` (matches v1). */
+  columns?: number
+  /**
+   * Forwarded to MUI's `<Table size>` so the loading layout matches the
+   * size you'll render in {@link TableUI}. Leave `undefined` (the
+   * default) to use MUI's own default density.
+   */
+  size?: MuiTableProps['size']
+}
+
+/**
+ * Loading placeholder for the Table widget. Renders the same MUI table
+ * primitives that {@link TableUI} uses so the loading layout (column
+ * widths, header band, row density) doesn't shift when data resolves.
+ *
+ * Mirrors the v1 widget's `<TableSkeleton>` structure with v2's themed
+ * `styles.headerCell`.
+ */
+export function TableSkeleton({
+  rows = 5,
+  columns = 4,
+  size,
+}: TableSkeletonProps) {
+  return (
+    <Box sx={styles.container} aria-label='Table skeleton'>
+      <MuiTable size={size} sx={styles.table} stickyHeader>
+        <TableHead>
+          <MuiTableRow>
+            {Array.from({ length: columns }).map((_, c) => (
+              <TableCell key={`head-${c}`} sx={styles.headerCell}>
+                <Skeleton variant='text' width='80%' height={24} />
+              </TableCell>
+            ))}
+          </MuiTableRow>
+        </TableHead>
+        <TableBody>
+          {Array.from({ length: rows }).map((_, r) => (
+            <MuiTableRow key={`row-${r}`} sx={styles.row}>
+              {Array.from({ length: columns }).map((__, c) => (
+                <TableCell key={`cell-${r}-${c}`}>
+                  <Skeleton variant='text' width='70%' height={20} />
+                </TableCell>
+              ))}
+            </MuiTableRow>
+          ))}
+        </TableBody>
+      </MuiTable>
+    </Box>
+  )
+}

package/src/widgets-v2/table/style.ts

@@ -0,0 +1,46 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  container: {
+    width: '100%',
+    overflowX: 'auto',
+  },
+  /**
+   * Minimum table width so columns don't collapse to unreadable widths on
+   * narrow widget shells. Mirrors v1.
+   */
+  table: {
+    minWidth: 650,
+  },
+  headerCell: {
+    fontWeight: 600,
+    backgroundColor: 'background.paper',
+  },
+  /**
+   * Strip the bottom border from the last body row so the body flushes
+   * against the pagination border instead of doubling it up. Mirrors v1.
+   */
+  row: {
+    '&:last-child td, &:last-child th': {
+      border: 0,
+    },
+  },
+  rowClickable: {
+    cursor: 'pointer',
+  },
+  pagination: {
+    borderTop: '1px solid',
+    borderColor: 'divider',
+  },
+  paginationActions: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 0.25,
+    ml: 1,
+  },
+  empty: {
+    textAlign: 'center',
+    color: 'text.secondary',
+    py: 3,
+  },
+} satisfies Record<string, SxProps<Theme>>