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

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 { 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'
+
+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])
+  })
+})

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

@@ -0,0 +1,179 @@
+import { useCallback, useMemo } from 'react'
+import {
+  getWidgetStore,
+  useWidget,
+  useWidgetId,
+  useWidgetShallow,
+} from '../stores'
+import { TableUI, type TableUIProps } from './table-ui'
+import {
+  DEFAULT_TABLE_PAGE_SIZE,
+  type TableColumn,
+  type TableRow,
+  type TableSortState,
+  type TableWidgetState,
+} from './types'
+import { deriveVisibleRows, resolveColumns } from './helpers'
+
+export interface TableProps<T extends TableRow = TableRow> extends Pick<
+  TableUIProps<T>,
+  | 'pageSizeOptions'
+  | 'selectable'
+  | 'labels'
+  | 'emptyContent'
+  | 'size'
+  | 'keyColumn'
+> {
+  /**
+   * Column definitions. Order can be overridden by ChangeColumn via the
+   * `columnOrder` field on the extended widget state.
+   */
+  columns: readonly TableColumn[]
+  /**
+   * When set, render only the first `visibleColumns` entries **after**
+   * applying the user's `columnOrder` from the store. Useful for showing
+   * a compact projection while letting consumers (e.g. `Widget.ChangeColumn`)
+   * see the full column list. When omitted, every column renders.
+   */
+  visibleColumns?: number
+  /** Initial page size (only on first mount; afterwards lives on the store). */
+  initialPageSize?: number
+  /** Selected row ids (destination-owned). */
+  selection?: readonly (string | number)[]
+  onSelectionChange?: (next: readonly (string | number)[]) => void
+  onRowClick?: (row: T) => void
+  onRowHover?: (row: T | null) => void
+  /**
+   * When `true`, the bridge stops sorting and paginating locally and
+   * renders `data` as-is — the consumer is then responsible for
+   * refetching the slice that matches the active `page` / `pageSize` /
+   * `sort` from the outbound callbacks below. `total` is required in
+   * this mode (the server already knows the full row count; the
+   * widget can't infer it from a partial page).
+   */
+  remote?: boolean
+  /**
+   * Server-reported total row count. Required when `remote === true`;
+   * ignored in local mode (where the bridge derives total from the
+   * sorted result of `deriveVisibleRows`).
+   */
+  total?: number
+  /** Fires after the store-level sort write so the consumer can refetch. */
+  onSortChange?: (next: TableSortState) => void
+  /** Fires after the store-level page write so the consumer can refetch. */
+  onPageChange?: (page: number) => void
+  /** Fires after the store-level pageSize write so the consumer can refetch. */
+  onPageSizeChange?: (pageSize: number) => void
+}
+
+/**
+ * Bridge component — reads the widget store's `data`, applies sort + pagination
+ * locally, and feeds `<TableUI />`. Sort, page, and pageSize live on the
+ * extended widget state ({@link TableWidgetState}).
+ */
+export function Table<T extends TableRow = TableRow>({
+  columns,
+  visibleColumns,
+  initialPageSize = DEFAULT_TABLE_PAGE_SIZE,
+  selection,
+  onSelectionChange,
+  onRowClick,
+  onRowHover,
+  remote = false,
+  total: remoteTotal,
+  onSortChange,
+  onPageChange,
+  onPageSizeChange,
+  ...uiProps
+}: TableProps<T>) {
+  const id = useWidgetId()
+  const data = useWidget(id, (s) => s.data as readonly T[] | undefined)
+  const ui = useWidgetShallow<
+    {
+      sort: TableSortState | undefined
+      page: number
+      pageSize: number
+      columnOrder: readonly string[] | undefined
+    },
+    TableWidgetState
+  >(id, (s) => ({
+    sort: s.sort,
+    page: s.page ?? 0,
+    pageSize: s.pageSize ?? initialPageSize,
+    columnOrder: s.columnOrder,
+  }))
+
+  const orderedColumns = useMemo(() => {
+    const reordered = resolveColumns(columns, ui.columnOrder)
+    return visibleColumns == null
+      ? reordered
+      : reordered.slice(0, visibleColumns)
+  }, [columns, ui.columnOrder, visibleColumns])
+
+  // In remote mode the consumer already paginated / sorted server-side,
+  // so pass `data` and `total` straight through. Local mode keeps the
+  // bridge-driven sort + slice via `deriveVisibleRows`.
+  const { rows, totalRows } = useMemo(() => {
+    if (remote) {
+      return {
+        rows: data ?? [],
+        totalRows: remoteTotal ?? 0,
+      }
+    }
+    const { sorted, visible } = deriveVisibleRows(data ?? [], {
+      sort: ui.sort,
+      page: ui.page,
+      pageSize: ui.pageSize,
+    })
+    return { rows: visible, totalRows: sorted.length }
+  }, [remote, data, remoteTotal, ui.sort, ui.page, ui.pageSize])
+
+  const handleSortChange = useCallback(
+    (next: TableSortState) => {
+      getWidgetStore(id).setState({
+        sort: next,
+        page: 0,
+      } as Partial<TableWidgetState>)
+      onSortChange?.(next)
+    },
+    [id, onSortChange],
+  )
+
+  const handlePageChange = useCallback(
+    (page: number) => {
+      getWidgetStore(id).setState({ page } as Partial<TableWidgetState>)
+      onPageChange?.(page)
+    },
+    [id, onPageChange],
+  )
+
+  const handlePageSizeChange = useCallback(
+    (pageSize: number) => {
+      getWidgetStore(id).setState({
+        pageSize,
+        page: 0,
+      } as Partial<TableWidgetState>)
+      onPageSizeChange?.(pageSize)
+    },
+    [id, onPageSizeChange],
+  )
+
+  return (
+    <TableUI
+      {...uiProps}
+      columns={orderedColumns}
+      rows={rows}
+      total={totalRows}
+      page={ui.page}
+      pageSize={ui.pageSize}
+      sort={ui.sort}
+      selection={selection}
+      onSortChange={handleSortChange}
+      onPageChange={handlePageChange}
+      onPageSizeChange={handlePageSizeChange}
+      onSelectionChange={onSelectionChange}
+      onRowClick={onRowClick}
+      onRowHover={onRowHover}
+    />
+  )
+}

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

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest'
+import { filterTableByLockedRows } from './transforms'
+
+describe('filterTableByLockedRows', () => {
+  const ROWS = [
+    { id: 'a', label: 'Alpha' },
+    { id: 'b', label: 'Beta' },
+    { id: 'c', label: 'Gamma' },
+  ]
+
+  it('returns input unchanged when locked set is empty', () => {
+    expect(filterTableByLockedRows(ROWS, [])).toBe(ROWS)
+  })
+
+  it('keeps only rows whose default `id` column is locked', () => {
+    expect(filterTableByLockedRows(ROWS, ['a', 'c'])).toEqual([
+      { id: 'a', label: 'Alpha' },
+      { id: 'c', label: 'Gamma' },
+    ])
+  })
+
+  it('uses a custom keyColumn when supplied', () => {
+    const rows = [
+      { sku: 'X1', name: 'Widget' },
+      { sku: 'X2', name: 'Gadget' },
+    ]
+    expect(filterTableByLockedRows(rows, ['X2'], 'sku')).toEqual([
+      { sku: 'X2', name: 'Gadget' },
+    ])
+  })
+
+  it('falls back to row index when the identity column is nullish', () => {
+    const rows = [{ label: 'first' }, { label: 'second' }]
+    expect(filterTableByLockedRows(rows, [1])).toEqual([{ label: 'second' }])
+  })
+
+  it('returns input unchanged when input is not array-shaped', () => {
+    expect(filterTableByLockedRows('nope', ['a'])).toBe('nope')
+  })
+})