# Data table

Sorting, filtering, selection and paging, on the client or the server.

Import from `@a31labs/rax/data-table`.

## Usage

```tsx
import { DataTable, type Column } from "@a31labs/rax/data-table";

const columns: Column<Service>[] = [
  { id: "name", header: "Service", cell: (s) => s.name, subtitle: (s) => s.desc, sortValue: (s) => s.name },
  { id: "req", header: "Requests", cell: (s) => s.req, sortValue: (s) => s.req, numeric: true, firstSort: "desc", hideable: true },
  { id: "p95", header: "p95", cell: (s) => s.p95 == null ? null : `${s.p95} ms`, sortValue: (s) => s.p95, numeric: true, hideable: true, defaultHidden: true },
];

<DataTable label="Services" rows={rows} columns={columns} getRowId={(s) => s.id}
  state={isLoading ? "loading" : error ? "error" : "ready"} error="Could not load services." onRetry={refetch}
  empty={{ title: "No services yet", action: <Button>New service</Button> }}
  selectable selected={selected} onSelectedChange={setSelected}
  globalFilter={query} pageSize={25}
  resizable reorderable storageKey="services" rowHref={(s) => `/services/${s.id}`} onRowNavigate={(href) => router.push(href)} />

// server data: rows render as given, the table reports sort and page intent
<DataTable label="Services" rows={pageRows} columns={columns} getRowId={(s) => s.id}
  manual={{ sort, onSortChange: setSort, page, pageCount, onPageChange: setPage, total }} />
```

## Rules

The only component that depends on `@tanstack/react-table` (v9); it is reachable only through this subpath.

Props: `rows`, `columns`, `getRowId`, `label` (accessible name), `state` (`ready` | `loading` | `error`), `error`, `onRetry`, `empty` (`{ title, description, action }`), `selectable` with `selected` and `onSelectedChange` (a `Set` of row ids), `globalFilter` and `filterFn`, `pageSize` (default 25), `columnRules` (default off), `density` (unset by default, so the table inherits the surrounding density), `manual`, `resizable`, `reorderable`, `storageKey`, `rowHref`, `onRowNavigate`, `toolbar` (a row inside the panel above the table, on the surface, for FilterBar and view controls), plus Panel props (`title`, `description`, `actions`).

A column is `{ id, header, cell, sortValue, numeric, subtitle, firstSort, hideable, defaultHidden }`. A `sortValue` makes the column sortable; `firstSort: "desc"` makes the first click sort descending (dates, counts); empty values (`null` or `undefined`) sort last in both directions and render `–` in `--rax-ink-3`. `numeric` right-aligns with tabular figures. `subtitle` (first column only) renders on the same line in ink-2 at 14px.

- Client-side by default: sorting, filtering and paging happen in the browser. The default filter searches columns that have a `sortValue`.
- `manual` hands sorting, paging and totals to the app for server-loaded data: `{ sort, onSortChange, page (0-based), pageCount, onPageChange, total }`. Filtering is then owned by the app, for example through FilterBar.
- Header row surface-2, 14px, weight 600, ink-2. Rows `--rax-row-h`, divided by `line`, hover surface-2, selected rows accent-soft with a 3px accent edge on the left. Sortable headers are buttons with `aria-sort` and a direction caret.
- Selection: a header checkbox selects every row matching the filter across pages (current page only in manual mode). The footer counts selected rows including filtered-out ones ("3 selected, 2 hidden by filter"). In manual mode it counts every id in `selected`, including rows on other server pages. Row checkbox names come from the first column's `sortValue`, falling back to the row id.
- Built-in states: loading (skeleton rows), empty (EmptyState), error (Alert with retry).
- Columns menu: when any column is `hideable`, a columns icon button (named "Columns") at the end of the header row lists those columns as checkboxes, plus "Reset columns" once the layout differs from the defaults. `defaultHidden` columns start hidden. The first column can never be hidden. Hidden columns still take part in filtering and keep their sort.
- `resizable`: each header gets a resize handle on its right edge (a focusable separator; arrow keys change the width by 16px). Widths stay automatic until the first resize, then every shown column gets a fixed width (64 to 800px, cells truncate with an ellipsis) and a filler column takes the rest. Double-click a handle to go back to automatic widths.
- `reorderable`: the Columns menu (shown even without hideable columns) becomes a SortableList of every column but the first, each with a grip ("Reorder X") and, for hideable columns, its checkbox. Drag a grip, or use Arrow Up, Arrow Down, Home and End on it. The first column always stays first. Columns missing from a stored order (added later) go to the end.
- `storageKey` persists widths, visibility and order in localStorage under `rax-table:<storageKey>`, shared between tabs. The server render uses the defaults, so hydration matches; the stored layout applies right after mount. Blocked storage falls back to memory.
- `rowHref` makes whole rows links: the first cell holds a real link (keyboard and screen readers), a click anywhere else in the row follows it, and Ctrl, ⌘, Shift or the middle button open a new tab. Clicks on controls inside the row (checkboxes, buttons, links) and text selection never navigate. `onRowNavigate(href, row)` plugs in client-side routing; the default is `location.assign`. Do not put links in the first column's cell when using `rowHref`. Only http(s) and relative URLs are followed; anything else (`javascript:`, `data:`) leaves the row unlinked.
- Scrolls horizontally inside its panel on narrow screens; the page never scrolls sideways.

Page: https://rax.a31.at/components/data-table
