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

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,13 +57,15 @@ 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.
@@ -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'
@@ -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`
@@ -219,6 +227,22 @@ one-way state; the `toggle*` callbacks are the write path.
 Header scope: `label`, `items` (the full list — handy for counts), `sortable`,
 `sortOrder`, `toggleSort`, `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
 policy the dynamic status maps to **full-name literals** (a lookup object) —
@@ -365,7 +389,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 +423,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 +713,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 +808,225 @@ 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).
+- Keys that match no declared column render nothing but are **preserved in
+  place**. So hide a column by filtering it out of `columns` — never out of
+  the order — and it 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 — persist that.
+- 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`.
+		     Hiding a column only filters `columns` — its key stays in the order,
+		     so it 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="toggleVisible(column.key)"
+				/>
+				<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="visibleColumns"
+				compact
+				item-value="id"
+				:items="invoices"
+				reorderable
+			/>
+		</div>
+		<p class="text-xs text-[color:var(--bb-text-muted)]">
+			Order model: <code>{{ JSON.stringify(order) }}</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.
+const columns: 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: render order (keys). Persist THIS. Seed it with the full key
+// list — it also completes itself on the first move.
+const order = ref<string[]>(columns.map((column) => column.key));
+const hidden = ref(new Set<string>());
+
+// Visibility is just filtering the declaration; the hidden key keeps its
+// slot in `order`.
+const visibleColumns = computed(() =>
+	columns.filter((column) => !hidden.value.has(column.key))
+);
+
+// The panel lists every declared column in the order the model has them.
+const panelColumns = computed(() =>
+	[...columns].sort(
+		(a, b) => order.value.indexOf(a.key) - order.value.indexOf(b.key)
+	)
+);
+
+const toggleVisible = (key: string) => {
+	const next = new Set(hidden.value);
+	if (next.has(key)) next.delete(key);
+	else next.add(key);
+	hidden.value = next;
+};
+
+const move = (key: string, delta: 1 | -1) => {
+	const next = [...order.value];
+	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>
+```
+
+**Pinned slots are positions, not columns.** `fixed-columns` indexes rendered
+slots like a spreadsheet's freeze panes (a selection column is slot 0). With
+column order the slot holds: whichever column lands in it is pinned, and
+dragging the identity column out of its pinned slot (slot 1 when
+`selectable`, slot 0 otherwise) unpins it (AG Grid pins columns; BbTable
+pins positions). Keep the reorder + pin combination for slots that
+never move — `select`, `actions`, or a first column you also lock by
+normalizing the model in your `@update:order` handler.
+
+**Nested tables.** An inheriting child aligns to the parent's rails by
+**position**, so a reordered parent re-pairs the child's columns unless the
+child follows. Give both tables the same `v-model:order` when they
+share keys (and the child declares no `snap`) and they stay paired by key.
+`snap` points are positional in the parent's rendered order: reorder the
+parent and a snap-mapped child follows its slots, but never reorder (or share
+the order with) the snap-mapped 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
@@ -1277,12 +1526,109 @@ 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
@@ -1293,23 +1639,39 @@ above it (this also forces fixed layout). The mechanics:
   allowed; `end: -1` runs to the end of the data region). Structural columns
   (`select`, actions) are accounted for automatically.
 - 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.
+- **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 map to the parent's content columns 1:1 (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**
 
@@ -1419,6 +1781,47 @@ const expanded = ref<string[]>([]);
 </script>
 ```
 
+#### Affixed actions on both tables
+
+A nested table can carry its own `fixed-columns` — child rows usually need
+their own row actions — and both action columns pin to the same visible edge:
+
+```vue
+<BbTable
+	id="programmes"
+	actions
+	:columns="columns"
+	:fixed-columns="[{ index: columns.length, position: 'right' }]"
+	:items="rows"
+	item-value="id"
+>
+	<template #expand="{ item }">
+		<BbTable
+			actions
+			:columns="childColumns"
+			:fixed-columns="[{ index: childColumns.length, position: 'right' }]"
+			inherit-column-widths="programmes"
+			:items="item.children"
+			item-value="id"
+		/>
+	</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. Snap the
+child's actions column onto the parent's actions track (see the snapping 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 +1835,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 +1851,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 +2071,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).
 
@@ -2005,8 +2442,14 @@ 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.
+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 +2492,107 @@ your wrapper actually sits on before sprinkling `min-width: 0` everywhere.)
 </div>
 ```
 
+### 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, `fixed-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
+			:fixed-columns="[0]"
+			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' },
+	{ 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 +2601,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.
+- **Drop the secondary ones from `columns` at the breakpoint** — a `computed`
+  over `useMobile()` (or your own `matchMedia`) that filters the secondary keys
+  out. Removing the column removes its 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.
+  A dropped key keeps its slot in `order` (the write-back never drops
+  unknown keys), so the column returns where it was — 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 +2617,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 `fixed-columns` 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 +2754,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 +2769,8 @@ 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 is not mirrored there: a column panel needs `columns` too,
+  so it lives where `v-model:order` is bound.)
 - `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 +2793,18 @@ 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.
+- `fixed-columns` pins **slots**, not columns: under `order` the
+  column that lands in a pinned slot is the pinned one (see Column order).
+- A column panel that holds a partial `order` receives the completed
+  array on the user's first move — its persisted list grows to every key.
 - 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 +2839,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 +2867,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,64 +2876,70 @@ 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`… |
+| `actions` | `boolean \| undefined` | `false` |  | Displays the actions column. |
 | `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. |
+| `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. Indices a… |
+| `fixedHeaders` | `boolean \| undefined` | `false` |  | 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 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`
 - `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`
@@ -2248,13 +2949,15 @@ records list.
 - `actions` — scope: `{ expanded?: boolean \| undefined; expandProps?: ExpandControllerProps \| undefined; toggleExpanded?: (() => void) \| undefined; highlighted?: boolean \| undefi…` — Content rendered in the actions cell for each row.
 - `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