bitboss-ui 3.0.0-beta.2 → 3.0.0-beta.21

package/dist/ai/BbTable.md

@@ -25,18 +25,20 @@ keyboard navigation, so your markup stays a column definition plus a few slots.
   domain objects straight to `items` and set `item-value` for stable row
   identity — never pre-map rows into `{ label, value }` shapes.
 
-The table **reports** state (sort, selection, page, expansion, highlight)
-through v-models; it never reorders, slices, or fetches on its own. You apply
+The table **reports** state (sort, column order, selection, page, expansion,
+highlight) through v-models; it never sorts, slices, or fetches on its own. You apply
 that state to your data source (client-side or via `dependencies`-driven
 refetch). This keeps it equally at home in a client-only screen and a
 server-paginated one.
 
-**`BbTable` ships no client-side virtualization or windowing** — every row you
-hand it in `items` mounts to the DOM, always. A few hundred rows is fine for a
-client-only screen. Past roughly 1,000 rows, don't ship the whole dataset to
-the browser: page it — feed `BbTable` the current slice as `items` and pass
-`page` / `per-page` / `total-items` (see § Pagination) so the server, not the
-DOM, holds the rest.
+**Every row in `items` mounts to the DOM unless you say `virtual`.** A few
+hundred rows is fine for a client-only screen. Past roughly 1,000 rows,
+either page it — feed `BbTable` the current slice as `items` and pass `page`
+/ `per-page` / `total-items` (see § Pagination) so the server, not the DOM,
+holds the rest — or, when the whole dataset legitimately lives in the
+browser (local filtering, a spreadsheet-shaped tool), add `virtual` and let
+the table window its rows (see § Virtual rows). The two compose: a large
+page can be windowed.
 
 ### Columns: the full grammar
 
@@ -55,17 +57,19 @@ needs is declared here, not in markup:
   `align` prop sets the default for the whole table (`left`).
 - **`width`** freezes the column: numbers and bare numeric strings are px
   (`130`, `'130'`); anything carrying a unit passes through (`'12rem'`,
-  `'20%'`). Declaring any `width` switches the table to `table-layout: fixed`
-  (widths are only authoritative there); unfrozen columns then share the
-  leftover space proportionally to their content.
+  `'20%'`). A declared width is the column's grid track and holds exactly;
+  unfrozen columns size to their content and share any leftover space equally
+  (the table is a CSS grid — the tracks are the width API, there is no
+  `table-layout`). When _every_ column declares a width, the surplus is shared
+  in proportion to the declared widths so the table still fills its container.
 - **`skeleton`** picks the loading placeholder shape (see Loading below).
 - **`sortable` / `sorted`** — see Sorting.
 - **`thClass` / `tdClass` / `rowClass`** style the header cell, the data cells,
-  and the whole `<tr>`. `tdClass` and `rowClass` may be functions
+  and the whole row. `tdClass` and `rowClass` may be functions
   `(content, key, item) => Classes` for state-dependent styling. Table-level
   `thClass` / `tdClass` / `rowClass` / `headerRowClass` apply everywhere; a
   row's classes accumulate the table `rowClass` plus every column's.
-- **`snap`** maps a nested table's column onto its parent's tracks — see
+- **`snap`** names the parent column a nested table's column sits under — see
   Nested tables.
 
 **Columns, formatters and a per-row class**
@@ -155,7 +159,7 @@ const invoices: Invoice[] = [
 	},
 ];
 
-// `row-class` is applied to each `<tr>`; use it to flag rows by state. Soft amber
+// `row-class` is applied to each row (`.bb-table-data__row`); use it to flag rows by state. Soft amber
 // wash matches the design-language attention accent — public API, no internals.
 const rowClass = (invoice: Invoice) =>
 	invoice.status === 'overdue'
@@ -194,11 +198,11 @@ pre-mapping your items:
 ```
 
 **`actions` and `select` are not columns.** Both are rendered by the table
-itself, from the `actions` and `selectable` props. Putting
-`{ key: 'actions' }` in `columns` adds an ordinary data column that reads
-`item.actions`, so you get a stray empty cell _and_ the `#actions` slot never
-renders — which looks like a broken slot and is really a bad column list. Dev
-builds warn.
+itself: the selection column from the `selectable` prop, the actions column
+from the `#actions` slot — providing the slot is what creates the column,
+there is no prop. Putting `{ key: 'actions' }` in `columns` adds an ordinary
+data column that reads `item.actions`, so you get a stray empty cell next to
+the real one. Dev builds warn.
 
 ### Custom cells and headers
 
@@ -207,7 +211,11 @@ Override any column's body with a `#<key>` slot and its header with a
 characters turned into `_` (dashes are kept as-is), **lowercased**:
 `address.city` → `#address_city`, `first_name` → `#first_name`, `issued-at` →
 `#issued-at`, but also `issuedAt` → `#issuedat` — prefer snake_case keys so
-slot names read naturally. Keep the column in `columns`
+slot names read naturally. Building slot names in code (columns from config, a
+dynamic `<template>` loop)? Import the normalizer itself — `import { slotKey }
+from 'bitboss-ui'` — instead of restating the rule: a hand copy that differs by
+one character (`\W+` collapses dashes; the real rule keeps them) makes the slot
+silently never match. Keep the column in `columns`
 even when you fully slot it: label, alignment and width still come from there.
 
 Body cell scope: `content` (the formatted value), `item` (raw row), `value`
@@ -217,7 +225,24 @@ Body cell scope: `content` (the formatted value), `item` (raw row), `value`
 one-way state; the `toggle*` callbacks are the write path.
 
 Header scope: `label`, `items` (the full list — handy for counts), `sortable`,
-`sortOrder`, `toggleSort`, `classes`.
+`sortOrder`, `toggleSort`, `hideColumn` (hides the column, see "Column
+visibility"), `classes`.
+
+**Add beside a header instead of replacing it** with
+`#header:<key>:prepend` / `#header:<key>:append` — rendered before / after the
+column's existing header content (the label + sort control, or your own
+`#header:<key>` replacement), so a resize grip or reorder handle no longer
+costs you the built-in sort button. The table-wide pair `#header:prepend` /
+`#header:append` applies one template to every data column's header (never the
+structural select/actions cells); both forms receive the header scope above
+plus `columnKey` (the raw column key) so a table-wide template can branch per
+column. When both a per-column and the table-wide slot are provided for the
+same side, the per-column one wins for that column — they never stack. Affixes
+render even beside a full `#header:<key>` replacement (the same rule as
+BbDropdown's `#<key>:prepend/append`). One caveat: a column key that
+normalizes to `prepend` or `append` collides with the table-wide slot names;
+the table-wide interpretation wins, per-column header slots are unavailable
+for that column, and dev builds warn.
 
 Below, the status badges carry brand glyphs shipped in the app's `iconDir`,
 referenced as `local:*` names on the badge's `prepend:icon`. Per the icons
@@ -365,7 +390,10 @@ Beyond per-column slots, the structural slots cover every other region:
 (replace the per-row checkbox/radio; scope: `item`, `value`, `checked`,
 `disabled`, `readonly`, `inputName`, `toggleSelected`), `#loading`, `#no-data`
 (both below), and `#thead` / `#tbody` / `#tfoot` to replace an entire region
-when you need full control (you then own its markup and semantics).
+when you need full control (you then own its markup and semantics: the table
+is a CSS grid, so pass `<div role="row">` rows holding `<div role="cell">` /
+`<div role="columnheader">` cells — never `<tr>`/`<td>`; a spanning cell uses
+`grid-column: span N` with `#tfoot`'s `columnCount`, see **Styling hooks**).
 
 ### Loading and empty states
 
@@ -396,8 +424,9 @@ it renders only when there is nothing to keep. (Scope: the current, possibly
 stale `items` — handy for matching the previous row count.) When `items` resolves
 empty the table shows its no-data row — localized default text, overridable via
 `no-data-text` or fully via the `#no-data` slot. That slot fills the table's own
-full-width empty-state cell (already centred, colspan already counted), so pass
-the content — a message, a "clear filters" button — not a `<tr>` of your own.
+full-width empty-state cell (already centred, already spanning every column),
+so pass the content — a message, a "clear filters" button — not a row of your
+own.
 
 `loading-text` is the loading row's `aria-live` announcement. Like
 `no-data-text` it has a **localized default** (`common.loadingText` —
@@ -685,14 +714,21 @@ scriptable from anywhere via `useBbTableContext`
 ### Sorting
 
 Mark columns `sortable` and bind `v-model:sort` — an ordered
-`BbTableSortEntry[]` (`[columnKey, 'asc' | 'desc']`). Header buttons cycle a
-column unsorted → asc → desc → removed; a direction flip updates the entry in
+`BbTableSortEntry[]` (`[columnKey, 'asc' | 'desc']`). A click anywhere on a
+sortable header (its whitespace included — AG Grid parity; the built-in
+button is the keyboard/AT control) cycles the column unsorted → asc → desc →
+removed; a direction flip updates the entry in
 place, so the column keeps its priority in a multi-column sort and other
 entries are never touched. The array order **is** the priority: first entry
 sorts first. The table only reports the model; **apply it to your data**
 (client-side, as below) or forward it to the server as `orderBy` and refetch
 via `dependencies`.
 
+The affordance is one arrow: nothing at rest, a faint arrow previewed while
+the header is hovered or focused, solid once the column is sorted (up for
+ascending, down for descending — the AG Grid convention), gone again on the
+third click.
+
 **Sortable headers driving a client-side sort**
 
 ```vue
@@ -773,11 +809,279 @@ const sortedInvoices = computed(() => {
 
 A custom `#header:<key>` slot replaces the built-in sort button, but its scope
 hands you `sortOrder` and `toggleSort` so your header can keep sorting alive
-(render your own button and call `toggleSort`). The column-level `sorted`
+(render your own button and call `toggleSort`). To merely add something next
+to the control — a resize grip, a filter icon — use
+`#header:<key>:prepend/append` instead and keep the built-in button (see
+"Custom cells and headers"). The column-level `sorted`
 field only seeds the header's `aria-sort` when no live model entry exists — it
 does not move the visual indicator; to start pre-sorted, seed `v-model:sort`
 instead (as the example does).
 
+### Column order
+
+`columns` declares what a column **is**; `v-model:order` is the order
+it **renders** in — an array of column keys, the same split as `sortable` +
+`v-model:sort`. Two things write it:
+
+- **Your own control** — a column panel, a settings drawer, a persisted
+  preference. Bind the model and write the array; the table follows. No flag
+  needed for this.
+- **The user, on the table** — with `reorderable`, every data header
+  is a grab surface: drag it and the column moves live under the pointer (AG
+  Grid style, a chip with the label follows), release to commit. The same
+  header row is also one keyboard tab stop (the AG Grid grammar): ←/→ move
+  focus between headers, **Shift+←/→** move the column one slot
+  (Shift+Home/End to the ends), Enter sorts a sortable header.
+  Each committed move writes the model once and is announced.
+
+The model's contract is what makes a column panel trivial:
+
+- Keys listed first render first; declared columns the array omits follow, in
+  declaration order (a column added to `columns` later renders last).
+- A `hidden` column (next section) keeps its slot without rendering, and keys
+  that match no declared column render nothing but are **preserved in
+  place** — a column that exists only for some users comes back exactly where
+  it was.
+- A user move relocates **exactly one key**; everything else, hidden keys
+  included, keeps its relative order. The first move on a partial (or empty)
+  model emits the completed array — every declared key, hidden ones included
+  — so persist that and the model is complete from then on.
+- A drop that changes nothing emits nothing; unbound, the table keeps the
+  order as per-mount state like `sort`.
+
+**A column panel and the header drag sharing one order**
+
+```vue
+<template>
+	<div class="flex max-w-2xl flex-col gap-3">
+		<!-- ONE order, two writers: the panel's buttons and the table's own
+		     header drag / keyboard handles both write `v-model:order`.
+		     Visibility is a flag ON the definition (`hidden`), so a hidden
+		     column stays declared, keeps its slot in the order, and comes back
+		     where it was. -->
+		<ul
+			aria-label="Columns"
+			class="flex flex-wrap gap-2 text-xs text-[color:var(--bb-text-muted)]"
+		>
+			<li
+				v-for="(column, index) in panelColumns"
+				:key="column.key"
+				class="flex items-center gap-1 rounded-[var(--bb-radius-sm)] border border-[color:var(--bb-border)] py-0.5 pl-2 pr-1"
+			>
+				<BbCheckbox
+					:label="column.label"
+					:model-value="!hidden.has(column.key)"
+					@update:model-value="setHidden(column.key, !$event)"
+				/>
+				<BbButton
+					:aria-label="`Move ${column.label} left`"
+					:disabled="index === 0"
+					icon="lucide:chevron-left"
+					size="xs"
+					variant="ghost"
+					@click="move(column.key, -1)"
+				/>
+				<BbButton
+					:aria-label="`Move ${column.label} right`"
+					:disabled="index === panelColumns.length - 1"
+					icon="lucide:chevron-right"
+					size="xs"
+					variant="ghost"
+					@click="move(column.key, 1)"
+				/>
+			</li>
+		</ul>
+		<div
+			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		>
+			<BbTable
+				v-model:order="order"
+				caption="Invoices"
+				:columns="columns"
+				compact
+				item-value="id"
+				:items="invoices"
+				reorderable
+				@hide:column="(key) => setHidden(key, true)"
+			>
+				<!-- A "hide" control beside every header: the slot's `hideColumn()` is
+				     one-way (a hidden column has no header), so the panel above
+				     is what brings a column back. -->
+				<template #header:append="{ hideColumn, label }">
+					<BbButton
+						:aria-label="`Hide ${label}`"
+						icon="lucide:eye-off"
+						size="xs"
+						variant="ghost"
+						@click="hideColumn"
+					/>
+				</template>
+			</BbTable>
+		</div>
+		<p class="text-xs text-[color:var(--bb-text-muted)]">
+			Order model: <code>{{ JSON.stringify(order) }}</code> · hidden:
+			<code>{{ JSON.stringify([...hidden]) }}</code>
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbButton, BbCheckbox, BbTable } from 'bitboss-ui';
+import type { BbTableColumn } from 'bitboss-ui';
+
+type Invoice = {
+	id: string;
+	number: string;
+	client: string;
+	issued: string;
+	amount: number;
+};
+
+const euro = new Intl.NumberFormat('en-IE', {
+	style: 'currency',
+	currency: 'EUR',
+});
+
+// The declaration: what a column IS. Never reordered, never filtered.
+const definitions: Array<BbTableColumn<Invoice>> = [
+	{ key: 'number', label: 'Invoice', width: 110 },
+	{ key: 'client', label: 'Client' },
+	{ key: 'issued', label: 'Issued', width: 110 },
+	{
+		key: 'amount',
+		label: 'Amount',
+		align: 'right',
+		width: 110,
+		formatter: euro.format,
+	},
+];
+
+const invoices: Invoice[] = [
+	{
+		id: '1',
+		number: 'INV-1041',
+		client: 'Northwind Traders',
+		issued: '2026-08-02',
+		amount: 4200,
+	},
+	{
+		id: '2',
+		number: 'INV-1042',
+		client: 'Globex',
+		issued: '2026-08-05',
+		amount: 980,
+	},
+	{
+		id: '3',
+		number: 'INV-1043',
+		client: 'Initech',
+		issued: '2026-08-11',
+		amount: 15600,
+	},
+	{
+		id: '4',
+		number: 'INV-1044',
+		client: 'Umbrella',
+		issued: '2026-08-19',
+		amount: 2750,
+	},
+];
+
+// The state, both persistable as-is: render order (keys) and the hidden set.
+// A partial or empty order is fine — the first move writes back the
+// complete array, hidden keys in their slots, because every column stays
+// declared below.
+const order = ref<string[]>([]);
+const hidden = ref(new Set<string>());
+
+// The definitions, with the persisted visibility mapped in. Same shape you
+// would use for persisted widths (`width`) — the definition is the truth.
+const columns = computed(() =>
+	definitions.map((column) => ({
+		...column,
+		hidden: hidden.value.has(column.key),
+	}))
+);
+
+// The panel lists every declared column in the order the model has them
+// (omitted keys follow in declaration order, exactly as the table renders).
+const panelColumns = computed(() => {
+	const rank = (key: string) => {
+		const index = order.value.indexOf(key);
+		return index < 0 ? order.value.length : index;
+	};
+	return [...definitions].sort((a, b) => rank(a.key) - rank(b.key));
+});
+
+const setHidden = (key: string, value: boolean) => {
+	const next = new Set(hidden.value);
+	if (value) next.add(key);
+	else next.delete(key);
+	hidden.value = next;
+};
+
+const move = (key: string, delta: 1 | -1) => {
+	const next = panelColumns.value.map((column) => column.key);
+	const from = next.indexOf(key);
+	const to = from + delta;
+	if (from < 0 || to < 0 || to >= next.length) return;
+	next.splice(from, 1);
+	next.splice(to, 0, key);
+	order.value = next;
+};
+</script>
+```
+
+### Column visibility
+
+`hidden: true` on a column definition hides it: no header, no cells, no grid
+track. The column stays **declared**, and that is the whole point — the order
+model is completed against every declared key, so a hidden column keeps its
+slot through any number of header drags, and it returns to that slot the
+moment the flag clears. Two rules follow:
+
+- **Hidden means "exists, not shown".** A column panel, a persisted
+  preference, a narrow-screen breakpoint all write `hidden` into the
+  definition (a `computed` over your persisted set — the example above does
+  exactly that). Filter `columns` only for a column that does **not exist**
+  for this user (a custom field they don't have); its key, if a saved order
+  still lists it, is preserved in place like any unknown key.
+- **There is no visibility model, on purpose** — the `width` shape, not the
+  `sort` one. The definition is the single declared truth. Header slots
+  (`#header:<key>`, `#header:<key>:append`, the table-wide `#header:append`)
+  receive a `hideColumn()` callback for a "Hide column" control of your own; calling
+  it hides the column for the mount and fires `@hide:column="(key) => …"`
+  once. Persist by writing `hidden: true` back into the definition — the
+  override matches it and stays; write `hidden: false` (the panel showing the
+  column again) and the definition wins. Unbound, the hide lives for the
+  mount, like an unbound resize. A hidden column has no header, so `hideColumn()`
+  is one-way by nature: if you offer it, own the persistence and give the
+  user a panel that shows columns again.
+
+A nested table that shares its parent's keys shares its `hidden` flags too,
+the same way it shares `order` — a hidden parent column has no track for a
+child cell to land on.
+
+**Pins travel with the column.** `fixed` is a field on the column
+definition (see "Pinned columns"), so a reorder moves the pin with the cell:
+drag the identity column to slot 3 and it is still sticky, now at slot 3.
+The offset is still positional — the pinned columns before it on the same
+side — so a pinned column dragged away from the edge sticks at `left: 0` and
+slides over the columns before it. Lock the pinned columns in place by
+normalizing the model in your `@update:order` handler when that matters.
+
+**Nested tables.** A parent that uses `order` or `reorderable` is inherited
+by **position**: its columns can move, so the child's `snap` targets and
+same-key pairing are ignored there (dev builds warn) and the child aligns to
+the parent's rails slot by slot. Give both tables the same `v-model:order`
+when they share keys and they stay paired. Never reorder (or share the order
+with) a snapped child itself — dev builds warn.
+
+Apply the model synchronously in your handler and persist afterwards: an
+`await` before the write moves the cell in a later flush, after the table
+has re-focused the handle, and keyboard focus is usually lost (whether it
+survives depends on which cell Vue's keyed patch detaches).
+
 ### Selection and bulk actions
 
 Add `selectable` for multi-select (`multiple` is the default) bound with
@@ -1143,7 +1447,7 @@ fields.
 Track open rows with `v-model:expanded-items` (an array of row values — set
 `item-value` so expansion is stable across refetches) and render their detail
 through the `#expand` slot, a full-width row below the main one. Trigger it
-from the `#actions` slot (enable the column with `actions`, label it with
+from the `#actions` slot (the slot creates the actions column; label it with
 `actions-text`): the scope hands you `toggleExpanded` — a **callback** — plus
 the read-only `expanded` flag. Drive open/close through the callback; the
 `expanded` prop is one-way state, not something to mutate.
@@ -1160,7 +1464,6 @@ the read-only `expanded` flag. Drive open/close through the callback; the
 	>
 		<BbTable
 			v-model:expanded-items="expanded"
-			actions
 			actions-text="Details"
 			caption="Invoices"
 			:columns="columns"
@@ -1277,39 +1580,161 @@ fixed first track).
 The actions-column toggle remains valid — prefer it when expansion reveals
 _detail about the row_ rather than _children of it_.
 
+### Column resize
+
+`resizable` puts a handle on the trailing edge of every data header:
+drag it and the column follows live, release to commit; double-click it to go
+back to the declared width. From the keyboard, **Alt+←/→** resizes the
+focused header in 10px steps (the header row is a tab stop whenever columns
+are resizable or reorderable).
+
+There is no width model on purpose. `width` on the column definition stays
+the single declared truth, and a user resize is an **override** the table
+keeps until that column's `width` changes:
+
+- Each commit fires `@resize:column="(key, width) => …"` **once** with the new width
+  in px — or `null` after a double-click reset.
+- To persist, write the reported width back into your column definition (a
+  `computed` over your persisted widths). The definition wins whenever it
+  changes, so a programmatic `width` change always takes effect.
+- Unbound, the override lives for the mount, like an unbound `sort`.
+- A resized width is always px; `width` still accepts `'20%'` / `'12rem'`
+  for what you declare yourself.
+
+Headers never wrap. A column you have not sized is never narrower than its
+own heading — the label is the table's size hint, so an empty or slim column
+with a long heading still reads on a narrow screen (the table overflows
+instead). Once a track is a length (a declared `width`, a user resize) the
+label cannot widen it: squeezed, it ellipsizes and the sort arrow stays; at
+the narrowest only the arrow (and the handle) survive, and the column is
+still resizable. The data cells of a resized column clip with an ellipsis
+instead of spilling into the neighbour (a squeezed track cannot wrap a single
+word); every other cell keeps wrapping. While a resize runs the whole page
+shows the resize cursor.
+
+A resized column becomes an **exact** track; the other columns keep doing
+what they did — unfrozen ones share the surplus, and a table whose columns
+are all declared with a `width` keeps sharing it among the un-resized ones —
+so a filling table stays filled and nothing collapses. **Shift+drag** moves
+the border instead: the right neighbour absorbs the delta, the total stays
+put, and both columns are reported. A table that inherits its widths from a
+parent (`inherit-column-widths`) renders no handles — its tracks are the
+parent's.
+
+**Resizable columns reporting widths back into the definition**
+
+```vue
+<template>
+	<div class="flex max-w-2xl flex-col gap-1.5">
+		<div
+			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		>
+			<BbTable
+				caption="Invoices"
+				:columns="columns"
+				compact
+				item-value="id"
+				:items="invoices"
+				resizable
+				@resize:column="onResize"
+			/>
+		</div>
+		<p class="text-xs text-[color:var(--bb-text-muted)]">
+			Widths: <code>{{ JSON.stringify(widths) }}</code>
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbTable } from 'bitboss-ui';
+import type { BbTableColumn } from 'bitboss-ui';
+
+type Invoice = { id: string; number: string; client: string; amount: number };
+
+const base: Array<BbTableColumn<Invoice>> = [
+	{ key: 'number', label: 'Invoice' },
+	{ key: 'client', label: 'Client' },
+	{ key: 'amount', label: 'Amount', align: 'right' },
+];
+// Persist THIS (localStorage, a user preference…): key → px.
+const widths = ref<Record<string, number>>({});
+// The definition carries the persisted widths; the table treats them as the
+// declared truth, so nothing jumps after a reload.
+const columns = computed(() =>
+	base.map((column) => ({ ...column, width: widths.value[column.key] }))
+);
+const onResize = (key: string, width: number | null) => {
+	const next = { ...widths.value };
+	if (width === null) delete next[key];
+	else next[key] = width;
+	widths.value = next;
+};
+const invoices: Invoice[] = [
+	{ id: '1', number: 'INV-1041', client: 'Northwind Traders', amount: 4200 },
+	{ id: '2', number: 'INV-1042', client: 'Globex', amount: 980 },
+	{ id: '3', number: 'INV-1043', client: 'Initech', amount: 15600 },
+];
+</script>
+```
+
 ### Nested tables that align with the parent
 
 A `BbTable` rendered inside another's `#expand` slot is independent by
 default. Add `inherit-column-widths` and it snaps its columns to the parent's
 tracks, so a line-items breakdown reads as a continuation of the invoice row
-above it (this also forces fixed layout). The mechanics:
+above it. The mechanics:
 
 - `inherit-column-widths` — `true` inherits from the nearest ancestor table;
   a string targets a specific ancestor's `id` (useful when an intermediate
   table has a different column count).
-- By default child columns map one-to-one onto the parent's data columns. A
-  column's `snap` remaps it: a number is a start track (`2` occupies the
-  parent's third data region), `[start, end]` spans a range (fractions
-  allowed; `end: -1` runs to the end of the data region). Structural columns
-  (`select`, actions) are accounted for automatically.
+- By default a child column pairs with the parent column of the **same key**,
+  and a column the parent lacks flows into the next parent track no other
+  column claimed. A column's `snap` names the parent column instead:
+  `snap: 'client'` takes that track, `['client', 'amount']` spans from the
+  start of one through the end of the other, and the parent's structural
+  columns are targets by name (`'select'`, `'actions'` — `['name',
+'actions']` runs a column across the parent's actions cell too). A
+  trailing `.digits` on a key in a pair is a fraction of that track
+  (`['a', 'b.5']` = all of `a` plus half of `b`). Snaps and keys resolve
+  against the parent's **rendered** columns: a target the parent hides (or
+  never had) makes the column flow like an unsnapped one; a snap that lands
+  before the previous column's cannot tile and flows too (dev builds warn);
+  under a parent that reorders, snaps are ignored (see Column order).
 - A child with **more** columns than the parent content-sizes the extras and
-  scrolls; with fewer, the last width-free column absorbs the slack so both
-  tables end flush.
-- **When the parent has `selectable`/`actions` columns, snap every child
-  column** (`snap: base` … `base + n`, where `base` is `1` under a selectable
-  parent, `0` otherwise). A width-free last column becomes the fill track and
-  absorbs the parent's actions region — right-aligned content then sits under
-  the expand/actions control instead of under the parent's last data column.
-  With every column snapped, the parent's select and actions tracks fold into
-  the child's first/last cell as _padding_, so the child's content stays flush
-  with the parent's data grid on both edges (a child without its own select
-  column starts flush with the parent's first data column — the inset itself
-  reads as hierarchy).
+  overflows into the parent's scroll (see below); with **fewer**, the leading
+  columns stay 1:1, the actions column inherits the parent's actions width,
+  and the last content column runs across every remaining parent track so
+  both tables end flush (a right-aligned total lands under the parent's last
+  column). Give that last column a `width` or an explicit `[start, end]`
+  snap only if you want it to stop short — the leftover then joins the
+  actions region instead. A column with nothing free left to flow into is an
+  overflow column too.
+- **An inheriting child does not scroll on its own — the parent's scrollport
+  is the only one.** That is what keeps the two grids locked together: a child
+  with its own scroll position would fall out of alignment the moment either
+  one moved, which is the whole thing `inherit-column-widths` exists to
+  prevent. One scrollbar moves both.
+- **The parent's `selectable`/`actions` columns are handled for you** — the
+  child's content columns pair with the parent's content columns by key (no
+  `snap` needed for that), and the parent's select/actions _regions_ are reserved on
+  each side: a child with its own select or actions column widens that cell
+  to the parent's (two equal cells, controls at the row's end, so the ⌃ sits
+  under the parent's); a child without one folds the region into its first/
+  last cell as _padding_, so its content stays flush with the parent's data
+  grid on both edges (the inset reads as hierarchy). Only a child cell
+  _wider_ than the parent's — a select the parent lacks, more buttons — moves
+  anything, and only the adjacent content column: it shrinks by the surplus
+  so every other rail holds. What a child publishes to its own children is
+  the same contract (content rails + regions), so a three-level nest aligns
+  at every depth.
 - **Scope any page-level cell-padding overrides to the parent's own cells.** A
-  bare `:deep(tbody td:first-child)` also matches the nested table's cells and
-  clobbers the offset padding it computes to stay aligned — use direct-child
-  combinators (`:deep(> table > tbody > tr > td:first-child)`) so the child
-  keeps its structural padding.
+  bare `:deep([role='cell']:first-child)` also matches the nested table's
+  cells and clobbers the offset padding it computes to stay aligned — use the
+  direct-child chain through the grid's containers
+  (`:deep(> .bb-table__table > .bb-table__body > [role='row'] > :first-child)`)
+  so the child, which lives inside `.bb-table-expand__cell`, keeps its
+  structural padding. The canonical `.table-flush` idiom is under **Styling
+  hooks**.
 
 **Invoice lines aligned under the invoice columns**
 
@@ -1323,7 +1748,6 @@ above it (this also forces fixed layout). The mechanics:
 	>
 		<BbTable
 			v-model:expanded-items="expanded"
-			actions
 			actions-text="Line items"
 			caption="Invoices"
 			:columns="columns"
@@ -1419,6 +1843,50 @@ const expanded = ref<string[]>([]);
 </script>
 ```
 
+#### Affixed actions on both tables
+
+A nested table can pin its own actions column with `fixed-actions` — child
+rows usually need their own row actions — and both action columns pin to the
+same visible edge:
+
+```vue
+<BbTable
+	id="programmes"
+	:columns="columns"
+	fixed-actions
+	:items="rows"
+	item-value="id"
+>
+	<template #actions="{ item }">…</template>
+	<template #expand="{ item }">
+		<BbTable
+			:columns="childColumns"
+			fixed-actions
+			inherit-column-widths="programmes"
+			:items="item.children"
+			item-value="id"
+		>
+			<template #actions="{ item }">…</template>
+		</BbTable>
+	</template>
+</BbTable>
+```
+
+This works because the child shares the parent's scrollport. `position: sticky`
+resolves against the nearest scrolling ancestor, and the child's own box is as
+wide as the parent's **content** — so if it opened a scrollport of its own, the
+child's actions would affix to an edge sitting out in the overflow, hundreds of
+pixels past what anyone can see, while the parent's pinned correctly. The
+child's actions column inherits the parent's actions region by itself (the
+structural rule above), so the two columns line up rather than merely both
+being pinned.
+
+A pinned cell is opaque — it paints the table's `--bg` surface because it
+slides over its siblings — so a nested table sitting on a tinted expand row
+(`--bb-muted` is the usual choice) shows white pinned actions unless you tell
+it which surface it is on: `.nest .bb-table { --bg: var(--bb-muted); }`. Same
+rule as any table on a non-panel surface (see **Styling hooks**).
+
 #### Flush tables + inherited widths: mind the edge padding
 
 `table-flush` removes the outer cell padding so the table reads edge-to-edge in
@@ -1432,9 +1900,10 @@ Two rules keep them honest:
 1. **Snap against the same base you paint.** Measure the parent's columns with
    the same flush/padded state the child renders in — never measure padded and
    render flush.
-2. **Never add nest padding on the body only.** Padding the child's `tbody` but
-   not its header (or vice versa) reintroduces exactly the offset the snap just
-   removed. Put the inset on the nest container, where both rows inherit it.
+2. **Never add nest padding on the body only.** Padding the child's body
+   (`.bb-table__body`) but not its header (or vice versa) reintroduces exactly
+   the offset the snap just removed. Put the inset on the nest container, where
+   both row groups inherit it.
 
 ### Row highlight (master–detail)
 
@@ -1447,11 +1916,42 @@ clicks are ignored on purpose: those inside interactive elements (links,
 buttons, inputs, labels keep their own semantics) and those ending a text
 selection (dragging to copy a cell must not mutate state).
 
+**Highlight is opt-in, and the model's value is the switch.** Bind nothing and
+the mechanic is entirely off — a row click emits `click:row` and does nothing
+else: no class, no `aria-current`, no state. That matters because the table has
+nowhere to put a highlight it invents; a table that highlighted itself would
+drive a cursor the app can neither read nor clear.
+
+The switch reads the value, not the binding: **`undefined` means "never
+initialised" and keeps highlight off; `null` means "initialised and currently
+empty" and turns it on.** So initialise the model:
+
+```ts
+const highlighted = ref(null); // ✅ connected
+const highlighted = ref(); // ❌ undefined — highlight stays off (warns in dev)
+```
+
+A value seeded through the shared context counts exactly the same, and binds
+two ways just like the prop:
+
+```ts
+const highlighted = ref(null);
+useBbTableContext('invoices-table', { highlighted });
+```
+
+`click:row` is never gated — it fires on every row click whether or not
+highlight is connected, so listening for clicks costs you nothing. Calling
+`toggleHighlighted` from a cell slot on an unconnected table does nothing and
+warns once in dev.
+
 Highlight ships with a **default cursor**: the row gets `aria-current="true"`
 and the `bb-table-data__row--highlighted` class, and the shipped stylesheet
-paints that class with a subtle primary-tinted fill plus a left accent bar —
-distinct from hover and from a plain focus ring, and readable in both light
-and dark. Screen-reader users get the `aria-current` announcement either way;
+paints that class with a quiet neutral fill plus a left accent bar in your
+brand primary — distinct from hover and from a plain focus ring, and readable
+in both light and dark. The fill is `--bb-muted` (the shared "selected/active"
+stop on the neutral surface ladder, one step above the `--bb-surface-hover`
+used for row hover) and steps to `--bb-pressed` while hovered, so it never
+depends on what your `--bb-primary` happens to be — only the accent bar does. Screen-reader users get the `aria-current` announcement either way;
 sighted users now get a visible cursor out of the box too, including once
 `keyboard-navigation` is on and the roving tabindex needs to be seen. Override
 it with `row-class` (or equivalent visible styling) whenever the default
@@ -1636,9 +2136,11 @@ const rowClass = (event: AuditEvent) =>
 ```
 
 Row events: `click:row`, `dblclick:row` and `contextmenu:row` fire with
-`(event, row, selected)`. Note that `row` is the table's internal row wrapper,
-not your item: read the raw record from `row.item` and its resolved value from
-`row.value`. Reserve these events for side effects that are not navigation —
+`(event, item)` — the native event and **your record exactly as you passed it
+in `items`**, nothing else. No wrapper to unpack, no third argument; selection
+state is already yours through the `v-model`, and the row's value resolves
+from the record through `item-value` exactly as the models do. Reserve these
+events for side effects that are not navigation —
 logging, opening a drawer (though `v-model:highlighted` usually covers that
 without any handler).
 
@@ -1665,7 +2167,6 @@ open-in-new-tab for free.
 		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
 	>
 		<BbTable
-			actions
 			actions-text="Actions"
 			caption="Invoices"
 			:columns="columns"
@@ -2001,12 +2502,16 @@ canonical palette lives in the
 
 `compact` tightens row padding. `fixed-headers` makes the header stick to the
 top of the nearest scroll container. `fixed` switches to an equal-width fixed
-layout. `fixed-columns` pins columns while the rest scroll horizontally: an
-array of column indices (left-pinned) or `{ index, position: 'left'|'right' }`
-objects; indices count rendered columns (a selection column is index 0), and
-an out-of-range index logs a console error and is skipped. When content can't
-fit, the table keeps every column at its measured minimum and overflows its
-container instead of clipping — this is by design, not a bug to work around.
+layout. Pinned columns (next section) stick while the rest scroll
+horizontally. When content can't
+fit, the table keeps every column at its measured minimum — its header label
+included — and overflows its container instead of clipping; this is by
+design, not a bug to work around. Note that truncating cells yourself
+(`overflow: hidden` + `text-overflow: ellipsis` via `tdClass`) removes that
+column's content floor — only the label floors it then, and the grid pads
+every column equally with whatever is left — so declare a `width` on the
+columns you truncate, or truncate with `white-space: nowrap` alone and let
+the table scroll.
 
 **The consumer overflow contract has two parts.** Wrap the table in an
 `overflow-x: auto` element (below), **and** make sure that wrapper is actually
@@ -2049,6 +2554,144 @@ your wrapper actually sits on before sprinkling `min-width: 0` everywhere.)
 </div>
 ```
 
+### Pinned columns
+
+`fixed: 'left' | 'right'` on a column definition makes its cells
+`position: sticky` on that side — in place, at the column's own render
+position, like a spreadsheet's freeze panes. Pin a contiguous run from the
+edge and the offsets accumulate (the second left-pinned column sticks right
+after the first). The two structural columns have no definition to carry the
+field, so they pin through the table: `fixed-select` for the selection
+column and `fixed-actions` for the actions column (each has one sensible
+side, so both are booleans).
+
+```vue
+<BbTable :columns="columns" fixed-actions fixed-select :items="rows" selectable>
+	<template #actions="{ item }">…</template>
+</BbTable>
+```
+
+```ts
+const columns = [
+	{ key: 'name', label: 'Name', fixed: 'left' },
+	{ key: 'region', label: 'Region' },
+	{ key: 'amount', label: 'Amount', align: 'right' },
+];
+```
+
+Three rules:
+
+- **The pin is the column's.** Under `order` / `reorderable` it travels with
+  the cell, and a `hidden` pinned column pins nothing. The offset is still
+  positional, so a lone left-pinned column dragged to the middle sticks at
+  `left: 0` and slides over the columns before it — by design; lock the
+  pinned columns in place by normalizing `@update:order` if you need to.
+- **Pinned cells are opaque** — they paint the table's `--bg` (see Styling
+  hooks), so a table on a tinted surface needs `--bg` set once.
+- **Nested tables pin against the ancestor scrollport.** A child that
+  inherits the parent's tracks has no scrollport of its own, so both tables'
+  pins land on the same visible edge (see Nested tables).
+
+### Virtual rows
+
+`virtual` windows the body: only the rows in the vertical scrollport (plus a
+few on each side) are mounted, and two spacer rows hold the scrollport at the
+full list height, so 5,000 or 50,000 rows scroll at the cost of a few dozen.
+Everything else is the same table — the rows stay in flow in the grid, so the
+stuck header, pinned columns, nested tables, selection, highlight and the
+keyboard grammar work untouched. One prop, no knobs.
+
+- **Give it a scroller.** Bound the table's height (`max-height` / `height`
+  on the table, or a flex item with `min-height: 0`) and the table itself
+  scrolls its rows; left unbounded it grows with the page and the page (or
+  the nearest scrolling ancestor) is the scroller. `virtual` implies a stuck
+  header — a windowed body without column names is a scroller, not a table.
+- **Columns are sized once.** A windowed body only ever holds a few rows, so
+  `auto` tracks would move as rows come and go. The first rendered batch is
+  measured and its widths become floors (`minmax(px, 1fr)`): they still share
+  surplus, later rows never widen them — and the cells of those columns are
+  single-line and **clip with an ellipsis** (like a resized column) so a
+  longer value that shows up later never spills into its neighbour. Want a
+  column to wrap (prose, notes)? Declare a `width` on it: a declared width
+  wins as always and keeps wrapping. A resize overrides as always, and an
+  empty→non-empty transition (a refetch) re-measures from the new first
+  batch.
+- **A fast wheel never shows blank space.** A band of skeleton rows is kept
+  rendered beyond the window on both sides (cheap: empty cells at the
+  measured row height), so a wheel that the compositor scrolls ahead of the
+  main thread reveals skeletons, not blank spacer, and they turn into real
+  rows as the window reaches them. While the scroll is fast, rows never
+  mounted before stay skeletons and are swapped for real rows as soon as
+  it slows; rows you have already seen stay real. A moderate scroll never
+  sees a skeleton.
+- **Dynamic heights are fine.** Every mounted row is measured (wrapping
+  cells, a "show more", an expand row that opens a nested table three levels
+  deep), measurements are cached by row so a row seen once stays right, and a
+  height change _above_ the viewport moves the scroll offset with it so what
+  you are reading does not jump.
+- **Focus is never lost to an unmount.** The row (or expand row) that owns
+  focus stays mounted however far it scrolls — a control inside a nested
+  table included — and is released on blur. Arrow keys, Home/End and
+  PageUp/PageDown work across the whole list (the target row is scrolled in,
+  mounted, then focused).
+- **Nested tables are not windowed.** A nested table inside an expand row is
+  one tall row to the virtualizer; give a huge nested dataset its own page.
+  `virtual` is ignored on a table that inherits its widths, and under a
+  `#tbody` slot.
+- **Rows keep their absolute position for AT** (`aria-rowcount` /
+  `aria-rowindex`), page or no page — a virtual table is one page unless you
+  say otherwise.
+
+**5,000 rows in a 320px scroller**
+
+```vue
+<template>
+	<!-- Bounding the table's height is what makes it the scroller of its own
+	     rows; `virtual` windows them and implies the stuck header. -->
+	<div
+		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+	>
+		<BbTable
+			caption="Ledger"
+			class="max-h-80"
+			:columns="columns"
+			compact
+			item-value="id"
+			:items="rows"
+			virtual
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { BbTable } from 'bitboss-ui';
+import type { BbTableColumn } from 'bitboss-ui';
+
+type Entry = {
+	id: number;
+	number: string;
+	client: string;
+	issued: string;
+	amount: string;
+};
+
+const columns: Array<BbTableColumn<Entry>> = [
+	{ key: 'number', label: 'Invoice', fixed: 'left' },
+	{ key: 'client', label: 'Client' },
+	{ key: 'issued', label: 'Issued' },
+	{ key: 'amount', label: 'Amount', align: 'right' },
+];
+
+const clients = ['Northwind Traders', 'Globex', 'Initech', 'Umbrella', 'Hooli'];
+const rows: Entry[] = Array.from({ length: 5000 }, (_, i) => ({
+	id: i,
+	number: `INV-${10000 + i}`,
+	client: clients[i % clients.length],
+	issued: `2026-${String(1 + (i % 12)).padStart(2, '0')}-${String(1 + (i % 28)).padStart(2, '0')}`,
+	amount: `€${((i * 37) % 9000) + 100}`,
+}));
+</script>
+```
+
 ### Narrow screens: hide columns, don't scroll everything
 
 An ops table with ten columns is unusable on a phone as a horizontal scroller —
@@ -2057,10 +2700,14 @@ leave the screen. Collapse instead of scroll:
 
 - **Rank the columns.** Identity + status + the one number that matters stay;
   everything else is secondary.
-- **Hide the secondary ones at a breakpoint** with the column's `thClass` _and_
-  `tdClass` (there is no `classes` field): give both the same
-  `'hidden md:table-cell'`, so they are gone rather than off-screen. Both are
-  needed — `thClass` hides the header, `tdClass` the body cells.
+- **Flag the secondary ones `hidden` at the breakpoint** — a `computed`
+  over `useMobile()` (or your own `matchMedia`) that maps the definitions
+  with `hidden: isMobile && secondary.has(key)`. A hidden column has no grid
+  track. Do **not** hide cells with `thClass`/`tdClass` + `display: none`:
+  the table is a grid, a hidden cell leaves its track in place and every
+  following cell shifts one track over. The hidden column stays declared, so
+  it keeps its slot in `order` and returns where it was when the screen
+  widens — never filter the order array.
 - **Stack what survives into the primary cell.** The identity slot renders the
   name plus the hidden facts under it, at `--bb-text-muted`, so nothing is
   actually lost.
@@ -2069,6 +2716,132 @@ Keep the sticky/pinned identity column for the case where the full grid really
 must stay reachable (a spreadsheet-shaped tool), not as the default for a
 records list.
 
+### Styling hooks
+
+**The table's surface is `--bg`** (default `var(--bb-panel)`), a local on
+`.bb-table`. Cells are transparent at rest so the row can tint them, but
+anything that slides over scrolled content — the stuck header band with
+`fixed-headers`, and pinned (`fixed`) cells — is opaque and paints `--bg` (a
+pinned cell also picks up its row's hover/highlight tint, so it never reads
+as a hole). When a table sits on a surface that is not the panel colour, set
+the one knob and everything pinned follows:
+
+```css
+.my-card .bb-table {
+	--bg: var(--card-bg);
+}
+```
+
+The table is a **CSS grid of `<div>`s with ARIA roles, not a `<table>`**: the
+root `.bb-table__table[role=table]` owns the column tracks and every row group
+and row is a subgrid of it. Style it through the classes and the roles — never
+through element names, which match nothing:
+
+| Region         | Class                                                                                                                      | Role                                      |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| grid root      | `.bb-table__table`                                                                                                         | `table`                                   |
+| header group   | `.bb-table__head`                                                                                                          | `rowgroup`                                |
+| header row     | `.bb-table-header-row`                                                                                                     | `row`                                     |
+| header cell    | `.bb-table-header` (+ `--select`, `--actions`)                                                                             | `columnheader`                            |
+| body group     | `.bb-table__body`                                                                                                          | `rowgroup`                                |
+| data row       | `.bb-table-data__row` (+ `--highlighted`)                                                                                  | `row`                                     |
+| data cell      | `.bb-table-data__cell` (+ `--select`)                                                                                      | `cell`                                    |
+| actions cell   | `.bb-table__cell--actions`                                                                                                 | `cell`                                    |
+| expand row     | `.bb-table-expand__row` > `.bb-table-expand__cell`                                                                         | `row` > `cell`                            |
+| empty state    | `.bb-table-no-data__row` > `.bb-table-no-data__cell`                                                                       | `row` > `cell`                            |
+| footer group   | `.bb-table__foot` (`#tfoot` content)                                                                                       | `rowgroup` only when `#tfoot` is provided |
+| focused header | `.bb-table-header[data-column-key]:focus-visible` (`reorderable` only; inset ring, the header row is one roving tab stop)  | `columnheader`                            |
+| dragged column | `.bb-table-header--dragging` on the header; `.bb-table__head--dragging` on the head group during a drag                    | —                                         |
+| clipped header | `.bb-table-header--clip` (the track is a length or an equal split, so the label ellipsizes instead of flooring the column) | `columnheader`                            |
+| virtual table  | `.bb-table--virtual` on the container (`overflow: auto`, the scroller once its height is bounded)                          | —                                         |
+| spacer row     | `.bb-table-spacer__row` (a `virtual` body's stand-in for unmounted rows, `aria-hidden`; never style its height)            | — (`aria-hidden`)                         |
+| skeleton row   | `.bb-table-placeholder__row` > `.bb-table-placeholder__cell` (a `virtual` body's skeleton band and fast-scroll stand-in)   | `row` > `cell` (`aria-hidden`)            |
+| drag chip      | `.bb-table-column-ghost` (a `popover="manual"` in the top layer; paints `--bb-panel`, not the table's `--bg`)              | — (`aria-hidden`)                         |
+| caption        | `.bb-table-caption` (before the root, `aria-labelledby`)                                                                   | —                                         |
+
+`[role='row']`, `[role='cell']` and `[role='columnheader']` are supported
+hooks, not incidental markup — use them when you mean "every row kind" or
+"every cell"; use the classes when you mean one kind. Cells are direct
+children of their row, so `:first-child` / `:last-child` / `:nth-child(n)`
+address columns.
+
+The full-bleed idiom every workspace page reaches for — the table bleeds past
+the content padding and hands the inset back to its outermost cells — is
+written with a **direct-child chain** so a nested table inheriting the
+parent's tracks (it lives inside `.bb-table-expand__cell`) is never touched:
+
+```css
+.table-flush {
+	--page-inset: 1rem;
+	margin-inline: calc(var(--page-inset) * -1);
+	width: calc(100% + var(--page-inset) * 2);
+}
+
+.table-flush
+	:deep(> .bb-table__table > .bb-table__head > [role='row'] > :first-child),
+.table-flush
+	:deep(
+		> .bb-table__table
+			> .bb-table__body
+			> [role='row']
+			> :first-child:not(.bb-table-expand__cell)
+	) {
+	padding-inline-start: var(--page-inset);
+}
+
+.table-flush
+	:deep(> .bb-table__table > .bb-table__head > [role='row'] > :last-child),
+.table-flush
+	:deep(
+		> .bb-table__table
+			> .bb-table__body
+			> [role='row']
+			> :last-child:not(.bb-table-expand__cell)
+	) {
+	padding-inline-end: var(--page-inset);
+}
+
+/* Expand rows stay edge-to-edge so the nested table can snap onto the parent
+   tracks without an extra inset shifting it sideways. */
+.table-flush
+	:deep(
+		> .bb-table__table > .bb-table__body > [role='row'] > .bb-table-expand__cell
+	) {
+	padding-inline: 0;
+}
+```
+
+Leave the geometry alone: `display: grid` / `gap: 0` on the root, row groups
+and rows, `grid-column: 1 / -1` **and `contain: inline-size`** on the
+full-width cells (without the containment, expand-row content resizes the
+parent's columns), `white-space: nowrap` on the actions cell (it sizes the
+actions track), and `position: sticky` on `.bb-table__head` under
+`fixed-headers`.
+
+When you replace a region with `#thead` / `#tbody` / `#tfoot`, ship the same
+shape the table does — role-complete rows, spanning with `grid-column` rather
+than `colspan`:
+
+```vue
+<template #tfoot="{ columnCount }">
+	<div role="row">
+		<div
+			role="cell"
+			:aria-colspan="columnCount - 1"
+			:style="{ gridColumn: `span ${columnCount - 1}` }"
+		>
+			Total
+		</div>
+		<div role="cell" class="text-right">{{ total }}</div>
+	</div>
+</template>
+```
+
+A `<tr>` inside the grid is not merely unsemantic — the browser wraps it in an
+implicit `<table>` and the cells never land on the tracks. Nothing lints the
+roles: a `<div>` row without them renders fine and is invisible to a screen
+reader.
+
 ### Config and platform
 
 - **Locale.** The plugin's `locale` (`it`/`en`) drives the built-in strings:
@@ -2080,10 +2853,13 @@ records list.
   plugin is still on the default locale, which is `it` — set the plugin's
   `locale` option, or override per table with `actions-text` (it is visually
   hidden in the header but read by screen readers).
-- **SSR / Nuxt.** A provider `items` function participates in
-  `onServerPrefetch`, so the first page can render server-side. The table
-  context (and thus `table-id` pagination wiring) is client-side only —
-  hydration-time onward.
+- **SSR / Nuxt.** Under `bitboss-ui/nuxt` a provider `items` function
+  participates in `onServerPrefetch` and its rows travel in the Nuxt payload, so
+  the first page renders server-side and hydrates without re-fetching. On other
+  SSR hosts the provider runs on the client only and the server renders the
+  empty table — see [SSR prefill](./guides/ssr-prefill.md). The table context
+  (and thus `table-id` pagination wiring) is client-side only — hydration-time
+  onward.
 - **Forms.** With `name`, the selection submits as hidden inputs — no JS
   needed between the table and a plain `<form>` POST (Inertia included).
 
@@ -2092,6 +2868,9 @@ records list.
 - `BbPagination` — shared page ref, or zero-wiring via `id` + `table-id`.
 - `useBbTableContext` (`./composables/useBbTableContext.md`) — bulk-action
   toolbars, detail panels, "reset sort" buttons living outside the table.
+  (Column order and visibility are not mirrored there: a column panel writes
+  `v-model:order` and the `hidden` flags, so it lives where `columns` is
+  built.)
 - `BbButton` — per-row links (`href`/`to`) in cells or `#actions`;
   `BbDropdown` for an overflow menu of row actions.
 - `BbBadge` / `BbAvatar` — status and identity cells via slots.
@@ -2114,12 +2893,25 @@ records list.
   localized `common.loadingText`, so an unset value still announces.
 - Row selection labels default to the localized "select" word plus every
   cell's content. `accessible-label` overrides that per row — it is called
-  `(columns, item)` with the mapped cells and the raw record, and whatever it
-  returns becomes the checkbox's label.
+  `(columns, item)` with the mapped cells (in **render** order — look them up
+  by `key`, never by position) and the raw record, and whatever it returns
+  becomes the checkbox's label.
+- A pin (`column.fixed`) travels with its column under `order`, but its
+  offset is positional: dragged away from the edge, a pinned column sticks
+  at `left: 0` and slides over the columns before it (see Pinned columns).
+- The actions column has no prop: the `#actions` slot creates it. A
+  conditional slot (`<template v-if="…" #actions>`) adds and removes the
+  column live.
+- A column panel that holds a partial `order` receives the completed
+  array on the user's first move — its persisted list grows to every declared
+  key, `hidden` ones included. Hide with the flag, not by filtering
+  `columns`: a filtered column is undeclared, so a partial model completes
+  without it and the key is gone from the persisted order.
 - Enabling select-all does not re-emit an empty `modelValue` (see the
   select-all section) — in all-mode, read `select-all` +
   `unselected-items`, not `modelValue`.
-- Row event payloads are the internal row wrapper — your record is `row.item`.
+- Row event payloads are `(event, item)` with `item` your raw record — there is
+  no wrapper to unpack and no `selected` argument.
 - A mistyped context/pagination `id` does not error; it silently syncs with
   nothing. If a toolbar "works" but the table never reacts, check the id.
 - In multiple mode `modelValue` must be an array, or it throws.
@@ -2154,6 +2946,15 @@ records list.
   identity rather than object reference.
 - Sortable headers set `aria-sort` and render real buttons; custom header
   slots should keep a button calling `toggleSort`.
+- With `reorderable` the header row becomes one roving tab stop
+  (the AG Grid grammar): ←/→ move focus between headers, Home/End to the
+  ends, **Shift+←/→** move the focused column one slot (Shift+Home/End to
+  the ends), Enter/Space sorts a sortable header — every move committed
+  immediately and announced through a polite status region ("X moved to
+  position 2 of 5"); a one-line sr-only instruction describes each header.
+  The sort button leaves the tab order (the header is the target; it still
+  works for the mouse). NVDA/JAWS browse mode intercepts arrows on a focused
+  element — the same focus-mode step as row keyboard navigation.
 - When you paginate, pass `page` / `per-page` / `total-items` so the table
   announces the full result count (`aria-rowcount`) and each row's absolute
   index (`aria-rowindex`, expansion-aware), not just the current page.
@@ -2173,6 +2974,7 @@ records list.
 - `v-model:expandedItems` — type: `any[] \| undefined`
 - `v-model:highlighted` — type: `any`
 - `v-model` — type: `any`
+- `v-model:order` — type: `string[] \| undefined`
 - `v-model:selectAll` — type: `boolean \| undefined`
 - `v-model:sort` — type: `BbTableSortEntry[] \| undefined`
 - `v-model:unselectedItems` — type: `any[] \| undefined`
@@ -2181,80 +2983,89 @@ records list.
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `accessibleLabel` | `((columns: MappedCell[], item: any) => string) \| undefined` |  |  | Function that accepts the columns and the current item as arguments and returns a label to be used for accessibility purposes. |
-| `actions` | `boolean \| undefined` |  |  | Displays the actions column. |
+| `accessibleLabel` | `((columns: MappedCell[], item: any) => string) \| undefined` |  |  | Function that accepts the columns and the current item as arguments and returns a label to be used for accessibility purposes. The cells arrive in RENDER order (they follow `order`, so the label reads like the row) — look a cell up by `key`… |
 | `actionsText` | `string \| undefined` |  |  | Label used in the header of the actions column. |
 | `align` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Text alignment of the columns. |
 | `caption` | `string \| undefined` |  |  | Caption that describes the content of the table. Used for accessibility purposes. |
 | `columns` | `InternalColumn<T>[] \| undefined` | `[]` |  | Array of definitions of how the columns should be rendered. |
-| `compact` | `boolean \| undefined` |  |  | Adds a CSS class that applies a compact style to the component. |
+| `compact` | `boolean \| undefined` | `false` |  | Adds a CSS class that applies a compact style to the component. |
 | `dependencies` | `unknown[] \| undefined` | `[]` |  | Defines an array of dependencies that will trigger actions in the component upon change. |
 | `depsDebounceTime` | `number \| undefined` | `0` |  | Timeout used to debounce response to changes to dependencies. |
-| `disabled` | `boolean \| undefined` |  |  | Disables the component |
-| `disableSelectAll` | `boolean \| undefined` |  |  | Hides the "Select all" checkbox that selectable multi-row tables display by default. |
-| `displayCaption` | `boolean \| undefined` |  |  | Boolean that defines whether to display or hide the caption. By default is true and the caption is hidden. |
-| `enforceCoherence` | `boolean \| undefined` |  |  | After every load (initial, `dependencies` refetch or a change of the `items` array) prunes the row-keyed models of values whose row is no longer in the result set: `modelValue`, `unselected-items`, `highlighted` and `expanded-items`. Values… |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
+| `disableSelectAll` | `boolean \| undefined` | `false` |  | Hides the "Select all" checkbox that selectable multi-row tables display by default. |
+| `displayCaption` | `boolean \| undefined` | `false` |  | Boolean that defines whether to display or hide the caption. By default is true and the caption is hidden. |
+| `enforceCoherence` | `boolean \| undefined` | `false` |  | After every load (initial, `dependencies` refetch or a change of the `items` array) prunes the row-keyed models of values whose row is no longer in the result set: `modelValue`, `unselected-items`, `highlighted` and `expanded-items`. Values… |
 | `expandedItems` | `any[] \| undefined` | `[]` |  | Used by `v-model:expandedItems`. Array of the currently expanded items — toggled by the row expand control and by external writes (mirrors the `highlighted`/`sort` v-model surfaces). Drives the `#expand` slot rows and their `aria-expanded`/… |
-| `fixed` | `boolean \| undefined` |  |  | Defines the table layout as fixed making each column take up the same amount of space. |
-| `fixedColumns` | `(number \| { index: number; position: "left" \| "right"; })[] \| undefined` | `[]` |  | Definition for which column should be fixed. It can be an array of index of the column to fix on the left side of the table or an array of objects indicating the index and the position `left` or `right` where to affix the columns. |
-| `fixedHeaders` | `boolean \| undefined` |  |  | Boolean that sets the headers as sticky to the top of the table. |
-| `headerRowClass` | `Classes \| undefined` |  |  | Defines the classes to be passed to the header `<tr>`. |
-| `highlighted` | `any` | `undefined` |  | Used by `v-model:highlighted`. A parallel, UI-intent state to selection — typically "the row whose details are open". A single item value (or `null`) — highlight is single by design. Purely mechanical: highlighted rows only get the `bb-tabl… |
+| `fixed` | `boolean \| undefined` | `false` |  | Splits the width equally among the columns that declare no `width` (each undeclared column becomes a `minmax(0, 1fr)` track) making each column take up the same amount of space. |
+| `fixedActions` | `boolean \| undefined` | `false` |  | Pins the actions column (the one the `#actions` slot creates) to the right edge, `position: sticky`, in place. Data columns pin through `column.fixed`; this is the same feature for the structural column that has no definition to carry it. N… |
+| `fixedHeaders` | `boolean \| undefined` | `false` |  | Boolean that sets the headers as sticky to the top of the table. |
+| `fixedSelect` | `boolean \| undefined` | `false` |  | Pins the selection column to the left edge, `position: sticky`, in place. Data columns pin through `column.fixed`; this is the same feature for the structural column that has no definition to carry it. No effect unless the table is `selecta… |
+| `headerRowClass` | `Classes \| undefined` |  |  | Defines the classes to be passed to the header row. |
+| `highlighted` | `any` | `undefined` |  | Used by `v-model:highlighted`. A parallel, UI-intent state to selection — typically "the row whose details are open". A single item value (or `null`) — highlight is single by design. **Opt-in, and `undefined` is the opt-out.** Leave it unbo… |
 | `id` | `string \| undefined` |  |  | Stable id for this table's width context. When omitted a unique id is generated. Nested tables use the nearest ancestor id to inherit widths. |
-| `inheritColumnWidths` | `string \| boolean \| undefined` |  |  | Opt a nested table into inheriting its column widths from an ancestor table's matching tracks (accounting for `select`/`actions` columns). This also forces `table-layout: fixed`, so it is **off by default** — a nested table renders independ… |
-| `interactiveWhileLoading` | `boolean \| undefined` |  |  | Keeps the table interactive while it is loading. The header and the rows are `inert` while loading by default — a refetch is about to replace the rows, so editing, selecting or sorting them races the incoming data. This escape hatch exists … |
+| `inheritColumnWidths` | `string \| boolean \| undefined` |  |  | Opt a nested table into inheriting its column widths from an ancestor table's matching tracks (accounting for `select`/`actions` columns). This also makes the parent's tracks authoritative, so it is **off by default** — a nested table rende… |
+| `interactiveWhileLoading` | `boolean \| undefined` | `false` |  | Keeps the table interactive while it is loading. The header and the rows are `inert` while loading by default — a refetch is about to replace the rows, so editing, selecting or sorting them races the incoming data. This escape hatch exists … |
 | `items` | `Item[] \| ((prefill: boolean, modelValue?: any) => Item[] \| Promise<Item[]>)` | `[]` | yes | Rows to render, or a fetcher that returns them. |
 | `itemValue` | `ItemAccessor<Item> \| undefined` |  |  |  |
-| `keyboardNavigation` | `boolean \| undefined` |  |  | Opt-in keyboard navigation with a roving tabindex: the body is one tab stop, ArrowUp/ArrowDown move the focused row (Home/End jump), and Enter/Space activate it through the same path as a mouse click (highlight toggle + `click:row`). Focus … |
+| `keyboardNavigation` | `boolean \| undefined` | `false` |  | Opt-in keyboard navigation with a roving tabindex: the body is one tab stop, ArrowUp/ArrowDown move the focused row (Home/End jump), and Enter/Space activate it through the same path as a mouse click (highlight toggle + `click:row`). Focus … |
 | `legend` | `string \| undefined` |  |  | Text content of the `<legend>` a `selectable` table renders (it becomes a `<fieldset>`, and the legend is that fieldset's accessible name). Omit it and the table falls back to `caption`, then to a localized default — the fieldset always end… |
-| `loading` | `boolean \| undefined` |  |  | Sets the component in a loading state, usually triggering some visual styles. With no rows yet this renders skeletons; over existing rows the rows stay on screen (dimmed, with an indeterminate bar) rather than being replaced — a refetch sho… |
-| `loadingText` | `string \| undefined` |  |  | Screen-reader announcement for the loading row's `aria-live` status. Visually hidden — the skeleton (or the `#loading` slot) is the visible signal. |
+| `loading` | `boolean \| undefined` | `false` |  | Sets the component in a loading state, usually triggering some visual styles. With no rows yet this renders skeletons; over existing rows the rows stay on screen (dimmed, with an indeterminate bar) rather than being replaced — a refetch sho… |
+| `loadingText` | `string \| undefined` | `the localized `common.loadingText` ("Loading...")` |  | Screen-reader announcement for the loading row's `aria-live` status. Visually hidden — the skeleton (or the `#loading` slot) is the visible signal. |
 | `max` | `number \| undefined` | `Infinity` |  | Maximum number of items that can be selected. |
 | `modelValue` | `any` | `[]` |  | Used by v-model. Can be any serializable type. |
 | `multiple` | `boolean \| undefined` | `true` |  | Allows the selection of multiple items. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
-| `noDataText` | `string \| undefined` |  |  | String displayed when there are no items to display. |
+| `noDataText` | `string \| undefined` | `the localized `common.noDataText` ("No data to display")` |  | String displayed when there are no items to display. |
+| `order` | `string[] \| undefined` | `[]` |  | Used by `v-model:order`. Ordered array of column keys — the render order of the data columns. Keys listed here render first, in this order; declared columns it omits follow, in declaration order (so a column added to `columns` later renders… |
 | `page` | `string \| number \| undefined` |  |  | Current page number starting from 1, used for accessibility purposes. Also flows into the shared table context, so a `BbPagination` paired through `id` reads it as the current page. Numeric strings are coerced (server pagination fields ofte… |
 | `perPage` | `string \| number \| undefined` |  |  | Number of items per page, used for accessibility purposes. Also flows into the shared table context read by a `BbPagination` paired through `id`. When omitted, an array `items` table infers it from `items.length`; an explicit value (or a co… |
-| `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
-| `rowClass` | `RowClasses<Item> \| undefined` |  |  | Defines the classes to be passed to each data `<tr>`. Can also be a function of the row's item for dynamic values. |
+| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
+| `reorderable` | `boolean \| undefined` | `false` |  | Lets the user reorder the data columns: drag a header cell (AG Grid style — the column moves live under the pointer and a chip with its label follows) or, from the keyboard, use each header's reorder handle (ArrowLeft / ArrowRight move the … |
+| `resizable` | `boolean \| undefined` | `false` |  | Lets the user resize the data columns of a root table: drag the handle on a header's trailing edge (the column follows live, the width commits on release), or press Alt + ArrowLeft / ArrowRight on the focused header; double-click the handle… |
+| `rowClass` | `RowClasses<Item> \| undefined` |  |  | Defines the classes to be passed to each data row. Can also be a function of the row's item for dynamic values. |
 | `selectable` | `boolean \| ((item: Item) => boolean) \| undefined` |  |  | Defines whether the table is selectable. Can be a global boolean that affects all rows or a function that accepts an item and returns a boolean that only affects that item. |
 | `selectAll` | `boolean \| undefined` | `false` |  | Defines whether the "Select all" checkbox is checked. |
 | `selectAllLabel` | `string \| undefined` |  |  | Text of the label used by the "Select all" boolean. |
 | `selectText` | `string \| undefined` |  |  | Text of the header used for the radio inputs when the table is not `multiple`. |
 | `sort` | `BbTableSortEntry[] \| undefined` | `[]` |  | Used by `v-model:sort`. Ordered array of `[columnKey, direction]` entries, one per actively sorted column. Bidirectional: the header buttons of `sortable` columns update it, and external writes update the header indicators. The table does n… |
-| `tdClass` | `ColumnClasses<Item> \| undefined` |  |  | Defines the classes to be passed to the `<td>` elements. Can also be a function for dynamic values. |
-| `thClass` | `Classes \| undefined` |  |  | Defines the classes to be passed to the `<th>`. |
+| `tdClass` | `ColumnClasses<Item> \| undefined` |  |  | Defines the classes to be passed to every data cell. Can also be a function for dynamic values. |
+| `thClass` | `Classes \| undefined` |  |  | Defines the classes to be passed to every header cell. |
 | `totalItems` | `string \| number \| undefined` |  |  | Total number of items there is. Also flows into the shared table context, where a `BbPagination` paired through `id` derives its page count from it. When omitted, an array `items` table infers it from `items.length`; an explicit value (or a… |
 | `totalPages` | `string \| number \| undefined` |  |  | Seeds the page count shown by a `BbPagination` paired through `id`. A shortcut for when the server reports a page count rather than a row count: the table renders nothing from it, it only flows into the shared table context. A known total a… |
 | `unselectedItems` | `any[] \| undefined` | `[]` |  | Items that are not selected. |
+| `virtual` | `boolean \| undefined` | `false` |  | Windows the body: only the rows in (and just around) the vertical scrollport are mounted, so a client-side dataset of any size scrolls at a constant cost. The table itself is the scroller as soon as you bound its height (`max-height` / `hei… |
 
 ## Events
 
-- `click:row` — `(e: "click:row", event: MouseEvent, item: any, selected: boolean): void`
-- `contextmenu:row` — `(e: "contextmenu:row", event: MouseEvent, item: any, selected: boolean): void`
-- `dblclick:row` — `(e: "dblclick:row", event: MouseEvent, item: any, selected: boolean): void`
+- `click:row` — `(e: "click:row", event: MouseEvent, item: any): void`
+- `contextmenu:row` — `(e: "contextmenu:row", event: MouseEvent, item: any): void`
+- `dblclick:row` — `(e: "dblclick:row", event: MouseEvent, item: any): void`
+- `hide:column` — `(e: "hide:column", key: string): void` — A column was hidden from its header (a `#header:<key>` / `#header:<key>:append` control calling the slot's `hideColumn()`). Fired once; the table keeps the column hidden for the mount, or until the column's `hidden` flag changes — write `hi…
 - `item:selected` — `(e: "item:selected", value: any): void`
 - `item:unselected` — `(e: "item:unselected", value: any): void`
+- `resize:column` — `(e: "resize:column", key: string, width: number \| null): void` — A column was resized by the user (`resizable`): the new width in px, or `null` when the handle was double-clicked to reset the column to its declared width.
 - `update:expandedItems` — `(e: "update:expandedItems", value: any[]): void`
 - `update:highlighted` — `(e: "update:highlighted", value: any): void`
 - `update:modelValue` — `(e: "update:modelValue", value: any): void`
+- `update:order` — `(e: "update:order", value: string[]): void`
 - `update:selectAll` — `(e: "update:selectAll", value: boolean): void`
 - `update:sort` — `(e: "update:sort", value: BbTableSortEntry[]): void`
 - `update:unselectedItems` — `(e: "update:unselectedItems", value: any[]): void`
 
 ## Slots
 
-- `actions` — scope: `{ expanded?: boolean \| undefined; expandProps?: ExpandControllerProps \| undefined; toggleExpanded?: (() => void) \| undefined; highlighted?: boolean \| undefi…` — Content rendered in the actions cell for each row.
+- `actions` — scope: `{ expanded?: boolean \| undefined; expandProps?: ExpandControllerProps \| undefined; toggleExpanded?: (() => void) \| undefined; highlighted?: boolean \| undefi…` — Content rendered in the actions cell for each row. Providing this slot is what CREATES the actions column (there is no prop): the header cell (labelled by `actions-text`, replaceable through `#header:actions`) and one cell per row appear wi…
 - `expand` — scope: `{ expanded: boolean; expandProps?: ExpandControllerProps \| undefined; toggleExpanded: () => void; highlighted?: boolean \| undefined; toggleHighlighted?: (() =…` — Full-width expandable content row rendered below each main row when expanded.
 - `header:actions` — scope: `{ text: string; }` — Replaces the default actions header cell content.
+- `header:append` — scope: `BbTableHeaderAffixSlotProps<Item>` — Content rendered after every data column's header cell content — the label + sort control, or the column's own `header:<key>` replacement. A column's `header:<key>:append` slot wins over this one for that column; they never stack. Branch on…
+- `header:prepend` — scope: `BbTableHeaderAffixSlotProps<Item>` — Content rendered before every data column's header cell content — the label + sort control, or the column's own `header:<key>` replacement. A column's `header:<key>:prepend` slot wins over this one for that column; they never stack. Branch …
 - `header:select` — scope: `{ multiple: boolean; selectAll: boolean; text: string; }` — Replaces the default selection header cell content (checkbox or radio label).
 - `loading` — scope: `{ items: Item[]; }` — Content shown while table rows are loading (replaces the skeleton rows).
-- `no-data` — scope: `object` — Content shown when the items list is empty and not loading. It fills the table's own full-width empty-state cell (the colspan already accounts for the selection/actions columns), so provide the *content* — a message, an illustration, a "cle…
+- `no-data` — scope: `object` — Content shown when the items list is empty and not loading. It fills the table's own full-width empty-state cell (it already spans the selection/actions columns), so provide the *content* — a message, an illustration, a "clear filters" butt…
 - `select` — scope: `{ item: Item; value: any; checked: boolean; disabled: boolean; inputName: string; readonly: boolean; toggleSelected?: (() => void) \| undefined; }` — Replaces the default checkbox/radio in the selection cell for each row.
-- `tbody` — scope: `object` — Replaces the entire `<tbody>` element. Use when you need full control over the body markup.
-- `tfoot` — scope: `{ columnCount: number; }` — Replaces the entire `<tfoot>` element. Use when you need full control over the footer markup.
-- `thead` — scope: `object` — Replaces the entire `<thead>` element. Use when you need full control over the header markup.
+- `tbody` — scope: `object` — Replaces the content of the body row group (`.bb-table__body`). Use when you need full control over the body markup. Provide role-complete rows — `<div role="row">` holding one `<div role="cell">` per column — never a `<tr>`/`<td>`. A full-…
+- `tfoot` — scope: `{ columnCount: number; }` — Fills the footer row group (`.bb-table__foot`). Use when you need a footer. Provide role-complete rows — `<div role="row">` holding `<div role="cell">` elements — never a `<tr>`/`<td>`.
+- `thead` — scope: `object` — Replaces the content of the header row group (`.bb-table__head`). Use when you need full control over the header markup. The table is a CSS grid, not a `<table>`: provide role-complete rows — `<div role="row">` holding one `<div role="colum…
 
 ## See Also