@carto/ps-react-ui 4.7.1 → 4.9.0

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
+  })
+})

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

@@ -0,0 +1,364 @@
+import { useCallback, useMemo } from 'react'
+import {
+  Box,
+  Checkbox,
+  IconButton,
+  Table as MuiTable,
+  TableBody,
+  TableCell,
+  TableContainer,
+  TableHead,
+  TablePagination,
+  TableRow as MuiTableRow,
+  TableSortLabel,
+  type TableProps as MuiTableProps,
+} from '@mui/material'
+import type { TablePaginationActionsProps } from '@mui/material/TablePagination/TablePaginationActions'
+import FirstPageIcon from '@mui/icons-material/FirstPage'
+import KeyboardArrowLeft from '@mui/icons-material/KeyboardArrowLeft'
+import KeyboardArrowRight from '@mui/icons-material/KeyboardArrowRight'
+import LastPageIcon from '@mui/icons-material/LastPage'
+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'
+
+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']
+}
+
+/**
+ * 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.
+ */
+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 (
+    <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}
+                    inputProps={{ '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)
+                          }}
+                          inputProps={{
+                            '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)
+          }
+          ActionsComponent={PaginationActions}
+          sx={styles.pagination}
+        />
+      ) : null}
+    </Box>
+  )
+}
+
+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 ''
+}
+
+/**
+ * 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 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>
+    )
+  }
+}

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

@@ -0,0 +1,119 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { act, fireEvent, render, screen } from '@testing-library/react'
+import { Provider } from '../provider/widget-provider'
+import { clearAllWidgetStores, getWidgetStore } from '../stores'
+import { Table } from './table'
+import type { TableColumn, TableWidgetState } from './types'
+
+beforeEach(() => clearAllWidgetStores())
+afterEach(() => clearAllWidgetStores())
+
+const COLUMNS: TableColumn[] = [
+  { id: 'name', label: 'Name', sortable: true },
+  { id: 'score', label: 'Score', sortable: true },
+]
+
+const DATA = Array.from({ length: 23 }, (_, i) => ({
+  id: i + 1,
+  name: `Row ${String(i + 1).padStart(2, '0')}`,
+  score: ((i * 7) % 11) + 1,
+}))
+
+describe('<Table>', () => {
+  it('paginates rows from the store, defaulting to page 0', () => {
+    render(
+      <Provider id='t1' data={DATA}>
+        <Table columns={COLUMNS} initialPageSize={5} />
+      </Provider>,
+    )
+    expect(screen.getByText('Row 01')).toBeTruthy()
+    expect(screen.getByText('Row 05')).toBeTruthy()
+    expect(screen.queryByText('Row 06')).toBeNull()
+  })
+
+  it('writes sort to the store and resets page=0', () => {
+    render(
+      <Provider id='t2' data={DATA}>
+        <Table columns={COLUMNS} initialPageSize={5} />
+      </Provider>,
+    )
+    // Move to page 2 first.
+    getWidgetStore('t2').setState({ page: 2 } as Partial<TableWidgetState>)
+    fireEvent.click(screen.getByText('Score'))
+    const state = getWidgetStore('t2').getState() as TableWidgetState
+    expect(state.sort).toEqual({ columnId: 'score', direction: 'asc' })
+    expect(state.page).toBe(0)
+  })
+
+  it('honors columnOrder from the store', () => {
+    render(
+      <Provider id='t3' data={DATA.slice(0, 2)}>
+        <Table columns={COLUMNS} initialPageSize={5} />
+      </Provider>,
+    )
+    act(() => {
+      getWidgetStore('t3').setState({
+        columnOrder: ['score', 'name'],
+      } as Partial<TableWidgetState>)
+    })
+    const headers = screen.getAllByRole('columnheader')
+    expect(headers[0]?.textContent).toContain('Score')
+    expect(headers[1]?.textContent).toContain('Name')
+  })
+
+  it('in remote mode renders data as-is and uses external `total` for the footer', () => {
+    // Only 3 rows worth of "current page" data, but the server says
+    // there are 87 total. The bridge must not re-sort / re-slice.
+    const PAGE = DATA.slice(0, 3)
+    render(
+      <Provider id='t-remote' data={PAGE}>
+        <Table columns={COLUMNS} remote total={87} initialPageSize={3} />
+      </Provider>,
+    )
+    expect(screen.getByText('Row 01')).toBeTruthy()
+    expect(screen.getByText('Row 03')).toBeTruthy()
+    expect(screen.queryByText('Row 04')).toBeNull()
+    // Pagination footer surfaces the remote total, not data.length.
+    expect(screen.getByText(/of 87/)).toBeTruthy()
+  })
+
+  it('fires onSortChange / onPageChange / onPageSizeChange after store writes', () => {
+    const onSortChange = vi.fn()
+    const onPageChange = vi.fn()
+    const onPageSizeChange = vi.fn()
+    render(
+      <Provider id='t-cb' data={DATA}>
+        <Table
+          columns={COLUMNS}
+          initialPageSize={5}
+          onSortChange={onSortChange}
+          onPageChange={onPageChange}
+          onPageSizeChange={onPageSizeChange}
+        />
+      </Provider>,
+    )
+    fireEvent.click(screen.getByText('Score'))
+    expect(onSortChange).toHaveBeenCalledWith({
+      columnId: 'score',
+      direction: 'asc',
+    })
+  })
+
+  it('selection prop drives the row checkbox state and onSelectionChange fires', () => {
+    const onSelectionChange = vi.fn()
+    render(
+      <Provider id='t4' data={DATA.slice(0, 2)}>
+        <Table
+          columns={COLUMNS}
+          selectable
+          selection={[2]}
+          onSelectionChange={onSelectionChange}
+        />
+      </Provider>,
+    )
+    const cb = screen.getByLabelText('Select row 2')
+    expect((cb as HTMLInputElement).checked).toBe(true)
+    fireEvent.click(screen.getByLabelText('Select row 1'))
+    expect(onSelectionChange).toHaveBeenCalledWith([2, 1])
+  })
+})