ui-data-table

Component contract

Every list view in Voyage admin is <UiDataTable>. Branches that need a table render this and supply column defs + a paginated row source. The linter scans the React source and flags any <table> not rendered through it.

• columns: ColumnDef[] — id, header, accessor, sortable, sortKey, width, align, cell renderer.
• rows: T[] — current page only. Component does NOT fetch.
• page, pageSize, total: number — pagination state controlled by parent.
• sort?: { columnId, dir: "asc" | "desc" } — controlled.
• onSortChange?: (sort) => void
• onPageChange?: (page) => void
• onRowClick?: (row) => void — optional row activation.
• selectable?: "single" | "multi" | false — adds selection column.
• selectedIds?: string[] + onSelectionChange?: (ids) => void
• state: "ready" | "loading" | "empty" | "error" — exclusive states.
• emptyMessage?: ReactNode · errorMessage?: ReactNode + onRetry?: () => void
• stickyHeader?: boolean (default true) · rowKey: (row) => string

Interaction surface

1. Header renders sortable columns with arrow indicators.

   Click a sortable column header → onSortChange fires. Direction cycles asc → desc → unsorted (or asc → desc → asc for required-sort tables). Active sort column has visible direction arrow.

2. Sticky header pinned during vertical scroll.

   Header row stays visible at the top of the table viewport when scrolling rows. Z-index above row content. Background opaque (no see-through).

3. Row click activates row, NOT child controls.

   Clicking a button or link inside a row does not trigger onRowClick — event must stop at the inner control. Clicking row whitespace fires onRowClick.

4. Selection scope is the current page.

   "Select all" checks every row on the current page only. To select across pages, the parent must offer "Select all N matching" as a separate action — the component never silently expands selection across pagination boundaries.

5. Empty / loading / error are visually + semantically distinct.

   Loading: skeleton rows in the table body, header still rendered. Empty: a single message row spanning all columns with optional CTA. Error: same message-row treatment with a retry button if onRetry is provided. Never zero output.

6. Keyboard navigation.

   Tab focuses the first sortable header, then row controls in DOM order. Up/Down arrow keys move row focus when a row is focused. Enter activates the focused row. Space toggles selection on the focused row when selectable.

Failure modes

Accessibility

• Underlying element is <table> with <thead>, <tbody>, <tr>, <th scope="col">, <td>.
• Sortable column headers are <button> inside <th> with aria-sort reflecting current state.
• Loading state: tbody has aria-busy="true".
• Empty state: a single tr.message-row with role="row", single td spanning all columns.
• Selection column: column header has aria-label="Select rows" + visually-hidden text. Each row checkbox has aria-label referencing the row identity.
• Color contrast: header text ≥ 4.5:1, row text ≥ 4.5:1, sort arrows ≥ 3:1 against header background.
• axe-clean at severity ≥ serious.

Stable test attributes

Visibility teeth. Each attribute must be present AND effectively visible in its applicable state. A hidden empty-state row is a Ratchet violation.

Agent test plan

- header-renders-all-columns: assert ui-data-table-column-header count === columns.length
- sort-fires-onSortChange: click sort-toggle on a sortable column, assert handler called with that columnId
- sort-arrow-reflects-state: dispatch sort=name-asc, assert that column's header has aria-sort=ascending
- sort-roundtrips-through-parent: page-1 sort=name-asc → page-2 sort=name-asc, last row of page-1 alphabetically before first row of page-2
- sticky-header-no-overlap: scroll body, screenshot header, assert no row text overlaps
- row-click-fires-handler: click row whitespace, onRowClick called once with that row
- inner-button-stops-propagation: click delete button inside row, onRowClick NOT called, delete handler called
- select-all-page-only: page-1 select all → selectedIds.length === pageSize
- bulk-select-all-matching-banner: after page-select, banner visible offering cross-page select
- bulk-select-all-matching-applies: click banner CTA → selectedIds.length === total
- state-loading-aria-busy: state=loading, tbody aria-busy=true, skeleton visible
- state-empty-message: state=empty, ui-data-table-empty visible, no rows
- state-error-with-retry: state=error, ui-data-table-error visible, retry button visible
- state-error-without-retry: state=error, no onRetry, error visible, retry absent
- empty-vs-loading-distinguishable: render both, screenshots differ AND data-state attr differs
- total-stable-across-pages: navigate pages 1→2→3, total prop unchanged, footer text "of N" consistent
- long-cell-truncates: cell with 4000-char string, row height ≤ 1.5× standard
- long-cell-tooltip: hover/focus a truncated cell, tooltip shows full content
- keyboard-row-focus: render with onRowClick, Tab to first row, arrow-down moves to row 2
- keyboard-row-enter: focus row, Enter fires onRowClick once
- keyboard-row-space-toggles-selection: focus row when selectable=multi, Space toggles ui-data-table-row-select
- color-contrast-header-text: ≥ 4.5:1
- color-contrast-row-text: ≥ 4.5:1
- color-contrast-sort-arrow: ≥ 3:1
- axe-clean-serious: no axe violations at serious or critical