@carto/ps-react-ui 5.1.0 → 6.0.0

package/src/widgets/table/index.ts

@@ -1,55 +1,24 @@
-// 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,
+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'
-
-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/skeleton.tsx

@@ -1,48 +1,65 @@
 import {
   Box,
   Skeleton,
-  Table,
+  Table as MuiTable,
   TableBody,
   TableCell,
   TableHead,
-  TableRow,
+  TableRow as MuiTableRow,
+  type TableProps as MuiTableProps,
 } from '@mui/material'
+import { styles } from './style'
 
 export interface TableSkeletonProps {
-  /** Number of columns to display */
-  columns?: number
-  /** Number of rows to display */
+  /** 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']
 }
 
 /**
- * Table skeleton loader component
+ * 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({ columns = 4, rows = 5 }: TableSkeletonProps) {
+export function TableSkeleton({
+  rows = 5,
+  columns = 4,
+  size,
+}: TableSkeletonProps) {
   return (
-    <Box aria-label='Table skeleton'>
-      <Table>
+    <Box sx={styles.container} aria-label='Table skeleton'>
+      <MuiTable size={size} sx={styles.table} stickyHeader>
         <TableHead>
-          <TableRow>
-            {Array.from({ length: columns }).map((_, index) => (
-              <TableCell key={index}>
-                <Skeleton width='80%' height={24} />
+          <MuiTableRow>
+            {Array.from({ length: columns }).map((_, c) => (
+              <TableCell key={`head-${c}`} sx={styles.headerCell}>
+                <Skeleton variant='text' width='80%' height={24} />
               </TableCell>
             ))}
-          </TableRow>
+          </MuiTableRow>
         </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} />
+          {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>
               ))}
-            </TableRow>
+            </MuiTableRow>
           ))}
         </TableBody>
-      </Table>
+      </MuiTable>
     </Box>
   )
 }

package/src/widgets/table/style.ts

@@ -3,32 +3,41 @@ import type { SxProps, Theme } from '@mui/material'
 export const styles = {
   container: {
     width: '100%',
-    overflow: 'auto',
+    overflowX: 'auto',
   },
+
   table: {
-    minWidth: 650,
+    minWidth: 0,
   },
   headerCell: {
     fontWeight: 600,
-    backgroundColor: (theme: Theme) => theme.palette.background.paper,
+    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,
     },
   },
-  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,
-    },
+  rowClickable: {
+    cursor: 'pointer',
   },
   pagination: {
-    borderTop: (theme: Theme) => `1px solid ${theme.palette.divider}`,
+    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/table/table-ui.tsx

@@ -1,64 +1,368 @@
+import { useCallback, useMemo } from 'react'
 import {
+  Box,
+  Checkbox,
+  IconButton,
   Table as MuiTable,
   TableBody,
   TableCell,
+  TableContainer,
   TableHead,
-  TableContainer as MuiTableContainer,
-  Paper,
+  TablePagination,
+  TableRow as MuiTableRow,
+  TableSortLabel,
   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'
+import type { TablePaginationActionsProps } from '@mui/material/TablePaginationActions'
+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 { DEFAULT_TABLE_LABELS, type TableLabels } from './labels'
+import {
+  DEFAULT_TABLE_PAGE_SIZE_OPTIONS,
+  type TableColumn,
+  type TableRow,
+  type TableSortDirection,
+  type TableSortState,
+} from './types'
+import { styles } from './style'
 
-/**
- * Props for the base Table component
- */
-interface TableComponentProps extends MuiTableProps {
-  /** Table element ref */
-  ref?: Ref<HTMLTableElement>
+export interface TableUIProps<T extends TableRow = TableRow> {
+  columns: readonly TableColumn[]
+  /** Already-paginated, already-sorted rows for the current view. */
+  rows: readonly T[]
+  /** Total row count (across all pages). Required for pagination footer. */
+  total: number
+  page: number
+  pageSize: number
+  pageSizeOptions?: readonly number[]
+  sort?: TableSortState
+  /**
+   * Column name to use as the row identity. Drives selection lookup,
+   * React keys, and aria labels. Defaults to `'id'` — point it at
+   * another column when your rows don't carry an `id` field.
+   */
+  keyColumn?: string
+  /** Selected row ids. Destination-owned. */
+  selection?: readonly (string | number)[]
+  selectable?: boolean
+  onSortChange?: (next: TableSortState) => void
+  onPageChange?: (page: number) => void
+  onPageSizeChange?: (pageSize: number) => void
+  onSelectionChange?: (next: readonly (string | number)[]) => void
+  onRowClick?: (row: T) => void
+  onRowHover?: (row: T | null) => void
+  labels?: Partial<TableLabels>
+  /** Row rendered when `rows` is empty for the current page. */
+  emptyContent?: React.ReactNode
+  /**
+   * Forwarded to MUI's `<Table size>` — `'small'` for compact rows,
+   * `'medium'` for the default density. Leave `undefined` (the default)
+   * to let MUI's own default kick in.
+   */
+  size?: MuiTableProps['size']
 }
 
 /**
- * Base Table component with compound component pattern
- * Provides Table.Head, Table.Body, Table.Row, Table.Cell, Table.CellHeader, Table.Pagination
+ * Pure renderer for a paginated, sortable, optionally-selectable table.
+ * Has no widget-store coupling — `<Table>` (the bridge) reads from the store
+ * and feeds this UI with already-projected data.
  */
-function Table({
-  children,
-  ref,
-  stickyHeader = true,
-  ...props
-}: TableComponentProps) {
+export function TableUI<T extends TableRow = TableRow>({
+  columns,
+  rows,
+  total,
+  page,
+  pageSize,
+  pageSizeOptions = DEFAULT_TABLE_PAGE_SIZE_OPTIONS,
+  sort,
+  keyColumn = 'id',
+  selection,
+  selectable = false,
+  onSortChange,
+  onPageChange,
+  onPageSizeChange,
+  onSelectionChange,
+  onRowClick,
+  onRowHover,
+  labels,
+  emptyContent,
+  size,
+}: TableUIProps<T>) {
+  if (process.env.NODE_ENV !== 'production') {
+    // Dev-time guard: a nullish identity collapses every row into the
+    // same selection-set entry, which manifests as "click one → all
+    // appear selected". Surface it loudly instead of silently degrading.
+    const missing = rows.some((r) => r[keyColumn] == null)
+    if (missing) {
+      // eslint-disable-next-line no-console
+      console.error(
+        `<TableUI>: rows are missing the identity column \`${keyColumn}\`. ` +
+          'Set the `keyColumn` prop to a column present on every row, or ' +
+          'add the column to the data.',
+      )
+    }
+  }
+  const _labels = useMemo(
+    () => ({ ...DEFAULT_TABLE_LABELS, ...labels }),
+    [labels],
+  )
+  // Auto-hide the pagination footer when every row already fits in the
+  // smallest available page size — the Rows-per-page selector + prev /
+  // next buttons would just be inert noise. Consumers force the footer
+  // on by passing a smaller `pageSizeOptions[0]` than `total`.
+  const minPageSize = Math.min(...pageSizeOptions)
+  const showPagination = total > minPageSize
+  // Own the `ActionsComponent` slot ourselves so the Meridian theme's
+  // `theme.components.MuiTablePagination.defaultProps.ActionsComponent`
+  // (which depends on `react-intl`) doesn't leak into the library. The
+  // MUI / Meridian style overrides for `MuiIconButton` /
+  // `MuiTablePagination` still apply.
+  const PaginationActions = useMemo(
+    () => makePaginationActions(_labels),
+    [_labels],
+  )
+  const selectionSet = useMemo(
+    () => new Set<string | number>(selection ?? []),
+    [selection],
+  )
+  // Resolve each row's identity from `keyColumn`, falling back to the row's
+  // index when the cell is nullish. The dev-time guard above surfaces the
+  // misconfiguration loudly, but in production we must NOT collapse every
+  // nullish-keyed row into the same selection-set entry (that's the
+  // "click one → all selected" bug) — a per-index fallback keeps ids
+  // distinct and React keys stable for a given page.
+  const resolveRowId = useCallback(
+    (row: T, index: number): string | number =>
+      (row[keyColumn] ?? index) as string | number,
+    [keyColumn],
+  )
+  const pageRowIds = useMemo(() => rows.map(resolveRowId), [rows, resolveRowId])
+  const allOnPageSelected =
+    pageRowIds.length > 0 && pageRowIds.every((id) => selectionSet.has(id))
+  const someOnPageSelected =
+    !allOnPageSelected && pageRowIds.some((id) => selectionSet.has(id))
+
+  const handleSort = (columnId: string) => {
+    if (!onSortChange) return
+    const sameCol = sort?.columnId === columnId
+    const nextDir: TableSortDirection =
+      sameCol && sort?.direction === 'asc' ? 'desc' : 'asc'
+    onSortChange({ columnId, direction: nextDir })
+  }
+
+  const handleSelectAllOnPage = () => {
+    if (!onSelectionChange) return
+    if (allOnPageSelected) {
+      onSelectionChange(
+        (selection ?? []).filter((id) => !pageRowIds.includes(id)),
+      )
+    } else {
+      const merged = new Set<string | number>(selection ?? [])
+      for (const id of pageRowIds) merged.add(id)
+      onSelectionChange([...merged])
+    }
+  }
+
+  const handleSelectRow = (rowId: string | number) => {
+    if (!onSelectionChange) return
+    const next = new Set<string | number>(selection ?? [])
+    if (next.has(rowId)) next.delete(rowId)
+    else next.add(rowId)
+    onSelectionChange([...next])
+  }
+
   return (
-    <MuiTable stickyHeader={stickyHeader} ref={ref} {...props}>
-      {children}
-    </MuiTable>
+    <Box sx={styles.container}>
+      <TableContainer>
+        <MuiTable stickyHeader size={size} sx={styles.table}>
+          <TableHead>
+            <MuiTableRow>
+              {selectable ? (
+                <TableCell padding='checkbox' sx={styles.headerCell}>
+                  <Checkbox
+                    checked={allOnPageSelected}
+                    indeterminate={someOnPageSelected}
+                    onChange={handleSelectAllOnPage}
+                    slotProps={{
+                      input: { 'aria-label': _labels.selectAll },
+                    }}
+                  />
+                </TableCell>
+              ) : null}
+              {columns.map((column) => {
+                const isSorted = sort?.columnId === column.id
+                const direction = isSorted ? sort?.direction : undefined
+                return (
+                  <TableCell
+                    key={column.id}
+                    align={column.align}
+                    sortDirection={direction}
+                    sx={styles.headerCell}
+                    style={
+                      column.width != null ? { width: column.width } : undefined
+                    }
+                  >
+                    {column.sortable && onSortChange ? (
+                      <TableSortLabel
+                        active={isSorted}
+                        direction={direction ?? 'asc'}
+                        onClick={() => handleSort(column.id)}
+                      >
+                        {column.label}
+                      </TableSortLabel>
+                    ) : (
+                      column.label
+                    )}
+                  </TableCell>
+                )
+              })}
+            </MuiTableRow>
+          </TableHead>
+          <TableBody>
+            {rows.length === 0 ? (
+              <MuiTableRow>
+                <TableCell
+                  colSpan={columns.length + (selectable ? 1 : 0)}
+                  sx={styles.empty}
+                >
+                  {emptyContent ?? null}
+                </TableCell>
+              </MuiTableRow>
+            ) : (
+              rows.map((row, index) => {
+                const rowId = resolveRowId(row, index)
+                const isSelected = selectionSet.has(rowId)
+                return (
+                  <MuiTableRow
+                    key={rowId}
+                    hover
+                    selected={isSelected}
+                    onClick={() => onRowClick?.(row)}
+                    onMouseEnter={() => onRowHover?.(row)}
+                    onMouseLeave={() => onRowHover?.(null)}
+                    sx={{
+                      ...styles.row,
+                      ...(onRowClick ? styles.rowClickable : null),
+                    }}
+                  >
+                    {selectable ? (
+                      <TableCell padding='checkbox'>
+                        <Checkbox
+                          checked={isSelected}
+                          onClick={(e) => {
+                            e.stopPropagation()
+                            handleSelectRow(rowId)
+                          }}
+                          slotProps={{
+                            input: {
+                              'aria-label': _labels.selectRow(rowId),
+                            },
+                          }}
+                        />
+                      </TableCell>
+                    ) : null}
+                    {columns.map((column) => (
+                      <TableCell key={column.id} align={column.align}>
+                        {column.formatter
+                          ? column.formatter(row[column.id], row)
+                          : stringifyCell(row[column.id])}
+                      </TableCell>
+                    ))}
+                  </MuiTableRow>
+                )
+              })
+            )}
+          </TableBody>
+        </MuiTable>
+      </TableContainer>
+      {showPagination ? (
+        <TablePagination
+          component='div'
+          count={total}
+          page={page}
+          rowsPerPage={pageSize}
+          rowsPerPageOptions={[...pageSizeOptions]}
+          onPageChange={(_, next) => onPageChange?.(next)}
+          onRowsPerPageChange={(e) => {
+            const next = parseInt(e.target.value, 10)
+            onPageSizeChange?.(next)
+          }}
+          labelRowsPerPage={_labels.rowsPerPage}
+          labelDisplayedRows={({ from, to, count }) =>
+            _labels.paginationOf(from, to, count)
+          }
+          sx={styles.pagination}
+          ActionsComponent={PaginationActions}
+        />
+      ) : null}
+    </Box>
   )
 }
 
-// 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 }
+function stringifyCell(value: unknown): React.ReactNode {
+  if (value == null) return ''
+  if (typeof value === 'string' || typeof value === 'number') return value
+  if (typeof value === 'boolean') return String(value)
+  if (Array.isArray(value) || typeof value === 'object') {
+    return JSON.stringify(value)
+  }
+  return ''
+}
 
 /**
- * TableContainer widget component
- * Integrates with widget store and provides ref registration using custom hook
+ * Build the `ActionsComponent` used by `<TablePagination>` — four MUI
+ * `IconButton`s for first / previous / next / last. We provide this
+ * ourselves so the Meridian theme's `defaultProps.ActionsComponent`
+ * (which depends on `react-intl`) is bypassed at the call site without
+ * disturbing the rest of the Meridian theme. The factory closes over
+ * the merged label set so aria-labels stay consistent with the rest
+ * of the table's i18n surface.
  */
-function TableContainer(props: TableUIProps) {
-  const { ref } = useWidgetRef<HTMLDivElement>(props.id)
-
-  return <MuiTableContainer ref={ref}>{props.children}</MuiTableContainer>
+function makePaginationActions(labels: TableLabels) {
+  return function PaginationActions({
+    count,
+    page,
+    rowsPerPage,
+    onPageChange,
+  }: TablePaginationActionsProps) {
+    const lastPage = Math.max(0, Math.ceil(count / rowsPerPage) - 1)
+    return (
+      <Box sx={styles.paginationActions}>
+        <IconButton
+          size='small'
+          onClick={(e) => onPageChange(e, 0)}
+          disabled={page === 0}
+          aria-label={labels.firstPage}
+        >
+          <FirstPageIcon fontSize='small' />
+        </IconButton>
+        <IconButton
+          size='small'
+          onClick={(e) => onPageChange(e, page - 1)}
+          disabled={page === 0}
+          aria-label={labels.previousPage}
+        >
+          <KeyboardArrowLeft fontSize='small' />
+        </IconButton>
+        <IconButton
+          size='small'
+          onClick={(e) => onPageChange(e, page + 1)}
+          disabled={page >= lastPage}
+          aria-label={labels.nextPage}
+        >
+          <KeyboardArrowRight fontSize='small' />
+        </IconButton>
+        <IconButton
+          size='small'
+          onClick={(e) => onPageChange(e, lastPage)}
+          disabled={page >= lastPage}
+          aria-label={labels.lastPage}
+        >
+          <LastPageIcon fontSize='small' />
+        </IconButton>
+      </Box>
+    )
+  }
 }