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

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

@@ -0,0 +1,131 @@
+import { toCsvString } from '../actions/download'
+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 {
+  // Pre-stringify with the table's own header/cell rules, then delegate the
+  // CSV assembly (quoting + spreadsheet formula-injection guard) to the shared
+  // `toCsvString` so escaping stays identical to every other widget's export.
+  const rows: string[][] = [columns.map((c) => stringifyHeader(c.label))]
+  for (const row of data) {
+    rows.push(columns.map((c) => stringifyCell(row[c.id])))
+  }
+  return toCsvString(rows)
+}
+
+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,24 @@
+export { Table, type TableProps } from './table'
+export { TableUI, type TableUIProps } from './table-ui'
+export { TableSkeleton, type TableSkeletonProps } from './skeleton'
+export { createTableDownloadConfig } from './download'
+export { filterTableByLockedRows } from './transforms'
+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,43 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  container: {
+    width: '100%',
+    overflowX: 'auto',
+  },
+
+  table: {
+    minWidth: 0,
+  },
+  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>>

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

@@ -0,0 +1,200 @@
+import { describe, it, expect, vi } from 'vitest'
+import { fireEvent, render, screen, within } from '@testing-library/react'
+import { TableUI } from './table-ui'
+import type { TableColumn } from './types'
+
+const COLUMNS: TableColumn[] = [
+  { id: 'name', label: 'Name', sortable: true },
+  { id: 'score', label: 'Score', sortable: true, align: 'right' },
+]
+
+const ROWS = [
+  { id: 1, name: 'Alpha', score: 12 },
+  { id: 2, name: 'Beta', score: 7 },
+]
+
+describe('<TableUI>', () => {
+  it('renders one row per item with each column cell', () => {
+    render(
+      <TableUI
+        columns={COLUMNS}
+        rows={ROWS}
+        total={ROWS.length}
+        page={0}
+        pageSize={10}
+      />,
+    )
+    expect(screen.getByText('Alpha')).toBeTruthy()
+    expect(screen.getByText('Beta')).toBeTruthy()
+    expect(screen.getByText('12')).toBeTruthy()
+    expect(screen.getByText('7')).toBeTruthy()
+  })
+
+  it('fires onSortChange with new column id and asc on first click', () => {
+    const onSortChange = vi.fn()
+    render(
+      <TableUI
+        columns={COLUMNS}
+        rows={ROWS}
+        total={ROWS.length}
+        page={0}
+        pageSize={10}
+        onSortChange={onSortChange}
+      />,
+    )
+    fireEvent.click(screen.getByText('Name'))
+    expect(onSortChange).toHaveBeenCalledWith({
+      columnId: 'name',
+      direction: 'asc',
+    })
+  })
+
+  it('flips direction on the same column', () => {
+    const onSortChange = vi.fn()
+    render(
+      <TableUI
+        columns={COLUMNS}
+        rows={ROWS}
+        total={ROWS.length}
+        page={0}
+        pageSize={10}
+        sort={{ columnId: 'name', direction: 'asc' }}
+        onSortChange={onSortChange}
+      />,
+    )
+    fireEvent.click(screen.getByText('Name'))
+    expect(onSortChange).toHaveBeenCalledWith({
+      columnId: 'name',
+      direction: 'desc',
+    })
+  })
+
+  it('renders a checkbox column when selectable', () => {
+    render(
+      <TableUI
+        columns={COLUMNS}
+        rows={ROWS}
+        total={ROWS.length}
+        page={0}
+        pageSize={10}
+        selectable
+      />,
+    )
+    expect(screen.getAllByRole('checkbox').length).toBe(ROWS.length + 1)
+  })
+
+  it('select-all toggles selection of all rows on the page', () => {
+    const onSelectionChange = vi.fn()
+    render(
+      <TableUI
+        columns={COLUMNS}
+        rows={ROWS}
+        total={ROWS.length}
+        page={0}
+        pageSize={10}
+        selectable
+        selection={[]}
+        onSelectionChange={onSelectionChange}
+      />,
+    )
+    const headerCheckbox = screen.getAllByRole('checkbox')[0]!
+    fireEvent.click(headerCheckbox)
+    expect(onSelectionChange).toHaveBeenCalledWith([1, 2])
+  })
+
+  it('row checkbox toggles individual rows', () => {
+    const onSelectionChange = vi.fn()
+    render(
+      <TableUI
+        columns={COLUMNS}
+        rows={ROWS}
+        total={ROWS.length}
+        page={0}
+        pageSize={10}
+        selectable
+        selection={[]}
+        onSelectionChange={onSelectionChange}
+      />,
+    )
+    const rowCheckbox = screen.getByLabelText('Select row 1')
+    fireEvent.click(rowCheckbox)
+    expect(onSelectionChange).toHaveBeenCalledWith([1])
+  })
+
+  it('marks already-selected rows as checked', () => {
+    render(
+      <TableUI
+        columns={COLUMNS}
+        rows={ROWS}
+        total={ROWS.length}
+        page={0}
+        pageSize={10}
+        selectable
+        selection={[2]}
+      />,
+    )
+    const rowCheckbox = screen.getByLabelText('Select row 2')
+    expect((rowCheckbox as HTMLInputElement).checked).toBe(true)
+  })
+
+  it('uses the column formatter when provided', () => {
+    const cols: TableColumn[] = [
+      { id: 'score', label: 'Score', formatter: (v) => `<<${String(v)}>>` },
+    ]
+    render(
+      <TableUI
+        columns={cols}
+        rows={ROWS}
+        total={ROWS.length}
+        page={0}
+        pageSize={10}
+      />,
+    )
+    expect(screen.getByText('<<12>>')).toBeTruthy()
+  })
+
+  it('fires onRowClick with the row when a row is clicked', () => {
+    const onRowClick = vi.fn()
+    render(
+      <TableUI
+        columns={COLUMNS}
+        rows={ROWS}
+        total={ROWS.length}
+        page={0}
+        pageSize={10}
+        onRowClick={onRowClick}
+      />,
+    )
+    fireEvent.click(screen.getByText('Alpha'))
+    expect(onRowClick).toHaveBeenCalledWith(ROWS[0])
+  })
+
+  it('shows the empty content when rows is empty', () => {
+    render(
+      <TableUI
+        columns={COLUMNS}
+        rows={[]}
+        total={0}
+        page={0}
+        pageSize={10}
+        emptyContent={<span>No rows</span>}
+      />,
+    )
+    expect(screen.getByText('No rows')).toBeTruthy()
+  })
+
+  it('renders pagination row count using the labels formatter', () => {
+    const { container } = render(
+      <TableUI
+        columns={COLUMNS}
+        rows={ROWS}
+        total={42}
+        page={0}
+        pageSize={10}
+        labels={{ paginationOf: (f, t, total) => `${f}…${t} / ${total}` }}
+      />,
+    )
+    expect(container.textContent).toContain('1…10 / 42')
+    void within
+  })
+})